@sixtyninecommerce/client 0.29.0 → 0.30.0

package/dist/pricing/index.js

@@ -1,11 +1,11 @@
 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 { backorderedQuantityForCart, isBackorderOnly, maxOrderableQuantity, validateOrderMinimums, } from './validation.js';
+import { backorderedQuantityForCart, canAddToCart, isBackorderOnly, isComingSoon, isPreorderOnly, 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 { backorderedQuantityForCart, isBackorderOnly, maxOrderableQuantity, validateOrderMinimums, } from './validation.js';
+export { backorderedQuantityForCart, canAddToCart, isBackorderOnly, isComingSoon, isPreorderOnly, 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
@@ -100,6 +100,9 @@ export function createPricingModule(ctx, http) {
         validateOrderMinimums,
         maxOrderableQuantity,
         isBackorderOnly,
+        isComingSoon,
+        isPreorderOnly,
+        canAddToCart,
         backorderedQuantityForCart,
     };
 }

package/dist/pricing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/pricing/index.ts"],"names":[],"mappings":"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"}
+{"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,EACL,0BAA0B,EAC1B,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB,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,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,cAAc,EACd,oBAAoB,EAEpB,qBAAqB,GACtB,MAAM,iBAAiB,CAAC;AAEzB;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAiB,EAAE,IAAiB;IACtE,8EAA8E;IAC9E,MAAM,WAAW,GAAG,GAAmB,EAAE,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IAEnF,0EAA0E;IAC1E,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;gBACP,kEAAkE;gBAClE,qDAAqD;gBACrD,IAAI,GAAG,IAAI,CAAC;YACd,CAAC;YACD,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,WAAW,EAAE,CAAC;YAExC,wEAAwE;YACxE,gEAAgE;YAChE,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;QACrB,oBAAoB;QACpB,eAAe;QACf,YAAY;QACZ,cAAc;QACd,YAAY;QACZ,0BAA0B;KAC3B,CAAC;AACJ,CAAC"}

package/dist/pricing/validation.d.ts

@@ -43,12 +43,22 @@ export declare function validateOrderMinimums(order: {
 export type { OrderableStockInput };
 /**
  * How many units of a variant the current shopper may put in the cart:
- * `max(0, saleable) + backorderAllowance`.
+ * `max(0, saleable) + backorderAllowance` — or `0` when the merchant is not
+ * accepting orders for it at all (`availability.orderable === false`, i.e.
+ * "coming soon").
  *
  * 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`.
+ *
+ * The coming-soon clamp comes FIRST and ignores stock: a coming-soon variant
+ * with units on hand is still refused by the server (`InsufficientStockError`,
+ * `quantityAvailable: 0`), so a stepper that let the shopper reach that number
+ * would be offering something no add-to-cart can deliver. `0` is returned
+ * rather than `null` even on a channel that hides stock, because `orderable:
+ * false` is a merchant decision the storefront CAN read — there is nothing to
+ * defer to the server about.
  */
 export declare function maxOrderableQuantity(variant: OrderableStockInput): number | null;
 /**
@@ -56,6 +66,84 @@ export declare function maxOrderableQuantity(variant: OrderableStockInput): numb
  * allowance. The signal to label "Backorder" instead of "Out of stock".
  */
 export declare function isBackorderOnly(variant: OrderableStockInput): boolean;
+/**
+ * Whether the merchant is showing this variant as "coming soon": visible, but
+ * not orderable by anyone — not from stock on hand, and not on backorder.
+ *
+ * The signal to render a "Coming soon" badge (with `availability.availableFrom`
+ * as the date when it is set) and to disable add-to-cart. Stock never ends the
+ * state: a coming-soon variant with units on hand is still refused.
+ *
+ * Deliberately a `===` comparison and not a `switch`: a state this SDK release
+ * has never heard of must read as "not coming soon", never as `undefined`.
+ */
+export declare function isComingSoon(variant: OrderableStockInput): boolean;
+/**
+ * Does the storefront KNOW there is nothing to buy outright?
+ *
+ * Three answers, and the third is the point: `true` known empty, `false` known
+ * to have stock, `null` when no signal is readable and nothing may be asserted
+ * either way.
+ *
+ * The signals, most precise first — and which one a shape carries depends on
+ * the document it came from:
+ *
+ * - `saleable`, the precise number. It is `null` whenever the channel does not
+ *   expose stock numbers — which is the DEFAULT
+ *   (`Channel.customFields.exposeStockToStorefront` is off until a merchant
+ *   turns it on), so on an ordinary retail tenant every shopper sees `null`.
+ * - `inStock`, the only stock signal a SEARCH row has: `SEARCH_PRODUCTS`
+ *   selects neither `saleable` nor `stockLevel`, so without this a search grid
+ *   could never tell a 0-stock pre-order from one with stock.
+ * - `stockLevel`, the coarse display string every VARIANT document selects.
+ *   Any value other than `'OUT_OF_STOCK'` means there is something to sell (a
+ *   custom `StockDisplayStrategy` may emit `'LOW_STOCK'` and the like).
+ */
+export declare function knownNothingSaleable(variant: OrderableStockInput): boolean | null;
+/**
+ * Whether this variant can be had ONLY as a pre-order: the merchant has it on
+ * pre-order AND the storefront can see there is nothing to buy outright.
+ *
+ * The label is "Pre-order", not "Out of stock". How MANY units this shopper may
+ * pre-order is `backorderAllowance` — pre-orders borrow the backorder cap, so
+ * an anonymous visitor sees `state: 'preorder'` with a `null` allowance and
+ * cannot in fact order beyond stock. Use `canAddToCart` for the button.
+ *
+ * **A `null` `saleable` is the DEFAULT, not an edge case, and it is not read as
+ * zero here.** `exposeStockToStorefront` is off until a merchant turns it on,
+ * so on an ordinary retail tenant `saleable` is `null` for everybody. Stock
+ * never ends a pre-order state either (the merchant may keep selling from the
+ * warehouse while the state stands), so reading `null` as "nothing saleable"
+ * badged a SKU with forty units on hand "Pre-order, ships 12 March" while the
+ * add succeeded from stock and the parcel shipped that afternoon. It now falls
+ * back to a search row's `inStock`, then to `stockLevel`, and answers `false`
+ * when no signal is knowable — "I cannot prove this is pre-order-only" rather
+ * than a wrong promise.
+ *
+ * **It does NOT match `isBackorderOnly`, despite the shape.** That one reads
+ * `saleable ?? 0` and cannot be wrong for the same reason: its
+ * `backorderAllowance > 0` clause is never true on a stock-hiding channel,
+ * since the allowance is `null` under exactly the same gate. The availability
+ * state has no such gate — it is public — so this helper needs the stock
+ * question answered properly.
+ */
+export declare function isPreorderOnly(variant: OrderableStockInput): boolean;
+/**
+ * Whether the buy button should be enabled for this shopper, right now.
+ *
+ * `true` unless the storefront can prove otherwise: the ceiling is `0` (coming
+ * soon, or out of stock with no allowance). A `null` ceiling — the channel
+ * hides stock — stays `true` and lets the server decide, exactly as before
+ * backorders and pre-orders existed.
+ *
+ * This is the ONE rule a storefront needs. In particular it is NOT
+ * `availability.orderable`: an anonymous shopper sees `orderable: true` on a
+ * pre-order they cannot order beyond stock, because the units come from
+ * `backorderAllowance`, which is `null` for them. The server refuses either way
+ * (`InsufficientStockError` on add, `INSUFFICIENT_STOCK` at placement) — this
+ * just stops the storefront offering it.
+ */
+export declare function canAddToCart(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

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,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"}
+{"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;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,MAAM,GAAG,IAAI,CAIhF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAErE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAElE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,GAAG,IAAI,CAMjF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAEpE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAElE;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

@@ -61,14 +61,26 @@ export function validateOrderMinimums(order, constraints) {
 }
 /**
  * How many units of a variant the current shopper may put in the cart:
- * `max(0, saleable) + backorderAllowance`.
+ * `max(0, saleable) + backorderAllowance` — or `0` when the merchant is not
+ * accepting orders for it at all (`availability.orderable === false`, i.e.
+ * "coming soon").
  *
  * 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`.
+ *
+ * The coming-soon clamp comes FIRST and ignores stock: a coming-soon variant
+ * with units on hand is still refused by the server (`InsufficientStockError`,
+ * `quantityAvailable: 0`), so a stepper that let the shopper reach that number
+ * would be offering something no add-to-cart can deliver. `0` is returned
+ * rather than `null` even on a channel that hides stock, because `orderable:
+ * false` is a merchant decision the storefront CAN read — there is nothing to
+ * defer to the server about.
  */
 export function maxOrderableQuantity(variant) {
+    if (variant.availability?.orderable === false)
+        return 0;
     if (variant.saleable == null)
         return null;
     return Math.max(0, variant.saleable) + Math.max(0, variant.backorderAllowance ?? 0);
@@ -80,6 +92,100 @@ export function maxOrderableQuantity(variant) {
 export function isBackorderOnly(variant) {
     return (variant.saleable ?? 0) <= 0 && (variant.backorderAllowance ?? 0) > 0;
 }
+/**
+ * Whether the merchant is showing this variant as "coming soon": visible, but
+ * not orderable by anyone — not from stock on hand, and not on backorder.
+ *
+ * The signal to render a "Coming soon" badge (with `availability.availableFrom`
+ * as the date when it is set) and to disable add-to-cart. Stock never ends the
+ * state: a coming-soon variant with units on hand is still refused.
+ *
+ * Deliberately a `===` comparison and not a `switch`: a state this SDK release
+ * has never heard of must read as "not coming soon", never as `undefined`.
+ */
+export function isComingSoon(variant) {
+    return variant.availability?.state === 'comingSoon';
+}
+/**
+ * Does the storefront KNOW there is nothing to buy outright?
+ *
+ * Three answers, and the third is the point: `true` known empty, `false` known
+ * to have stock, `null` when no signal is readable and nothing may be asserted
+ * either way.
+ *
+ * The signals, most precise first — and which one a shape carries depends on
+ * the document it came from:
+ *
+ * - `saleable`, the precise number. It is `null` whenever the channel does not
+ *   expose stock numbers — which is the DEFAULT
+ *   (`Channel.customFields.exposeStockToStorefront` is off until a merchant
+ *   turns it on), so on an ordinary retail tenant every shopper sees `null`.
+ * - `inStock`, the only stock signal a SEARCH row has: `SEARCH_PRODUCTS`
+ *   selects neither `saleable` nor `stockLevel`, so without this a search grid
+ *   could never tell a 0-stock pre-order from one with stock.
+ * - `stockLevel`, the coarse display string every VARIANT document selects.
+ *   Any value other than `'OUT_OF_STOCK'` means there is something to sell (a
+ *   custom `StockDisplayStrategy` may emit `'LOW_STOCK'` and the like).
+ */
+export function knownNothingSaleable(variant) {
+    if (typeof variant.saleable === 'number')
+        return variant.saleable <= 0;
+    if (typeof variant.inStock === 'boolean')
+        return !variant.inStock;
+    if (variant.stockLevel === 'OUT_OF_STOCK')
+        return true;
+    if (typeof variant.stockLevel === 'string' && variant.stockLevel !== '')
+        return false;
+    return null;
+}
+/**
+ * Whether this variant can be had ONLY as a pre-order: the merchant has it on
+ * pre-order AND the storefront can see there is nothing to buy outright.
+ *
+ * The label is "Pre-order", not "Out of stock". How MANY units this shopper may
+ * pre-order is `backorderAllowance` — pre-orders borrow the backorder cap, so
+ * an anonymous visitor sees `state: 'preorder'` with a `null` allowance and
+ * cannot in fact order beyond stock. Use `canAddToCart` for the button.
+ *
+ * **A `null` `saleable` is the DEFAULT, not an edge case, and it is not read as
+ * zero here.** `exposeStockToStorefront` is off until a merchant turns it on,
+ * so on an ordinary retail tenant `saleable` is `null` for everybody. Stock
+ * never ends a pre-order state either (the merchant may keep selling from the
+ * warehouse while the state stands), so reading `null` as "nothing saleable"
+ * badged a SKU with forty units on hand "Pre-order, ships 12 March" while the
+ * add succeeded from stock and the parcel shipped that afternoon. It now falls
+ * back to a search row's `inStock`, then to `stockLevel`, and answers `false`
+ * when no signal is knowable — "I cannot prove this is pre-order-only" rather
+ * than a wrong promise.
+ *
+ * **It does NOT match `isBackorderOnly`, despite the shape.** That one reads
+ * `saleable ?? 0` and cannot be wrong for the same reason: its
+ * `backorderAllowance > 0` clause is never true on a stock-hiding channel,
+ * since the allowance is `null` under exactly the same gate. The availability
+ * state has no such gate — it is public — so this helper needs the stock
+ * question answered properly.
+ */
+export function isPreorderOnly(variant) {
+    return variant.availability?.state === 'preorder' && knownNothingSaleable(variant) === true;
+}
+/**
+ * Whether the buy button should be enabled for this shopper, right now.
+ *
+ * `true` unless the storefront can prove otherwise: the ceiling is `0` (coming
+ * soon, or out of stock with no allowance). A `null` ceiling — the channel
+ * hides stock — stays `true` and lets the server decide, exactly as before
+ * backorders and pre-orders existed.
+ *
+ * This is the ONE rule a storefront needs. In particular it is NOT
+ * `availability.orderable`: an anonymous shopper sees `orderable: true` on a
+ * pre-order they cannot order beyond stock, because the units come from
+ * `backorderAllowance`, which is `null` for them. The server refuses either way
+ * (`InsufficientStockError` on add, `INSUFFICIENT_STOCK` at placement) — this
+ * just stops the storefront offering it.
+ */
+export function canAddToCart(variant) {
+    return maxOrderableQuantity(variant) !== 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

package/dist/pricing/validation.js.map

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

package/dist/seo/availability.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Availability for structured data: one variant's stock + merchant publication
+ * state, expressed as the schema.org `ItemAvailability` URL that
+ * `Offer.availability` wants and the OpenGraph token `product:availability`
+ * wants.
+ *
+ * These are separate vocabularies for the same fact, and `ProductSeoExtras`
+ * carries ONE `availability` string that feeds both tags. So the schema.org URL
+ * is the value a storefront passes, and `openGraphAvailability` translates it
+ * back for the OpenGraph tag. Anything the SDK does not recognise is passed
+ * through untouched, which is what every caller that predates this file gets.
+ */
+import type { ProductAvailability } from '../types.js';
+/** The three `ItemAvailability` members this SDK emits. */
+export type SchemaOrgAvailability = 'https://schema.org/InStock' | 'https://schema.org/OutOfStock' | 'https://schema.org/PreOrder';
+/**
+ * What `schemaOrgAvailability` reads; satisfied by every SDK variant shape AND
+ * by a search row. The stock signals are the ones `isPreorderOnly` reads, read
+ * the same way (`knownNothingSaleable`), so the feed and the badge cannot
+ * disagree about whether a pre-order is buyable today.
+ */
+export interface AvailabilityForSeo {
+    /**
+     * The merchant publication state in force. Absent or `null` (a search row
+     * that predates the attribute, an older engine) is read as "nothing in
+     * force" — the pre-order-free behaviour.
+     */
+    availability?: ProductAvailability | null;
+    /** Available-to-promise units — the precise signal, preferred when present. */
+    saleable?: number | null;
+    /** A search row's stock flag, the only stock signal `SEARCH_PRODUCTS` selects. */
+    inStock?: boolean | null;
+    /** Vendure's display string — `'IN_STOCK'` / `'OUT_OF_STOCK'`. */
+    stockLevel?: string | null;
+}
+/**
+ * The schema.org `ItemAvailability` URL for a variant. Pass the result as
+ * `extras.availability` to `metaTagsFor` — JSON-LD emits it verbatim as
+ * `Offer.availability`, and the OpenGraph `product:availability` tag gets the
+ * matching Facebook token automatically.
+ *
+ * ```ts
+ * const extras = {
+ *   availability: schemaOrgAvailability(variant),
+ *   availabilityStarts: variant.availability?.availableFrom,
+ *   ...
+ * };
+ * ```
+ *
+ * | state | stock the storefront can SEE | result |
+ * |---|---|---|
+ * | `comingSoon` | anything | `OutOfStock` |
+ * | `preorder` | known nothing to buy | `PreOrder` |
+ * | `preorder` | known stock, or no signal | `InStock` |
+ * | anything else | known nothing to buy | `OutOfStock` |
+ * | anything else | known stock, or no signal | `InStock` |
+ *
+ * **Coming soon is `OutOfStock`, whatever the stock.** schema.org defines
+ * `PreOrder` as "Indicates that the item is available for pre-order" — an
+ * assertion that it can be ORDERED now for later delivery, which is the one
+ * thing this SDK guarantees a coming-soon item is not (`orderable: false`,
+ * `canAddToCart` false, and the engine refuses every add with
+ * `quantityAvailable: 0`, stock on hand or not). Emitting it would advertise a
+ * purchasable offer behind a disabled buy button — a Merchant Center
+ * availability-versus-landing-page mismatch. `OutOfStock` is the honest
+ * member for "not currently purchasable". (`SoldOut` is wrong the other way:
+ * it says the item HAD stock and it went, not that it has not launched.)
+ *
+ * **A pre-order is `PreOrder` only while there is nothing to buy outright** —
+ * exactly when `isPreorderOnly(variant)` is true, through the same
+ * `knownNothingSaleable` predicate. Stock never ENDS a pre-order state (the
+ * merchant may keep selling from the warehouse while it stands), but a variant
+ * with stock on hand ships today: the page shows the ordinary in-stock UI, and
+ * a feed saying "Pre-order, available 12 March" for it is the same mismatch in
+ * the other direction. So it is `InStock`, and the JSON-LD composer drops
+ * `availabilityStarts` for an `InStock` offer. When no stock signal is
+ * readable it is not claimed as a pre-order either, matching the label.
+ *
+ * Everything else is today's rule, read through the same predicate:
+ * `saleable` when the channel exposes it, then a search row's `inStock`, then
+ * the `stockLevel` string, and `InStock` when nothing says otherwise. An
+ * unknown state — one a later engine added — falls through to the stock rule
+ * rather than throwing, which is why this is a chain of comparisons and not a
+ * `switch`.
+ */
+export declare function schemaOrgAvailability(variant: AvailabilityForSeo): SchemaOrgAvailability;
+/**
+ * The OpenGraph `product:availability` token for an availability value.
+ *
+ * Translates the three schema.org URLs into Facebook's vocabulary and passes
+ * anything else through verbatim — so a storefront that has always passed
+ * `'in stock'` keeps emitting `'in stock'`, byte for byte.
+ */
+export declare function openGraphAvailability(availability: string): string;
+//# sourceMappingURL=availability.d.ts.map

package/dist/seo/availability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"availability.d.ts","sourceRoot":"","sources":["../../src/seo/availability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEvD,2DAA2D;AAC3D,MAAM,MAAM,qBAAqB,GAC7B,4BAA4B,GAC5B,+BAA+B,GAC/B,6BAA6B,CAAC;AAElC;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,YAAY,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC1C,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kFAAkF;IAClF,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,kBAAkB,GAAG,qBAAqB,CAMxF;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAKlE"}

package/dist/seo/availability.js

@@ -0,0 +1,89 @@
+/**
+ * Availability for structured data: one variant's stock + merchant publication
+ * state, expressed as the schema.org `ItemAvailability` URL that
+ * `Offer.availability` wants and the OpenGraph token `product:availability`
+ * wants.
+ *
+ * These are separate vocabularies for the same fact, and `ProductSeoExtras`
+ * carries ONE `availability` string that feeds both tags. So the schema.org URL
+ * is the value a storefront passes, and `openGraphAvailability` translates it
+ * back for the OpenGraph tag. Anything the SDK does not recognise is passed
+ * through untouched, which is what every caller that predates this file gets.
+ */
+import { knownNothingSaleable } from '../pricing/validation.js';
+/**
+ * The schema.org `ItemAvailability` URL for a variant. Pass the result as
+ * `extras.availability` to `metaTagsFor` — JSON-LD emits it verbatim as
+ * `Offer.availability`, and the OpenGraph `product:availability` tag gets the
+ * matching Facebook token automatically.
+ *
+ * ```ts
+ * const extras = {
+ *   availability: schemaOrgAvailability(variant),
+ *   availabilityStarts: variant.availability?.availableFrom,
+ *   ...
+ * };
+ * ```
+ *
+ * | state | stock the storefront can SEE | result |
+ * |---|---|---|
+ * | `comingSoon` | anything | `OutOfStock` |
+ * | `preorder` | known nothing to buy | `PreOrder` |
+ * | `preorder` | known stock, or no signal | `InStock` |
+ * | anything else | known nothing to buy | `OutOfStock` |
+ * | anything else | known stock, or no signal | `InStock` |
+ *
+ * **Coming soon is `OutOfStock`, whatever the stock.** schema.org defines
+ * `PreOrder` as "Indicates that the item is available for pre-order" — an
+ * assertion that it can be ORDERED now for later delivery, which is the one
+ * thing this SDK guarantees a coming-soon item is not (`orderable: false`,
+ * `canAddToCart` false, and the engine refuses every add with
+ * `quantityAvailable: 0`, stock on hand or not). Emitting it would advertise a
+ * purchasable offer behind a disabled buy button — a Merchant Center
+ * availability-versus-landing-page mismatch. `OutOfStock` is the honest
+ * member for "not currently purchasable". (`SoldOut` is wrong the other way:
+ * it says the item HAD stock and it went, not that it has not launched.)
+ *
+ * **A pre-order is `PreOrder` only while there is nothing to buy outright** —
+ * exactly when `isPreorderOnly(variant)` is true, through the same
+ * `knownNothingSaleable` predicate. Stock never ENDS a pre-order state (the
+ * merchant may keep selling from the warehouse while it stands), but a variant
+ * with stock on hand ships today: the page shows the ordinary in-stock UI, and
+ * a feed saying "Pre-order, available 12 March" for it is the same mismatch in
+ * the other direction. So it is `InStock`, and the JSON-LD composer drops
+ * `availabilityStarts` for an `InStock` offer. When no stock signal is
+ * readable it is not claimed as a pre-order either, matching the label.
+ *
+ * Everything else is today's rule, read through the same predicate:
+ * `saleable` when the channel exposes it, then a search row's `inStock`, then
+ * the `stockLevel` string, and `InStock` when nothing says otherwise. An
+ * unknown state — one a later engine added — falls through to the stock rule
+ * rather than throwing, which is why this is a chain of comparisons and not a
+ * `switch`.
+ */
+export function schemaOrgAvailability(variant) {
+    const state = variant.availability?.state;
+    if (state === 'comingSoon')
+        return 'https://schema.org/OutOfStock';
+    const nothingSaleable = knownNothingSaleable(variant) === true;
+    if (state === 'preorder' && nothingSaleable)
+        return 'https://schema.org/PreOrder';
+    return nothingSaleable ? 'https://schema.org/OutOfStock' : 'https://schema.org/InStock';
+}
+/**
+ * The OpenGraph `product:availability` token for an availability value.
+ *
+ * Translates the three schema.org URLs into Facebook's vocabulary and passes
+ * anything else through verbatim — so a storefront that has always passed
+ * `'in stock'` keeps emitting `'in stock'`, byte for byte.
+ */
+export function openGraphAvailability(availability) {
+    if (availability === 'https://schema.org/InStock')
+        return 'in stock';
+    if (availability === 'https://schema.org/OutOfStock')
+        return 'out of stock';
+    if (availability === 'https://schema.org/PreOrder')
+        return 'preorder';
+    return availability;
+}
+//# sourceMappingURL=availability.js.map

package/dist/seo/availability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"availability.js","sourceRoot":"","sources":["../../src/seo/availability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AA8BhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA2B;IAC/D,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,EAAE,KAAK,CAAC;IAC1C,IAAI,KAAK,KAAK,YAAY;QAAE,OAAO,+BAA+B,CAAC;IACnE,MAAM,eAAe,GAAG,oBAAoB,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC/D,IAAI,KAAK,KAAK,UAAU,IAAI,eAAe;QAAE,OAAO,6BAA6B,CAAC;IAClF,OAAO,eAAe,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,4BAA4B,CAAC;AAC1F,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,YAAoB;IACxD,IAAI,YAAY,KAAK,4BAA4B;QAAE,OAAO,UAAU,CAAC;IACrE,IAAI,YAAY,KAAK,+BAA+B;QAAE,OAAO,cAAc,CAAC;IAC5E,IAAI,YAAY,KAAK,6BAA6B;QAAE,OAAO,UAAU,CAAC;IACtE,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/dist/seo/index.d.ts

@@ -2,6 +2,8 @@ import type { StoreContext } from '../types.js';
 import type { SeoModule } from './types.js';
 export declare function createSeoModule(ctx: StoreContext): SeoModule;
 export type { AiSummaryInput, LlmsTxtEntryInput, } from './ai.js';
+export type { AvailabilityForSeo, SchemaOrgAvailability } from './availability.js';
+export { openGraphAvailability, schemaOrgAvailability } from './availability.js';
 export type { CmsMetaTagsInput, CmsSeoExtras, CollectionMetaTagsInput, CollectionSeoExtras, HreflangLinkTag, MetaTagsEntityInput, MetaTagsResult, OpenGraphTag, ProductMetaTagsInput, ProductSeoExtras, TwitterTag, } from './meta-tags.js';
 export type { RawCmsSeo, RawCollectionSeo, RawProductMetadata } from './metadata-parser.js';
 export { parseCmsItemMetadata, parseCollectionMetadata, parseProductMetadata, robotsFromFlags, } from './metadata-parser.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/seo/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAOhD,OAAO,KAAK,EAAkB,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5D,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,CAyE5D;AAED,YAAY,EACV,cAAc,EACd,iBAAiB,GAClB,MAAM,SAAS,CAAC;AACjB,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,GACX,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC5F,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,YAAY,EACZ,uBAAuB,EACvB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,UAAU,EACV,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,MAAM,EACN,YAAY,EACZ,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,OAAO,EACP,SAAS,EACT,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/seo/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAQhD,OAAO,KAAK,EAAkB,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5D,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,SAAS,CA0E5D;AAED,YAAY,EACV,cAAc,EACd,iBAAiB,GAClB,MAAM,SAAS,CAAC;AACjB,YAAY,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACnF,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACjF,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,uBAAuB,EACvB,mBAAmB,EACnB,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,oBAAoB,EACpB,gBAAgB,EAChB,UAAU,GACX,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC5F,OAAO,EACL,oBAAoB,EACpB,uBAAuB,EACvB,oBAAoB,EACpB,eAAe,GAChB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,YAAY,EACZ,uBAAuB,EACvB,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,EACrB,UAAU,EACV,yBAAyB,EACzB,wBAAwB,EACxB,yBAAyB,EACzB,eAAe,EACf,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,MAAM,EACN,YAAY,EACZ,eAAe,GAChB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,GACvB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,mBAAmB,GACpB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,cAAc,EACd,OAAO,EACP,SAAS,EACT,iBAAiB,GAClB,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/seo/index.js

@@ -2,6 +2,7 @@ import { createContextAssetUrlResolver } from '../media/urls.js';
 import { aiSummaryFor, llmsTxtEntryFor } from './ai.js';
 import { alternatesFor } from './alternates.js';
 import { createArtifactUrls, reportNotFound } from './artifacts.js';
+import { schemaOrgAvailability } from './availability.js';
 import { canonicalFor } from './canonical.js';
 import { metaTagsFor } from './meta-tags.js';
 import { composePerBotDirectives } from './robots.js';
@@ -72,6 +73,7 @@ export function createSeoModule(ctx) {
                 xRobotsHeaders: [],
             };
         },
+        schemaOrgAvailability,
         aiSummaryFor(entity) {
             return aiSummaryFor(entity);
         },
@@ -80,6 +82,7 @@ export function createSeoModule(ctx) {
         },
     };
 }
+export { openGraphAvailability, schemaOrgAvailability } from './availability.js';
 export { parseCmsItemMetadata, parseCollectionMetadata, parseProductMetadata, robotsFromFlags, } from './metadata-parser.js';
 export { DEFAULT_PRODUCT_PATH_SEGMENT, isUserFacingRoot, normalizeProductPathSegment, pickCanonicalRootIndex, } from './product-path.js';
 export { buildUrl, readUrlStrategy } from './url-builder.js';

package/dist/seo/index.js.map

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

package/dist/seo/json-ld.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-ld.d.ts","sourceRoot":"","sources":["../../src/seo/json-ld.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC5F,OAAO,KAAK,EAAoB,aAAa,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAuB1D,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,eAAe,EAAE,gBAAgB,CAAC;IAClC,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACrC,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9D;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAyDvF;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,iBAAiB,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,aAAa,CAAC,uBAAuB,CAAC,CAAC;CAClD;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkB7F;AAqCD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,gFAAgF;IAChF,eAAe,EAAE,gBAAgB,CAAC;CACnC;AAQD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWvF;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWhF;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUtF"}
+{"version":3,"file":"json-ld.d.ts","sourceRoot":"","sources":["../../src/seo/json-ld.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,KAAK,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC5F,OAAO,KAAK,EAAoB,aAAa,EAAE,MAAM,YAAY,CAAC;AAClE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAuB1D,MAAM,WAAW,kBAAkB;IACjC,gFAAgF;IAChF,eAAe,EAAE,gBAAgB,CAAC;IAClC,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,gBAAgB,GAAG,SAAS,CAAC;IACrC,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9D;AAYD,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAiFvF;AAED,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,iBAAiB,CAAC;IACvB,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,aAAa,CAAC,uBAAuB,CAAC,CAAC;CAClD;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAkB7F;AAqCD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,gFAAgF;IAChF,eAAe,EAAE,gBAAgB,CAAC;CACnC;AAQD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWvF;AAED,4DAA4D;AAC5D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWhF;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,aAAa,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAUtF"}

package/dist/seo/json-ld.js

@@ -24,6 +24,15 @@ function pickImageUrls(resolveAssetUrl, ...assets) {
     }
     return urls;
 }
+/**
+ * The two `ItemAvailability` values `schemaOrgAvailability` returns for an
+ * offer that cannot be bought outright today — the only ones a future
+ * `availabilityStarts` is consistent with. `InStock` is deliberately absent.
+ */
+const NOT_PURCHASABLE_NOW = new Set([
+    'https://schema.org/PreOrder',
+    'https://schema.org/OutOfStock',
+]);
 export function composeProductJsonLd(input) {
     const { product, metadata, canonical, title, description, extras, reviews } = input;
     const out = {
@@ -50,9 +59,33 @@ export function composeProductJsonLd(input) {
         };
         if (extras.availability) {
             // schema.org expects an ItemAvailability URL, but text is also widely
-            // accepted by validators. Pass-through whatever the storefront provides.
+            // accepted by validators. Pass-through whatever the storefront provides —
+            // `schemaOrgAvailability(variant)` (`./availability.js`) is what produces
+            // the URL, and it is the only way `PreOrder` ever gets emitted: a
+            // pre-order with nothing on hand reads 0 stock, so anything derived from
+            // `stockLevel` alone would say `OutOfStock` and hide a product the
+            // merchant is actively taking orders for.
             offer.availability = extras.availability;
         }
+        if (extras.availabilityStarts && NOT_PURCHASABLE_NOW.has(extras.availability ?? '')) {
+            // `https://schema.org/availabilityStarts` — "The beginning of the
+            // availability of the product or service included in the offer", a
+            // property of `Offer` (verified against schema.org). It is the date half
+            // of the two merchant states: a `PreOrder` with no availability date is
+            // an item-level feed error, and a coming-soon item (mapped to
+            // `OutOfStock`, which says nothing about WHEN) has no other way to say
+            // it is arriving.
+            //
+            // Only beside an offer that is NOT purchasable now. A pre-order with stock
+            // on hand is `InStock` — it ships today — and "in stock, available from
+            // 12 March" contradicts itself; a storefront passing
+            // `variant.availability?.availableFrom` unconditionally must not produce
+            // that. A hand-written availability string is not recognised either: the
+            // SDK cannot tell whether that offer is purchasable now. Nothing is
+            // emitted without a date, so an offer from a storefront that predates this
+            // field is byte-identical.
+            offer.availabilityStarts = extras.availabilityStarts;
+        }
         if (extras.condition) {
             offer.itemCondition = `https://schema.org/${extras.condition === 'new'
                 ? 'NewCondition'