brainerce 1.57.0 → 1.58.1

package/README.md

@@ -269,32 +269,33 @@ the credential, no customer token needed.
 
 The SDK exports these utility functions for common UI tasks:
 
-| Function                                       | Purpose                                                                                      | Example                                                |
-| ---------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| `formatPrice(amount, { currency?, locale? })`  | Format prices for display                                                                    | `formatPrice("99.99", { currency: 'USD' })` → `$99.99` |
-| `getPriceDisplay(amount, currency?, locale?)`  | Alias for `formatPrice`                                                                      | Same as above                                          |
-| `getDescriptionContent(product)`               | Get product description (HTML or text)                                                       | `getDescriptionContent(product)`                       |
-| `isHtmlDescription(product)`                   | Check if description is HTML                                                                 | `isHtmlDescription(product)` → `true/false`            |
-| `getStockStatus(inventory)`                    | Get human-readable stock status                                                              | `getStockStatus(inventory)` → `"In Stock"`             |
-| `getProductPrice(product)`                     | Get effective price (handles sales)                                                          | `getProductPrice(product)` → `29.99`                   |
-| `getProductPriceInfo(product)`                 | Get price + sale info + discount % (falls back to `priceMin` when `basePrice=0` on VARIABLE) | `{ price, isOnSale, discountPercent }`                 |
-| `getVariantPrice(variant, basePrice)`          | Get variant price with fallback                                                              | `getVariantPrice(variant, '29.99')` → `34.99`          |
-| `getCartTotals(cart, shippingPrice?)`          | Calculate cart subtotal/discount/total                                                       | `{ subtotal, discount, shipping, total }`              |
-| `getCartItemName(item)`                        | Get name from nested cart item (product + variant)                                           | `getCartItemName(item)` → `"Blue T-Shirt - Large"`     |
-| `getCartItemImage(item)`                       | Get image URL from cart item                                                                 | `getCartItemImage(item)` → `"https://..."`             |
-| `getVariantOptions(variant)`                   | Get variant attributes as array                                                              | `[{ name: "Color", value: "Red" }]`                    |
-| `isCouponApplicableToProduct(coupon, product)` | Check if coupon applies                                                                      | `isCouponApplicableToProduct(coupon, product)`         |
-| `isAllowedPaymentUrl(url, options?)`           | Validate a payment URL host                                                                  | `isAllowedPaymentUrl(intent.clientSecret)` → `true`    |
-| `safePaymentRedirect(url, options?)`           | Validate then `window.location.href`                                                         | `safePaymentRedirect(intent.clientSecret)`             |
-| `buildProductJsonLd(product, opts)`            | schema.org Product JSON-LD (PDPs only)                                                       | See SEO section                                        |
-| `buildArticleJsonLd(post, opts)`               | schema.org Article JSON-LD for blog posts                                                    | See SEO section                                        |
-| `buildOrganizationJsonLd(store, opts)`         | schema.org Organization for the homepage                                                     | See SEO section                                        |
-| `buildBreadcrumbJsonLd(items)`                 | schema.org BreadcrumbList                                                                    | See SEO section                                        |
-| `jsonLdScriptProps(data)`                      | XSS-safe `<script type="application/ld+json">` props                                         | `<script {...jsonLdScriptProps(data)} />`              |
-| `getBlogSitemapEntries(client, opts)`          | Paginate published posts into sitemap entries                                                | See SEO section                                        |
-| `getProductSitemapEntries(client, opts)`       | ALL published products into sitemap entries (no 100-item clamp)                              | See SEO section                                        |
-| `getCategorySitemapEntries(client, opts)`      | Category tree into sitemap entries                                                           | See SEO section                                        |
-| `client.resolveSlugRedirect(type, slug)`       | Renamed slug → current slug (301 support in not-found paths)                                 | See SEO section                                        |
+| Function                                       | Purpose                                                                                         | Example                                                |
+| ---------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `formatPrice(amount, { currency?, locale? })`  | Format prices for display                                                                       | `formatPrice("99.99", { currency: 'USD' })` → `$99.99` |
+| `getPriceDisplay(amount, currency?, locale?)`  | Alias for `formatPrice`                                                                         | Same as above                                          |
+| `getDescriptionContent(product)`               | Get product description (HTML or text)                                                          | `getDescriptionContent(product)`                       |
+| `isHtmlDescription(product)`                   | Check if description is HTML                                                                    | `isHtmlDescription(product)` → `true/false`            |
+| `getStockStatus(inventory)`                    | Get human-readable stock status                                                                 | `getStockStatus(inventory)` → `"In Stock"`             |
+| `getProductPrice(product)`                     | Get effective price (handles sales)                                                             | `getProductPrice(product)` → `29.99`                   |
+| `getProductPriceInfo(product)`                 | Get price + sale info + discount % (falls back to `priceMin` when `basePrice=0` on VARIABLE)    | `{ price, isOnSale, discountPercent }`                 |
+| `getVariantPrice(variant, basePrice)`          | Get variant price with fallback                                                                 | `getVariantPrice(variant, '29.99')` → `34.99`          |
+| `getCartTotals(cart, shippingPrice?)`          | Calculate cart subtotal/discount/total                                                          | `{ subtotal, discount, shipping, total }`              |
+| `getCartItemName(item)`                        | Get name from nested cart item (product + variant)                                              | `getCartItemName(item)` → `"Blue T-Shirt - Large"`     |
+| `getCartItemImage(item)`                       | Get image URL from cart item                                                                    | `getCartItemImage(item)` → `"https://..."`             |
+| `getVariantOptions(variant)`                   | Get variant attributes as array                                                                 | `[{ name: "Color", value: "Red" }]`                    |
+| `isCouponApplicableToProduct(coupon, product)` | Check if coupon applies                                                                         | `isCouponApplicableToProduct(coupon, product)`         |
+| `isAllowedPaymentUrl(url, options?)`           | Validate a payment URL host                                                                     | `isAllowedPaymentUrl(intent.clientSecret)` → `true`    |
+| `safePaymentRedirect(url, options?)`           | Validate then `window.location.href`                                                            | `safePaymentRedirect(intent.clientSecret)`             |
+| `buildProductJsonLd(product, opts)`            | schema.org Product JSON-LD (PDPs only)                                                          | See SEO section                                        |
+| `buildArticleJsonLd(post, opts)`               | schema.org Article JSON-LD for blog posts                                                       | See SEO section                                        |
+| `buildOrganizationJsonLd(store, opts)`         | schema.org Organization for the homepage                                                        | See SEO section                                        |
+| `buildBreadcrumbJsonLd(items)`                 | schema.org BreadcrumbList                                                                       | See SEO section                                        |
+| `buildProductFaqJsonLd(product)`               | schema.org FAQPage from `product.faq` (null when empty) — render the same pairs as visible text | `const faq = buildProductFaqJsonLd(product)`           |
+| `jsonLdScriptProps(data)`                      | XSS-safe `<script type="application/ld+json">` props                                            | `<script {...jsonLdScriptProps(data)} />`              |
+| `getBlogSitemapEntries(client, opts)`          | Paginate published posts into sitemap entries                                                   | See SEO section                                        |
+| `getProductSitemapEntries(client, opts)`       | ALL published products into sitemap entries (no 100-item clamp)                                 | See SEO section                                        |
+| `getCategorySitemapEntries(client, opts)`      | Category tree into sitemap entries                                                              | See SEO section                                        |
+| `client.resolveSlugRedirect(type, slug)`       | Renamed slug → current slug (301 support in not-found paths)                                    | See SEO section                                        |
 
 ```typescript
 import {
@@ -495,6 +496,8 @@ import {
   buildOrganizationJsonLd,   // homepage
   buildCollectionPageJsonLd, // category landing pages
   buildBreadcrumbJsonLd,
+  buildProductFaqJsonLd,     // FAQPage from product.faq (returns null when empty);
+                             // ALWAYS render the same Q&A as visible text on the page
   jsonLdScriptProps,         // XSS-safe <script> props
 } from 'brainerce';
 
@@ -1030,6 +1033,16 @@ text. Suggestions come from Google Places; each resolved address is flagged
 `inZone` against the store's configured shipping zones — a soft signal for a
 warning banner, never a hard block.
 
+Suggestions are limited to deliverable address types (street addresses, routes,
+buildings, sub-premises). Businesses, stations and other establishments are
+never returned — a courier cannot deliver to one. A shopper who types only a
+landmark name gets an empty list and has to type the street.
+
+`inZone` resolves a zone's currency-region restriction the same way the checkout
+does — destination country first, then the `regionId` you pass, then the store's
+default region — so a `true` here is not contradicted by the rates you fetch
+afterwards.
+
 ```typescript
 const sessionToken = crypto.randomUUID(); // one per address-entry attempt
 
@@ -4282,6 +4295,118 @@ 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.
 
+### Bulk Product Creation (catalog import)
+
+Importing a catalog — a supplier feed, a CSV/Excel export, a store migration —
+should not be thousands of `createProduct` calls. `bulkCreateProducts` takes an
+array and returns a **job id**: the work is queued, and the products appear over
+the following seconds or minutes.
+
+```typescript
+import type {
+  BulkCreateProductsDto,
+  BulkCreateProductsJob,
+  BulkCreateProductsStatus,
+} from 'brainerce';
+
+const job: BulkCreateProductsJob = await client.bulkCreateProducts({
+  products: [
+    {
+      name: 'Classic T-Shirt',
+      sku: 'TSH-001',
+      externalId: 'supplier-88213', // your source-system id — makes retries safe
+      basePrice: 29.99,
+      type: 'SIMPLE',
+      categoryNames: ['Apparel'], // auto-created if missing
+      brandNames: ['Acme'],
+      tags: ['summer'],
+      inventory: { total: 100 },
+    },
+    // ...up to 1000 per call
+  ],
+  importId: 'supplier-catalog-2026-08-21', // ties chunks of one import together
+  conflictStrategy: 'skip', // 'skip' (default) | 'error'
+});
+
+console.log(job.jobId, job.total); // the import has STARTED, not finished
+```
+
+**This call does not return the created products.** Poll for progress:
+
+```typescript
+let status: BulkCreateProductsStatus = await client.getBulkCreateProductsStatus(job.jobId);
+while (status.status === 'QUEUED' || status.status === 'RUNNING') {
+  await new Promise((r) => setTimeout(r, 2000));
+  status = await client.getBulkCreateProductsStatus(job.jobId);
+}
+
+// succeeded = created. skipped = already existed, NOT created.
+// "succeeded + skipped" is not the number of products you imported.
+console.log(status.succeeded, status.skipped, status.failed, status.pending);
+```
+
+`COMPLETED_WITH_ERRORS` means the import finished and some rows failed — there
+is nothing to re-run. Read the failures instead; each carries the 1-indexed
+`row` from the array you submitted, so it maps back to the line of the source
+spreadsheet:
+
+```typescript
+if (status.failed > 0) {
+  const { data, meta } = await client.getBulkCreateProductsErrors(job.jobId, { limit: 100 });
+  for (const e of data) {
+    console.log(`row ${e.row} (${e.sku ?? e.productName}): [${e.code}] ${e.message}`);
+  }
+  // Every failure is stored — nothing is truncated — so walk the pages.
+  console.log(`${meta.total} failures across ${meta.totalPages} pages`);
+}
+```
+
+**Importing 3,000-50,000 products.** A single request is capped at 1000 rows
+(500 is the comfortable size) because validating a huge nested array costs real
+CPU in the request handler. Chunk the catalog and pass the same `importId` on
+every call, then poll **once** for the whole import:
+
+```typescript
+const importId = `migration-${Date.now()}`;
+for (const chunk of chunks(allProducts, 500)) {
+  await client.bulkCreateProducts({
+    products: chunk,
+    importId,
+    idempotencyKey: `${importId}-${chunkIndex}`, // re-sending returns the original job
+  });
+}
+
+const overall = await client.getBulkCreateProductsImportStatus(importId);
+console.log(`${overall.processed}/${overall.total}`, overall.status);
+```
+
+`getBulkCreateProductsImportStatus` reports the least-complete state across the
+chunks and leaves `finishedAt` null until every one has finished, so a partial
+result can never read as a finished import.
+
+**Duplicates.** A row whose `sku` or `externalId` already exists in the store is
+skipped rather than duplicated — so a batch re-sent after a timeout cannot
+create the catalog twice. This is a database-level check, so it still holds days
+later and across retries. Rows carrying **neither** a `sku` nor an `externalId`
+have nothing to match on and will be created again on a re-send; set
+`externalId` on rows without SKUs. Pass `conflictStrategy: 'error'` when a
+duplicate means the source file is wrong and you want it reported rather than
+skipped.
+
+**One difference from `createProduct`.** If a row's explicit `slug` is already
+taken, the importer appends a suffix (`t-shirt`, `t-shirt-1`, ...) and imports
+the row, where `createProduct` returns a 400. Rows colliding with each other
+inside the same batch are resolved the same way, in submission order. That is
+deliberate — a spreadsheet with two "T-Shirt" rows should import, not fail — but
+it means the slug you sent is not always the slug you get. Read it back from
+the product if you depend on it.
+
+**Channel sync.** By default (`syncMode: 'coalesced'`) the per-product push to
+connected sales channels is suppressed during the import and one sync per
+affected channel is filed at the end — connectors are rate-limited per catalog,
+and a per-product fan-out would exhaust those limits. Use `syncMode: 'none'` to
+write to Brainerce only.
+
 ### Taxonomy Management
 
 ```typescript
@@ -6018,6 +6143,8 @@ The widget persists an anonymous session in `localStorage`, restores conversatio
 
 **Add to cart resolution** (never a dead button): the widget first calls your `onAddToCart` option; without one it dispatches a cancelable `brainerce:bot:add-to-cart` `CustomEvent` on `window` (`detail: { productId, variantId, quantity, connectionId }` — call `preventDefault()` after handling it); if nothing handles either, it navigates to the product page. Products too complex for in-chat picking (3+ attribute dimensions or 25+ variants) always navigate. Aside from your own cart handler, the widget is read-only by design — shoppers can never mutate the store through it.
 
+**Where the bot is allowed to load.** Every widget call — bootstrap, chat, escalation — is validated against the page's `Origin` and the domain configured on the connection, the same rule the rest of the storefront API uses. A **Live** connection accepts only its configured domain (exact host or a subdomain) plus any additional allowed origins it lists; a **Test** connection with no domain accepts any origin, which is what makes `localhost` and preview URLs work; a Test connection _with_ a domain behaves like Live. A blocked origin is **not** an error — the bot simply does not render, indistinguishable from "switched off", so nobody can probe which connection ids exist. Mount client-side: server-rendered calls carry no `Origin` and a Live connection refuses them.
+
 Merchant-side display controls (Studio → Storefront Bot): chat size (compact / full screen / shopper's choice), auto-open, position, and whether shoppers may expand the window (`allowExpand`).
 
 ## Webhooks

package/dist/index.d.mts

@@ -626,6 +626,16 @@ interface Product {
     gtin?: string | null;
     /** Manufacturer Part Number. Emitted in Product JSON-LD. */
     mpn?: string | null;
+    /**
+     * Product Q&A pairs (AI-generated from real product data or merchant-
+     * edited). Render as a visible FAQ section on the product page and emit
+     * `buildProductFaqJsonLd(product)` — the extractable question/answer format
+     * AI answer engines cite.
+     */
+    faq?: Array<{
+        q: string;
+        a: string;
+    }> | null;
     /**
      * Base price as string (e.g., "29.99"). Use parseFloat() for calculations.
      *
@@ -1470,6 +1480,16 @@ interface CreateProductDto {
     gtin?: string;
     /** Manufacturer Part Number — used by Google Shopping (with brand) when no GTIN exists. */
     mpn?: string;
+    /**
+     * Your own stable identifier for this product in the SOURCE system (supplier
+     * feed, legacy store, ERP). Unique per store.
+     *
+     * Exists for retry-safety on imports: re-sending a batch after a timeout
+     * matches on this value and skips the product instead of creating a
+     * duplicate. Set it on rows that have no SKU, which would otherwise have
+     * nothing to dedup on.
+     */
+    externalId?: string;
     description?: string;
     basePrice: number;
     salePrice?: number;
@@ -1499,6 +1519,103 @@ interface CreateProductDto {
     /** Unit shared by shippingLengthValue/shippingWidthValue/shippingHeightValue. */
     shippingDimensionUnit?: 'cm' | 'in';
 }
+/**
+ * Payload for `bulkCreateProducts`.
+ *
+ * Each entry in `products` accepts everything `createProduct` accepts. The call
+ * is QUEUED — it returns a job id, not the created products.
+ */
+interface BulkCreateProductsDto {
+    /**
+     * The products to create. At most 1000 per request (500 is the comfortable
+     * size). Split a larger catalog across several calls carrying the same
+     * `importId`.
+     *
+     * Rows are validated INDIVIDUALLY on the server: an invalid row is reported
+     * as a row failure in `getBulkCreateProductsErrors`, it does not reject the
+     * batch. So a supplier file with a few bad rows still imports the good ones.
+     */
+    products: CreateProductDto[];
+    /**
+     * Ties several calls together as ONE logical import, so a 50,000-product
+     * catalog sent as 100 requests is polled once via
+     * `getBulkCreateProductsImportStatus` rather than 100 times.
+     */
+    importId?: string;
+    /**
+     * What to do with a row whose `sku` or `externalId` already exists in the
+     * store. `'skip'` (default) counts it under `skipped`; `'error'` records it
+     * as a failure instead.
+     */
+    conflictStrategy?: 'skip' | 'error';
+    /**
+     * Channel sync behaviour. `'coalesced'` (default) suppresses the per-product
+     * connector push and files one sync per affected sales channel once the
+     * import finishes. `'none'` writes to Brainerce only.
+     */
+    syncMode?: 'coalesced' | 'none';
+    /**
+     * Durable dedup key for this batch. Re-sending the same key returns the
+     * ORIGINAL job id instead of importing again. The `Idempotency-Key` header
+     * does the same thing over HTTP; this field is stored in the database rather
+     * than Redis, so it outlives the header's 24h window.
+     */
+    idempotencyKey?: string;
+}
+/** What `bulkCreateProducts` returns. The import has been accepted, not finished. */
+interface BulkCreateProductsJob {
+    jobId: string;
+    importId: string | null;
+    status: BulkCreateProductsStatus['status'];
+    total: number;
+    /** True when an existing job was returned because the idempotency key matched. */
+    replayed: boolean;
+}
+/**
+ * Progress of a queued product import.
+ *
+ * `skipped` counts rows that already existed and were NOT created — they are
+ * neither successes nor failures, so `succeeded` alone is the number of
+ * products this import added.
+ */
+interface BulkCreateProductsStatus {
+    jobId: string;
+    importId: string | null;
+    /**
+     * `COMPLETED_WITH_ERRORS` means every row was attempted and some failed —
+     * nothing to retry wholesale; read the failures with
+     * `getBulkCreateProductsErrors`. `FAILED` means the job itself died and the
+     * batch can be re-sent.
+     */
+    status: 'QUEUED' | 'RUNNING' | 'COMPLETED' | 'COMPLETED_WITH_ERRORS' | 'FAILED' | 'CANCELLED';
+    total: number;
+    processed: number;
+    succeeded: number;
+    failed: number;
+    skipped: number;
+    /** `total - processed`. */
+    pending: number;
+    conflictStrategy: string;
+    syncMode: string;
+    /** Set only when the JOB failed (infrastructure), never for a row failure. */
+    errorMessage: string | null;
+    startedAt: string | null;
+    /** On an aggregate read, stays null until every chunk has finished. */
+    finishedAt: string | null;
+    createdAt: string;
+    /** Present only on an aggregate (importId) read: how many chunks rolled up. */
+    jobCount?: number;
+}
+/** One failed row from a product import. */
+interface BulkCreateProductsError {
+    /** 1-indexed position in the `products` array you submitted. */
+    row: number;
+    sku: string | null;
+    externalId: string | null;
+    productName: string | null;
+    code: 'VALIDATION' | 'DUPLICATE' | 'PLAN_LIMIT' | 'INTERNAL' | string;
+    message: string;
+}
 interface UpdateProductDto {
     name?: string;
     slug?: string;
@@ -7092,6 +7209,82 @@ declare class BrainerceClient {
      * Create a new product
      */
     createProduct(data: CreateProductDto): Promise<Product>;
+    /**
+     * Create many products in one call.
+     *
+     * QUEUED, not immediate: this returns a job id straight away and the products
+     * appear over the following seconds or minutes. It does NOT return the
+     * created products — poll {@link getBulkCreateProductsStatus} with the
+     * returned `jobId`.
+     *
+     * Every field {@link createProduct} accepts is accepted per row, including
+     * variants, categories, brands, tags, images, translations and tax behaviour.
+     *
+     * At most 1000 products per call (500 is the comfortable size). For a
+     * 3,000-50,000 product catalog, send several calls carrying the same
+     * `importId` and poll {@link getBulkCreateProductsImportStatus} once for the
+     * whole import.
+     *
+     * Retry-safe: a row whose `sku` or `externalId` already exists is skipped
+     * rather than duplicated, so re-sending a batch after a timeout cannot create
+     * the catalog twice. Pass `idempotencyKey` to have an identical re-send
+     * return the original job instead of starting a second import.
+     *
+     * @example
+     * ```typescript
+     * const job = await client.bulkCreateProducts({
+     *   products: rows.map((r) => ({
+     *     name: r.title,
+     *     sku: r.sku,
+     *     externalId: r.supplier_id,
+     *     basePrice: Number(r.price),
+     *     type: 'SIMPLE',
+     *     categoryNames: [r.category],
+     *   })),
+     *   importId: 'supplier-catalog-2026-08-21',
+     * });
+     *
+     * let status = await client.getBulkCreateProductsStatus(job.jobId);
+     * while (status.status === 'QUEUED' || status.status === 'RUNNING') {
+     *   await new Promise((r) => setTimeout(r, 2000));
+     *   status = await client.getBulkCreateProductsStatus(job.jobId);
+     * }
+     * // `succeeded` is what was created; `skipped` already existed.
+     * console.log(status.succeeded, status.skipped, status.failed);
+     * ```
+     */
+    bulkCreateProducts(data: BulkCreateProductsDto): Promise<BulkCreateProductsJob>;
+    /**
+     * Progress of one queued product import.
+     *
+     * Read the counters literally: `skipped` rows already existed and were NOT
+     * created, so `succeeded` alone is what this import added.
+     *
+     * `COMPLETED_WITH_ERRORS` means the import finished with some rows failing —
+     * that is not something to re-run; read the failures with
+     * {@link getBulkCreateProductsErrors}.
+     */
+    getBulkCreateProductsStatus(jobId: string): Promise<BulkCreateProductsStatus>;
+    /**
+     * Aggregate progress across every batch that shared an `importId`.
+     *
+     * The status is the least-complete state across the chunks, and `finishedAt`
+     * stays null until all of them have finished — so a caller cannot mistake
+     * "the first 500 landed" for "the catalog is imported".
+     */
+    getBulkCreateProductsImportStatus(importId: string): Promise<BulkCreateProductsStatus>;
+    /**
+     * Per-row failures for a product import, paginated.
+     *
+     * Every failure is recorded — nothing is truncated — so walk the pages when
+     * `meta.totalPages > 1`. Each entry carries the 1-indexed `row` from the
+     * array you submitted, so a failure maps back to the line of the source
+     * spreadsheet.
+     */
+    getBulkCreateProductsErrors(jobId: string, options?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<BulkCreateProductsError>>;
     /**
      * Update an existing product
      */
@@ -8029,11 +8222,18 @@ declare class BrainerceClient {
      * @param options.redirectUrl - Where to send the browser once OAuth finishes —
      *   on success *and* on failure. Validated server-side against the sales
      *   channel's trusted origins, so what is accepted depends on the mode:
-     *   - vibe-coded (`salesChannelId: 'vc_*'`): an absolute URL on the channel's
-     *     registered `domain` or one of its `allowedOrigins`; in TEST mode, any
-     *     `localhost`/`127.0.0.1` port. A relative path (`/auth/callback`) also
-     *     works — it is resolved against the channel's `domain` on the way back,
-     *     so the channel must have one registered.
+     *   - vibe-coded (`salesChannelId: 'vc_*'`), **LIVE**: an `https` URL on the
+     *     channel's registered `domain`, or on a subdomain of it. Nothing else —
+     *     `allowedOrigins` grants no OAuth redirect on a LIVE channel, and an
+     *     `http://` target is refused even on the registered domain. You
+     *     therefore cannot complete social login from `localhost` against a LIVE
+     *     channel; use a TEST channel for that.
+     *   - vibe-coded, **TEST**: the above, plus an **exact** match (scheme, host
+     *     and port) against one of the channel's `allowedOrigins`, plus any
+     *     `localhost`/`127.0.0.1`/`[::1]` port.
+     *   - Either mode: a relative path (`/auth/callback`) also works — it is
+     *     resolved against the channel's `domain` on the way back, so the channel
+     *     must have one registered.
      *   - storefront (`storeId`): **social login cannot round-trip in this mode.**
      *     No channel is bound to the request, so an absolute URL has no
      *     trusted-origin list to match (400 at this call) and a relative path has
@@ -11839,6 +12039,18 @@ declare function buildWebsiteJsonLd(store: StoreInfo, opts: JsonLdOptions & {
  * {@link buildBreadcrumbJsonLd} built from `category.breadcrumb`.
  */
 declare function buildCollectionPageJsonLd(category: Pick<CategoryDetail, 'name' | 'description' | 'metaDescription' | 'image'>, opts: JsonLdOptions): JsonLd;
+/**
+ * schema.org/FAQPage from a product's Q&A pairs. Returns null when the
+ * product carries no Q&A, so callers can conditionally render the script tag.
+ * Keep the SAME pairs visible as text on the page — engines extract from
+ * rendered HTML; the schema is corroboration, not a substitute.
+ */
+declare function buildProductFaqJsonLd(product: {
+    faq?: Array<{
+        q: string;
+        a: string;
+    }> | null;
+}): JsonLd | null;
 /** schema.org/BreadcrumbList. Items in order from root to current page. */
 declare function buildBreadcrumbJsonLd(items: Array<{
     name: string;
@@ -11941,4 +12153,4 @@ interface CategorySitemapOptions {
  */
 declare function getCategorySitemapEntries(client: BrainerceClient, opts: CategorySitemapOptions): Promise<SitemapEntry[]>;
 
-export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BlogPost, type BlogPostListParams, type BlogPostListResponse, type BlogSitemapOptions, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type BusinessHoursWindow, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryDetail, type CategoryNode, type CategorySitemapOptions, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DateAvailabilityConstraints, type DateFieldParseResult, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type JsonLdOptions, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyStatus, type LoyaltyTierSummary, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldFilter, type MetafieldFilterValue, type MetafieldFiltersResponse, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type MyProductReview, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type ParsedDateFieldValue, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductSitemapOptions, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type StoreTracking, type SubmitProductReviewInput, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type TrackingEventItem, type TrackingEventName, type TrackingEventPayload, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, buildArticleJsonLd, buildBreadcrumbJsonLd, buildCollectionPageJsonLd, buildOrganizationJsonLd, buildProductJsonLd, buildWebsiteJsonLd, computeAvailableSlots, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getBlogSitemapEntries, getBusinessHoursForDate, getCartItemImage, getCartItemName, getCartTotals, getCategorySitemapEntries, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSitemapEntries, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCalendarDateAllowed, isCouponApplicableToProduct, isDateValueAllowed, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseDateFieldValue, parseWebhookEvent, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };
+export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BlogPost, type BlogPostListParams, type BlogPostListResponse, type BlogSitemapOptions, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkCreateProductsDto, type BulkCreateProductsError, type BulkCreateProductsJob, type BulkCreateProductsStatus, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type BusinessHoursWindow, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryDetail, type CategoryNode, type CategorySitemapOptions, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DateAvailabilityConstraints, type DateFieldParseResult, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type JsonLdOptions, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyStatus, type LoyaltyTierSummary, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldFilter, type MetafieldFilterValue, type MetafieldFiltersResponse, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type MyProductReview, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type ParsedDateFieldValue, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductSitemapOptions, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type StoreTracking, type SubmitProductReviewInput, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type TrackingEventItem, type TrackingEventName, type TrackingEventPayload, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, buildArticleJsonLd, buildBreadcrumbJsonLd, buildCollectionPageJsonLd, buildOrganizationJsonLd, buildProductFaqJsonLd, buildProductJsonLd, buildWebsiteJsonLd, computeAvailableSlots, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getBlogSitemapEntries, getBusinessHoursForDate, getCartItemImage, getCartItemName, getCartTotals, getCategorySitemapEntries, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSitemapEntries, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCalendarDateAllowed, isCouponApplicableToProduct, isDateValueAllowed, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseDateFieldValue, parseWebhookEvent, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };

package/dist/index.d.ts

@@ -626,6 +626,16 @@ interface Product {
     gtin?: string | null;
     /** Manufacturer Part Number. Emitted in Product JSON-LD. */
     mpn?: string | null;
+    /**
+     * Product Q&A pairs (AI-generated from real product data or merchant-
+     * edited). Render as a visible FAQ section on the product page and emit
+     * `buildProductFaqJsonLd(product)` — the extractable question/answer format
+     * AI answer engines cite.
+     */
+    faq?: Array<{
+        q: string;
+        a: string;
+    }> | null;
     /**
      * Base price as string (e.g., "29.99"). Use parseFloat() for calculations.
      *
@@ -1470,6 +1480,16 @@ interface CreateProductDto {
     gtin?: string;
     /** Manufacturer Part Number — used by Google Shopping (with brand) when no GTIN exists. */
     mpn?: string;
+    /**
+     * Your own stable identifier for this product in the SOURCE system (supplier
+     * feed, legacy store, ERP). Unique per store.
+     *
+     * Exists for retry-safety on imports: re-sending a batch after a timeout
+     * matches on this value and skips the product instead of creating a
+     * duplicate. Set it on rows that have no SKU, which would otherwise have
+     * nothing to dedup on.
+     */
+    externalId?: string;
     description?: string;
     basePrice: number;
     salePrice?: number;
@@ -1499,6 +1519,103 @@ interface CreateProductDto {
     /** Unit shared by shippingLengthValue/shippingWidthValue/shippingHeightValue. */
     shippingDimensionUnit?: 'cm' | 'in';
 }
+/**
+ * Payload for `bulkCreateProducts`.
+ *
+ * Each entry in `products` accepts everything `createProduct` accepts. The call
+ * is QUEUED — it returns a job id, not the created products.
+ */
+interface BulkCreateProductsDto {
+    /**
+     * The products to create. At most 1000 per request (500 is the comfortable
+     * size). Split a larger catalog across several calls carrying the same
+     * `importId`.
+     *
+     * Rows are validated INDIVIDUALLY on the server: an invalid row is reported
+     * as a row failure in `getBulkCreateProductsErrors`, it does not reject the
+     * batch. So a supplier file with a few bad rows still imports the good ones.
+     */
+    products: CreateProductDto[];
+    /**
+     * Ties several calls together as ONE logical import, so a 50,000-product
+     * catalog sent as 100 requests is polled once via
+     * `getBulkCreateProductsImportStatus` rather than 100 times.
+     */
+    importId?: string;
+    /**
+     * What to do with a row whose `sku` or `externalId` already exists in the
+     * store. `'skip'` (default) counts it under `skipped`; `'error'` records it
+     * as a failure instead.
+     */
+    conflictStrategy?: 'skip' | 'error';
+    /**
+     * Channel sync behaviour. `'coalesced'` (default) suppresses the per-product
+     * connector push and files one sync per affected sales channel once the
+     * import finishes. `'none'` writes to Brainerce only.
+     */
+    syncMode?: 'coalesced' | 'none';
+    /**
+     * Durable dedup key for this batch. Re-sending the same key returns the
+     * ORIGINAL job id instead of importing again. The `Idempotency-Key` header
+     * does the same thing over HTTP; this field is stored in the database rather
+     * than Redis, so it outlives the header's 24h window.
+     */
+    idempotencyKey?: string;
+}
+/** What `bulkCreateProducts` returns. The import has been accepted, not finished. */
+interface BulkCreateProductsJob {
+    jobId: string;
+    importId: string | null;
+    status: BulkCreateProductsStatus['status'];
+    total: number;
+    /** True when an existing job was returned because the idempotency key matched. */
+    replayed: boolean;
+}
+/**
+ * Progress of a queued product import.
+ *
+ * `skipped` counts rows that already existed and were NOT created — they are
+ * neither successes nor failures, so `succeeded` alone is the number of
+ * products this import added.
+ */
+interface BulkCreateProductsStatus {
+    jobId: string;
+    importId: string | null;
+    /**
+     * `COMPLETED_WITH_ERRORS` means every row was attempted and some failed —
+     * nothing to retry wholesale; read the failures with
+     * `getBulkCreateProductsErrors`. `FAILED` means the job itself died and the
+     * batch can be re-sent.
+     */
+    status: 'QUEUED' | 'RUNNING' | 'COMPLETED' | 'COMPLETED_WITH_ERRORS' | 'FAILED' | 'CANCELLED';
+    total: number;
+    processed: number;
+    succeeded: number;
+    failed: number;
+    skipped: number;
+    /** `total - processed`. */
+    pending: number;
+    conflictStrategy: string;
+    syncMode: string;
+    /** Set only when the JOB failed (infrastructure), never for a row failure. */
+    errorMessage: string | null;
+    startedAt: string | null;
+    /** On an aggregate read, stays null until every chunk has finished. */
+    finishedAt: string | null;
+    createdAt: string;
+    /** Present only on an aggregate (importId) read: how many chunks rolled up. */
+    jobCount?: number;
+}
+/** One failed row from a product import. */
+interface BulkCreateProductsError {
+    /** 1-indexed position in the `products` array you submitted. */
+    row: number;
+    sku: string | null;
+    externalId: string | null;
+    productName: string | null;
+    code: 'VALIDATION' | 'DUPLICATE' | 'PLAN_LIMIT' | 'INTERNAL' | string;
+    message: string;
+}
 interface UpdateProductDto {
     name?: string;
     slug?: string;
@@ -7092,6 +7209,82 @@ declare class BrainerceClient {
      * Create a new product
      */
     createProduct(data: CreateProductDto): Promise<Product>;
+    /**
+     * Create many products in one call.
+     *
+     * QUEUED, not immediate: this returns a job id straight away and the products
+     * appear over the following seconds or minutes. It does NOT return the
+     * created products — poll {@link getBulkCreateProductsStatus} with the
+     * returned `jobId`.
+     *
+     * Every field {@link createProduct} accepts is accepted per row, including
+     * variants, categories, brands, tags, images, translations and tax behaviour.
+     *
+     * At most 1000 products per call (500 is the comfortable size). For a
+     * 3,000-50,000 product catalog, send several calls carrying the same
+     * `importId` and poll {@link getBulkCreateProductsImportStatus} once for the
+     * whole import.
+     *
+     * Retry-safe: a row whose `sku` or `externalId` already exists is skipped
+     * rather than duplicated, so re-sending a batch after a timeout cannot create
+     * the catalog twice. Pass `idempotencyKey` to have an identical re-send
+     * return the original job instead of starting a second import.
+     *
+     * @example
+     * ```typescript
+     * const job = await client.bulkCreateProducts({
+     *   products: rows.map((r) => ({
+     *     name: r.title,
+     *     sku: r.sku,
+     *     externalId: r.supplier_id,
+     *     basePrice: Number(r.price),
+     *     type: 'SIMPLE',
+     *     categoryNames: [r.category],
+     *   })),
+     *   importId: 'supplier-catalog-2026-08-21',
+     * });
+     *
+     * let status = await client.getBulkCreateProductsStatus(job.jobId);
+     * while (status.status === 'QUEUED' || status.status === 'RUNNING') {
+     *   await new Promise((r) => setTimeout(r, 2000));
+     *   status = await client.getBulkCreateProductsStatus(job.jobId);
+     * }
+     * // `succeeded` is what was created; `skipped` already existed.
+     * console.log(status.succeeded, status.skipped, status.failed);
+     * ```
+     */
+    bulkCreateProducts(data: BulkCreateProductsDto): Promise<BulkCreateProductsJob>;
+    /**
+     * Progress of one queued product import.
+     *
+     * Read the counters literally: `skipped` rows already existed and were NOT
+     * created, so `succeeded` alone is what this import added.
+     *
+     * `COMPLETED_WITH_ERRORS` means the import finished with some rows failing —
+     * that is not something to re-run; read the failures with
+     * {@link getBulkCreateProductsErrors}.
+     */
+    getBulkCreateProductsStatus(jobId: string): Promise<BulkCreateProductsStatus>;
+    /**
+     * Aggregate progress across every batch that shared an `importId`.
+     *
+     * The status is the least-complete state across the chunks, and `finishedAt`
+     * stays null until all of them have finished — so a caller cannot mistake
+     * "the first 500 landed" for "the catalog is imported".
+     */
+    getBulkCreateProductsImportStatus(importId: string): Promise<BulkCreateProductsStatus>;
+    /**
+     * Per-row failures for a product import, paginated.
+     *
+     * Every failure is recorded — nothing is truncated — so walk the pages when
+     * `meta.totalPages > 1`. Each entry carries the 1-indexed `row` from the
+     * array you submitted, so a failure maps back to the line of the source
+     * spreadsheet.
+     */
+    getBulkCreateProductsErrors(jobId: string, options?: {
+        page?: number;
+        limit?: number;
+    }): Promise<PaginatedResponse<BulkCreateProductsError>>;
     /**
      * Update an existing product
      */
@@ -8029,11 +8222,18 @@ declare class BrainerceClient {
      * @param options.redirectUrl - Where to send the browser once OAuth finishes —
      *   on success *and* on failure. Validated server-side against the sales
      *   channel's trusted origins, so what is accepted depends on the mode:
-     *   - vibe-coded (`salesChannelId: 'vc_*'`): an absolute URL on the channel's
-     *     registered `domain` or one of its `allowedOrigins`; in TEST mode, any
-     *     `localhost`/`127.0.0.1` port. A relative path (`/auth/callback`) also
-     *     works — it is resolved against the channel's `domain` on the way back,
-     *     so the channel must have one registered.
+     *   - vibe-coded (`salesChannelId: 'vc_*'`), **LIVE**: an `https` URL on the
+     *     channel's registered `domain`, or on a subdomain of it. Nothing else —
+     *     `allowedOrigins` grants no OAuth redirect on a LIVE channel, and an
+     *     `http://` target is refused even on the registered domain. You
+     *     therefore cannot complete social login from `localhost` against a LIVE
+     *     channel; use a TEST channel for that.
+     *   - vibe-coded, **TEST**: the above, plus an **exact** match (scheme, host
+     *     and port) against one of the channel's `allowedOrigins`, plus any
+     *     `localhost`/`127.0.0.1`/`[::1]` port.
+     *   - Either mode: a relative path (`/auth/callback`) also works — it is
+     *     resolved against the channel's `domain` on the way back, so the channel
+     *     must have one registered.
      *   - storefront (`storeId`): **social login cannot round-trip in this mode.**
      *     No channel is bound to the request, so an absolute URL has no
      *     trusted-origin list to match (400 at this call) and a relative path has
@@ -11839,6 +12039,18 @@ declare function buildWebsiteJsonLd(store: StoreInfo, opts: JsonLdOptions & {
  * {@link buildBreadcrumbJsonLd} built from `category.breadcrumb`.
  */
 declare function buildCollectionPageJsonLd(category: Pick<CategoryDetail, 'name' | 'description' | 'metaDescription' | 'image'>, opts: JsonLdOptions): JsonLd;
+/**
+ * schema.org/FAQPage from a product's Q&A pairs. Returns null when the
+ * product carries no Q&A, so callers can conditionally render the script tag.
+ * Keep the SAME pairs visible as text on the page — engines extract from
+ * rendered HTML; the schema is corroboration, not a substitute.
+ */
+declare function buildProductFaqJsonLd(product: {
+    faq?: Array<{
+        q: string;
+        a: string;
+    }> | null;
+}): JsonLd | null;
 /** schema.org/BreadcrumbList. Items in order from root to current page. */
 declare function buildBreadcrumbJsonLd(items: Array<{
     name: string;
@@ -11941,4 +12153,4 @@ interface CategorySitemapOptions {
  */
 declare function getCategorySitemapEntries(client: BrainerceClient, opts: CategorySitemapOptions): Promise<SitemapEntry[]>;
 
-export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BlogPost, type BlogPostListParams, type BlogPostListResponse, type BlogSitemapOptions, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type BusinessHoursWindow, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryDetail, type CategoryNode, type CategorySitemapOptions, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DateAvailabilityConstraints, type DateFieldParseResult, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type JsonLdOptions, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyStatus, type LoyaltyTierSummary, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldFilter, type MetafieldFilterValue, type MetafieldFiltersResponse, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type MyProductReview, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type ParsedDateFieldValue, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductSitemapOptions, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type StoreTracking, type SubmitProductReviewInput, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type TrackingEventItem, type TrackingEventName, type TrackingEventPayload, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, buildArticleJsonLd, buildBreadcrumbJsonLd, buildCollectionPageJsonLd, buildOrganizationJsonLd, buildProductJsonLd, buildWebsiteJsonLd, computeAvailableSlots, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getBlogSitemapEntries, getBusinessHoursForDate, getCartItemImage, getCartItemName, getCartTotals, getCategorySitemapEntries, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSitemapEntries, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCalendarDateAllowed, isCouponApplicableToProduct, isDateValueAllowed, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseDateFieldValue, parseWebhookEvent, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };
+export { type AddToCartDto, type AddressDetailsResult, type AddressSuggestion, type AnnouncementContent, type AnnouncementSeverity, type AppliedDiscount, type ApplyCouponDto, type AttachModifierGroupInput, type Attribute, type AttributeOption, type AttributeSource, type BlogPost, type BlogPostListParams, type BlogPostListResponse, type BlogSitemapOptions, type BrainerceApiError, BrainerceClient, type BrainerceClientOptions, BrainerceError, type Brand, type BulkCreateProductsDto, type BulkCreateProductsError, type BulkCreateProductsJob, type BulkCreateProductsStatus, type BulkInventoryResponse, type BulkSaveVariantsDto, type BulkSaveVariantsResponse, type BulkVariantInput, type BusinessHoursWindow, type Cart, type CartAppliedDiscount, type CartBundleOffer, type CartBundlesResponse, type CartIncludeOption, type CartIncludeOptions, type CartItem, type CartItemModifierLine, type CartNudge, type CartRecommendationsResponse, type CartStatus, type CartUpgradeSuggestion, type CartUpgradesResponse, type CartWithIncludes, type Category, type CategoryDetail, type CategoryNode, type CategorySitemapOptions, type CategorySuggestion, type Checkout, type CheckoutAddress, type CheckoutBumpsResponse, type CheckoutCustomFieldDefinition, type CheckoutFieldPricing, type CheckoutFieldVisibility, type CheckoutLineItem, type CheckoutPrefillData, type CheckoutStatus, type CompleteCheckoutResponse, type CompleteDraftDto, type ConfigureOAuthProviderDto as ConfigureOAuthProviderInput, type ConflictStatus, type ConnectorPlatform, type ContactFormFieldType, type ContactFormFieldValidation, type ContactFormPublic, type ContactFormPublicField, type ContactFormSummary, type Content, type ContentDataMap, type ContentStatus, type ContentSummary, type ContentType, type Coupon, type CouponCreateResponse, type CouponQueryParams, type CouponStatus, type CouponType, type CouponValidationWarning, type CreateAddressDto, type CreateAttributeDto as CreateAttributeInput, type CreateAttributeOptionDto as CreateAttributeOptionInput, type CreateBrandDto as CreateBrandInput, type CreateCategoryDto as CreateCategoryInput, type CreateCheckoutDto, type CreateContentInput, type CreateCouponDto, type CreateCustomApiDto, type CreateCustomerDto, type CreateEmailTemplateDto as CreateEmailTemplateInput, type CreateGuestOrderDto, type CreateInquiryInput, type CreateInquiryResponse, type CreateMetafieldDefinitionDto as CreateMetafieldDefinitionInput, type CreateModifierGroupInput, type CreateModifierInput, type CreateOrderDto, type CreateProductDto, type CreateRefundDto, type CreateShippingRateDto as CreateShippingRateInput, type CreateShippingZoneDto as CreateShippingZoneInput, type CreateTagDto as CreateTagInput, type CreateTaxRateDto as CreateTaxRateInput, type CreateVariantDto, type CustomApiAuthType, type CustomApiConnectionStatus, type CustomApiCredentials, type CustomApiIntegration, type CustomApiSyncConfig, type CustomApiSyncDirection, type CustomApiTestResult, type Customer, type CustomerAddress, type CustomerAuthResponse, type CustomerOAuthProvider, type CustomerProfile, type CustomerQueryParams, type DateAvailabilityConstraints, type DateFieldParseResult, type DeleteProductResponse, type DiscountBanner, type DiscountRuleType, type DownloadFile, type DraftLineItem, type EditInventoryDto, type EmailDomain, type EmailEventSettings, type EmailEventType, type EmailSettings, type EmailTemplate, type EmailTemplatePreview, type EmailTemplatesResponse, type EmailVerificationResponse, type ExtendReservationResponse, type FaqContent, type FaqItem, type FooterColumn, type FooterContent, type FooterLink, type FooterSocialLink, type FormatPriceOptions, type FormatProductPriceOptions, type FreeAllocationPolicy, type FulfillOrderDto, type GuestCheckoutStartResponse, type GuestOrderResponse, type HeaderContent, type HeaderCta, type HeaderLogo, type HeaderNavItem, type InsufficientStockError, type InventoryInfo, type InventoryReservationStrategy, type InventorySyncStatus, type InventoryTrackingMode, type InvitationStatus, type InviteMemberDto as InviteMemberInput, type InviteStoreMemberDto as InviteStoreMemberInput, type JsonLdOptions, type ListModifierGroupsParams, type LocalCart, type LocalCartItem, type LockedVariant, type LoyaltyNextTierSummary, type LoyaltyReward, type LoyaltyStatus, type LoyaltyTierSummary, type MergeCartsDto, type MetafieldConflict, type MetafieldConflictResolution, type MetafieldDefinition, type MetafieldFilter, type MetafieldFilterValue, type MetafieldFiltersResponse, type MetafieldType, type Modifier, type ModifierGroup, type ModifierSelection, type ModifierSelectionType, type ModifierValidationCode, type ModifierValidationError, type MyProductReview, type OAuthAuthorizeResponse, type OAuthCallbackResponse, type OAuthConnection, type OAuthConnectionsResponse, type OAuthProviderConfig, type OAuthProviderType, type OAuthProvidersResponse, type Order, type OrderAddress, type OrderBump, type OrderCustomer, type OrderDownloadLink, type OrderItem, type OrderQueryParams, type OrderStatus, type OrderStatusChange, type PageContent, type PageSeo, type PaginatedResponse, type ParsedDateFieldValue, type PaymentClientSdk, type PaymentConfig, type PaymentIntent, type PaymentProvider, type PaymentProviderConfig, type PaymentProvidersConfig, type PaymentStatus, type PaymentUrlOptions, type PickupLocation, type PlatformCouponCapabilities, type PlatformMetafieldMetadata, type PreviewEmailTemplateDto as PreviewEmailTemplateInput, type Product, type ProductAttributeInput, type ProductAvailability, type ProductCustomizationField, type ProductDiscount, type ProductDiscountBadge, type ProductImage, type ProductMetafield, type ProductMetafieldValue, type ProductModifierGroupAttachment, type ProductQueryParams, type ProductRecommendation, type ProductRecommendationsResponse, type ProductRelationType, type ProductReview, type ProductReviewAdmin, type ProductSitemapOptions, type ProductSuggestion, type ProductVariant, type PublicMetafieldDefinition, type PublishProductResponse, RTL_LOCALES, type RecommendationVariant, type ReconcileInventoryResponse, type RedeemRewardResult, type ReferralInfo, type Refund, type RefundLineItem, type RefundLineItemResponse, type RefundType, type RegisterCustomerDto, type ReservationInfo, type ResolveMetafieldConflictDto as ResolveMetafieldConflictInput, type ResolveSyncConflictDto as ResolveSyncConflictInput, type RichTextContent, SDK_VERSION, type SearchSuggestions, type SelectPickupLocationDto, type SelectShippingMethodDto, type SendInvoiceDto, type SessionCartRef, type SetBillingAddressDto, type SetCheckoutCustomFieldsDto, type SetCheckoutCustomerDto, type SetDefinitionProductsDto as SetDefinitionProductsInput, type SetMetafieldPlatformsDto as SetMetafieldPlatformsInput, type SetShippingAddressDto, type SetShippingAddressResponse, type ShippingDestinations, type ShippingLine, type ShippingRate, type ShippingRateConfig, type ShippingRateType, type ShippingSummaryEntry, type ShippingZone, type ShippingZoneQueryParams, type SitemapEntry, type StockAvailabilityRequest, type StockAvailabilityResponse, type StockAvailabilityResult, type StoreInfo, type StoreInvitation, type StoreInvitationDetails, type StoreMember, type StorePermission, type StoreRole, type StoreTeamResponse, type StoreTracking, type SubmitProductReviewInput, type SupportedLocaleObject, type SyncConflict, type SyncConflictResolution, type SyncJob, type Tag, type TaxBreakdown, type TaxBreakdownItem, type TaxRate, type TaxonomyQueryParams, type TeamInvitation, type TeamInvitationsResponse, type TeamMember, type TeamMembersResponse, type TeamRole, type TrackingEventItem, type TrackingEventName, type TrackingEventPayload, type UpdateAddressDto, type UpdateAttachmentInput, type UpdateAttributeDto as UpdateAttributeInput, type UpdateAttributeOptionDto as UpdateAttributeOptionInput, type UpdateBrandDto as UpdateBrandInput, type UpdateCartItemDto, type UpdateCategoryDto as UpdateCategoryInput, type UpdateContentInput, type UpdateCouponDto, type UpdateCustomApiDto, type UpdateCustomerDto, type UpdateDraftDto, type UpdateEmailSettingsDto as UpdateEmailSettingsInput, type UpdateEmailTemplateDto as UpdateEmailTemplateInput, type UpdateInventoryDto, type UpdateMemberRoleDto as UpdateMemberRoleInput, type UpdateMetafieldDefinitionDto as UpdateMetafieldDefinitionInput, type UpdateModifierGroupInput, type UpdateModifierInput, type UpdateOAuthProviderDto as UpdateOAuthProviderInput, type UpdateOrderDto, type UpdateOrderShippingDto, type UpdateProductDto, type UpdateShippingRateDto as UpdateShippingRateInput, type UpdateShippingZoneDto as UpdateShippingZoneInput, type UpdateStoreMemberDto as UpdateStoreMemberInput, type UpdateTagDto as UpdateTagInput, type UpdateTaxRateDto as UpdateTaxRateInput, type UpdateVariantDto, type UpdateVariantInventoryDto, type UpsertProductMetafieldDto as UpsertProductMetafieldInput, type UserStore, type UserStorePermissions, type VariantInventoryResponse, type VariantPlatformOverlay, type VariantStatus, type WaitForOrderOptions, type WaitForOrderResult, type WebhookEvent, type WebhookEventType, type WriteProductReviewInput, buildArticleJsonLd, buildBreadcrumbJsonLd, buildCollectionPageJsonLd, buildOrganizationJsonLd, buildProductFaqJsonLd, buildProductJsonLd, buildWebsiteJsonLd, computeAvailableSlots, createWebhookHandler, deriveSeoDescription, enableDevGuards, formatMoney, formatPrice, formatProductPrice, formatVariantPrice, getBlogSitemapEntries, getBusinessHoursForDate, getCartItemImage, getCartItemName, getCartTotals, getCategorySitemapEntries, getDescriptionContent, getDirectionForLocale, formatPrice as getPriceDisplay, getProductCustomizationFields, getProductMetafield, getProductMetafieldValue, getProductMetafieldsByType, getProductPrice, getProductPriceInfo, getProductSitemapEntries, getProductSwatches, getStockStatus, getVariantOptions, getVariantPrice, isAllowedPaymentUrl, isCalendarDateAllowed, isCouponApplicableToProduct, isDateValueAllowed, isHtmlDescription, isWebhookEventType, jsonLdScriptProps, parseDateFieldValue, parseWebhookEvent, resolveStoreLocalParts, safePaymentRedirect, stripHtml, validateDateAvailabilityConfig, verifyWebhook };

package/dist/index.js

@@ -38,6 +38,7 @@ __export(index_exports, {
   buildBreadcrumbJsonLd: () => buildBreadcrumbJsonLd,
   buildCollectionPageJsonLd: () => buildCollectionPageJsonLd,
   buildOrganizationJsonLd: () => buildOrganizationJsonLd,
+  buildProductFaqJsonLd: () => buildProductFaqJsonLd,
   buildProductJsonLd: () => buildProductJsonLd,
   buildWebsiteJsonLd: () => buildWebsiteJsonLd,
   computeAvailableSlots: () => computeAvailableSlots,
@@ -1998,6 +1999,98 @@ var _BrainerceClient = class _BrainerceClient {
   async createProduct(data) {
     return this.request("POST", "/api/v1/products", data);
   }
+  /**
+   * Create many products in one call.
+   *
+   * QUEUED, not immediate: this returns a job id straight away and the products
+   * appear over the following seconds or minutes. It does NOT return the
+   * created products — poll {@link getBulkCreateProductsStatus} with the
+   * returned `jobId`.
+   *
+   * Every field {@link createProduct} accepts is accepted per row, including
+   * variants, categories, brands, tags, images, translations and tax behaviour.
+   *
+   * At most 1000 products per call (500 is the comfortable size). For a
+   * 3,000-50,000 product catalog, send several calls carrying the same
+   * `importId` and poll {@link getBulkCreateProductsImportStatus} once for the
+   * whole import.
+   *
+   * Retry-safe: a row whose `sku` or `externalId` already exists is skipped
+   * rather than duplicated, so re-sending a batch after a timeout cannot create
+   * the catalog twice. Pass `idempotencyKey` to have an identical re-send
+   * return the original job instead of starting a second import.
+   *
+   * @example
+   * ```typescript
+   * const job = await client.bulkCreateProducts({
+   *   products: rows.map((r) => ({
+   *     name: r.title,
+   *     sku: r.sku,
+   *     externalId: r.supplier_id,
+   *     basePrice: Number(r.price),
+   *     type: 'SIMPLE',
+   *     categoryNames: [r.category],
+   *   })),
+   *   importId: 'supplier-catalog-2026-08-21',
+   * });
+   *
+   * let status = await client.getBulkCreateProductsStatus(job.jobId);
+   * while (status.status === 'QUEUED' || status.status === 'RUNNING') {
+   *   await new Promise((r) => setTimeout(r, 2000));
+   *   status = await client.getBulkCreateProductsStatus(job.jobId);
+   * }
+   * // `succeeded` is what was created; `skipped` already existed.
+   * console.log(status.succeeded, status.skipped, status.failed);
+   * ```
+   */
+  async bulkCreateProducts(data) {
+    return this.request("POST", "/api/v1/products/bulk", data);
+  }
+  /**
+   * Progress of one queued product import.
+   *
+   * Read the counters literally: `skipped` rows already existed and were NOT
+   * created, so `succeeded` alone is what this import added.
+   *
+   * `COMPLETED_WITH_ERRORS` means the import finished with some rows failing —
+   * that is not something to re-run; read the failures with
+   * {@link getBulkCreateProductsErrors}.
+   */
+  async getBulkCreateProductsStatus(jobId) {
+    return this.request(
+      "GET",
+      `/api/v1/products/bulk/${encodePathSegment(jobId)}`
+    );
+  }
+  /**
+   * Aggregate progress across every batch that shared an `importId`.
+   *
+   * The status is the least-complete state across the chunks, and `finishedAt`
+   * stays null until all of them have finished — so a caller cannot mistake
+   * "the first 500 landed" for "the catalog is imported".
+   */
+  async getBulkCreateProductsImportStatus(importId) {
+    return this.request(
+      "GET",
+      `/api/v1/products/bulk/import/${encodePathSegment(importId)}`
+    );
+  }
+  /**
+   * Per-row failures for a product import, paginated.
+   *
+   * Every failure is recorded — nothing is truncated — so walk the pages when
+   * `meta.totalPages > 1`. Each entry carries the 1-indexed `row` from the
+   * array you submitted, so a failure maps back to the line of the source
+   * spreadsheet.
+   */
+  async getBulkCreateProductsErrors(jobId, options) {
+    return this.request(
+      "GET",
+      `/api/v1/products/bulk/${encodePathSegment(jobId)}/errors`,
+      void 0,
+      { page: options?.page, limit: options?.limit }
+    );
+  }
   /**
    * Update an existing product
    */
@@ -3264,11 +3357,18 @@ var _BrainerceClient = class _BrainerceClient {
    * @param options.redirectUrl - Where to send the browser once OAuth finishes —
    *   on success *and* on failure. Validated server-side against the sales
    *   channel's trusted origins, so what is accepted depends on the mode:
-   *   - vibe-coded (`salesChannelId: 'vc_*'`): an absolute URL on the channel's
-   *     registered `domain` or one of its `allowedOrigins`; in TEST mode, any
-   *     `localhost`/`127.0.0.1` port. A relative path (`/auth/callback`) also
-   *     works — it is resolved against the channel's `domain` on the way back,
-   *     so the channel must have one registered.
+   *   - vibe-coded (`salesChannelId: 'vc_*'`), **LIVE**: an `https` URL on the
+   *     channel's registered `domain`, or on a subdomain of it. Nothing else —
+   *     `allowedOrigins` grants no OAuth redirect on a LIVE channel, and an
+   *     `http://` target is refused even on the registered domain. You
+   *     therefore cannot complete social login from `localhost` against a LIVE
+   *     channel; use a TEST channel for that.
+   *   - vibe-coded, **TEST**: the above, plus an **exact** match (scheme, host
+   *     and port) against one of the channel's `allowedOrigins`, plus any
+   *     `localhost`/`127.0.0.1`/`[::1]` port.
+   *   - Either mode: a relative path (`/auth/callback`) also works — it is
+   *     resolved against the channel's `domain` on the way back, so the channel
+   *     must have one registered.
    *   - storefront (`storeId`): **social login cannot round-trip in this mode.**
    *     No channel is bound to the request, so an absolute URL has no
    *     trusted-origin list to match (400 at this call) and a relative path has
@@ -10424,6 +10524,21 @@ function buildCollectionPageJsonLd(category, opts) {
     ...category.image ? { image: [category.image] } : {}
   };
 }
+function buildProductFaqJsonLd(product) {
+  const pairs = (product.faq ?? []).filter(
+    (i) => typeof i?.q === "string" && typeof i?.a === "string" && i.q && i.a
+  );
+  if (pairs.length === 0) return null;
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: pairs.map((i) => ({
+      "@type": "Question",
+      name: i.q,
+      acceptedAnswer: { "@type": "Answer", text: i.a }
+    }))
+  };
+}
 function buildBreadcrumbJsonLd(items) {
   return {
     "@context": "https://schema.org",
@@ -10814,6 +10929,7 @@ function isCouponApplicableToProduct(coupon, productId) {
   buildBreadcrumbJsonLd,
   buildCollectionPageJsonLd,
   buildOrganizationJsonLd,
+  buildProductFaqJsonLd,
   buildProductJsonLd,
   buildWebsiteJsonLd,
   computeAvailableSlots,

package/dist/index.mjs

@@ -1911,6 +1911,98 @@ var _BrainerceClient = class _BrainerceClient {
   async createProduct(data) {
     return this.request("POST", "/api/v1/products", data);
   }
+  /**
+   * Create many products in one call.
+   *
+   * QUEUED, not immediate: this returns a job id straight away and the products
+   * appear over the following seconds or minutes. It does NOT return the
+   * created products — poll {@link getBulkCreateProductsStatus} with the
+   * returned `jobId`.
+   *
+   * Every field {@link createProduct} accepts is accepted per row, including
+   * variants, categories, brands, tags, images, translations and tax behaviour.
+   *
+   * At most 1000 products per call (500 is the comfortable size). For a
+   * 3,000-50,000 product catalog, send several calls carrying the same
+   * `importId` and poll {@link getBulkCreateProductsImportStatus} once for the
+   * whole import.
+   *
+   * Retry-safe: a row whose `sku` or `externalId` already exists is skipped
+   * rather than duplicated, so re-sending a batch after a timeout cannot create
+   * the catalog twice. Pass `idempotencyKey` to have an identical re-send
+   * return the original job instead of starting a second import.
+   *
+   * @example
+   * ```typescript
+   * const job = await client.bulkCreateProducts({
+   *   products: rows.map((r) => ({
+   *     name: r.title,
+   *     sku: r.sku,
+   *     externalId: r.supplier_id,
+   *     basePrice: Number(r.price),
+   *     type: 'SIMPLE',
+   *     categoryNames: [r.category],
+   *   })),
+   *   importId: 'supplier-catalog-2026-08-21',
+   * });
+   *
+   * let status = await client.getBulkCreateProductsStatus(job.jobId);
+   * while (status.status === 'QUEUED' || status.status === 'RUNNING') {
+   *   await new Promise((r) => setTimeout(r, 2000));
+   *   status = await client.getBulkCreateProductsStatus(job.jobId);
+   * }
+   * // `succeeded` is what was created; `skipped` already existed.
+   * console.log(status.succeeded, status.skipped, status.failed);
+   * ```
+   */
+  async bulkCreateProducts(data) {
+    return this.request("POST", "/api/v1/products/bulk", data);
+  }
+  /**
+   * Progress of one queued product import.
+   *
+   * Read the counters literally: `skipped` rows already existed and were NOT
+   * created, so `succeeded` alone is what this import added.
+   *
+   * `COMPLETED_WITH_ERRORS` means the import finished with some rows failing —
+   * that is not something to re-run; read the failures with
+   * {@link getBulkCreateProductsErrors}.
+   */
+  async getBulkCreateProductsStatus(jobId) {
+    return this.request(
+      "GET",
+      `/api/v1/products/bulk/${encodePathSegment(jobId)}`
+    );
+  }
+  /**
+   * Aggregate progress across every batch that shared an `importId`.
+   *
+   * The status is the least-complete state across the chunks, and `finishedAt`
+   * stays null until all of them have finished — so a caller cannot mistake
+   * "the first 500 landed" for "the catalog is imported".
+   */
+  async getBulkCreateProductsImportStatus(importId) {
+    return this.request(
+      "GET",
+      `/api/v1/products/bulk/import/${encodePathSegment(importId)}`
+    );
+  }
+  /**
+   * Per-row failures for a product import, paginated.
+   *
+   * Every failure is recorded — nothing is truncated — so walk the pages when
+   * `meta.totalPages > 1`. Each entry carries the 1-indexed `row` from the
+   * array you submitted, so a failure maps back to the line of the source
+   * spreadsheet.
+   */
+  async getBulkCreateProductsErrors(jobId, options) {
+    return this.request(
+      "GET",
+      `/api/v1/products/bulk/${encodePathSegment(jobId)}/errors`,
+      void 0,
+      { page: options?.page, limit: options?.limit }
+    );
+  }
   /**
    * Update an existing product
    */
@@ -3177,11 +3269,18 @@ var _BrainerceClient = class _BrainerceClient {
    * @param options.redirectUrl - Where to send the browser once OAuth finishes —
    *   on success *and* on failure. Validated server-side against the sales
    *   channel's trusted origins, so what is accepted depends on the mode:
-   *   - vibe-coded (`salesChannelId: 'vc_*'`): an absolute URL on the channel's
-   *     registered `domain` or one of its `allowedOrigins`; in TEST mode, any
-   *     `localhost`/`127.0.0.1` port. A relative path (`/auth/callback`) also
-   *     works — it is resolved against the channel's `domain` on the way back,
-   *     so the channel must have one registered.
+   *   - vibe-coded (`salesChannelId: 'vc_*'`), **LIVE**: an `https` URL on the
+   *     channel's registered `domain`, or on a subdomain of it. Nothing else —
+   *     `allowedOrigins` grants no OAuth redirect on a LIVE channel, and an
+   *     `http://` target is refused even on the registered domain. You
+   *     therefore cannot complete social login from `localhost` against a LIVE
+   *     channel; use a TEST channel for that.
+   *   - vibe-coded, **TEST**: the above, plus an **exact** match (scheme, host
+   *     and port) against one of the channel's `allowedOrigins`, plus any
+   *     `localhost`/`127.0.0.1`/`[::1]` port.
+   *   - Either mode: a relative path (`/auth/callback`) also works — it is
+   *     resolved against the channel's `domain` on the way back, so the channel
+   *     must have one registered.
    *   - storefront (`storeId`): **social login cannot round-trip in this mode.**
    *     No channel is bound to the request, so an absolute URL has no
    *     trusted-origin list to match (400 at this call) and a relative path has
@@ -10337,6 +10436,21 @@ function buildCollectionPageJsonLd(category, opts) {
     ...category.image ? { image: [category.image] } : {}
   };
 }
+function buildProductFaqJsonLd(product) {
+  const pairs = (product.faq ?? []).filter(
+    (i) => typeof i?.q === "string" && typeof i?.a === "string" && i.q && i.a
+  );
+  if (pairs.length === 0) return null;
+  return {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    mainEntity: pairs.map((i) => ({
+      "@type": "Question",
+      name: i.q,
+      acceptedAnswer: { "@type": "Answer", text: i.a }
+    }))
+  };
+}
 function buildBreadcrumbJsonLd(items) {
   return {
     "@context": "https://schema.org",
@@ -10726,6 +10840,7 @@ export {
   buildBreadcrumbJsonLd,
   buildCollectionPageJsonLd,
   buildOrganizationJsonLd,
+  buildProductFaqJsonLd,
   buildProductJsonLd,
   buildWebsiteJsonLd,
   computeAvailableSlots,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brainerce",
-  "version": "1.57.0",
+  "version": "1.58.1",
   "description": "Official SDK for building e-commerce storefronts with Brainerce Platform. Perfect for vibe-coded sites, AI-built stores (Cursor, Lovable, v0), and custom storefronts.",
   "main": "dist/index.js",
   "module": "dist/index.mjs",