@ikas/code-components-mcp 1.4.0-beta.165 → 1.4.0-beta.167

package/data/storefront-api.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-18T15:07:09.984Z",
+  "generatedAt": "2026-08-19T12:18:27.436Z",
   "functions": [
     {
       "name": "apiListProductBrand",
@@ -12589,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": [
@@ -12604,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": [

package/data/storefront-types.json

@@ -1,5 +1,5 @@
 {
-  "generatedAt": "2026-08-18T15:07:10.008Z",
+  "generatedAt": "2026-08-19T12:18:27.461Z",
   "types": [
     {
       "name": "TextElementTagTypes",

package/dist/index.js

@@ -1682,6 +1682,44 @@ function suggestClosestNames(input, candidates, opts) {
         .sort((a, b) => a.d - b.d);
     return edits.slice(0, max).map((s) => s.name);
 }
+/**
+ * Formatted ` — matching sections: ...` suffix naming the guide sections that match the query,
+ * so a hit buried mid-guide (e.g. "Quantity Limits" inside cart-patterns) is visible without
+ * opening the full guide. Section bodies are scored on purpose: a query for an identifier that
+ * appears only inside a section (an error code, a prop name) must still surface that section's
+ * heading. Returns "" when the query matches most of the guide's sections — matchScore is
+ * presence-based, so a broad query ("cart" against cart-patterns) ties every section and a
+ * top-3 would just echo document order, hinting nothing.
+ */
+function sectionHint(content, query) {
+    // Line walk instead of a heading-regex split: a `## ` line inside a fenced code block must
+    // not become a pseudo-section (it would surface a heading that doesn't exist in the guide
+    // and swallow the rest of the real section's body).
+    const sections = [];
+    let fenceOpen = false;
+    for (const line of content.split("\n")) {
+        if (/^\s*```/.test(line))
+            fenceOpen = !fenceOpen;
+        const headingMatch = fenceOpen ? null : line.match(/^#{2,4} (.+)/);
+        if (headingMatch)
+            sections.push({ heading: headingMatch[1].trim(), body: "" });
+        else if (sections.length > 0)
+            sections[sections.length - 1].body += line + "\n";
+    }
+    const scored = [];
+    for (const { heading, body } of sections) {
+        // Heading hits weigh double. The floor of 3 drops sections whose only signal is a single
+        // squashed-identifier body match (worth 2) — a literal word hit (3) or any heading match
+        // clears it.
+        const score = matchScore(heading, query) * 2 + matchScore(body, query);
+        if (score >= 3)
+            scored.push({ heading, score });
+    }
+    if (scored.length === 0 || scored.length > sections.length / 2)
+        return "";
+    const top = scored.sort((a, b) => b.score - a.score).slice(0, 3);
+    return ` — matching sections: ${top.map((s) => `"${s.heading}"`).join(", ")}`;
+}
 function searchFunctions(query) {
     const scored = storefrontData.functions
         .map((fn) => {
@@ -1919,7 +1957,7 @@ server.tool("search_docs", "Search across all ikas storefront API docs, framewor
     if (topics.length > 0) {
         parts.push("\n## Matching Framework Topics\n");
         for (const item of topics) {
-            parts.push(`- **${item.topic.title}** (key: \`${item.key}\`) - ${item.topic.description}`);
+            parts.push(`- **${item.topic.title}** (key: \`${item.key}\`) - ${item.topic.description}${sectionHint(item.topic.content, query)}`);
         }
         parts.push("");
         parts.push("Use `get_framework_guide(topic)` to get full content for any topic.");
@@ -1935,7 +1973,7 @@ server.tool("search_docs", "Search across all ikas storefront API docs, framewor
     if (migrationTopics.length > 0) {
         parts.push("\n## Matching Migration Topics\n");
         for (const item of migrationTopics) {
-            parts.push(`- [migration] **${item.topic.title}** (key: \`${item.key}\`) - ${item.topic.description}`);
+            parts.push(`- [migration] **${item.topic.title}** (key: \`${item.key}\`) - ${item.topic.description}${sectionHint(item.topic.content, query)}`);
         }
         parts.push("");
         parts.push("Use `get_migration_guide(topic)` to get full content for any migration topic.");