sbuilder-mcp 0.88.0 → 0.88.1

package/CHANGELOG.md

@@ -6,6 +6,16 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.88.1] - 2026-10-12
+
+### Added
+- The API catalog is refreshed to 853 operations, including device sign-in for the CLI; the device approval operation cannot be called with a session.
+
+### Fixed
+- Every tool call keeps working after the access token expires, because a rejected session token is refreshed once and the call is retried once; API keys are never refreshed.
+- Concurrent rejections share a single token refresh, and signing out or back in during a refresh is no longer overwritten.
+- `sb_media_upload` and `sb_live_join` reconnects refresh the token before it expires, so uploads and live sessions survive past the token lifetime.
+
 ## [0.88.0] - 2026-10-12
 
 ### Added

package/CHANGELOG.vi.md

@@ -6,6 +6,16 @@ Mọi thay đổi đáng chú ý của dự án được ghi lại trong file n
 Định dạng dựa trên [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 và dự án tuân theo [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.88.1] - 2026-10-12
+
+### Added
+- Catalog API được làm mới lên 853 operation, gồm đăng nhập bằng thiết bị cho CLI; operation duyệt thiết bị không gọi được bằng phiên đăng nhập.
+
+### Fixed
+- Mọi lời gọi tool tiếp tục chạy sau khi access token hết hạn, vì token phiên bị từ chối sẽ được làm mới một lần và lời gọi được thử lại một lần; API key không bao giờ bị làm mới.
+- Các lần bị từ chối đồng thời dùng chung một lượt làm mới token, và việc đăng xuất hoặc đăng nhập lại trong lúc làm mới không còn bị ghi đè.
+- `sb_media_upload` và việc kết nối lại của `sb_live_join` làm mới token trước khi hết hạn, nên upload và phiên live vẫn chạy được sau thời hạn của token.
+
 ## [0.88.0] - 2026-10-12
 
 ### Added

package/README.md

@@ -118,7 +118,7 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_store` | Run a store flow that must happen in a fixed order — `checkout` (the four writes that make a working one), `checkout_sync` (the store's current payment and delivery methods into every existing order form, checkout page republished), `form` (any of the platform's 17 templates with its own field document), `chrome` (one shared header or footer on a real site menu — desktop menu, mobile drawer, cart and account icons), `menu` (a menu node bound to the site's menu, its links resolved), `overlay_attach` (a pop-up or quick view on the open page), `cart` (the site's cart drawer, when it has none; `relocalize` puts an existing one in the site's language) and `app` (a built-in app plus the pages it needs), `global_attach` / `global_detach` (put an EXISTING shared section on the open page, or take it off), `global_promote` (make a section on the page a NEW shared section) and `template_save` (save a section as a reusable template) |
 | `sb_undo` | Undo / redo this session's writes — page and form edits and `sb_api_call` PUTs; a page is refused if someone else saved it since. The platform's versions and history (`sb_page_version`) outlive this process |
 
-Twenty-eight tools, **849 API operations** (312 of the 393 writes carrying a body shape read
+Twenty-eight tools, **853 API operations** (316 of the 397 writes carrying a body shape read
 off the handler), 123 elements, 94 binding sources. `sb_api_find`
 is an index rather than a tool per endpoint, so the tool list stays short while everything
 the platform can do stays reachable — and operations added to the platform arrive with the

package/README.vi.md

@@ -115,7 +115,7 @@ nhét ngược lại vào mọi bản cài.
 | `sb_store` | Chạy một luồng cửa hàng bắt buộc đúng thứ tự — `checkout` (bốn lệnh ghi tạo nên trang thanh toán), `checkout_sync` (đưa phương thức thanh toán và giao hàng hiện tại vào mọi form đặt hàng đã có, publish lại trang thanh toán), `form` (một trong 17 template của nền tảng kèm field document của nó), `chrome` (một header hoặc footer dùng chung trên menu thật của site — menu desktop, drawer mobile, icon giỏ hàng và tài khoản), `menu` (một node menu bind vào menu của site, link đã phân giải), `overlay_attach` (một pop-up hay quick view trên trang đang mở), `cart` (ngăn giỏ hàng của site, khi chưa có; `relocalize` đưa ngăn giỏ đã có về ngôn ngữ của site), `app` (một app dựng sẵn kèm những trang nó cần), và `global_attach` / `global_detach` (đặt một section dùng chung ĐÃ CÓ lên trang đang mở, hoặc gỡ ra), `global_promote` (biến một section trên trang thành section dùng chung MỚI) và `template_save` (lưu một section làm mẫu dùng lại) |
 | `sb_undo` | Hoàn tác / làm lại các thao tác ghi trong phiên — chỉnh sửa trang, form và PUT qua `sb_api_call`; trang bị từ chối nếu người khác đã lưu sau đó. Version và history của nền tảng (`sb_page_version`) sống lâu hơn process này |
 
-Hai mươi tám tool, **849 operation API** (312 trong 393 lệnh ghi có hình dạng body đọc thẳng
+Hai mươi tám tool, **853 operation API** (316 trong 397 lệnh ghi có hình dạng body đọc thẳng
 từ handler), 123 element, 94 nguồn binding. `sb_api_find` là
 một chỉ mục chứ không phải mỗi endpoint một tool, nên danh sách tool vẫn ngắn trong khi mọi
 thứ nền tảng làm được vẫn với tới — và operation mới thêm bên nền tảng sẽ tự có sau lần

package/dist/catalog/api.generated.js

@@ -1,8 +1,8 @@
 export const SWAGGER_SOURCE = {
-    "operations": 849,
-    "definitions": 280,
-    "bodyCarrying": 376,
-    "bodyUndescribed": 102,
+    "operations": 853,
+    "definitions": 282,
+    "bodyCarrying": 380,
+    "bodyUndescribed": 106,
     "generatedFrom": "server/docs/swagger.json"
 };
 export const API_OPERATIONS = [
@@ -1900,6 +1900,90 @@ export const API_OPERATIONS = [
         "bodyRef": null,
         "credential": "none"
     },
+    {
+        "id": "post:/api/auth/device/approve",
+        "method": "POST",
+        "path": "/api/auth/device/approve",
+        "tags": [
+            "auth"
+        ],
+        "summary": "Approve or deny a pending device login",
+        "params": [
+            {
+                "name": "body",
+                "in": "body",
+                "required": true,
+                "type": "object",
+                "description": "userCode + decision (approve|deny)"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "none"
+    },
+    {
+        "id": "post:/api/auth/device/inspect",
+        "method": "POST",
+        "path": "/api/auth/device/inspect",
+        "tags": [
+            "auth"
+        ],
+        "summary": "Describe a pending device login by its typed user code",
+        "params": [
+            {
+                "name": "body",
+                "in": "body",
+                "required": true,
+                "type": "object",
+                "description": "userCode"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "none"
+    },
+    {
+        "id": "post:/api/auth/device/start",
+        "method": "POST",
+        "path": "/api/auth/device/start",
+        "tags": [
+            "auth"
+        ],
+        "summary": "Start a browser device login (sb CLI)",
+        "params": [
+            {
+                "name": "body",
+                "in": "body",
+                "required": true,
+                "type": "object",
+                "description": "client + clientVersion"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "none"
+    },
+    {
+        "id": "post:/api/auth/device/token",
+        "method": "POST",
+        "path": "/api/auth/device/token",
+        "tags": [
+            "auth"
+        ],
+        "summary": "Poll a device login; returns a token pair once approved",
+        "params": [
+            {
+                "name": "body",
+                "in": "body",
+                "required": true,
+                "type": "object",
+                "description": "deviceCode"
+            }
+        ],
+        "bodyDescribed": false,
+        "bodyRef": null,
+        "credential": "none"
+    },
     {
         "id": "post:/api/auth/forgot-password",
         "method": "POST",
@@ -27046,6 +27130,43 @@ export const API_OPERATIONS = [
     }
 ];
 export const API_DEFINITIONS = {
+    "github_com_webbuilder_server_internal_auth.DeviceRequest": {
+        "type": "object",
+        "properties": {
+            "client": {
+                "type": "string"
+            },
+            "clientVersion": {
+                "type": "string"
+            },
+            "createdAt": {
+                "type": "string"
+            },
+            "expiresAt": {
+                "type": "string"
+            }
+        }
+    },
+    "github_com_webbuilder_server_internal_auth.DeviceStart": {
+        "type": "object",
+        "properties": {
+            "deviceCode": {
+                "type": "string"
+            },
+            "expiresIn": {
+                "type": "integer"
+            },
+            "interval": {
+                "type": "integer"
+            },
+            "userCode": {
+                "type": "string"
+            },
+            "verificationUri": {
+                "type": "string"
+            }
+        }
+    },
     "github_com_webbuilder_server_internal_codefiles.CodeFile": {
         "type": "object",
         "properties": {

package/dist/catalog/deadkeys.generated.js

@@ -1,6 +1,6 @@
 export const DEAD_KEY_SOURCE = {
-    "files": 5692,
-    "identifiers": 104086,
+    "files": 5704,
+    "identifiers": 104277,
     "seededKeys": 445,
     "dead": 0
 };

package/dist/catalog/shapes.generated.js

@@ -1,10 +1,10 @@
 export const SHAPE_SOURCE = {
-    "writeOperations": 393,
-    "shaped": 312,
-    "fromHandlers": 302,
+    "writeOperations": 397,
+    "shaped": 316,
+    "fromHandlers": 306,
     "fromSwaggerOnly": 10,
     "withReadOnly": 30,
-    "structsRead": 3226
+    "structsRead": 3237
 };
 export const REQUEST_SHAPES = {
     "post:/api/sites/{id}/ai-credits/purchase": {
@@ -656,6 +656,58 @@ export const REQUEST_SHAPES = {
         "source": "go",
         "goType": "(inline)"
     },
+    "post:/api/auth/device/start": {
+        "fields": [
+            {
+                "name": "client",
+                "type": "string"
+            },
+            {
+                "name": "clientVersion",
+                "type": "string"
+            }
+        ],
+        "source": "go",
+        "goType": "(inline)"
+    },
+    "post:/api/auth/device/inspect": {
+        "fields": [
+            {
+                "name": "userCode",
+                "type": "string"
+            },
+            {
+                "name": "decision",
+                "type": "string"
+            }
+        ],
+        "source": "go",
+        "goType": "deviceDecision"
+    },
+    "post:/api/auth/device/approve": {
+        "fields": [
+            {
+                "name": "userCode",
+                "type": "string"
+            },
+            {
+                "name": "decision",
+                "type": "string"
+            }
+        ],
+        "source": "go",
+        "goType": "deviceDecision"
+    },
+    "post:/api/auth/device/token": {
+        "fields": [
+            {
+                "name": "deviceCode",
+                "type": "string"
+            }
+        ],
+        "source": "go",
+        "goType": "(inline)"
+    },
     "post:/api/auth/register": {
         "fields": [
             {

package/dist/catalog/source.generated.js

@@ -1,7 +1,7 @@
 // GENERATED by scripts/gen-catalog.ts — do not edit by hand.
 // The platform commit every other generated file here describes.
 export const PLATFORM_SOURCE = {
-    "commit": "74ca59dd2340133e4ecf7f2faaf0947874ec3554",
-    "committedAt": "2026-10-12T10:37:24+07:00",
+    "commit": "e69eb03e217da1518783d08db53c776038293778",
+    "committedAt": "2026-10-12T11:10:11+07:00",
     "dirty": false
 };

package/dist/tools/live.js

@@ -272,7 +272,9 @@ export function liveTokenFor(ctx) {
 export function joinRoom(ctx, session, siteId) {
     const tokenFn = liveTokenFor(ctx);
     const wsBase = ctx.base.replace(/^http/, 'ws').replace(/\/$/, '');
-    const socket = new RealtimeSocket(`${wsBase}/api/realtime/ws?site=${encodeURIComponent(siteId)}`, tokenFn);
+    const socket = new RealtimeSocket(`${wsBase}/api/realtime/ws?site=${encodeURIComponent(siteId)}`, tokenFn, undefined, 
+    // A key never expires this way; a session renews near its end of life.
+    ctx.apiKey ? undefined : () => ctx.session.ensureFresh());
     const live = new LiveSession(socket, {
         onRemote: (patches) => session.applyRemote(patches),
         onDesync: (reason) => session.roomDesync(reason),

package/dist/transport/auth.js

@@ -1,9 +1,9 @@
-import { request } from './http.js';
+import { onUnauthorized, request } from './http.js';
 /**
  * A user session against the platform's private API.
  *
  * `token()` is a GETTER, deliberately, and every consumer must call it per use
- * rather than capture its result. The access token lives ~15 minutes and rotates
+ * rather than capture its result. The access token's lifetime is the operator's (AUTH_ACCESS_TTL) and it rotates
  * on refresh; a client holding the string it was built with replays an expired
  * token forever, and the failure is SILENT — a rejected socket auth still fires
  * onopen, so there is no error event and nothing in any UI. The editor shipped
@@ -15,12 +15,39 @@ export class Session {
     base;
     fetchImpl;
     access = null;
+    /** When the access token stops working (ms epoch), from the pair's expiresIn; 0 = unknown. */
+    expiresAt = 0;
     refreshToken = null;
     name = '';
     constructor(base, fetchImpl) {
         this.base = base;
         this.fetchImpl = fetchImpl;
     }
+    /**
+     * Answer a 401 on THIS session's current token with one refresh — see
+     * onUnauthorized in http.ts. Concurrent 401s share one refresh: refresh
+     * tokens are single-use, and presenting one twice ends the session.
+     * Registered while signed in only, so a signed-out session holds nothing.
+     */
+    unrenew = null;
+    listen() {
+        this.unrenew ??= onUnauthorized(async (stale) => {
+            // A request that carried a token THIS session already replaced (a second
+            // 401 landing after the first one renewed) takes the current one.
+            if (this.retired.has(stale) && this.access)
+                return this.access;
+            if (stale !== this.access || !this.refreshToken)
+                return null;
+            this.renewing ??= this.refresh().finally(() => {
+                this.renewing = null;
+            });
+            await this.renewing;
+            return this.access;
+        });
+    }
+    renewing = null;
+    /** Access tokens this session has replaced, so a late 401 on one still renews. */
+    retired = new Set();
     get userName() {
         return this.name;
     }
@@ -52,37 +79,65 @@ export class Session {
         }));
         this.access = out.tokens.accessToken;
         this.refreshToken = out.tokens.refreshToken;
+        this.expiresAt = expiry(out.tokens.expiresIn);
         this.name = out.user?.name ?? '';
+        this.listen();
     }
     /** Rotate. The platform issues a NEW refresh token each time; keep that one. */
     async refresh() {
-        if (!this.refreshToken)
+        const rt = this.refreshToken;
+        if (!rt)
             throw new Error('sbuilder: no refresh token — log in first');
         const out = (await request({
             base: this.base,
             method: 'POST',
             path: '/api/auth/refresh',
-            body: { refreshToken: this.refreshToken },
+            body: { refreshToken: rt },
             fetchImpl: this.fetchImpl,
         }));
+        // Signed out, or signed in afresh, while this was in flight: the pair it
+        // brought back belongs to a session that no longer exists here.
+        if (this.refreshToken !== rt)
+            return;
+        if (this.access)
+            this.retired.add(this.access);
         this.access = out.tokens.accessToken;
         this.refreshToken = out.tokens.refreshToken;
+        this.expiresAt = expiry(out.tokens.expiresIn);
+    }
+    /**
+     * Renew BEFORE a call that cannot retry itself — a media upload sends its
+     * own fetch, outside the 401 retry in http.ts. Within 30s of the lifetime the
+     * pair was issued with, refresh first (shared with any 401 renewal in flight).
+     */
+    async ensureFresh() {
+        if (!this.refreshToken || !this.expiresAt || Date.now() < this.expiresAt - 30_000)
+            return;
+        this.renewing ??= this.refresh().finally(() => {
+            this.renewing = null;
+        });
+        await this.renewing;
     }
     /**
      * Sign this device out. Best effort, never throws.
      *
      * EVERY password sign-in is its own DEVICE SESSION since web_builder 9db1b2a9e,
      * capped at 10 per account; past the cap the one that has gone longest
-     * without a REFRESH is deleted. This client never refreshes (the access token
-     * lives 30 days), so a process that exits without signing out leaves a slot
-     * held, and about ten agent runs later the evicted session is the merchant's
+     * without a REFRESH is deleted. This client refreshes only when refused (the
+     * access token lives 30 days by default), so a process that exits without
+     * signing out leaves a slot held, and about ten agent runs later the evicted session is the merchant's
      * own editor — signed out mid-edit, by nothing they can see. A SIGKILLed
      * process still leaks its slot; nothing on this side can prevent that.
      */
     async logout() {
+        // A renewal in flight is about to rotate the refresh token; revoke the one it
+        // brings back, not the one it just spent (presenting a used one ends the session).
+        await this.renewing?.catch(() => undefined);
         const refreshToken = this.refreshToken;
         this.access = null;
         this.refreshToken = null;
+        this.unrenew?.();
+        this.unrenew = null;
         if (!refreshToken)
             return;
         try {
@@ -99,3 +154,7 @@ export class Session {
         }
     }
 }
+/** expiresIn seconds → an epoch deadline; 0 when the pair carried none. */
+function expiry(seconds) {
+    return typeof seconds === 'number' && seconds > 0 ? Date.now() + seconds * 1000 : 0;
+}

package/dist/transport/http.js

@@ -222,7 +222,12 @@ async function announced(opts, siteId, pageId, doc) {
     }
     return out;
 }
-async function send(opts) {
+const renewers = new Set();
+export function onUnauthorized(r) {
+    renewers.add(r);
+    return () => renewers.delete(r);
+}
+async function send(opts, retried = false) {
     const doFetch = opts.fetchImpl ?? fetch;
     // Identity rides on EVERY call rather than on a handshake of its own. There is
     // no "connect" request to hang it off — the first thing this server does is
@@ -243,6 +248,15 @@ async function send(opts) {
         headers,
         body: body === undefined ? undefined : multipart ? body : JSON.stringify(body),
     });
+    if (res.status === 401 && opts.token && !retried) {
+        for (const renew of renewers) {
+            const fresh = await renew(opts.token).catch(() => null);
+            if (fresh && fresh !== opts.token) {
+                void res.body?.cancel().catch(() => undefined); // release the refused response
+                return send({ ...opts, token: fresh }, true);
+            }
+        }
+    }
     if (opts.binary && res.ok)
         return new Uint8Array(await res.arrayBuffer());
     const raw = await res.text();

package/dist/transport/media.js

@@ -86,6 +86,9 @@ export function typeForName(name) {
  */
 async function fromUrl(ctx, siteId, url, source) {
     const doFetch = ctx.fetchImpl ?? fetch;
+    // Its own fetch, so the 401 renewal in http.ts never sees it — renew first.
+    if (!ctx.apiKey && ctx.session.loggedIn())
+        await ctx.session.ensureFresh().catch(() => undefined);
     const res = await doFetch(`${ctx.base.replace(/\/$/, '')}/api/media/${encodeURIComponent(siteId)}/from-url`, {
         method: 'POST',
         headers: {
@@ -311,6 +314,8 @@ export async function fetchPublic(ctx, doFetch, url) {
 }
 export async function uploadMedia(ctx, siteId, source) {
     const doFetch = ctx.fetchImpl ?? fetch;
+    if (!ctx.apiKey && ctx.session.loggedIn())
+        await ctx.session.ensureFresh().catch(() => undefined);
     // THE SERVER'S OWN DOOR FIRST, when the source is a URL.
     //
     // `POST /api/media/{siteId}/from-url` fetches it where the platform already

package/dist/transport/socket.js

@@ -17,6 +17,7 @@ export class RealtimeSocket {
     url;
     token;
     factory;
+    prepare;
     ws = null;
     closed = false;
     attempt = 0;
@@ -42,10 +43,17 @@ export class RealtimeSocket {
      * expired token on every reconnect, and the failure is SILENT — a rejected
      * auth still fires `onopen`, so no error event ever surfaces.
      */
-    token, factory = (u) => new WebSocket(u)) {
+    token, factory = (u) => new WebSocket(u), 
+    /**
+     * Run before each RECONNECT — renews a session token near its end of life,
+     * since the getter above is synchronous and a reconnect is the moment an
+     * expired token would be presented. Failure never blocks the attempt.
+     */
+    prepare) {
         this.url = url;
         this.token = token;
         this.factory = factory;
+        this.prepare = prepare;
     }
     get attempts() {
         return this.attempt;
@@ -127,7 +135,13 @@ export class RealtimeSocket {
             if (this.closed)
                 return;
             const wait = Math.min(RETRY_BASE_MS * 2 ** this.attempt, RETRY_MAX_MS);
-            this.timer = setTimeout(() => this.connect(), wait);
+            this.timer = setTimeout(() => {
+                if (!this.prepare)
+                    return this.connect();
+                void this.prepare()
+                    .catch(() => undefined)
+                    .then(() => this.connect());
+            }, wait);
         };
         ws.onerror = () => {
             // Genuinely rare: a policy close is not an error. Nothing to do here —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbuilder-mcp",
-  "version": "0.88.0",
+  "version": "0.88.1",
   "description": "MCP server that designs and operates a Store Builder site — pages, data, theme and publish — through the platform's own API and live-edit protocol.",
   "mcpName": "io.github.vuluu2k/sbuilder-mcp",
   "type": "module",