@01.software/sdk 0.51.0 → 0.56.1

package/CHANGELOG.md

@@ -1,5 +1,132 @@
 # @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

package/README.md

@@ -779,8 +779,8 @@ Membership self-service is split by credential boundary:
 - Browser/customer JWT clients can read the signed-in customer's current or
   latest membership and request cancellation for active, trialing, or past-due
   memberships.
-- Server clients with a Secret Key can subscribe a customer after the storefront
-  has completed the delegated first charge.
+- Server clients with a Secret Key prepare a paid customer subscription before
+  the tenant's PSP executes the first charge.
 
 ```typescript
 import { createClient } from '@01.software/sdk'
@@ -801,28 +801,71 @@ const server = createServerClient({
   secretKey: process.env.SOFTWARE_SECRET_KEY!,
 })
 
-await server.memberships.subscribe({
+const prepared = await server.memberships.subscribe({
   planId: 'plan_123',
+  priceId: 'price_monthly_123',
   customerId: 'customer_123',
   customerRef: 'cus_provider_123',
-  pgPaymentId: 'pay_123',
-  amount: 9900,
-  currency: 'KRW',
   subscribeIntentKey: 'checkout-session-123',
   card: { last4: '4242', brand: 'visa' },
 })
+
+if (prepared.status === 'incomplete') {
+  await tenantPsp.charge({
+    idempotencyKey: prepared.firstCharge.idempotencyKey,
+    amount: prepared.firstCharge.amount,
+    currency: prepared.firstCharge.currency,
+  })
+  // Post the PSP outcome to Console's existing signed charge-result webhook.
+}
 ```
 
 `subscribeIntentKey` is sent as `X-Idempotency-Key`; it is not part of the JSON
-body. Replays must use the same plan, customer reference, amount, currency, and
-paid-start provider payment id snapshot as the original incomplete membership.
-Trial subscriptions may omit `pgPaymentId` because no first-period charge has
-been captured yet; paid starts must include the provider payment id that funded
-the first period.
+body. A paid response is `incomplete` and contains the immutable first-charge
+instruction. The tenant charges its PSP with `firstCharge.idempotencyKey`, then
+posts the signed outcome through the configured charge-result webhook. A trial
+response is immediately `trialing` and has no `firstCharge` field. Before a paid
+subscribe, configure an active delegated billing connection for
+the tenant; otherwise Console returns `409 conflict` without lifecycle writes.
+Do not start
+the PSP payment at or after `expiresAt`; deduplicate PSP work with
+`firstCharge.idempotencyKey`. A late paid result remains evidence but cannot
+activate the Membership, so the tenant handles any refund outside this API. Replays use
+the same plan, price, customer reference, and idempotency key while the first
+charge is pending. A replay after settlement or `expiresAt` returns `409`
+instead of a payment instruction.
 `memberships.me()` and browser `memberships.cancel()` require the customer JWT
 configured on the client. Refund webhook `refundedAmount` values are cumulative
 charge totals, not per-event deltas.
 
+### Source-aware customer groups (server only)
+
+Manage manual Customer Group membership through the shaped server API. The
+read result includes every current reason a customer qualifies, so revoking a
+manual source does not hide a still-active Membership source.
+
+```typescript
+const page = await server.customerGroups.listMembers({
+  groupId: '00000000-0000-4000-8000-000000000002',
+  limit: 100,
+})
+
+await server.customerGroups.grantMember({
+  groupId: '00000000-0000-4000-8000-000000000002',
+  customerId: '00000000-0000-4000-8000-000000000003',
+  reason: 'support-approved',
+})
+
+await server.customerGroups.revokeMember({
+  groupId: '00000000-0000-4000-8000-000000000002',
+  customerId: '00000000-0000-4000-8000-000000000003',
+})
+```
+
+Keep these calls in trusted server code. Do not mutate `customers.groups`
+directly: after source-authority activation it is a read-compatible projection
+and direct writes return `customer_groups_direct_write_retired`.
+
 ## Storefront performance defaults
 
 - **PLP:** prefer `commerce.product.listingPage()` or `useProductListingPage()` (GET `/api/products/listing-groups/query/catalog`, CDN-cacheable, card-ready). Use `listingGroupsCatalog({ productIds })` only when IDs are already known. Treat the full listing-groups response shape as a server-auth escape hatch because it can include operational stock fields. Avoid fetching a product list and then calling `detail()` per card.