webcake-storefront-mcp 1.30.0 → 1.31.1

package/dist/api.js

@@ -29,7 +29,7 @@ export class WebcakeCmsApi {
     getBundleParams() {
         return { token: this._adminToken, x_cms_api_key: this._cmsApiKey };
     }
-    async request(method, path, { body, query, timeout } = {}) {
+    async request(method, path, { body, query, timeout, headers: extraHeaders } = {}) {
         const url = new URL(`${this.baseUrl}${path}`);
         if (query) {
             for (const [k, v] of Object.entries(query)) {
@@ -41,6 +41,7 @@ export class WebcakeCmsApi {
             "Content-Type": "application/json",
             Authorization: `Bearer ${this.token}`,
             ...(this.sessionId && { "x-session-id": this.sessionId }),
+            ...(extraHeaders || {}),
         };
         const controller = new AbortController();
         const timer = setTimeout(() => controller.abort(), timeout || DEFAULT_TIMEOUT);
@@ -340,8 +341,37 @@ export class WebcakeCmsApi {
     getCollection(id) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/db_collections/${id}`);
     }
-    queryCollectionRecords(tableName, query) {
-        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records`, { query });
+    /** Header carrying the CMS api key — collection-data endpoints (records) need it on top of
+     *  the dashboard JWT (without it they 401). Fetches the key once and caches it. */
+    async cmsApiHeader() {
+        await this.fetchCmsTokens();
+        return this._cmsApiKey ? { "x-cms-api-key": this._cmsApiKey } : {};
+    }
+    /** Query a collection's records. Needs the CMS api-key header (else 401). The records
+     *  endpoint accepts page/limit plus `where` (a filter object/JSON) and `order_by`. */
+    async queryCollectionRecords(tableName, query) {
+        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) {
+        const headers = await this.cmsApiHeader();
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records`, { body: record, headers });
+    }
+    /** Update a record by id. Body = the changed fields. CMS-api-key authed. */
+    async updateCollectionRecord(tableName, recordId, record) {
+        const headers = await this.cmsApiHeader();
+        return this.request("PATCH", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records/${recordId}`, { body: record, headers });
+    }
+    /** Delete a record by id. CMS-api-key authed. */
+    async deleteCollectionRecord(tableName, recordId) {
+        const headers = await this.cmsApiHeader();
+        return this.request("DELETE", `/api/v1/dashboard/site/${this.siteId}/db_collections/collections/${tableName}/records/${recordId}`, { headers });
+    }
+    /** Create a collection (table). Body: { name, schema:[{name,type,...}], ... }. */
+    async createCollection(params) {
+        const headers = await this.cmsApiHeader();
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/db_collections`, { body: params, headers, timeout: 60000 });
     }
     // ── Blog Articles ──
     listArticles(query) {

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "v": "1.31.1",
+    "d": "26/06/2026",
+    "type": "Fixed",
+    "en": "The webcake-data SDK reference embedded in get_http_function and get_site_custom_code now documents the correct Mongoose-document API: filters are…",
+    "vi": "Tài liệu tham chiếu SDK webcake-data được nhúng trong get_http_function và get_site_custom_code nay ghi lại đúng API kiểu Mongoose-document: bộ lọc…"
+  },
+  {
+    "v": "1.31.0",
+    "d": "26/06/2026",
+    "type": "Added",
+    "en": "New create_collection tool creates a custom data table by accepting a name and a schema array of field definitions (with types such as string,…",
+    "vi": "Tool mới create_collection tạo bảng dữ liệu tùy chỉnh bằng cách nhận tham số name và mảng schema chứa định nghĩa các trường (với các kiểu dữ liệu…"
+  },
   {
     "v": "1.30.0",
     "d": "26/06/2026",
@@ -26,19 +40,5 @@
     "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ỗ…"
-  },
-  {
-    "v": "1.26.1",
-    "d": "26/06/2026",
-    "type": "Fixed",
-    "en": "list_products now correctly unwraps the { products, total_product } API response shape, returning a product array and accurate total instead of…",
-    "vi": "list_products nay giải nén đúng kiểu phản hồi { products, total_product } từ API, trả về mảng sản phẩm và tổng chính xác thay vì trả thẳng đối tượng…"
-  },
-  {
-    "v": "1.26.0",
-    "d": "26/06/2026",
-    "type": "Fixed",
-    "en": "create_product now accepts a short_description parameter and sends it to the backend as [{description}] — the array shape the real product schema…",
-    "vi": "create_product nay nhận thêm tham số short_description và gửi lên backend dưới dạng [{description}] — đúng kiểu mảng mà schema sản phẩm thực tế yêu…"
   }
 ]

package/dist/guides.js

@@ -22,38 +22,59 @@ ANY method → /api/v1/{site_id}/_functions/{FunctionName}
 The caller receives your return value as data.result. From the storefront, the
 webcake-fn client (api.method_FunctionName(params)) returns that result directly.
 
-## webcake-data — Database SDK (built-in)
+## webcake-data — Database SDK (built-in). This is the MAIN way to read/write a site's collections.
 import { DBConnection } from 'webcake-data';
 const db = new DBConnection();              // auto-uses the sandbox global site/token
-const Model = db.model('collection_name');
-
-### Model CRUD (all async unless noted)
-- Model.create(doc)                         → created doc
-- Model.insertMany([doc, ...])              → array
-- Model.find(filter)                        → QueryBuilder (NOT a promise — chain then .exec()/await)
-- Model.findOne(filter, { select, sort, populate })
-- Model.findById(id, { select, populate })
-- Model.updateOne(filter, update)           → { acknowledged, matchedCount, modifiedCount }
-- Model.findByIdAndUpdate(id, update, { new: true })
-- Model.findOneAndUpdate(filter, update)
-- Model.updateMany(filter, update)
-- Model.deleteOne(filter)                   → { acknowledged, deletedCount }
-- Model.findByIdAndDelete(id) / Model.findOneAndDelete(filter)
-- Model.deleteMany(filter)
-- Model.countDocuments(filter)              → number
-- Model.exists(filter)                      → boolean
-
-### QueryBuilder (from Model.find())
-Chain then terminate with .exec() (or just await the chain):
-Model.find().where('age').gte(25).lte(40).in('role',['admin']).like('email','%@ex.com')
-  .sort({ age:-1 }).limit(20).skip(10).select('name email').exec()
-Operators: where, eq, ne, gt, gte, lt, lte, in, nin, between, like, sort, limit, skip, select, populate.
-
-### Populate (join another collection)
-Model.find().populate({
-  field:'posts', table:'posts', referenceField:'user_id',
-  select:'title', where:{}, sort:{ created_at:-1 }, limit:5, skip:0, justOne:false
-}).exec()
+const Model = db.model('collection_name');  // 'collection_name' = the table_name of a collection
+
+The API is Mongoose-DOCUMENT style: filters are plain MongoDB-style OBJECTS, chains are
+DIRECTLY AWAITABLE (NO .exec()), and you select fields with an ARRAY. Every document has an
+\`id\` (UUID string) plus \`inserted_at\` / \`updated_at\`.
+
+### Read
+- await Model.findOne(filter)                          → one doc (or null)
+- await Model.findOne(filter, { populate:{ field, select:[...] } })
+- await Model.find(filter).select([...]).populate({...}).sort({...}).limit(n)   → array (await the CHAIN; no .exec())
+- await Model.countDocuments(filter)                   → number
+
+filter is a MongoDB-style object. Operators go INSIDE the field value:
+  { thanh_vien: userId }                                 // equals
+  { status: { $in: [0, 1, 2] } }                         // in a list
+  { trang_thai_tg: { $ne: 3 } }                          // not equal
+  // also $nin, $gt, $gte, $lt, $lte, $exists — the usual MongoDB query operators.
+
+Chain methods on a Model.find(filter):
+  .select(["id", "name", "diem_so"])                    // ARRAY of field names to return
+  .sort({ inserted_at: -1 })                            // 1 ascending, -1 descending (multi-key ok)
+  .limit(20)  .skip(0)
+  .populate({ field: "thanh_vien", select: ["id", "name", "avatar"] })
+
+### Populate (resolve a reference field)
+A reference field stores the related row's \`id\` (a string). \`.populate({ field, select:[...] })\`
+replaces it with the related OBJECT (only the selected fields). After populate, read it as an
+object; before/without populate it's the raw id string. Handle both:
+  const id = typeof row.thanh_vien === "object" ? row.thanh_vien.id : row.thanh_vien;
+populate also works as a 2nd-arg option on findOne: Model.findOne(filter, { populate:{ field, select:[...] } }).
+
+### Write
+- await Model.create(doc)                               → created doc (use doc.id afterwards)
+- await Model.findOneAndUpdate(filter, update, { new: true })   → the UPDATED doc ({ new:true } = return the new version)
+- await Model.updateOne(filter, update)                 → write result
+- await Model.updateMany(filter, update)                → bulk update matching rows
+- await Model.deleteMany(filter)                        → delete matching rows
+(update is a plain object of the fields to set, e.g. { status: 1, ty_le_thang: 75 }.)
+
+### Real example pattern (from a production function)
+const Members = db.model("thanh_vien_ps");
+const rows = await Members
+  .find({ playspace: psId, status: { $in: [0, 1, 2] } })
+  .select(["id", "thanh_vien", "tien_con_lai", "status"])
+  .populate({ field: "thanh_vien", select: ["id", "name", "avatar"] })
+  .sort({ status: 1, inserted_at: 1 })
+  .limit(50);
+const count = await Members.countDocuments({ playspace: psId, status: { $in: [0, 1, 2] } });
+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)
 Thin wrappers over the backend's /cms_function/{site_id}/... endpoints. Pass request so
@@ -136,18 +157,36 @@ Runs sandboxed: ~4 MB memory, ~30 s timeout. The return value MUST be JSON-seria
 ## Cron jobs (jobs_config JSON)
 { "jobs": [{ "functionLocation": "backend/http_function", "functionName": "myFunc", "executionConfig": { "cronExpression": "0 2 * * *" } }] }
 
-## Example
+## Example (real-world shape)
+Declare the models + db ONCE at module top, then one export per endpoint. Read the caller from
+request.customer?.id (auth) and the inputs from request.params. Return a plain JSON object —
+the convention is { mess: "OK", ...data } on success or { mess: "ERROR_CODE" } on failure.
 import { DBConnection } from 'webcake-data';
 import { findCustomerById } from '@webcake/customer';
-export const post_RecentOrders = async (request) => {
-  const { params, customer } = request;
-  const db = new DBConnection();
-  const orders = await db.model('orders')
-    .find().where('customer_id').eq(customer.id || params.customer_id)
-    .sort({ created_at:-1 }).limit(10)
-    .populate({ field:'items', table:'order_items', referenceField:'order_id', limit:50 })
-    .exec();
-  return { count: orders.length, orders };
+
+const db = new DBConnection();
+const Members = db.model('thanh_vien_ps');
+
+export const post_MyMembers = async (request) => {
+  const userId = request.customer?.id ?? "";        // the logged-in storefront customer
+  if (!userId) return { mess: "NO_ACCOUNT_CALL" };
+  const { playspace = "" } = request.params || {};  // POST body params
+  try {
+    const rows = await Members
+      .find({ playspace, status: { $in: [0, 1, 2] } })
+      .select(["id", "thanh_vien", "tien_con_lai", "status"])
+      .populate({ field: "thanh_vien", select: ["id", "name", "avatar"] })
+      .sort({ status: 1, inserted_at: 1 })
+      .limit(50);
+    const data = rows.map((row) => {
+      const m = row.thanh_vien || {};                // populated object
+      return { thanh_vien_ps: row.id, ten: m.name || "", tien: Number(row.tien_con_lai) || 0 };
+    });
+    return { mess: "OK", data };
+  } catch (err) {
+    console.error(err?.message || err);
+    return { mess: "SYSTEM_ERROR" };
+  }
 };
 `;
 export const CUSTOM_CODE_GUIDE = `

package/dist/tools/collections.js

@@ -25,9 +25,40 @@ export function registerCollectionTools(server, api, handle) {
     server.tool("get_collection", "Get a specific collection's details including full schema (field names, types, constraints, references) and records", {
         id: z.string().describe("Collection ID"),
     }, ({ id }) => handle(() => api.getCollection(id)));
-    server.tool("query_collection_records", "Query records from a collection by table name. Use to inspect existing data", {
-        table_name: z.string().describe("Collection table name (e.g. 'subscribers', 'custom_orders')"),
+    server.tool("query_collection_records", "Query records from a collection (custom data table) by table name. Supports paging + an optional `where` filter and `order_by` sort. (Uses the CMS api-key auth the records endpoint requires.)", {
+        table_name: z.string().describe("Collection table name (e.g. 'subscribers', 'custom_orders') — from get_collection.table_name"),
         page: z.number().optional().describe("Page number"),
         limit: z.number().optional().describe("Items per page"),
-    }, ({ table_name, page, limit }) => handle(() => api.queryCollectionRecords(table_name, { page, limit })));
+        where: z.record(z.any()).optional().describe("Filter object, e.g. { status: 'active' } — matches records by field value."),
+        order_by: z.string().optional().describe("Field to sort by (e.g. 'inserted_at')."),
+    }, ({ table_name, page, limit, where, order_by }) => handle(() => {
+        const query = { page: page ?? 1, limit: limit ?? 50 };
+        if (where && Object.keys(where).length)
+            query.where = JSON.stringify(where);
+        if (order_by)
+            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)));
 }

package/package.json

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