webcake-storefront-mcp 1.31.0 → 1.31.2

package/dist/changelog.json

@@ -1,4 +1,18 @@
 [
+  {
+    "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",
+    "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",
@@ -26,19 +40,5 @@
     "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ỗ…"
-  },
-  {
-    "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…"
   }
 ]

package/dist/guides.js

@@ -22,40 +22,87 @@ 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()
-
-## Built-in @webcake/* modules (first arg is always request; they auth via global.token)
+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 });
+
+### 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.
 
@@ -75,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).
@@ -136,18 +188,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/package.json

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