@ikas/code-components-mcp 1.4.0-beta.176 → 1.4.0-beta.178

package/data/storefront-api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-24T11:36:32.957Z",
+  "generatedAt": "2026-09-01T07:21:40.959Z",
   "functions": [
     {
       "name": "apiListProductBrand",
@@ -101,16 +101,16 @@
     },
     {
       "name": "apiListLoyaltyProgramPointHistory",
-      "signature": "async function apiListLoyaltyProgramPointHistory(params: ListLoyaltyProgramPointHistoryQueryParams): Promise<APIResponse<IkasLoyaltyProgramPointHistoryPaginationResponse>>",
+      "signature": "async function apiListLoyaltyProgramPointHistory(params: ListLoyaltyProgramPointHistoryQueryParams): Promise<APIResponse<IkasLoyaltyProgramPointHistory[]>>",
       "description": "",
       "params": [],
-      "returnType": "Promise<APIResponse<IkasLoyaltyProgramPointHistoryPaginationResponse>>",
+      "returnType": "Promise<APIResponse<IkasLoyaltyProgramPointHistory[]>>",
       "categories": [],
       "related": [],
       "isAsync": true,
       "isClass": false,
       "parameterTypes": [
-        "IkasLoyaltyProgramPointHistoryPaginationResponse"
+        "IkasLoyaltyProgramPointHistory"
       ]
     },
     {
@@ -3085,6 +3085,35 @@
         "IkasOrderGiftPackageLine"
       ]
     },
+    {
+      "name": "getIkasOrderGiftCardTotalPrice",
+      "displayName": "getGiftCardTotalPrice",
+      "signature": "function getIkasOrderGiftCardTotalPrice(order: IkasOrder): number",
+      "description": "Returns the total amount covered by the gift cards (and store credits) applied to the order or cart.\n\nThis is a derived value, the API does not return it: it sums `amount` over `order.giftCardLines`.\nSubtract it from `order.totalFinalPrice` to get the amount still due.",
+      "params": [
+        {
+          "name": "order",
+          "description": "- The IkasOrder or IkasCart holding the gift card lines"
+        }
+      ],
+      "returns": "The summed gift card amount, or 0 when no gift card is applied",
+      "returnType": "number",
+      "example": "```typescript\nimport { getIkasOrderGiftCardTotalPrice } from \"@ikas/bp-storefront\";\n\nconst giftCardTotal = getIkasOrderGiftCardTotalPrice(cart);\nconst remainingPrice = cart.totalFinalPrice - giftCardTotal;\n```",
+      "categories": [
+        "Order",
+        "Cart"
+      ],
+      "related": [
+        "removeGiftCardLine",
+        "saveCouponCode"
+      ],
+      "isAsync": false,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasOrderGiftCardTotalPrice",
+        "IkasOrder"
+      ]
+    },
     {
       "name": "getIkasOrderDistinctItemCount",
       "displayName": "getDistinctItemCount",
@@ -13168,6 +13197,37 @@
         "IkasCartOperationResult"
       ]
     },
+    {
+      "name": "removeGiftCardLine",
+      "signature": "async function removeGiftCardLine(cart: IkasCart, giftCardId?: string | null): Promise<IkasCartOperationResult>",
+      "description": "Remove a gift card (or store credit) line from the cart.\n\nGift cards are applied through `saveCouponCode` with the gift card code, and the applied\ncards are listed on `cart.giftCardLines`. Pass the `giftCardId` of the line to remove; when\nomitted, every gift card line is removed from the cart.",
+      "params": [
+        {
+          "name": "cart",
+          "description": "- The cart object"
+        },
+        {
+          "name": "giftCardId",
+          "description": "- The gift card to remove, or null/undefined to remove all of them"
+        }
+      ],
+      "returns": "Result with success flag",
+      "returnType": "Promise<IkasCartOperationResult>",
+      "example": "```typescript\nimport { cartStore, removeGiftCardLine } from \"@ikas/bp-storefront\";\n\nasync function handleRemoveGiftCard(giftCardId: string) {\n  if (!cartStore.cart) return;\n\n  const result = await removeGiftCardLine(cartStore.cart, giftCardId);\n  if (result.success) {\n    showToast(\"Gift card removed\");\n  }\n}\n```",
+      "categories": [
+        "Cart"
+      ],
+      "related": [
+        "saveCouponCode",
+        "getIkasOrderGiftCardTotalPrice"
+      ],
+      "isAsync": true,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasCart",
+        "IkasCartOperationResult"
+      ]
+    },
     {
       "name": "getCart",
       "signature": "async function getCart(): Promise<void>",
@@ -14435,17 +14495,17 @@
     {
       "name": "cs_listLoyaltyProgramPointHistory",
       "displayName": "listLoyaltyProgramPointHistory",
-      "signature": "async function cs_listLoyaltyProgramPointHistory(customerStore: IkasCustomerStore, params: ListLoyaltyProgramPointHistoryQueryParams): Promise<IkasLoyaltyProgramPointHistoryPaginationResponse | undefined>",
+      "signature": "async function cs_listLoyaltyProgramPointHistory(customerStore: IkasCustomerStore, params: ListLoyaltyProgramPointHistoryQueryParams): Promise<IkasLoyaltyProgramPointHistory[] | undefined>",
       "description": "",
       "params": [],
-      "returnType": "Promise<IkasLoyaltyProgramPointHistoryPaginationResponse | undefined>",
+      "returnType": "Promise<IkasLoyaltyProgramPointHistory[] | undefined>",
       "categories": [],
       "related": [],
       "isAsync": true,
       "isClass": false,
       "parameterTypes": [
         "IkasCustomerStore",
-        "IkasLoyaltyProgramPointHistoryPaginationResponse"
+        "IkasLoyaltyProgramPointHistory"
       ]
     },
     {

package/data/storefront-types.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-24T11:36:32.988Z",
+  "generatedAt": "2026-09-01T07:21:40.992Z",
   "types": [
     {
       "name": "TextElementTagTypes",
@@ -2467,6 +2467,7 @@
         "findExistingCartItemWithProduct",
         "saveCouponCode",
         "removeCouponCode",
+        "removeGiftCardLine",
         "setCart"
       ]
     },
@@ -5370,16 +5371,6 @@
           "type": "number",
           "optional": false
         },
-        {
-          "name": "baseAmount",
-          "type": "number | null",
-          "optional": false
-        },
-        {
-          "name": "baseQuantity",
-          "type": "number | null",
-          "optional": false
-        },
         {
           "name": "createdAt",
           "type": "any | null",
@@ -5430,16 +5421,6 @@
           "type": "string | null",
           "optional": false
         },
-        {
-          "name": "refundTransactionId",
-          "type": "string | null",
-          "optional": false
-        },
-        {
-          "name": "retroactiveCalculationId",
-          "type": "string | null",
-          "optional": false
-        },
         {
           "name": "type",
           "type": "LoyaltyProgramPointHistoryTypeEnum",
@@ -5451,39 +5432,6 @@
           "optional": false
         }
       ],
-      "filePath": "loyalty-program/point-history/index.ts"
-    },
-    {
-      "name": "IkasLoyaltyProgramPointHistoryPaginationResponse",
-      "kind": "type",
-      "domain": "loyalty-program",
-      "properties": [
-        {
-          "name": "count",
-          "type": "number",
-          "optional": false
-        },
-        {
-          "name": "data",
-          "type": "IkasLoyaltyProgramPointHistory[]",
-          "optional": false
-        },
-        {
-          "name": "hasNext",
-          "type": "boolean",
-          "optional": false
-        },
-        {
-          "name": "limit",
-          "type": "number",
-          "optional": false
-        },
-        {
-          "name": "page",
-          "type": "number",
-          "optional": false
-        }
-      ],
       "filePath": "loyalty-program/point-history/index.ts",
       "relatedFunctions": [
         "apiListLoyaltyProgramPointHistory",
@@ -6373,6 +6321,77 @@
         "hasIkasOrderCustomer"
       ]
     },
+    {
+      "name": "IkasOrderGiftCardLine",
+      "kind": "type",
+      "domain": "order",
+      "properties": [
+        {
+          "name": "id",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "amount",
+          "type": "number",
+          "optional": false
+        },
+        {
+          "name": "code",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "giftCardId",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "type",
+          "type": "IkasGiftCardType | null",
+          "optional": false
+        },
+        {
+          "name": "appliedTransactions",
+          "type": "IkasOrderGiftCardLineAppliedTransaction[]",
+          "optional": false
+        }
+      ],
+      "filePath": "order/gift-card-line/index.ts"
+    },
+    {
+      "name": "IkasOrderGiftCardLineAppliedTransaction",
+      "kind": "type",
+      "domain": "order",
+      "properties": [
+        {
+          "name": "id",
+          "type": "string",
+          "optional": false
+        },
+        {
+          "name": "amount",
+          "type": "number",
+          "optional": false
+        },
+        {
+          "name": "type",
+          "type": "IkasTransactionType",
+          "optional": false
+        }
+      ],
+      "filePath": "order/gift-card-line/index.ts"
+    },
+    {
+      "name": "IkasGiftCardType",
+      "kind": "type",
+      "domain": "order",
+      "unionValues": [
+        "GIFT_CARD",
+        "STORE_CREDIT"
+      ],
+      "filePath": "order/gift-card-line/index.ts"
+    },
     {
       "name": "IkasOrderGiftPackageLine",
       "kind": "type",
@@ -6464,6 +6483,11 @@
           "type": "string | null",
           "optional": false
         },
+        {
+          "name": "giftCardLines",
+          "type": "IkasOrderGiftCardLine[] | null",
+          "optional": false
+        },
         {
           "name": "giftPackageLines",
           "type": "IkasOrderGiftPackageLine[] | null",
@@ -6577,6 +6601,7 @@
       ],
       "filePath": "order/index.ts",
       "relatedFunctions": [
+        "getIkasOrderGiftCardTotalPrice",
         "getIkasOrderDistinctItemCount",
         "getIkasOrderTotalItemCount",
         "getIkasOrderDisplayedPackages",

package/dist/index.js

@@ -1969,7 +1969,7 @@ const server = new McpServer({
     version: "0.1.0",
 }, {
     instructions: "Examples and section templates from this server are API reference only — reuse imports, function calls, and data-access patterns; create your own JSX structure, CSS class names, and visual design.\n\n" +
-        "Live-editor actions (require `ikas theme dev` running with the editor connected): `list_editor_pages` → page ids; `list_imported_sections` → imported component ids; `import_section` → import a built component; `add_section_to_page` → place one section (`add_sections_to_page` places MANY at once and can set their props in the same call — fastest way to build a page); `list_page_sections` → the sections placed on a page (LEAN roster: per-placement `elementId`, `componentId`, `propCount`, which props are filled — NO schema/values, so it never truncates); `move_page_section` → reorder a section already placed on a page (by `direction` up/down or an absolute `to_index`) — the only way to change section order, since the editor UI offers it solely as a drag; `get_component_props` → a component's prop blueprint (types, ENUM valid `options`, COMPONENT_LIST `allowedComponentIds`) for any section OR child id; `get_section_values` → one section's current prop values (for read-modify-write); `get_page_by_type` → a theme page id by pageType (e.g. CATEGORY), to build PAGE links to entities (`create_page` adds that page if it does not exist yet, so you never guess a slug); `update_section_prop` → change a single prop value of a placed section (`update_page_sections` fills MANY sections/props of a page in ONE call — strongly prefer it to cut round-trips when filling content); `upload_image` → upload one image (file or URL) and get an image id (`upload_images` uploads many in one call — prefer it for several); `search_products` / `list_categories` / `list_brands` / `list_blogs` / `list_blog_categories` → find real entity ids for PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY prop values; `publish_theme` → publish the theme LIVE and get back the preview URL to review (guarded — needs `confirm:true`, and `confirm_production:true` for the main theme; only call it when the user explicitly asks to publish). For the full end-to-end process (placing a section and filling its content, with per-prop value shapes and COMPONENT_LIST rules), call `get_editor_workflow` first.\n\n" +
+        "Live-editor actions (require `ikas theme dev` running with the editor connected): `list_editor_pages` → page ids; `list_imported_sections` → imported component ids; `import_section` → import a built component; `add_section_to_page` → place one section (`add_sections_to_page` places MANY at once and can set their props in the same call — fastest way to build a page); `list_page_sections` → the sections placed on a page (LEAN roster: per-placement `elementId`, `componentId`, `propCount`, which props are filled — NO schema/values, so it never truncates); `move_page_section` → reorder a section already placed on a page (by `direction` up/down or an absolute `to_index`) — the only way to change section order, since the editor UI offers it solely as a drag; `get_component_props` → a component's prop blueprint (types, ENUM valid `options`, COMPONENT_LIST `allowedComponentIds`) for any section OR child id; `get_section_values` → one section's current prop values (for read-modify-write); `get_page_by_type` → a theme page id by pageType (e.g. CATEGORY), to build PAGE links to entities (`create_page` adds that page if it does not exist yet, so you never guess a slug); `update_section_prop` → change a single prop value of a placed section (`update_page_sections` fills MANY sections/props of a page in ONE call — strongly prefer it to cut round-trips when filling content); `upload_image` → upload one image (file or URL) and get an image id (`upload_images` uploads many in one call — prefer it for several); `search_products` / `list_categories` / `list_brands` / `list_blogs` / `list_blog_categories` → find real entity ids for PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY prop values; `publish_theme` → publish the theme LIVE and get back the preview URL to review (guarded — needs `confirm:true`, and `confirm_production:true` for the main theme; only call it when the user explicitly asks to publish); `list_builtin_pages` / `update_builtin_page_prop` / `enable_builtin_pages` → the ikas-rendered built-in account/membership pages (login, register, my account, orders, …) — these are NOT sections and the section tools cannot edit them; use these three to enable the groups, read their prop schemas, and brand/localize them. When the user asks to BUILD a login/register/password/my-account/orders/addresses page, FIRST offer these ready-made built-in pages instead of assembling one from sections — they are fully functional out of the box and brandable; build a custom section page only if the user prefers a custom design. Offer, don't flip: `enable_builtin_pages` creates/removes pages, so get the user's explicit OK before calling it. For the full end-to-end process (placing a section and filling its content, with per-prop value shapes and COMPONENT_LIST rules), call `get_editor_workflow` first.\n\n" +
         "To CHANGE/EDIT a prop value (text, color, boolean, number, etc.) of a section that is already on a page, this IS supported: call `list_page_sections(page_id)` to get the placement `elementId` and the prop names/ids, then `update_section_prop(page_id, element_id, prop_name|prop_id, value)`. Do not assume prop editing is unavailable.\n\n" +
         "TWO DISTINCT JOBS — do not confuse them, and do not jump to writing code for the second one:\n" +
         "(A) DEFINING props / authoring a component = changing which props a component HAS. This edits the component source/config (types.ts via `ikas-component config add-prop`/`add-component`, JSX in index.tsx, etc.) and requires a rebuild. Use this ONLY when the needed prop does not exist yet, or the user explicitly asks to build/modify the component's code or prop schema.\n" +
@@ -4308,6 +4308,129 @@ server.tool("create_page", 'Create a theme page of a given pageType in the conne
     return callEditorAction(project_root, args);
 });
 // Tool: publish_theme
+// Tool: list_builtin_pages
+server.tool("list_builtin_pages", "List the ikas-rendered BUILT-IN account/membership pages (login, register, forgot/recover password, my account, orders, addresses, favorites, email verification) and how to customize them. These pages are rendered by ikas's own components, NOT by sections: a built-in page carries no sections, so `list_page_sections` shows nothing and `update_section_prop` cannot touch it — `update_builtin_page_prop` is the write tool. Without arguments returns the roster: per-group (`membership` = login/register/password flows, `account` = my-account pages) enabled state, every built-in page type with its theme pageId and which props the merchant already edited, plus the SHARED SCOPES (logo, palette, account-menu labels — values edited once that reach every page in the scope's group). Pass `page_type` (e.g. LOGIN) or `scope_id` for that page's/scope's FULL prop schema (types, defaults, ENUM options, translations) and current values (`values` = what the page renders with; `ownValues` = what this page's own layer stores). Pass `sf_routing_id` to read what one storefront routing/locale sees — the no-argument call lists the store's routings (id, path, locale; `isDefault: true` = the base, needing no sf_routing_id). Typical branding flow: read the theme's palette via `list_theme_globals`, then set the shared scope's colors as `{ \"patternValueId\": \"<global color id>\" }` bindings so the pages follow the theme's colors live.", {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .optional()
+        .describe("One built-in page's full prop schema and values (e.g. LOGIN, ACCOUNT, ORDERS)."),
+    scope_id: z
+        .string()
+        .optional()
+        .describe("One shared scope's full prop schema and values (scope ids come from the no-argument call)."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("Read the values one storefront routing/locale sees (default: the base routing)."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, scope_id, sf_routing_id, port }) => {
+    const args = [
+        "list-builtin-pages",
+        ...(page_type ? ["--page-type", page_type] : []),
+        ...(scope_id ? ["--scope-id", scope_id] : []),
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: update_builtin_page_prop
+server.tool("update_builtin_page_prop", 'Set, bind, or clear ONE prop of an ikas-rendered built-in account/membership page — the write half of `list_builtin_pages`, and the ONLY way to customize those pages (they have no sections, so `update_section_prop` cannot reach them). Target a page\'s own prop with `page_type` (e.g. LOGIN) or a SHARED prop — logo, palette, menu labels, edited once for every page in the scope\'s group — with `scope_id`. Identify the prop by `prop_id` or `prop_name` from `list_builtin_pages`. VALUES ARE RAW (no `{ "value": ... }` envelope — an envelope is tolerated and unwrapped): TEXT = the plain string; BOOLEAN = true/false; NUMBER = a number; ENUM = one of the prop\'s `enumOptions` VALUES; COLOR = "#rrggbb" OR `{ "patternValueId": "<global color id>" }` to follow a theme color live (ids from `list_theme_globals` → colors[].id — prefer the binding when branding, so a palette change updates the pages); IMAGE = `{ "id": "<image id>" }` (id from `upload_image`); LINK/LIST_OF_LINK = copy the shape from `list_builtin_pages` values. `bind_global` (a global\'s `name` from `list_theme_globals`) makes the prop follow a Theme Setting instead of holding a value; `clear: true` deletes the stored value so the prop falls back to the shared value or the manifest default. `sf_routing_id` writes one routing\'s override — use it to localize texts per language; without it you write the base value every routing inherits. Writes are undoable in the editor.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    page_type: z
+        .string()
+        .optional()
+        .describe("Built-in page type whose OWN prop to write (e.g. LOGIN). Pass this or scope_id."),
+    scope_id: z
+        .string()
+        .optional()
+        .describe("Shared scope whose prop to write — reaches every built-in page in its group."),
+    prop_id: z
+        .string()
+        .optional()
+        .describe("Prop id from list_builtin_pages. Provide this or prop_name."),
+    prop_name: z
+        .string()
+        .optional()
+        .describe("Prop name (alternative to prop_id)."),
+    value: z
+        .any()
+        .optional()
+        .describe("The RAW value (see the tool description for per-type shapes). Omit when using bind_global or clear."),
+    bind_global: z
+        .string()
+        .optional()
+        .describe("Bind the prop to a global variable (Theme Setting) — pass the global's `name` from list_theme_globals."),
+    clear: z
+        .boolean()
+        .optional()
+        .describe("true deletes the stored value; the prop falls back to the shared value or the manifest default."),
+    sf_routing_id: z
+        .string()
+        .optional()
+        .describe("Write one storefront routing's override (localization). Omit to write the base value."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, page_type, scope_id, prop_id, prop_name, value, bind_global, clear, sf_routing_id, port, }) => {
+    const args = [
+        "update-builtin-page-prop",
+        ...(page_type ? ["--page-type", page_type] : []),
+        ...(scope_id ? ["--scope-id", scope_id] : []),
+        ...(prop_id ? ["--prop-id", prop_id] : []),
+        ...(prop_name ? ["--prop-name", prop_name] : []),
+        ...(bind_global
+            ? ["--bind-global", bind_global]
+            : clear
+                ? ["--clear"]
+                : value !== undefined
+                    ? [
+                        "--value",
+                        // ALWAYS JSON-encode: the CLI JSON.parses --value (raw-string fallback), so a
+                        // verbatim TEXT string that happens to parse — "2024", "true", "null" — would
+                        // arrive as a number/boolean/clear. Encoded, it round-trips as the string it is.
+                        JSON.stringify(value),
+                    ]
+                    : []),
+        ...(sf_routing_id ? ["--sf-routing-id", sf_routing_id] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: enable_builtin_pages
+server.tool("enable_builtin_pages", 'Turn one GROUP of ikas-rendered built-in pages on or off: "membership" (login, register, forgot/recover password, email verification) or "account" (my account, orders, order detail, addresses, favorites). Enabling records the choice and creates any page of the group the theme does not have yet — each born rendered by ikas\'s built-in component; customize them right after with `update_builtin_page_prop`. Disabling removes ONLY the untouched pages the toggle itself created — a page the merchant built on is never deleted. The flip is one undo step in the editor. Check the current state first with `list_builtin_pages`.', {
+    project_root: z
+        .string()
+        .describe("Absolute path to the code-component project."),
+    group: z
+        .enum(["membership", "account"])
+        .describe('"membership" = login/register/password flows; "account" = my-account pages.'),
+    enabled: z
+        .boolean()
+        .describe("true to enable the group, false to disable it."),
+    port: z
+        .number()
+        .optional()
+        .describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, group, enabled, port }) => {
+    const args = [
+        "enable-builtin-pages",
+        "--group",
+        group,
+        "--enabled",
+        String(enabled),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
 server.tool("publish_theme", "Publish the current theme LIVE — the same action as the editor's Publish button (uploads the whole project to the storefront). This is REAL and customer-facing: the published site changes. SAFETY: it publishes nothing unless `confirm: true` is passed; if you omit it you get a dry-run with the `previewUrl` and a warning describing the impact. The MAIN/production theme additionally requires `confirm_production: true` (its URL is the live customer-facing domain). Use this when the user explicitly asks to publish/go live — do NOT publish on your own initiative. On success returns `{ published: true, previewUrl, isMainTheme }`; open `previewUrl` to review the result. Requires `ikas theme dev` running with the editor connected.", {
     project_root: z
         .string()