webcake-storefront-mcp 1.0.1

package/dist/api.js

@@ -0,0 +1,346 @@
+const DEFAULT_TIMEOUT = 15000;
+export class WebcakeCmsApi {
+    baseUrl;
+    token;
+    siteId;
+    sessionId;
+    _adminToken;
+    _cmsApiKey;
+    constructor({ baseUrl, token, siteId, sessionId }) {
+        this.baseUrl = (baseUrl || "").replace(/\/$/, "");
+        this.token = token;
+        this.siteId = siteId;
+        this.sessionId = sessionId || "";
+        this._adminToken = null;
+        this._cmsApiKey = null;
+    }
+    // CMS file / HTTP-function endpoints require an extra admin token + CMS API key
+    // bundled into the body. Fetched lazily and cached; reset on token/site switch.
+    async fetchCmsTokens() {
+        if (this._adminToken && this._cmsApiKey)
+            return;
+        const [adminRes, apiKeyRes] = await Promise.all([
+            this.request("GET", `/api/v1/dashboard/site/${this.siteId}/db_collections/token`),
+            this.request("GET", `/api/v1/dashboard/site/${this.siteId}/db_collections/api_key`),
+        ]);
+        this._adminToken = (adminRes && adminRes.data && adminRes.data.key) || null;
+        this._cmsApiKey = (apiKeyRes && apiKeyRes.data && apiKeyRes.data.key) || null;
+    }
+    getBundleParams() {
+        return { token: this._adminToken, x_cms_api_key: this._cmsApiKey };
+    }
+    async request(method, path, { body, query, timeout } = {}) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (query) {
+            for (const [k, v] of Object.entries(query)) {
+                if (v != null)
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.token}`,
+            ...(this.sessionId && { "x-session-id": this.sessionId }),
+        };
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeout || DEFAULT_TIMEOUT);
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const json = await res.json().catch(() => null);
+        if (!res.ok) {
+            const msg = (json && json.message) || (json && json.error) || res.statusText;
+            throw new Error(`API ${res.status}: ${msg}`);
+        }
+        return json;
+    }
+    // ── Account & Sites ──
+    getMe() {
+        return this.request("GET", `/api/v1/@me`);
+    }
+    listMySites(query) {
+        return this.request("GET", `/api/v1/dashboard/site/all`, { query });
+    }
+    getSiteInfo() {
+        return this.request("GET", `/api/v1/site/${this.siteId}/`);
+    }
+    /** Switch to a different site (in-memory, no restart needed) */
+    switchSite(siteId) {
+        this.siteId = siteId;
+        this._adminToken = null;
+        this._cmsApiKey = null;
+    }
+    /** Update auth token (in-memory) */
+    switchToken(token) {
+        this.token = token;
+        this._adminToken = null;
+        this._cmsApiKey = null;
+    }
+    /** Update session ID */
+    switchSession(sessionId) {
+        this.sessionId = sessionId;
+    }
+    // ── CMS Files ──
+    listCmsFiles() {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/cms_files`);
+    }
+    async createCmsFile(params) {
+        await this.fetchCmsTokens();
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/cms_files`, {
+            body: { ...params, ...this.getBundleParams() },
+        });
+    }
+    async updateCmsFile(id, params) {
+        await this.fetchCmsTokens();
+        return this.request("PATCH", `/api/v1/dashboard/site/${this.siteId}/cms_files/${id}`, {
+            body: { ...params, ...this.getBundleParams() },
+        });
+    }
+    getHttpFunction() {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/cms_files/http_function`);
+    }
+    async createOrUpdateHttpFunction(params) {
+        await this.fetchCmsTokens();
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/cms_files/http_function`, {
+            body: { ...params, ...this.getBundleParams() },
+        });
+    }
+    debugFunction(params) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/cms_files/debug`, { body: params });
+    }
+    runFunction(functionName, method, params) {
+        return this.request(method, `/api/v1/${this.siteId}/_functions/${functionName}`, { body: params });
+    }
+    saveFileVersion(params) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/cms_files/save_version_file`, { body: params });
+    }
+    getFileVersions(query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/cms_files/version_file`, { query });
+    }
+    toggleDebugRender(params) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/cms_files/toggle_is_debug_render`, { body: params });
+    }
+    // ── Pages ──
+    listPages() {
+        return this.request("GET", `/api/v1/site/${this.siteId}/pages`);
+    }
+    createPage(params) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/page`, { body: params });
+    }
+    updatePage(pageId, params) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/${pageId}/update_page`, { body: params });
+    }
+    updatePageSource(pageId, params) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/${pageId}/update_page_source`, { body: params });
+    }
+    deletePage(params) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/delete_page`, { body: params });
+    }
+    getPageVersions(pageId) {
+        return this.request("GET", `/api/v1/site/${this.siteId}/page_versions/${pageId}`);
+    }
+    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 });
+    }
+    listGlobalSections() {
+        return this.request("GET", `/api/v1/site/${this.siteId}/global_sections`);
+    }
+    getSite() {
+        return this.request("GET", `/api/v1/site/${this.siteId}/`);
+    }
+    saveSite(params = {}) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/save`, { body: params, timeout: 60000 });
+    }
+    publishSite(params = {}) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/publish`, { body: params, timeout: 60000 });
+    }
+    uploadImageBase64({ base64, content_type } = {}) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/media/content/b64`, {
+            body: { base64, content_type },
+            timeout: 60000,
+        });
+    }
+    async getSiteSettingField(field) {
+        const siteRes = await this.request("GET", `/api/v1/site/${this.siteId}/`, { timeout: 60000 });
+        const raw = (siteRes && siteRes.data && siteRes.data.settings) || "";
+        if (typeof raw === "object")
+            return raw[field] || "";
+        const needle = `"${field}":`;
+        const idx = raw.indexOf(needle);
+        if (idx === -1)
+            return "";
+        let vStart = idx + needle.length;
+        while (vStart < raw.length && raw[vStart] === " ")
+            vStart++;
+        if (raw[vStart] !== '"')
+            return "";
+        let vEnd = vStart + 1;
+        while (vEnd < raw.length) {
+            if (raw[vEnd] === "\\") {
+                vEnd += 2;
+                continue;
+            }
+            if (raw[vEnd] === '"') {
+                vEnd++;
+                break;
+            }
+            vEnd++;
+        }
+        try {
+            return JSON.parse(raw.slice(vStart, vEnd));
+        }
+        catch {
+            return "";
+        }
+    }
+    async updateSiteSettings(newSettings) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/update_site`, { body: { settings: newSettings }, timeout: 60000 });
+    }
+    // ── Collections ──
+    listCollections(query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/db_collections`, { query });
+    }
+    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 });
+    }
+    // ── Blog Articles ──
+    listArticles(query) {
+        return this.request("GET", `/api/v1/cms_function/${this.siteId}/blog/article/all`, { query });
+    }
+    getArticle(id) {
+        return this.request("GET", `/api/v1/cms_function/${this.siteId}/blog/article/${id}`);
+    }
+    createArticle(params) {
+        return this.request("POST", `/api/v1/cms_function/${this.siteId}/blog/article`, { body: params });
+    }
+    updateArticle(id, params) {
+        return this.request("PATCH", `/api/v1/cms_function/${this.siteId}/blog/article/${id}`, { body: params });
+    }
+    deleteArticle(id) {
+        return this.request("DELETE", `/api/v1/cms_function/${this.siteId}/blog/article/${id}`);
+    }
+    // ── Products ──
+    listProducts(query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/products/all`, { query });
+    }
+    getProduct(id) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/products/${id}`);
+    }
+    searchProducts(query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/products/search`, { query });
+    }
+    listCategories() {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/categories/all`);
+    }
+    getProductsByCategory(categoryId) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/categories/products`, { query: { category_id: categoryId } });
+    }
+    // ── Orders ──
+    listOrders(query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/orders/all`, { query });
+    }
+    getOrder(orderId) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/orders/${orderId}`);
+    }
+    countOrdersByStatus() {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/orders/count_by_status`);
+    }
+    // ── Site Style / Themes ──
+    listThemes() {
+        return this.request("GET", `/api/v1/site/${this.siteId}/themes`);
+    }
+    /**
+     * Semantic search over the theme marketplace embeddings (bge-m3, cosine similarity).
+     * Returns { results: [[theme_embedding_record, score], ...] }.
+     */
+    semanticSearchThemes(query) {
+        return this.request("POST", `/api/v1/ai/semantic_search`, { body: { query }, timeout: 45000 });
+    }
+    // ── Applications ──
+    listApps() {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/applications/subcriptions/all`);
+    }
+    getApp(type) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/applications/subcriptions/get_app`, { query: { type } });
+    }
+    // ── Promotions ──
+    listPromotions(query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/promotion_advance/all`, { query });
+    }
+    getPromotion(id) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/promotion_advance/get_promotion`, { query: { id } });
+    }
+    getPromotionItems(id, query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/promotion_advance/get_items`, { query: { id, ...query } });
+    }
+    getActivePromotions() {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/promotion_advance/get_promotions_actived`);
+    }
+    searchPromotions(query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/promotion_advance/get_promotions_advance`, { query });
+    }
+    // ── Combos ──
+    listCombos(query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/combo_product/all`, { query });
+    }
+    getComboItems(comboProductId, query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/combo_product/items`, { query: { combo_product_id: comboProductId, ...query } });
+    }
+    // ── Customers ──
+    findCustomerById(id) {
+        return this.request("GET", `/api/v1/cms_function/${this.siteId}/customer/identity/${id}`);
+    }
+    findCustomerByPhone(phone) {
+        return this.request("GET", `/api/v1/cms_function/${this.siteId}/customer/phone/${phone}`);
+    }
+    findCustomerByEmail(email) {
+        return this.request("GET", `/api/v1/cms_function/${this.siteId}/customer/email/${email}`);
+    }
+    // ── Global Sources (cart, popup, overview, etc.) ──
+    getSourceCart() {
+        return this.request("GET", `/api/v1/site/${this.siteId}/cart/get_source_cart`);
+    }
+    createSourceCart(params) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/cart/create_source_cart`, { body: params });
+    }
+    updateSourceCart(params) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/cart/update_source_cart`, { body: params });
+    }
+    getGlobalSources(query) {
+        return this.request("GET", `/api/v1/site/${this.siteId}/global_source/`, { query });
+    }
+    createGlobalSource(params) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/global_source/create`, { body: params });
+    }
+    updateGlobalSource(params) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/global_source/update`, { body: params });
+    }
+    deleteGlobalSource(params) {
+        return this.request("POST", `/api/v1/site/${this.siteId}/global_source/delete`, { body: params });
+    }
+    getGlobalSourceContents(query) {
+        return this.request("GET", `/api/v1/dashboard/site/${this.siteId}/multilingual/global_source_contents`, { query });
+    }
+    updateGlobalSourceContents(params) {
+        return this.request("POST", `/api/v1/dashboard/site/${this.siteId}/multilingual/update_global_source_contents`, { body: params });
+    }
+    // ── Automation ──
+    sendMail(params) {
+        return this.request("POST", `/api/v1/cms_function/${this.siteId}/application/automation/send_mail`, { body: params });
+    }
+}

package/dist/auth/login.js

@@ -0,0 +1,87 @@
+// Browser login: spins up a loopback server, opens the builder app's /mcp-connect
+// page, and receives the user's token back on the local callback — then saves it to
+// the local config db so the stdio server picks it up automatically.
+import { createServer } from "node:http";
+import { randomBytes } from "node:crypto";
+import { spawn } from "node:child_process";
+import { resolveSettings } from "../config.js";
+import { setConfig } from "../db.js";
+function parseArgs(argv) {
+    const opts = { open: true };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--no-open")
+            opts.open = false;
+        else if (a === "--port")
+            opts.port = Number(argv[++i]);
+        else if (a === "--api-base" || a === "--api-url")
+            opts.apiUrl = argv[++i];
+        else if (a === "--app-base" || a === "--app-url")
+            opts.appUrl = argv[++i];
+        else if (a === "--site" || a === "--site-id")
+            opts.siteId = argv[++i];
+    }
+    return opts;
+}
+function openBrowser(url) {
+    const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "start" : "xdg-open";
+    try {
+        spawn(cmd, [url], { stdio: "ignore", detached: true, shell: process.platform === "win32" }).unref();
+    }
+    catch {
+        /* user can open the URL manually */
+    }
+}
+const SUCCESS_HTML = "<!doctype html><meta charset=utf-8><title>Connected</title><body style='font:16px system-ui;padding:3rem;text-align:center'><h2>✓ Connected to WebCake</h2><p>You can close this tab and return to your terminal.</p></body>";
+function readQuery(url) {
+    const q = (url ?? "").indexOf("?");
+    return new URLSearchParams(q === -1 ? "" : (url ?? "").slice(q + 1));
+}
+export async function runLogin(argv) {
+    const opts = parseArgs(argv);
+    const settings = resolveSettings({ apiUrl: opts.apiUrl, appUrl: opts.appUrl });
+    const appUrl = settings.appUrl.replace(/\/$/, "");
+    const apiUrl = settings.apiUrl.replace(/\/$/, "");
+    const state = randomBytes(16).toString("hex");
+    await new Promise((resolve, reject) => {
+        const server = createServer((req, res) => {
+            const params = readQuery(req.url);
+            const token = params.get("token") || params.get("jwt");
+            const wsid = params.get("wsid") || params.get("session_id") || "";
+            const returnedState = params.get("state");
+            if (!token) {
+                res.writeHead(400, { "content-type": "text/html" }).end("<p>Missing token.</p>");
+                return;
+            }
+            if (returnedState && returnedState !== state) {
+                res.writeHead(400, { "content-type": "text/html" }).end("<p>State mismatch.</p>");
+                return;
+            }
+            setConfig("token", token);
+            if (wsid)
+                setConfig("session_id", wsid);
+            if (apiUrl)
+                setConfig("api_url", apiUrl);
+            if (opts.siteId)
+                setConfig("site_id", opts.siteId);
+            res.writeHead(200, { "content-type": "text/html" }).end(SUCCESS_HTML);
+            console.error(`\n✓ Connected. Token${wsid ? " + session" : ""} saved to local config (api ${apiUrl || "<unset>"}).`);
+            server.close();
+            resolve();
+        });
+        server.listen(opts.port ?? 0, "127.0.0.1", () => {
+            const addr = server.address();
+            const port = typeof addr === "object" && addr ? addr.port : opts.port;
+            const redirectUri = `http://127.0.0.1:${port}/callback`;
+            const full = `${appUrl}/mcp-storefront?redirect_uri=${encodeURIComponent(redirectUri)}&state=${state}`;
+            console.error("Opening your browser to connect (log in to WebCake there if prompted):");
+            console.error("  " + full + "\n");
+            if (opts.open)
+                openBrowser(full);
+        });
+        setTimeout(() => {
+            server.close();
+            reject(new Error("login timed out after 180s."));
+        }, 180_000).unref();
+    });
+}

package/dist/builder/catalog.js

@@ -0,0 +1,186 @@
+// Catalog / registry layer over builder/factory.js.
+//
+// The factory functions are the source of truth for a valid BuilderX component node.
+// Here we (1) build a type -> factory map automatically by probing every exported
+// create* function, (2) attach curated, human-readable metadata (category + summary)
+// so an AI agent can understand the palette, and (3) expose helpers the MCP tools use.
+import * as F from "./factory.js";
+// Probe every factory once with safe default opts to learn the type string it produces
+// and whether it is a container (has a children array). Calling with {children:[]} is
+// safe for all 132 factories (verified) — none throw.
+const FACTORY_BY_TYPE = {};
+const CONTAINER_TYPES = new Set();
+const ALL_TYPES = [];
+for (const [name, fn] of Object.entries(F)) {
+    if (typeof fn !== "function" || !name.startsWith("create"))
+        continue;
+    let node;
+    try {
+        node = fn({ children: [] });
+    }
+    catch {
+        continue;
+    }
+    if (!node || !node.type)
+        continue;
+    if (!FACTORY_BY_TYPE[node.type]) {
+        FACTORY_BY_TYPE[node.type] = fn;
+        ALL_TYPES.push(node.type);
+        if (Array.isArray(node.children))
+            CONTAINER_TYPES.add(node.type);
+    }
+}
+ALL_TYPES.sort();
+// ── Curated categorisation ───────────────────────────────────────────────────
+// Maps each known type to a category. Types not listed fall back to "other".
+const CATEGORY_MEMBERS = {
+    layout: [
+        "section", "container", "row", "slide", "carousel", "swiper", "collapse",
+        "collapse-item", "collapse-content", "tabs", "custom-layout", "question-container",
+        "layout-dataset",
+    ],
+    content: [
+        "text", "text-dataset", "image", "image-dataset", "video", "video-dataset",
+        "rectangle", "rectangle-dataset", "line", "gallery", "list-ordered", "embed",
+        "googlemap", "breadcrumb", "tags", "countdown", "table", "agency", "calendar",
+        "calendar-content",
+    ],
+    button: [
+        "button", "submit-button", "paypal-button", "button-login-google",
+        "button-login-facebook", "current-location",
+    ],
+    form: [
+        "form", "input", "email", "phone-number", "retype-phone-number", "password",
+        "retype-password", "current-password", "text-area", "select", "group-select",
+        "checkbox", "checkbox-group", "checkbox-item", "radio", "radio-group", "address",
+        "detect-address", "postal-code", "country", "input-file", "input-number",
+        "input-date", "input-search", "input-product-note", "otp-input", "rating-input",
+        "two-point-range", "identity", "search-form", "search-droppable", "color-group",
+        "switch",
+    ],
+    commerce: [
+        "grid-product", "slider-product", "product-gallery", "product-image-carousel",
+        "cart-items", "cart-icon", "cart-droppable", "cart-items-empty", "quantity-input",
+        "attr", "payment", "delivery-method", "order-items", "order-history", "coupon",
+        "product-overlay", "product-review", "masonry-review", "empty-product-layout",
+        "bonus-items", "flash-sale", "promotions", "promotions-short", "grid-category",
+        "slider-category", "number-step", "warehouse", "warehouse-dataset",
+        "customer-address", "reward-point", "referral-code", "lucky-wheel", "tee-form",
+        "wishlist", "favorite-icon",
+    ],
+    navigation: [
+        "menu", "menu-item", "menu-anchor-item", "submenu", "menu-droppable", "member-bar",
+        "member-dropdown", "dropdown", "dropdown-content", "language-menu",
+    ],
+    blog: [
+        "post-list", "slider-post", "grid-blog", "slider-blog", "post-overlay",
+        "blog-overlay",
+    ],
+    marketing: [
+        "notify", "popup", "auto-number", "random-number", "user-point-log",
+    ],
+    course: [
+        "lesson-sidebar", "lesson-items", "next-lesson-droppable", "list-lesson-droppable",
+    ],
+};
+const CATEGORY_BY_TYPE = {};
+for (const [cat, members] of Object.entries(CATEGORY_MEMBERS)) {
+    for (const t of members)
+        CATEGORY_BY_TYPE[t] = cat;
+}
+// Short one-line summaries for the most commonly authored types. Types without an
+// entry get an auto summary. get_element returns a live skeleton anyway, so this only
+// needs to help the agent pick the right type.
+const SUMMARY = {
+    section: "Top-level band/row container. Every page is a stack of sections. Holds children in a CSS grid.",
+    container: "Generic grid/flex box to group elements and position them together.",
+    row: "Simple horizontal row wrapper.",
+    text: "Rich text block (headings, paragraphs). Content in specials.text, tag in specials.tag.",
+    "text-dataset": "Text bound to a dataset field (product name, price...). Uses bindings[].",
+    image: "Static image. URL goes in runtime.config.src.",
+    "image-dataset": "Image bound to a dataset field. Uses bindings[].",
+    video: "Video player. specials.src + specials.thumbnail.",
+    rectangle: "Coloured box / shape, useful as a background or divider.",
+    line: "Separator line.",
+    button: "Clickable button. Label in specials.text, actions in events[].",
+    "submit-button": "Form submit button.",
+    gallery: "Image gallery/lightbox. Images in specials.media[].",
+    carousel: "Auto/paginated carousel of slides.",
+    slide: "A single slide inside a carousel.",
+    form: "Form wrapper. Put input fields as children. specials.type selects form behaviour.",
+    input: "Text input field. specials.field_name, placeholder, label, required.",
+    email: "Email input field.",
+    "phone-number": "Phone number input field.",
+    "text-area": "Multi-line text input.",
+    select: "Dropdown select.",
+    checkbox: "Single checkbox.",
+    radio: "Radio button.",
+    address: "Address input.",
+    "grid-product": "Product grid (lists products from the store).",
+    "slider-product": "Product slider/carousel.",
+    "cart-items": "Shopping cart line items.",
+    "cart-icon": "Cart icon with item count.",
+    "quantity-input": "Quantity stepper for products.",
+    payment: "Payment methods block.",
+    "delivery-method": "Shipping/delivery options block.",
+    "order-items": "Order summary line items.",
+    coupon: "Coupon / discount code input.",
+    menu: "Navigation menu container.",
+    "menu-item": "A single navigation menu link.",
+    countdown: "Countdown timer.",
+    embed: "Raw HTML / iframe embed.",
+    googlemap: "Google Maps iframe embed.",
+    popup: "Modal/overlay popup container.",
+    notify: "Notification / alert banner.",
+    tabs: "Tabbed content container.",
+    collapse: "Accordion / collapsible panel.",
+    breadcrumb: "Breadcrumb navigation trail.",
+};
+function describeType(type) {
+    return {
+        type,
+        category: CATEGORY_BY_TYPE[type] || "other",
+        container: CONTAINER_TYPES.has(type),
+        summary: SUMMARY[type] || `BuilderX "${type}" element.`,
+    };
+}
+/** Build a fresh, structurally-valid node of the given type using the real factory. */
+export function buildElement(type, opts = {}) {
+    const fn = FACTORY_BY_TYPE[type];
+    if (!fn) {
+        const err = new Error(`Unknown element type "${type}". Use list_elements to see valid types.`);
+        err.code = "UNKNOWN_TYPE";
+        throw err;
+    }
+    // Guarantee children-using factories never throw on a missing children array.
+    return fn({ children: [], ...opts });
+}
+export function isKnownType(type) {
+    return Boolean(FACTORY_BY_TYPE[type]);
+}
+export function listElements() {
+    const categories = {};
+    for (const type of ALL_TYPES) {
+        const d = describeType(type);
+        (categories[d.category] ||= []).push({
+            type: d.type,
+            container: d.container,
+            summary: d.summary,
+        });
+    }
+    return { total: ALL_TYPES.length, categories };
+}
+export function getElement(type) {
+    if (!isKnownType(type)) {
+        return {
+            error: `Unknown type "${type}"`,
+            valid_types: ALL_TYPES,
+        };
+    }
+    const d = describeType(type);
+    // A live skeleton straight from the factory = authoritative shape for this type.
+    const skeleton = buildElement(type, {});
+    return { ...d, skeleton };
+}
+export const ELEMENT_TYPES = ALL_TYPES;
+export const CONTAINER_TYPE_SET = CONTAINER_TYPES;