跳至主要内容

變更記錄

embed SDK 與 platform API 的重要變更。wire contract 在 /embed/v1/* 與 /inference-api/b2b/v1/* 下進行版本管理；破壞相容性的變更 會作為新的主版本與舊版本並行發布（CDN 版本管理）。

2026-09​

  • Capability-policy SSOT。 Product → scope 與 tier → API-capabilities 現在只在 @kaleidr/shared-types 中定義一次 （B2B_PRODUCT_REQUIRED_SCOPE, B2B_TIER_API_CAPABILITIES），並配有 parity tests。由 shared-api（mint / rotate / PATCH clamp）、 inference-api（session exchange, runtime credentials）以及文件共同使用。
  • 有效 capability = 已儲存 key × 目前 tier。 Session exchange 與所有 runtime credential path 都會根據組織的目前 tier 重新計算 admission — 如果 Pro-tier key 降級為 Free，則從該時刻開始只會建立 tile session。使用不同的 subcode： tier_capability_not_allowed（以前擁有，但目前 tier 已不再允許）與 insufficient_scope（從未擁有）。
  • Billing plan 變更會使 apikey:* cache 失效。 Subscription webhook 會清除每個 key 的 snapshot，使 downgrade/upgrade 立即 影響 runtime。由於 session 會在每次 request 時重新讀取 key 的 live policy， downgrade 現在也會影響已經建立的 session — 不再受 session TTL 限制。upgrade 仍然需要新的 session，因為 session 只能相對其 parent 收窄權限。
  • 拒絕 Free-tier PATCH 擴權。 編輯 Free-tier key，試圖將 scopes / allowed_products 擴展到 tier admission 之外時， 會傳回 403 tier_capability_not_allowed，包括 empty-products = all 的情況。
  • 已移除 SSE grounding event。 Grounding 仍會影響回答； 只是已不再透過 wire 傳送 frame。曾監聽此事件的用戶端 將不再收到它。

2026-08​

  • 底圖存取採用金鑰授權。 第三方直接使用 tile.kaleidr.com 會受到限制；<kaleidr-map> embed 與 Kaleidr 託管地圖不受影響。底圖 session 會扣減組織的 共用每月地圖載入額度 （quota）。
  • Session exchange + refresh。 Publishable key 會被交換為 短期、綁定 origin 的 session（kld_sess_{env}_…, 15-min TTL）； session refresh 由 SDK 處理。
  • Place bridge / iframe seam。 已標準化 iframe 產品與父 頁面之間跨 frame Place event 的 postMessage seam。
  • 組織預設底圖。 當 embed 未指定時，/sdk/sessions 會傳回組織已儲存的 預設 basemap_style_id；SDK 會先套用它，再回退至 kaleidr-morning。
  • 瀏覽器拒絕 server key。 SDK 在 mount 時會拒絕 kld_sk_… （server key 僅供伺服器端使用）。
  • Dev / prod CDN + API bake。 兩個環境都透過 版本穩定的 endpoint 提供；viewerBase 已從 loader base 分離， tileBase 也為 editor 的 tile CDN 單獨拆分。
  • Seam v2 路線顏色。 Route event 在穩定 contract 中帶有 color / label / alternatives / comparison。

v1​

  • kaleidr.js loader + <kaleidr-map> element — 一個 façade、四個 product（chat / viewer / editor / tile）、兩種 doorway。
  • Publishable browser key（kld_pk_）與 server key（kld_sk_），包含 scopes ai | maps | design | vendor；publishable key 會被交換為 短期、綁定 origin 的 session。舊版 kld_live_ key 會繼續 運作。
  • /inference-api/b2b/v1/chat/* (SSE) + /design/* route family。

此頁面會隨版本發布持續補充。