@classytic/primitives 0.26.2 → 0.26.3

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 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

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.2",
+  "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",