webcake-storefront-mcp 1.33.1 → 1.33.2

package/dist/api.js

@@ -186,8 +186,15 @@ export class WebcakeCmsApi {
     listPageContents(query) {
         return this.request("GET", `/api/v1/site/${this.siteId}/page_contents`, { query });
     }
-    updatePageContent(params) {
-        return this.request("POST", `/api/v1/site/${this.siteId}/page_contents/page_content`, { body: params });
+    /** One page's translation in one language: { content: { [elementId]: {...} } } ({} when none yet). Read-only. */
+    getPageContent(page_id, lang) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/page_contents/page_content`, { body: { page_id, lang } });
+    }
+    /** Upsert one page translation (matched by page_id + language_code) — the editor's multilingual save. */
+    updatePageContent({ page_id, language_code, content, meta_tags }) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/multilingual/update_page_contents`, {
+            body: { pages: [{ contents: [{ page_id, language_code, content, meta_tags, site_id: this.siteId }] }] },
+        });
     }
     listGlobalSections() {
         return this.request("GET", `/api/v1/site/${this.siteId}/global_sections`);
@@ -647,14 +654,25 @@ export class WebcakeCmsApi {
     listCustomers(query) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/customer/all`, { query });
     }
+    /** /api/v1/cms_function/:site_id/* sits behind builderx_api's CmsFunctionAuth plug, which only
+     *  accepts the site's CMS admin token (db_collections/token) as the Bearer — the session JWT 401s. */
+    async cmsFunction(method, path, body) {
+        await this.fetchCmsTokens();
+        if (!this._adminToken)
+            throw new Error("This site has no CMS admin token, so cms_function routes are unavailable.");
+        return this.request(method, `/api/v1/cms_function/${this.siteId}${path}`, {
+            body,
+            headers: { Authorization: `Bearer ${this._adminToken}` },
+        });
+    }
     findCustomerById(id) {
-        return this.request("GET", `/api/v1/cms_function/${this.siteId}/customer/identity/${id}`);
+        return this.cmsFunction("GET", `/customer/identity/${encodeURIComponent(id)}`);
     }
     findCustomerByPhone(phone) {
-        return this.request("GET", `/api/v1/cms_function/${this.siteId}/customer/phone/${phone}`);
+        return this.cmsFunction("GET", `/customer/phone/${encodeURIComponent(phone)}`);
     }
     findCustomerByEmail(email) {
-        return this.request("GET", `/api/v1/cms_function/${this.siteId}/customer/email/${email}`);
+        return this.cmsFunction("GET", `/customer/email/${encodeURIComponent(email)}`);
     }
     // ── Global Sources (cart, popup, overview, etc.) ──
     getSourceCart() {
@@ -704,7 +722,7 @@ export class WebcakeCmsApi {
         return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/automations/delete`, { body: { ids } });
     }
     sendMail(params) {
-        return this.request("POST", `/api/v1/cms_function/${this.siteId}/application/automation/send_mail`, { body: params });
+        return this.cmsFunction("POST", "/application/automation/send_mail", params);
     }
     // ── App lifecycle (applications/subcriptions) ──
     /** Uninstall an app by its subscription id (the `id` from list_apps / get_app). */
@@ -1143,13 +1161,7 @@ export class WebcakeCmsApi {
     getCourseMembers(query) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/course-app/members`, { query });
     }
-    // ── Sale channels: sitemap + partner feeds + catalogs ──
-    sitemapSync(kind) {
-        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/sale_channels/sitemap/sync_${kind}`, { body: {} });
-    }
-    sitemapRebuild(type) {
-        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/sale_channels/sitemap/rebuild`, { body: { type } });
-    }
+    // ── Sale channels: partner feeds + catalogs ──
     listPartnerFeeds(query) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/sale_channels/partner_feeds/all`, { query });
     }

package/dist/builder/attributes.js

@@ -174,7 +174,7 @@ export const ELEMENT_ATTRS = {
     // ── layout ──
     section: {
         specials: { global: "Mark as a global/shared section (reused across pages).", custom_class: "CSS class.", layout: "Nested layout payload (advanced)." },
-        config: { stickyPosition: "Make the section sticky: default | autobottom | none.", stickyTop: "Sticky offset from top (px).", showShadowWhenSticky: "Add a shadow when stuck (0/1).", video_background: "Section video background {background_display,…}.", pattern_overlay: "Overlay pattern image url.", apply_pattern_overlay: "Apply the overlay pattern (boolean).", nameLineClamp: "Clamp the section title to N lines." },
+        config: { position: "Scroll behaviour: default | sticky (sticks while scrolling — sticky header) | pinned (fixed to the viewport). See get_build_guide → Sticky & pinned.", stickyPosition: "With position:'sticky': autotop (default) | autobottom | default (both edges).", stickyTop: "Sticky offset from top (px, default 0).", stickyBottom: "Sticky offset from bottom (px, default 0).", showShadowWhenSticky: "Keep the section's boxShadow only while stuck (1, default) or always (0).", video_background: "Section video background {background_display,…}.", pattern_overlay: "Overlay pattern image url.", apply_pattern_overlay: "Apply the overlay pattern (boolean).", nameLineClamp: "Clamp the section title to N lines." },
         events: "none",
         notes: "Top-level band; centred 3-column grid. Children go in the centre column (new_section handles this). Make a header section sticky with config.stickyPosition; add a video/pattern background via config.",
     },
@@ -322,7 +322,7 @@ export const ELEMENT_ATTRS = {
     "next-lesson-droppable": { events: "none", notes: "Next-lesson panel (course app)." },
     "list-lesson-droppable": { events: "none", notes: "Lessons droppable list (course app)." },
     // ── marketing / popups / misc widgets (rarely in page sources; built via apps/global_sources) ──
-    popup: { specials: { effect: "Open animation (fade-in|slide|…).", timeAnim: "Animation duration (s).", trigger: "When it opens: load | delay | exit_intent | scroll.", delay: "Seconds before auto-open (trigger=delay).", onlyOnce: "Show once per visitor (boolean).", overlay: "Dim the page behind (boolean)." }, config: { popupHorizontalPosition: "left | center | right.", popupVerticalPosition: "top | center | bottom." }, events: "hide — fires when the popup closes.", notes: "Modal/overlay. NOT a page section — wrap a section in a popup node and save it as a global_source (component:'popup'). Open/close from any element via events open_popup/close_popup {popup_id}. See get_build_guide → Popups." },
+    popup: { specials: { effect: "Open animation (fade-in|slide|…).", timeAnim: "Animation duration (s).", openPopupAction: "Auto-open: none | openPopupWithTime (after timeOpenPopup s) | openPopupWhenScroll (when the element in `target` scrolls into view) | openWhenNonLogin (after timeOpenPopup s, only for logged-out visitors).", timeOpenPopup: "Delay in seconds for openPopupWithTime / openWhenNonLogin (default 0).", target: "Element id for openPopupWhenScroll.", page_ids: "Pages it auto-opens on (default ['all']).", countOpenPopup: "Max auto-opens per browser session (0/unset = unlimited)." }, config: { popupHorizontalPosition: "left | center | right.", popupVerticalPosition: "top | center | bottom." }, events: "hide — fires when the popup closes.", notes: "Modal/overlay. NOT a page section — wrap a section in a popup node and save it as a global_source (component:'popup'). Open/close from any element via events open_popup/close_popup {popup_id}. See get_build_guide → Popups." },
     notify: { specials: { type: "Toast/banner kind.", autoClose: "Auto-dismiss (boolean).", duration: "Visible time (s)." }, events: "none", notes: "Notification / toast banner (e.g. add-to-cart confirmation). Often referenced by add_to_cart's activeNotify." },
     "random-number": { specials: { min: "Lowest value.", max: "Highest value." }, events: "none", notes: "Displays a random number (minigame / fake-stock urgency widget)." },
     table: { specials: { datagrid_id: "Linked data-grid id (the table's data source).", tableItems: "Column definitions [{name,key}]." }, config: { titleBackground: "Header background.", titleColor: "Header text colour.", oddBackground: "Odd-row background.", evenBackground: "Even-row background." }, events: "none", notes: "Data table bound to a data grid (specs / comparison)." },

package/dist/builder/factory.js

@@ -507,6 +507,9 @@ export const createCartIcon = ({ svg, itemCount, config, style, children } = {})
     cart.specials.itemCount = itemCount ?? 0;
     if (children)
         cart.children = children || [];
+    // The renderer's cart-icon has no click handler of its own — opening the cart IS this event
+    // (SPA factory.js 9877f2c99). Without it a built cart icon does nothing when clicked.
+    cart.events = [{ id: 'EVENT-' + randomString(6), eventName: 'click', action: 'open_cart' }];
     return cart;
 };
 export const createWishlist = ({ svg, itemCount, config, children, style } = {}) => {

package/dist/builder/guide.js

@@ -347,6 +347,16 @@ create the globals — they embed into each page's source. If you later overwrit
 (delete_global_section by the section NODE id, then create once) to re-embed cleanly. Edit a global
 later with update_global_section_element(s) and it updates on every page at once.
 
+STICKY & PINNED (runtime.config, on a section or any element):
+  position:"sticky"  sticks while scrolling — the usual sticky header: the header section gets
+                     { position:"sticky", stickyPosition:"autotop", stickyTop:0 }. stickyPosition:
+                     autotop (default) | autobottom | default (both); offsets stickyTop / stickyBottom (px).
+  position:"pinned"  fixed to the viewport — floating hotline/Zalo button, back-to-top. ALSO set
+                     runtime.style.position:"fixed". fixedPosition: top_left | top_center | top_right |
+                     bottom_left | bottom_center | bottom_right | center_left | center_right; offsets
+                     fixedTop / fixedLeft / fixedRight / fixedBottom (px, default 20).
+  Anything else (or unset) = normal flow. stickyPosition alone does nothing without position:"sticky".
+
 ### HEADER must be RESPONSIVE — add a MOBILE MENUBAR, don't just let nav stack
 A header built as one horizontal row of nav links looks fine on desktop but on a phone the links
 squash or collapse into an ugly vertical pile. Build a header that carries TWO navs and swap them
@@ -373,7 +383,7 @@ A popup is a GLOBAL SOURCE, not a page section. Compose it from elements (there
 shortcut), then save it as a "popup" global source:
 1. Build the popup node: new_element("popup", { children:[…heading,text,form,close button…], style:{ width:480, background:"#fff", borderRadius:"12px" }, config:{ popupHorizontalPosition:"center", popupVerticalPosition:"center" }, specials:{ effect:"fade-in", timeAnim:0.5 } }).
    - SIZE + POSITION live in the popup's runtime style/config (width/height/background + popupHorizontalPosition/popupVerticalPosition), NOT in specials. createPopup seeds a centred-modal default.
-   - TRIGGER (auto-open) lives in SPECIALS: \`openPopupAction:"openPopupWithTime"\` + \`timeOpenPopup:<seconds>\` for a delay; \`page_ids:[…]\` to limit which pages it shows on; \`effect\`/\`timeAnim\` for the animation. (There is no exit-intent/only-once flag in the node — those are app settings.)
+   - TRIGGER (auto-open) lives in SPECIALS: \`openPopupAction:"openPopupWithTime"\` + \`timeOpenPopup:<seconds>\` for a delay; \`page_ids:[…]\` to limit which pages it shows on; \`effect\`/\`timeAnim\` for the animation. Other triggers: \`openPopupWhenScroll\` + \`target:"<elementId>"\` (opens when that element scrolls into view), \`openWhenNonLogin\` (logged-out visitors only, after \`timeOpenPopup\`). \`countOpenPopup:<n>\` caps auto-opens per browser session (unset = every page view). There is no exit-intent trigger.
    - OVERLAY is NOT on the popup node — it's a field on the open_popup EVENT (popup_overlay:true).
 2. Save it: create_global_source({ component:"popup", source:{ sections:[<popupNode>] } }) -> returns its id.
 3. Open/close from any element via events: a button { action:"open_popup", popup_id:"<id>", popup_overlay:true };

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.33.2",
+    "d": "14/10/2026",
+    "type": "Added",
+    "en": "list_orders responses now include a status_name field alongside the numeric status.",
+    "vi": "Kết quả trả về của list_orders nay có thêm trường status_name bên cạnh status dạng số."
+  },
   {
     "v": "1.33.1",
     "d": "14/10/2026",
@@ -33,12 +40,5 @@
     "type": "Added",
     "en": "create_article and update_article accept a new seo object (page_title, meta_description, page_keywords, og_title, og_description, og_image) that…",
     "vi": "create_article và update_article nay nhận thêm đối tượng seo (page_title, meta_description, page_keywords, og_title, og_description, og_image) để…"
-  },
-  {
-    "v": "1.31.11",
-    "d": "11/09/2026",
-    "type": "Changed",
-    "en": "create_site and create_site_from_template now stamp the new site with by_ai: \"mcp\" (persisted to the backend sites.by_ai column), extending the…",
-    "vi": "create_site và create_site_from_template nay đánh dấu site mới với by_ai: \"mcp\" (lưu vào cột sites.by_ai ở backend), mở rộng dấu hiệu AI-tạo vốn chỉ…"
   }
 ]

package/dist/tools/orders.js

@@ -1,9 +1,16 @@
 import { z } from "zod";
+/** builderx_api Enum.OrderStatus (lib/builderx_api/enum.ex). */
+const ORDER_STATUS = {
+    0: "new", 1: "submitted", 2: "shipped", 3: "delivered", 4: "returning", 5: "returned", 6: "canceled",
+    7: "removed", 8: "packing", 9: "pending", 11: "waiting", 12: "wait_print", 13: "printed",
+    15: "part_returned", 16: "received_money", 17: "wait_submit", 20: "ordered", 22: "draft", 50: "blocked",
+};
+const STATUS_HELP = Object.entries(ORDER_STATUS).map(([k, v]) => `${k}=${v}`).join(", ");
 export function registerOrderTools(server, api, handle) {
     server.tool("list_orders", "List orders of the site (metadata only). Use get_order for full details including items", {
         page: z.number().optional().describe("Page number"),
         limit: z.number().optional().describe("Items per page"),
-        status: z.number().optional().describe("Filter by status (0=pending, 50=confirmed, 100=shipping, 150=delivered, -1=cancelled)"),
+        status: z.number().optional().describe(`Filter by status: ${STATUS_HELP}. Omit or -1 = all (except removed/blocked).`),
     }, ({ page, limit, status }) => handle(async () => {
         const res = await api.listOrders({ page, limit, status });
         // Real shape: { orders: { data:[…], total_entries, count_status } }.
@@ -16,6 +23,7 @@ export function registerOrderTools(server, api, handle) {
                 bill_full_name: o.bill_full_name,
                 bill_phone_number: o.bill_phone_number,
                 status: o.status,
+                status_name: ORDER_STATUS[o.status] ?? null,
                 payment_status: o.payment_status,
                 payment_method: o.payment_method,
                 invoice_value: o.invoice_value || o.total,

package/dist/tools/pages.js

@@ -453,31 +453,39 @@ For full rewrites, use update_site_custom_code instead.`, {
     server.tool("get_page_versions", "View version history of a page", {
         page_id: z.string().describe("Page ID"),
     }, ({ page_id }) => handle(() => api.getPageVersions(page_id)));
-    server.tool("list_page_contents", "List multi-language contents of a page", {
-        page_id: z.string().optional().describe("Filter by Page ID"),
-    }, ({ page_id }) => handle(() => api.listPageContents({ page_id })));
+    server.tool("list_page_contents", "List multi-language contents (translations) of the site's pages and global sections. Pass page_id + language_code to read one page's translation.", {
+        page_id: z.string().optional().describe("Page ID — narrows the result to that page"),
+        language_code: z.string().optional().describe("With page_id: return just that language's content map"),
+    }, ({ page_id, language_code }) => handle(async () => {
+        if (page_id && language_code) {
+            const res = await api.getPageContent(page_id, language_code);
+            return res?.data ?? res;
+        }
+        const res = await api.listPageContents(); // backend ignores page_id here, so filter client-side
+        const data = res?.data ?? res;
+        return page_id ? { pages: (data?.pages || []).filter((p) => p.id === page_id) } : data;
+    }));
     server.tool("update_page_content", `Create/update page content for a specific language.
 IMPORTANT: Before calling, you MUST read existing content with list_page_contents first, then show the user what will change and get explicit confirmation. NEVER update without user approval.`, {
         page_id: z.string().describe("Page ID"),
         language_code: z.string().describe("Language code (e.g. 'en', 'vi')"),
-        content: z.record(z.any()).describe("Page content"),
+        content: z
+            .record(z.any())
+            .describe('Translations keyed by element id → field, e.g. { "<elementId>": { "text": "Hello" } } (also "placeholder", or "options": [{ id, name }]). Replaces this language\'s whole map — merge into the existing one.'),
         meta_tags: z.array(z.record(z.any())).optional().describe("SEO meta tags"),
     }, ({ page_id, language_code, content, meta_tags }) => handle(async () => {
         // Safeguard: read existing content and block if new content is suspiciously smaller
-        const existingRes = await api.listPageContents({ page_id });
-        const existingContents = (existingRes && existingRes.data) || existingRes || [];
-        if (Array.isArray(existingContents)) {
-            const existing = existingContents.find((c) => c.language_code === language_code);
-            if (existing && existing.content) {
-                const existingStr = JSON.stringify(existing.content);
-                const newStr = JSON.stringify(content);
-                if (existingStr.length > 200 && newStr.length < existingStr.length * 0.5) {
-                    return {
-                        error: `BLOCKED: New content (${newStr.length} chars) is much smaller than existing (${existingStr.length} chars) — ${Math.round((newStr.length / existingStr.length) * 100)}% of original. This may indicate fabricated data or data loss. Read existing content with list_page_contents first, then merge your changes.`,
-                        existing_length: existingStr.length,
-                        new_length: newStr.length,
-                    };
-                }
+        const existingRes = await api.getPageContent(page_id, language_code);
+        const existing = existingRes?.data ?? existingRes;
+        if (existing && existing.content) {
+            const existingStr = JSON.stringify(existing.content);
+            const newStr = JSON.stringify(content);
+            if (existingStr.length > 200 && newStr.length < existingStr.length * 0.5) {
+                return {
+                    error: `BLOCKED: New content (${newStr.length} chars) is much smaller than existing (${existingStr.length} chars) — ${Math.round((newStr.length / existingStr.length) * 100)}% of original. This may indicate fabricated data or data loss. Read it with list_page_contents(page_id, language_code) first, then merge your changes.`,
+                    existing_length: existingStr.length,
+                    new_length: newStr.length,
+                };
             }
         }
         return api.updatePageContent({ page_id, language_code, content, meta_tags });

package/dist/tools/sale-channels.js

@@ -1,12 +1,9 @@
 import { z } from "zod";
-// Sale-channels app: sitemap generation, partner product feeds (Google/Facebook/etc.),
-// and catalog syncs. Google Ads / OAuth-connect flows are intentionally omitted —
+// Sale-channels app: partner product feeds (Google/Facebook/etc.) and catalog syncs.
+// Sitemaps need no tool: the backend builds them at render time (<domain>/root_sitemaps.xml). Google Ads / OAuth-connect flows are intentionally omitted —
 // they require an externally-authorized Google/Facebook partner.
 export function registerSaleChannelTools(server, api, handle) {
     const unwrap = (res, key) => (key && (res?.data?.[key] ?? res?.[key])) ?? res?.data ?? res;
-    // ── Sitemap ──
-    server.tool("sync_sitemap", "Sync a resource type into the site's sitemap. Requires sitemap enabled in site settings.", { kind: z.enum(["products", "categories", "articles", "pages"]).describe("What to sync into the sitemap") }, ({ kind }) => handle(() => api.sitemapSync(kind)));
-    server.tool("rebuild_sitemap", "Rebuild the whole sitemap (async background job).", { type: z.string().optional().describe("Optional rebuild scope hint") }, ({ type }) => handle(() => api.sitemapRebuild(type)));
     // ── Partner feeds ──
     server.tool("list_partner_feeds", "List product feeds for sale channels (Google Shopping, Facebook, etc.).", {
         page: z.number().optional().describe("Page number"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.33.1",
+  "version": "1.33.2",
   "description": "MCP server for the WebCake/StoreCake storefront builder — page CRUD, page authoring, products, orders, and more",
   "mcpName": "io.github.vuluu2k/webcake-storefront-mcp",
   "license": "MIT",