@01.software/sdk 0.48.0 → 0.51.0

package/CHANGELOG.md

@@ -1,5 +1,161 @@
 # @01.software/sdk
 
+## 0.51.0
+
+### Minor Changes
+
+- 8dd8ef7: BREAKING (0.x minor): reclassify `discounts` from the browser-public
+  `COLLECTIONS` bucket to `SERVER_ONLY_COLLECTIONS`. This is the
+  `PLAT-API-002` security/implementation-boundary correction: raw discount
+  definitions require a server credential, so a publishable-key-only raw read
+  never succeeded. Browser discount validation remains available through the
+  existing shaped `POST /api/discounts/validate` operation.
+
+  `SERVER_COLLECTIONS` continues to include `discounts` for secret-key/PAT SDK
+  clients. The browser `PublicCollection` union no longer accepts `discounts`,
+  and the raw REST route now rejects its publishable-key-only reads at the
+  server-only guard (404) rather than at collection access (403). Contract v1.23.0
+  is a compatible correction of that false callable-surface claim; this SDK
+  package change is still a pre-1.0 breaking minor under `docs/packages/release.md`.
+
+- b08250c: Add a redacted `01 doctor` app-integration diagnostic with structured Agent CLI output.
+  Its explicit app environment input is the Node-runtime-safe `--app-env-file`.
+
+  Export the canonical tenant-context path on the SDK server entry for the
+  diagnostic-only, uncredentialed CORS probe.
+
+  Print the redacted app-integration diagnostic as the next setup step only for
+  Next.js and Node targets that receive its required app credential pair.
+
+- bf6df96: BREAKING (0.x minor): Make signed webhook receivers fail closed when their
+  signing secret is missing, empty, or blank. Use `handleSignedWebhook()` for the
+  default signed path and `handleUnsignedWebhook()` only for an intentionally
+  unsigned endpoint; both new names and `SignedWebhookOptions` are exported from
+  `@01.software/sdk/webhook`, not the SDK root. The deprecated `handleWebhook()`
+  and `WebhookOptions` compatibility exports remain available at their existing
+  root and webhook-subpath locations, require signed options, and follow the same
+  fail-closed runtime behavior.
+
+  `toleranceSeconds` is now validated. It keeps its 300-second default for an
+  absent or null value, but a present value must be a number within an inclusive
+  0-86400-second range; anything else (including `Infinity`, `NaN`, a negative
+  number, a non-number, or a week-long window) is a configuration error that
+  returns 500 with a distinct tolerance message before the body is consumed.
+
+- 2ce3aa9: Add explicit embedded-admin browser and server SDK entrypoints for the receiver
+  handshake and strict assertion verification. Add the PAT-only Human CLI
+  `embedded-app show`, `configure`, and `disable` commands for single-binding
+  management.
+
+### Patch Changes
+
+- 48372ad: Synchronize the optional tenant embedded-admin binding in generated Payload
+  types. This does not add an SDK method or expose embedded session credentials.
+- 3fb53f0: Clarify PAT revocation audit metadata for trusted machine reconciliation.
+- eea3ea8: Align canonical Order and Checkout response validation with the authoritative non-empty nullable item fields.
+- 46c32e6: Ensure the packed SDK runtime declares its `jose` dependency with the portable
+  npm range used by standalone consumers.
+- a1567cc: Validate SDK release tarballs with patched package-analysis dependencies.
+- 9fecd85: Register the internal `commerce-payment-webhook-routes` collection so the SDK
+  collection registry stays in lockstep with Console. The collection is
+  Console-internal PortOne webhook routing state: it adds no SDK method, appears
+  in no public or server-only bucket, and exposes no credential.
+- 41fbcb6: Synchronize required customer, period-end, and idempotency-key fields for the
+  SDK-hidden `membership-charges` generated type. The collection remains
+  server-only and gains no public write method.
+
+## 0.50.0
+
+### Minor Changes
+
+- 0e0ab60: Add server-only full-tuple PortOne payment find and durable reconciliation methods, including atomic domain-and-receipt completion for crash-safe same-key replay.
+- 743b895: Add optional canonical `allDayStartDate` and exclusive
+  `allDayEndDateExclusive` fields to public event-range DTOs while retaining
+  instant compatibility shadows and existing TypeScript object-literal source
+  compatibility. Generated Event types also add optional canonical
+  `recurrence.untilDate` for all-day structured recurrence; existing object
+  literals that omit it remain valid.
+- 743b895: Expose `managed_refund_attestation_forbidden` as the typed commerce error for registered managed captures while preserving existing cancel-refund errors and detail placement.
+- 6b584bc: Expose the PortOne Standard V2 action's permanent non-cancelability and exact-action-only retry policy through an exact negotiated create/retrieve projection, while normalizing released Console responses for bidirectional non-lockstep compatibility. Console may deploy first because unnegotiated responses retain the released exact shape; the SDK may deploy first because it accepts and normalizes that old-server shape. Hosted create and all cancel operations remain unnegotiated. Package publication remains a separate post-merge release action.
+- 743b895: BREAKING (0.x minor): Retire the expired ADR 0025 product media compatibility
+  shims. `resolveProductMedia()` and `resolveProductGallery()` — plus their
+  compatibility-only types `MediaPointerSource`, `ResolveProductMediaInput`,
+  `ResolveProductMediaResult`, `ProductMediaSetMatchType`, `ProductMediaSetInput`,
+  `ProductGallerySource`, `ResolveProductGalleryInput`, and
+  `ResolveProductGalleryResult` — are no longer exported from the package root or
+  `utils`.
+
+  These shipped in 0.34.0 as a one-release migration aid and forwarded to the
+  canonical resolvers. Replace `resolveProductMedia()` and
+  `resolveProductGallery()` with `resolveProductSelectionMedia()` for
+  variant/option selection media and `resolveProductDisplayMedia()` for listing
+  and PDP display fallback. Pre-ADR-0025 `mediaSets` inputs have no replacement:
+  variant `images[]` subsets and `product-option-values.swatch.mediaItemId` are
+  the canonical selection sources.
+
+  Canonical selection and display precedence, result shapes, and edge-case
+  behavior are unchanged. See `packages/published/sdk/MIGRATION.md`.
+
+- bca928f: Add provider-neutral `paymentReconciliationRequired` and
+  `paymentRefundRequiresAttention` commerce notification webhook types, handlers,
+  and runtime validation.
+
+### Patch Changes
+
+- 743b895: Expose the nullable ownership scope on the generated server-only inbound
+  webhook ledger document type.
+- 743b895: Align commerce endpoint descriptors with the shared HTTP contract manifest without changing endpoint methods, paths, or error families.
+- 743b895: Expose the additive Toss capture-evidence variants in generated private
+  PaymentSession types while preserving the existing public payment API.
+- 743b895: Expose the additive durable Return-refund canonical envelope and stable
+  post-commit replay outcome in generated Payload types. Refund execution now
+  rejects changed payment identity and cross-tenant explicit-key reuse before
+  provider I/O while preserving identical cache-loss replay payloads.
+- 0c4c5fd: Synchronize generated ProviderConnection configuration-attestation fields for
+  the SDK-hidden `commerce-payment-accounts` collection. The operator-only REST
+  actions remain internal to Console and add no public SDK transport method.
+- 743b895: Standardize customer-facing Console terminology in initialization guidance and
+  generated SDK descriptions without changing runtime behavior or API contracts.
+- 743b895: Remove the unsupported minor and guardian-consent fields from generated
+  server-only Customer document types as a privacy correction. Shaped customer
+  registration and `/me` response types are unchanged.
+- 743b895: Clarify the generated webhook subscription descriptions: an empty subscription
+  list is a wildcard for ordinary collection create/update events only, and
+  commerce notifications require an explicit row for their source collection.
+  Descriptions only — no schema, runtime, or API contract change.
+- 743b895: Add optional sanitized commerce notification diagnostics fields (`eventType`,
+  `notificationEvent`, `notificationIntentId`, `notificationDedupeKey`,
+  `sourceId`) to the generated internal `WebhookDelivery` document type. The
+  collection stays internal and is not exposed through the SDK surface;
+  existing object literals remain valid because every field is optional.
+
+## 0.49.0
+
+### Minor Changes
+
+- aef44ec: Fix SDK error guards across independently bundled entrypoints and expose the guards from the client and server entries.
+- 86f74d3: Expose immutable membership subscribe-admission snapshot fields in the generated SDK types.
+- edc790e: BREAKING (0.x minor): Checkout `paymentState.activePaymentSession.provider` can
+  now be `portone`. Consumers using `@01.software/sdk` 0.45.0, 0.46.0, or 0.46.1
+  must upgrade to the 0.49.0 release produced by this minor changeset, or later,
+  before the server exposes managed PortOne sessions; otherwise
+  `checkouts.retrieve` and `checkouts.query` throw during strict response
+  validation. SDK 0.48.0's runtime decoder already accepts `portone`, but its
+  published TypeScript `CheckoutPaymentSessionRef` remains `provider: 'toss'`, so
+  0.48.0 is not the fully compatible public-contract floor. `checkouts.create` is
+  not part of this break because the current producer does not return an active
+  PortOne session reference.
+
+  Keep custom bridge recovery on the server-only exact lookup.
+
+- fa71a21: Add a fail-closed PortOne Standard V2 Toss Payments CARD browser action with a required redirect, PG-safe payment identity, and durable single-slot retry semantics.
+- 5ea6348: Expose non-commerce API reasons through `SDKError.apiReason` and the family-aware `getSDKErrorReason` accessor while preserving strict commerce error typing.
+
+### Patch Changes
+
+- cb2a742: Clarify that idempotent commerce mutation response fields do not provide exactly-once side-effect semantics.
+- 15c1024: Synchronize generated Payload types for the internal payment-kernel result and owner-commit records without exposing those collections through a public SDK collection bucket.
+
 ## 0.48.0
 
 ### Minor Changes
@@ -1043,7 +1199,7 @@ displayStatus` JSDoc comment from `Order.status`. The Console removed that
   disabled. Customer auth failures now surface the same SDK-specific error classes
   as other SDK requests instead of the previous generic API error shape.
 
-## Unreleased
+## Historical 0.34.0 migration notes
 
 ### Minor Changes
 

package/MIGRATION.md

@@ -1,5 +1,61 @@
 # @01.software/sdk Migration Notes
 
+## Product media compatibility shim retirement (#721)
+
+This is a `BREAKING (0.x minor)` change. The ADR 0025 one-release compatibility
+shims first published in `0.34.0` are removed from the package root and
+`utils`.
+
+| Removed                                                     | Replacement                                                                              |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| `resolveProductMedia(input)`                                | `resolveProductSelectionMedia(input)`, then `resolveProductDisplayMedia(input)` fallback |
+| `resolveProductGallery(input)`                              | `resolveProductSelectionMedia(input)`, then `resolveProductDisplayMedia(input)` fallback |
+| `ResolveProductMediaInput` / `ResolveProductGalleryInput`   | `ResolveProductSelectionMediaInput`                                                      |
+| `ResolveProductMediaResult` / `ResolveProductGalleryResult` | `ResolveProductSelectionMediaResult`                                                     |
+| `MediaPointerSource` / `ProductGallerySource`               | `ProductSelectionMediaSource` / `ProductDisplayMediaSource`                              |
+| `ProductMediaSetInput` / `ProductMediaSetMatchType`         | none; use variant `images[]` and `swatch.mediaItemId`                                    |
+
+```ts
+// Before
+const gallery = resolveProductGallery({
+  pool: product.images,
+  selectedVariantId: variant.id,
+  selectedOptionValueIds: valueIds,
+})
+
+// After
+const selection = resolveProductSelectionMedia({
+  productMediaPool: product.images,
+  selectedVariant: variant,
+  selectedOptionValues: optionValues,
+})
+const media =
+  selection.source === 'none'
+    ? resolveProductDisplayMedia({
+        productMediaPool: product.images,
+        featuredImage: product.featuredImage,
+      })
+    : selection
+```
+
+Use this two-step sequence when replacing either shim. Stopping after a
+selection result with `source === 'none'` would drop the previous
+featured-image/product-pool display fallback.
+
+The shims already forwarded to these resolvers, so canonical selection and
+display precedence, result shapes, and edge-case behavior are unchanged. The
+legacy-only inputs they accepted have no replacement:
+`variantFeaturedMediaItemId` and `selectedOptionValueMediaItemIds` become
+`selectedVariant.images[]` and `selectedOptionValues[].swatch`, the `legacy`
+direct-media object was already ignored, and `mediaSets` was removed from the
+product schema before the shims expired.
+
+`source` values also narrow: the shim-only `'variant_featured'`,
+`'exact_variant_set'`, `'option_value_set'`, and `'default_set'` values are gone.
+Selection media reports `'variant_media_selected'`, `'variant_media_matching'`,
+`'option_swatch'`, or `'none'`; display media reports `'featured_image'`,
+`'product_pool'`, or `'none'`.
+
 ## SDK 0.46 server-only custom-provider bridge (#3485)
 
 SDK 0.46 adds