@classytic/primitives 0.26.1 → 0.26.3

package/CHANGELOG.md

@@ -3,6 +3,40 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.26.3
+
+### Added — `PaymentProviderPort.wantsRawBody`
+
+Optional `readonly wantsRawBody?: boolean` on the payment gateway port.
+Providers that verify an HMAC signature (Stripe signs the bytes it transmitted)
+must declare `true` — the transport then hands the raw body rather than the
+parsed object. Absent / `false` preserves the historical behaviour (parsed
+body), which is correct for manual, cash and terminal providers that sign
+nothing.
+
+## 0.26.2
+
+### Added — `stockKeyFor` (`/item-identity`): one stock-key precedence for every package
+
+The product-level stock key, with a single precedence:
+
+1. the variant's stamped `skuRef` — assigned once at birth, immutable
+2. a **sole** variant with no stamp → the product's `_id`, never the label
+   (legacy writers derived `variantSku || productId`, and for one variant that
+   key IS the `_id`)
+3. a **sibling** with no stamp → its label, which genuinely is its legacy key
+4. nothing addressable → the product's `_id`
+
+The caller declares only what it HAS — `{ kind: 'sole' | 'label' | 'variant' }`
+— so the sole-vs-sibling decision is internal and a caller cannot make it wrong.
+That choice previously lived at every call site across three packages, in two
+functions with different fallbacks; they disagreed on a sole, unstamped,
+labelled variant, and the read then looked up a key no quant is stored under.
+
+It lives here, below every domain, because `@spinekit/order` and
+`@spinekit/catalog` must not import a peer domain — the rule sitting one layer
+too high is exactly why each package re-derived it.
+
 ## 0.26.1
 
 - `./testing/stock-key-seam` — new subpath; `scanStockKeySeam`, `assertStockKeySeam`, `takesStockKeyFromLabel`, `STOCK_KEY_SEAM_FIXTURES` for conformance-scanning packages that resolve stock keys

package/dist/item-identity.d.mts

@@ -31,6 +31,50 @@ interface SkuFields {
 declare function stockKeyOf(item: SkuFields, fallback?: string | {
   toString(): string;
 }): StockKey | undefined;
+/** The minimal product shape {@link stockKeyFor} reads. */
+interface StockKeySource {
+  _id: string | {
+    toString(): string;
+  };
+  variants?: ReadonlyArray<SkuFields> | null;
+}
+/**
+ * WHAT THE CALLER HAS — never what the key should be.
+ *
+ * - `sole`    nothing selected (a simple product, or a whole-product read)
+ * - `label`   an operator-typed / scanned SKU label
+ * - `variant` one variant record in hand, from iterating `variants`
+ */
+type StockKeySelector = {
+  readonly kind: "sole";
+} | {
+  readonly kind: "label";
+  readonly sku: string;
+} | {
+  readonly kind: "variant";
+  readonly variant: SkuFields;
+};
+/**
+ * THE product-level stock key. One precedence, for every package.
+ *
+ *   1. the variant's STAMPED `skuRef` — assigned once at birth, immutable
+ *   2. a SOLE variant with no stamp -> the product's `_id`. Never the label:
+ *      legacy writers derived `variantSku || productId`, and for one variant
+ *      that key IS the `_id`
+ *   3. a SIBLING with no stamp -> its label, which genuinely IS its legacy key
+ *   4. nothing addressable -> the product's `_id`
+ *
+ * The caller declares only what it HAS; the sole-vs-sibling decision is
+ * internal, so a caller cannot make it wrong. That choice previously lived at
+ * every call site across three packages, in two functions with different
+ * fallbacks — they disagreed on a sole, unstamped, labelled variant, and the
+ * read then looked up a key no quant is stored under.
+ *
+ * Lives HERE, below every domain, because `@spinekit/order` and
+ * `@spinekit/catalog` must not import a peer domain — the rule being one layer
+ * too high is exactly why each re-derived it.
+ */
+declare function stockKeyFor(product: StockKeySource, selector: StockKeySelector): StockKey;
 /**
  * {@link stockKeyOf} that THROWS. Use wherever the key feeds a stock movement:
  * a reservation on `undefined` returns "out of stock" instead of failing.
@@ -58,4 +102,4 @@ declare function skuDisplay(item: SkuFields): SkuDisplay;
  */
 declare function looksLikeOpaqueId(value: string | undefined): boolean;
 //#endregion
-export { SkuDisplay, SkuFields, StockKey, looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyOf };
+export { SkuDisplay, SkuFields, StockKey, StockKeySelector, StockKeySource, looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyFor, stockKeyOf };

package/dist/item-identity.mjs

@@ -14,6 +14,49 @@ function stockKeyOf(item, fallback) {
 	return nonEmpty(item.skuRef) ?? nonEmpty(item.sku) ?? (fallback !== void 0 ? String(fallback) : void 0);
 }
 /**
+* THE product-level stock key. One precedence, for every package.
+*
+*   1. the variant's STAMPED `skuRef` — assigned once at birth, immutable
+*   2. a SOLE variant with no stamp -> the product's `_id`. Never the label:
+*      legacy writers derived `variantSku || productId`, and for one variant
+*      that key IS the `_id`
+*   3. a SIBLING with no stamp -> its label, which genuinely IS its legacy key
+*   4. nothing addressable -> the product's `_id`
+*
+* The caller declares only what it HAS; the sole-vs-sibling decision is
+* internal, so a caller cannot make it wrong. That choice previously lived at
+* every call site across three packages, in two functions with different
+* fallbacks — they disagreed on a sole, unstamped, labelled variant, and the
+* read then looked up a key no quant is stored under.
+*
+* Lives HERE, below every domain, because `@spinekit/order` and
+* `@spinekit/catalog` must not import a peer domain — the rule being one layer
+* too high is exactly why each re-derived it.
+*/
+function stockKeyFor(product, selector) {
+	const productId = String(product._id);
+	const variants = product.variants ?? [];
+	const sole = variants.length <= 1;
+	switch (selector.kind) {
+		case "sole":
+			if (!sole) return productId;
+			return nonEmpty(variants[0]?.skuRef) ?? productId;
+		case "label": {
+			const matched = variants.find((v) => v.sku === selector.sku);
+			const stamp = nonEmpty(matched?.skuRef);
+			if (stamp !== void 0) return stamp;
+			if (sole) return productId;
+			return selector.sku;
+		}
+		case "variant": {
+			const stamp = nonEmpty(selector.variant.skuRef);
+			if (stamp !== void 0) return stamp;
+			if (sole) return productId;
+			return stockKeyOf(selector.variant, productId);
+		}
+	}
+}
+/**
 * {@link stockKeyOf} that THROWS. Use wherever the key feeds a stock movement:
 * a reservation on `undefined` returns "out of stock" instead of failing.
 */
@@ -47,4 +90,4 @@ function looksLikeOpaqueId(value) {
 	return typeof value === "string" && /^[0-9a-f]{24}$/i.test(value);
 }
 //#endregion
-export { looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyOf };
+export { looksLikeOpaqueId, requireStockKey, skuDisplay, stockKeyFor, stockKeyOf };

package/dist/payment-gateway.d.mts

@@ -277,6 +277,25 @@ interface PaymentProviderPort {
    * without this cannot be auto-reconciled — the engine then RETAINS the reservation.
    */
   getRefundStatus?(query: RefundStatusQuery, command?: PaymentCommandContext): Promise<PaymentResult>;
+  /**
+   * Does this provider need the EXACT transmitted bytes, rather than the
+   * parsed body?
+   *
+   * `true` for anything that verifies an HMAC signature — Stripe signs the
+   * bytes it sent, and a re-serialized object differs in key order, spacing and
+   * unicode escaping, so a check against the parsed form can never pass.
+   *
+   * Declared by the provider rather than decided by the transport, because the
+   * transport cannot know. Handing raw bytes to every provider breaks the ones
+   * that read `payload.sessionId` — they get a string and silently see
+   * `undefined`, so the webhook resolves to no transaction and the payment
+   * never applies. Handing the parsed body to every provider breaks signature
+   * verification. Only the provider knows which it is.
+   *
+   * Absent means `false`: the historical behaviour, and correct for manual,
+   * cash and terminal providers that sign nothing.
+   */
+  readonly wantsRawBody?: boolean;
   handleWebhook(payload: unknown, headers?: Record<string, string>): Promise<WebhookEvent>;
   /**
    * Reject a forged webhook. Returning `true` unconditionally is only acceptable for a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.26.1",
+  "version": "0.26.3",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",