@xkova/sdk 0.1.0-alpha.2 → 0.1.0-alpha.3

package/README.md

@@ -197,26 +197,17 @@ For your own OIDC provider, use `beginAuthorization` and
 code unless your integration explicitly assigns that exchange to XKOVA. Both
 sign-in paths use the same XKOVA session and store contracts.
 
-### Sandbox demo sign-in
-
-For a sandbox application explicitly enabled for demo sign-in, call
-`completeSandboxDemoAuthorization({ state: start.state, transactionStore })`
-after `beginHostedAuthorization`. The SDK obtains the capability and exact
-callback from the server-held transaction, validates the returned callback and
-expiry, and returns `{ callbackUrl, expiresAt }`. Complete that callback through
-`completeHostedAuthorization` with the original browser flow cookie. The API
-reserves a demo account for the session. This operation is not
-available to ordinary tenant applications or production workspaces, and it
-accepts no member, email, wallet, or callback selector.
-
-Keep the same pending reservation and transaction after an ambiguous admission
-failure. Repeating the method uses the same idempotency key and recovers the
-same demo account reservation. The method never retries automatically.
-`isDefinitiveXKOVASandboxDemoAdmissionFailure(error)` identifies confirmed
-rejection before an account was reserved; network, malformed-response, and
-unknown server failures can leave the reservation outcome uncertain.
-API errors retain their status, correlation ID, and Retry-After. Both admission
-and session requests reject HTTP redirects.
+### Local development
+
+The SDK accepts HTTP API URLs, browser origins, callbacks, and storage URLs on
+`localhost` and `127.0.0.1`. Remote hosts require HTTPS. Register each origin
+and callback with its exact scheme, host, port, and path. These two local hosts
+are distinct origins; cookies and browser storage are not shared between them.
+
+For local passkeys, serve the authentication page on `localhost` and use
+`localhost` as its relying-party ID. An IP address cannot be a passkey
+relying-party ID. Keep API keys and member sessions in your BFF, including
+during local development.
 
 ### Stores and callback recovery
 
@@ -344,6 +335,10 @@ Business requests use `no-store` and reject redirects so credentials cannot
 follow a redirect. Network failures preserve the application session. Reuse the
 original idempotency key when reconciling an uncertain write.
 
+`resolved.resources.self.profile()` returns the current member's profile,
+including email and name. These fields are display metadata, not authentication
+proof. Read the profile when displaying it instead of caching it in the session.
+
 `resolved.resources.self.verification()` returns the member's verification
 requirements and sessions through the public self-verification operation.
 `resolved.resources.self.uploadAvatar(image)` performs presign, object upload,
@@ -351,7 +346,7 @@ confirmation, and refreshed avatar lookup. Pass a nonempty PNG, JPEG, WebP, or G
 `Blob` of at most 5 MiB. Storage receives only the image bytes and their content
 headers, never bearer credentials, request signatures, member context, or cookies.
 The helper rejects redirects, expired capabilities, URL credentials, and non-HTTPS
-storage URLs (localhost HTTP is permitted for local development). It does not
+storage URLs (HTTP on `localhost` or `127.0.0.1` is permitted for local development). It does not
 retry an upload. `XKOVAUploadError` identifies the object-storage stage without
 exposing the signed URL; API failures retain `XKOVAApiError` metadata.
 
@@ -371,7 +366,44 @@ Durable application cookies use the host-only `__Host-` prefix, `Secure`, `HttpO
 
 The publishable key is a non-secret application registration identifier. It grants no member or tenant authority by itself. The registered application pins tenant, workspace, environment, provider kind, issuer, audience, origins, redirects, and session policy, and must also match the authenticated workspace principal.
 
-## Cancellation and deadlines
+### Recover an existing member payment
+
+Read recovery state through the resolved member resources:
+
+```ts
+const recovery = await resolved.resources.payments.recovery(paymentId);
+// Call only after the member confirms cancellation in your app.
+if (recovery.can_cancel) {
+  await resolved.resources.payments.cancelForMember(paymentId);
+}
+```
+
+The API permits reads by the sender or recipient. Only the sender can cancel
+or continue. The API principal needs `payment.read` and `payment.cancel`
+permissions for these operations. Your BFF must validate the session, exact
+Origin, and CSRF token before cancellation. Cancellation does not require a
+passkey because it sends no value.
+
+When `can_continue` is true, use `beginMemberAction()` with
+`resourceType: 'payment'`, the existing `resourceId`, and `action: 'sign'`.
+Complete fresh authorization through the registered provider. Keep the original
+amount, recipient, fees, and deadline. Do not create a second payment or reuse
+an expired signing credential. Recovery uses the payment ID, so a new valid
+session for the same member can recover it without the original form draft.
+
+`approval_expired` means the signing window has closed. It remains cancellable
+until a signature has been accepted. After acceptance, `processing` disables
+both actions. `cancelled`, `completed`, and `failed` are separate outcomes;
+retain all three in history. These actions apply to payments; escrow
+cancellation has its own authorization and settlement rules.
+
+Availability can change between a read and a click. After a conflict or an
+uncertain cancellation response, read recovery state again. Repeating an
+already completed member cancellation returns the cancelled payment. Aborting
+an HTTP request or cancelling an authorization ceremony does not cancel the
+payment.
+
+## Request cancellation and deadlines
 
 Set `timeoutMs` on the client for a default request deadline. Mutation options and workflow polling also accept an `AbortSignal`:
 
@@ -386,6 +418,33 @@ await xkova.payments.cancel('pay_...', {
 
 The SDK does not automatically retry writes. Use `withRetry` with a stable idempotency key when retry behavior is appropriate for your application.
 
+## Product enrollment
+
+After a member accepts your displayed terms, call
+`resources.self.acceptProductEnrollment(product, { terms_version })` from the
+BFF. Select the product and terms version on your server. Read the saved result
+with `resources.self.productEnrollment(product)` when the member returns.
+Acceptance does not require an `Idempotency-Key` header. Repeating the same
+acceptance preserves its timestamp. Changed terms or credit parameters with the
+same product are rejected.
+
+Sandbox applications can include `sandbox_credit: { token_deployment_id,
+amount }` to issue a test-token welcome credit. Use an active dUSDC deployment.
+The credit is issued once per member, workspace, and product, across application
+registrations. The daily workspace budget is 1000 dUSDC. Keep amounts and token
+selection in the BFF, and give each product a stable identifier.
+
+For Hosted Auth, set `require_passkey: true` to hold activation and the credit
+until the member has an active passkey and has acknowledged recovery codes.
+`setup_required` means terms are saved and security setup remains incomplete.
+Open Account Center with the `security` intent, then read the enrollment again
+on return. The setup requirement is fixed when the enrollment is accepted.
+
+Poll the enrollment after acceptance. `opening` means delivery is pending;
+`active` means the credit has a successful receipt and an indexed balance.
+`requires_review` needs operator investigation. Do not create another product
+identifier to retry an uncertain credit. Credits do not debit bank accounts.
+
 ## Errors
 
 `XKOVAApiError.retryAfter` preserves the upstream `Retry-After` header when

package/dist/client.js

@@ -1,4 +1,5 @@
 import { XKOVAApiError } from './errors.js';
+import { isAllowedProtocol } from './url.js';
 import { generateIdempotencyKey } from './idempotency.js';
 import { signXKOVARequest, validateXKOVARequestSigner, xkovaContentDigest, } from './request-signing.js';
 import { AccountHoldersResource, } from './resources/account-holders.js';
@@ -240,8 +241,8 @@ function normalizeApiBaseUrl(baseUrl) {
     if (url.username || url.password || url.search || url.hash) {
         throw new TypeError('XKOVA SDK baseUrl must be an API origin or /v1 base URL');
     }
-    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === 'localhost')) {
-        throw new TypeError('XKOVA SDK baseUrl must use HTTPS or localhost HTTP');
+    if (!isAllowedProtocol(url)) {
+        throw new TypeError('XKOVA SDK baseUrl must use HTTPS or loopback HTTP');
     }
     const pathname = url.pathname.replace(/\/+$/, '');
     if (pathname !== '' && pathname !== '/v1') {

package/dist/generated/types.d.ts

@@ -1115,6 +1115,24 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/account-holders/self/product-enrollments/{product}": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /** Read the member's product enrollment */
+        get: operations["getAccountHolderSelfProductEnrollment"];
+        put?: never;
+        /** Record product terms acceptance */
+        post: operations["acceptAccountHolderSelfProductEnrollment"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/account-holders/self/wallet-readiness": {
         parameters: {
             query?: never;
@@ -1234,6 +1252,50 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/account-holders/self/payments/{id}/recovery": {
+        parameters: {
+            query?: never;
+            header: {
+                "X-Member-Session-Id": components["parameters"]["xMemberSessionId"];
+                "X-XKOVA-Publishable-Key": components["parameters"]["xXkovaPublishableKey"];
+            };
+            path: {
+                id: components["parameters"]["pathId"];
+            };
+            cookie?: never;
+        };
+        /** Read a member payment and its available actions */
+        get: operations["getMemberPaymentRecovery"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/account-holders/self/payments/{id}/cancel": {
+        parameters: {
+            query?: never;
+            header: {
+                "X-Member-Session-Id": components["parameters"]["xMemberSessionId"];
+                "X-XKOVA-Publishable-Key": components["parameters"]["xXkovaPublishableKey"];
+            };
+            path: {
+                id: components["parameters"]["pathId"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /** Cancel the current member's unsigned payment */
+        post: operations["cancelMemberPayment"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/account-holders/self/transactions": {
         parameters: {
             query?: never;
@@ -2711,23 +2773,6 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
-    "/member-auth/hosted/authorizations/sandbox-demo": {
-        parameters: {
-            query?: never;
-            header?: never;
-            path?: never;
-            cookie?: never;
-        };
-        get?: never;
-        put?: never;
-        /** Admit a platform-leased sandbox demo persona */
-        post: operations["admitMemberAuthSandboxDemo"];
-        delete?: never;
-        options?: never;
-        head?: never;
-        patch?: never;
-        trace?: never;
-    };
     "/member-auth/hosted/authorizations/exchange": {
         parameters: {
             query?: never;
@@ -4313,6 +4358,22 @@ export interface components {
             /** Format: uri */
             avatar_url?: string | null;
         };
+        MemberProductEnrollment: {
+            product: string;
+            /** @enum {string} */
+            status: "not_opened" | "setup_required" | "opening" | "active" | "requires_review";
+            terms_version: string | null;
+            /** Format: date-time */
+            accepted_at: string | null;
+            credit: {
+                amount: string;
+                /** Format: uuid */
+                token_deployment_id: string;
+                /** @enum {string} */
+                status: "pending" | "submitted" | "settled" | "requires_review";
+                transaction_hash: string | null;
+            } | null;
+        };
         CuPayoutAccountRef: {
             routing_number: string;
             account_number: string;
@@ -4328,6 +4389,13 @@ export interface components {
         AccountHolderSelfBalance: {
             balances: components["schemas"]["AccountHolderSelfBalanceEntry"][];
         };
+        MemberPaymentRecovery: {
+            payment: components["schemas"]["Payment"];
+            /** @enum {string} */
+            state: "awaiting_approval" | "approval_expired" | "on_hold" | "processing" | "completed" | "cancelled" | "failed";
+            can_continue: boolean;
+            can_cancel: boolean;
+        };
         AccountHolderSelfTransactionList: {
             data: components["schemas"]["AccountHolderSelfTransaction"][];
             next_cursor: string | null;
@@ -7533,6 +7601,14 @@ export interface operations {
                 };
             };
             400: components["responses"]["BadRequest"];
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
             422: {
                 headers: {
                     [name: string]: unknown;
@@ -8063,6 +8139,74 @@ export interface operations {
             403: components["responses"]["Forbidden"];
         };
     };
+    getAccountHolderSelfProductEnrollment: {
+        parameters: {
+            query?: never;
+            header: {
+                "X-Member-Session-Id": components["parameters"]["xMemberSessionId"];
+                "X-XKOVA-Publishable-Key": components["parameters"]["xXkovaPublishableKey"];
+            };
+            path: {
+                product: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MemberProductEnrollment"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+        };
+    };
+    acceptAccountHolderSelfProductEnrollment: {
+        parameters: {
+            query?: never;
+            header: {
+                "X-Member-Session-Id": components["parameters"]["xMemberSessionId"];
+                "X-XKOVA-Publishable-Key": components["parameters"]["xXkovaPublishableKey"];
+            };
+            path: {
+                product: string;
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": {
+                    terms_version: string;
+                    /** @default false */
+                    require_passkey?: boolean;
+                    sandbox_credit?: {
+                        /** Format: uuid */
+                        token_deployment_id: string;
+                        amount: string;
+                    };
+                };
+            };
+        };
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MemberProductEnrollment"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            409: components["responses"]["Conflict"];
+            422: components["responses"]["UnprocessableEntity"];
+            429: components["responses"]["TooManyRequests"];
+        };
+    };
     getAccountHolderSelfWalletReadiness: {
         parameters: {
             query?: never;
@@ -8265,6 +8409,76 @@ export interface operations {
             403: components["responses"]["Forbidden"];
         };
     };
+    getMemberPaymentRecovery: {
+        parameters: {
+            query?: never;
+            header: {
+                "X-Member-Session-Id": components["parameters"]["xMemberSessionId"];
+                "X-XKOVA-Publishable-Key": components["parameters"]["xXkovaPublishableKey"];
+            };
+            path: {
+                id: components["parameters"]["pathId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MemberPaymentRecovery"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+        };
+    };
+    cancelMemberPayment: {
+        parameters: {
+            query?: never;
+            header: {
+                "X-Member-Session-Id": components["parameters"]["xMemberSessionId"];
+                "X-XKOVA-Publishable-Key": components["parameters"]["xXkovaPublishableKey"];
+            };
+            path: {
+                id: components["parameters"]["pathId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["MemberPaymentRecovery"];
+                };
+            };
+            401: components["responses"]["Unauthorized"];
+            403: components["responses"]["Forbidden"];
+            404: components["responses"]["NotFound"];
+            409: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+            422: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorResponse"];
+                };
+            };
+        };
+    };
     listAccountHolderSelfTransactions: {
         parameters: {
             query?: {
@@ -11574,45 +11788,6 @@ export interface operations {
             429: components["responses"]["TooManyRequests"];
         };
     };
-    admitMemberAuthSandboxDemo: {
-        parameters: {
-            query?: never;
-            header: {
-                "Idempotency-Key": components["parameters"]["idempotencyKey"];
-                "X-XKOVA-Publishable-Key": components["parameters"]["xXkovaPublishableKey"];
-            };
-            path?: never;
-            cookie?: never;
-        };
-        requestBody: {
-            content: {
-                "application/json": {
-                    transaction: string;
-                };
-            };
-        };
-        responses: {
-            200: {
-                headers: {
-                    [name: string]: unknown;
-                };
-                content: {
-                    "application/json": {
-                        /** Format: uri */
-                        redirect_url: string;
-                        /** Format: date-time */
-                        expires_at: string;
-                    };
-                };
-            };
-            401: components["responses"]["Unauthorized"];
-            403: components["responses"]["Forbidden"];
-            409: components["responses"]["Conflict"];
-            422: components["responses"]["UnprocessableEntity"];
-            429: components["responses"]["TooManyRequests"];
-            503: components["responses"]["ServiceUnavailable"];
-        };
-    };
     completeMemberAuthHostedAuthorization: {
         parameters: {
             query?: never;

package/dist/member-action-intents.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { isAllowedProtocol } from './url.js';
 export class XKOVAMemberIntentError extends Error {
     code;
     status;
@@ -33,8 +34,7 @@ export class XKOVAMemberActionIntents {
             location.username ||
             location.password ||
             location.hash ||
-            (location.protocol !== 'https:' &&
-                !(location.protocol === 'http:' && location.hostname === 'localhost')))
+            !isAllowedProtocol(location))
             throw new TypeError('Action review requires the exact application origin');
         const snapshot = JSON.parse(canonicalJson({
             request: input.request,

package/dist/member-bff.d.ts

@@ -350,20 +350,6 @@ export declare class XKOVAMemberBffClient {
         readonly redirectUri: string;
         readonly transactionStore: XKOVAMemberAuthorizationTransactionStore<TApplicationData>;
     }): Promise<XKOVAHostedMemberAuthorizationStart>;
-    /**
-     * Available only to sandbox applications enabled for demo sign-in. The stored
-     * Hosted transaction determines the demo account and callback. An uncertain
-     * response preserves the key so a retry recovers the same reservation.
-     * Complete the returned callback using
-     * completeHostedAuthorization and the original browser flow cookie.
-     */
-    completeSandboxDemoAuthorization<TApplicationData>(input: {
-        readonly state: string;
-        readonly transactionStore: XKOVAMemberAuthorizationTransactionStore<TApplicationData>;
-    }): Promise<{
-        readonly callbackUrl: string;
-        readonly expiresAt: string;
-    }>;
     /**
      * Completes the one-time Hosted Auth result-code exchange and persists the
      * provider-neutral XKOVA member session. The returned projection is safe for
@@ -492,8 +478,6 @@ export declare class XKOVAMemberBffClient {
     private readSessionMaterial;
     private requestSignal;
 }
-/** Only confirmed admission rejections may release a customer's pending demo reservation. */
-export declare function isDefinitiveXKOVASandboxDemoAdmissionFailure(error: unknown): boolean;
 export declare function projectXKOVAMemberSession(session: XKOVAMemberContext): XKOVABrowserMemberProjection;
 export declare function serializeXKOVAMemberSessionCookie(input: {
     readonly cookieName: string;

package/dist/member-bff.js

@@ -1,5 +1,6 @@
 import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { XKOVAApiError } from './errors.js';
+import { isAllowedProtocol } from './url.js';
 import { XKOVAClient } from './client.js';
 import { XKOVAMemberResources } from './member-resources.js';
 import { XKOVAMemberActionIntents, } from './member-action-intents.js';
@@ -195,54 +196,6 @@ export class XKOVAMemberBffClient {
             throw error;
         }
     }
-    /**
-     * Available only to sandbox applications enabled for demo sign-in. The stored
-     * Hosted transaction determines the demo account and callback. An uncertain
-     * response preserves the key so a retry recovers the same reservation.
-     * Complete the returned callback using
-     * completeHostedAuthorization and the original browser flow cookie.
-     */
-    async completeSandboxDemoAuthorization(input) {
-        if (!this.options.apiKey.startsWith('xkv_test_') ||
-            !this.options.publishableKey.startsWith('xkova_pk_sandbox_')) {
-            throw new XKOVAMemberAuthorizationTerminalError('provider_rejected', 'Demo admission requires a sandbox application');
-        }
-        const stateHash = hashOpaque(input.state);
-        return input.transactionStore.runExclusive(stateHash, async () => {
-            const transaction = await input.transactionStore.get(stateHash);
-            if (!transaction || transaction.expiresAt <= Date.now()) {
-                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'Demo admission requires an active Hosted transaction');
-            }
-            assertMemberBffClientFingerprint(transaction.clientFingerprint, this.clientFingerprint);
-            if (transaction.status !== 'pending' ||
-                transaction.completionMode !== 'hosted_result_code' ||
-                !transaction.authorizationUrl) {
-                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'Demo admission requires a completed Hosted start');
-            }
-            const authorization = new URL(normalizeHostedAuthorizationUrl(transaction.authorizationUrl));
-            const capability = authorization.searchParams.get('transaction');
-            if (!/^\/authorize\/?$/.test(authorization.pathname) ||
-                !capability ||
-                !/^[A-Za-z0-9_-]{43}$/.test(capability)) {
-                throw new XKOVAMemberAuthorizationTerminalError('transaction_unavailable', 'Demo admission capability is invalid');
-            }
-            const value = await this.postJson('/member-auth/hosted/authorizations/sandbox-demo', { transaction: capability }, undefined, `sandbox-demo-${stateHash}`);
-            const body = requireObject(value, 'Sandbox demo admission');
-            const { expiresAt } = boundedAuthorizationExpiry(body, transaction.expiresAt, 'Sandbox demo admission');
-            const callback = new URL(requireString(body, 'redirect_url', 'Sandbox demo admission'));
-            const code = callback.searchParams.get('code');
-            if (!sameCallback(callback, new URL(transaction.redirectUri)) ||
-                callback.searchParams.getAll('state').length !== 1 ||
-                callback.searchParams.get('state') !== input.state ||
-                callback.searchParams.getAll('code').length !== 1 ||
-                !code ||
-                callback.searchParams.has('error')) {
-                throw new Error('Sandbox demo admission returned the wrong callback binding');
-            }
-            assertHostedAuthorizationResultCode(code);
-            return { callbackUrl: callback.toString(), expiresAt };
-        });
-    }
     /**
      * Completes the one-time Hosted Auth result-code exchange and persists the
      * provider-neutral XKOVA member session. The returned projection is safe for
@@ -560,7 +513,7 @@ export class XKOVAMemberBffClient {
                 clientFingerprint: this.clientFingerprint,
                 codeVerifier,
                 redirectUri: returnUri,
-                exchangeAttemptId: generateXKOVAMemberOperationAttemptId(),
+                exchangeAttemptId: randomUUID(),
                 sessionReference: input.sessionReference,
                 intent: 'action',
                 ...(applicationReturnUri !== undefined && { applicationReturnUri }),
@@ -1210,14 +1163,6 @@ export class XKOVAMemberBffClient {
             : AbortSignal.timeout(this.options.timeoutMs);
     }
 }
-/** Only confirmed admission rejections may release a customer's pending demo reservation. */
-export function isDefinitiveXKOVASandboxDemoAdmissionFailure(error) {
-    return (error instanceof XKOVAMemberAuthorizationTerminalError ||
-        (error instanceof XKOVAApiError &&
-            (error.status < 500 ||
-                error.code === 'demo_persona_unavailable' ||
-                error.code === 'demo_login_disabled')));
-}
 export function projectXKOVAMemberSession(session) {
     return {
         signedIn: true,
@@ -1339,8 +1284,8 @@ function normalizeApiBaseUrl(baseUrl) {
     if (url.username || url.password || url.search || url.hash) {
         throw new TypeError('XKOVA member BFF baseUrl must be an API origin or /v1 base URL');
     }
-    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === 'localhost')) {
-        throw new TypeError('XKOVA member BFF baseUrl must use HTTPS or localhost HTTP');
+    if (!isAllowedProtocol(url)) {
+        throw new TypeError('XKOVA member BFF baseUrl must use HTTPS or loopback HTTP');
     }
     const pathname = url.pathname.replace(/\/+$/, '');
     if (pathname !== '' && pathname !== '/v1') {
@@ -1353,16 +1298,15 @@ function normalizeCallbackUri(value) {
     if (url.username || url.password || url.search || url.hash) {
         throw new TypeError('member authorization redirectUri must not contain credentials, query, or fragment');
     }
-    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === 'localhost')) {
-        throw new TypeError('member authorization redirectUri must use HTTPS or localhost HTTP');
+    if (!isAllowedProtocol(url)) {
+        throw new TypeError('member authorization redirectUri must use HTTPS or loopback HTTP');
     }
     return url.toString();
 }
 function normalizeBrowserOrigin(value) {
     const url = new URL(value);
-    if (url.origin !== value ||
-        (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === 'localhost'))) {
-        throw new TypeError('member authorization browserOrigin must be an exact HTTPS or localhost origin');
+    if (url.origin !== value || !isAllowedProtocol(url)) {
+        throw new TypeError('member authorization browserOrigin must be an exact HTTPS or loopback origin');
     }
     return value;
 }
@@ -1372,18 +1316,14 @@ function normalizeApplicationReturnUri(value, browserOrigin) {
         url.username ||
         url.password ||
         url.hash ||
-        (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === 'localhost'))) {
+        !isAllowedProtocol(url)) {
         throw new TypeError('member action applicationReturnUri must use the exact browser origin');
     }
     return url.toString();
 }
 function normalizeHostedAuthorizationUrl(value) {
     const url = new URL(value);
-    if (url.username ||
-        url.password ||
-        url.hash ||
-        (url.protocol !== 'https:' &&
-            !(url.protocol === 'http:' && (url.hostname === 'localhost' || url.hostname === '127.0.0.1')))) {
+    if (url.username || url.password || url.hash || !isAllowedProtocol(url)) {
         throw new Error('XKOVA member Hosted authorization URL must use HTTPS or loopback HTTP without credentials or a fragment');
     }
     return url.toString();

package/dist/member-resources.d.ts

@@ -18,6 +18,56 @@ export declare class XKOVAMemberResources {
     get paymentRequests(): import("./resources/index.js").PaymentRequestsResource;
     get wallets(): import("./resources/index.js").WalletsResource;
     readonly self: {
+        profile: () => Promise<{
+            id: import("./generated/types.js").components["schemas"]["AccountHolderId"];
+            tenant_id?: string;
+            state: "active" | "held" | "closed" | "closed_uncooperative" | "provisioning_failed";
+            state_reason?: string | null;
+            state_changed_at?: import("./generated/types.js").components["schemas"]["TimestampUtc"] | null;
+            tier: "tier_1" | "tier_2";
+            tier_2_uplift_status?: "not_requested" | "pending" | "passed" | "failed";
+            first_use_completed: boolean;
+            cip_payload?: {
+                name_hash?: string;
+                dob_hash?: string;
+                id_hash?: string;
+                address_hash?: string;
+            } | null;
+            cip_accepted_at?: import("./generated/types.js").components["schemas"]["TimestampUtc"] | null;
+            merchant_role_state?: "none" | "pending_review" | "approved" | "rejected" | "revoked";
+            auto_save_contacts?: boolean;
+            created_at: import("./generated/types.js").components["schemas"]["TimestampUtc"];
+            updated_at?: import("./generated/types.js").components["schemas"]["TimestampUtc"];
+            email?: string | null;
+            first_name?: string | null;
+            last_name?: string | null;
+            phone?: string | null;
+            avatar_url?: string | null;
+        }>;
+        productEnrollment: (product: string, control?: XKOVARequestControl) => Promise<{
+            product: string;
+            status: "not_opened" | "setup_required" | "opening" | "active" | "requires_review";
+            terms_version: string | null;
+            accepted_at: string | null;
+            credit: {
+                amount: string;
+                token_deployment_id: string;
+                status: "pending" | "submitted" | "settled" | "requires_review";
+                transaction_hash: string | null;
+            } | null;
+        }>;
+        acceptProductEnrollment: (product: string, body: ReqBody<"acceptAccountHolderSelfProductEnrollment">, opts?: XKOVAMutationOptions) => Promise<{
+            product: string;
+            status: "not_opened" | "setup_required" | "opening" | "active" | "requires_review";
+            terms_version: string | null;
+            accepted_at: string | null;
+            credit: {
+                amount: string;
+                token_deployment_id: string;
+                status: "pending" | "submitted" | "settled" | "requires_review";
+                transaction_hash: string | null;
+            } | null;
+        }>;
         actionReadiness: (control?: XKOVARequestControl) => Promise<{
             authorization_method: "hosted_passkey" | "external_oidc";
             setup_status: "passkey_required" | "recovery_acknowledgement_required" | "recovery_required" | "ready" | "externally_managed";

package/dist/member-resources.js

@@ -31,6 +31,9 @@ export class XKOVAMemberResources {
         return this.client.wallets;
     }
     self = {
+        profile: () => this.client.accountHolders.retrieve(this.accountHolderId),
+        productEnrollment: (product, control) => this.client.accountHolders.selfProductEnrollment(this.context, product, control),
+        acceptProductEnrollment: (product, body, opts) => this.client.accountHolders.acceptSelfProductEnrollment(this.context, product, body, opts),
         actionReadiness: (control) => this.client.accountHolders.selfActionReadiness({ ...this.context, accountHolderId: this.accountHolderId }, control),
         sandboxBankingContext: (control) => this.client.accountHolders.selfSandboxBankingContext(this.context, control),
         verification: (control) => this.client.accountHolders.selfVerification(this.context, control),

package/dist/resources/account-holders.d.ts

@@ -118,6 +118,30 @@ export declare class AccountHoldersResource extends Resource {
         }[];
         verification_url: string | null;
     }>;
+    selfProductEnrollment(context: XKOVAMemberSessionContext, product: string, control?: XKOVARequestControl): Promise<{
+        product: string;
+        status: "not_opened" | "setup_required" | "opening" | "active" | "requires_review";
+        terms_version: string | null;
+        accepted_at: string | null;
+        credit: {
+            amount: string;
+            token_deployment_id: string;
+            status: "pending" | "submitted" | "settled" | "requires_review";
+            transaction_hash: string | null;
+        } | null;
+    }>;
+    acceptSelfProductEnrollment(context: XKOVAMemberSessionContext, product: string, body: ReqBody<'acceptAccountHolderSelfProductEnrollment'>, opts?: XKOVAMutationOptions): Promise<{
+        product: string;
+        status: "not_opened" | "setup_required" | "opening" | "active" | "requires_review";
+        terms_version: string | null;
+        accepted_at: string | null;
+        credit: {
+            amount: string;
+            token_deployment_id: string;
+            status: "pending" | "submitted" | "settled" | "requires_review";
+            transaction_hash: string | null;
+        } | null;
+    }>;
     selfBalance(context: XKOVAMemberSessionContext, control?: XKOVARequestControl): Promise<{
         balances: import("../generated/types.js").components["schemas"]["AccountHolderSelfBalanceEntry"][];
     }>;

package/dist/resources/account-holders.js

@@ -1,5 +1,6 @@
 import { Resource } from './base.js';
 import { XKOVAUploadError } from '../errors.js';
+import { isAllowedProtocol } from '../url.js';
 function memberSessionHeaders(context) {
     return {
         'X-Member-Session-Id': context.memberSessionId,
@@ -30,6 +31,12 @@ export class AccountHoldersResource extends Resource {
     selfVerification(context, control) {
         return this.getJson('/account-holders/self/verification', undefined, control, memberSessionHeaders(context));
     }
+    selfProductEnrollment(context, product, control) {
+        return this.getJson(`/account-holders/self/product-enrollments/${this.enc(product)}`, undefined, control, memberSessionHeaders(context));
+    }
+    acceptSelfProductEnrollment(context, product, body, opts) {
+        return this.postJson(`/account-holders/self/product-enrollments/${this.enc(product)}`, body, opts, undefined, memberSessionHeaders(context));
+    }
     selfBalance(context, control) {
         return this.getJson('/account-holders/self/balance', undefined, control, memberSessionHeaders(context));
     }
@@ -115,8 +122,7 @@ export class AccountHoldersResource extends Resource {
         if (target.username ||
             target.password ||
             target.hash ||
-            (target.protocol !== 'https:' &&
-                !(target.protocol === 'http:' && target.hostname === 'localhost')) ||
+            !isAllowedProtocol(target) ||
             !Number.isFinite(Date.parse(upload.expires_at)) ||
             Date.parse(upload.expires_at) <= Date.now()) {
             throw new XKOVAUploadError('The avatar upload capability is invalid or expired');

package/dist/resources/payments.d.ts

@@ -178,5 +178,18 @@ export declare class PaymentsResource extends Resource {
         created_at: import("../generated/types.js").components["schemas"]["TimestampUtc"];
         finalized_at: import("../generated/types.js").components["schemas"]["TimestampUtc"] | null;
     }>;
+    /** Requires a resolved member session. Only the sender can continue or cancel. */
+    recovery(id: string): Promise<{
+        payment: import("../generated/types.js").components["schemas"]["Payment"];
+        state: "awaiting_approval" | "approval_expired" | "on_hold" | "processing" | "completed" | "cancelled" | "failed";
+        can_continue: boolean;
+        can_cancel: boolean;
+    }>;
+    cancelForMember(id: string, opts?: XKOVAMutationOptions): Promise<{
+        payment: import("../generated/types.js").components["schemas"]["Payment"];
+        state: "awaiting_approval" | "approval_expired" | "on_hold" | "processing" | "completed" | "cancelled" | "failed";
+        can_continue: boolean;
+        can_cancel: boolean;
+    }>;
 }
 export {};

package/dist/resources/payments.js

@@ -30,4 +30,11 @@ export class PaymentsResource extends Resource {
     cancel(id, opts) {
         return this.postJson(`/payments/${this.enc(id)}/cancel`, undefined, opts);
     }
+    /** Requires a resolved member session. Only the sender can continue or cancel. */
+    recovery(id) {
+        return this.getJson(`/account-holders/self/payments/${this.enc(id)}/recovery`);
+    }
+    cancelForMember(id, opts) {
+        return this.postJson(`/account-holders/self/payments/${this.enc(id)}/cancel`, undefined, opts);
+    }
 }

package/dist/url.d.ts

@@ -0,0 +1 @@
+export declare function isAllowedProtocol(url: URL): boolean;

package/dist/url.js

@@ -0,0 +1,4 @@
+export function isAllowedProtocol(url) {
+    return (url.protocol === 'https:' ||
+        (url.protocol === 'http:' && (url.hostname === 'localhost' || url.hostname === '127.0.0.1')));
+}

package/llms.txt

@@ -74,6 +74,26 @@ API availability does not grant permission. Product entitlement, selected API-ke
 - Reuse one createMemberActionReference() from @xkova/browser for a durable review. Save the draft before setup detours. Expired or missing reviews require checking activity and an explicit new review.
 - Setup readiness is advisory. beginMemberAction() and completeMemberAction() obtain fresh approval for the exact resource. Browser code must not receive provider wallet credentials or internal signing capabilities. Completion of authorization is distinct from execution and settlement.
 
+## Payment recovery
+
+Use resolved.resources.payments.recovery(paymentId) to read the current
+member's payment and available actions. Only the sender can continue or cancel.
+On explicit cancellation, call cancelForMember(paymentId) after BFF session,
+Origin and CSRF checks. The principal needs payment.read and payment.cancel.
+Cancellation sends no value and does not require a passkey.
+
+Continue only when can_continue is true. Begin a fresh member action for the
+same payment resourceId with action sign, then complete the registered proof
+ceremony. Never create another payment, change its fees or deadline, or reuse
+an expired signing credential. A new session for the same member can recover
+the payment without its original draft. Expired approvals remain cancellable;
+accepted signatures close cancellation. Keep cancelled payments in history.
+After a conflict or uncertain cancellation, re-read state before another action.
+
 ## Before handing off code
 
 List the Console setup and stores the application needs. Test denied access, uncertain writes, pagination, cancellation, and terminal outcomes. Report a missing method or setup requirement explicitly. Do not invent methods, suppress type errors, or bypass authorization to make an example run.
+
+## Product opt-in
+
+Use resolveResources().self.productEnrollment(product) to read acceptance and credit status. After explicit consent, call self.acceptProductEnrollment(product, { terms_version, sandbox_credit? }). The BFF chooses the product, terms, amount, and token. Reads do not enroll members. Acceptance needs no Idempotency-Key header; reuse the same product and parameters when retrying. Sandbox credits are dUSDC only and issued once per workspace/member/product; the workspace daily budget is 1000 dUSDC. Poll opening until active. Treat requires_review as unresolved delivery, never as permission to request a second product credit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xkova/sdk",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "description": "TypeScript SDK for the XKOVA API.",
   "homepage": "https://docs.xkova.com",
   "repository": {