webcake-storefront-mcp 1.31.1 → 1.31.3

package/dist/api.js

@@ -353,25 +353,29 @@ export class WebcakeCmsApi {
         const headers = await this.cmsApiHeader();
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records`, { query, headers });
     }
-    /** Insert a record into a collection. Body = the record fields. CMS-api-key authed. */
-    async insertCollectionRecord(tableName, record) {
+    /** Create a collection (TABLE). VERIFIED body: { name, table_name } — the table starts with
+     *  only the system columns (id/inserted_at/updated_at/creator_id). Add custom columns after
+     *  with updateCollectionSchema(). (Sending a schema in the create body 500s.) */
+    async createCollection(params) {
         const headers = await this.cmsApiHeader();
-        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records`, { body: record, headers });
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/db_collections`, { body: params, headers, timeout: 60000 });
     }
-    /** Update a record by id. Body = the changed fields. CMS-api-key authed. */
-    async updateCollectionRecord(tableName, recordId, record) {
+    /** Get one collection by id (includes its full `schema`). */
+    async getCollectionById(id) {
         const headers = await this.cmsApiHeader();
-        return this.request("PATCH", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records/${recordId}`, { body: record, headers });
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/db_collections/${id}`, { headers });
     }
-    /** Delete a record by id. CMS-api-key authed. */
-    async deleteCollectionRecord(tableName, recordId) {
+    /** Add/edit columns: PATCH the collection's FULL schema array. NOTE: this REPLACES the schema,
+     *  so it MUST include the existing system columns + your custom ones. Each custom column =
+     *  { name, type, display_name?, create_type:"custom", is_required?, is_unique? }. */
+    async updateCollectionSchema(id, schema) {
         const headers = await this.cmsApiHeader();
-        return this.request("DELETE", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records/${recordId}`, { headers });
+        return this.request("PATCH", `/api/v1/dashboard/site/${this.siteId}/db_collections/${id}`, { body: { schema }, headers, timeout: 60000 });
     }
-    /** Create a collection (table). Body: { name, schema:[{name,type,...}], ... }. */
-    async createCollection(params) {
+    /** Delete a collection (table) by id. */
+    async deleteCollection(id) {
         const headers = await this.cmsApiHeader();
-        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/db_collections`, { body: params, headers, timeout: 60000 });
+        return this.request("DELETE", `/api/v1/dashboard/site/${this.siteId}/db_collections/${id}`, { headers });
     }
     // ── Blog Articles ──
     listArticles(query) {

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.31.3",
+    "d": "26/06/2026",
+    "type": "Added",
+    "en": "New update_collection_columns tool reads the current collection schema and PATCHes it with the system columns plus the provided custom columns,…",
+    "vi": "Tool mới update_collection_columns đọc schema hiện tại của collection rồi PATCH lại với các cột hệ thống cộng các cột tùy chỉnh được cung cấp, cho…"
+  },
+  {
+    "v": "1.31.2",
+    "d": "26/06/2026",
+    "type": "Changed",
+    "en": "The HTTP_FUNCTION_GUIDE embedded in get_http_function and get_site_custom_code now includes a \"Common patterns\" section with battle-tested…",
+    "vi": "HTTP_FUNCTION_GUIDE được nhúng trong get_http_function và get_site_custom_code nay bổ sung phần \"Common patterns\" với các recipe đã được kiểm chứng…"
+  },
   {
     "v": "1.31.1",
     "d": "26/06/2026",
@@ -26,19 +40,5 @@
     "type": "Added",
     "en": "scaffold_global_sections now accepts a logo parameter (hosted image URL) that renders an image element in the header instead of the brand-name text…",
     "vi": "scaffold_global_sections nay nhận thêm tham số logo (URL hình ảnh được host) để hiển thị phần tử image trong header thay vì node text tên thương hiệu."
-  },
-  {
-    "v": "1.28.0",
-    "d": "26/06/2026",
-    "type": "Added",
-    "en": "New scaffold_popup tool builds and saves a designed newsletter/promo popup (heading + subtext + email subscribe form + close button, centred modal)…",
-    "vi": "Tool mới scaffold_popup xây dựng và lưu một popup newsletter/promo được thiết kế sẵn (tiêu đề + phụ đề + form đăng ký email + nút đóng, dạng modal…"
-  },
-  {
-    "v": "1.27.0",
-    "d": "26/06/2026",
-    "type": "Added",
-    "en": "build_page now accepts an seo object (title, description, keyword, favicon, thumbnail) that is written to page.settings.seo with Open Graph…",
-    "vi": "build_page nay nhận thêm đối tượng seo (title, description, keyword, favicon, thumbnail) và ghi vào page.settings.seo kèm mirroring Open Graph; hỗ…"
   }
 ]

package/dist/guides.js

@@ -76,7 +76,33 @@ const count = await Members.countDocuments({ playspace: psId, status: { $in: [0,
 const created = await Members.create({ thanh_vien: userId, playspace: psId, status: 0 });
 await Members.updateOne({ id: created.id }, { tien_con_lai: 100000 });
 
-## Built-in @webcake/* modules (first arg is always request; they auth via global.token)
+### Common patterns (battle-tested in production functions)
+- FIND-OR-CREATE (ensure a row exists):
+    let row = await M.findOne({ key: v });
+    if (!row) row = await M.create({ key: v, ...defaults });
+    return row;
+- UPSERT + read back the new version:
+    const updated = await M.findOneAndUpdate({ key: v }, { field: x }, { new: true });
+- COUNT then DENORMALIZE onto a parent (cheap reads later):
+    const n = await Members.countDocuments({ playspace: psId, status: { $in: [0,1,2] } });
+    await PlaySpace.updateOne({ id: psId }, { so_thanh_vien: n });
+- MULTI-TABLE write (no transactions — do the steps in order, validate first):
+    for (const it of items) await Members.updateOne({ id: it.id }, { tien_con_lai: it.bal });
+    await PlaySpace.updateOne({ id: psId }, { tien_con_lai: total });
+    await History.create({ playspace: psId, items });           // append an audit/history row
+- SOFT DELETE (keep history) — set a status instead of deleteMany:
+    await M.updateOne({ id }, { status: INACTIVE });            // and filter it out with { status: { $ne: INACTIVE } }
+- REFERENCE id helpers (a ref field is an id string, or an object after populate):
+    const toId = (v) => (v && typeof v === "object" ? String(v.id || "") : String(v || ""));
+    const toNumber = (v, d = 0) => (Number.isFinite(Number(v)) ? Number(v) : d);
+- STATUS as numeric enums (define constants up top): const STATUS = { OWNER:0, ACTIVE:1, GUEST:2, INACTIVE:3 };
+  then query with { status: { $in: [STATUS.OWNER, STATUS.ACTIVE] } }.
+- ALWAYS guard auth + wrap in try/catch returning a coded mess:
+    const userId = request.customer?.id ?? ""; if (!userId) return { mess: "NO_ACCOUNT_CALL" };
+    try { /* … */ return { mess: "OK", ...data }; } catch (err) { console.error(err?.message || err); return { mess: "SYSTEM_ERROR" }; }
+
+## Built-in @webcake/* modules (first arg is always request; they auth via global.token — these run
+## INSIDE the function sandbox, so they reach the /cms_function endpoints the dashboard JWT can't)
 Thin wrappers over the backend's /cms_function/{site_id}/... endpoints. Pass request so
 they pick up site_id. Below is EXACTLY what each call sends to the backend + what it returns.
 
@@ -96,15 +122,20 @@ they pick up site_id. Below is EXACTLY what each call sends to the backend + wha
     updateArticleById(request, id, data)    PATCH .../blog/article/{id}   (same fields) → response
     deleteArticleById(request, id)          DELETE .../blog/article/{id}  → response
 
-- '@webcake/customer'  (backend: /cms_function/{site}/customer/…)  → customer object ({} if none)
-    findCustomerById(request, id)     GET .../customer/identity/{id}
+- '@webcake/customer'  (backend: /cms_function/{site}/customer/…)  → customer object ({} if none).
+    The object has at least { id, name, avatar, email, phone_number }. ALWAYS check \`customer?.id\`
+    before using it (returns {} when not found). Confirmed against a real production function.
+    findCustomerById(request, id)       GET .../customer/identity/{id}
     findCustomerByPhone(request, phone) GET .../customer/phone/{phone}
     findCustomerByEmail(request, email) GET .../customer/email/{email}
+    Typical lookup-by-anything helper: try a code/sku table first, else normalize the phone and
+    call findCustomerByPhone, else (has "@") findCustomerByEmail, else findCustomerById.
 
-- '@webcake/promotion'  (backend: /cms_function/{site}/promotion/add_bonus)
+- '@webcake/promotion'  (backend: /cms_function/{site}/promotion/add_bonus)  — confirmed in real code
     addBonus(request, data)   POST add_bonus → response.
         It ADDS REWARD POINTS to a customer. data: { customer_id (required),
         point (number, required), message? (defaults "Bạn được cộng điểm") }.
+        e.g. await addBonus(request, { customer_id: "abc", point: 10, message: "Cộng 10 điểm" }).
 
 - '@webcake/token'  (backend: /external/oauth/token)
     getAccessToken(request)   → access_token string (throws if none).

package/dist/tools/collections.js

@@ -39,26 +39,52 @@ export function registerCollectionTools(server, api, handle) {
             query.order_by = order_by;
         return api.queryCollectionRecords(table_name, query);
     }));
-    // ── Write tools (custom data CRUD). Endpoints follow the same /db_collections/collections/
-    //    {table}/records[/{id}] REST pattern as the verified read endpoint, with the CMS api-key
-    //    header. They mutate live data — run a small test first to confirm your field shape. ──
-    server.tool("create_collection", "Create a new collection (custom data TABLE) so you can store/query arbitrary data. Pass a name + the field schema. The backend adds id/inserted_at/updated_at automatically.", {
-        name: z.string().describe("Collection / table name (e.g. 'subscribers')."),
-        schema: z
-            .array(z.object({ name: z.string(), type: z.string().describe("Field type: string | text | integer | float | boolean | naive_datetime | binary_id | map | array"), required: z.boolean().optional() }))
-            .describe("Field definitions, e.g. [{name:'email',type:'string',required:true},{name:'joined_at',type:'naive_datetime'}]."),
-    }, ({ name, schema }) => handle(() => api.createCollection({ name, schema })));
-    server.tool("insert_collection_record", "Insert a record into a collection (custom data table). `record` is a field→value object matching the table schema.", {
-        table_name: z.string().describe("Collection table name."),
-        record: z.record(z.any()).describe("Record fields, e.g. { email:'a@b.com', joined_at:'2026-06-26T10:00:00' }."),
-    }, ({ table_name, record }) => handle(() => api.insertCollectionRecord(table_name, record)));
-    server.tool("update_collection_record", "Update a record in a collection by id. `record` carries only the changed fields.", {
-        table_name: z.string().describe("Collection table name."),
-        record_id: z.string().describe("Record id to update."),
-        record: z.record(z.any()).describe("Changed fields."),
-    }, ({ table_name, record_id, record }) => handle(() => api.updateCollectionRecord(table_name, record_id, record)));
-    server.tool("delete_collection_record", "Delete a record from a collection by id.", {
-        table_name: z.string().describe("Collection table name."),
-        record_id: z.string().describe("Record id to delete."),
-    }, ({ table_name, record_id }) => handle(() => api.deleteCollectionRecord(table_name, record_id)));
+    // ── Table-management tools (VERIFIED live: create table, edit columns, delete table). ──
+    // Field type ∈ string | text | integer | float | boolean | naive_datetime | binary_id | map | array.
+    const COLUMN = z.object({
+        name: z.string().describe("Column name (snake_case)."),
+        type: z.string().describe("string | text | integer | float | boolean | naive_datetime | binary_id | map | array"),
+        display_name: z.string().optional(),
+        is_required: z.boolean().optional(),
+        is_unique: z.boolean().optional(),
+    });
+    server.tool("create_collection", "Create a new collection (custom data TABLE). It starts with the system columns (id/inserted_at/updated_at/creator_id); pass `columns` to add custom fields. NOTE: to WRITE records into it, use an HTTP function (webcake-data: db.model(table).create({...})) — the dashboard has no direct record-insert API. See get_http_function for the SDK guide.", {
+        name: z.string().describe("Display name."),
+        table_name: z.string().optional().describe("Table name (snake_case, unique). Defaults to name."),
+        columns: z.array(COLUMN).optional().describe("Custom columns to add, e.g. [{name:'email',type:'string'},{name:'amount',type:'integer'}]."),
+    }, ({ name, table_name, columns }) => handle(async () => {
+        const tn = (table_name || name).trim();
+        const created = await api.createCollection({ name, table_name: tn });
+        const col = (created && (created.data || created)) || {};
+        const id = col.id;
+        if (!id)
+            return { error: "Collection created but no id returned.", raw: created };
+        let schema = col.schema || [];
+        if (columns && columns.length) {
+            // PATCH the FULL schema = existing system columns + the new custom ones.
+            const custom = columns.map((c) => ({ ...c, display_name: c.display_name || c.name, create_type: "custom" }));
+            const res = await api.updateCollectionSchema(id, [...schema, ...custom]);
+            schema = (res && (res.data || res) || {}).schema || [...schema, ...custom];
+        }
+        return {
+            success: true,
+            collection_id: id,
+            table_name: col.table_name || tn,
+            columns: schema.map((f) => ({ name: f.name, type: f.type, kind: f.create_type || "system" })),
+            note: "Write rows via an HTTP function (db.model('" + (col.table_name || tn) + "').create({...})); query them with query_collection_records.",
+        };
+    }));
+    server.tool("update_collection_columns", "Add or change a collection's custom columns. Reads the current schema, then PATCHes it with the system columns + your custom columns (the PATCH replaces the whole schema, so omitting a column drops it).", {
+        collection_id: z.string().describe("Collection id (from list_collections / get_collection)."),
+        columns: z.array(COLUMN).describe("The FULL set of custom columns the table should have."),
+    }, ({ collection_id, columns }) => handle(async () => {
+        const cur = await api.getCollectionById(collection_id);
+        const schema = ((cur && (cur.data || cur)) || {}).schema || [];
+        const system = schema.filter((f) => (f.create_type || "system") === "system");
+        const custom = columns.map((c) => ({ ...c, display_name: c.display_name || c.name, create_type: "custom" }));
+        const res = await api.updateCollectionSchema(collection_id, [...system, ...custom]);
+        const newSchema = ((res && (res.data || res)) || {}).schema || [...system, ...custom];
+        return { success: true, collection_id, columns: newSchema.map((f) => ({ name: f.name, type: f.type, kind: f.create_type || "system" })) };
+    }));
+    server.tool("delete_collection", "Delete a collection (table) and all its records by id. Irreversible.", { collection_id: z.string().describe("Collection id.") }, ({ collection_id }) => handle(() => api.deleteCollection(collection_id)));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webcake-storefront-mcp",
-  "version": "1.31.1",
+  "version": "1.31.3",
   "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",