brainerce 2.3.0 → 2.5.0

package/README.md

@@ -596,6 +596,26 @@ if (!page) notFound();
 
 All `get` / `getBySlug` return `null` on 404. Render a hard-coded fallback so the page never crashes when the merchant hasn't seeded yet.
 
+**Admin mode (API key) — every call needs an explicit `storeId`.** The reads above (`get`, `list`, `getBySlug`) are storefront APIs; in admin mode they throw and point you at the admin pair below. Admin mode has no ambient store — `storeId` is only set in storefront mode — and the admin content routes are store-scoped, so omitting it is rejected fail-closed by the store scope guard (`403 STORE_SCOPE_REQUIRED`). Pass the id of the store your API key is bound to; naming any other store is rejected as cross-tenant.
+
+```typescript
+// Read (drafts included)
+const rows = await client.content.listAdmin({ storeId, type: 'FAQ', status: 'DRAFT' });
+const row = await client.content.findById('cnt_123', storeId);
+
+// Write
+const created = await client.content.faq.create(
+  { key: 'shipping', name: 'Shipping FAQ', data: { items: [{ question: '…', answer: '…' }] } },
+  storeId
+);
+await client.content.update('cnt_123', { name: 'Shipping FAQ' }, storeId);
+await client.content.publish('cnt_123', storeId);
+await client.content.unpublish('cnt_123', storeId);
+await client.content.remove('cnt_123', storeId);
+```
+
+Your API key needs the `content:read` scope for the reads and `content:write` for the writes.
+
 **Security**: `FAQ.items[i].answer`, `RICH_TEXT.html`, `PAGE.html`, and `Product.description` are **merchant-authored HTML**. The server does NOT pre-sanitize FAQ/RICH_TEXT/PAGE (merchants may embed iframes); `Product.description` is server-sanitized on write but you still sanitize on render. `Product.description` may contain `<video>` and host-locked YouTube/Vimeo `<iframe>` embeds, so allow those tags (iframe restricted to `www.youtube.com` / `www.youtube-nocookie.com` / `player.vimeo.com`) and add those hosts to your CSP `frame-src`. ALWAYS sanitize before injecting:
 
 ```typescript
@@ -612,18 +632,35 @@ Full guide: [Core Integration "Content"](https://brainerce.com/docs/integration/
 Merchants publish blog posts in **Content → Blog**. Storefronts choose their own URL scheme: render posts at `/blog/[slug]`, `/articles/[slug]`, or whatever fits the brand.
 
 ```typescript
-// List published posts (any SDK mode)
+// List published posts (storefront / vibe-coded mode)
 const { data: posts, meta } = await client.blog.getPosts({ page: 1, limit: 10 });
 
 // Filter by category or tag
 const { data: news } = await client.blog.getPosts({ category: 'news' });
 const { data: tips } = await client.blog.getPosts({ tag: 'tutorial' });
 
-// Fetch one by slug — returns null on 404
+// Fetch one by slug — returns null on 404 (storefront / vibe-coded mode)
 const post = await client.blog.getPost(params.slug);
 if (!post) notFound();
 ```
 
+**Admin mode (API key) — every call needs an explicit `storeId`.** Admin mode has no ambient store (`storeId` is only set in storefront mode) and the admin blog routes are store-scoped, so omitting it is rejected fail-closed by the store scope guard (`403 STORE_SCOPE_REQUIRED`). Pass the id of the store your API key is bound to; naming any other store is rejected as cross-tenant. Admin lookups are **by id, not by slug** — `getPost(slug)` is a storefront read and throws in admin mode.
+
+```typescript
+// Read (drafts included)
+const { data, meta } = await client.blog.getPosts({ page: 1, limit: 10 }, storeId);
+const post = await client.blog.findById('post_123', storeId); // null on 404
+
+// Write
+const draft = await client.blog.create({ title: 'Hello World' }, storeId);
+await client.blog.update('post_123', { title: 'Renamed' }, storeId);
+await client.blog.publish('post_123', storeId);
+await client.blog.unpublish('post_123', storeId);
+await client.blog.remove('post_123', storeId);
+```
+
+Your API key needs the `blog:read` scope for the reads and `blog:write` for the writes.
+
 **Security**: `post.content` is merchant-authored HTML. Always sanitize before rendering:
 
 ```tsx
@@ -638,7 +675,7 @@ return <div dangerouslySetInnerHTML={{ __html: safeHtml }} className="prose" />;
 
 ### SEO: JSON-LD builders, sitemap helpers, IndexNow key, llms.txt + agents.md
 
-The SDK ships schema.org builders that encode Google's structured-data rules (aggregateRating gated on `reviewCount > 0` with explicit `bestRating`/`worstRating`, AggregateOffer with `offerCount` for VARIABLE products, XSS-safe serialization, and the full availability mapping: `InStock` from the backend's pre-computed `inventory.inStock`, `BackOrder` for purchasable-while-out-of-stock products, `OutOfStock` otherwise). `buildProductJsonLd`'s Offer also always includes `itemCondition` (hardcoded `NewCondition`, for a first-party new-goods catalog), `priceValidUntil` when the product has an active sale-price window (`salePriceEndsAt`), and `shippingDetails` when you pass `shipping` (real flat-rate/free zones from `storeInfo.shipping`, omitted entirely and never fabricated if you don't pass it). A `'KIT'` product is emitted with **no `offers` block at all** — a kit prices from its components, so publishing its placeholder `basePrice` would advertise a price it will not be sold at, and a price mismatch against the landing page is a Merchant Center violation. Prefer these builders over hand-rolled JSON-LD:
+The SDK ships schema.org builders that encode Google's structured-data rules (aggregateRating gated on `reviewCount > 0` with explicit `bestRating`/`worstRating`, AggregateOffer with `offerCount` for VARIABLE products, XSS-safe serialization, and the full availability mapping: `InStock` from the backend's pre-computed `inventory.inStock`, `BackOrder` for purchasable-while-out-of-stock products, `OutOfStock` otherwise). `buildProductJsonLd`'s Offer also always includes `itemCondition` (hardcoded `NewCondition`, for a first-party new-goods catalog), `priceValidUntil` when the product has an active sale-price window (`salePriceEndsAt`), and `shippingDetails` when you pass `shipping` (real flat-rate/free zones from `storeInfo.shipping`, omitted entirely and never fabricated if you don't pass it). A `'KIT'` product is emitted with **no `offers` block at all**, which is deliberate: kits are not published to Google or Meta shopping feeds, so the builder does not advertise a price for one. Do not hand-roll an Offer to add it. Prefer these builders over hand-rolled JSON-LD:
 
 ```tsx
 import {
@@ -1740,6 +1777,39 @@ const { data } = await client.getProducts({
 
 ### Products
 
+#### Kits (`type: 'KIT'`)
+
+A kit is one purchasable product assembled from other catalog products. It is
+bought as a SINGLE cart line: pass the kit's own `productId` to `addToCart` and
+the server reserves each component behind that line. Adding components
+separately charges twice and reserves twice.
+
+A kit has **no `inventory` block**. Read `kitAvailable` on the product (`null` =
+unlimited, `0` = not sellable), or `available` from `getKitComponents`. Outside
+`FIXED` pricing the product row's `basePrice` is a placeholder; use the resolved
+price.
+
+```typescript
+// Read what's in a kit (admin API key required)
+const kit = await client.getKitComponents('prod_123');
+console.log(kit.price, kit.available, kit.pricingMode);
+kit.components.forEach((c) => console.log(c.name, 'x' + c.quantity));
+
+// Replace its contents, and how it's priced
+await client.setKitComponents('prod_123', {
+  components: [
+    { componentProductId: 'prod_bottle', quantity: 1 },
+    // A VARIABLE component must have one variant pinned
+    { componentProductId: 'prod_glass', componentVariantId: 'pv_300ml', quantity: 2 },
+  ],
+  pricingMode: 'SUM_MINUS_PERCENT', // or 'FIXED' | 'SUM'
+  discountValue: 10,
+});
+```
+
+On the storefront, `getProductBySlug` returns `kitComponents` for display so a
+shopper can see what is in the box. Those rows are display only.
+
 #### Get Products (with pagination)
 
 ```typescript
@@ -1888,10 +1958,35 @@ interface Product {
   displayCurrency?: string; // ISO 4217 of the display* fields
   status: string; // e.g. "active" | "draft"
   type: 'SIMPLE' | 'VARIABLE' | 'KIT';
+  // ── KIT only ──────────────────────────────────────────────────────────────
+  // What the kit contains. Returned on the single-product (by slug) read ONLY,
+  // never on list responses. DISPLAY ONLY — render it so the shopper sees what
+  // is in the box; never turn these rows into cart lines.
+  kitComponents?: Array<{
+    productId: string;
+    variantId: string | null;
+    name: string;
+    sku: string | null;
+    quantity: number;
+    image: string | null;
+  }>;
+  // How many kits can be sold: whichever component runs out first decides.
+  // null = unlimited, 0 = NOT SELLABLE (including a kit with no components).
+  // A kit has NO `inventory` block, so this is the ONLY stock signal. Reading
+  // a missing `inventory` as "in stock" renders a sold-out kit as buyable.
+  kitAvailable?: number | null;
+  // How the kit is priced. FIXED (default) keeps the merchant's own basePrice.
+  // SUM = exactly what the components cost, recomputed on every read.
+  // SUM_MINUS_PERCENT = that sum less kitDiscountValue percent (0-100).
+  // Outside FIXED the stored basePrice is a PLACEHOLDER — but the storefront
+  // reads overlay `basePrice` with the resolved price, so render basePrice.
+  kitPricingMode?: 'FIXED' | 'SUM' | 'SUM_MINUS_PERCENT';
+  kitDiscountValue?: number;
+  // ──────────────────────────────────────────────────────────────────────────
   isDownloadable?: boolean;
   downloads?: DownloadFile[] | null; // when isDownloadable
   images?: ProductImage[];
-  inventory?: InventoryInfo | null;
+  inventory?: InventoryInfo | null; // null/absent on a KIT — use kitAvailable
   variants?: ProductVariant[];
   categories?: Array<{ id: string; name: string; slug?: string | null }>; // NOT string[] — use slug to link to /category/{slug}
   brands?: Array<{ id: string; name: string }>; // objects, not string[]
@@ -2222,19 +2317,41 @@ function ProductPrice({ product }: { product: Product }) {
 
 **When the product is a `'KIT'`:**
 
-A kit is a bundle sold as one line, priced from real component products. It is
-not a Bundle offer and not a discount rule — it is a product with its own page,
-slug and SEO.
-
-- Show `basePrice` / `salePrice` as you would for a `'SIMPLE'` product. The
-  backend has already resolved the kit's price from its components, so do NOT
-  try to sum them yourself.
-- A kit carries **no `inventory` of its own**. Availability is derived from what
-  its components have in stock, so never render "out of stock" from a missing
-  `inventory` object on a kit.
-- Add it to the cart by `productId` with no `variantId`, like a `'SIMPLE'`
-  product. Kits take no variants and no modifier selections; sending
-  `selections` is rejected.
+A kit is one purchasable product assembled from other catalog products, sold as
+one line. It is not a Bundle offer and not a discount rule: it is a product with
+its own page, slug and SEO.
+
+- Show `basePrice` as you would for a `'SIMPLE'` product. The storefront reads
+  overlay it with the **resolved** kit price, so do NOT sum the components
+  yourself.
+- ⛔ **`salePrice` is only meaningful on a `FIXED` kit.** On `SUM` and
+  `SUM_MINUS_PERCENT` the discount is already expressed by the pricing mode and
+  the kit's own sale price is ignored by the engine, so rendering a strikethrough
+  from it shows the shopper a discount that is not being applied. Both reads
+  behave the same way: outside `FIXED` they null the kit's `salePrice`, and on
+  `FIXED` they leave `basePrice`/`salePrice` untouched so the normal was/now
+  logic works. Gate any strikethrough on `kitPricingMode === 'FIXED'`.
+- **Do not tell the shopper the price is fixed.** There are three pricing modes
+  and two of them move on their own. `kitPricingMode: 'FIXED'` (the default) is
+  the number the merchant typed and stays put. `'SUM'` makes the kit cost
+  exactly what its contents cost, **recomputed on every read**, so a component
+  going on sale lowers the kit price by itself. `'SUM_MINUS_PERCENT'` is that
+  sum less `kitDiscountValue` percent. Outside `FIXED` the stored `basePrice`
+  on the raw product row is a **placeholder** — never cache it, and never
+  compute from a value you fetched earlier.
+- A kit carries **no `inventory` of its own**. Read **`kitAvailable`**:
+  `null` = unlimited, `0` = **not sellable** (including a kit with no
+  components), any other number = how many kits can be sold. "Don't render
+  out-of-stock just because `inventory` is missing" is only half the rule:
+  without `kitAvailable` a sold-out kit renders as buyable, which is worse.
+- Render **`kitComponents`** so the shopper can see what is in the box. It comes
+  back on the single-product (by slug) read only, never on list responses, as
+  `{ productId, variantId, name, sku, quantity, image }` rows. They are
+  **display only**.
+- Add it to the cart by the kit's own `productId` with **no `variantId`** — a
+  kit has no variants and sending one is rejected. It takes no modifier
+  `selections` either (HTTP 400). ⛔ **Never add its components as separate
+  lines**: that charges the customer twice and reserves the stock twice.
 
 #### Rendering Product Descriptions
 
@@ -3196,9 +3313,15 @@ interface Checkout {
   discountAmount: string;
   shippingAmount: string;
   taxAmount: string; // "0" in inclusive (VAT) mode — see taxBreakdown.totalTax
-  taxBreakdown?: TaxBreakdown | null; // { totalTax, pricesIncludeTax, breakdown[] }
+  taxBreakdown?: TaxBreakdown | null; // { subtotal, shippingNet, totalTax, total, pricesIncludeTax, breakdown[] }
   // breakdown[] is ONE ROW PER TAX and is often more than one row (Canada charges
   // GST + PST/QST). Loop it; never read breakdown[0].
+  // taxBreakdown.subtotal is NOT the `subtotal` above: it is the net of every
+  // taxed line and it INCLUDES the shipping net, so subtotal + shipping + tax
+  // counts shipping twice. Use taxBreakdown.subtotal - taxBreakdown.shippingNet
+  // for a goods-only row, and subtract shippingNet rather than the gross
+  // shippingAmount — they are equal only while shipping is untaxed. The
+  // top-level `subtotal` is goods-only and needs no adjustment.
   total: string;
   couponCode?: string | null;
   // Gift cards held against this checkout, oldest first. Read these to re-render
@@ -5083,6 +5206,12 @@ const product: Product = await client.createProduct({
   costPrice: 12.0, // Optional, internal — never synced to platforms
   status: 'active', // 'active' | 'draft' (default: 'active')
   type: 'SIMPLE', // 'SIMPLE' | 'VARIABLE' | 'KIT' (default: 'SIMPLE')
+  // KIT only. FIXED (default) means you set basePrice and it stays put. SUM
+  // means the kit costs exactly what its components cost, recomputed on every
+  // read, so a component going on sale lowers the kit price on its own.
+  // SUM_MINUS_PERCENT is that sum less kitDiscountValue percent.
+  // kitPricingMode: 'SUM_MINUS_PERCENT',
+  // kitDiscountValue: 10, // 0-100, required with SUM_MINUS_PERCENT
   categories: ['cat_id'], // Existing category IDs
   categoryNames: ['Apparel'], // Or assign/auto-create by name — merged with `categories`
   brands: ['brand_id'],
@@ -5155,6 +5284,69 @@ await client.bulkSaveVariants(variableProduct.id, {
 
 **GTIN vs MPN:** these are two different identifiers, not interchangeable: GTIN (EAN/UPC/ISBN) is a universal barcode; MPN is manufacturer-specific and only meaningful paired with a brand. Provide GTIN when the product has one; otherwise brand + MPN. A product typically needs one or the other, not both.
 
+### Kit Management (`type: 'KIT'`)
+
+⛔ **`createProduct({ type: 'KIT' })` gives you an EMPTY kit, and an empty kit
+cannot be bought.** A kit is defined by its component list, so creating the
+product is only half the job: until you call `setKitComponents`, the kit has no
+price, `kitAvailable` is `0`, and `addToCart` refuses it as unavailable. It is
+not an error state you will see in the response — the create succeeds and the
+product looks fine. Create, then set components, in that order.
+
+```typescript
+import type { KitDetail, KitComponentWriteInput } from 'brainerce';
+
+// 1. Create the kit product (empty and unbuyable at this point)
+const kit = await client.createProduct({
+  name: 'Wine Gift Box',
+  basePrice: 199, // required to save; only charged on FIXED pricing
+  type: 'KIT',
+  kitPricingMode: 'SUM_MINUS_PERCENT', // also settable on updateProduct
+  kitDiscountValue: 10, // 0-100, required with SUM_MINUS_PERCENT
+});
+
+// 2. Give it contents — this is what makes it purchasable
+const detail: KitDetail = await client.setKitComponents(kit.id, {
+  components: [
+    { componentProductId: 'prod_bottle', quantity: 1 },
+    // A VARIABLE component MUST have exactly one variant pinned
+    { componentProductId: 'prod_glass', componentVariantId: 'pv_300ml', quantity: 2 },
+  ],
+  pricingMode: 'SUM_MINUS_PERCENT', // optional — omit to leave the mode alone
+  discountValue: 10,
+});
+
+// 3. Read it back any time
+const read: KitDetail = await client.getKitComponents(kit.id);
+console.log(read.price, read.available, read.pricingMode, read.discountValue);
+read.components.forEach((c) => console.log(c.name, 'x' + c.quantity, c.unitPrice, c.available));
+```
+
+`setKitComponents` is a **full replace**, not a patch: send the list the kit
+should end up with. An empty `components` array clears the kit and makes it
+unbuyable again. Max **30** components; `quantity` is 1-2000 per slot.
+
+`getKitComponents` is safe to call on any product id — a non-KIT returns an
+empty, unsellable shape rather than throwing, so callers need not branch on
+product type first.
+
+**Pricing modes:** `FIXED` (default) charges the kit's own `basePrice` /
+`salePrice`. `SUM` charges exactly what the components cost, **recomputed on
+every read**, so a component going on sale lowers the kit price on its own.
+`SUM_MINUS_PERCENT` is that sum less `kitDiscountValue` percent. Outside `FIXED`
+the stored `basePrice` is a **placeholder** and the kit's own `salePrice` is
+ignored. Use `KitDetail.price`, or the `basePrice` on a storefront read, which
+outside `FIXED` is already overlaid with the resolved figure (on `FIXED` the
+stored prices are returned as they are, sale included).
+
+**Refused on write:** a product that is not a `KIT`; a component from another
+store; a component that is itself a `KIT` (kits do not nest); a `VARIABLE`
+component with no `componentVariantId`; a variant that does not belong to its
+product; the same slot listed twice; and the kit itself. You also cannot delete
+a product while it sits inside a kit — remove it from the kit first. `SIMPLE` ↔
+`KIT` conversion is allowed (`KIT` → `SIMPLE` only once the kit is empty);
+`VARIABLE` ↔ `KIT` is refused outright.
+
 ### Bulk Product Creation (catalog import)
 
 Importing a catalog (a supplier feed, a CSV/Excel export, a store migration)
@@ -5897,8 +6089,10 @@ Each store has its own team with roles (`OWNER`, `MANAGER`, `STAFF`, `VIEWER`) a
 granular permissions, including per-sales-channel scoping. **Managing it is a dashboard
 operation. There is no SDK path to it, and this is deliberate.**
 
-This section previously showed store-level team calls. **Since SDK 2.1.1 they throw a
-`BrainerceError` that says so, instead of returning a bare 404.** Ten methods are
+This section previously showed store-level team calls. **Since SDK 2.2.0 they throw a
+`BrainerceError` that says so, instead of returning a bare 404.** (The change is dated
+2.1.1 in the changelog, but that version was never published: npm went 2.1.0 straight to
+2.2.0, so 2.2.0 is the first release you can actually install it from.) Ten methods are
 affected: `getStoreTeam`, `inviteStoreMember`, `updateStoreMember`,
 `updateStoreMemberSalesChannels`, `removeStoreMember`, `resendStoreInvitation`,
 `revokeStoreInvitation`, `acceptStoreInvitation`, `getMyStores` and
@@ -5919,17 +6113,22 @@ route is `@Public()`, and it was only ever failing because the SDK asked for
 Use it to render an invitation-acceptance page; the acceptance itself must happen in the
 dashboard, because it is matched against the invited user's own email address.
 
-> **The older account-level methods are not a substitute for this.** `getTeamMembers`,
-> `getTeamInvitations`, `inviteTeamMember`, `resendTeamInvitation`, `revokeTeamInvitation`,
-> `updateTeamMemberRole` and `removeTeamMember` do still reach `/api/v1/team/…`, but they
-> manage the **account** team, not a store's. They will not invite anyone to a store or
-> scope a member to a sales channel; only the dashboard does that.
+> ⛔ **The older account-level methods are not a substitute, and they do not work
+> either.** `getTeamMembers`, `getTeamInvitations`, `inviteTeamMember`,
+> `resendTeamInvitation`, `revokeTeamInvitation`, `updateTeamMemberRole` and
+> `removeTeamMember` now **throw** instead of calling `/api/v1/team/…`. An earlier
+> version of this page said they remained the supported call for the account team.
+> That was wrong: those routes hand the team service a synthetic `api-key-user`
+> principal that has no account membership row, so every one of them answered
+> `Access denied to this account`. The SDK raises that locally now, naming the cause,
+> rather than sending a request that cannot succeed.
 >
-> **For the account team, they remain the supported call.** All seven are tagged
-> `@deprecated`, which records an intent to retire them, not a migration you can perform
-> today. There is no API-key replacement: the store-level methods named above are
-> dashboard-only. Keep using these until an API-key route ships, and expect the tag to
-> outlive this note.
+> **There is no API-key path to team management, at either level, and there should
+> not be.** Team membership is account-scoped and an invite can grant ownership of
+> every store on the account, while an API key is bound to exactly one store.
+> Admitting the key would turn a single-store credential into account ownership.
+> Manage members in the dashboard, or use the store-scoped `team:*` tools on the
+> admin MCP server, which are OAuth-authenticated and bound to one store.
 
 ### Email Settings & Templates