@01.software/sdk 0.46.1 → 0.48.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # @01.software/sdk
 
+## 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 +1061,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

@@ -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'
@@ -109,7 +109,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 +137,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 +145,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 +256,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 +269,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 +722,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 +733,7 @@ if (
 }
 
 const server = createServerClient({
-  publishableKey: 'pk_live_...',
+  publishableKey: 'pk01_...',
   secretKey: process.env.SOFTWARE_SECRET_KEY!,
 })
 
@@ -1345,12 +1353,39 @@ 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)
+}
+
 // 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()
@@ -1396,6 +1431,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 +1457,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,
@@ -1693,6 +1748,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 +1876,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`                                                                                                                 |