sbuilder-mcp 0.81.1 → 0.82.0

package/CHANGELOG.md

@@ -6,6 +6,18 @@ 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.82.0] - 2026-10-10
+
+### Added
+- `sb_api_call` accepts `merge` on a PUT to deep-merge `body` over the current record before sending, so a PUT that replaces a whole record (settings, orders, payment gateways) keeps the fields the caller omits.
+- `sb_api_call` accepts `file` to send a local file as multipart (for example a product import spreadsheet), and a GET with `file` saves the response bytes to a new path without overwriting an existing file.
+- `sb_api_call` accepts `if_match` and reads the version itself on routes that require `If-Match`, such as the shipping-config PATCH, and a `shipping_config_moved` conflict names the route to re-read.
+- Form fields in the element catalog gain `urlParam` and `hideOnPage` settings.
+
+### Changed
+- `sb_api_call` on a PUT without `merge` returns a `replace_warning` listing the fields the write would erase, and its `dry_run` preview shows only the caller's body, never data read from a GET.
+- The shipping readiness check points at the shipping-config route, because the v1 route answers 409 on a site that has saved rules.
+
 ## [0.81.1] - 2026-10-10
 
 ### Fixed

package/CHANGELOG.vi.md

@@ -6,6 +6,18 @@ 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.82.0] - 2026-10-10
+
+### Added
+- `sb_api_call` nhận `merge` trên PUT để trộn sâu `body` lên bản ghi hiện tại trước khi gửi, nên PUT thay cả bản ghi (settings, đơn hàng, cổng thanh toán) giữ lại các field người gọi bỏ qua.
+- `sb_api_call` nhận `file` để gửi file cục bộ dạng multipart (ví dụ bảng tính import sản phẩm), và GET với `file` lưu bytes phản hồi ra đường dẫn mới mà không ghi đè file đã có.
+- `sb_api_call` nhận `if_match` và tự đọc version trên các route yêu cầu `If-Match`, như PATCH shipping-config, và xung đột `shipping_config_moved` chỉ ra route cần đọc lại.
+- Form field trong catalog element có thêm thiết lập `urlParam` và `hideOnPage`.
+
+### Changed
+- `sb_api_call` trên PUT không có `merge` trả về `replace_warning` liệt kê các field lần ghi sẽ xoá, và bản xem trước `dry_run` chỉ in body của người gọi, không in dữ liệu đọc từ GET.
+- Kiểm tra readiness của shipping trỏ sang route shipping-config, vì route v1 trả 409 trên site đã lưu rules.
+
 ## [0.81.1] - 2026-10-10
 
 ### Fixed

package/README.md

@@ -83,7 +83,7 @@ in this client: one would put the very key the platform exists to hold back into
 | `sb_connect` | Log in, list the sites this account can operate, report which credentials are present |
 | `sb_site_list` | List the sites this account can operate |
 | `sb_api_find` | Find API operations by intent — one line per match — then read one operation's call sheet by id: real parameter schemas, the credential it needs, and the body's fields read off the handler that decodes them, each carrying the trap its own doc comment records |
-| `sb_api_call` | Execute an operation, or any route by method+path; dry run by default. Field selection and local result pagination |
+| `sb_api_call` | Execute an operation, or any route by method+path; dry run by default. Field selection and local result pagination; `merge` for whole-record PUTs, `If-Match`, multipart `file` |
 | `sb_page_open` | Open a page for editing and return its outline — or, with `form_id`, a form's field document (fields, defaults, dependent-field rules) |
 | `sb_outline` | The open page as a compressed tree — never a raw document dump |
 | `sb_node_read` | One node in full, with a warning if it is a shared global |

package/README.vi.md

@@ -80,7 +80,7 @@ nhét ngược lại vào mọi bản cài.
 | `sb_connect` | Đăng nhập, liệt kê site tài khoản vận hành được, báo đang có credential nào |
 | `sb_site_list` | Liệt kê site tài khoản vận hành được |
 | `sb_api_find` | Tìm operation theo ý định — mỗi kết quả một dòng — rồi đọc call sheet của một operation theo id: schema tham số thật, credential cần dùng, và các trường body đọc thẳng từ handler decode chúng, mỗi trường mang theo cái bẫy doc comment của chính nó ghi lại |
-| `sb_api_call` | Chạy operation, hoặc bất kỳ route nào bằng method+path; mặc định chạy khô. Chọn field và phân trang kết quả phía MCP |
+| `sb_api_call` | Chạy operation, hoặc bất kỳ route nào bằng method+path; mặc định chạy khô. Chọn field và phân trang kết quả phía MCP; `merge` cho PUT thay cả bản ghi, `If-Match`, `file` multipart |
 | `sb_page_open` | Mở một trang để sửa và trả về outline — hoặc, với `form_id`, tài liệu trường của biểu mẫu (trường, giá trị mặc định, quy tắc trường phụ thuộc) |
 | `sb_outline` | Trang đang mở dạng cây nén — không bao giờ dump tài liệu thô |
 | `sb_node_read` | Một node đầy đủ, kèm cảnh báo nếu nó là global dùng chung |

package/dist/catalog/checkout.generated.js

@@ -114,6 +114,8 @@ export const CHECKOUT_FORM_DOCUMENT = {
                 "showLabel": true,
                 "mapTo": "customer.fullName",
                 "prefillValue": "",
+                "urlParam": "",
+                "hideOnPage": false,
                 "multiline": false,
                 "inputType": "text",
                 "limitChars": false,
@@ -154,6 +156,8 @@ export const CHECKOUT_FORM_DOCUMENT = {
                 "showLabel": true,
                 "mapTo": "customer.phone",
                 "prefillValue": "",
+                "urlParam": "",
+                "hideOnPage": false,
                 "multiline": false,
                 "inputType": "tel",
                 "limitChars": false,
@@ -194,6 +198,8 @@ export const CHECKOUT_FORM_DOCUMENT = {
                 "showLabel": true,
                 "mapTo": "customer.email",
                 "prefillValue": "",
+                "urlParam": "",
+                "hideOnPage": false,
                 "multiline": false,
                 "inputType": "email",
                 "limitChars": false,
@@ -394,6 +400,8 @@ export const CHECKOUT_FORM_DOCUMENT = {
                 "showLabel": true,
                 "mapTo": "order.discountCode",
                 "prefillValue": "",
+                "urlParam": "",
+                "hideOnPage": false,
                 "multiline": false,
                 "inputType": "text",
                 "limitChars": false,
@@ -465,6 +473,8 @@ export const CHECKOUT_FORM_DOCUMENT = {
                 "showLabel": true,
                 "mapTo": "order.note",
                 "prefillValue": "",
+                "urlParam": "",
+                "hideOnPage": false,
                 "multiline": true,
                 "inputType": "text",
                 "limitChars": false,
@@ -946,6 +956,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.fullName",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "text",
                         "limitChars": false,
@@ -986,6 +998,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.email",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "email",
                         "limitChars": false,
@@ -1026,6 +1040,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.phone",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "tel",
                         "limitChars": false,
@@ -1066,6 +1082,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.notes",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": true,
                         "inputType": "text",
                         "limitChars": false,
@@ -1238,6 +1256,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": false,
                         "mapTo": "customer.email",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "email",
                         "limitChars": false,
@@ -1389,6 +1409,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.fullName",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "text",
                         "limitChars": false,
@@ -1429,6 +1451,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.phone",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "tel",
                         "limitChars": false,
@@ -1598,6 +1622,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "order.quantity",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "setRange": true,
                         "minValue": 1,
                         "maxValue": 500,
@@ -1634,6 +1660,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "order.note",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": true,
                         "inputType": "text",
                         "limitChars": false,
@@ -1790,6 +1818,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.fullName",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "text",
                         "limitChars": false,
@@ -1830,6 +1860,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.phone",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "tel",
                         "limitChars": false,
@@ -1870,6 +1902,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.email",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "email",
                         "limitChars": false,
@@ -2070,6 +2104,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "order.discountCode",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "text",
                         "limitChars": false,
@@ -2141,6 +2177,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "order.note",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": true,
                         "inputType": "text",
                         "limitChars": false,
@@ -2300,6 +2338,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.fullName",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "text",
                         "limitChars": false,
@@ -2340,6 +2380,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.phone",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "tel",
                         "limitChars": false,
@@ -3064,6 +3106,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.fullName",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "text",
                         "limitChars": false,
@@ -3104,6 +3148,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.phone",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "tel",
                         "limitChars": false,
@@ -3144,6 +3190,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.notes",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": true,
                         "inputType": "text",
                         "limitChars": false,
@@ -3293,6 +3341,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.fullName",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "text",
                         "limitChars": false,
@@ -3333,6 +3383,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.phone",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "tel",
                         "limitChars": false,
@@ -3441,6 +3493,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.notes",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": true,
                         "inputType": "text",
                         "limitChars": false,
@@ -3592,6 +3646,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.fullName",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "text",
                         "limitChars": false,
@@ -3632,6 +3688,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.phone",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "tel",
                         "limitChars": false,
@@ -3777,6 +3835,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "setRange": true,
                         "minValue": 1,
                         "maxValue": 10,
@@ -3813,6 +3873,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.notes",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": true,
                         "inputType": "text",
                         "limitChars": false,
@@ -3996,6 +4058,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.notes",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": true,
                         "inputType": "text",
                         "limitChars": false,
@@ -4036,6 +4100,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.email",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "email",
                         "limitChars": false,
@@ -4184,6 +4250,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.fullName",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "text",
                         "limitChars": false,
@@ -4224,6 +4292,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.phone",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "tel",
                         "limitChars": false,
@@ -4264,6 +4334,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.email",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "email",
                         "limitChars": false,
@@ -4304,6 +4376,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "setRange": true,
                         "minValue": 1,
                         "maxValue": 20,
@@ -4448,6 +4522,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.fullName",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "text",
                         "limitChars": false,
@@ -4488,6 +4564,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.phone",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "tel",
                         "limitChars": false,
@@ -4528,6 +4606,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.email",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "email",
                         "limitChars": false,
@@ -4568,6 +4648,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.notes",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": true,
                         "inputType": "text",
                         "limitChars": false,
@@ -4717,6 +4799,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "text",
                         "limitChars": false,
@@ -4757,6 +4841,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "tel",
                         "limitChars": false,
@@ -4797,6 +4883,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "email",
                         "limitChars": false,
@@ -4837,6 +4925,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": true,
                         "inputType": "text",
                         "limitChars": false,
@@ -5016,6 +5106,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.email",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "email",
                         "limitChars": false,
@@ -5056,6 +5148,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "password",
                         "limitChars": false,
@@ -5263,6 +5357,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.fullName",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "text",
                         "limitChars": false,
@@ -5303,6 +5399,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.email",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "email",
                         "limitChars": false,
@@ -5343,6 +5441,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "password",
                         "limitChars": false,
@@ -5383,6 +5483,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "password",
                         "limitChars": false,
@@ -5558,6 +5660,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.email",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "email",
                         "limitChars": false,
@@ -5733,6 +5837,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.email",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "email",
                         "limitChars": false,
@@ -5773,6 +5879,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "text",
                         "limitChars": false,
@@ -5921,6 +6029,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "customer.email",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "email",
                         "limitChars": false,
@@ -5961,6 +6071,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "text",
                         "limitChars": false,
@@ -6001,6 +6113,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "password",
                         "limitChars": false,
@@ -6041,6 +6155,8 @@ export const FORM_TEMPLATES = {
                         "showLabel": true,
                         "mapTo": "",
                         "prefillValue": "",
+                        "urlParam": "",
+                        "hideOnPage": false,
                         "multiline": false,
                         "inputType": "password",
                         "limitChars": false,

package/dist/catalog/deadkeys.generated.js

@@ -1,7 +1,7 @@
 export const DEAD_KEY_SOURCE = {
-    "files": 5594,
-    "identifiers": 102591,
-    "seededKeys": 443,
+    "files": 5598,
+    "identifiers": 102652,
+    "seededKeys": 445,
     "dead": 0
 };
 /**

package/dist/catalog/elements.generated.js

@@ -7123,6 +7123,8 @@ export const ELEMENTS = {
                 "showLabel": true,
                 "mapTo": "",
                 "prefillValue": "",
+                "urlParam": "",
+                "hideOnPage": false,
                 "multiline": false,
                 "inputType": "text",
                 "limitChars": false,
@@ -7668,6 +7670,8 @@ export const ELEMENTS = {
                 "showLabel": true,
                 "mapTo": "",
                 "prefillValue": "",
+                "urlParam": "",
+                "hideOnPage": false,
                 "setRange": false,
                 "minValue": 1,
                 "maxValue": 500,

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": "3afc245582a8f81fa58e1bfdc666355d7ecc65fa",
-    "committedAt": "2026-10-09T07:52:30+07:00",
+    "commit": "045c6f78414bfeec8924263a391a6aa8f989e565",
+    "committedAt": "2026-10-10T18:23:19+07:00",
     "dirty": false
 };

package/dist/catalog/translations.generated.js

@@ -3,7 +3,7 @@
 export const TRANSLATION_SOURCE = {
     "elements": 67,
     "pairs": 187,
-    "neverKeys": 178,
+    "neverKeys": 180,
     "entityTypes": 11
 };
 /** Every entity type a translation record can name, including "node". */
@@ -429,6 +429,7 @@ export const NEVER_TRANSLATED = [
     "formId",
     "formRules",
     "format",
+    "hideOnPage",
     "hideWhenEmpty",
     "hoverHostDepth",
     "href",
@@ -533,6 +534,7 @@ export const NEVER_TRANSLATED = [
     "target",
     "thresholdCents",
     "trackUrl",
+    "urlParam",
     "variant",
     "videoId",
     "videoSrc"

package/dist/domains/site/readiness.js

@@ -608,7 +608,10 @@ export function readinessGaps(input) {
             problem: 'No delivery options. The checkout page seeds a shipping select whose options ARE the ' +
                 "site's own methods, so the shopper meets a required-looking field with nothing in it " +
                 'and every order ships free.',
-            fix: 'Add at least one shipping method (sb_api_find "shipping methods").',
+            // Through shipping-config, not the v1 methods route: once a site has saved
+            // rules, every v1 writer answers 409 shipping_config_moved.
+            fix: 'Add at least one shipping method: GET /api/sites/{siteId}/shipping-config, then PATCH it ' +
+                '(sb_api_call reads the If-Match version itself) and POST …/shipping-config/preview to check the price.',
         });
     }
     // THE OTHER FIXED PATHS.

package/dist/tools/api.js

@@ -2,9 +2,79 @@ import { z } from 'zod';
 import { API_OPERATIONS, SWAGGER_SOURCE } from '../catalog/api.generated.js';
 import { REQUEST_SHAPES } from '../catalog/shapes.generated.js';
 import { searchOperations, describeOperation, summarizeOperation, findOperation, } from '../catalog/search.js';
-import { request, redact } from '../transport/http.js';
+import { readFile, stat, writeFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { request, redact, ApiError } from '../transport/http.js';
+import { typeForName } from '../transport/media.js';
+import { restoreBodyFrom } from './undo.js';
 import { text } from '../mcp/response.js';
 import { credentialFor } from '../transport/credential.js';
+/**
+ * ROUTES THAT REFUSE A WRITE WITHOUT `If-Match: "<version>"` (428
+ * if_match_required) — the shipping rules engine's one versioned document
+ * (`server/internal/shipping/rest/config.go`). The version is the GET's own
+ * `config.version`, which is what the editor sends (`features/shipping/config.ts`).
+ */
+const IF_MATCH_ROUTES = new Set([
+    'patch:/api/sites/{siteId}/shipping-config',
+    'post:/api/sites/{siteId}/shipping-config/versions/{id}/restore',
+]);
+const quoteVersion = (v) => {
+    if (typeof v === 'number' || /^\d+$/.test(v))
+        return `"${v}"`;
+    // The server reads W/"7", "7" and 7 (shipping/rest/config.go ifMatch); anything
+    // else is a 400 if_match_invalid that reads like a server fault.
+    if (/^(W\/)?"\d+"$/.test(v))
+        return v;
+    throw new Error(`sbuilder: if_match must be a version number (7 or "7"), not ${JSON.stringify(v)}.`);
+};
+/**
+ * Once a site's shipping lives in the rules engine, every v1 method/zone
+ * writer answers 409 `shipping_config_moved` (`shipping/store.go movedLocked`).
+ * The platform's sentence does not say where the prices went.
+ */
+const SHIPPING_MOVED_FIX = ' — this site\'s shipping lives in the rules engine now: edit it with PATCH ' +
+    '/api/sites/{siteId}/shipping-config (sb_api_call reads If-Match for you), then verify with ' +
+    'POST /api/sites/{siteId}/shipping-config/preview.';
+const isPlain = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/** `over` wins; objects merge key by key; arrays and scalars replace. */
+export function deepMerge(base, over) {
+    if (!isPlain(base) || !isPlain(over))
+        return over;
+    const out = { ...base };
+    for (const [k, v] of Object.entries(over))
+        out[k] = deepMerge(base[k], v);
+    return out;
+}
+/** Leaf paths where `b` differs from `a` (arrays compared whole). */
+function changedPaths(a, b, at = '') {
+    if (isPlain(a) && isPlain(b)) {
+        return [...new Set([...Object.keys(a), ...Object.keys(b)])].flatMap((k) => changedPaths(a[k], b[k], at ? `${at}.${k}` : k));
+    }
+    return JSON.stringify(a) === JSON.stringify(b) ? [] : [at];
+}
+const isEmpty = (v) => v === null || v === undefined || v === '' || v === false || v === 0 ||
+    (Array.isArray(v) && v.length === 0) || (isPlain(v) && Object.keys(v).length === 0);
+/**
+ * What a whole-document PUT of `body` would ERASE: every path holding a value
+ * now that the body leaves out. Go decodes a PUT into a fresh struct, so an
+ * omitted `enabled: true` arrives as false, and an omitted settings key is gone.
+ */
+/** Fields the server owns on every record: a PUT never sets them, so never "erases" them. */
+const SERVER_OWNED = new Set(['id', 'siteId', 'createdAt', 'updatedAt', 'deletedAt', 'createdBy', 'updatedBy', 'rev', 'version', 'number']);
+function erasedPaths(current, body, at = '', owned = SERVER_OWNED) {
+    if (!isPlain(current))
+        return [];
+    return Object.entries(current).flatMap(([k, v]) => {
+        const p = at ? `${at}.${k}` : k;
+        if (isEmpty(v) || owned.has(k))
+            return [];
+        if (!isPlain(body) || !(k in body))
+            return [p];
+        return isPlain(v) && isPlain(body[k]) ? erasedPaths(v, body[k], p, owned) : [];
+    });
+}
+const listPaths = (ps) => (ps.length > 12 ? `${ps.slice(0, 12).join(', ')}, …` : ps.join(', '));
 /** Past this many characters a list response is cut to fit and says so. */
 export const RESULT_CAP = 60_000;
 /**
@@ -466,11 +536,109 @@ export async function callOperation(ctx, args) {
     }
     const token = tokenFor(ctx, op.credential);
     const dryRun = args.dry_run !== false;
+    if (args.merge && op.method !== 'PUT') {
+        throw new Error('sbuilder: merge is for a PUT — it merges body over the record the PUT replaces.');
+    }
+    if (args.merge && args.file)
+        throw new Error('sbuilder: merge and file do not go together.');
+    // A PUT IS A REPLACE, AND THE PLATFORM HAS NO HISTORY. Read what is about to
+    // be destroyed first: `sb_undo` puts it back, `merge` builds on it, and a
+    // dry run warns what the replace would erase. Reads only, never a write.
+    const canRead = op.method === 'PUT' && !args.file && !!REQUEST_SHAPES[op.id] &&
+        API_OPERATIONS.some((o) => o.id === `get:${op.path}`);
+    if (args.merge && !canRead) {
+        throw new Error(`sbuilder: merge needs a body shape and a matching GET; ${op.id} has none. Send the whole record.`);
+    }
+    let before;
+    if (canRead) {
+        try {
+            before = await request({
+                base: ctx.base,
+                method: 'GET',
+                path,
+                token: tokenFor(ctx, findOperation(`get:${op.path}`)?.credential ?? op.credential),
+                fetchImpl: ctx.fetchImpl,
+            });
+        }
+        catch (e) {
+            // The row may not exist yet — the common case for a PUT that creates.
+            // Nothing to undo or warn about; but nothing to merge onto either.
+            if (args.merge)
+                throw new Error(`sbuilder: merge could not read the current record: ${e.message}`);
+        }
+    }
+    const current = before === undefined ? null : restoreBodyFrom(op.id, before);
+    if (args.merge && !current) {
+        throw new Error(`sbuilder: merge found no record in the GET answer for ${op.id}. Send the whole record.`);
+    }
+    if (args.merge && isPlain(args.body) && isPlain(current)) {
+        // A key the record does not have at the top is a body in the wrong envelope
+        // ({locale} for {settings:{locale}}): merged, it would report a change the
+        // server ignores.
+        const stray = Object.keys(args.body).filter((k) => !(k in current));
+        if (stray.length && Object.keys(current).length === 1) {
+            throw new Error(`sbuilder: this PUT takes { ${Object.keys(current)[0]}: … } — put ${stray.join(', ')} inside it.`);
+        }
+    }
+    const body = args.merge ? deepMerge(current, args.body) : args.body;
+    const merged = args.merge ? { changed: changedPaths(current, body) } : undefined;
+    // The settings PUT MERGES a body that is exactly {settings:{locale}}
+    // (sitesettings/rest/rest.go LocaleOnly), so nothing is erased there.
+    const localeOnly = op.id.endsWith('/settings') && isPlain(args.body) && isPlain(args.body.settings) &&
+        Object.keys(args.body).length === 1 && Object.keys(args.body.settings).join() === 'locale';
+    const owned = new Set([...SERVER_OWNED, ...(REQUEST_SHAPES[op.id]?.readOnly ?? [])]);
+    const erased = !args.merge && current && !localeOnly ? erasedPaths(current, args.body, '', owned) : [];
+    const replaceWarning = erased.length
+        ? `This PUT replaces the whole record; ${erased.length} field(s) it holds now ` +
+            `${dryRun ? 'would be' : 'were'} erased: ${listPaths(erased)}. ` +
+            (dryRun ? 'Pass merge:true to keep them.' : 'sb_undo puts them back.')
+        : undefined;
+    // If-Match: given, or — on a route that refuses a write without one — the
+    // version the GET answers right now.
+    const headers = {};
+    let ifMatchRead;
+    if (args.if_match !== undefined)
+        headers['If-Match'] = quoteVersion(args.if_match);
+    else if (IF_MATCH_ROUTES.has(op.id)) {
+        ifMatchRead = path.replace(/(\/shipping-config).*$/, '$1');
+        if (dryRun) {
+            headers['If-Match'] = `(read from GET ${ifMatchRead} at send)`;
+        }
+        else {
+            const got = (await request({ base: ctx.base, method: 'GET', path: ifMatchRead, token, fetchImpl: ctx.fetchImpl }));
+            if (typeof got?.config?.version !== 'number') {
+                throw new Error(`sbuilder: GET ${ifMatchRead} answered no config.version; pass if_match.`);
+            }
+            headers['If-Match'] = quoteVersion(got.config.version);
+        }
+    }
+    // MULTIPART: a non-GET sends a local file under `field` (default "file") —
+    // the product import takes `file:formData/file` and cannot read JSON. A GET
+    // with `file` saves the answer's bytes (an xlsx template) rather than
+    // pasting binary into the result.
+    const download = !!args.file && (op.method === 'GET' || op.method === 'HEAD');
+    if (download && !dryRun && (await stat(args.file.path).then(() => true, () => false))) {
+        throw new Error(`sbuilder: ${args.file.path} already exists — nothing was overwritten; name a new path.`);
+    }
+    const field = args.file?.field ?? 'file';
+    const scalars = isPlain(args.body)
+        ? Object.entries(args.body).filter(([, v]) => ['string', 'number', 'boolean'].includes(typeof v))
+        : [];
     if (dryRun) {
         // THE DRY RUN IS THE DEFAULT, so a directive said only after a real send
         // reaches nobody who looks before they leap. Once per process either way:
         // a dry run that said it leaves the send that follows silent.
         const directive = op.raw ? ctx.notices.once('raw_call', RAW_CALL_NOTICE) : undefined;
+        const upload = args.file && !download
+            ? {
+                multipart: {
+                    field,
+                    path: args.file.path,
+                    bytes: (await stat(args.file.path)).size,
+                    ...(scalars.length ? { fields: Object.fromEntries(scalars) } : {}),
+                },
+            }
+            : undefined;
         return {
             dry_run: true,
             ...(op.raw ? { uncatalogued: true } : {}),
@@ -480,45 +648,71 @@ export async function callOperation(ctx, args) {
                 url: ctx.base.replace(/\/$/, '') + path,
                 query: args.query,
                 Authorization: token ? `Bearer ${token}` : undefined,
-                body: args.body,
+                ...(Object.keys(headers).length ? { headers } : {}),
+                // The CALLER's body, never the merged one: a merge folds in what the GET
+                // answered, and redact() hides only secret-looking KEY NAMES — a webhook
+                // URL or an account number under an ordinary key would be printed.
+                body: upload ?? args.body,
             }),
+            ...(download ? { would_save: args.file.path } : {}),
+            ...(merged ? { merge: merged } : {}),
+            ...(replaceWarning ? { replace_warning: replaceWarning } : {}),
             // Shaping is part of what the call WOULD do, so the preview says it;
             // otherwise a dry run reads identically whether or not it was asked for.
             ...(args.pick !== undefined || args.max_items !== undefined || args.item_offset !== undefined
                 ? { shaping: { pick: args.pick, max_items: args.max_items, item_offset: args.item_offset } }
                 : {}),
-            note: 'Nothing was sent. Re-call with dry_run:false to execute.',
+            note: before !== undefined
+                ? 'Nothing was written — only the current record was read, to ' +
+                    (merged ? 'merge onto' : 'check what the replace would erase') +
+                    '. Re-call with dry_run:false to execute.'
+                : 'Nothing was sent. Re-call with dry_run:false to execute.',
         };
     }
-    // A PUT IS A REPLACE, AND THE PLATFORM HAS NO HISTORY. Read what is about to
-    // be destroyed first, so `sb_undo` can put it back — one extra round trip on a
-    // write, never on a read and never on a dry run. Silent on failure: an undo
-    // that could not be prepared must not stop the write the caller asked for.
-    if (op.method === 'PUT' && REQUEST_SHAPES[op.id] && API_OPERATIONS.some((o) => o.id === `get:${op.path}`)) {
+    if (before !== undefined)
+        ctx.undo.record(op.id, path, before);
+    let sendBody = body;
+    if (args.file && !download) {
+        const form = new FormData();
+        const name = basename(args.file.path);
+        const type = typeForName(name);
+        form.set(field, new Blob([await readFile(args.file.path)], type ? { type } : undefined), name);
+        for (const [k, v] of scalars)
+            form.set(k, String(v));
+        sendBody = form;
+    }
+    let raw;
+    try {
+        raw = await request({
+            base: ctx.base,
+            method: op.method,
+            path,
+            token,
+            query: args.query,
+            body: sendBody,
+            ...(Object.keys(headers).length ? { headers } : {}),
+            ...(download ? { binary: true } : {}),
+            fetchImpl: ctx.fetchImpl,
+        });
+    }
+    catch (e) {
+        if (e instanceof ApiError && e.code === 'shipping_config_moved')
+            e.message += SHIPPING_MOVED_FIX;
+        throw e;
+    }
+    if (download && raw instanceof Uint8Array) {
+        // 'wx': a download never replaces a file that is already there.
         try {
-            const before = await request({
-                base: ctx.base,
-                method: 'GET',
-                path,
-                token: tokenFor(ctx, findOperation(`get:${op.path}`)?.credential ?? op.credential),
-                fetchImpl: ctx.fetchImpl,
-            });
-            ctx.undo.record(op.id, path, before);
+            await writeFile(args.file.path, raw, { flag: 'wx' });
         }
-        catch {
-            // The state could not be read — the row may not exist yet, which is the
-            // common case for a PUT that creates. Nothing to undo, nothing to say.
+        catch (e) {
+            if (e.code === 'EEXIST') {
+                throw new Error(`sbuilder: ${args.file.path} already exists — nothing was overwritten; name a new path.`);
+            }
+            throw e;
         }
+        return { ok: true, saved: args.file.path, bytes: raw.byteLength };
     }
-    const raw = await request({
-        base: ctx.base,
-        method: op.method,
-        path,
-        token,
-        query: args.query,
-        body: args.body,
-        fetchImpl: ctx.fetchImpl,
-    });
     // A 204 HAS NO BODY, and `null` is not an answer a caller can read: a DELETE
     // that worked and a DELETE that returned nothing looked identical, so sixteen
     // page deletes in a row reported `null` sixteen times and the only way to know
@@ -532,10 +726,16 @@ export async function callOperation(ctx, args) {
             max_items: args.max_items,
             item_offset: args.item_offset,
         });
+    const extra = {
+        ...(ifMatchRead ? { if_match: { sent: headers['If-Match'], read_from: `GET ${ifMatchRead}` } } : {}),
+        ...(merged ? { merge: merged } : {}),
+        ...(replaceWarning ? { replace_warning: replaceWarning } : {}),
+    };
+    const told = Object.keys(extra).length && isPlain(answer) ? { ...answer, ...extra } : answer;
     if (!op.raw)
-        return answer;
+        return told;
     const note = ctx.notices.once('raw_call', RAW_CALL_NOTICE);
-    return { uncatalogued: true, ...(note ? { note } : {}), data: answer };
+    return { uncatalogued: true, ...(note ? { note } : {}), data: told };
 }
 /**
  * WHY A SUMMARY CAN BE ABOUT A DIFFERENT ROUTE.
@@ -615,6 +815,12 @@ export function registerApiTools(server, ctx) {
             pick: z.array(z.string()).optional(),
             max_items: z.number().int().min(1).optional(),
             item_offset: z.number().int().min(0).optional().describe('Offset within this response, after API paging. Reads only.'),
+            if_match: z.union([z.string(), z.number()]).optional().describe('If-Match version; shipping-config reads it itself'),
+            merge: z.boolean().optional().describe('PUT: deep-merge body over the current record (arrays replace)'),
+            file: z
+                .object({ path: z.string(), field: z.string().optional() })
+                .optional()
+                .describe('Local file: multipart upload (field "file"); on a GET, saves the answer there'),
         },
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     }, async (args) => text(await callOperation(ctx, args)));

package/dist/transport/http.js

@@ -232,14 +232,19 @@ async function send(opts) {
     const headers = { Accept: 'application/json', ...identityHeaders(), ...opts.headers };
     if (opts.token)
         headers.Authorization = `Bearer ${opts.token}`;
-    if (opts.body !== undefined)
+    // A FormData body is multipart, and fetch must write its Content-Type itself
+    // so the boundary matches the body it builds.
+    const multipart = opts.body instanceof FormData;
+    if (opts.body !== undefined && !multipart)
         headers['Content-Type'] = 'application/json';
     const body = withPageRoot(opts);
     const res = await doFetch(buildUrl(opts.base, opts.path, opts.query), {
         method: opts.method,
         headers,
-        body: body === undefined ? undefined : JSON.stringify(body),
+        body: body === undefined ? undefined : multipart ? body : JSON.stringify(body),
     });
+    if (opts.binary && res.ok)
+        return new Uint8Array(await res.arrayBuffer());
     const raw = await res.text();
     let parsed = undefined;
     if (raw) {

package/dist/transport/media.js

@@ -53,8 +53,11 @@ const TYPE_BY_EXT = {
     '.woff': 'font/woff',
     '.ttf': 'font/ttf',
     '.otf': 'font/otf',
+    // `sb_api_call file` — the product import takes a workbook.
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.csv': 'text/csv',
 };
-function typeForName(name) {
+export function typeForName(name) {
     const dot = name.lastIndexOf('.');
     return dot < 0 ? '' : (TYPE_BY_EXT[name.slice(dot).toLowerCase()] ?? '');
 }

package/package.json

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