@01.software/sdk 0.46.1 → 0.49.0

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # @01.software/sdk
 
+## 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
+
+- 715fe57: Expose active tenant custom-field structure in the optional version-1
+  collection schema response and preserve it through Agent CLI schema output.
+- b23608d: Preserve canonical strict commerce errors through the mounted Console handlers and public Cart, Checkout, and PaymentSession facades, including the additive handler reason vocabulary.
+
+### Patch Changes
+
+- 3096b74: Align the SDK build and test toolchain with the Payload release that removes
+  the vulnerable archived image parser dependency.
+- d98f7b3: Synchronize generated Payload types for internal settlement receipt and reconciliation evidence. These collections remain absent from every public SDK collection bucket and add no public SDK API.
+
+## 0.47.0
+
+### Minor Changes
+
+- 5a523e8: Add the managed PortOne Hosted v2 payment-session flow, provider-specific
+  checkout action parsing, CLI dispatch, and compatible event-template recovery
+  behavior. Expose the full current Hosted v2 payment-method vocabulary while
+  preserving per-connection allowlists.
+- 5e68929: Add a browser-safe shaped `community.getPost({ postId })` helper while keeping
+  raw community posts server-only, and update the generated community template to
+  consume that helper without a raw collection workaround.
+- 5a523e8: Add a server-only exact custom PaymentSession recovery lookup by provider
+  session or payment identity.
+- 5a523e8: Expose the additive `tenantPurpose` and `testExpiresAt` fields on the generated
+  `Tenant` type for time-limited, externally fenced test tenants.
+- d63c3c8: Reclassify `tenants` from the browser-public `COLLECTIONS` bucket to
+  `SERVER_ONLY_COLLECTIONS`. The tenant document denies reads without an
+  authenticated user, so a publishable key never reached it; the bucket promised a
+  browser surface that always failed at runtime. `tenant-metadata` remains the
+  browser-public tenant identity slug, and server (secret key) access to `tenants`
+  is unchanged because `SERVER_COLLECTIONS` still contains it.
+
+  Runtime behavior changes for one case, and the change is a narrowing.
+  `SERVER_ONLY_COLLECTIONS` is a runtime guard input, not only a type: the Console
+  REST route imports it and refuses a publishable-key raw read of any member. A
+  browser request to `/api/tenants` that previously reached Payload and was denied
+  by collection access now stops at that guard and returns **404** instead of 403.
+  Both were failures before and after; only the status and the point of denial
+  move. No caller could have succeeded on this path.
+
+  Type-level impact: `tenants` leaves the `PublicCollection` union, so a browser
+  client typed against it now fails to compile instead of failing at request time.
+
+### Patch Changes
+
+- 05f7b8d: Send the publishable-key raw-read safety query when listing community post
+  categories, post tags, and reaction types.
+- 2fd5f57: Synchronize generated types for the new Discount operator field descriptions (validity window, scope target requirement, usage limit minimums, unsupported each-line allocation). Comment-only; the Discount type shape and every public wire contract are unchanged.
+- 5a523e8: Synchronize generated types for the write-only provider-credential inputs on the SDK-hidden `commerce-payment-accounts` collection. The public SDK surface is unchanged: the collection remains internal, and the two added fields are virtual Admin-only inputs that are never persisted or returned.
+- 07db902: Send the publishable-key raw-read safety query when listing or resolving
+  community customer profile lists.
+- 309418a: Correct three drifted README examples. The realtime sub-path import now names
+  `RealtimeConnection`, which the package actually exports (`createRealtimeClient`
+  does not exist), and publishable-key placeholders use the real `pk01_` prefix
+  instead of `pk_xxx` / `pk_live_...`. Documentation only; no runtime or type
+  change.
+- c5e896c: Correct the generated `ShippingPolicy` field documentation. The
+  `freeShippingMinAmount` doc comment previously pointed at the shipping rates
+  array, which owns no free-shipping condition; it now names the two surfaces
+  that do — an order-amount rate row priced at 0, or an automatic
+  `free_shipping` discount with a minimum order amount. `isActive` and
+  `isDefault` gain doc comments describing their pricing side effects. Types and
+  runtime behavior are unchanged.
+
 ## 0.46.1
 
 ### Patch Changes
@@ -993,7 +1088,7 @@ displayStatus` JSDoc comment from `Order.status`. The Console removed that
   customer auth rather than public request body input. **Breaking:** **`POST
 /api/event-registrations/register` rejects `body.customer` with `400
 bad_request`;** bind customers with `Authorization: Bearer` only. See
-  `docs/events/public-api-contract.md` for migration. Guest-token lookup/cancel
+  `docs/events/public-api-reference.md` for migration. Guest-token lookup/cancel
   helpers send tokens in POST bodies. Range helpers support calendar, category,
   and tag filters aligned with the Console public range endpoint. Exported
   structural `RootClient` / `RootServerClient` keep `events` optional for

package/README.md

@@ -29,7 +29,7 @@ pnpm add @01.software/sdk
 import { createClient } from '@01.software/sdk'
 
 // Server-only entry - keep Secret Key code out of browser-facing imports
-import { createServerClient } from '@01.software/sdk/server'
+import { createServerClient, isCommerceSDKError } from '@01.software/sdk/server'
 
 // Webhook only - webhook handlers
 import {
@@ -38,7 +38,7 @@ import {
 } from '@01.software/sdk/webhook'
 
 // Realtime only
-import { createRealtimeClient } from '@01.software/sdk/realtime'
+import { RealtimeConnection } from '@01.software/sdk/realtime'
 
 // Storefront cache resource names for SSG/ISR adapters
 import { storefrontCacheResources } from '@01.software/sdk/storefront-cache'
@@ -61,8 +61,8 @@ entry.
 | Import                              | Feature(s)                                                               | Install when used                                                                                          |
 | ----------------------------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
 | `@01.software/sdk`                  | browser-safe `createClient`, commerce helpers, collection helpers, types | none                                                                                                       |
-| `@01.software/sdk/client`           | browser-safe `createClient` entry                                        | none                                                                                                       |
-| `@01.software/sdk/server`           | `createServerClient`, server-only collection, commerce, and preview APIs | none; keep `secretKey` code on the server                                                                  |
+| `@01.software/sdk/client`           | browser-safe `createClient` entry and SDK error guards                   | none                                                                                                       |
+| `@01.software/sdk/server`           | `createServerClient`, server-only APIs, and SDK error guards             | none; keep `secretKey` code on the server                                                                  |
 | `@01.software/sdk/errors`           | SDK error classes and guards                                             | none                                                                                                       |
 | `@01.software/sdk/analytics`        | browser analytics client and typed event helpers                         | none                                                                                                       |
 | `@01.software/sdk/metadata`         | SEO metadata extraction and generation helpers                           | none                                                                                                       |
@@ -92,6 +92,9 @@ Migration quick reference:
 - `createClient` remains available from `@01.software/sdk` and
   `@01.software/sdk/client`.
 - `createServerClient` must be imported from `@01.software/sdk/server`.
+- Error guards are available from the same `@01.software/sdk/client` or
+  `@01.software/sdk/server` entry as the client that throws; the root and
+  `@01.software/sdk/errors` guards also classify errors across entries.
 - React Query hooks and cache helpers must be imported from
   `@01.software/sdk/query`.
 - Product storefront cache resource helpers must be imported from
@@ -109,7 +112,7 @@ Migration quick reference:
 // Pageviews + custom events (browser)
 import { createAnalytics } from '@01.software/sdk/analytics'
 
-const analytics = createAnalytics({ publishableKey: 'pk_xxx' })
+const analytics = createAnalytics({ publishableKey: 'pk01_xxx' })
 // auto-tracks pageviews; call analytics.pageview('/custom-path') manually if needed
 analytics.track('signup', { plan: 'pro', trial: false })
 ```
@@ -137,7 +140,7 @@ type ShopEvents = {
   checkout_start: undefined // no props
 }
 
-const analytics = createAnalytics<ShopEvents>({ publishableKey: 'pk_xxx' })
+const analytics = createAnalytics<ShopEvents>({ publishableKey: 'pk01_xxx' })
 analytics.track('signup', { plan: 'pro', trial: false }) // ✅
 analytics.track('checkout_start') // ✅ no props
 // analytics.track('signpu', { plan: 'pro', trial: false }) // ❌ unknown event
@@ -145,7 +148,7 @@ analytics.track('checkout_start') // ✅ no props
 
 // Bind the map once to avoid repeating the generic:
 const create = defineAnalyticsEvents<ShopEvents>()
-const a2 = create({ publishableKey: 'pk_xxx' })
+const a2 = create({ publishableKey: 'pk01_xxx' })
 ```
 
 **React.** Use `AnalyticsProvider` + `useAnalytics()` to fire events from
@@ -256,10 +259,12 @@ without calling the Console endpoint directly:
 
 ```typescript
 const context = await server.tenant.context()
+const productSchema = await server.tenant.collectionSchema('products')
 
 console.log(context.features)
 console.log(context.collections.active)
 console.log(context.fieldConfigs)
+console.log(productSchema.collection.customFields)
 ```
 
 Pass `{ includeCounts: true }` only when document counts and webhook
@@ -267,6 +272,12 @@ configuration are needed. That mode bypasses the endpoint cache and performs
 additional collection reads. Tenant introspection is server-only and is not
 exported from the browser-safe root entry.
 
+`collection.customFields` is optional and currently applies to `customers` and
+`products`. It exposes `storagePath: 'customData'`, active definition machine
+keys and types, optional `required: true`, and select option storage values.
+Operator labels and stored document values are excluded; this schema metadata
+does not grant collection read or write access.
+
 Server-rendered preview routes can use `server.preview.detail()` with the
 short-lived preview token issued by Console:
 
@@ -714,7 +725,7 @@ Membership self-service is split by credential boundary:
 import { createClient } from '@01.software/sdk'
 import { createServerClient } from '@01.software/sdk/server'
 
-const client = createClient({ publishableKey: 'pk_live_...' })
+const client = createClient({ publishableKey: 'pk01_...' })
 
 const membership = await client.memberships.me()
 if (
@@ -725,7 +736,7 @@ if (
 }
 
 const server = createServerClient({
-  publishableKey: 'pk_live_...',
+  publishableKey: 'pk01_...',
   secretKey: process.env.SOFTWARE_SECRET_KEY!,
 })
 
@@ -1317,10 +1328,8 @@ Treat a replayed Cart result as an operation receipt: never replace a newer
 cached Cart with a lower `revision`; retrieve when response ordering is unclear.
 
 ```typescript
-import {
-  createCommerceIdempotencyKey,
-  isCommerceSDKError,
-} from '@01.software/sdk'
+import { createCommerceIdempotencyKey } from '@01.software/sdk'
+import { isCommerceSDKError } from '@01.software/sdk/errors'
 
 const checkoutIdempotencyKey = createCommerceIdempotencyKey()
 const { checkout, checkoutToken } = await client.commerce.checkouts.create({
@@ -1345,12 +1354,57 @@ if (
   // Initialize the Toss widget with the returned public client/variant fields.
 }
 
+// PortOne Hosted V2 uses the same canonical lifecycle with a provider-specific
+// HTTPS action. Redirect completion is not payment finality; retrieve the
+// PaymentSession and let Console converge from PortOne's authenticated API.
+const portOneSession = await client.commerce.paymentSessions.createPortOne({
+  checkoutToken,
+  provider: 'portone',
+  providerOptions: { profile: 'hosted_v2', paymentMethod: 'CARD_KR' },
+  idempotencyKey: createCommerceIdempotencyKey(),
+})
+if (
+  portOneSession.presentationStatus === 'actionable' &&
+  portOneSession.nextAction.type === 'portone_checkout'
+) {
+  window.location.assign(portOneSession.nextAction.checkoutUrl)
+}
+
+// Standard V2 is a distinct Browser SDK capability, not a Hosted fallback.
+// Do not treat the SDK result or mobile redirect as payment finality.
+const standardPortOneSession =
+  await client.commerce.paymentSessions.createPortOne({
+    checkoutToken,
+    provider: 'portone',
+    providerOptions: { profile: 'standard_v2', paymentMethod: 'CARD' },
+    idempotencyKey: createCommerceIdempotencyKey(),
+  })
+if (
+  standardPortOneSession.presentationStatus === 'actionable' &&
+  standardPortOneSession.nextAction.type === 'portone_sdk'
+) {
+  // PortOne V2 requires its currency constant (`CURRENCY_KRW`), not ISO `KRW`.
+  // await PortOne.requestPayment(standardPortOneSession.nextAction)
+  // Always retrieve the session afterwards; Console lookup/webhook is authoritative.
+}
+
 // Browser recovery requires the parent capability.
 await client.commerce.paymentSessions.retrieve({
   paymentSessionId: paymentSession.id,
   checkoutToken,
 })
 
+await client.commerce.paymentSessions.retrievePortOne({
+  paymentSessionId: portOneSession.id,
+  checkoutToken,
+})
+
+// The server equivalent requires a write-capable credential because the
+// provider-authoritative lookup can converge and finalize domain state.
+await server.commerce.paymentSessions.retrievePortOne({
+  paymentSessionId: portOneSession.id,
+})
+
 // Toss confirmation is a typed server-only adapter action. There is no generic
 // `confirmVerified` or provider-paid Order creation escape hatch.
 const confirmationIdempotencyKey = createCommerceIdempotencyKey()
@@ -1389,6 +1443,12 @@ 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 }`.
 
+Custom bridge sessions intentionally remain `null` in
+`checkout.paymentState.activePaymentSession`: Checkout exposes only managed
+adapters from its closed provider vocabulary. Persist the `providerSessionId`
+returned by `custom.create` and use `custom.retrieve` with that identity as the
+supported custom-lane settlement recovery path.
+
 ```typescript
 const customSession = await server.commerce.paymentSessions.custom.create({
   provider: 'my-provider',
@@ -1396,6 +1456,12 @@ const customSession = await server.commerce.paymentSessions.custom.create({
   idempotencyKey: createCommerceIdempotencyKey(),
 })
 
+// A recovery path can resolve the custom session without a 01 session ID.
+const pending = await server.commerce.paymentSessions.custom.retrieve({
+  provider: customSession.provider,
+  by: { providerSessionId: customSession.providerSessionId },
+})
+
 const verifiedCapture = await verifyMyProviderCapture({
   expectedAmount: customSession.money.amountMinor,
   expectedCurrency: customSession.money.currency,
@@ -1416,8 +1482,22 @@ const customConfirmation = await server.commerce.paymentSessions.custom.confirm(
 )
 
 console.log(customConfirmation.orderId)
+
+const recovered = await server.commerce.paymentSessions.custom.retrieve({
+  provider: customSession.provider,
+  by: { providerPaymentId: verifiedCapture.paymentId },
+})
+if (recovered.finalizationStatus === 'committed') {
+  console.log(recovered.orderId)
+}
 ```
 
+`custom.retrieve` is an exact lookup by either `providerSessionId` or
+`providerPaymentId` (exactly one). It returns only bounded recovery state:
+provider identity, session/provider/finalization status, Money, and the resolved
+`orderId`. It does not list sessions or expose raw PaymentSession relations,
+provider evidence, credentials, or fingerprints.
+
 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,
@@ -1436,6 +1516,38 @@ Canonical commerce error envelopes become `CommerceSDKError`. Branch on its
 stable `reason`, inspect `retryable`, and log `requestId`; a newer server reason
 is preserved as `reason: 'unknown_commerce_error'` plus `rawReason`.
 
+Non-commerce endpoints preserve their open-ended machine reason separately as
+`SDKError.apiReason`. Use `getSDKErrorReason(error)` when shared error handling
+must read either family: it returns the canonical commerce reason, the verbatim
+unknown commerce `rawReason`, or the non-commerce `apiReason`. Existing
+`details` payloads remain available for compatibility, but consumers no longer
+need to normalize `details.reason` and `details.body.reason` themselves.
+
+#### Idempotent mutation results are not exactly-once receipts
+
+No commerce mutation response field is a safe exactly-once gate for a
+non-idempotent side effect such as an operational alert, outbound webhook, or
+ledger entry. Use a consumer-owned durable claim keyed by the side effect's
+stable logical identity. The public webhook guide's
+[`processOnce`](https://docs.01.software/developers/webhooks) pattern uses a
+database unique key, queue idempotency store, or provider-safe send ledger.
+
+`custom.confirm` returns `alreadyConfirmed: true` when the session was already
+confirmed at observation time. It does not attribute the transition to the
+current call. The field is absent from the initial successful confirmation, so
+code that only interprets the response shape must test
+`'alreadyConfirmed' in result`, not `result.alreadyConfirmed === false`. That
+presence check is still not a side-effect gate: when the initial commit succeeds
+but its response is lost, a retry returns `alreadyConfirmed: true` and would
+otherwise silently miss the transition.
+
+Likewise, the `orders.cancelOrder` fields `cancelCommitted` and
+`alreadyCanceled` are domain effect dispositions, not transport replay markers.
+A same-key retry replays the cached initial 2xx body byte-for-byte and can
+therefore return the original `cancelCommitted: true` again. Neither field says
+whether the response was replayed or whether an external side effect has already
+run.
+
 ### Commerce Orders (post-placement operations)
 
 Provider-paid `orders.create`, `orders.confirmPayment`, and ordinary
@@ -1693,6 +1805,25 @@ replacement API. Pass an empty list to clear codes. Singular `admission`,
 Browser `mine()`/`merge({ guestCartToken })` derive customer identity from the
 JWT; server calls require an explicit `customerToken`.
 
+### Community public reads
+
+Use the shaped `community` helpers for browser/customer community screens. A
+publishable key is sufficient for list and detail reads; a customer JWT may be
+attached for the same response shape, but no secret key is needed.
+
+```typescript
+const page = await client.community.listPosts({ limit: 20 })
+const post = await client.community.getPost({ postId: page.docs[0].id })
+
+if (!post) {
+  // Missing, hidden, and cross-tenant posts are intentionally indistinguishable.
+}
+```
+
+`getPost()` returns the allowlisted `CommunityPost` DTO and resolves `404
+not_found` to `null`. Raw `client.collections.from('posts')` remains
+server-only; do not use it in browser or customer template code.
+
 ### Community Moderation (ServerClient-only)
 
 Available only on ServerClient via `server.community.moderation.*`.
@@ -1802,7 +1933,7 @@ Source of truth: `packages/published/sdk/src/core/collection/const.ts` (`COLLECT
 
 | Category           | Browser-public generic collections                                                                                                                                 |
 | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Tenant             | `tenants`, `tenant-metadata`                                                                                                                                       |
+| Tenant             | `tenant-metadata`                                                                                                                                                  |
 | Products           | `products`, `product-variants`, `product-options`, `product-option-values`, `product-categories`, `product-tags`, `product-collections`, `markets`, `brands`       |
 | Customers          | `customer-profiles`                                                                                                                                                |
 | Commerce           | `discounts`, `shipping-policies`, `shipping-zones`                                                                                                                 |