webcake-storefront-mcp 1.7.0 → 1.8.0

package/dist/api.js

@@ -363,6 +363,13 @@ export class WebcakeCmsApi {
     getApp(type) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/applications/subcriptions/get_app`, { query: { type } });
     }
+    /** Install (register) an application on the site. type = Enum.Application value
+     *  (e.g. automation=2, send_email=7). Body: { site_id, type, is_active }. */
+    registerApp(type, is_active = true) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/applications/subcriptions/register`, {
+            body: { site_id: this.siteId, type, is_active },
+        });
+    }
     // ── Promotions ──
     listPromotions(query) {
         return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/promotion_advance/all`, { query });
@@ -425,6 +432,24 @@ export class WebcakeCmsApi {
         return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/multilingual/update_global_source_contents`, { body: params });
     }
     // ── Automation ──
+    /** List the site's automations (id, name, rule/trigger, status). Use this to find the
+     *  automation_id to pass to send_mail. Returns { data: [...], total_entries, ... }. */
+    listAutomations(query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/automations/all`, { query });
+    }
+    createAutomation(automationAttrs) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/automations/create`, {
+            body: { automation_attrs: { ...automationAttrs, site_id: this.siteId } },
+        });
+    }
+    updateAutomation(automationAttrs) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/automations/update`, {
+            body: { automation_attrs: automationAttrs },
+        });
+    }
+    deleteAutomations(ids) {
+        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 });
     }

package/dist/changelog.json

@@ -1,4 +1,11 @@
 [
+  {
+    "v": "1.8.0",
+    "d": "23/06/2026",
+    "type": "Added",
+    "en": "New list_automations tool returns each automation's id, name, status, and trigger info so agents can find the automation_id required by send_mail or…",
+    "vi": "Tool mới list_automations trả về id, name, status và thông tin trigger của từng automation, giúp agent tìm được automation_id cần truyền vào…"
+  },
   {
     "v": "1.7.0",
     "d": "23/06/2026",
@@ -33,12 +40,5 @@
     "type": "Changed",
     "en": "The install command's interactive wizard now presents numbered choices with ANSI colour output and a completion summary.",
     "vi": "Trình hướng dẫn tương tác của lệnh install nay hiển thị các lựa chọn được đánh số kèm màu ANSI và thông báo tóm tắt sau khi hoàn tất."
-  },
-  {
-    "v": "1.3.0",
-    "d": "23/06/2026",
-    "type": "Added",
-    "en": "New create_site tool creates a brand-new storefront site for the current account (seeded with sample products, categories, and a blog), optionally…",
-    "vi": "Tool mới create_site tạo một site storefront hoàn toàn mới cho tài khoản hiện tại (kèm sản phẩm, danh mục và blog mẫu), tự động chuyển sang site vừa…"
   }
 ]

package/dist/enums.js

@@ -0,0 +1,46 @@
+// WebCake enum reference, mirrored from builderx_api so the AI knows what the numeric
+// codes / string values mean. Sources:
+//   - Enum.Application (lib/builderx_api/enum.ex) — application/app types
+//   - Automation schema (lib/builderx_api/automations/automation.ex) — type/status
+//   - Enum.PageType (page kinds) — kept here for one-stop reference
+/** Application types (the `type` used by get_app / install_app / register). */
+export const APP_TYPES = {
+    product_review: 0,
+    articles_review: 1,
+    automation: 2,
+    telegram: 3,
+    affiliates: 4,
+    multilingual: 5,
+    appointment: 6,
+    send_email: 7,
+    botcake: 8,
+    sale_channel: 9,
+    product_design: 10,
+    auth_otp: 11,
+    personal_product_design: 12,
+    course: 14,
+    zalo_mini_app: 15,
+    cms: 16,
+    recaptcha: 17,
+    pwa: 18,
+};
+export const APP_NAMES = Object.keys(APP_TYPES);
+/** name -> code and code -> name helpers. */
+export const APP_TYPE_BY_NAME = { ...APP_TYPES };
+export const APP_NAME_BY_TYPE = Object.fromEntries(Object.entries(APP_TYPES).map(([k, v]) => [v, k]));
+/** Automation.status values. */
+export const AUTOMATION_STATUS = ["ACTIVE", "INACTIVE"];
+/** Automation.type — user-built automations default to CUSTOM. */
+export const AUTOMATION_TYPE_DEFAULT = "CUSTOM";
+/** Page kinds (Enum.PageType) — numeric value stored on a page. */
+export const PAGE_TYPES = {
+    main: 1,
+    store: 2,
+    member: 3,
+    blog: 4,
+    custom: 5,
+    error: 6,
+    maintain: 7,
+};
+/** A compact human-readable summary, handy to surface in tool output. */
+export const APP_TYPE_REFERENCE = APP_NAMES.map((n) => `${APP_TYPES[n]}=${n}`).join(", ");

package/dist/guides.js

@@ -2,65 +2,127 @@ export const HTTP_FUNCTION_GUIDE = `
 # HTTP Function Guide
 
 ## Syntax
-export const [method]_[FunctionName] = (request) => { return result; }
-- Method: lowercase (get, post, put, patch, delete)
-- FunctionName: PascalCase
+export const [method]_[FunctionName] = async (request) => { return result; }
+- Method: lowercase (get, post, put, patch, delete) — picked from the export-name prefix.
+- FunctionName: keep it stable; it becomes the endpoint name.
+- Make it async; the return value is JSON-serialized and sent back to the caller.
 - Examples: get_Products, post_CreateOrder, delete_RemoveItem
 
-## Request object
-- request.params    — query params or body params
-- request.customer  — logged-in customer { id, name, email, first_name, last_name, phone_number, avatar }
-- request.account   — admin account { id, name, email, first_name, last_name, phone_number, avatar }
-- request.data      — full request params (including query string)
-
-## API endpoint after deploy
-GET/POST/PUT/PATCH /api/v1/{site_id}/_functions/{FunctionName}
-
-## webcake-data (Database SDK, built-in, no config needed)
+## The request argument
+Your function is called with ONE object: { params, customer, site_id, account, data }.
+- request.params    — the arguments the caller passed (query string for GET, body for POST/…).
+- request.customer  — the logged-in storefront customer (when authenticated), else {}. Fields: id, name, email, first_name, last_name, phone_number, avatar.
+- request.account   — the logged-in admin account (when called by an admin), else {}.
+- request.site_id   — the current site id (string).
+- request.data      — extra request data (usually {}).
+IMPORTANT: pass request through to the @webcake/* module functions (their first arg).
+
+## Endpoint after deploy
+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)
 import { DBConnection } from 'webcake-data';
-const db = new DBConnection();
-const Model = db.model('table_name');
+const db = new DBConnection();              // auto-uses the sandbox global site/token
+const Model = db.model('collection_name');
 
-### CRUD
-- Model.create({ field: value })
-- Model.insertMany([...])
-- Model.find(filter).sort().limit().skip().select().exec()
+### 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)
-- Model.updateOne(filter, update)
-- Model.findByIdAndUpdate(id, update)
+- 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)
-- Model.findByIdAndDelete(id)
+- Model.deleteOne(filter)                   → { acknowledged, deletedCount }
+- Model.findByIdAndDelete(id) / Model.findOneAndDelete(filter)
 - Model.deleteMany(filter)
-- Model.countDocuments(filter)
-- Model.exists(filter)
-
-### QueryBuilder
-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()
-
-### Populate (joins)
-Model.find().populate({ field: 'posts', table: 'posts', referenceField: 'user_id', select: 'title', where: {}, sort: {}, limit: 5 }).exec()
-
-### Operators
-where, eq, ne, gt, gte, lt, lte, in, nin, between, like, sort, limit, skip, select, populate
-
-## Built-in Modules
-- import { findArticleById, findArticle, createArticle, updateArticleById, deleteArticleById } from '@webcake/article'
-- import { findCustomerById, findCustomerByPhone, findCustomerByEmail } from '@webcake/customer'
-- import { addBonus } from '@webcake/promotion'
-- import { getAccessToken } from '@webcake/token'
-- import { sendMail } from '@webcake/app/automation'
-All module functions take (request, ...args) and auto-use global token/site_id.
-
-## Sandbox Globals (no import needed)
-- fetch(url, options) — HTTP requests
-- URLSearchParams — URL query building
-- console.log/warn/error — logging (captured in debug mode)
+- 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)
+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.
+
+- '@webcake/article'  (backend: /cms_function/{site}/blog/article…)
+    findArticleById(request, id, opts?)
+        GET .../blog/article/{id}?opts=<json>   → the article object ({} if not found)
+    findArticle(request, payload, opts?)
+        GET .../blog/article/all?<payload>&filters=<json>&opts=<json>
+        payload: { filters?:{...}, page?, limit? }   → { data:[...], ... }
+    createArticle(request, data)            POST .../blog/article   → full response
+        data the backend accepts: { name (required), summary, content (HTML),
+        images: string[] (hosted URLs), tags: string[], status_approval,
+        render_inserted_at, render_expired_at }.  slug is auto-generated; the article is
+        auto-filed under the default blog category (this endpoint takes NO category_id —
+        use the create_article MCP tool if you need explicit category linkage).
+        creator_id/customer_id come from the authenticated request.
+    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}
+    findCustomerByPhone(request, phone) GET .../customer/phone/{phone}
+    findCustomerByEmail(request, email) GET .../customer/email/{email}
+
+- '@webcake/promotion'  (backend: /cms_function/{site}/promotion/add_bonus)
+    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") }.
+
+- '@webcake/token'  (backend: /external/oauth/token)
+    getAccessToken(request)   → access_token string (throws if none).
+        Needs request.x_storecake_refresh_token present (sent as x-storecake-refresh-token).
+
+- '@webcake/app/automation'  (backend: /cms_function/{site}/application/automation/send_mail)
+    sendMail(request, automationId, data)   → response (throws if send fails).
+        Sends body { automation_id, data }. automation_id MUST be a valid UUID of an
+        automation set up on the site — find it with the MCP tool list_automations.
+        data is the payload passed into that automation/email template.
+
+## Sandbox globals (no import)
+- fetch(url, options)            — HTTP requests; response.ok/status/text()/json().
+- URLSearchParams                — build/parse query strings.
+- console.log / warn / error     — captured in debug mode (returned in data.logs).
+- encodeURIComponent / decodeURIComponent / encodeURI / decodeURI
 - global.domain, global.siteId, global.token, global.headers
+- Standard JS: JSON, Math, Date, Object, Array, String, Number, Map, Set, Promise, Error.
+NOT available: require()/import at runtime, Buffer, crypto, fs, process, setTimeout/setInterval, eval/Function.
+
+## Limits
+Runs sandboxed: ~4 MB memory, ~30 s timeout. The return value MUST be JSON-serializable.
 
-## Cron Jobs (jobs_config JSON)
+## Cron jobs (jobs_config JSON)
 { "jobs": [{ "functionLocation": "backend/http_function", "functionName": "myFunc", "executionConfig": { "cronExpression": "0 2 * * *" } }] }
+
+## Example
+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 };
+};
 `;
 export const CUSTOM_CODE_GUIDE = `
 # Custom Code Guide

package/dist/tools/apps.js

@@ -1,7 +1,40 @@
 import { z } from "zod";
+import { APP_TYPES, APP_NAMES, APP_TYPE_REFERENCE, APP_NAME_BY_TYPE } from "../enums.js";
 export function registerAppTools(server, api, handle) {
-    server.tool("list_apps", "List all installed applications/subscriptions of the site. Returns app type, status, and settings", {}, () => handle(() => api.listApps()));
-    server.tool("get_app", "Get a specific installed app by type ID. Common types: 1=CMS, 2=Product Design, 10=Multilingual, etc.", {
-        type: z.string().describe("App type ID"),
-    }, ({ type }) => handle(() => api.getApp(type)));
+    server.tool("list_apps", `List the site's installed applications (type, status, settings).
+App type codes: ${APP_TYPE_REFERENCE}.`, {}, () => handle(async () => {
+        const res = await api.listApps();
+        const raw = res?.data ?? res ?? [];
+        const list = Array.isArray(raw) ? raw : raw?.data || [];
+        return {
+            apps: list.map((a) => ({
+                type: a.type,
+                type_name: APP_NAME_BY_TYPE[a.type] ?? undefined,
+                status: a.status,
+                id: a.id,
+            })),
+            app_types: APP_TYPES,
+        };
+    }));
+    server.tool("get_app", `Get one installed app by its type code (returns null if not installed).
+App type codes: ${APP_TYPE_REFERENCE}. You may pass the number or the name.`, {
+        type: z.union([z.number(), z.string()]).describe(`App type — a code (e.g. 2) or a name (e.g. "automation"). Codes: ${APP_TYPE_REFERENCE}`),
+    }, ({ type }) => handle(() => {
+        const code = typeof type === "string" && type in APP_TYPES ? APP_TYPES[type] : type;
+        return api.getApp(code);
+    }));
+    server.tool("install_app", `Install (register) an application on the current site so its features become usable.
+For example, automations need the "automation" app installed first.
+App types: ${APP_TYPE_REFERENCE}.`, {
+        app: z.enum(APP_NAMES).describe("App to install (by name)"),
+        is_active: z.boolean().default(true).describe("Activate the app on install"),
+    }, ({ app, is_active }) => handle(async () => {
+        const type = APP_TYPES[app];
+        const existing = await api.getApp(type).catch(() => null);
+        if (existing?.app ?? existing?.data) {
+            return { app, type, already_installed: true };
+        }
+        await api.registerApp(type, is_active);
+        return { app, type, installed: true };
+    }));
 }

package/dist/tools/automation.js

@@ -1,8 +1,78 @@
 import { z } from "zod";
+import { APP_TYPES } from "../enums.js";
 export function registerAutomationTools(server, api, handle) {
-    server.tool("send_mail", "Send email via CMS automation", {
-        to: z.string().describe("Recipient email"),
-        subject: z.string().describe("Email subject"),
-        body: z.string().describe("Email body (supports HTML)"),
-    }, (params) => handle(() => api.sendMail(params)));
+    server.tool("list_automations", `List the site's automations so you can find an automation_id (e.g. to call send_mail, or to trigger from an HTTP function via @webcake/app/automation sendMail).
+Returns each automation's id, name, status and trigger info. Filter with 'term'. The id is what send_mail / the cms automation flow needs.`, {
+        term: z.string().optional().describe("Search by automation name"),
+        page: z.number().default(1).describe("Page number"),
+        limit: z.number().default(50).describe("Items per page"),
+    }, ({ term, page, limit }) => handle(async () => {
+        const res = await api.listAutomations({ ...(term ? { term } : {}), page, limit });
+        // Response shape: { automations: { data:[...], total_entries, page, limit }, ... }
+        const body = res?.automations || res?.data || res;
+        const raw = body?.data || body || [];
+        const list = Array.isArray(raw) ? raw : [];
+        const automations = list.map((a) => ({
+            id: a.id,
+            name: a.name,
+            status: a.status ?? (a.is_completed ? "completed" : undefined),
+            is_completed: a.is_completed,
+            // surface the trigger so the agent can tell which automation does what
+            trigger: a.rule?.trigger?.triggerType || a.rule?.trigger?.triggerKey || a.trigger_type || undefined,
+            updated_at: a.updated_at,
+        }));
+        return {
+            automations,
+            total: body?.total_entries ?? automations.length,
+            page,
+            hint: "Pass an automation's id as send_mail.automation_id (or to sendMail(request, automationId, data) inside an HTTP function).",
+        };
+    }));
+    // Automation lives behind the "Automation" application (Enum.Application automation = 2).
+    // Creating an automation requires that app installed, so we ensure it first.
+    const AUTOMATION_APP = APP_TYPES.automation;
+    async function ensureAutomationApp() {
+        const res = await api.getApp(AUTOMATION_APP).catch(() => null);
+        const app = res?.app ?? res?.data ?? null;
+        if (app)
+            return { installed: true, just_installed: false };
+        await api.registerApp(AUTOMATION_APP, true);
+        return { installed: true, just_installed: true };
+    }
+    server.tool("create_automation", `Create an automation. Checks the Automation app is installed first and installs it if needed.
+An automation = { name, type, status, rule }. 'rule' holds the trigger + actions (a map; shape depends on the trigger). Returns the new automation id (use it with send_mail for cms-triggered email).`, {
+        name: z.string().describe("Automation name"),
+        description: z.string().optional().describe("Description"),
+        type: z.string().default("CUSTOM").describe("Automation type (default CUSTOM)"),
+        status: z.enum(["ACTIVE", "INACTIVE"]).default("ACTIVE").describe("ACTIVE to run it, INACTIVE to keep it off"),
+        rule: z.record(z.any()).default({}).describe("Trigger + actions map. Leave {} for a blank automation you wire up later."),
+    }, ({ name, description, type, status, rule }) => handle(async () => {
+        const app = await ensureAutomationApp();
+        const res = await api.createAutomation({ name, ...(description ? { description } : {}), type, status, rule });
+        const a = res?.automation ?? res?.data ?? res;
+        return { success: true, automation_id: a?.id ?? null, name, status, app, hint: "Pass automation_id to send_mail to trigger it." };
+    }));
+    server.tool("update_automation", "Update an automation by id. Pass only the fields to change (name, description, type, status, rule).", {
+        id: z.string().describe("Automation id"),
+        name: z.string().optional(),
+        description: z.string().optional(),
+        type: z.string().optional(),
+        status: z.enum(["ACTIVE", "INACTIVE"]).optional(),
+        rule: z.record(z.any()).optional().describe("Replace the trigger + actions map"),
+    }, ({ id, ...fields }) => handle(async () => {
+        const res = await api.updateAutomation({ id, ...fields });
+        const a = res?.automation ?? res?.data ?? res;
+        return { success: true, automation_id: a?.id ?? id, updated: Object.keys(fields) };
+    }));
+    server.tool("delete_automation", "Delete one or more automations by id.", {
+        ids: z.array(z.string()).describe("Automation ids to delete"),
+    }, ({ ids }) => handle(async () => {
+        await api.deleteAutomations(ids);
+        return { success: true, deleted: ids };
+    }));
+    server.tool("send_mail", `Trigger a CMS automation to send an email (same endpoint @webcake/app/automation sendMail uses).
+Requires the automation_id — get it from list_automations. 'data' is the payload passed to that automation/email template.`, {
+        automation_id: z.string().describe("Automation id (a UUID) — from list_automations"),
+        data: z.record(z.any()).default({}).describe("Data object passed into the automation (e.g. recipient, variables for the email template)"),
+    }, ({ automation_id, data }) => handle(() => api.sendMail({ automation_id, data })));
 }

package/package.json

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