@01.software/sdk 0.45.0 → 0.46.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @01.software/sdk
 
+## 0.46.0
+
+### Minor Changes
+
+- 8742373: Add a server-only custom PaymentSession bridge with typed create and confirm
+  operations, strict safe projections, exact-body optional HMAC proof signing,
+  and shared OpenAPI transport parity.
+
 ## 0.45.0
 
 ### Minor Changes

package/MIGRATION.md

@@ -1,5 +1,24 @@
 # @01.software/sdk Migration Notes
 
+## SDK 0.46 server-only custom-provider bridge (#3485)
+
+SDK 0.46 adds
+`createServerClient().commerce.paymentSessions.custom.create/confirm` for the
+existing bounded custom PaymentSession endpoints. This is additive and
+server-only: browser clients and the package root expose neither the namespace
+nor its custom types.
+
+Create requires a durable header idempotency key and returns only
+`{ id, provider, providerSessionId, money }`. The caller independently verifies
+its provider API response or signed webhook, then confirms the exact provider
+session/payment/event identities and captured Money. Where tenant policy
+requires custom-payment HMAC, pass `createProof(rawBody)` as the confirm option;
+it signs the exact JSON bytes sent by the SDK.
+
+This bridge does not restore `orders.create`, `orders.confirmPayment`, or
+`orders.updateTransaction`, and it is not adapter support, refund authority, or
+a manual/offline pending-order placement API.
+
 ## SDK 0.45 canonical commerce surface (#2375)
 
 Target release: `0.45.0`. This is a `BREAKING (0.x minor)` release.

package/README.md

@@ -1383,6 +1383,49 @@ const checkoutPage = await server.commerce.checkouts.query({
 void checkoutPage.nextCursor
 ```
 
+For a provider that is not backed by a first-party adapter, trusted server code
+can use the bounded custom bridge. The caller must first verify the provider's
+authoritative API response or signed webhook, then report the exact captured
+identity and Money. The create response is intentionally limited to
+`{ id, provider, providerSessionId, money }`.
+
+```typescript
+const customSession = await server.commerce.paymentSessions.custom.create({
+  provider: 'my-provider',
+  checkoutToken,
+  idempotencyKey: createCommerceIdempotencyKey(),
+})
+
+const verifiedCapture = await verifyMyProviderCapture({
+  expectedAmount: customSession.money.amountMinor,
+  expectedCurrency: customSession.money.currency,
+})
+
+if (!verifiedCapture.ok) throw new Error('Provider capture was not verified')
+
+const customConfirmation = await server.commerce.paymentSessions.custom.confirm(
+  {
+    provider: customSession.provider,
+    providerSessionId: customSession.providerSessionId,
+    providerPaymentId: verifiedCapture.paymentId,
+    providerEventId: verifiedCapture.eventId,
+    amount: customSession.money.amountMinor,
+    currency: customSession.money.currency,
+    occurredAt: verifiedCapture.occurredAt,
+  },
+)
+
+console.log(customConfirmation.orderId)
+```
+
+If the tenant's custom-provider policy requires HMAC, pass
+`{ createProof(rawBody) }` as the second argument to `custom.confirm`. The
+callback receives the exact JSON bytes the SDK sends and returns `{ timestamp,
+signature }`; signature headers are redacted from SDK debug output. This is not
+a generic “mark paid” API, adapter support, refund authority, or a manual/offline
+pending-order flow. Use Draft Orders for current back-office manual pending
+orders; storefront manual/offline placement is a separate capability.
+
 `checkoutToken` is returned only alongside Checkout creation; ordinary Checkout
 DTOs never echo the bearer capability. Browser `checkouts.retrieve` and
 PaymentSession retrieve/cancel calls accept that token. Server
@@ -1396,10 +1439,12 @@ is preserved as `reason: 'unknown_commerce_error'` plus `rawReason`.
 ### Commerce Orders (post-placement operations)
 
 Provider-paid `orders.create`, `orders.confirmPayment`, and ordinary
-`orders.updateTransaction` were removed in SDK 0.45. No general manual Order API
-is exposed. After a PaymentSession commits an Order, trusted server code can use
-the remaining fulfillment, cancellation, and return operations. Customer order
-reads remain available through `client.commerce.orders.listMine()`.
+`orders.updateTransaction` were removed in SDK 0.45. The server-only custom
+PaymentSession bridge above does not restore those methods or expose a general
+manual Order API. After a PaymentSession commits an Order, trusted server code
+can use the remaining fulfillment, cancellation, and return operations.
+Customer order reads remain available through
+`client.commerce.orders.listMine()`.
 
 The SDK root no longer exports raw generated `Order`, `Transaction`, `Cart`, or
 `CartItem` Payload documents. Use the canonical `PublicOrder` / `PublicCart`

package/dist/client.cjs

@@ -403,6 +403,11 @@ function redactSensitiveHeaders(headers) {
       redacted["x-preview-token"]
     );
   }
+  if (redacted["x-custom-payment-signature"]) {
+    redacted["x-custom-payment-signature"] = redactSensitiveHeader(
+      redacted["x-custom-payment-signature"]
+    );
+  }
   return redacted;
 }
 function getErrorSuggestion(status) {
@@ -1396,6 +1401,14 @@ var COMMERCE_ENDPOINTS = {
     create: endpoint("POST", "/api/payment-sessions/create"),
     retrieve: endpoint("POST", "/api/payment-sessions/retrieve"),
     cancel: endpoint("POST", "/api/payment-sessions/cancel"),
+    custom: {
+      create: sharedEndpoint(
+        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.custom.create
+      ),
+      confirm: sharedEndpoint(
+        COMMERCE_ENDPOINT_OPERATIONS.paymentSessions.custom.confirm
+      )
+    },
     server: {
       create: endpoint("POST", "/api/payment-sessions/server/create"),
       retrieve: endpoint("POST", "/api/payment-sessions/server/retrieve"),