@ikas/code-components-mcp 1.4.0-beta.17 → 1.4.0-beta.171

package/data/storefront-api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-06-03T18:42:32.196Z",
+  "generatedAt": "2026-08-19T15:11:04.648Z",
   "functions": [
     {
       "name": "apiListProductBrand",
@@ -167,7 +167,7 @@
       "name": "getAttributeDetailValues",
       "displayName": "getValues",
       "signature": "function getAttributeDetailValues(attributeDetail: IkasProductAttributeDetail): IkasProductAttributeValue[]",
-      "description": "Retrieves the attribute values for a product attribute detail, merging variant and product-level attributes.",
+      "description": "Retrieves the attribute values for a product attribute detail, merging variant and product-level attributes.\nThis is how a PRODUCT_ATTRIBUTE code-component prop is consumed: that prop hands you the\nIkasProductAttributeDetail wrapper ({ product, attributePropValue }), never the attribute value itself, so\nreading `prop.value` silently yields nothing — call this function instead.",
       "params": [
         {
           "name": "attributeDetail",
@@ -195,7 +195,7 @@
       "name": "getAttributeListValues",
       "displayName": "getValues",
       "signature": "function getAttributeListValues(list: IkasProductAttributeList): IkasProductAttributeMap[]",
-      "description": "Retrieves grouped attribute values for a product attribute list, combining variant and product-level attributes.",
+      "description": "Retrieves grouped attribute values for a product attribute list, combining variant and product-level attributes.\nThis is how a PRODUCT_ATTRIBUTE_LIST code-component prop is consumed: that prop hands you a single\nIkasProductAttributeList wrapper ({ product, attributeListPropValue }) — never an array — so mapping over the\nprop is a runtime error; call this function and iterate the returned { attribute, values } maps instead.",
       "params": [
         {
           "name": "list",
@@ -2761,16 +2761,16 @@
     {
       "name": "getDefaultSrc",
       "signature": "function getDefaultSrc(image: IkasImage): string",
-      "description": "Returns the default source URL for an image at 1080px resolution.",
+      "description": "Returns the default source URL for an image OR video at 1080px resolution.\n\nProduct media items (IkasProductImage) can be videos. ALWAYS check `item.isVideo`\nand render a `<video src={getDefaultSrc(item)}>` instead of an `<img>` when it is true.\nNever assume every media item is an image.",
       "params": [
         {
           "name": "image",
           "description": "- The image object to generate the default source URL for."
         }
       ],
-      "returns": "The CDN URL string for the image at 1080px size.",
+      "returns": "The CDN URL string for the image or video at 1080px size.",
       "returnType": "string",
-      "example": "```typescript\nimport { getDefaultSrc } from \"@ikas/bp-storefront\";\n\nconst src = getDefaultSrc(image);\nconsole.log(src); // \"https://cdn.example.com/images/.../1080/image.webp\"\n```",
+      "example": "```typescript\nimport { getDefaultSrc, createMediaSrcset } from \"@ikas/bp-storefront\";\n\n// Product images can be videos — ALWAYS branch on isVideo when mapping media:\n{product.images.map((item, i) =>\n  item.isVideo ? (\n    <video key={i} src={getDefaultSrc(item)} muted playsInline preload=\"metadata\">\n      <track kind=\"captions\" />\n    </video>\n  ) : (\n    <img key={i} src={getDefaultSrc(item)} srcSet={createMediaSrcset(item)} alt={`Product ${i + 1}`} />\n  )\n)}\n```",
       "categories": [
         "Image"
       ],
@@ -2788,16 +2788,16 @@
     {
       "name": "getThumbnailSrc",
       "signature": "function getThumbnailSrc(image: IkasImage): string",
-      "description": "Returns the thumbnail source URL for an image at 180px resolution.",
+      "description": "Returns the thumbnail source URL for an IMAGE at 180px resolution.\n\nVIDEOS HAVE NO 180px THUMBNAIL and no poster URL. When `image.isVideo === true` the size is\nIGNORED and this returns the same full-size .mp4 as `getDefaultSrc(image)` — so using it in a\nthumbnail-sized box (swatch, cart line, order line) downloads the whole video instead of a\n180px webp. Nothing looks broken, which makes it a silent performance regression.\n\nBranch on `item.isVideo` first and only pass images here. For the video branch in a small,\nstatic context render `<video src={getDefaultSrc(item)} preload=\"metadata\" muted playsInline>`\nwith no `autoPlay`: the browser fetches only the first frame and holds it as a stand-in poster.",
       "params": [
         {
           "name": "image",
-          "description": "- The image object to generate the thumbnail source URL for."
+          "description": "- The image object to generate the thumbnail source URL for. Videos ignore the size."
         }
       ],
-      "returns": "The CDN URL string for the image at 180px size.",
+      "returns": "The CDN URL string: a 180px image, or — for `isVideo` items — the original .mp4.",
       "returnType": "string",
-      "example": "```typescript\nimport { getThumbnailSrc } from \"@ikas/bp-storefront\";\n\nconst thumbnailSrc = getThumbnailSrc(image);\nconsole.log(thumbnailSrc); // \"https://cdn.example.com/images/.../180/image.webp\"\n```",
+      "example": "```typescript\nimport { getThumbnailSrc, getDefaultSrc } from \"@ikas/bp-storefront\";\n\n// Thumbnail rail — branch on isVideo per item (no autoPlay: first frame acts as the poster):\n{product.images.map((item, i) =>\n  item.isVideo ? (\n    <video key={i} src={getDefaultSrc(item)} muted playsInline preload=\"metadata\">\n      <track kind=\"captions\" />\n    </video>\n  ) : (\n    <img key={i} src={getThumbnailSrc(item)} sizes=\"112px\" alt={`Thumb ${i + 1}`} />\n  )\n)}\n```",
       "categories": [
         "Image"
       ],
@@ -2815,7 +2815,7 @@
     {
       "name": "getSrc",
       "signature": "function getSrc(image: IkasImage, size: number): string",
-      "description": "Generates the full CDN source URL for an image or video at the specified size, handling both legacy path-based and merchant-scoped ID formats.",
+      "description": "Generates the full CDN source URL for an image or video at the specified size, handling both legacy path-based and merchant-scoped ID formats.\n\nNOTE: For videos (`image.isVideo === true`) the `size` argument is IGNORED — the original .mp4 is always returned.\nSo `getSrc(item, 240)` and `getDefaultSrc(item)` produce the identical URL for a video. PREFER `getDefaultSrc(item)`\nfor video `src` (no size param) — do NOT pass an arbitrary size like `getSrc(item, 240)`, it is misleading.",
       "params": [
         {
           "name": "image",
@@ -2823,12 +2823,12 @@
         },
         {
           "name": "size",
-          "description": "- The desired image width in pixels for the generated URL."
+          "description": "- The desired image width in pixels. Ignored for videos."
         }
       ],
       "returns": "The full CDN URL string for the image or video.",
       "returnType": "string",
-      "example": "```typescript\nimport { getSrc } from \"@ikas/bp-storefront\";\n\nconst src = getSrc(image, 640);\nconsole.log(src); // \"https://cdn.example.com/images/.../640/image.webp\"\n```",
+      "example": "```typescript\nimport { getSrc, getDefaultSrc } from \"@ikas/bp-storefront\";\n\nconst src = getSrc(image, 640);\nconsole.log(src); // \"https://cdn.example.com/images/.../640/image.webp\"\n\n// For a video, use getDefaultSrc (size is ignored anyway):\n<video src={getDefaultSrc(item)} muted playsInline preload=\"metadata\" />\n```",
       "categories": [
         "Image"
       ],
@@ -2846,7 +2846,7 @@
     {
       "name": "createMediaSrcset",
       "signature": "function createMediaSrcset(image?: IkasImage | null): string",
-      "description": "Generates a complete responsive `srcset` string for an image across all standard sizes (180–3840px).",
+      "description": "Generates a complete responsive `srcset` string for an image across all standard sizes (180–3840px).\n\nsrcset applies to `<img>` only — video media (`item.isVideo === true`) has no srcset\nand must be rendered with `<video src={getDefaultSrc(item)}>`. When mapping product\nimages, branch on `item.isVideo` first, then only use createMediaSrcset on the image branch.",
       "params": [
         {
           "name": "image",
@@ -2855,7 +2855,7 @@
       ],
       "returns": "A srcset string like `\"url 180w, url 360w, ...\"`, or an empty string if no image is provided.",
       "returnType": "string",
-      "example": "```typescript\nimport { createMediaSrcset, getDefaultSrc } from \"@ikas/bp-storefront\";\n\n<img\n  src={getDefaultSrc(image)}\n  srcSet={createMediaSrcset(image)}\n  sizes=\"(max-width: 768px) 100vw, 50vw\"\n  alt=\"Product\"\n/>\n```",
+      "example": "```typescript\nimport { createMediaSrcset, getDefaultSrc } from \"@ikas/bp-storefront\";\n\n// Product images can be videos — ALWAYS branch on isVideo when mapping media:\n{product.images.map((item, i) =>\n  item.isVideo ? (\n    <video key={i} src={getDefaultSrc(item)} muted playsInline preload=\"metadata\">\n      <track kind=\"captions\" />\n    </video>\n  ) : (\n    <img\n      key={i}\n      src={getDefaultSrc(item)}\n      srcSet={createMediaSrcset(item)}\n      sizes=\"(max-width: 768px) 100vw, 50vw\"\n      alt={`Product ${i + 1}`}\n    />\n  )\n)}\n```",
       "categories": [
         "Image"
       ],
@@ -4628,7 +4628,7 @@
       "name": "getIkasProductAttrributeProductIds",
       "displayName": "getProductIds",
       "signature": "function getIkasProductAttrributeProductIds(value: IkasProductAttributeValue): string[]",
-      "description": "Extracts and returns the product IDs from a PRODUCT-type attribute value's JSON string.",
+      "description": "Extracts and returns the product IDs from a PRODUCT-type attribute value's JSON string.\nNOTE: the export name really is misspelled — \"Attrribute\" with a double r. It is kept as-is because\nrenaming a published export would break every theme that imports it, so import it VERBATIM; the\ncorrectly spelled `getIkasProductAttributeProductIds` does not exist and will not compile. This is\nnot a documentation typo to report or \"fix\". In the blueprint editor the display alias is\n`getProductIds`, which hides the misspelling; only direct TypeScript imports see it.",
       "params": [
         {
           "name": "value",
@@ -7310,16 +7310,16 @@
       "name": "getProductVariantMainImage",
       "displayName": "getMainImage",
       "signature": "function getProductVariantMainImage(variant: IkasProductVariant): IkasProductImage | undefined",
-      "description": "Get the main/primary image for a product variant.",
+      "description": "Get the main/primary media item for a product variant.\n\nThe returned IkasProductImage may be a video (`isVideo === true`) — branch on it\nand render `<video>` instead of `<img>`.",
       "params": [
         {
           "name": "variant",
           "description": "- The product variant"
         }
       ],
-      "returns": "The first IkasProductImage of the variant, or undefined if no images. Access `.image` to get the IkasImage for CDN helpers.",
+      "returns": "The first IkasProductImage of the variant, or undefined if no images. Check `.isVideo` to decide between `<video>` and `<img>`, and access `.image` to get the IkasImage for CDN helpers.",
       "returnType": "IkasProductImage | undefined",
-      "example": "```typescript\nimport { getProductVariantMainImage, getSelectedProductVariant, getDefaultSrc } from \"@ikas/bp-storefront\";\nimport { IkasProduct } from \"@ikas/bp-storefront\";\n\nfunction ProductImage({ product }: { product: IkasProduct }) {\n  const variant = getSelectedProductVariant(product);\n  const productImage = getProductVariantMainImage(variant);\n  const image = productImage?.image;\n\n  if (!image) {\n    return <div className=\"no-image\">No image available</div>;\n  }\n\n  return <img src={getDefaultSrc(image)} alt={product.name} />;\n}\n```",
+      "example": "```typescript\nimport { getProductVariantMainImage, getSelectedProductVariant, getDefaultSrc, createMediaSrcset } from \"@ikas/bp-storefront\";\nimport { IkasProduct } from \"@ikas/bp-storefront\";\n\nfunction ProductImage({ product }: { product: IkasProduct }) {\n  const variant = getSelectedProductVariant(product);\n  const productImage = getProductVariantMainImage(variant);\n  const image = productImage?.image;\n\n  if (!image) {\n    return <div className=\"no-image\">No image available</div>;\n  }\n\n  // Media can be a video — branch on isVideo:\n  return productImage.isVideo ? (\n    <video src={getDefaultSrc(image)} muted playsInline loop>\n      <track kind=\"captions\" />\n    </video>\n  ) : (\n    <img src={getDefaultSrc(image)} srcSet={createMediaSrcset(image)} alt={product.name} />\n  );\n}\n```",
       "categories": [
         "ProductDetail",
         "ProductList"
@@ -7597,14 +7597,14 @@
       "name": "getProductVariantAppliedCampaignAmount",
       "displayName": "getAppliedCampaignAmount",
       "signature": "function getProductVariantAppliedCampaignAmount(variant: IkasProductVariant): IkasAppliedCampaignAmount | null",
-      "description": "Get the applied campaign discount amount details for a product variant, including type and formatted value.",
+      "description": "Get the applied campaign discount amount details for a product variant, including type and formatted value.\n\nHow the discount value is interpreted depends on `campaign.type`:\n- `\"FIXED_AMOUNT\"` → the value is an absolute money amount, returned in `formattedPrice` (e.g. \"$10.00\"); `discountPercentage` stays null.\n- `\"RATIO\"` → the value is a percentage, returned in `discountPercentage` (e.g. \"10\" for 10% off); `formattedPrice` stays null.\n\nBoth fixed and tiered campaigns are supported. For a tiered-discount campaign\n(`campaign.fixedDiscount` is null and the discount lives in `campaign.tieredDiscount.rules`),\nthe first tier's amount (`campaign.tieredDiscount.rules[0].amount`) is used, matching the storefront runtime.",
       "params": [
         {
           "name": "variant",
           "description": "- The product variant to check for applied campaigns"
         }
       ],
-      "returns": "An object with campaign type, formatted price, and discount percentage, or null if no campaign is applied",
+      "returns": "An object `{ type, formattedPrice, discountPercentage }` — `formattedPrice` is set for FIXED_AMOUNT campaigns, `discountPercentage` for RATIO campaigns (fixed and tiered alike); the other field stays null. Returns null if no campaign is applied.",
       "returnType": "IkasAppliedCampaignAmount | null",
       "example": "```typescript\nimport { getProductVariantAppliedCampaignAmount, getSelectedProductVariant } from \"@ikas/bp-storefront\";\nimport { IkasProduct } from \"@ikas/bp-storefront\";\n\nfunction CampaignInfo({ product }: { product: IkasProduct }) {\n  const variant = getSelectedProductVariant(product);\n  const campaignAmount = getProductVariantAppliedCampaignAmount(variant);\n\n  if (!campaignAmount) return null;\n\n  return (\n    <div>\n      {campaignAmount.type === \"RATIO\"\n        ? `${campaignAmount.discountPercentage}% off`\n        : `${campaignAmount.formattedPrice} off`}\n    </div>\n  );\n}\n```",
       "categories": [
@@ -7999,6 +7999,36 @@
         "IkasProductVariant"
       ]
     },
+    {
+      "name": "getProductVariantTieredDiscountProducts",
+      "displayName": "getTieredDiscountProducts",
+      "signature": "function getProductVariantTieredDiscountProducts(variant: IkasProductVariant): IkasTieredDiscountProduct[]",
+      "description": "Get the tiered-discount breakdown for a product variant, one entry per discount tier.\n\nA tiered discount defines multiple quantity tiers (`campaign.tieredDiscount.rules`), each with its own\namount and quantity range. This resolves every tier against the variant's price and returns the\nper-tier sell/final prices (both raw numbers and formatted strings), matching the storefront runtime.\nThe raw rules are `IkasProductTieredDiscountRule` (ranges may be null); this function returns the\nresolved `IkasTieredDiscountProduct` with normalized `{ min, max }` — use the resolved shape, not the raw rule.\n\n`sellPrice`/`finalPrice` (and their `formatted*` variants) are PER UNIT; the `*WithQuantity` fields are the\ntier total for buying the minimum quantity. A `\"FIXED_AMOUNT\"` discount is applied only to that total, so\nper-unit `finalPrice` equals `sellPrice` and the saving shows only in `finalPriceWithQuantity`.\n\nThe discount `amount` is interpreted by `campaign.type`: `\"RATIO\"` treats it as a percentage,\n`\"FIXED_AMOUNT\"` as an absolute money amount subtracted from the tier total. `amount`/`type` are\ninformational — the discount is already applied in the resolved `*Price` fields, so prefer those over\nrecomputing it yourself.\n\n`lineItemQuantityRange.min`/`max` are normalized numbers where `0` means \"unbounded\". In particular\n`max === 0` marks an open-ended top tier (e.g. \"6+\" with no upper limit) — render it as \"min+\" rather\nthan \"min–max\", and never treat `max` as a real quantity when it is `0`.\n\nEach tier's `salesChannelIds` lists the channels it targets (empty/null = all channels). Filter tiers\nagainst `IkasStorefrontConfig.salesChannelId` so only those valid for the current storefront are shown.\n\nReturns an empty array when the variant has no tiered-discount campaign, when a\n`PRODUCT_AND_VARIANT` filter excludes this variant, or when no tier defines a quantity range.",
+      "params": [
+        {
+          "name": "variant",
+          "description": "- The product variant to resolve tiered discounts for"
+        }
+      ],
+      "returns": "An array of tier objects (`amount`, `lineItemQuantityRange`, `type`, sell/final prices with their formatted variants, `salesChannelIds`), or an empty array if no tiered discount applies",
+      "returnType": "IkasTieredDiscountProduct[]",
+      "example": "```typescript\nimport {\n  getProductVariantTieredDiscountProducts,\n  getSelectedProductVariant,\n  IkasStorefrontConfig,\n} from \"@ikas/bp-storefront\";\nimport { IkasProduct } from \"@ikas/bp-storefront\";\n\nfunction TieredDiscountTable({ product }: { product: IkasProduct }) {\n  const variant = getSelectedProductVariant(product);\n  const tiers = getProductVariantTieredDiscountProducts(variant);\n  const salesChannelId = IkasStorefrontConfig.salesChannelId;\n\n  if (!tiers.length) return null;\n\n  return (\n    <ul>\n      {tiers.map((tier, i) => {\n        // A tier applies when it targets no channels or includes the current one\n        const scoped =\n          !tier.salesChannelIds?.length ||\n          (!!salesChannelId && tier.salesChannelIds.includes(salesChannelId));\n        if (!scoped) return null;\n\n        return (\n          <li key={i}>\n            Buy {tier.lineItemQuantityRange.min}+ → {tier.formattedFinalPriceWithQuantity}{\" \"}\n            <s>{tier.formattedSellPriceWithQuantity}</s>\n          </li>\n        );\n      })}\n    </ul>\n  );\n}\n```",
+      "categories": [
+        "Pricing",
+        "ProductVariant"
+      ],
+      "related": [
+        "getProductVariantAppliedCampaignAmount",
+        "getProductVariantCampaignOffersDiscountPercentage",
+        "getProductVariantFinalPrice"
+      ],
+      "isAsync": false,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasProductVariant",
+        "IkasTieredDiscountProduct"
+      ]
+    },
     {
       "name": "getProductVariantIsBackInStockEnabled",
       "displayName": "isBackInStockEnabled",
@@ -9556,7 +9586,7 @@
       "name": "initAddressForm",
       "displayName": "init",
       "signature": "async function initAddressForm(addressForm: AddressForm, address?: IkasCustomerAddress): Promise<void>",
-      "description": "Initializes an address form with default or existing address values, loads location data, and configures field settings.",
+      "description": "Initializes an address form with default or existing address values, loads location data, and configures field settings.\n\nAlso resolves `addressForm.addressFormat` for the selected country. That is an\n`AddressFormItem[][]` describing which fields the country uses and how they group into rows\n(outer array = rows, inner array = fields sharing a row), and it is the only correct source\nfor laying out an address form -- a hardcoded field list will be wrong for most countries.\nIt is empty until this promise resolves, and `setAddressFormCountry` re-resolves it, so\nrender from it rather than copying it into local state.",
       "params": [
         {
           "name": "addressForm",
@@ -9569,7 +9599,7 @@
       ],
       "returns": "A promise that resolves once the form is fully initialized, including country/state/city lists, field settings, checkout settings, and shipping zones.",
       "returnType": "Promise<void>",
-      "example": "```typescript\nimport { initAddressForm } from \"@ikas/bp-storefront\";\n\n// Initialize an empty address form\nawait initAddressForm(addressForm);\n\n// Initialize with an existing customer address for editing\nawait initAddressForm(addressForm, existingAddress);\n```",
+      "example": "```tsx\nimport { useEffect, useState } from \"preact/hooks\";\nimport {\n  type AddressForm,\n  type AddressFormItem,\n  initAddressForm,\n  setAddressFormFirstName,\n  setAddressFormLastName,\n  setAddressFormIdentityNumber,\n  setAddressFormAddressLine1,\n  setAddressFormAddressLine2,\n  setAddressFormPostalCode,\n  setAddressFormPhone,\n} from \"@ikas/bp-storefront\";\n\n// Initialize an empty address form\nawait initAddressForm(addressForm);\n\n// Initialize with an existing customer address for editing\nawait initAddressForm(addressForm, existingAddress);\n\n// addressFormat is empty until init resolves, so gate the render on it.\nconst [isLoading, setIsLoading] = useState(true);\nuseEffect(() => {\n  initAddressForm(addressForm, address).then(() => setIsLoading(false));\n}, []);\n\n// Every addressFormat key has a matching setter, each taking (addressForm, value).\n// The location keys (country, state, city, district, region) are omitted here: they\n// render as selects fed by addressForm.countryOptions / stateOptions / cityOptions /\n// districtOptions / regionOptions, and must fall back to a text input when the field\n// isFreeText or has no options.\nconst SETTERS: Partial<Record<AddressFormItem, (form: AddressForm, value: string) => void>> = {\n  firstName: setAddressFormFirstName,\n  lastName: setAddressFormLastName,\n  identityNumber: setAddressFormIdentityNumber,\n  addressLine1: setAddressFormAddressLine1,\n  addressLine2: setAddressFormAddressLine2,\n  postalCode: setAddressFormPostalCode,\n  phone: setAddressFormPhone,\n};\n\n// Render the country's own layout: outer array = rows, inner array = fields in that row.\n(addressForm.addressFormat ?? []).map((row) => {\n  // A field the country does not use is absent from the form object entirely.\n  const keys = row.filter((key) => addressForm[key] != null);\n  if (!keys.length) return null;\n\n  return (\n    <div className=\"address-row\" key={keys.join(\"-\")}>\n      {keys.map((key) => {\n        // Each entry is an IkasFormItem: value, label, placeholder, hasError, message.\n        const field = addressForm[key];\n        if (!field) return null; // already guaranteed by the filter above; narrows the type\n        return (\n          <label key={key}>\n            {field.label}\n            <input\n              value={field.value ?? \"\"}\n              placeholder={field.placeholder}\n              onInput={(e) => SETTERS[key]?.(addressForm, e.currentTarget.value)}\n            />\n            {field.hasError && <small>{field.message}</small>}\n          </label>\n        );\n      })}\n    </div>\n  );\n})\n```",
       "categories": [
         "Address",
         "Form",
@@ -12559,11 +12589,27 @@
       "name": "bs_searchProductById",
       "displayName": "searchProductById",
       "signature": "async function bs_searchProductById(baseStore: BaseStore, params: { productId: string }): Promise<{\n  isSuccess: boolean;\n  product: IkasProduct | null;\n}>",
-      "description": "",
-      "params": [],
+      "description": "Fetches a single product by id and returns it as a full `IkasProduct`.\n\nUse this when a lightweight reference (e.g. a cart line's `IkasOrderLineVariant`, which carries\nneither `salesChannels` nor `stock`) needs product-level data: the returned product includes\n`salesChannels` filtered to the active sales channel (with `minQuantityPerCart` /\n`maxQuantityPerCart`) and per-variant `stock` (summed over the sales channel's configured\nstock locations). `selectedVariantValues` is seeded from the first active variant (or the\nfirst variant when none is active). For multiple ids, prefer `bs_searchProductsById` — one\nbatched request.",
+      "params": [
+        {
+          "name": "baseStore",
+          "description": "- The base store instance"
+        },
+        {
+          "name": "params",
+          "description": "- `{ productId }` — id of the product to fetch"
+        }
+      ],
+      "returns": "`{ isSuccess, product }` — `product` is null when not found or on failure",
       "returnType": "Promise<{\n  isSuccess: boolean;\n  product: IkasProduct | null;\n}>",
-      "categories": [],
-      "related": [],
+      "example": "```tsx\nimport { baseStore, bs_searchProductById, IkasStorefrontConfig } from \"@ikas/bp-storefront\";\n\nconst { isSuccess, product } = await bs_searchProductById(baseStore, { productId });\nif (isSuccess && product) {\n  const channel = product.salesChannels?.find(sc => sc.id === IkasStorefrontConfig.salesChannelId);\n  console.log(channel?.maxQuantityPerCart);\n}\n```",
+      "categories": [
+        "Product",
+        "Search"
+      ],
+      "related": [
+        "bs_searchProductsById"
+      ],
       "isAsync": true,
       "isClass": false,
       "parameterTypes": [
@@ -12574,11 +12620,29 @@
       "name": "bs_searchProductsById",
       "displayName": "searchProductsById",
       "signature": "async function bs_searchProductsById(baseStore: BaseStore, params: { productIds: string[] }): Promise<{\n  isSuccess: boolean;\n  products: IkasProduct[] | null;\n}>",
-      "description": "",
-      "params": [],
+      "description": "Batch-fetches products by id in a single request and returns them as full `IkasProduct` objects.\n\nThe go-to function when cart lines (or any lightweight reference) need product-level data they\ndo not carry: `IkasOrderLineVariant` has neither `salesChannels` nor `stock`, while the products\nreturned here include `salesChannels` filtered to the active sales channel (with\n`minQuantityPerCart` / `maxQuantityPerCart`) and per-variant `stock` (summed over the sales\nchannel's configured stock locations). Collect the distinct `productId`s of the lines and\nfetch them in ONE call instead of one request per line. Called with an empty `productIds`,\nit returns `{ isSuccess: true, products: [] }` without a network request.",
+      "params": [
+        {
+          "name": "baseStore",
+          "description": "- The base store instance"
+        },
+        {
+          "name": "params",
+          "description": "- `{ productIds }` — product ids to fetch (deduplicate before calling)"
+        }
+      ],
+      "returns": "`{ isSuccess, products }` — `products` is null on failure",
       "returnType": "Promise<{\n  isSuccess: boolean;\n  products: IkasProduct[] | null;\n}>",
-      "categories": [],
-      "related": [],
+      "example": "```tsx\nimport { baseStore, bs_searchProductsById, cartStore, IkasStorefrontConfig } from \"@ikas/bp-storefront\";\n\n// Enforce per-cart quantity limits on cart lines:\nconst productIds = [\n  ...new Set(\n    (cartStore.cart?.orderLineItems ?? [])\n      .map(item => item.variant.productId)\n      .filter((id): id is string => !!id)\n  ),\n];\nconst { products } = await bs_searchProductsById(baseStore, { productIds });\nconst maxByProductId = new Map<string, number | null>();\nfor (const p of products ?? []) {\n  const channel = p.salesChannels?.find(sc => sc.id === IkasStorefrontConfig.salesChannelId);\n  maxByProductId.set(p.id, channel?.maxQuantityPerCart ?? null);\n}\n```",
+      "categories": [
+        "Product",
+        "Cart",
+        "Search"
+      ],
+      "related": [
+        "bs_searchProductById",
+        "changeItemQuantity"
+      ],
       "isAsync": true,
       "isClass": false,
       "parameterTypes": [
@@ -12616,7 +12680,7 @@
       "name": "addItemToCart",
       "displayName": "addVariantToCart",
       "signature": "async function addItemToCart(variant: IkasProductVariant, product: IkasProduct, initialQuantity: number = 1, options?: AddItemOptions): Promise<IkasCartOperationResult>",
-      "description": "Add a product variant to the shopping cart.",
+      "description": "Add a product variant to the shopping cart.\n\nClamps the quantity to the sales channel's `minQuantityPerCart`/`maxQuantityPerCart` only\nwhen it creates a new cart line. When the variant already has a line in the cart, the add\nis delegated to `changeItemQuantity` (existing quantity + `initialQuantity`) with no\nclient-side clamp — a quantity past `maxQuantityPerCart` is then rejected by the API with\nthe `MAX_QUANTITY_PER_CART_LIMIT_REACHED` code in `result.response.errorCodes`, never as a\n`validationError`. See `changeItemQuantity` for the handling pattern.",
       "params": [
         {
           "name": "variant",
@@ -12692,7 +12756,7 @@
       "name": "changeItemQuantity",
       "displayName": "changeQuantityOnCart",
       "signature": "async function changeItemQuantity(item: IkasOrderLineItem, quantity: number, offers?: IkasProductOffer[], product?: IkasProduct): Promise<IkasCartOperationResult>",
-      "description": "Change the quantity of an item in the cart.\nUse quantity=0 to remove the item.",
+      "description": "Change the quantity of an item in the cart.\nUse quantity=0 to remove the item.\n\nPerforms no client-side clamping or validation: a quantity above the sales channel's\n`maxQuantityPerCart` is rejected by the API with the `MAX_QUANTITY_PER_CART_LIMIT_REACHED`\ncode in `result.response.errorCodes` (never as a `validationError`). Prevent violations in\nthe stepper and treat the error code as the fallback.",
       "params": [
         {
           "name": "item",
@@ -12713,7 +12777,7 @@
       ],
       "returns": "Result with success flag",
       "returnType": "Promise<IkasCartOperationResult>",
-      "example": "```typescript\nimport { cartStore, changeItemQuantity } from \"@ikas/bp-storefront\";\n\n// Increment quantity\nasync function handleIncrement(itemId: string) {\n  const item = cartStore.cart?.orderLineItems.find(i => i.id === itemId);\n  if (item) {\n    const result = await changeItemQuantity(item, item.quantity + 1);\n    if (!result.success) {\n      showToast(\"Failed to update quantity\");\n    }\n  }\n}\n\n// Decrement quantity\nasync function handleDecrement(itemId: string) {\n  const item = cartStore.cart?.orderLineItems.find(i => i.id === itemId);\n  if (item && item.quantity > 1) {\n    await changeItemQuantity(item, item.quantity - 1);\n  }\n}\n```",
+      "example": "```typescript\nimport { APIErrorCode, cartStore, changeItemQuantity } from \"@ikas/bp-storefront\";\n\n// Increment quantity\nasync function handleIncrement(itemId: string) {\n  const item = cartStore.cart?.orderLineItems.find(i => i.id === itemId);\n  if (item) {\n    const result = await changeItemQuantity(item, item.quantity + 1);\n    if (!result.success) {\n      const limitHit = result.response?.errorCodes?.includes(\n        APIErrorCode.MAX_QUANTITY_PER_CART_LIMIT_REACHED\n      );\n      showToast(limitHit ? \"Per-cart quantity limit reached\" : \"Failed to update quantity\");\n    }\n  }\n}\n\n// Decrement quantity\nasync function handleDecrement(itemId: string) {\n  const item = cartStore.cart?.orderLineItems.find(i => i.id === itemId);\n  if (item && item.quantity > 1) {\n    await changeItemQuantity(item, item.quantity - 1);\n  }\n}\n```",
       "categories": [
         "Cart"
       ],
@@ -14862,7 +14926,7 @@
     {
       "name": "getEmptyAddressForm",
       "signature": "function getEmptyAddressForm(customerStore: IkasCustomerStore): AddressForm",
-      "description": "Create and return a new, empty address form with validation, wrapped in MobX observability.",
+      "description": "Create and return a new, empty address form with validation, wrapped in MobX observability.\n\nUse this to create an address; use `getIkasCustomerAddressForm(address)` to edit an existing\none. It starts `initAddressForm` internally but does not await it, so await `initAddressForm`\nyourself when you need to know that the country layout (`addressFormat`) and the country/state/\ncity lists are ready to render.",
       "params": [
         {
           "name": "customerStore",
@@ -14871,14 +14935,16 @@
       ],
       "returns": "A new observable address form object with validated fields",
       "returnType": "AddressForm",
-      "example": "```typescript\nimport { customerStore, getEmptyAddressForm, saveCustomer } from \"@ikas/bp-storefront\";\n\nfunction AddAddressPage() {\n  const form = getEmptyAddressForm(customerStore);\n\n  const handleSave = async () => {\n    const customer = { ...customerStore.customer! };\n    customer.addresses = [...(customer.addresses || []), formToAddress(form)];\n    await saveCustomer(customerStore, customer);\n  };\n\n  return (\n    <form>\n      <input\n        value={form.addressLine1.value}\n        onChange={e => form.addressLine1.value = e.target.value}\n      />\n      <button onClick={handleSave}>Save Address</button>\n    </form>\n  );\n}\n```",
+      "example": "```tsx\nimport {\n  customerStore,\n  getEmptyAddressForm,\n  initAddressForm,\n  setAddressFormAddressLine1,\n  submitAddressForm,\n} from \"@ikas/bp-storefront\";\n\n// Create the form once, then await init before rendering the country-driven layout.\nconst [form] = useState(() => getEmptyAddressForm(customerStore));\nconst [isLoading, setIsLoading] = useState(true);\nuseEffect(() => {\n  initAddressForm(form).then(() => setIsLoading(false));\n}, []);\n\n// Always go through the setters. Assigning `form.addressLine1.value` directly skips\n// re-validation and the dependent-field resets the location setters perform.\nsetAddressFormAddressLine1(form, \"123 Main Street\");\n\n// submitAddressForm validates and saves the address onto the customer itself --\n// do not hand-build a customer object and call saveCustomer for this.\nconst ok = await submitAddressForm(form);\n```",
       "categories": [
         "Customer",
         "Address"
       ],
       "related": [
-        "deleteCustomerAddress",
-        "saveCustomer"
+        "initAddressForm",
+        "submitAddressForm",
+        "getIkasCustomerAddressForm",
+        "deleteCustomerAddress"
       ],
       "isAsync": false,
       "isClass": false,
@@ -15116,6 +15182,128 @@
       "isClass": true,
       "className": "Router"
     },
+    {
+      "name": "withRoutePrefix",
+      "signature": "function withRoutePrefix(path: string): string",
+      "description": "Put the visitor's storefront routing in front of a path you wrote yourself.\n\nEntity links (`getProductHref`, `getIkasOrderHref`, …) and LINK props already carry the prefix.\nA literal path in your own markup does not: `href=\"/cart\"` sends a visitor browsing `/en` to the\ndefault language. Wrap it, and a store with no extra routings gets the path back unchanged.\n\nIdempotent — a path that already starts with a supported routing segment is returned as-is.\nAnything that is not a path on this storefront — an absolute URL, `mailto:`, `tel:` — is returned\nuntouched, so a merchant-authored prop can be wrapped without checking it first.",
+      "params": [
+        {
+          "name": "path",
+          "description": "- A path on this storefront, starting with `/`"
+        }
+      ],
+      "returns": "The path under the current routing (e.g. `/cart` → `/en/cart`)",
+      "returnType": "string",
+      "example": "```tsx\nimport { Router, withRoutePrefix } from \"@ikas/bp-storefront\";\n\n// Correct href for crawlers, middle-click and open-in-new-tab...\n<a href={withRoutePrefix(\"/cart\")} onClick={e => {\n  e.preventDefault();\n  Router.navigateToPage(\"CART\"); // ...and this prefixes on its own.\n}}>Cart</a>\n```",
+      "categories": [
+        "Navigation"
+      ],
+      "related": [
+        "navigate",
+        "navigateToPage"
+      ],
+      "isAsync": false,
+      "isClass": false
+    },
+    {
+      "name": "registerThemeSettingValues",
+      "signature": "function registerThemeSettingValues(values: Record<string, any> | null): void",
+      "description": "Register the live global-variable object (`_g_`) so `getThemeSetting`/`getThemeSettings`\nreturn actual runtime values (constants, computed getters, and in-editor edits) instead\nof the serialized design-time defaults. Called by generated code, not by component authors.",
+      "params": [],
+      "returnType": "void",
+      "categories": [],
+      "related": [],
+      "isAsync": false,
+      "isClass": false
+    },
+    {
+      "name": "getThemeSettings",
+      "signature": "function getThemeSettings(): ThemeSetting[]",
+      "description": "All global variables (Theme Settings) defined for the theme.",
+      "params": [],
+      "returnType": "ThemeSetting[]",
+      "categories": [],
+      "related": [],
+      "isAsync": false,
+      "isClass": false
+    },
+    {
+      "name": "getThemeSetting",
+      "signature": "function getThemeSetting(name: string): ThemeSetting | undefined",
+      "description": "A single global variable by its stable key (`variableName`, e.g. `_6Q0KV7VGGM`).\nDiscover keys via  (each item carries a human `displayName`).\nThe returned `value` is the live blueprint value when available, else the default.\nIts shape is discriminated by `type` (see ); note an\nIMAGE setting's value is an image REFERENCE (no `.url`) — resolve with\n`getDefaultSrc`/`getSrc`.",
+      "params": [],
+      "returnType": "ThemeSetting | undefined",
+      "categories": [],
+      "related": [],
+      "isAsync": false,
+      "isClass": false
+    },
+    {
+      "name": "getThemeSettingValue",
+      "signature": "function getThemeSettingValue(name: string): any",
+      "description": "Convenience: the resolved value of a global variable, or `undefined` if not found.",
+      "params": [],
+      "returnType": "any",
+      "categories": [],
+      "related": [],
+      "isAsync": false,
+      "isClass": false
+    },
+    {
+      "name": "getThemeColors",
+      "signature": "function getThemeColors(): RuntimeDesignToken[]",
+      "description": "Theme color tokens. Each carries a resolved value and a `var(--id)` CSS reference.",
+      "params": [],
+      "returnType": "RuntimeDesignToken[]",
+      "categories": [],
+      "related": [],
+      "isAsync": false,
+      "isClass": false
+    },
+    {
+      "name": "getThemeTypography",
+      "signature": "function getThemeTypography(): RuntimeTypographyToken[]",
+      "description": "Theme typography tokens (text styles). Apply `className` or read `resolved` CSS values.",
+      "params": [],
+      "returnType": "RuntimeTypographyToken[]",
+      "categories": [],
+      "related": [],
+      "isAsync": false,
+      "isClass": false
+    },
+    {
+      "name": "getThemeBreakpoints",
+      "signature": "function getThemeBreakpoints(): RuntimeBreakpointToken[]",
+      "description": "Theme responsive breakpoints (`{ id, width }`).",
+      "params": [],
+      "returnType": "RuntimeBreakpointToken[]",
+      "categories": [],
+      "related": [],
+      "isAsync": false,
+      "isClass": false
+    },
+    {
+      "name": "getThemeKeyframes",
+      "signature": "function getThemeKeyframes(): RuntimeKeyframeToken[]",
+      "description": "Theme keyframe/transition animations. Use `ref` as the CSS animation name.",
+      "params": [],
+      "returnType": "RuntimeKeyframeToken[]",
+      "categories": [],
+      "related": [],
+      "isAsync": false,
+      "isClass": false
+    },
+    {
+      "name": "getThemeColorSchemes",
+      "signature": "function getThemeColorSchemes(): RuntimeThemeColorSchemes",
+      "description": "Theme color schemes (palettes). Returns two PARALLEL lists with different jobs:\n- `schemes`: the color SLOTS as `{ id }` only — no colors and no display label live here at\n  runtime. A slot's human name is authoring-only (read it via the CLI/MCP `list-theme-globals`\n  or the editor); at runtime identify a slot solely by its `id`.\n- `values`: the actual palettes. A palette's colors live in its `colorsByScheme`\n  map, keyed by slot id → `{ resolved, cssVar }`.\n\nTo render swatches, iterate `values[].colorsByScheme` (the source of truth for\ncolors), NOT the top-level `schemes` array — `schemes` carries slot ids only, so\niterating it renders empty:\n\n  const { values } = getThemeColorSchemes();\n  values.forEach(palette =>\n    Object.entries(palette.colorsByScheme).forEach(([slotId, { resolved, cssVar }]) => {\n      // slotId → stable slot key, cssVar → live var() ref (prefer this), resolved → hex snapshot\n    })\n  );",
+      "params": [],
+      "returnType": "RuntimeThemeColorSchemes",
+      "categories": [],
+      "related": [],
+      "isAsync": false,
+      "isClass": false
+    },
     {
       "name": "isBrowser",
       "signature": "function isBrowser(yes?: () => void, no?: () => void): void",
@@ -15142,6 +15330,38 @@
         "IkasComponentRendererProps"
       ]
     },
+    {
+      "name": "formatCurrency",
+      "signature": "function formatCurrency(price: number, currencyCode: string, currencySymbol: string | null): string",
+      "description": "Format a free-standing amount with the merchant's currency format settings. Use this for\namounts that are NOT tied to a model (remaining amount to free shipping, gift wrap threshold,\nbulk discount limits, cart limit warnings). For model-bound prices, prefer the\n`get*FormattedPrice` helpers — they call this function internally.\n\nApplies the merchant's `currencyFormats` entry for the given currency code (symbol,\nsymbolPosition, thousandSeparator, decimalSeparator, omitZeroDecimal). Behavior details:\nalways two decimal places, and a space between the symbol and the number. `omitZeroDecimal`\ndrops the fraction only when it is exactly `00`.\n\nDo NOT use `Intl.NumberFormat` for currency — it falls back to the browser locale and\nproduces a format that conflicts with platform-formatted prices on the same screen.",
+      "params": [
+        {
+          "name": "price",
+          "description": "- The amount to format"
+        },
+        {
+          "name": "currencyCode",
+          "description": "- Currency code used to look up the merchant format settings (e.g. \"TRY\", \"USD\")"
+        },
+        {
+          "name": "currencySymbol",
+          "description": "- Fallback symbol used when the merchant has no format entry for the code.\nAlways pass the symbol from the model you took the amount from (e.g. `cart.currencySymbol`) —\npassing `null` can render the amount with no symbol at all."
+        }
+      ],
+      "returns": "The amount formatted with the merchant's currency format (e.g. \"₺ 1,950.00\")",
+      "returnType": "string",
+      "example": "```typescript\nimport { cartStore, formatCurrency } from \"@ikas/bp-storefront\";\n\nfunction FreeShippingBar({ threshold }: { threshold: number }) {\n  const cart = cartStore.cart;\n  if (!cart) return null;\n\n  const remaining = threshold - cart.totalFinalPrice;\n  if (remaining <= 0) return <span>Free shipping unlocked!</span>;\n\n  return <span>Add {formatCurrency(remaining, cart.currencyCode, cart.currencySymbol)} more for free shipping</span>;\n}\n```",
+      "categories": [
+        "Pricing"
+      ],
+      "related": [
+        "getProductVariantFormattedFinalPrice",
+        "getOrderLineItemFormattedFinalPrice",
+        "getIkasOrderFormattedTotalFinalPrice"
+      ],
+      "isAsync": false,
+      "isClass": false
+    },
     {
       "name": "httpRequest",
       "signature": "async function httpRequest(url: string, method: HttpMethod, body?: Record<string, any>, headers?: Record<string, string>): Promise<FetchResponse>",
@@ -15196,6 +15416,55 @@
       "related": [],
       "isAsync": false,
       "isClass": false
+    },
+    {
+      "name": "PayWithIkas",
+      "signature": "function PayWithIkas({ product, quantity = 1, className, style }: PayWithIkasProps): VNode<ClassAttributes<HTMLIFrameElement> & { ref: MutableRef<HTMLIFrameElement | null>; title: string; ... 4 more ...; style: { ...; }; }> | null",
+      "description": "\"Pay with ikas\" (Hızlı Öde) fast-checkout button for the product detail page.\nDrop-in Preact component that renders the pay-with-ikas checkout iframe and\nwires up its whole message protocol, so a theme gets the one-click \"Hızlı Öde\"\nflow without owning any of the plumbing. Use it next to the add-to-cart button\non the product detail page.\n\nThe pay-with-ikas URL is read from `IkasStorefrontConfig.getPayWithIkasUrl()`;\nwhen the merchant has not enabled Pay with ikas the component renders nothing.\nThe add-to-cart-enabled state is tracked reactively via mobx `autorun`, so the\niframe stays in sync as the product's availability changes (e.g. variant\nselection). Clicking \"Hızlı Öde\" creates a temporary cart via\n`createPayWithIkasSession` and redirects to the returned pay URL.",
+      "params": [
+        {
+          "name": "product",
+          "description": "- The product to fast-checkout via Pay with ikas"
+        },
+        {
+          "name": "quantity",
+          "description": "- Quantity to purchase (defaults to 1)"
+        },
+        {
+          "name": "className",
+          "description": "- Optional CSS class applied to the iframe"
+        },
+        {
+          "name": "style",
+          "description": "- Optional inline styles applied to the iframe"
+        }
+      ],
+      "returnType": "VNode<ClassAttributes<HTMLIFrameElement> & { ref: MutableRef<HTMLIFrameElement | null>; title: string; ... 4 more ...; style: { ...; }; }> | null",
+      "example": "```tsx\nimport { PayWithIkas } from \"@ikas/bp-storefront\";\n\n// On the product detail page, alongside the add-to-cart button:\n<PayWithIkas product={product} quantity={quantity} />\n```",
+      "categories": [
+        "ProductDetail",
+        "Checkout"
+      ],
+      "related": [
+        "createPayWithIkasSession",
+        "isAddToCartEnabled"
+      ],
+      "isAsync": false,
+      "isClass": false,
+      "parameterTypes": [
+        "IkasProps"
+      ]
+    },
+    {
+      "name": "normalizeSvg",
+      "signature": "function normalizeSvg(svg: string, options: NormalizeSvgOptions): string",
+      "description": "Isomorphic, DOM-free normalization of a raw SVG markup string for render.\nSafe to call in SSR, browser, and node — pure string transforms only.",
+      "params": [],
+      "returnType": "string",
+      "categories": [],
+      "related": [],
+      "isAsync": false,
+      "isClass": false
     }
   ],
   "codeExamples": []