@sixtyninecommerce/client 0.24.0 → 0.26.0

package/dist/pricing/tax-display.js.map

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

package/dist/pricing/tiers.d.ts

@@ -1,4 +1,13 @@
 import type { PriceTier, TierTableEntry, VariantPriceData } from '../types.js';
+/**
+ * Find the active price tier for a given quantity.
+ * Tiers are matched by the highest minQuantity that does not exceed the given quantity.
+ * Returns null if no tiers or quantity is below all thresholds.
+ */
 export declare function getTierForQuantity(tiers: PriceTier[], quantity: number): PriceTier | null;
+/**
+ * Build a tier table with savings percentages relative to the retail price.
+ * If no retail price is available, savings are computed relative to the variant's base price.
+ */
 export declare function computeTierTable(variant: VariantPriceData): TierTableEntry[];
 //# sourceMappingURL=tiers.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"tiers.d.ts","sourceRoot":"","sources":["../../src/pricing/tiers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAO/E,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAYzF;AAMD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,cAAc,EAAE,CAkB5E"}
+{"version":3,"file":"tiers.d.ts","sourceRoot":"","sources":["../../src/pricing/tiers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/E;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAYzF;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,GAAG,cAAc,EAAE,CAkB5E"}

package/dist/pricing/tiers.js

@@ -1,3 +1,8 @@
+/**
+ * Find the active price tier for a given quantity.
+ * Tiers are matched by the highest minQuantity that does not exceed the given quantity.
+ * Returns null if no tiers or quantity is below all thresholds.
+ */
 export function getTierForQuantity(tiers, quantity) {
     if (!tiers.length)
         return null;
@@ -11,6 +16,10 @@ export function getTierForQuantity(tiers, quantity) {
     }
     return matched;
 }
+/**
+ * Build a tier table with savings percentages relative to the retail price.
+ * If no retail price is available, savings are computed relative to the variant's base price.
+ */
 export function computeTierTable(variant) {
     const tiers = variant.priceTiers;
     if (!tiers?.length)

package/dist/pricing/tiers.js.map

@@ -1 +1 @@
-{"version":3,"file":"tiers.js","sourceRoot":"","sources":["../../src/pricing/tiers.ts"],"names":[],"mappings":"AAOA,MAAM,UAAU,kBAAkB,CAAC,KAAkB,EAAE,QAAgB;IACrE,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAE/B,IAAI,OAAO,GAAqB,IAAI,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,QAAQ,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACjC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;gBACvD,OAAO,GAAG,IAAI,CAAC;YACjB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAMD,MAAM,UAAU,gBAAgB,CAAC,OAAyB;IACxD,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC;IACjC,IAAI,CAAC,KAAK,EAAE,MAAM;QAAE,OAAO,EAAE,CAAC;IAE9B,MAAM,cAAc,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,KAAK,CAAC;IAC5D,IAAI,cAAc,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAEnC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,OAAO,EAAE,OAAO,CAAC,cAAc,EAAE,KAAK,IAAI,IAAI;QAC9C,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,iBAAiB,EACf,cAAc,GAAG,CAAC;YAChB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,cAAc,CAAC,GAAG,GAAG,CAAC;YACpE,CAAC,CAAC,IAAI;KACX,CAAC,CAAC,CAAC;AACN,CAAC"}
+{"version":3,"file":"tiers.js","sourceRoot":"","sources":["../../src/pricing/tiers.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAkB,EAAE,QAAgB;IACrE,IAAI,CAAC,KAAK,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAE/B,IAAI,OAAO,GAAqB,IAAI,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,QAAQ,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACjC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;gBACvD,OAAO,GAAG,IAAI,CAAC;YACjB,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAyB;IACxD,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC;IACjC,IAAI,CAAC,KAAK,EAAE,MAAM;QAAE,OAAO,EAAE,CAAC;IAE9B,MAAM,cAAc,GAAG,OAAO,CAAC,WAAW,IAAI,OAAO,CAAC,KAAK,CAAC;IAC5D,IAAI,cAAc,IAAI,CAAC;QAAE,OAAO,EAAE,CAAC;IAEnC,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC1B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,OAAO,EAAE,OAAO,CAAC,cAAc,EAAE,KAAK,IAAI,IAAI;QAC9C,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,iBAAiB,EACf,cAAc,GAAG,CAAC;YAChB,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,cAAc,CAAC,GAAG,GAAG,CAAC;YACpE,CAAC,CAAC,IAAI;KACX,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/pricing/validation.d.ts

@@ -1,14 +1,69 @@
-import type { OrderValidationResult } from '../types.js';
+import type { OrderableStockInput, OrderValidationResult } from '../types.js';
+/**
+ * Validate an order against the channel's order minimums.
+ * Call before `transitionToArrangingPayment()` to provide early feedback.
+ *
+ * Pass the object from `getOrderConstraints()` straight through — its
+ * `minOrderAmountGross` / `minOrderQuantity` fields are read directly:
+ *
+ * ```ts
+ * const constraints = await client.checkout.getOrderConstraints();
+ * const result = client.pricing.validateOrderMinimums(order, constraints);
+ * ```
+ *
+ * The server enforces both minimums at the transition regardless, and its
+ * message may name the price list that binds ("Minimum order for Wholesale
+ * is …"), which the client cannot know. Display the server's message as-is on
+ * failure; these messages are for the pre-checkout shortfall hint.
+ */
 export declare function validateOrderMinimums(order: {
     totalWithTax: number;
     currencyCode: string;
     totalQuantity?: number;
+    /**
+     * Net (tax-exclusive) total, minor units. Only needed when the channel
+     * returns `minOrderAmountNet`; `subTotal` is preferred over `total` because
+     * the server compares line totals, which exclude shipping.
+     */
     subTotal?: number;
     total?: number;
 }, constraints: {
+    /** Minimum vs the GROSS order total, minor units. As returned by `getOrderConstraints()`. */
     minOrderAmountGross?: number | null;
+    /**
+     * Minimum vs the NET order total, minor units. Independent of the gross
+     * minimum — both bind. As returned by `getOrderConstraints()`.
+     */
     minOrderAmountNet?: number | null;
+    /** Minimum total item count. As returned by `getOrderConstraints()`. */
     minOrderQuantity?: number | null;
+    /** @deprecated Use `minOrderAmountGross` — the field `getOrderConstraints()` actually returns. */
     minOrderAmount?: number | null;
 }): OrderValidationResult;
+export type { OrderableStockInput };
+/**
+ * How many units of a variant the current shopper may put in the cart:
+ * `max(0, saleable) + backorderAllowance`.
+ *
+ * Returns `null` when the channel does not expose stock (`saleable == null`) —
+ * the storefront cannot know a ceiling then and should let the server decide,
+ * exactly as before backorders existed. A `null` allowance counts as 0, so a
+ * shopper the policy does not admit gets plain `saleable`.
+ */
+export declare function maxOrderableQuantity(variant: OrderableStockInput): number | null;
+/**
+ * Whether a variant is orderable only on backorder: nothing saleable, but an
+ * allowance. The signal to label "Backorder" instead of "Out of stock".
+ */
+export declare function isBackorderOnly(variant: OrderableStockInput): boolean;
+/**
+ * Units of a cart line physical stock will not cover — the "N on backorder"
+ * hint BEFORE placement, when `backorderedQuantity` is still 0 — computed the
+ * way the server stamps it at placement: `max(0, quantity − max(0, saleable))`.
+ *
+ * `null` when there is nothing to say: the channel hides stock
+ * (`saleable == null` — never read that as 0, or every in-stock line would
+ * be "on backorder"), or stock covers the line. Pass the line's variant.
+ */
+export declare function backorderedQuantityForCart(variant: Pick<OrderableStockInput, 'saleable'>, quantity: number): number | null;
 //# sourceMappingURL=validation.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/pricing/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAoB/E,wBAAgB,qBAAqB,CACnC,KAAK,EAAE;IACL,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IAMvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,EACD,WAAW,EAAE;IAEX,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAKpC,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAElC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAEjC,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,GACA,qBAAqB,CAgDvB"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/pricing/validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAwB,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAGpG;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE;IACL,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,EACD,WAAW,EAAE;IACX,6FAA6F;IAC7F,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,kGAAkG;IAClG,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,GACA,qBAAqB,CAgDvB;AAED,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,CAGhF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAErE;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,EAC9C,QAAQ,EAAE,MAAM,GACf,MAAM,GAAG,IAAI,CAIf"}

package/dist/pricing/validation.js

@@ -1,4 +1,21 @@
 import { formatPrice } from './format.js';
+/**
+ * Validate an order against the channel's order minimums.
+ * Call before `transitionToArrangingPayment()` to provide early feedback.
+ *
+ * Pass the object from `getOrderConstraints()` straight through — its
+ * `minOrderAmountGross` / `minOrderQuantity` fields are read directly:
+ *
+ * ```ts
+ * const constraints = await client.checkout.getOrderConstraints();
+ * const result = client.pricing.validateOrderMinimums(order, constraints);
+ * ```
+ *
+ * The server enforces both minimums at the transition regardless, and its
+ * message may name the price list that binds ("Minimum order for Wholesale
+ * is …"), which the client cannot know. Display the server's message as-is on
+ * failure; these messages are for the pre-checkout shortfall hint.
+ */
 export function validateOrderMinimums(order, constraints) {
     const errors = [];
     const minAmount = constraints.minOrderAmountGross ?? constraints.minOrderAmount;
@@ -10,17 +27,25 @@ export function validateOrderMinimums(order, constraints) {
             actual: order.totalWithTax,
         });
     }
+    // A net minimum is checked separately, never folded into the gross one: the
+    // two are different bases and converting between them needs a tax rate the
+    // client does not have. Both can fail on the same cart.
     const minAmountNet = constraints.minOrderAmountNet;
     const netTotal = order.subTotal ?? order.total;
     if (minAmountNet != null && minAmountNet > 0 && netTotal != null && netTotal < minAmountNet) {
         errors.push({
             type: 'min_amount',
+            // Says "excl. tax" so the figure is not read against the gross total the
+            // buyer sees on screen, where it would look wrong.
             message: `Minimum order amount is ${formatPrice(minAmountNet, order.currencyCode)} excl. tax`,
             required: minAmountNet,
             actual: netTotal,
         });
     }
     const minQuantity = constraints.minOrderQuantity;
+    // `totalQuantity` is optional so a caller passing only totals still validates
+    // the amount. Skipping the quantity check when it is absent is correct;
+    // silently failing it against `undefined` would not be.
     if (minQuantity != null &&
         minQuantity > 0 &&
         order.totalQuantity != null &&
@@ -34,4 +59,40 @@ export function validateOrderMinimums(order, constraints) {
     }
     return { valid: errors.length === 0, errors };
 }
+/**
+ * How many units of a variant the current shopper may put in the cart:
+ * `max(0, saleable) + backorderAllowance`.
+ *
+ * Returns `null` when the channel does not expose stock (`saleable == null`) —
+ * the storefront cannot know a ceiling then and should let the server decide,
+ * exactly as before backorders existed. A `null` allowance counts as 0, so a
+ * shopper the policy does not admit gets plain `saleable`.
+ */
+export function maxOrderableQuantity(variant) {
+    if (variant.saleable == null)
+        return null;
+    return Math.max(0, variant.saleable) + Math.max(0, variant.backorderAllowance ?? 0);
+}
+/**
+ * Whether a variant is orderable only on backorder: nothing saleable, but an
+ * allowance. The signal to label "Backorder" instead of "Out of stock".
+ */
+export function isBackorderOnly(variant) {
+    return (variant.saleable ?? 0) <= 0 && (variant.backorderAllowance ?? 0) > 0;
+}
+/**
+ * Units of a cart line physical stock will not cover — the "N on backorder"
+ * hint BEFORE placement, when `backorderedQuantity` is still 0 — computed the
+ * way the server stamps it at placement: `max(0, quantity − max(0, saleable))`.
+ *
+ * `null` when there is nothing to say: the channel hides stock
+ * (`saleable == null` — never read that as 0, or every in-stock line would
+ * be "on backorder"), or stock covers the line. Pass the line's variant.
+ */
+export function backorderedQuantityForCart(variant, quantity) {
+    if (variant.saleable == null)
+        return null;
+    const units = Math.max(0, quantity - Math.max(0, variant.saleable));
+    return units > 0 ? units : null;
+}
 //# sourceMappingURL=validation.js.map

package/dist/pricing/validation.js.map

@@ -1 +1 @@
-{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/pricing/validation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAmB1C,MAAM,UAAU,qBAAqB,CACnC,KAWC,EACD,WAYC;IAED,MAAM,MAAM,GAA2B,EAAE,CAAC;IAE1C,MAAM,SAAS,GAAG,WAAW,CAAC,mBAAmB,IAAI,WAAW,CAAC,cAAc,CAAC;IAChF,IAAI,SAAS,IAAI,IAAI,IAAI,SAAS,GAAG,CAAC,IAAI,KAAK,CAAC,YAAY,GAAG,SAAS,EAAE,CAAC;QACzE,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,YAAY;YAClB,OAAO,EAAE,2BAA2B,WAAW,CAAC,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC,EAAE;YAChF,QAAQ,EAAE,SAAS;YACnB,MAAM,EAAE,KAAK,CAAC,YAAY;SAC3B,CAAC,CAAC;IACL,CAAC;IAKD,MAAM,YAAY,GAAG,WAAW,CAAC,iBAAiB,CAAC;IACnD,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,KAAK,CAAC;IAC/C,IAAI,YAAY,IAAI,IAAI,IAAI,YAAY,GAAG,CAAC,IAAI,QAAQ,IAAI,IAAI,IAAI,QAAQ,GAAG,YAAY,EAAE,CAAC;QAC5F,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,YAAY;YAGlB,OAAO,EAAE,2BAA2B,WAAW,CAAC,YAAY,EAAE,KAAK,CAAC,YAAY,CAAC,YAAY;YAC7F,QAAQ,EAAE,YAAY;YACtB,MAAM,EAAE,QAAQ;SACjB,CAAC,CAAC;IACL,CAAC;IAED,MAAM,WAAW,GAAG,WAAW,CAAC,gBAAgB,CAAC;IAIjD,IACE,WAAW,IAAI,IAAI;QACnB,WAAW,GAAG,CAAC;QACf,KAAK,CAAC,aAAa,IAAI,IAAI;QAC3B,KAAK,CAAC,aAAa,GAAG,WAAW,EACjC,CAAC;QACD,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,cAAc;YACpB,OAAO,EAAE,6BAA6B,WAAW,QAAQ;YACzD,QAAQ,EAAE,WAAW;YACrB,MAAM,EAAE,KAAK,CAAC,aAAa;SAC5B,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;AAChD,CAAC"}
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/pricing/validation.ts"],"names":[],"mappings":"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"}

package/dist/redirects/index.d.ts

@@ -1,5 +1,6 @@
 import type { StoreContext } from '../types.js';
 import type { RedirectStore, RedirectStoreConfig } from './types.js';
+/** Wire a redirect store from an initialized client's context. */
 export declare function createRedirectsModule(ctx: StoreContext, options?: Pick<RedirectStoreConfig, 'ttlMs' | 'timeoutMs' | 'onError'>): RedirectStore;
 export { createRedirectStore, normalizeLookupPath } from './store.js';
 export { REDIRECT_STATUS_CODES, type RedirectMatch, type RedirectRule, type RedirectSnapshot, type RedirectStatusCode, type RedirectStore, type RedirectStoreConfig, } from './types.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/redirects/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGrE,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,YAAY,EACjB,OAAO,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAAC,GACrE,aAAa,CAOf;AAED,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EACL,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/redirects/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,KAAK,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAErE,kEAAkE;AAClE,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,YAAY,EACjB,OAAO,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAAC,GACrE,aAAa,CAOf;AAED,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EACL,qBAAqB,EACrB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,EACvB,KAAK,aAAa,EAClB,KAAK,mBAAmB,GACzB,MAAM,YAAY,CAAC"}

package/dist/redirects/index.js

@@ -1,4 +1,5 @@
 import { createRedirectStore } from './store.js';
+/** Wire a redirect store from an initialized client's context. */
 export function createRedirectsModule(ctx, options) {
     return createRedirectStore({
         storeCode: ctx.channel.code,

package/dist/redirects/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/redirects/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAIjD,MAAM,UAAU,qBAAqB,CACnC,GAAiB,EACjB,OAAsE;IAEtE,OAAO,mBAAmB,CAAC;QACzB,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI;QAC3B,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,GAAG,OAAO;KACX,CAAC,CAAC;AACL,CAAC;AAED,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EACL,qBAAqB,GAOtB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/redirects/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAGjD,kEAAkE;AAClE,MAAM,UAAU,qBAAqB,CACnC,GAAiB,EACjB,OAAsE;IAEtE,OAAO,mBAAmB,CAAC;QACzB,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,IAAI;QAC3B,UAAU,EAAE,GAAG,CAAC,UAAU;QAC1B,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,GAAG,OAAO;KACX,CAAC,CAAC;AACL,CAAC;AAED,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACtE,OAAO,EACL,qBAAqB,GAOtB,MAAM,YAAY,CAAC"}

package/dist/redirects/store.d.ts

@@ -1,4 +1,24 @@
+/**
+ * In-process redirect map for a storefront.
+ *
+ * Fetches the platform's public per-channel snapshot once per TTL and matches
+ * pathnames against it in memory, so a middleware costs a Map lookup rather
+ * than a network hop. Revalidation is ETag-conditional: an unchanged map comes
+ * back as a 304 with no body.
+ *
+ * Deliberately fail-open — a refresh failure keeps the last good map in service
+ * and reports through `onError` rather than throwing. A platform blip must not
+ * turn a tenant's working redirects into 404s.
+ *
+ * Only the FIRST load is awaited. Once a map exists, revalidation happens in the
+ * background and callers are served the current one: this runs in middleware
+ * ahead of every page render, so a slow platform must never become a slow store.
+ */
 import { type RedirectStore, type RedirectStoreConfig } from './types.js';
+/**
+ * Match the platform's own source normalization: trailing slashes are stripped
+ * so `/a` and `/a/` are the same rule. The root path keeps its slash.
+ */
 export declare function normalizeLookupPath(pathname: string): string;
 export declare function createRedirectStore(config: RedirectStoreConfig): RedirectStore;
 //# sourceMappingURL=store.d.ts.map

package/dist/redirects/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/redirects/store.ts"],"names":[],"mappings":"AAkBA,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAC;AA2BpB,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAe5D;AAsCD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,aAAa,CA+J9E"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/redirects/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAML,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAC;AAuBpB;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAe5D;AAsCD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,aAAa,CA+J9E"}

package/dist/redirects/store.js

@@ -1,25 +1,57 @@
+/**
+ * In-process redirect map for a storefront.
+ *
+ * Fetches the platform's public per-channel snapshot once per TTL and matches
+ * pathnames against it in memory, so a middleware costs a Map lookup rather
+ * than a network hop. Revalidation is ETag-conditional: an unchanged map comes
+ * back as a 304 with no body.
+ *
+ * Deliberately fail-open — a refresh failure keeps the last good map in service
+ * and reports through `onError` rather than throwing. A platform blip must not
+ * turn a tenant's working redirects into 404s.
+ *
+ * Only the FIRST load is awaited. Once a map exists, revalidation happens in the
+ * background and callers are served the current one: this runs in middleware
+ * ahead of every page render, so a slow platform must never become a slow store.
+ */
 import { DEFAULT_PLUGINS_URL } from '../constants.js';
 import { REDIRECT_STATUS_CODES, } from './types.js';
 const DEFAULT_TTL_MS = 60_000;
 const DEFAULT_TIMEOUT_MS = 5_000;
+/**
+ * How long a FAILED load is remembered before the next attempt. Deliberately
+ * well above `DEFAULT_TIMEOUT_MS`: if the two were equal, an outage would spend
+ * half of every cycle inside a fetch that callers are waiting on.
+ */
 const FAILURE_BACKOFF_MS = 30_000;
+/** Base for lookup-path canonicalization only — never requested. */
 const CANONICAL_BASE = 'https://redirect.invalid';
+/**
+ * Match the platform's own source normalization: trailing slashes are stripped
+ * so `/a` and `/a/` are the same rule. The root path keeps its slash.
+ */
 export function normalizeLookupPath(pathname) {
     const trimmed = pathname.trim();
     if (trimmed === '' || trimmed === '/')
         return '/';
     const withLeadingSlash = trimmed.startsWith('/') ? trimmed : `/${trimmed}`;
+    // The platform stores the canonical percent-encoded form, which is also what
+    // a browser sends. Re-encoding here is idempotent and lets a caller pass the
+    // human-readable `/café` and still hit the `/caf%C3%A9` rule.
     let canonical = withLeadingSlash;
     try {
         canonical = new URL(withLeadingSlash, CANONICAL_BASE).pathname;
     }
     catch {
+        // Not URL-shaped — fall through with the raw value rather than throwing
+        // out of a middleware's hot path.
     }
     return canonical.replace(/\/+$/, '') || '/';
 }
 function isRedirectStatusCode(value) {
     return typeof value === 'number' && REDIRECT_STATUS_CODES.includes(value);
 }
+/** Parse the wire payload defensively — the platform is an external boundary. */
 function parseSnapshot(raw) {
     if (typeof raw !== 'object' || raw === null) {
         throw new Error('Redirect snapshot is not an object');
@@ -63,6 +95,7 @@ export function createRedirectStore(config) {
     let etag = null;
     let freshUntil = 0;
     let inFlight = null;
+    /** Set once a load has failed; cleared by the next success. */
     let lastLoadFailed = false;
     function indexOf(snapshot) {
         const map = new Map();
@@ -100,12 +133,19 @@ export function createRedirectStore(config) {
             clearTimeout(timeoutId);
         }
     }
+    /** One refresh at a time; concurrent callers share the in-flight request. */
     function loadOnce() {
         inFlight ??= load().finally(() => {
             inFlight = null;
         });
         return inFlight;
     }
+    /**
+     * Load that is guaranteed to observe state as of NOW. An in-flight request
+     * may have been issued before the change we are being told about, so joining
+     * it would report success while leaving the stale map in place — chain a new
+     * load after it instead.
+     */
     function loadAfterInFlight() {
         const pending = inFlight;
         if (!pending)
@@ -115,8 +155,12 @@ export function createRedirectStore(config) {
     function reportFailure(error) {
         lastLoadFailed = true;
         config.onError?.(error instanceof Error ? error : new Error(String(error)));
+        // Back off whether or not there is a map to fall back on. With a warm cache
+        // that means serving the last good map for another TTL; with a COLD one it
+        // is what stops every request paying the full fetch timeout.
         freshUntil = Date.now() + (cached ? ttlMs : FAILURE_BACKOFF_MS);
     }
+    /** Warm the map without anyone waiting on it. Never rejects. */
     function refreshInBackground() {
         void loadOnce().then(() => {
             lastLoadFailed = false;
@@ -128,14 +172,25 @@ export function createRedirectStore(config) {
         if (Date.now() < freshUntil) {
             return cached;
         }
+        // Stale-while-revalidate: once there IS a map, no caller ever waits on the
+        // network again. Revalidating in the foreground put one request per TTL —
+        // and every request concurrent with it — behind a round-trip that can run to
+        // `timeoutMs`, in middleware, ahead of a page render. Serving a map up to
+        // one TTL stale is what this store already accepts on error, so accepting it
+        // on a slow platform too is the consistent choice.
         if (cached) {
             refreshInBackground();
             return cached;
         }
+        // Cold cache AND we already know loads are failing: do not make this caller
+        // wait to rediscover that. Retry in the background and let the request
+        // through unredirected.
         if (lastLoadFailed) {
             refreshInBackground();
             return null;
         }
+        // The very first load IS awaited, so a healthy cold start never misses a
+        // redirect it had the data to serve.
         try {
             const snapshot = await loadOnce();
             lastLoadFailed = false;
@@ -157,6 +212,8 @@ export function createRedirectStore(config) {
             const snapshot = await ensureFresh();
             if (snapshot)
                 return snapshot;
+            // No cached map to fall back on — the caller asked for data we do not
+            // have, so surface the load error rather than inventing an empty map.
             return loadOnce();
         },
         async refresh() {

package/dist/redirects/store.js.map

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

package/dist/redirects/types.d.ts

@@ -1,5 +1,7 @@
+/** The redirect statuses the platform accepts. Mirrors the plugins service. */
 export declare const REDIRECT_STATUS_CODES: readonly [301, 302, 303, 307, 308];
 export type RedirectStatusCode = (typeof REDIRECT_STATUS_CODES)[number];
+/** One stored rule. `from` is always a literal path; `to` is a path or an https URL. */
 export interface RedirectRule {
     from: string;
     to: string;
@@ -7,26 +9,48 @@ export interface RedirectRule {
 }
 export interface RedirectSnapshot {
     channelCode: string;
+    /** Content hash of the rule set — equal to the ETag the platform served. */
     version: string;
+    /** ISO instant the platform rendered this snapshot. */
     generatedAt: string;
     rules: RedirectRule[];
+    /**
+     * Stored rows the platform could not express as an exact-path rule (legacy
+     * wildcard/pattern rows). Non-zero means the merchant has rows to clean up.
+     */
     unservableCount: number;
 }
 export interface RedirectMatch {
+    /** Resolved target, exactly as stored. */
     to: string;
     status: RedirectStatusCode;
 }
 export interface RedirectStoreConfig {
+    /** Store channel code, e.g. `fashion-store`. */
     storeCode: string;
+    /** Plugins service origin. Defaults to the SDK's configured plugins URL. */
     pluginsUrl?: string;
+    /** How long a fetched snapshot is served before revalidating. Default 60s. */
     ttlMs?: number;
+    /** Upstream fetch timeout. Default 5s — a middleware must not hang a request. */
     timeoutMs?: number;
     fetch?: typeof globalThis.fetch;
+    /**
+     * Called when a refresh fails. The store keeps serving the last good snapshot
+     * (a platform blip must not break the storefront's URLs), so this callback is
+     * the only signal that revalidation is failing — wire it to your logger.
+     */
     onError?: (error: Error) => void;
 }
 export interface RedirectStore {
+    /**
+     * Look up one pathname. Returns null when nothing matches. Never throws:
+     * on a cold cache with an unreachable platform it resolves to null.
+     */
     match(pathname: string): Promise<RedirectMatch | null>;
+    /** The current snapshot, fetching or revalidating if the TTL has lapsed. */
     snapshot(): Promise<RedirectSnapshot>;
+    /** Force a revalidation regardless of TTL. */
     refresh(): Promise<RedirectSnapshot>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/redirects/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/redirects/types.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,qBAAqB,oCAAqC,CAAC;AACxE,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAGxE,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IAEpB,OAAO,EAAE,MAAM,CAAC;IAEhB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,YAAY,EAAE,CAAC;IAKtB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAE5B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAElC,SAAS,EAAE,MAAM,CAAC;IAElB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAMhC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,aAAa;IAK5B,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAEvD,QAAQ,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAEtC,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACtC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/redirects/types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,oCAAqC,CAAC;AACxE,MAAM,MAAM,kBAAkB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,kBAAkB,CAAC;CAC5B;AAED,MAAM,WAAW,mBAAmB;IAClC,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAC;IAChC;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC;AAED,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IACvD,4EAA4E;IAC5E,QAAQ,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACtC,8CAA8C;IAC9C,OAAO,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACtC"}

package/dist/redirects/types.js

@@ -1,2 +1,3 @@
+/** The redirect statuses the platform accepts. Mirrors the plugins service. */
 export const REDIRECT_STATUS_CODES = [301, 302, 303, 307, 308];
 //# sourceMappingURL=types.js.map

package/dist/redirects/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/redirects/types.ts"],"names":[],"mappings":"AACA,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/redirects/types.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAU,CAAC"}

package/dist/revalidation/event-plan.d.ts

@@ -1,23 +1,56 @@
+/**
+ * Event → revalidation mapping. Pure: no `next`, no I/O, so a pull-feed
+ * consumer can reuse it exactly as the webhook handler does.
+ *
+ * Path rules the whole module keeps:
+ * - Event paths are channel-relative and locale-UNPREFIXED. Each is composed
+ *   per locale with the channel's own URL rule (`buildUrl`) and then mapped to
+ *   a route path (default: the URL's pathname).
+ * - A commerce path prefix is never prepended and never stripped: commerce
+ *   paths on the bus already carry it, and CMS paths never do — a CMS page may
+ *   legitimately live at `/store/about` beside `commercePathPrefix: '/store'`.
+ * - Whenever an event cannot say which URLs moved (a truncated list, a moved
+ *   base path, a rule change), the plan is the WHOLE site. Never quieter.
+ */
 import type { PlatformEventEnvelope } from '../events/envelope.js';
 import type { ChannelUrlRuleSet, UrlContext } from './url-context.js';
+/** Above this many route paths, one whole-site revalidation replaces them — as the legacy dispatcher does. */
 export declare const DEFAULT_MAX_REVALIDATE_PATHS = 500;
 export type RevalidationSkipReason = 'unknown_type' | 'unsupported_schema_version';
 export interface RevalidationPlan {
+    /** Route paths for `revalidatePath`, de-duplicated. Empty when `all`. */
     readonly paths: string[];
+    /** Tags for `revalidateTag`. */
     readonly tags: string[];
+    /** Revalidate the whole site — `revalidatePath('/', 'layout')`. */
     readonly all: boolean;
+    /** Set when the event is not one this SDK acts on; the plan is then empty. */
     readonly skipped?: RevalidationSkipReason;
+    /**
+     * Set by `createEventRevalidateHandler` when a path event's URLs could not be
+     * composed — the URL context could not be read or is unusable, or
+     * `toRoutePath` threw or returned a non-path — and it revalidated the whole
+     * site instead, answering 200. `planRevalidation` never sets it; it throws.
+     */
     readonly degraded?: RevalidationDegradedReason;
 }
 export type RevalidationDegradedReason = 'url_mapping_failed';
 export interface RevalidationPlanOptions {
+    /** Above this many route paths, plan a whole-site revalidation instead. Default 500. */
     maxPaths?: number;
+    /**
+     * Map a composed storefront URL to the route path to revalidate, or `null` to
+     * skip it. Default: `url.pathname`. Override when your routes differ from your
+     * public URLs — e.g. `subdomain` locales rewritten to `/[locale]/...` routes.
+     */
     toRoutePath?(url: URL, locale: string): string | null;
 }
+/** A signed, known-type, version-1 event whose `data` does not match its contract. */
 export declare class EventPayloadError extends Error {
     constructor(message: string);
 }
 type PathPair = readonly [path: string, locale: string];
+/** What an event asks for, before any URL is composed. Internal to the SDK. */
 export type RevalidationIntent = {
     readonly kind: 'skip';
     readonly reason: RevalidationSkipReason;
@@ -31,9 +64,24 @@ export type RevalidationIntent = {
     readonly kind: 'paths';
     expand(locales: readonly string[]): PathPair[];
 };
+/**
+ * Classify an envelope. Unknown types and unsupported versions are skips, not
+ * errors — a subscriber on an older SDK must keep accepting newer events.
+ * Throws {@link EventPayloadError} for a known v1 type whose `data` is off-contract.
+ */
 export declare function classifyEvent(envelope: Pick<PlatformEventEnvelope, 'type' | 'schema_version' | 'data'>): RevalidationIntent;
 export declare function resolveMaxPaths(maxPaths: number | undefined): number;
+/** Turn an intent into a plan, composing URLs only when the intent has paths. */
 export declare function planFromIntent(intent: RevalidationIntent, urls: UrlContext | null, options?: RevalidationPlanOptions): RevalidationPlan;
+/**
+ * The revalidation a platform event calls for — the mapping
+ * `createEventRevalidateHandler` applies, for consumers of the pull feed or of
+ * their own webhook plumbing.
+ *
+ * Throws {@link EventPayloadError} when a known version-1 event's `data` does
+ * not match its contract, and `TypeError` when `urls` is unusable for an event
+ * that carries paths.
+ */
 export declare function planRevalidation(envelope: Pick<PlatformEventEnvelope, 'type' | 'schema_version' | 'data'>, urls: UrlContext, options?: RevalidationPlanOptions): RevalidationPlan;
 export {};
 //# sourceMappingURL=event-plan.d.ts.map