@01.software/sdk 0.49.0 → 0.56.1

package/CHANGELOG.md

@@ -1,5 +1,261 @@
 # @01.software/sdk
 
+## 0.56.1
+
+### Patch Changes
+
+- d7ac700: Sync the shipping policy free-shipping field description from Console schemas.
+- e15348a: The generated `Article` type now documents `slug` as the URL slug that stays fixed once an article is created.
+- c3ab3b9: Sync the product slug field description, which now notes that the slug is fixed after creation.
+
+## 0.56.0
+
+### Minor Changes
+
+- bab54b6: BREAKING (0.x minor): Make paid membership subscribe return a first-charge prepare instruction instead of accepting a caller payment identifier. Tenant billing now uses the returned idempotency key and the existing signed charge-result flow.
+
+## 0.55.1
+
+### Patch Changes
+
+- 9ee5438: Synchronize generated Payload event hold and internal TicketPurchase draft types
+  with the Console schema.
+
+## 0.55.0
+
+### Minor Changes
+
+- 3ddc653: BREAKING (0.x minor): Generated Membership payment method and credential types
+  now expose delegated-only fields. Legacy connect and backend-charge metadata is
+  removed from the SDK type surface; stored database columns remain intact.
+
+### Patch Changes
+
+- 4732259: Sync event registration provenance fields from Console schemas.
+- 313ed5b: Synchronize generated Payload membership-charge types with normalized terminal
+  decline evidence fields.
+
+## 0.54.2
+
+### Patch Changes
+
+- c040018: Add typed webhook support for thin membership lifecycle notifications.
+
+## 0.54.1
+
+### Patch Changes
+
+- d09060b: Add generated internal usage-attribution fields for Project environment billing evidence.
+
+## 0.54.0
+
+### Minor Changes
+
+- 1e2f5ce: Add server-only source-aware Customer Group member listing, grant, and revoke helpers.
+
+### Patch Changes
+
+- 5d183fd: Add optional Checkout and Order discount snapshot fields for canonical
+  condition digests and private customer-eligibility evidence.
+
+## 0.53.0
+
+### Minor Changes
+
+- b3b3878: Synchronize generated Payload types for Project-scoped subscription authority.
+  `Project.authorityMode` now includes `project-billing`, and `Subscription` gains
+  an optional `project` relationship while retaining its required Live tenant
+  anchor.
+
+  This is additive only: no collection becomes publicly addressable, existing
+  tenant identifiers keep their meaning, and tenant-scoped SDK behavior is
+  unchanged.
+
+## 0.52.2
+
+### Patch Changes
+
+- e808fb7: Improve PaymentSession provider-mismatch cancellation recovery guidance after
+  validating the complete actual-provider response and cancellation state.
+
+  **BREAKING (0.x minor):** `01 payment-session retrieve` and `01 payment-session cancel` now require `--provider toss` or `--provider portone`; the CLI no longer assumes Toss when it is omitted.
+
+## 0.52.1
+
+### Patch Changes
+
+- 1f62cb3: Keep managed payment-provider response validation aligned with the SDK's public checkout provider type.
+- 2848ab8: Remove retired stg smoke reconciliation wording from the generated PAT type mirror.
+
+## 0.52.0
+
+### Minor Changes
+
+- ebd2544: Synchronize generated types for the Project environment expand phase (ADR 0056). A `Project` interface is added, and `Tenant` gains five optional, nullable fields describing its Project/environment binding: `project`, `environmentKind`, `environmentGeneration`, `environmentState`, and `environmentIsCurrent`.
+
+  Additive only. Every new field is optional, no existing field becomes nullable, and `tenantId` keeps its exact meaning. The `projects` slug is deliberately absent from `COLLECTIONS`, `SERVER_ONLY_COLLECTIONS`, and `INTERNAL_COLLECTIONS`, so no collection is newly addressable and no runtime behavior changes; the additive public client context is owned by a later issue.
+
+### Patch Changes
+
+- 9620154: Keep generated SDK collection metadata and Payload types aligned with the Console customer-group grant authority.
+
+## 0.51.2
+
+### Patch Changes
+
+- 6f08721: Align the generated Order field order with the Admin Panel order information tab.
+- 18c9eb7: Synchronize the generated Payload types after the Console `customers`
+  collection declares `email` before `name`: `Customer` and `CustomersSelect`
+  change property order only. This does not add, remove, or retype any SDK
+  surface.
+- 6d2e6ac: Update the audited Next runtime dependencies used by SDK verification and the
+  published app templates.
+- 7eb25b2: Payload CMS 3.89.0 선행 업그레이드에 맞춰 SDK 검증용 개발 의존성을 갱신하고,
+  upstream 실제 수정 전까지 보상 통제를 유지합니다.
+
+## 0.51.1
+
+### Patch Changes
+
+- ff7a716: Serialize persisted `CustomerAuth` refresh rotation across browser contexts and make the persisted session atomic.
+
+  The canonical session now lives in a single versioned JSON record at `<key>:session` holding the access/refresh pair plus a monotonic revision. Writing the pair in one store operation removes the torn write that could publish a new access token beside an already-consumed refresh token, and every write re-reads the record first and carries forward the field it does not change, which keeps a stale instance from carrying its own outdated counterpart into the write. That merge is best-effort, not a compare-and-swap.
+
+  Refresh-token rotation — and only rotation — is serialized through a Web Locks lease keyed by the storage key plus the canonical API/tenant identity (equivalent URL spellings share one namespace; token material never appears in a lease name). Inside the lease the rotation re-reads canonical state and classifies it on the credential it will present, so it never replays a credential the record already replaced, never strands the successor it already paid for, and preserves an access token another context deliberately replaced while committing the successor refresh in the same write. `getToken()` / `getRefreshToken()` re-read canonical state before use, so another tab's rotation or logout is observed before the next credential use.
+
+  Limits, stated rather than implied: Web Storage has no compare-and-swap, so the read preceding a write is not atomic with it, and the synchronous mutators (`logout`, `setToken`, `setRefreshToken`) cannot await the lease. A commit landing inside that window is lost by ordering — including a counterpart the merge just read, which is then republished stale. Those interleavings are last-writer-wins; server-side single-use rotation and refresh-family reuse detection remain the only authority. Browsers without Web Locks, a throwing `navigator.locks` accessor, a failed acquisition, an expired bounded wait, or storage that denies access all degrade to a per-instance or memory-only session while still presenting the canonical credential.
+
+  Storage compatibility: `<key>` still holds the current access token as a single-value publication for code that reads it directly, and an existing pair under the older `<key>` / `<key>:refresh` layout is migrated on first read — but only while `<key>:session` is absent. `logout()` writes a cleared record even against empty storage, so an ended session cannot be migrated back out of the older keys. The older refresh entry is retired before any newer access token is mirrored, so those two are never published together, and if that retirement fails the newer access token is not mirrored beside it; such a reader falls back to the bearer refresh path, and server-side reuse detection resolves an older pair it may still hold. A record this version cannot interpret fails closed to a memory-only session rather than being reinterpreted through the older keys. A context running an SDK version that predates the record is outside the coordination guarantee. `persist: false` and SSR behavior are unchanged.
+
+## 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
@@ -1070,7 +1326,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