brainerce 1.27.0 → 1.28.0

package/README.md

@@ -93,7 +93,7 @@ Violating any of these causes production incidents or broken orders. Read them b
 
 - Customer auth tokens (`result.token` from `loginCustomer`/`registerCustomer`) should be passed to `client.setCustomerToken(token)`. The SDK stores session state internally.
 - NEVER put the admin API key (`brainerce_*`) in client code. It is a server-only secret.
-- OAuth callbacks arrive with the token in URL params. Extract and apply the token before redirecting.
+- OAuth callbacks arrive with a one-time `auth_code` URL param. Call `client.exchangeOAuthCode(authCode)` to swap it for the JWT and apply via `setCustomerToken`. (The legacy `?token=` URL param is still emitted for backward compatibility but will be removed in the next major release.)
 
 ### i18n
 
@@ -205,11 +205,16 @@ These sequences are non-negotiable. The order of SDK calls matters.
    });
    window.location.href = authorizationUrl; // full-page redirect, NOT a popup
    ```
-3. On callback, the URL contains `token` + `oauth_success` (or `oauth_error`) query params:
+3. On callback, the URL contains `auth_code` + `oauth_success` (or `oauth_error`) query params. Exchange the single-use code for the JWT:
    ```ts
-   const token = new URLSearchParams(location.search).get('token');
-   if (token) client.setCustomerToken(token); // then redirect to account
+   const params = new URLSearchParams(location.search);
+   const code = params.get('auth_code');
+   if (code) {
+     const result = await client.exchangeOAuthCode(code);
+     client.setCustomerToken(result.token); // then redirect to account
+   }
    ```
+   The legacy `?token=` URL param is still emitted for backward compatibility but will be removed in the next major release — migrate to `auth_code` now.
 4. On `oauth_error` query param: redirect to login with an error message.
 
 > Build the OAuth button region AND the callback handler even when no providers are configured.
@@ -1936,6 +1941,11 @@ console.log(cart.discountAmount); // Discount applied
 console.log(cart.couponCode); // 'SAVE20'
 ```
 
+> **Region-restricted coupons:** a coupon may be limited to specific regions via
+> its `regionIds`. If the buyer's checkout region isn't in that list, redemption is
+> rejected even when the code is otherwise valid. An empty/omitted `regionIds`
+> applies in all regions. See [`/docs/concepts/region-coupons`](/docs/concepts/region-coupons).
+
 #### Remove Coupon
 
 ```typescript
@@ -1994,6 +2004,52 @@ const checkout = await client.createCheckout({
 });
 ```
 
+#### Multi-Region Checkout
+
+If your store uses [regions](#regions), pass a `regionId` to associate the
+checkout with one (the region must belong to the store). Resolve the buyer's
+country to a region client-side with `detectRegion`:
+
+```typescript
+const { data: regions } = await client.getRegions(); // or a storefront region list
+const region = client.detectRegion(buyerCountry, regions);
+
+const checkout = await client.createCheckout({
+  cartId: cart.id,
+  regionId: region?.id, // omit to associate no region
+});
+```
+
+> The region is recorded on the checkout and used for payment-provider scoping.
+> Currency continues to follow the cart until FX price conversion lands, so
+> passing a `regionId` does not re-price the cart.
+
+#### Region display pricing (`getProducts({ regionId })`)
+
+Product reads accept an optional `regionId`. When set, each product/variant that
+a region [price list](#price-lists) resolves gains additive fields —
+`resolvedPrice`, `resolvedCurrency`, `resolvedCompareAtPrice`, and `priceSource`
+(`'variant-entry'` | `'product-entry'`). Your existing `basePrice` / `salePrice`
+stay in the store currency; the fields appear **only** when a region entry
+actually applies, so an omitted/invalid region (or a catalog-price fallback)
+leaves the response byte-identical.
+
+```typescript
+const { data: products } = await client.getProducts({ regionId: 'region_eu' });
+const p = products[0];
+const display = p.resolvedPrice
+  ? `${p.resolvedPrice} ${p.resolvedCurrency}` // e.g. "27.00 EUR"
+  : p.basePrice; // store-currency catalog price
+
+// Single product (id or slug) takes the same option:
+await client.getProduct('prod_tshirt', { regionId: 'region_eu' });
+```
+
+> **Display-only** — like checkout, `regionId` here does not charge the region
+> price; it only changes what you render until currency-lock ships. **Mode note:**
+> region resolution applies on storefront (`storeId`) and admin (`apiKey`) reads;
+> it is currently ignored in vibe-coded (`vc_*`/`salesChannelId`) mode.
+
 #### Partial Checkout (AliExpress-style)
 
 Allow customers to select which items to checkout from their cart. Only selected items are purchased - remaining items stay in the cart for later.
@@ -3394,6 +3450,14 @@ const zone = await client.createShippingZone({
   countries: ['US'],
 });
 
+// Restrict a zone to specific regions (PRD §25). Empty/omitted = any region;
+// a non-empty list hides the zone unless the checkout resolved to one of them.
+const euZone = await client.createShippingZone({
+  name: 'EU Express',
+  countries: ['DE', 'FR', 'IT'],
+  regionIds: ['reg_eu'],
+});
+
 // Shipping Rates
 const rates = await client.getZoneShippingRates('zone_id');
 await client.createZoneShippingRate('zone_id', {
@@ -3406,14 +3470,168 @@ await client.createZoneShippingRate('zone_id', {
 
 ### Tax Configuration
 
+`rate` is a **whole percentage** (`7.25` = 7.25%, not `0.0725`). A rate may target
+a [tax class](#tax-classes) via `taxClassId`; a rate with `taxClassId: null` (the
+default) is the **Standard fallback** applied to any line whose class has no
+class-specific rate.
+
 ```typescript
 const rates = await client.getTaxRates();
+
+// Standard rate (applies to everything without a class-specific rate)
 await client.createTaxRate({
   name: 'CA Sales Tax',
   rate: 7.25,
   country: 'US',
   region: 'CA',
 });
+
+// Class-specific rate — only lines assigned to this tax class use it.
+// Create the class in the dashboard (Settings → Tax) to get its id.
+await client.createTaxRate({
+  name: 'CA Reduced (Food)',
+  rate: 0,
+  country: 'US',
+  region: 'CA',
+  taxClassId: 'taxclass_food_id',
+});
+```
+
+### Tax Classes
+
+Tax classes let you charge different rates for different product types (e.g.
+Standard / Reduced / Zero-rated / Food). Assign a class to a product, variant, or
+category; checkout resolves each line's class **variant → product → category →
+store default → null** and picks the matching `TaxRate`, falling back to the
+Standard (null-class) rate. See [`/docs/concepts/tax-classes`](/docs/concepts/tax-classes)
+for the full resolution order. `storeId` is derived from the API key. Requires
+the `tax-classes:read` / `tax-classes:write` scopes.
+
+```typescript
+// List / inspect
+const { data: classes } = await client.getTaxClasses();
+const detail = await client.getTaxClass('taxclass_id');
+detail.dependents; // { productCount, variantCount, categoryCount, taxRateCount }
+
+// Create (slug is kebab-case, unique per store)
+const food = await client.createTaxClass({
+  name: 'Food',
+  slug: 'food',
+  description: 'Zero / reduced-rate groceries',
+});
+
+await client.updateTaxClass(food.id, { description: 'Reduced VAT' });
+await client.setDefaultTaxClass(food.id); // the class auto-applied to unclassified products
+
+// Bulk-assign a class to products / variants / categories
+const { updated } = await client.assignTaxClass(food.id, {
+  productIds: ['prod_1', 'prod_2'],
+  categoryIds: ['cat_groceries'],
+});
+
+// Merge moves every product/variant/category/rate FK onto the target, then
+// deletes this class. Delete is blocked (409) while dependents exist — merge first.
+await client.mergeTaxClasses(food.id, 'taxclass_standard_id');
+await client.deleteTaxClass(food.id);
+```
+
+**Storefront (public, no API key).** A storefront lists classes in `storeId`
+mode — storefront-safe fields only (for a "9% VAT" transparency badge):
+
+```typescript
+const store = new BrainerceClient({ storeId: 'store_123' });
+const { data: classes } = await store.getStoreTaxClasses();
+```
+
+### Regions
+
+A **region** binds a set of countries to a currency, a tax-display mode
+(`taxInclusive`), and the payment providers enabled there. `storeId` is derived
+from the API key. Requires the `regions:read` / `regions:write` scopes. See
+[`/docs/concepts/regions`](/docs/concepts/regions).
+
+```typescript
+// List / inspect
+const { data: regions } = await client.getRegions();
+const region = await client.getRegion('region_id');
+
+// Create — paymentProviderIds are AppInstallation IDs to enable in this region
+const eu = await client.createRegion({
+  name: 'European Union',
+  currency: 'EUR',
+  countries: ['DE', 'FR', 'IT', 'ES'],
+  taxInclusive: true,
+  paymentProviderIds: ['app_inst_stripe'],
+});
+
+await client.updateRegion(eu.id, { isActive: true });
+await client.setDefaultRegion(eu.id);
+
+// Manage the country set
+await client.addRegionCountries(eu.id, ['NL', 'BE']);
+await client.removeRegionCountry(eu.id, 'BE');
+
+// Manage payment providers (replaces the full set)
+await client.updateRegionPaymentProviders(eu.id, ['app_inst_stripe', 'app_inst_paypal']);
+
+// Which installed providers can serve this region's countries?
+const compatible = await client.getRegionCompatibleProviders(eu.id);
+
+// Pure client-side helper (no network) — pick a region for a country code
+const dest = client.detectRegion('DE', regions); // → the EU region, or the default, or null
+
+await client.deleteRegion(eu.id);
+```
+
+**Storefront (public, no API key).** A storefront fetches regions in `storeId`
+mode — only active regions, only storefront-safe fields:
+
+```typescript
+const store = new BrainerceClient({ storeId: 'store_123' });
+
+const { data: regions } = await store.getStoreRegions();
+const region = await store.getStoreRegion(regions[0].id); // + paymentProviders
+const dest = store.detectRegion('DE', regions); // pick by country, client-side
+```
+
+> **Multi-region checkout:** pass a `regionId` to `createCheckout` to associate the
+> checkout with a region (for reporting + payment-provider scoping). The region
+> must belong to the store. Currency still follows the cart until FX price
+> conversion lands. See the Checkout section.
+
+### Price Lists (per-region pricing)
+
+Each region has a **price list** — entries that override a product's or variant's
+catalog price for buyers in that region. Requires `price-lists:read` /
+`price-lists:write`. Prices are in the region's currency.
+
+> ⚠️ **Data-entry only for now.** Region prices are **not yet applied at checkout** —
+> charging a region-currency price through the store-currency cart needs FX
+> conversion (a later phase). These methods let you populate the price book ahead of
+> activation; until then checkout uses the catalog price.
+
+```typescript
+// One entry per product OR variant (variant wins). price > 0; compareAtPrice optional.
+const res = await client.upsertPriceListEntries('region_eu', [
+  { productId: 'prod_tshirt', price: 27, compareAtPrice: 32 },
+  { variantId: 'var_tshirt_l', price: 29 },
+]);
+res.upserted; // 2
+res.warnings; // e.g. ["PL-004: compareAtPrice not greater than price …"] (non-blocking)
+
+// Inspect
+const meta = await client.getPriceList('region_eu'); // { currency, entryCount, … }
+const { data: entries } = await client.listPriceListEntries('region_eu', {
+  productId: 'prod_tshirt',
+});
+
+// Bulk CSV (columns: productSku,variantSku?,price,compareAtPrice?). Unknown SKUs /
+// bad prices are skipped + reported, not fatal.
+const imported = await client.importPrices('region_eu', csvString);
+imported.skipped; // ['row 4: product SKU "NOPE" not found', …]
+const csv = await client.exportPrices('region_eu'); // round-trips with importPrices
+
+await client.deletePriceListEntry('region_eu', 'entry_id'); // line falls back to catalog
 ```
 
 ### Metafield Definitions
@@ -3495,6 +3713,7 @@ const { members, invitations } = await client.getStoreTeam('store_id');
 const invitation = await client.inviteStoreMember('store_id', {
   email: 'newmember@example.com',
   role: 'MANAGER', // 'MANAGER' | 'STAFF' | 'VIEWER'
+  salesChannelIds: ['vc_abc123'], // optional: restrict to vibe-coded channels (connectionId); omit/[] = all channels
 });
 
 // Update member role or set custom permissions
@@ -3503,6 +3722,11 @@ await client.updateStoreMember('store_id', 'member_id', {
   permissions: ['VIEW_PRODUCTS', 'VIEW_ORDERS', 'FULFILL_ORDERS'], // overrides role defaults
 });
 
+// Replace a member's vibe-coded sales-channel scope ([] clears all restrictions)
+await client.updateStoreMemberSalesChannels('store_id', 'member_id', {
+  salesChannelIds: ['vc_abc123', 'vc_def456'],
+});
+
 // Remove a member
 await client.removeStoreMember('store_id', 'member_id');