Update to Brainerce

{
  "description": "Look up the real shape of the Brainerce storefront SDK: method names, arguments, return types and the TypeScript definitions behind them. Use when a developer asks what does this SDK method take, what comes back from it, what is the type of a product or an order, how do I fetch products with variants, which method loads a category, or is there a method for this at all. This is the reference, so reach for it whenever you are about to write a Brainerce call and are not certain of its exact signature. For developers. Do not choose this for the ordered sequence a checkout or login has to follow, use brainerce-checkout-flows. Do not choose this to plan or scaffold a whole storefront, use brainerce-storefront-build. Do not choose this for admin or dashboard operations such as creating a product as a merchant, those are merchant skills. Keywords: SDK, method, signature, arguments, return type, TypeScript types, interface, BrainerceClient, getProducts, types, API reference, does this method exist.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 756
    },
    {
      "relative_path": "assets/icon.png",
      "size_in_bytes": 3208
    },
    {
      "relative_path": "references/sdk-account-cart-and-offers.md",
      "size_in_bytes": 18809
    },
    {
      "relative_path": "references/sdk-content.md",
      "size_in_bytes": 7026
    },
    {
      "relative_path": "references/sdk-gift-cards-admin.md",
      "size_in_bytes": 8212
    },
    {
      "relative_path": "references/sdk-products.md",
      "size_in_bytes": 30999
    },
    {
      "relative_path": "references/sdk-setup.md",
      "size_in_bytes": 12543
    },
    {
      "relative_path": "references/sdk-tax.md",
      "size_in_bytes": 14686
    },
    {
      "relative_path": "references/type-definitions.md",
      "size_in_bytes": 147341
    }
  ],
  "name": "brainerce-sdk",
  "skill_md_contents": "---\nname: brainerce-sdk\ndescription: 'Look up the real shape of the Brainerce storefront SDK: method names, arguments, return types and the TypeScript definitions behind them. Use when a developer asks what does this SDK method take, what comes back from it, what is the type of a product or an order, how do I fetch products with variants, which method loads a category, or is there a method for this at all. This is the reference, so reach for it whenever you are about to write a Brainerce call and are not certain of its exact signature. For developers. Do not choose this for the ordered sequence a checkout or login has to follow, use brainerce-checkout-flows. Do not choose this to plan or scaffold a whole storefront, use brainerce-storefront-build. Do not choose this for admin or dashboard operations such as creating a product as a merchant, those are merchant skills. Keywords: SDK, method, signature, arguments, return type, TypeScript types, interface, BrainerceClient, getProducts, types, API reference, does this method exist.'\ncompatibility: ChatGPT, Claude Code, Claude Desktop, Cursor\nmaintainer: Brainerce\nmetadata:\n  author: Brainerce\n  version: '1.1.0'\n---\n\nBe certain about a Brainerce SDK call before writing it.\n\n## Core principle\n\nAn invented method is the most expensive mistake available here. It compiles, it reads well, it fails at runtime in front of a customer, and it is hard to spot in review because it looks exactly like a real call. So: if a method is not in these references, it does not exist. Say so and offer the closest real one rather than producing something plausible.\n\n## When to use this skill first\n\n- \"What arguments does this take\", \"what comes back\".\n- \"What is the type of a product, an order, a cart line\".\n- \"Is there a method for X\".\n- Any moment you are about to write a Brainerce call and are not certain of the exact name or shape.\n\n## When NOT to use this skill first\n\n- The order of operations for checkout, login, password reset or inventory reservation: use `brainerce-checkout-flows`. Signatures are here; sequences are there, and a correct call in the wrong order still breaks.\n- Planning or scaffolding a storefront: use `brainerce-storefront-build`.\n- Auditing an existing integration: use `brainerce-integration-verify`.\n- Merchant-side operations through the admin connector: those are the merchant skills, and they use a different tool surface entirely.\n\n---\n\n## How to use the references\n\n- `references/type-definitions.md` is the full TypeScript surface. Search it for the type name before describing any shape.\n- `references/sdk-setup.md`: creating and configuring the client, and the options it takes.\n- `references/sdk-products.md`: catalog reads, variants, modifier groups, the real product shape.\n- `references/sdk-content.md`: pages, blog and content reads.\n- `references/sdk-tax.md`: tax handling and how totals are presented, including where a gift card goes in the order summary. It is a means of payment, not a discount, so it sits BELOW the total with an \"Amount due\" row and never inside the discount block.\n- `references/sdk-gift-cards-admin.md`: the eight admin gift-card methods, the scope each needs, and the one rule that matters most here: a storefront must never hold `gift_cards:issue`. A storefront redeems (`applyGiftCard`, `removeGiftCard`, `checkGiftCardBalance`) and needs no API key to do it.\n- `references/sdk-account-cart-and-offers.md`: the account address book and OAuth links, order bumps and bundles, recommendations and nudges, the cart badge and lifecycle hooks, pre-checkout stock validation, locale discovery, `trackEvent`, and guest download retrieval. Each entry names the modes it works in, because several of these throw outside one specific mode.\n\nWhen the Brainerce MCP server is connected (Claude Code, Cursor, or the CLI), `get-sdk-docs` and `get-type-definitions` serve the same content live and reflect the installed SDK version. Prefer them there. In ChatGPT there is no such connection, and these snapshots are the source of truth.\n\n## Rules\n\n- **Quote the reference, do not paraphrase from memory.** If your recollection and the file disagree, the file wins.\n- **Prices are strings.** Parse them before arithmetic. This is the single most common bug in Brainerce integrations and it survives review because the code looks right.\n- **Never invent a method.** \"I do not see a method for that; the closest is X, which does Y\" is a good answer. A confidently wrong method name is not.\n- **Do not flatten a nested shape** because it would be more convenient. Line items in particular are nested in some responses and flat in others; check which one you have.\n- **An admin API key is server-side only, and `gift_cards:issue` is the one to refuse hardest.** It mints stored value, so a key carrying it in browser-reachable code lets a stranger create money. Storefronts redeem gift cards with public calls that take no key at all. See `references/sdk-gift-cards-admin.md`.\n- **Currency, locale and store id come from the store**, never from a constant in the code.\n- **Say which SDK version the reference reflects** if the developer is debugging behaviour that does not match. A snapshot can lag a published release, and `npm view brainerce version` settles it in one command.\n\n- A product may be `SIMPLE`, `VARIABLE` or `KIT`. A KIT is one sellable product\n  made of other products: add the KIT itself to the cart, never its components,\n  and read `kitAvailable` rather than `inventory`, which a kit does not have.\n  `kitComponents` comes back on the by-slug read and is for display only.\n\n## Response shape\n\n> `client.getProducts(options)` takes:\n>\n> - `limit` and `page` for pagination. The API caps `limit` at 100, so do not use this to build a sitemap; there is a dedicated helper for that.\n> - `categories`, `brands`, `tags` for filtering, `search` for free text, `minPrice` / `maxPrice` for a price band, and `metafields` for custom-field facets.\n> - `categories`, `brands` and `tags` take **IDs**, not slugs and not names: `categories: ['cat_123']`, never `categories: ['t-shirts']`. There is no `categorySlug` and no `tag` parameter.\n>\n> There is no slug filter, so on a `/category/{slug}` route resolve the slug to an id first:\n>\n> ```typescript\n> const category = await client.getCategoryBySlug(slug); // sales-channel mode only\n> const { data } = await client.getProducts({ categories: [category.id] });\n> ```\n>\n> `getCategoryBySlug` throws outside sales-channel mode, and so does `client.getCategories()`: in storeId or admin mode there is NO public category read at all (nor `getBrands()` / `getTags()`), so there is no tree to walk. In those modes the only category data you can see is the `categories[]` array (`{ id, name, slug }`) on the products you have already fetched; build navigation from those, or connect through a `vc_` sales channel. In sales-channel mode the tree from `getCategories()` is `CategoryNode[]`, nested to any depth through `children`, so recurse rather than reading only the top level; the shape is in `references/type-definitions.md`. Tag ids come from `client.getTags()` (sales-channel only); there is no tag-slug lookup at all.\n>\n> Locale is not a per-call argument here: `getProducts` does not send one. Call `client.setLocale(locale)` once on the client and the reads come back translated.\n>\n> It returns `{ data: Product[], meta: { page, limit, total, totalPages } }`.\n>\n> Note the money fields are strings, so parse them before any arithmetic. A product carries `basePrice` and `salePrice`, not a `price`; `getProductPriceInfo(product)` resolves which one is in effect.\n\n**Method does not exist, use this shape:**\n\n> There is no `getProductBySku` in the SDK. The closest is `getProducts({ search })`, which matches on SKU among other fields, so you would filter the result. If you need an exact SKU lookup, that is worth confirming with the Brainerce team rather than working around it.\n\n## Cross-skill connections\n\n- Sequences rather than signatures: `brainerce-checkout-flows`.\n- Building a whole storefront: `brainerce-storefront-build`.\n- Checking a finished integration: `brainerce-integration-verify`.\n\nRoute once, and do not bounce back and forth.\n"
}