@sixtyninecommerce/client 0.24.0 → 0.26.0

package/dist/next/redirect-middleware.js

@@ -1,4 +1,17 @@
+/**
+ * Middleware factory that applies the tenant's platform-managed redirects.
+ *
+ * Zero `next` imports by design: it takes a `Request` and returns a plain
+ * `Response`, which is exactly what a Next.js middleware may return. It never
+ * throws — an unmatched path, a cold cache or an unreachable platform all
+ * resolve to `undefined`, meaning "carry on with normal routing".
+ */
 import { createRedirectStore } from '../redirects/store.js';
+/**
+ * Build the destination URL against the request origin, so a stored path
+ * redirects on the storefront's own host and an absolute `https://` target
+ * leaves it.
+ */
 function resolveTarget(to, request, preserveQuery) {
     const requestUrl = new URL(request.url);
     const target = new URL(to, requestUrl.origin);
@@ -11,6 +24,25 @@ function resolveTarget(to, request, preserveQuery) {
     }
     return target.toString();
 }
+/**
+ * Usage (App Router):
+ * ```ts
+ * // src/middleware.ts
+ * import { createRedirectMiddleware } from '@sixtyninecommerce/client/next';
+ *
+ * const redirects = createRedirectMiddleware({
+ *   storeCode: process.env.STORE_CODE!,
+ *   pluginsUrl: process.env.PLUGINS_URL,
+ *   onError: (error) => console.error('[redirects]', error),
+ * });
+ *
+ * export async function middleware(request: Request) {
+ *   return (await redirects(request)) ?? undefined;
+ * }
+ *
+ * export const config = { matcher: ['/((?!_next|api|.*\\..*).*)'] };
+ * ```
+ */
 export function createRedirectMiddleware(options) {
     const preserveQuery = options.preserveQuery ?? true;
     const store = 'store' in options ? options.store : createRedirectStore(options);

package/dist/next/redirect-middleware.js.map

@@ -1 +1 @@
-{"version":3,"file":"redirect-middleware.js","sourceRoot":"","sources":["../../src/next/redirect-middleware.ts"],"names":[],"mappings":"AASA,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AA6B5D,SAAS,aAAa,CAAC,EAAU,EAAE,OAAgB,EAAE,aAAsB;IACzE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,EAAE,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE9C,IAAI,aAAa,EAAE,CAAC;QAClB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,UAAU,CAAC,YAAY,EAAE,CAAC;YACnD,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClC,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAqBD,MAAM,UAAU,wBAAwB,CACtC,OAAsF;IAEtF,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC;IACpD,MAAM,KAAK,GACT,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,mBAAmB,CAAC,OAA8B,CAAC,CAAC;IAE3F,MAAM,UAAU,GAAG,KAAK,EAAE,OAAgB,EAAiC,EAAE;QAC3E,IAAI,QAAgB,CAAC;QACrB,IAAI,CAAC;YACH,QAAQ,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;YACxB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,OAAO,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE;SACvE,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,CAAuB,CAAC;AACpE,CAAC"}
+{"version":3,"file":"redirect-middleware.js","sourceRoot":"","sources":["../../src/next/redirect-middleware.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAwB5D;;;;GAIG;AACH,SAAS,aAAa,CAAC,EAAU,EAAE,OAAgB,EAAE,aAAsB;IACzE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,EAAE,EAAE,UAAU,CAAC,MAAM,CAAC,CAAC;IAE9C,IAAI,aAAa,EAAE,CAAC;QAClB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,UAAU,CAAC,YAAY,EAAE,CAAC;YACnD,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;gBAClC,MAAM,CAAC,YAAY,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC,QAAQ,EAAE,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAsF;IAEtF,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC;IACpD,MAAM,KAAK,GACT,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,mBAAmB,CAAC,OAA8B,CAAC,CAAC;IAE3F,MAAM,UAAU,GAAG,KAAK,EAAE,OAAgB,EAAiC,EAAE;QAC3E,IAAI,QAAgB,CAAC;QACrB,IAAI,CAAC;YACH,QAAQ,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC1C,IAAI,CAAC,KAAK;YAAE,OAAO,SAAS,CAAC;QAE7B,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE;YACxB,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,OAAO,EAAE,EAAE,QAAQ,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE;SACvE,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,OAAO,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,EAAE,KAAK,EAAE,CAAuB,CAAC;AACpE,CAAC"}

package/dist/next/revalidate-handler.d.ts

@@ -1,10 +1,40 @@
+/**
+ * Route-handler factory for the storefront's /api/revalidate endpoint.
+ * Framework functions (`revalidatePath`/`revalidateTag` from `next/cache`)
+ * are INJECTED so this package never imports `next`; the handler itself uses
+ * only web-standard Request/Response and is unit-testable anywhere.
+ *
+ * Requires ISR-capable hosting (the default Next server build) — under
+ * `output: 'export'` there is nothing to revalidate at request time.
+ *
+ * It speaks only the legacy SEO revalidation webhook, which the platform no
+ * longer sends (its sender is retired) — a route mounted with it receives
+ * nothing. A platform event envelope is refused here with a 400 (no `paths`),
+ * so point an event subscription at `createEventRevalidateHandler` instead,
+ * on its own route.
+ */
 import type { RevalidateWebhookPayload } from '../revalidation/types.js';
+/**
+ * @deprecated Options of the legacy SEO webhook handler — use
+ * `EventRevalidateHandlerOptions` with `createEventRevalidateHandler`.
+ */
 export interface RevalidateHandlerOptions {
+    /** The shared secret the legacy webhook was signed with. Server-only env. */
     secret: string;
+    /** Pass `revalidatePath` from 'next/cache'. */
     revalidatePath(path: string, type?: 'page' | 'layout'): void;
+    /** Pass `revalidateTag` from 'next/cache' (optional — tags are skipped without it). */
     revalidateTag?(tag: string): void;
+    /** Reject deliveries whose occurred_at is older/newer than this. Default 300s. */
     toleranceSeconds?: number;
+    /** Observe accepted deliveries (logging, metrics). Errors are swallowed. */
     onEvent?(payload: RevalidateWebhookPayload): void | Promise<void>;
 }
+/**
+ * @deprecated The legacy SEO revalidation webhook, which the platform no longer
+ * sends. Kept, unchanged, so existing `/api/revalidate` routes still compile.
+ * Storefronts subscribe to platform events and mount
+ * `createEventRevalidateHandler` at `/api/revalidate/events`.
+ */
 export declare function createRevalidateHandler(options: RevalidateHandlerOptions): (request: Request) => Promise<Response>;
 //# sourceMappingURL=revalidate-handler.d.ts.map

package/dist/next/revalidate-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"revalidate-handler.d.ts","sourceRoot":"","sources":["../../src/next/revalidate-handler.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AASzE,MAAM,WAAW,wBAAwB;IAEvC,MAAM,EAAE,MAAM,CAAC;IAEf,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IAE7D,aAAa,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAElC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAE1B,OAAO,CAAC,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE;AAeD,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,GAChC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAiEzC"}
+{"version":3,"file":"revalidate-handler.d.ts","sourceRoot":"","sources":["../../src/next/revalidate-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,0BAA0B,CAAC;AAKzE;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,6EAA6E;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAAC;IAC7D,uFAAuF;IACvF,aAAa,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,kFAAkF;IAClF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,4EAA4E;IAC5E,OAAO,CAAC,CAAC,OAAO,EAAE,wBAAwB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnE;AASD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,GAChC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAiEzC"}

package/dist/next/revalidate-handler.js

@@ -1,3 +1,18 @@
+/**
+ * Route-handler factory for the storefront's /api/revalidate endpoint.
+ * Framework functions (`revalidatePath`/`revalidateTag` from `next/cache`)
+ * are INJECTED so this package never imports `next`; the handler itself uses
+ * only web-standard Request/Response and is unit-testable anywhere.
+ *
+ * Requires ISR-capable hosting (the default Next server build) — under
+ * `output: 'export'` there is nothing to revalidate at request time.
+ *
+ * It speaks only the legacy SEO revalidation webhook, which the platform no
+ * longer sends (its sender is retired) — a route mounted with it receives
+ * nothing. A platform event envelope is refused here with a 400 (no `paths`),
+ * so point an event subscription at `createEventRevalidateHandler` instead,
+ * on its own route.
+ */
 import { verifyWebhookSignature } from '../revalidation/verify.js';
 const DEFAULT_TOLERANCE_SECONDS = 300;
 function json(status, body) {
@@ -6,6 +21,12 @@ function json(status, body) {
         headers: { 'Content-Type': 'application/json' },
     });
 }
+/**
+ * @deprecated The legacy SEO revalidation webhook, which the platform no longer
+ * sends. Kept, unchanged, so existing `/api/revalidate` routes still compile.
+ * Storefronts subscribe to platform events and mount
+ * `createEventRevalidateHandler` at `/api/revalidate/events`.
+ */
 export function createRevalidateHandler(options) {
     const tolerance = (options.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS) * 1000;
     return async (request) => {
@@ -56,6 +77,7 @@ export function createRevalidateHandler(options) {
                     await options.onEvent(payload);
                 }
                 catch {
+                    // observer errors must not fail the delivery
                 }
             }
             return json(200, { revalidated: true, paths, tags });

package/dist/next/revalidate-handler.js.map

@@ -1 +1 @@
-{"version":3,"file":"revalidate-handler.js","sourceRoot":"","sources":["../../src/next/revalidate-handler.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"revalidate-handler.js","sourceRoot":"","sources":["../../src/next/revalidate-handler.ts"],"names":[],"mappings":"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"}

package/dist/order-scope.d.ts

@@ -1,3 +1,30 @@
 import type { OrderScope } from './types.js';
+/**
+ * Does an order belong to `scope`?
+ *
+ * THE CASE DIFFERS ON PURPOSE, and this helper is the one place that has to
+ * know. The wire and storage value is lower-case (`'consumer'` / `'trade'`) —
+ * it is a Vendure `string` custom field with a `varchar(16)` column and a
+ * `'consumer'` default — while the client-side {@link OrderScope} union and the
+ * `OrderScope` GraphQL enum are upper-case, because that is what a GraphQL enum
+ * looks like. So the obvious comparison,
+ *
+ *   order.customFields.orderScope === client.getOrderScope()   // never true
+ *
+ * silently never matches, and a storefront filtering its own order list on it
+ * shows an empty page with no error anywhere.
+ *
+ * Two rules, both mirroring the engine (`scopeOf` in
+ * `services/vendure/src/order-scope/order-scope.ts`):
+ *
+ *  - the comparison is case-insensitive;
+ *  - an ABSENT, null or unrecognised value reads as `CONSUMER`. Every order
+ *    placed before the scope existed has no value, and the engine treats those
+ *    as consumer orders — so must a storefront, or a consumer shop's history
+ *    page loses everything the customer bought before the feature shipped.
+ *
+ * @example
+ * const mine = orders.filter((o) => orderScopeMatches(o.customFields?.orderScope, 'TRADE'));
+ */
 export declare function orderScopeMatches(customFieldValue: string | null | undefined, scope: OrderScope | string): boolean;
 //# sourceMappingURL=order-scope.d.ts.map

package/dist/order-scope.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"order-scope.d.ts","sourceRoot":"","sources":["../src/order-scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AA6B7C,wBAAgB,iBAAiB,CAC/B,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC3C,KAAK,EAAE,UAAU,GAAG,MAAM,GACzB,OAAO,CAOT"}
+{"version":3,"file":"order-scope.d.ts","sourceRoot":"","sources":["../src/order-scope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,iBAAiB,CAC/B,gBAAgB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAC3C,KAAK,EAAE,UAAU,GAAG,MAAM,GACzB,OAAO,CAOT"}

package/dist/order-scope.js

@@ -1,6 +1,35 @@
+/**
+ * Does an order belong to `scope`?
+ *
+ * THE CASE DIFFERS ON PURPOSE, and this helper is the one place that has to
+ * know. The wire and storage value is lower-case (`'consumer'` / `'trade'`) —
+ * it is a Vendure `string` custom field with a `varchar(16)` column and a
+ * `'consumer'` default — while the client-side {@link OrderScope} union and the
+ * `OrderScope` GraphQL enum are upper-case, because that is what a GraphQL enum
+ * looks like. So the obvious comparison,
+ *
+ *   order.customFields.orderScope === client.getOrderScope()   // never true
+ *
+ * silently never matches, and a storefront filtering its own order list on it
+ * shows an empty page with no error anywhere.
+ *
+ * Two rules, both mirroring the engine (`scopeOf` in
+ * `services/vendure/src/order-scope/order-scope.ts`):
+ *
+ *  - the comparison is case-insensitive;
+ *  - an ABSENT, null or unrecognised value reads as `CONSUMER`. Every order
+ *    placed before the scope existed has no value, and the engine treats those
+ *    as consumer orders — so must a storefront, or a consumer shop's history
+ *    page loses everything the customer bought before the feature shipped.
+ *
+ * @example
+ * const mine = orders.filter((o) => orderScopeMatches(o.customFields?.orderScope, 'TRADE'));
+ */
 export function orderScopeMatches(customFieldValue, scope) {
     const normalized = typeof customFieldValue === 'string' ? customFieldValue.trim().toUpperCase() : '';
     const effective = normalized === 'CONSUMER' || normalized === 'TRADE' ? normalized : 'CONSUMER';
+    // Both sides are normalised: a JS caller passing 'trade' must match — the helper
+    // exists to absorb exactly this casing split, on either argument.
     return effective === String(scope).trim().toUpperCase();
 }
 //# sourceMappingURL=order-scope.js.map

package/dist/order-scope.js.map

@@ -1 +1 @@
-{"version":3,"file":"order-scope.js","sourceRoot":"","sources":["../src/order-scope.ts"],"names":[],"mappings":"AA6BA,MAAM,UAAU,iBAAiB,CAC/B,gBAA2C,EAC3C,KAA0B;IAE1B,MAAM,UAAU,GACd,OAAO,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACpF,MAAM,SAAS,GAAG,UAAU,KAAK,UAAU,IAAI,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC;IAGhG,OAAO,SAAS,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"order-scope.js","sourceRoot":"","sources":["../src/order-scope.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,iBAAiB,CAC/B,gBAA2C,EAC3C,KAA0B;IAE1B,MAAM,UAAU,GACd,OAAO,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACpF,MAAM,SAAS,GAAG,UAAU,KAAK,UAAU,IAAI,UAAU,KAAK,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC;IAChG,iFAAiF;IACjF,kEAAkE;IAClE,OAAO,SAAS,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AAC1D,CAAC"}

package/dist/pricing/format.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Format a price in minor units to a human-readable string.
+ * Uses Intl.NumberFormat for locale-aware formatting.
+ *
+ * The platform stores money in a currency's minor units, so the divisor is
+ * `10 ** fractionDigits`, NOT a hardcoded 100: EUR/USD have 2 digits (÷100),
+ * JPY 0 (÷1 — `2999` is ¥2,999, not ¥30), BHD 3 (÷1000). The digit count comes
+ * from the same Intl formatter, so it always matches how the value is rendered.
+ *
+ * Vendure `LanguageCode` region variants use underscores (`pt_BR`, `zh_Hans`),
+ * which are not valid BCP-47 separators and make `Intl.NumberFormat` throw —
+ * normalize to hyphens so a channel default language can be passed straight in.
+ */
 export declare function formatPrice(amount: number, currencyCode: string, locale?: string): string;
+/**
+ * Format a price range from two minor-unit amounts.
+ * Returns "€10.00 - €20.00" or the single price if min === max.
+ */
 export declare function formatPriceRange(min: number, max: number, currencyCode: string, locale?: string): string;
 //# sourceMappingURL=format.d.ts.map

package/dist/pricing/format.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/pricing/format.ts"],"names":[],"mappings":"AAaA,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CASzF;AAMD,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAKR"}
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/pricing/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CASzF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAKR"}

package/dist/pricing/format.js

@@ -1,11 +1,30 @@
+/**
+ * Format a price in minor units to a human-readable string.
+ * Uses Intl.NumberFormat for locale-aware formatting.
+ *
+ * The platform stores money in a currency's minor units, so the divisor is
+ * `10 ** fractionDigits`, NOT a hardcoded 100: EUR/USD have 2 digits (÷100),
+ * JPY 0 (÷1 — `2999` is ¥2,999, not ¥30), BHD 3 (÷1000). The digit count comes
+ * from the same Intl formatter, so it always matches how the value is rendered.
+ *
+ * Vendure `LanguageCode` region variants use underscores (`pt_BR`, `zh_Hans`),
+ * which are not valid BCP-47 separators and make `Intl.NumberFormat` throw —
+ * normalize to hyphens so a channel default language can be passed straight in.
+ */
 export function formatPrice(amount, currencyCode, locale) {
     const format = new Intl.NumberFormat((locale ?? 'en').replace(/_/g, '-'), {
         style: 'currency',
         currency: currencyCode,
     });
+    // `currency` style always resolves a digit count; `?? 2` is a defensive
+    // fallback for the base type only (`maximumFractionDigits` is `number | undefined`).
     const fractionDigits = format.resolvedOptions().maximumFractionDigits ?? 2;
     return format.format(amount / 10 ** fractionDigits);
 }
+/**
+ * Format a price range from two minor-unit amounts.
+ * Returns "€10.00 - €20.00" or the single price if min === max.
+ */
 export function formatPriceRange(min, max, currencyCode, locale) {
     if (min === max) {
         return formatPrice(min, currencyCode, locale);

package/dist/pricing/format.js.map

@@ -1 +1 @@
-{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/pricing/format.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,YAAoB,EAAE,MAAe;IAC/E,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE;QACxE,KAAK,EAAE,UAAU;QACjB,QAAQ,EAAE,YAAY;KACvB,CAAC,CAAC;IAGH,MAAM,cAAc,GAAG,MAAM,CAAC,eAAe,EAAE,CAAC,qBAAqB,IAAI,CAAC,CAAC;IAC3E,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,EAAE,IAAI,cAAc,CAAC,CAAC;AACtD,CAAC;AAMD,MAAM,UAAU,gBAAgB,CAC9B,GAAW,EACX,GAAW,EACX,YAAoB,EACpB,MAAe;IAEf,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;QAChB,OAAO,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,CAAC;AACjG,CAAC"}
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/pricing/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,YAAoB,EAAE,MAAe;IAC/E,MAAM,MAAM,GAAG,IAAI,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE;QACxE,KAAK,EAAE,UAAU;QACjB,QAAQ,EAAE,YAAY;KACvB,CAAC,CAAC;IACH,wEAAwE;IACxE,qFAAqF;IACrF,MAAM,cAAc,GAAG,MAAM,CAAC,eAAe,EAAE,CAAC,qBAAqB,IAAI,CAAC,CAAC;IAC3E,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,GAAG,EAAE,IAAI,cAAc,CAAC,CAAC;AACtD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAC9B,GAAW,EACX,GAAW,EACX,YAAoB,EACpB,MAAe;IAEf,IAAI,GAAG,KAAK,GAAG,EAAE,CAAC;QAChB,OAAO,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,GAAG,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,CAAC,MAAM,WAAW,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,CAAC,EAAE,CAAC;AACjG,CAAC"}

package/dist/pricing/index.d.ts

@@ -3,6 +3,13 @@ import type { PricingModule, StoreContext } from '../types.js';
 export { formatPrice, formatPriceRange } from './format.js';
 export { ACTIVE_TAX_DISPLAY_MODE, DEFAULT_TAX_DISPLAY_POLICY, identityStamp, parseTaxDisplayPolicy, parseTaxExclusiveCountries, resolveTaxDisplayMode, taxDisplayModeFromEnum, } from './tax-display.js';
 export { computeTierTable, getTierForQuantity } from './tiers.js';
-export { validateOrderMinimums } from './validation.js';
+export { backorderedQuantityForCart, isBackorderOnly, maxOrderableQuantity, type OrderableStockInput, validateOrderMinimums, } from './validation.js';
+/**
+ * @param http Optional Shop API client. Without it the module is fully offline
+ *   (formatting, tier maths, the pure policy helpers) and
+ *   `getTaxDisplayMode()` degrades to the channel storage mode rather than
+ *   failing — which is what the `@sixtyninecommerce/client/pricing` subpath and
+ *   the existing single-argument callers get.
+ */
 export declare function createPricingModule(ctx: StoreContext, http?: HttpClient): PricingModule;
 //# sourceMappingURL=index.d.ts.map

package/dist/pricing/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pricing/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAEV,aAAa,EACb,YAAY,EAGb,MAAM,aAAa,CAAC;AAYrB,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,aAAa,EACb,qBAAqB,EACrB,0BAA0B,EAC1B,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AASxD,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,aAAa,CA2GvF"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pricing/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAClD,OAAO,KAAK,EAEV,aAAa,EACb,YAAY,EAGb,MAAM,aAAa,CAAC;AAiBrB,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,aAAa,EACb,qBAAqB,EACrB,0BAA0B,EAC1B,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,EACL,0BAA0B,EAC1B,eAAe,EACf,oBAAoB,EACpB,KAAK,mBAAmB,EACxB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,aAAa,CA8GvF"}

package/dist/pricing/index.js

@@ -1,13 +1,22 @@
 import { formatPrice, formatPriceRange } from './format.js';
 import { ACTIVE_TAX_DISPLAY_MODE, identityStamp, parseTaxDisplayPolicy, resolveTaxDisplayMode, taxDisplayModeFromEnum, } from './tax-display.js';
 import { computeTierTable, getTierForQuantity } from './tiers.js';
-import { validateOrderMinimums } from './validation.js';
+import { backorderedQuantityForCart, isBackorderOnly, maxOrderableQuantity, validateOrderMinimums, } from './validation.js';
 export { formatPrice, formatPriceRange } from './format.js';
 export { ACTIVE_TAX_DISPLAY_MODE, DEFAULT_TAX_DISPLAY_POLICY, identityStamp, parseTaxDisplayPolicy, parseTaxExclusiveCountries, resolveTaxDisplayMode, taxDisplayModeFromEnum, } from './tax-display.js';
 export { computeTierTable, getTierForQuantity } from './tiers.js';
-export { validateOrderMinimums } from './validation.js';
+export { backorderedQuantityForCart, isBackorderOnly, maxOrderableQuantity, validateOrderMinimums, } from './validation.js';
+/**
+ * @param http Optional Shop API client. Without it the module is fully offline
+ *   (formatting, tier maths, the pure policy helpers) and
+ *   `getTaxDisplayMode()` degrades to the channel storage mode rather than
+ *   failing — which is what the `@sixtyninecommerce/client/pricing` subpath and
+ *   the existing single-argument callers get.
+ */
 export function createPricingModule(ctx, http) {
+    /** The pre-policy behaviour: display in whatever basis the channel stores. */
     const storageMode = () => (ctx.pricesIncludeTax ? 'gross' : 'net');
+    /** The cached mode, but only while it belongs to the current identity. */
     const cachedMode = () => {
         const cached = ctx.taxDisplay;
         return cached && cached.stamp === identityStamp(ctx) ? cached.mode : null;
@@ -28,10 +37,14 @@ export function createPricingModule(ctx, http) {
                 mode = taxDisplayModeFromEnum(data?.activeTaxDisplayMode);
             }
             catch {
+                // Unreachable engine, an expired session, an engine predating the
+                // query — never fail a render over the display mode.
                 mode = null;
             }
             if (mode === null)
                 return storageMode();
+            // Stamp AFTER the round-trip: the response may have rotated the session
+            // token, and the answer belongs to the identity that now holds.
             ctx.taxDisplay = { stamp: identityStamp(ctx), mode };
             return mode;
         },
@@ -85,6 +98,9 @@ export function createPricingModule(ctx, http) {
             };
         },
         validateOrderMinimums,
+        maxOrderableQuantity,
+        isBackorderOnly,
+        backorderedQuantityForCart,
     };
 }
 //# sourceMappingURL=index.js.map

package/dist/pricing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/pricing/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,uBAAuB,EACvB,aAAa,EACb,qBAAqB,EACrB,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AAExD,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,aAAa,EACb,qBAAqB,EACrB,0BAA0B,EAC1B,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iBAAiB,CAAC;AASxD,MAAM,UAAU,mBAAmB,CAAC,GAAiB,EAAE,IAAiB;IAEtE,MAAM,WAAW,GAAG,GAAmB,EAAE,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAGnF,MAAM,UAAU,GAAG,GAA0B,EAAE;QAC7C,MAAM,MAAM,GAAG,GAAG,CAAC,UAAU,CAAC;QAC9B,OAAO,MAAM,IAAI,MAAM,CAAC,KAAK,KAAK,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5E,CAAC,CAAC;IAEF,OAAO;QACL,gBAAgB,EAAE,GAAG,CAAC,gBAAgB;QAEtC,KAAK,CAAC,iBAAiB,CAAC,OAA+B;YACrD,IAAI,OAAO,EAAE,OAAO,KAAK,IAAI,EAAE,CAAC;gBAC9B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;gBAC5B,IAAI,MAAM,KAAK,IAAI;oBAAE,OAAO,MAAM,CAAC;YACrC,CAAC;YACD,IAAI,CAAC,IAAI;gBAAE,OAAO,WAAW,EAAE,CAAC;YAEhC,IAAI,IAAI,GAA0B,IAAI,CAAC;YACvC,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC,OAAO,CAC7B,uBAAuB,CACxB,CAAC;gBACF,IAAI,GAAG,sBAAsB,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;YAC5D,CAAC;YAAC,MAAM,CAAC;gBAGP,IAAI,GAAG,IAAI,CAAC;YACd,CAAC;YACD,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,WAAW,EAAE,CAAC;YAIxC,GAAG,CAAC,UAAU,GAAG,EAAE,KAAK,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC;YACrD,OAAO,IAAI,CAAC;QACd,CAAC;QAED,qBAAqB;YACnB,OAAO,UAAU,EAAE,IAAI,WAAW,EAAE,CAAC;QACvC,CAAC;QAED,qBAAqB;QACrB,qBAAqB;QAErB,WAAW,CAAC,MAAM,EAAE,YAAa,EAAE,MAAO;YACxC,OAAO,WAAW,CAAC,MAAM,EAAE,YAAY,IAAI,GAAG,CAAC,YAAY,EAAE,MAAM,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;QAC3F,CAAC;QAED,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,YAAa,EAAE,MAAO;YAC/C,OAAO,gBAAgB,CACrB,GAAG,EACH,GAAG,EACH,YAAY,IAAI,GAAG,CAAC,YAAY,EAChC,MAAM,IAAI,GAAG,CAAC,YAAY,CAC3B,CAAC;QACJ,CAAC;QAED,kBAAkB;QAClB,gBAAgB;QAEhB,kBAAkB,CAAC,OAAyB,EAAE,IAAqB;YACjE,MAAM,OAAO,GAAG,CAAC,IAAI,IAAI,UAAU,EAAE,IAAI,WAAW,EAAE,CAAC,KAAK,OAAO,CAAC;YACpE,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;YAC9D,MAAM,YAAY,GAAG,OAAO;gBAC1B,CAAC,CAAC,CAAC,OAAO,CAAC,kBAAkB,IAAI,IAAI,CAAC;gBACtC,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,IAAI,IAAI,CAAC,CAAC;YAClC,OAAO;gBACL,MAAM;gBACN,YAAY;gBACZ,YAAY,EAAE,OAAO,CAAC,YAAY;gBAClC,OAAO;gBACP,WAAW,EAAE,YAAY,IAAI,IAAI,IAAI,YAAY,GAAG,MAAM;aAC3D,CAAC;QACJ,CAAC;QAED,eAAe,CAAC,OAAyB;YACvC,MAAM,WAAW,GAAG,OAAO,CAAC,WAAW,IAAI,IAAI,IAAI,OAAO,CAAC,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC;YAEvF,IAAI,kBAAkB,GAAkB,IAAI,CAAC;YAC7C,IAAI,WAAW,IAAI,OAAO,CAAC,WAAW,IAAI,IAAI,IAAI,OAAO,CAAC,WAAW,GAAG,CAAC,EAAE,CAAC;gBAC1E,kBAAkB,GAAG,IAAI,CAAC,KAAK,CAC7B,CAAC,CAAC,OAAO,CAAC,WAAW,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,GAAG,GAAG,CACpE,CAAC;YACJ,CAAC;YAED,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,EAAE,MAAM;gBAC3C,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;gBAC3C,CAAC,CAAC,IAAI,CAAC;YAET,OAAO;gBACL,KAAK,EAAE,OAAO,CAAC,KAAK;gBACpB,YAAY,EAAE,OAAO,CAAC,YAAY;gBAClC,YAAY,EAAE,OAAO,CAAC,YAAY;gBAClC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;gBACxC,kBAAkB,EAAE,OAAO,CAAC,kBAAkB,IAAI,IAAI;gBACtD,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,IAAI;gBAC5C,OAAO,EAAE,OAAO,CAAC,cAAc,EAAE,KAAK,IAAI,IAAI;gBAC9C,WAAW;gBACX,kBAAkB;gBAClB,UAAU;aACX,CAAC;QACJ,CAAC;QAED,qBAAqB;KACtB,CAAC;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/pricing/index.ts"],"names":[],"mappings":"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"}

package/dist/pricing/tax-display.d.ts

@@ -1,9 +1,86 @@
+/**
+ * Which tax figure a shopper sees: incl. (`gross`) or excl. (`net`) tax.
+ *
+ * `Channel.pricesIncludeTax` is a STORAGE mode — it says which of `price` /
+ * `priceWithTax` the merchant typed in, not which one this shopper should be
+ * quoted. Those differ in real shops: US sales tax varies by state and even by
+ * district, so a US shopper must never be quoted a tax-inclusive price, and
+ * Dutch B2B buyers work in ex-VAT numbers, while Dutch consumers keep seeing
+ * the gross price the law requires. One channel, three audiences.
+ *
+ * So the engine resolves the mode per request and exposes it as
+ * `Query.activeTaxDisplayMode` — that query is the authority, and
+ * `client.pricing.getTaxDisplayMode()` is how a storefront reads it. The pure
+ * helpers below mirror the engine's rules
+ * (`services/vendure/src/tax-display/tax-display-policy.ts`) RULE FOR RULE so a
+ * client can preview a mode — a "who sees what" table, an SSR guess before the
+ * first round-trip — without one. Change one, change both.
+ *
+ * The channel policy behind it (three `public: true` Channel customFields, all
+ * defaulting to today's behaviour):
+ *
+ *   taxDisplayDefault      channel | gross | net    (default `channel`)
+ *   taxDisplayB2b          inherit | gross | net    (default `inherit`)
+ *   taxExclusiveCountries  JSON ["US"]              (default empty)
+ */
 import type { StoreContext, TaxDisplayInputs, TaxDisplayMode, TaxDisplayPolicy } from '../types.js';
+/** Every channel reads this until a merchant changes something. */
 export declare const DEFAULT_TAX_DISPLAY_POLICY: TaxDisplayPolicy;
+/**
+ * The resolved mode for the active shopper. Public, anonymous-safe, and it
+ * never errors server-side — a lookup failure there falls back to the channel
+ * default rather than failing the request.
+ *
+ * The answer depends on the request's identity, so the SDK sends it with the
+ * same `Authorization` / `x-order-scope` headers as every other call.
+ */
 export declare const ACTIVE_TAX_DISPLAY_MODE = "\n  query ActiveTaxDisplayMode {\n    activeTaxDisplayMode\n  }\n";
+/**
+ * Resolve the mode for one shopper — the engine's rule, offline.
+ *
+ * Precedence — country, then B2B, then the default — and the order is the
+ * point. A US dealer is a US shopper first: their state's sales tax is the
+ * reason the price cannot be quoted gross, and that reason does not go away
+ * because they also happen to be a trade account.
+ *
+ * This is a PREVIEW. `getTaxDisplayMode()` is what a storefront renders from;
+ * only the server knows the shopper's resolved country (active order shipping
+ * address, else their default shipping address).
+ */
 export declare function resolveTaxDisplayMode(policy: TaxDisplayPolicy, inputs: TaxDisplayInputs): TaxDisplayMode;
+/**
+ * Read the policy off `activeChannel.customFields`. LENIENT by design: an
+ * unreadable value degrades to the pre-policy default rather than throwing
+ * while a catalogue page renders. The dashboard's write-side validation is what
+ * stops a bad value being stored.
+ */
 export declare function parseTaxDisplayPolicy(fields: unknown): TaxDisplayPolicy;
+/**
+ * The tax-exclusive country list, normalised to upper-case alpha-2 with
+ * duplicates dropped. Anything unreadable is an EMPTY list — the rule is
+ * opt-in, so falling open means "no country override", never "every country".
+ */
 export declare function parseTaxExclusiveCountries(raw: unknown): readonly string[];
+/**
+ * Map the Shop API enum (`GROSS` / `NET`, upper-case like `OrderScope`) to the
+ * SDK's lower-case union. Returns `null` for anything else — an engine that
+ * predates the enum, a null, a typo — so the caller can fall back to the
+ * channel storage mode instead of rendering a guess.
+ */
 export declare function taxDisplayModeFromEnum(value: unknown): TaxDisplayMode | null;
+/**
+ * Identity fingerprint of the current request context — the cache key for a
+ * resolved mode.
+ *
+ * The mode is a function of WHO is asking: the session (`Authorization`) and
+ * the storefront scope (`x-order-scope`) are the two things the SDK can change
+ * mid-session that also change the answer. Sign in, sign out, or switch to the
+ * trade portal and the stamp changes, so the next read re-resolves instead of
+ * showing the previous shopper's mode.
+ *
+ * A country change is the one non-identity input that can flip the mode; it is
+ * handled by clearing the cache in `setShippingAddress`, since the stamp cannot
+ * see it.
+ */
 export declare function identityStamp(ctx: Pick<StoreContext, 'authToken' | 'orderScope'>): string;
 //# sourceMappingURL=tax-display.d.ts.map

package/dist/pricing/tax-display.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tax-display.d.ts","sourceRoot":"","sources":["../../src/pricing/tax-display.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EACV,YAAY,EAGZ,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAYrB,eAAO,MAAM,0BAA0B,EAAE,gBAIxC,CAAC;AAUF,eAAO,MAAM,uBAAuB,sEAInC,CAAC;AAyBF,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,gBAAgB,GACvB,cAAc,CAShB;AAQD,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,CAWvE;AAOD,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAoB1E;AAQD,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAM5E;AAgBD,wBAAgB,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,YAAY,CAAC,GAAG,MAAM,CAEzF"}
+{"version":3,"file":"tax-display.d.ts","sourceRoot":"","sources":["../../src/pricing/tax-display.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EACV,YAAY,EAGZ,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EACjB,MAAM,aAAa,CAAC;AAWrB,mEAAmE;AACnE,eAAO,MAAM,0BAA0B,EAAE,gBAIxC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,sEAInC,CAAC;AAaF;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,gBAAgB,GACvB,cAAc,CAShB;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,CAWvE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAoB1E;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,GAAG,IAAI,CAM5E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,EAAE,WAAW,GAAG,YAAY,CAAC,GAAG,MAAM,CAEzF"}

package/dist/pricing/tax-display.js

@@ -1,22 +1,76 @@
+/**
+ * Which tax figure a shopper sees: incl. (`gross`) or excl. (`net`) tax.
+ *
+ * `Channel.pricesIncludeTax` is a STORAGE mode — it says which of `price` /
+ * `priceWithTax` the merchant typed in, not which one this shopper should be
+ * quoted. Those differ in real shops: US sales tax varies by state and even by
+ * district, so a US shopper must never be quoted a tax-inclusive price, and
+ * Dutch B2B buyers work in ex-VAT numbers, while Dutch consumers keep seeing
+ * the gross price the law requires. One channel, three audiences.
+ *
+ * So the engine resolves the mode per request and exposes it as
+ * `Query.activeTaxDisplayMode` — that query is the authority, and
+ * `client.pricing.getTaxDisplayMode()` is how a storefront reads it. The pure
+ * helpers below mirror the engine's rules
+ * (`services/vendure/src/tax-display/tax-display-policy.ts`) RULE FOR RULE so a
+ * client can preview a mode — a "who sees what" table, an SSR guess before the
+ * first round-trip — without one. Change one, change both.
+ *
+ * The channel policy behind it (three `public: true` Channel customFields, all
+ * defaulting to today's behaviour):
+ *
+ *   taxDisplayDefault      channel | gross | net    (default `channel`)
+ *   taxDisplayB2b          inherit | gross | net    (default `inherit`)
+ *   taxExclusiveCountries  JSON ["US"]              (default empty)
+ */
+/** ISO-3166 alpha-2: exactly two ASCII letters. */
 const ALPHA2 = /^[A-Za-z]{2}$/;
+/** Channel-wide default. `channel` follows `Channel.pricesIncludeTax`. */
 const TAX_DISPLAY_DEFAULTS = ['channel', 'gross', 'net'];
+/** B2B override. `inherit` leaves B2B shoppers on the channel default. */
 const TAX_DISPLAY_B2B_MODES = ['inherit', 'gross', 'net'];
+/** Every channel reads this until a merchant changes something. */
 export const DEFAULT_TAX_DISPLAY_POLICY = {
     default: 'channel',
     b2b: 'inherit',
     countries: [],
 };
+/**
+ * The resolved mode for the active shopper. Public, anonymous-safe, and it
+ * never errors server-side — a lookup failure there falls back to the channel
+ * default rather than failing the request.
+ *
+ * The answer depends on the request's identity, so the SDK sends it with the
+ * same `Authorization` / `x-order-scope` headers as every other call.
+ */
 export const ACTIVE_TAX_DISPLAY_MODE = `
   query ActiveTaxDisplayMode {
     activeTaxDisplayMode
   }
 `;
+/**
+ * Trim and upper-case one country code, or `null` when it is not a plausible
+ * alpha-2 code. Applied to both the stored list and the country being judged,
+ * so `"us"` and `" US "` can never disagree with `"US"`.
+ */
 function normalizeCountryCode(raw) {
     if (typeof raw !== 'string')
         return null;
     const trimmed = raw.trim();
     return ALPHA2.test(trimmed) ? trimmed.toUpperCase() : null;
 }
+/**
+ * Resolve the mode for one shopper — the engine's rule, offline.
+ *
+ * Precedence — country, then B2B, then the default — and the order is the
+ * point. A US dealer is a US shopper first: their state's sales tax is the
+ * reason the price cannot be quoted gross, and that reason does not go away
+ * because they also happen to be a trade account.
+ *
+ * This is a PREVIEW. `getTaxDisplayMode()` is what a storefront renders from;
+ * only the server knows the shopper's resolved country (active order shipping
+ * address, else their default shipping address).
+ */
 export function resolveTaxDisplayMode(policy, inputs) {
     const country = normalizeCountryCode(inputs.countryCode);
     if (country !== null && policy.countries.includes(country))
@@ -27,6 +81,12 @@ export function resolveTaxDisplayMode(policy, inputs) {
         return policy.default;
     return inputs.pricesIncludeTax ? 'gross' : 'net';
 }
+/**
+ * Read the policy off `activeChannel.customFields`. LENIENT by design: an
+ * unreadable value degrades to the pre-policy default rather than throwing
+ * while a catalogue page renders. The dashboard's write-side validation is what
+ * stops a bad value being stored.
+ */
 export function parseTaxDisplayPolicy(fields) {
     const raw = (fields ?? {});
     return {
@@ -35,6 +95,11 @@ export function parseTaxDisplayPolicy(fields) {
         countries: parseTaxExclusiveCountries(raw.taxExclusiveCountries),
     };
 }
+/**
+ * The tax-exclusive country list, normalised to upper-case alpha-2 with
+ * duplicates dropped. Anything unreadable is an EMPTY list — the rule is
+ * opt-in, so falling open means "no country override", never "every country".
+ */
 export function parseTaxExclusiveCountries(raw) {
     if (typeof raw !== 'string')
         return [];
@@ -59,6 +124,12 @@ export function parseTaxExclusiveCountries(raw) {
     }
     return codes;
 }
+/**
+ * Map the Shop API enum (`GROSS` / `NET`, upper-case like `OrderScope`) to the
+ * SDK's lower-case union. Returns `null` for anything else — an engine that
+ * predates the enum, a null, a typo — so the caller can fall back to the
+ * channel storage mode instead of rendering a guess.
+ */
 export function taxDisplayModeFromEnum(value) {
     if (typeof value !== 'string')
         return null;
@@ -69,6 +140,20 @@ export function taxDisplayModeFromEnum(value) {
         return 'net';
     return null;
 }
+/**
+ * Identity fingerprint of the current request context — the cache key for a
+ * resolved mode.
+ *
+ * The mode is a function of WHO is asking: the session (`Authorization`) and
+ * the storefront scope (`x-order-scope`) are the two things the SDK can change
+ * mid-session that also change the answer. Sign in, sign out, or switch to the
+ * trade portal and the stamp changes, so the next read re-resolves instead of
+ * showing the previous shopper's mode.
+ *
+ * A country change is the one non-identity input that can flip the mode; it is
+ * handled by clearing the cache in `setShippingAddress`, since the stamp cannot
+ * see it.
+ */
 export function identityStamp(ctx) {
     return `${ctx.authToken ?? ''}|${ctx.orderScope ?? ''}`;
 }