sbuilder-mcp 0.31.0 → 0.32.0

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.32.0] - 2026-09-11
+
+### Added
+- sb_api_find's call sheet for any `/apps` or `/builtin-apps` operation now explains how to place an installed app's block on a page: build `specials.appBlockRef` as `"<installId>/<blockKey>"` from a row of `GET /api/sites/{siteId}/apps/blocks` and add it with sb_add, which was previously reachable only in the platform's Go source.
+- The same call sheet names the two silent traps around a placed block: never author `specials.appBlockId` or `appBlockHash` (the server's own composition stamps), and an edit made inside a composed block's subtree is stored nowhere.
+- The call sheet also explains installing an app: a built-in app installs with `POST /api/sites/{siteId}/builtin-apps/{key}`, while a marketplace app requires a merchant to approve an OAuth consent screen and cannot be installed through this server.
+
+### Fixed
+- The `key` parameter on the built-in app install and list operations now documents all eight installable keys (mail, multilingual, agent, chat, booking, loyalty, payments, courses) instead of only the first two ever shipped.
+
 ## [0.31.0] - 2026-09-11
 
 ### 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.32.0] - 2026-09-11
+
+### Added
+- Call sheet của sb_api_find cho mọi operation `/apps` hoặc `/builtin-apps` giờ giải thích cách đặt block của một app đã cài lên trang: dựng `specials.appBlockRef` dạng `"<installId>/<blockKey>"` từ một dòng của `GET /api/sites/{siteId}/apps/blocks` rồi thêm bằng sb_add — điều trước đây chỉ có thể biết được qua mã nguồn Go của nền tảng.
+- Cùng call sheet đó nêu rõ hai cái bẫy âm thầm quanh một block đã đặt: không bao giờ tự viết `specials.appBlockId` hay `appBlockHash` (đây là các dấu server tự gắn khi compose), và một chỉnh sửa bên trong subtree đã compose sẽ không được lưu ở đâu cả.
+- Call sheet cũng giải thích cách cài app: một app tích hợp sẵn cài bằng `POST /api/sites/{siteId}/builtin-apps/{key}`, còn một app từ marketplace cần merchant tự duyệt màn hình xác nhận OAuth và không thể cài qua server này.
+
+### Fixed
+- Tham số `key` trên các operation cài và liệt kê app tích hợp sẵn giờ ghi đủ tám key có thể cài (mail, multilingual, agent, chat, booking, loyalty, payments, courses) thay vì chỉ hai key đầu tiên từng có.
+
 ## [0.31.0] - 2026-09-11
 
 ### Added

package/dist/catalog/api.generated.js

@@ -3971,7 +3971,7 @@ export const API_OPERATIONS = [
                 "in": "path",
                 "required": true,
                 "type": "string",
-                "description": "App key (mail | multilingual)"
+                "description": "App key: mail | multilingual | agent | chat | booking | loyalty | payments | courses"
             }
         ],
         "bodyDescribed": false,
@@ -3999,7 +3999,7 @@ export const API_OPERATIONS = [
                 "in": "path",
                 "required": true,
                 "type": "string",
-                "description": "App key (mail | multilingual)"
+                "description": "App key: mail | multilingual | agent | chat | booking | loyalty | payments | courses"
             }
         ],
         "bodyDescribed": false,

package/dist/catalog/search.js

@@ -91,6 +91,34 @@ export function describeOperation(op) {
     if (/\/translations(\/|$)/.test(op.path)) {
         out.translation_fields = translationCallSheet();
     }
+    // AN APP'S BLOCKS WERE REACHABLE AND UNUSABLE, because the one thing needed to
+    // place one is a string format that exists only in Go. `page/appblocks.go`
+    // spells it out — SpecAppBlockRef is "<installId>/<blockKey>" — and every
+    // field to build it comes back from `/apps/blocks` (`installId`, `key`). An
+    // agent had the list of blocks, the route that returns it, and no way to turn
+    // a row into a node.
+    //
+    // Attached to the call sheet for the same reason the translation table is:
+    // that is where the agent already is when it decides what to send. No new
+    // tool — placing one is `sb_add`, which already takes the specials it needs.
+    if (/\/(apps|builtin-apps)(\/|$)/.test(op.path)) {
+        out.app_blocks = {
+            place: 'A block from an installed app goes on a page as ONE node carrying ' +
+                'specials.appBlockRef = "<installId>/<blockKey>" — both fields come back from ' +
+                'GET /api/sites/{siteId}/apps/blocks. Add it with sb_add; the platform composes the ' +
+                "app's markup underneath on read.",
+            never: 'Never author specials.appBlockId or appBlockHash. Those are the stamps the SERVER ' +
+                'writes when it composes, and writing one makes the next save decompose your node over ' +
+                'the app instead.',
+            interior: 'An edit INSIDE a composed block is stored nowhere and reported nowhere — the save ' +
+                'reduces the subtree back to the reference. Configure the block through its own ' +
+                'props/slots, never by editing what it rendered.',
+            installing: 'A BUILT-IN app installs with POST /api/sites/{siteId}/builtin-apps/{key} and that key ' +
+                "parameter's description names every installable one. A MARKETPLACE app cannot be " +
+                'installed from here at all: it goes through an OAuth consent screen a person has to ' +
+                'approve, so ask the merchant to install it and then read /apps/blocks again.',
+        };
+    }
     const shape = REQUEST_SHAPES[op.id];
     if (shape) {
         out.body_shape = shape;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbuilder-mcp",
-  "version": "0.31.0",
+  "version": "0.32.0",
   "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",