@01.software/sdk 0.51.0 → 0.65.0

package/README.md

@@ -50,7 +50,6 @@ import { receiveEmbeddedAdminSession } from '@01.software/sdk/embedded-admin'
 import { verifyEmbeddedAdminSession } from '@01.software/sdk/embedded-admin/server'
 
 // Components - sub-path imports per domain
-import { Analytics } from '@01.software/sdk/analytics/react'
 import { RichTextContent } from '@01.software/sdk/ui/rich-text'
 import { Image } from '@01.software/sdk/ui/image'
 import { FormRenderer } from '@01.software/sdk/ui/form'
@@ -70,7 +69,6 @@ entry.
 | `@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                                                                                                       |
 | `@01.software/sdk/webhook`               | webhook handlers, event guards, and webhook types                        | none                                                                                                       |
 | `@01.software/sdk/query`                 | React Query hooks, cache helpers, `getQueryClient`                       | `@tanstack/react-query`, `react`, `react-dom`                                                              |
@@ -78,7 +76,6 @@ entry.
 | `@01.software/sdk/storefront-cache`      | product storefront cache resource name helpers                           | none                                                                                                       |
 | `@01.software/sdk/embedded-admin`        | embedded app browser handshake and shared protocol types                 | none                                                                                                       |
 | `@01.software/sdk/embedded-admin/server` | assertion verification and JWKS loading                                  | none; keep receiver session creation on the server                                                         |
-| `@01.software/sdk/analytics/react`       | `<Analytics />`                                                          | `react`, `react-dom`                                                                                       |
 | `@01.software/sdk/ui/rich-text`          | `RichTextContent`, `StyledRichTextContent`                               | `react`, `react-dom`, `@payloadcms/richtext-lexical`                                                       |
 | `@01.software/sdk/ui/form`               | `FormRenderer`                                                           | `react`, `react-dom`                                                                                       |
 | `@01.software/sdk/ui/code-block`         | `CodeBlock`, `highlight`                                                 | `react`, `react-dom`, `shiki`, `hast-util-to-jsx-runtime`                                                  |
@@ -87,6 +84,18 @@ entry.
 | `@01.software/sdk/ui/video`              | `VideoPlayer`                                                            | `react`, `react-dom`, `@mux/mux-player-react`                                                              |
 | `@01.software/sdk/ui/image`              | `Image`                                                                  | `react`, `react-dom`                                                                                       |
 
+### Video playback admission
+
+On your server, call `createServerClient(...).video.playback(video.id)` after
+applying your viewer's content-access policy. Pass its `streamUrl` to
+`<VideoPlayer video={video} streamUrl={streamUrl} />`.
+The bearer URL expires after two hours; refresh it before the deadline during
+long playback or after a long pause. Free playback uses a quota-metered gateway and can return 403 when the
+monthly allowance is exhausted or 503 when admission cannot be verified.
+`muxPlaybackId`, `getVideoStreamUrl`, and raw Mux thumbnail/MP4 helpers are
+legacy public-ID paths for unmigrated paid assets. A signed asset's retained
+`muxPlaybackId` is historical usage evidence and is not a playable URL.
+
 `CanvasRenderer` renders reserved `shape` nodes (`terminator`, `process`,
 `decision`, `io`, `subprocess`) with first-party SVG geometry, without a tenant
 catalog row or QuickJS template.
@@ -162,91 +171,7 @@ Migration quick reference:
   self-contained and must not import private contracts; Console code should
   import shared helpers from contracts directly.
 
-### Analytics
-
-```typescript
-// Pageviews + custom events (browser)
-import { createAnalytics } from '@01.software/sdk/analytics'
-
-const analytics = createAnalytics({ publishableKey: 'pk01_xxx' })
-// auto-tracks pageviews; call analytics.pageview('/custom-path') manually if needed
-analytics.track('signup', { plan: 'pro', trial: false })
-```
-
-**Custom events must be registered first.** Each custom event name, its
-dimensions, and any enum/boolean value sets are defined per workspace in
-Console → Analytics. An unregistered or mistyped event is accepted by the
-browser (200/204) and then **silently dropped server-side** — no client error.
-Register the event before firing it.
-
-**Typed events (compile-time safety).** Declare an event map as a plain `type`
-(do **not** `extends AnalyticsEventMap` — an index signature would defeat
-typo detection) and pass it as the generic. Mistyped names and out-of-enum
-values then fail to compile:
-
-```typescript
-import {
-  createAnalytics,
-  defineAnalyticsEvents,
-} from '@01.software/sdk/analytics'
-
-type ShopEvents = {
-  signup: { plan: 'free' | 'pro'; trial: boolean }
-  add_to_cart: { productId: string; price: number }
-  checkout_start: undefined // no props
-}
-
-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
-// analytics.track('signup', { plan: 'team', trial: false }) // ❌ enum violation
-
-// Bind the map once to avoid repeating the generic:
-const create = defineAnalyticsEvents<ShopEvents>()
-const a2 = create({ publishableKey: 'pk01_xxx' })
-```
-
-**React.** Use `AnalyticsProvider` + `useAnalytics()` to fire events from
-components. The provider auto-tracks pageviews like `<Analytics/>` and owns one
-instance for its subtree:
-
-Reusing the `ShopEvents` type from above:
-
-```tsx
-import {
-  AnalyticsProvider,
-  useAnalytics,
-} from '@01.software/sdk/analytics/react'
-
-function Root() {
-  return (
-    <AnalyticsProvider>
-      <App />
-    </AnalyticsProvider>
-  )
-}
-
-function SignupButton() {
-  const { track, pageview } = useAnalytics<ShopEvents>()
-  // pageview(path?) is available for manual SPA pageviews; the provider already auto-tracks pageviews
-  return (
-    <button onClick={() => track('signup', { plan: 'pro', trial: false })}>
-      Sign up
-    </button>
-  )
-}
-```
-
-`<Analytics />` remains available as a pageview-only mount helper for apps that
-do not fire custom events from components.
-
-**Send mode.** `mode: 'auto'` (default) suppresses sends on local hosts
-(`localhost` / `127.0.0.1` / `*.local`); `'production'` always sends, even
-locally; `'development'` never sends. The hosted `<script>` snippet uses the
-same vocabulary via `window.__01_analytics__.mode` or `data-mode`; its legacy
-`captureOnLocalhost: true` flag is equivalent to `mode: 'production'` and is
-honored only when `mode` is unset.
+For website analytics, integrate an external tool such as GA4, Plausible, or Vercel Analytics in your own frontend. The SDK no longer provides analytics collection helpers.
 
 ## Getting Started
 
@@ -390,11 +315,26 @@ storefronts can render time-sensitive copy.
 
 `content.galleryItems.list()` calls `GET /api/gallery-items/storefront`;
 gallery item DTOs include title, description, content, gallery reference, and
-image media. Tenant, metadata, draft status, and storage/provider internals are
+optional `mediaType` (`image` or `video`). Treat an omitted `mediaType` as `image`
+for older responses. Image items retain `image` media. Video items include a
+safe `video` descriptor with `availability: 'ready' | 'processing' | 'unavailable'`,
+and may include a video document `id` and uploaded `thumbnail`. Disabled or
+plan-blocked video features, missing/deleted targets, and failed videos return
+only `{ availability: 'unavailable' }`, preserving each item's position and
+pagination. The image relationship is not used as a video poster.
+Tenant, metadata, draft status, and storage/provider internals are
 omitted. Gallery item reads require either `gallerySlug` or `galleryId`; prefer
 `gallerySlug` for storefront routes. The default gallery item sort is `manual`,
 matching curator order from the Console.
 
+The descriptor's `ready` state is preparation metadata, not playback authority.
+Your application server must verify that the requested video belongs to the
+published gallery/item and apply its viewer policy before calling
+`server.video.playback(video.id)`. Deliver that response's `streamUrl` to the
+player; playback rechecks the current tenant, video state, and feature/plan.
+Keep server credentials on the application server. Gallery responses do not
+include playback URLs, provider IDs, or tokens.
+
 Both helpers return Payload-style pagination (`docs`, `totalDocs`, `page`,
 `limit`, etc.). `limit` is bounded server-side to `1..100`; invalid query,
 publishable-key, feature, rate-limit, and server errors surface through the
@@ -779,8 +719,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 +741,115 @@ 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`.
+
+### External Customer links (server only)
+
+`server.externalCustomerLinks` connects a platform Customer to an external
+Customer ID within the namespace and environment derived from an active
+integration registration. Your app supplies a normalized stable `accountScope`
+to reserve identity; namespace-bound keys authorize all accounts in that
+namespace, and account scope is not an account ACL. All six methods (`connect`,
+`get`, `list`,
+`unlink`, `capturePreviousState`, `clearPreviousState`) require server
+credentials and Customer read or write scope.
+
+```typescript
+const link = await server.externalCustomerLinks.connect({
+  integrationId,
+  customerId,
+  accountScope,
+  externalCustomerId: 'contact-123',
+  requestId: crypto.randomUUID(),
+})
+const capture = {
+  integrationId,
+  customerId,
+  linkId: link.id,
+  requestId: crypto.randomUUID(),
+  expectedVersion: link.version,
+  previousState: { tier: 'silver' },
+}
+await server.externalCustomerLinks.capturePreviousState(capture)
+// After an interrupted response, retry this exact request, including expectedVersion.
+```
+
+The bounded previous state accepts up to 16 flat string/number/boolean/null
+fields, 512 characters per string, and 2048 UTF-8 JSON bytes. It records only
+what your server supplies; the platform performs no external provider I/O.
+Before restoring provider state, check the current active owner with
+`list({ integrationId, accountScope, externalCustomerId, state: 'active' })`
+and evaluate whether the restoration is still appropriate. Lists accept optional Customer,
+account scope, external ID, and state filters (external ID requires account
+scope), `limit` (default 25, maximum 100), and `afterId`;
+use `nextCursor` for the next page. Unlink and clear also require a fresh
+request UUID and the current version; exact retries retain the original values.
+A privacy-erased snapshot has state `erased`, null `externalCustomerId`, and
+null `previousState`. Keep these calls and snapshots in trusted server code.
+
 ## 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.
@@ -1094,6 +1121,49 @@ await server.collections.from('articles').updateMany(where, data)
 await server.collections.from('articles').removeMany(where)
 ```
 
+Collection `find`, `count`, `updateMany`, and `removeMany` share filter validation.
+`equals: null` and `not_equals: null` retain their null meaning through Payload
+REST, including text fields; null-containing filters use Payload's native JSON
+`where` query parameter. Other filters keep bracketed encoding. The SDK throws
+`ValidationError` before a request for undefined values, null outside those two
+operators, empty condition objects, empty arrays (including `and`/`or`), nesting
+beyond 10 levels, and arrays with more than 1000 elements. Omit `where` for an
+unfiltered read. For a dynamically empty ID list, return an empty result before
+calling the SDK rather than passing `in: []`. False, zero, empty strings, and
+Date conditions remain valid.
+
+Check your bulk filters carefully: calls that previously failed with HTTP 400
+now perform updates or deletions. Large `in`/`not_in`
+lists can exceed URL length limits (around 250 UUIDs); split work into smaller
+batches. For `not_in`, keep the full exclusion condition in every batch rather
+than splitting the exclusions across separate mutations.
+
+### Orders update compatibility
+
+Orders accept one-document updates only. Admin Panel bulk edits and generic
+`server.collections.from('orders').updateMany(...)` are rejected before any
+Order changes with HTTP 400 (`errors[0].data.code: order_bulk_update_unsupported`).
+Use `update(orderId, data)` for an unconditional edit. For a conditional update,
+keep the entire where predicate in the raw `PATCH /api/orders` query and set
+`limit=1`; send the field data as the body. Local API callers use numeric
+`limit: 1`, or a strict UUID `id.equals` that bounds the complete predicate.
+An ID in only one OR branch is insufficient. SDK `updateMany` has no limit
+option and is not a supported Orders CAS path.
+
+A conditional miss returns `docs: [], errors: []`. A collected hook failure
+instead returns HTTP 500 (`errors[0].data.code: order_update_failed`), with a
+localized message and rollback of the supported single operation. Access and
+tenant checks remain in force. Do not replace a conditional update with an
+unconditional ID update or automatically retry payment capture. Separate
+per-order edits do not promise atomic success across the whole selection.
+
+Console Local API Orders updates also require a live transaction. Setting
+`disableTransaction: true` without a live external transaction rejects both
+top-ID and where updates before writes with HTTP 400
+(`errors[0].data.code: order_transaction_required`). Remove that option to
+use Payload's normal transaction, or pass a live external transaction;
+a request transaction ID by itself is not sufficient.
+
 ### API Response Types (Payload Native)
 
 The SDK returns Payload CMS native response types without wrapping:
@@ -1296,7 +1366,6 @@ const { token, customer } = await client.customer.auth.login({
 // Profile & token management
 const profile = await client.customer.auth.me()
 client.customer.auth.isAuthenticated()
-client.customer.auth.logout()
 
 // Authenticated customer's own orders (Client-only)
 const orders = await client.commerce.orders.listMine({
@@ -1305,12 +1374,22 @@ const orders = await client.commerce.orders.listMine({
   financialStatus: 'paid',
 })
 
+await client.customer.auth.logoutAsync()
+
 // Password
 await client.customer.auth.forgotPassword('john@example.com')
 await client.customer.auth.resetPassword(token, newPassword)
 await client.customer.auth.changePassword(currentPassword, newPassword)
 ```
 
+`logoutAsync()` revokes the direct refresh-token family on the server and clears
+local credentials even when the request fails. Handle a rejection as incomplete
+server revocation. The older synchronous `logout(): void` clears local state
+immediately but cannot revoke the server session. `useCustomerLogout()` awaits
+the server request and clears authenticated customer query data on success or
+failure. An issued access token can remain valid for up to 15 minutes; legacy
+bearer-only refresh remains a separate compatibility path.
+
 `forgotPassword()` keeps the same SDK signature in both delivery modes. A
 tenant administrator chooses either backward-compatible signed webhook
 delivery or platform-managed email in the Console customer-authentication
@@ -1319,6 +1398,31 @@ the platform appends the `token` query parameter and sends through the verified
 tenant sender or the platform fallback. Do not add reset tokens or dynamic
 redirect URLs to the SDK call.
 
+#### Self-withdrawal
+
+A signed-in customer with a local password can withdraw using their current
+password. With an authenticated client:
+
+```ts
+const { withdrawnAt } = await client.customer.auth.withdraw(currentPassword)
+```
+
+This calls `POST /api/customers/withdraw` with the publishable key and Customer
+JWT. Success archives the account immediately and clears the SDK's local
+credentials. Clear any application-owned session cookies and customer cache as
+well. Archived accounts cannot use existing sessions or authenticate again.
+Withdrawal preserves order, payment and membership-charge history; it does not
+erase personal data or free the email for a new registration.
+
+Branch on `SDKError.apiReason`: `active_membership_exists` (409) requires the
+membership to end first, including scheduled cancellations still in an active
+status; `reauthentication_unavailable` (409) means no local password is set and
+the customer should contact the tenant administrator. Incorrect passwords use
+the shared login attempt counter and temporary lock (`account_locked`, 423).
+Refusal leaves the SDK credentials intact. Server keys cannot withdraw on a
+customer's behalf. Operator restore continues to follow the existing archive
+rules; the withdrawal timestamp is retained.
+
 ### Market discovery
 
 Discover a tenant's active buyer markets and resolve the default market. These
@@ -1970,6 +2074,28 @@ await server.community.moderation.banCustomer({ customerId, isPermanent?, banned
 await server.community.moderation.unbanCustomer({ customerId })
 ```
 
+### Installation credentials (server only)
+
+`createServerClient().installationCredentials` stores one bounded ciphertext
+for a registered non-payment OAuth installation. A tenant administrator must
+register the installation and explicitly bind the server key; an ordinary
+`sk01_` key or external-effect claim grant is insufficient. Encrypt before
+`create`, decrypt only in your server, and keep OAuth and provider calls there.
+
+```typescript
+const current = await server.installationCredentials.get({ installationId })
+const next = await server.installationCredentials.replace({
+  installationId,
+  expectedVersion: current.version,
+  ciphertext: newlyEncryptedCredential,
+})
+```
+
+Replacement uses a version condition; after an uncertain result, read back
+before retrying. `dispose` clears the platform copy but does not revoke a
+credential already read by your server. A platform database restore requires
+re-authorization before older installations become readable again.
+
 ### Webhook
 
 Webhooks created in Console start inactive. Use this setup order so no event is
@@ -2243,7 +2369,7 @@ SOFTWARE_SECRET_KEY=sk01_...  # Server only — opaque API key from Console
 
 > `secretKey` may be an `sk01_...` API key or a `pat01_...` personal access token. Server SDK calls must also send the matching `publishableKey`; PAT tenant selection is pinned server-side, and callers must not send `X-Tenant-Id`.
 
-API keys created without explicit scopes use the default `['read', 'write']`. Console API-key creation can request narrower `scopes[]`; in the first explicit-scope slice tenant admins may grant only `read` and `write`. Higher-authority scopes such as `webhook`, `analytics`, and `super-admin` require platform authority and otherwise return `scope_grant_forbidden`.
+API keys created without explicit scopes use the default `['read', 'write']`. Console API-key creation can request narrower `scopes[]`; tenant admins may grant only `read` and `write`. `webhook` and `super-admin` require a super-admin session. Requests containing the retired `analytics` scope, alone or mixed, are rejected for every role. Previously issued keys keep their identity; an analytics-only key has no effective access, while a mixed key keeps its other scopes.
 
 > **SDK 0.9.0**: Server auth now uses opaque bearer tokens (`sk01_...`). Generate API keys from the Console. `createServerToken`, `createApiKey`, and `parseApiKey` are no longer part of the SDK surface.