sbuilder-mcp 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,28 @@ 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.3.0] - 2026-09-08
+
+### Added
+- sb_event authors a click action on any node (such as open_cart), with an allow-list per element read from the catalog; a purchase action is refused here and pointed at sb_bind instead of being silently accepted and doing nothing.
+- sb_bind takes action, so a purchase control can be authored at all: the binding writes the reserved id bind-product-action and stores buy_now as the document's own dynamic_checkout, which is what the renderer reads to decide a button is a purchase button.
+- sb_outline lists satellite nodes (an accordion item's skin, a tab's shared button, a quantity stepper's buttons and input, a repeater's empty state) under their owner as satellite: "<config key>", so a node that used to be invisible to every tool is now on the map; it is not counted in children.
+- sb_review reports accountPage and searchPage gaps when a store has no page for the fixed /account or /search paths, alongside the existing checkout/gateway/product/shipping/cartTrigger gaps.
+- The install CLI accepts --site (and refuses any unrecognized flag instead of silently ignoring it), writing SB_SITE so every site_id argument falls back to it through siteFor().
+- A 204 response (such as a page delete) now reports what it did instead of answering null.
+
+### Changed
+- sb_look walks the full page before shooting a fullPage screenshot, so a lazy-loaded image below the fold is no longer photographed as an empty box.
+- sb_review no longer reports empty_container for a bound media-dataset, which paints the record itself and needs no children; and no longer reports off_canvas for nodes inside the cart drawer, which is parked off-screen until a shopper opens it.
+- sb_add's dataset elements (list-dataset, dataset-block, media-dataset, collection-media, product-variants, quantity-dataset, and others) now derive their bindings from the config.datasetSource supplied in the same call, instead of always seeding the element's default source; sb_set repairs a mismatched binding the same way.
+- sb_site_list's error message no longer tells a key-only install to call sb_connect first, since listing sites is an account-only call a key deliberately cannot make.
+- sb_api_call's error for a missing path parameter now says it belongs in path_params instead of naming the parameter without saying where it goes.
+- sb_media_upload now retries on the partner upload endpoint before reporting the key's scopes as the problem, since a deployment that has not yet enabled key uploads on the primary endpoint otherwise blames a valid key.
+- The API catalog is regenerated: 456 operations and 99 definitions (up from 412 and 97), recovering 44 previously-undocumented operations including the payment-gateway read/write endpoints; the element catalog grows to 107 with the addition of order-receipt.
+
+### Fixed
+- Saving an edit to a shared global section or an overlay (the cart drawer, a global header or footer) no longer silently drops every edit after the first one in a session; the save now re-stamps each master's revision from the platform's response instead of replaying a stale one that the platform rejects with a 200.
+
 ## [0.2.2] - 2026-09-07
 
 ### Fixed

package/CHANGELOG.vi.md

@@ -6,6 +6,28 @@ 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.3.0] - 2026-09-08
+
+### Added
+- sb_event giờ có thể gán một click action lên bất kỳ node nào (như open_cart), với danh sách hành động hợp lệ cho từng element đọc từ catalog; một hành động mua hàng bị từ chối ở đây và được chỉ sang sb_bind thay vì âm thầm chấp nhận mà không làm gì.
+- sb_bind nhận tham số action, nên giờ đã có thể tạo được nút mua hàng: binding ghi id cố định bind-product-action và lưu buy_now dưới dạng dynamic_checkout của chính document — đây là thứ mà renderer đọc để quyết định một nút có phải nút mua hàng hay không.
+- sb_outline giờ liệt kê các node vệ tinh (skin của một mục accordion, nút dùng chung của tab, các nút và ô nhập của quantity stepper, trạng thái rỗng của một repeater) dưới owner của chúng dưới dạng satellite: "<config key>" — một loại node trước đây vô hình với mọi tool giờ đã có mặt trên bản đồ; nó không được tính vào children.
+- sb_review giờ báo cáo gap accountPage và searchPage khi cửa hàng chưa có trang cho đường dẫn cố định /account hoặc /search, bên cạnh các gap checkout/gateway/product/shipping/cartTrigger đã có.
+- CLI cài đặt giờ nhận --site (và từ chối mọi flag không nhận diện được thay vì âm thầm bỏ qua), ghi SB_SITE để mọi tham số site_id fallback về giá trị này qua siteFor().
+- Một response 204 (như xóa trang) giờ báo cáo đã làm gì thay vì trả về null.
+
+### Changed
+- sb_look giờ duyệt qua toàn bộ trang trước khi chụp ảnh fullPage, nên một ảnh lazy-load dưới màn hình không còn bị chụp thành hộp trống.
+- sb_review không còn báo cáo empty_container cho một media-dataset đã bind, vì element này tự vẽ record và không cần child; cũng không còn báo off_canvas cho các node bên trong cart drawer, vốn nằm ngoài màn hình cho tới khi shopper mở nó ra.
+- Các dataset element của sb_add (list-dataset, dataset-block, media-dataset, collection-media, product-variants, quantity-dataset, và các loại khác) giờ tính binding dựa trên config.datasetSource được truyền trong cùng lời gọi, thay vì luôn seed theo nguồn mặc định của element; sb_set sửa một binding sai lệch theo cùng cách.
+- Thông báo lỗi của sb_site_list không còn bảo một cài đặt chỉ dùng key phải gọi sb_connect trước, vì liệt kê site là một lời gọi cấp tài khoản mà key không thể thực hiện được.
+- Lỗi của sb_api_call khi thiếu path parameter giờ nói rõ tham số đó thuộc path_params thay vì chỉ nêu tên tham số mà không nói nó nằm ở đâu.
+- sb_media_upload giờ thử lại trên endpoint upload phía đối tác trước khi báo lỗi do quyền của key, vì một bản triển khai chưa bật upload bằng key trên endpoint chính trước đây sẽ đổ lỗi sai cho một key hợp lệ.
+- Catalog API được tạo lại: 456 operation và 99 definition (tăng từ 412 và 97), khôi phục 44 operation trước đây chưa được ghi nhận, bao gồm các endpoint đọc/ghi payment-gateway; catalog element tăng lên 107 với việc bổ sung order-receipt.
+
+### Fixed
+- Lưu một chỉnh sửa vào global section dùng chung hoặc một overlay (cart drawer, header hoặc footer dùng chung) không còn âm thầm làm mất mọi chỉnh sửa sau lần đầu tiên trong một phiên; lần lưu giờ cập nhật lại revision của từng bản gốc từ response của nền tảng thay vì gửi lại một revision cũ mà nền tảng từ chối kèm mã 200.
+
 ## [0.2.2] - 2026-09-07
 
 ### Fixed

package/README.md

@@ -11,11 +11,17 @@ publish it — with no human clicking anything.
 One command writes this server into every agent client on your machine:
 
 ```bash
-npx -y sbuilder-mcp install --token wbk_… --api https://your-host
+npx -y sbuilder-mcp install --token wbk_… --api https://your-host --site site_…
 ```
 
 It knows Claude Code, Claude Desktop, Cursor, Windsurf, VS Code and Codex, and installs into
-the ones it finds. Name them with `--client cursor,codex`, or rehearse with `--dry-run`.
+the ones it finds. Name them with `--client cursor,codex`, or rehearse with `--dry-run`. An
+option it does not know is **refused**, not ignored — a flag that silently does nothing is
+worse than one that does not exist.
+
+`--site` is optional and worth passing: a key belongs to exactly one site, so it is written
+as `SB_SITE` and every tool then defaults to it. Without it the model has to carry the id
+through the session, which it can only get by listing pages and reading one back.
 
 It **merges**: the servers already in those files stay, whatever it replaces is copied to
 `<file>.sbuilder-backup`, and a config it cannot parse is refused rather than overwritten —
@@ -32,7 +38,7 @@ The store's **Apps → AI agent** screen hands you this command with the key alr
     "sbuilder": {
       "command": "npx",
       "args": ["-y", "sbuilder-mcp"],
-      "env": { "SB_API": "https://api.your-host", "SB_TOKEN": "wbk_…" }
+      "env": { "SB_API": "https://api.your-host", "SB_TOKEN": "wbk_…", "SB_SITE": "site_…" }
     }
   }
 }
@@ -85,7 +91,8 @@ make, because those mean "this person's account".
 | `sb_media_upload` | Add an image and get its URL — the only route, the upload is multipart |
 | `sb_live_join` | Join the editor's live-edit room as a visible peer — edits then appear live |
 | `sb_look` | Save, render, and return screenshots plus measured node boxes and layout defects measured on the render |
-| `sb_bind` | Bind a node's content to real store data |
+| `sb_event` | Give a node a click action — open the cart, go to a page, open a pop-up |
+| `sb_bind` | Bind a node's content to real store data, or make a button add to the cart |
 
 Twenty-five tools, **412 API operations**, 106 elements, 77 binding sources. `sb_api_find`
 is an index rather than a tool per endpoint, so the tool list stays short while everything

package/README.vi.md

@@ -11,11 +11,17 @@ quả rồi xuất bản — mà không cần người bấm gì.
 Một lệnh ghi server này vào mọi agent client trên máy bạn:
 
 ```bash
-npx -y sbuilder-mcp install --token wbk_… --api https://your-host
+npx -y sbuilder-mcp install --token wbk_… --api https://your-host --site site_…
 ```
 
 Nó biết Claude Code, Claude Desktop, Cursor, Windsurf, VS Code và Codex, và cài vào những
-cái nó tìm thấy. Chỉ định bằng `--client cursor,codex`, hoặc diễn thử với `--dry-run`.
+cái nó tìm thấy. Chỉ định bằng `--client cursor,codex`, hoặc diễn thử với `--dry-run`. Một
+tuỳ chọn nó không biết sẽ bị **từ chối**, không phải bỏ qua — một cờ âm thầm không làm gì
+còn tệ hơn một cờ không tồn tại.
+
+`--site` là tuỳ chọn nhưng nên truyền: một khoá chỉ thuộc đúng một site, nên nó được ghi
+thành `SB_SITE` và mọi tool sau đó mặc định dùng site đó. Không có nó thì model phải mang
+theo id suốt phiên, mà cách duy nhất để lấy là liệt kê trang rồi đọc ngược ra.
 
 Nó **gộp**: các server đã có trong file được giữ nguyên, thứ nó thay thế được chép sang
 `<file>.sbuilder-backup`, và một config nó không đọc được thì bị từ chối chứ không ghi đè —
@@ -31,7 +37,7 @@ Màn hình **Apps → AI agent** của cửa hàng đưa sẵn lệnh này kèm
     "sbuilder": {
       "command": "npx",
       "args": ["-y", "sbuilder-mcp"],
-      "env": { "SB_API": "https://api.your-host", "SB_TOKEN": "wbk_…" }
+      "env": { "SB_API": "https://api.your-host", "SB_TOKEN": "wbk_…", "SB_SITE": "site_…" }
     }
   }
 }
@@ -82,7 +88,8 @@ là "tài khoản của người này".
 | `sb_media_upload` | Thêm ảnh và lấy URL — đường duy nhất, vì upload là multipart |
 | `sb_live_join` | Vào phòng live-edit của editor như một peer nhìn thấy được — sửa gì hiện ngay |
 | `sb_look` | Lưu, render, trả về ảnh chụp kèm box đo được của node và lỗi bố cục đo trên bản render |
-| `sb_bind` | Gắn nội dung một node vào dữ liệu cửa hàng thật |
+| `sb_event` | Gắn click action cho một node — mở giỏ, sang trang, mở pop-up |
+| `sb_bind` | Gắn nội dung một node vào dữ liệu cửa hàng thật, hoặc biến một nút thành nút thêm vào giỏ |
 
 Hai mươi lăm tool, **412 operation API**, 106 element, 77 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