@xkova/sdk 0.1.0-alpha.5 → 0.1.0-alpha.7

package/dist/member-bff.d.ts

@@ -34,6 +34,14 @@ export interface XKOVAMemberSessionMaterial extends XKOVAMemberContext {
     /** Confidential refresh credential, BFF storage only. */
     readonly refreshToken: string;
 }
+export interface XKOVAExternalMemberEnrollment {
+    readonly accountHolderId: string;
+    readonly applicationId: string;
+    readonly publishableKey: string;
+    readonly applicationConfigVersion: number;
+    readonly providerNamespace: string;
+    readonly created: boolean;
+}
 export interface XKOVABrowserMemberProjection {
     readonly signedIn: true;
     readonly accountHolderId: string;
@@ -49,8 +57,12 @@ export interface StoredXKOVAMemberSession<TApplicationData = unknown> extends XK
 }
 /**
  * `runExclusive` must serialize refresh and logout for the same reference
- * across all BFF instances. Use a database transaction or distributed lock;
- * a process-local mutex cannot coordinate multiple instances.
+ * across all BFF instances. Use a distributed or session-level database lock;
+ * a process-local mutex cannot coordinate multiple instances. This lock is not
+ * a surrounding rollback transaction: every awaited put/replace/delete must be
+ * durable before resolving and must survive a later error from work(). In
+ * particular, a pending refresh-attempt checkpoint cannot roll back after the
+ * provider/API has acted. replace is exact-existing-only, never an upsert.
  */
 export interface XKOVAMemberSessionStore<TApplicationData = unknown> {
     put(reference: string, session: StoredXKOVAMemberSession<TApplicationData>): Promise<void>;
@@ -116,7 +128,7 @@ export type XKOVAMemberAuthorizationTransaction<TApplicationData = unknown> = {
     readonly sessionReference: string;
     readonly intent: XKOVAAccountCenterIntent;
     readonly actionAuthorization?: {
-        readonly method: 'hosted_passkey';
+        readonly method: 'hosted_passkey' | 'xkova_webauthn';
     } | {
         readonly method: 'external_oidc';
         readonly actionToken: string;
@@ -169,6 +181,11 @@ export type XKOVAMemberAuthorizationTransaction<TApplicationData = unknown> = {
  * every BFF instance. `replace` and `delete` must target that exact state. A
  * production store must encrypt the transaction because it can briefly hold a
  * confidential provider proof while XKOVA session exchange is retried.
+ * Every awaited write must commit independently of a later work() exception.
+ * Never wrap the entire callback in a rollback transaction: that can erase the
+ * staged proof after its one-time provider code has already been consumed.
+ * On uncertain write acknowledgement, reconcile the same exact record; never
+ * re-exchange the provider code or invent a replacement operation identity.
  */
 export interface XKOVAMemberAuthorizationTransactionStore<TApplicationData = unknown> {
     put(stateHash: string, transaction: XKOVAMemberAuthorizationTransaction<TApplicationData>): Promise<void>;
@@ -198,6 +215,10 @@ export type XKOVAMemberProofExchangeTransaction<TApplicationData = unknown> = {
  * Durable transaction store for a confidential proof exchange that does not
  * use the browser callback helper. Pending records contain a provider proof
  * and customer application data, so production adapters must encrypt them.
+ * Serialize the exact reference across replicas without a surrounding rollback
+ * transaction. Awaited put/replace/delete checkpoints must remain committed if
+ * the later exchange fails. Reconcile an uncertain acknowledgement against the
+ * same reference and attempt identity before retrying.
  */
 export interface XKOVAMemberProofExchangeTransactionStore<TApplicationData = unknown> {
     put(exchangeHash: string, transaction: XKOVAMemberProofExchangeTransaction<TApplicationData>): Promise<void>;
@@ -239,7 +260,7 @@ export interface XKOVAAccountCenterHandoffCompletion {
     readonly applicationReturnUri?: string;
 }
 export type XKOVAMemberActionAuthorizationStart = {
-    readonly authorizationMethod: 'hosted_passkey';
+    readonly authorizationMethod: 'hosted_passkey' | 'xkova_webauthn';
     readonly authorizationUrl: string;
     readonly state: string;
     readonly expiresAt: string;
@@ -321,6 +342,18 @@ export declare class XKOVAMemberBffClient {
     exchangeProof(proofToken: string, options: {
         readonly attemptId: string;
     }): Promise<XKOVAMemberSessionMaterial>;
+    /**
+     * BFF-only membership provisioning after validating the provider identity or
+     * resolving it from a trusted directory. This creates no login session or
+     * wallet and does not substitute for genuine provider-proof verification.
+     * Save one idempotencyKey before the first attempt and retain the same subject,
+     * selector and observed configuration version during response-loss recovery.
+     */
+    enrollExternalMember(input: {
+        readonly externalSub: string;
+        readonly applicationConfigVersion: number;
+        readonly idempotencyKey: string;
+    }): Promise<XKOVAExternalMemberEnrollment>;
     refresh(refreshToken: string, options: {
         readonly attemptId: string;
     }): Promise<XKOVAMemberSessionMaterial>;
@@ -426,6 +459,17 @@ export declare class XKOVAMemberBffClient {
         readonly transactionStore: XKOVAMemberAuthorizationTransactionStore<TApplicationData>;
         readonly sessionStore: XKOVAMemberSessionStore<TApplicationData>;
         readonly exchangeProviderCode: (input: XKOVAMemberProviderCodeExchangeInput) => XKOVAMemberProviderCodeExchangeResult | Promise<XKOVAMemberProviderCodeExchangeResult>;
+        /**
+         * Optional OIDC enrollment, invoked only after the validated provider proof
+         * is durably staged. Validate/extract its exact subject on your backend and
+         * call enrollExternalMember with this stable idempotency key. Do not perform
+         * enrollment RPC inside exchangeProviderCode: failure there can otherwise
+         * require reusing an already-consumed provider authorization code.
+         */
+        readonly ensureMemberEnrollment?: (input: {
+            readonly proofToken: string;
+            readonly idempotencyKey: string;
+        }) => Promise<XKOVAExternalMemberEnrollment>;
         readonly applicationData: TApplicationData;
         readonly applicationSessionSeconds?: number;
     }): Promise<EstablishedXKOVAMemberSession<TApplicationData>>;
@@ -455,6 +499,11 @@ export declare class XKOVAMemberBffClient {
     resolveResources<TApplicationData>(input: {
         readonly reference: string;
         readonly sessionStore: XKOVAMemberSessionStore<TApplicationData>;
+        /**
+         * Defaults true. Set false only when the bound resource request executes
+         * immediately and therefore performs the same exact-session validation.
+         */
+        readonly validateWithXkova?: boolean;
     }): Promise<{
         readonly session: StoredXKOVAMemberSession<TApplicationData>;
         readonly resources: XKOVAMemberResources;

package/dist/member-bff.js

@@ -79,6 +79,48 @@ export class XKOVAMemberBffClient {
             proof_token: proofToken,
         }), 'proof exchange');
     }
+    /**
+     * BFF-only membership provisioning after validating the provider identity or
+     * resolving it from a trusted directory. This creates no login session or
+     * wallet and does not substitute for genuine provider-proof verification.
+     * Save one idempotencyKey before the first attempt and retain the same subject,
+     * selector and observed configuration version during response-loss recovery.
+     */
+    async enrollExternalMember(input) {
+        if (typeof input.externalSub !== 'string' ||
+            input.externalSub.length === 0 ||
+            input.externalSub.length > 512 ||
+            /\u0000/u.test(input.externalSub) ||
+            !/\S/u.test(input.externalSub))
+            throw new TypeError('externalSub must be an exact nonempty provider subject of at most 512 characters');
+        assertPositiveInteger(input.applicationConfigVersion, 'applicationConfigVersion');
+        if (!/^[A-Za-z0-9._:-]{1,255}$/u.test(input.idempotencyKey))
+            throw new TypeError('idempotencyKey must be a retained opaque operation key of at most 255 characters');
+        const value = await this.recoverablePostJson('/member-auth/enrollments', {
+            publishable_key: this.options.publishableKey,
+            application_config_version: input.applicationConfigVersion,
+            external_sub: input.externalSub,
+        }, undefined, input.idempotencyKey);
+        const result = requireObject(value, 'external member enrollment');
+        const applicationId = requireString(result, 'application_id', 'external member enrollment');
+        assertUuid(applicationId, 'enrollment application id');
+        const publishableKey = requireString(result, 'publishable_key', 'external member enrollment');
+        const applicationConfigVersion = requirePositiveInteger(result, 'application_config_version', 'external member enrollment');
+        const providerNamespace = requireString(result, 'provider_namespace', 'external member enrollment');
+        if (publishableKey !== this.options.publishableKey ||
+            applicationConfigVersion !== input.applicationConfigVersion ||
+            !providerNamespace.startsWith('oidc:') ||
+            typeof result.created !== 'boolean')
+            throw new Error('XKOVA external member enrollment returned a different application or configuration');
+        return {
+            accountHolderId: requireString(result, 'account_holder_id', 'external member enrollment'),
+            applicationId,
+            publishableKey,
+            applicationConfigVersion,
+            providerNamespace,
+            created: result.created,
+        };
+    }
     async refresh(refreshToken, options) {
         if (refreshToken.length < 20) {
             throw new TypeError('member refresh token is malformed');
@@ -536,15 +578,15 @@ export class XKOVAMemberBffClient {
                 const object = requireObject(value, 'member action authorization start');
                 const method = requireString(object, 'authorization_method', 'member action authorization start');
                 const { expiresAt, expiresAtMillis } = boundedAuthorizationExpiry(object, provisionalExpiresAt, 'member action authorization start');
-                if (method === 'hosted_passkey') {
+                if (method === 'hosted_passkey' || method === 'xkova_webauthn') {
                     const authorizationUrl = normalizeHostedAuthorizationUrl(requireString(object, 'authorization_url', 'member action authorization start'));
                     await input.transactionStore.replace(stateHash, {
                         ...transaction,
-                        actionAuthorization: { method: 'hosted_passkey' },
+                        actionAuthorization: { method },
                         expiresAt: expiresAtMillis,
                     });
                     return {
-                        authorizationMethod: 'hosted_passkey',
+                        authorizationMethod: method,
                         authorizationUrl,
                         state,
                         expiresAt,
@@ -606,7 +648,7 @@ export class XKOVAMemberBffClient {
         if (initial?.completionMode === 'account_center_result_code' &&
             initial.status === 'pending' &&
             initial.intent === 'action' &&
-            initial.actionAuthorization?.method === 'hosted_passkey') {
+            ['hosted_passkey', 'xkova_webauthn'].includes(initial.actionAuthorization?.method ?? '')) {
             const completion = await this.completeAccountCenterHandoff(input);
             if (!completion.signingExchangeCode || !completion.signingUrl) {
                 throw new Error('XKOVA Hosted action completion omitted its signing projection');
@@ -759,6 +801,10 @@ export class XKOVAMemberBffClient {
             if (transaction.completionMode !== 'provider_proof') {
                 throw new Error('member authorization transaction is not a provider-proof flow');
             }
+            if (input.ensureMemberEnrollment &&
+                transaction.status === 'pending' &&
+                transaction.proofKind !== 'oidc')
+                throw new Error('external member enrollment is available only for an OIDC proof flow');
             if (!sameCallback(callback, new URL(transaction.redirectUri))) {
                 throw new Error('member authorization callback does not match its redirect URI');
             }
@@ -821,6 +867,14 @@ export class XKOVAMemberBffClient {
                     },
                 });
             }
+            const enrollment = input.ensureMemberEnrollment
+                ? await input.ensureMemberEnrollment({
+                    proofToken,
+                    idempotencyKey: `enroll:${transaction.exchangeAttemptId}`,
+                })
+                : undefined;
+            if (enrollment && enrollment.publishableKey !== this.options.publishableKey)
+                throw new Error('member enrollment does not belong to this application');
             const established = await this.persistSessionWithAttempt({
                 proofToken,
                 attemptId: transaction.exchangeAttemptId,
@@ -828,6 +882,7 @@ export class XKOVAMemberBffClient {
                 sessionStore: input.sessionStore,
                 applicationData,
                 applicationExpiresAt,
+                ...(enrollment !== undefined && { expectedAccountHolderId: enrollment.accountHolderId }),
             });
             await input.transactionStore.replace(stateHash, {
                 status: 'completed',
@@ -1014,6 +1069,9 @@ export class XKOVAMemberBffClient {
         const material = await this.exchangeProof(input.proofToken, {
             attemptId: input.attemptId,
         });
+        if (input.expectedAccountHolderId !== undefined &&
+            material.accountHolderId !== input.expectedAccountHolderId)
+            throw new Error('XKOVA proof exchange returned a different member from the enrolled identity');
         return this.persistSessionMaterial({
             material,
             reference: input.reference,
@@ -1064,8 +1122,7 @@ export class XKOVAMemberBffClient {
             ...(idempotencyKey !== undefined && { idempotencyKey }),
         });
     }
-    async recoverablePostJson(path, body, sessionId) {
-        const idempotencyKey = generateIdempotencyKey();
+    async recoverablePostJson(path, body, sessionId, idempotencyKey = generateIdempotencyKey()) {
         try {
             return await this.postJson(path, body, sessionId, idempotencyKey);
         }

package/dist/member-resources.d.ts

@@ -52,6 +52,9 @@ export declare class XKOVAMemberResources {
             credit: {
                 amount: string;
                 token_deployment_id: string;
+                token_address: string;
+                token_symbol: string;
+                chain: import("./generated/types.js").components["schemas"]["ChainDescriptor"];
                 status: "pending" | "submitted" | "settled" | "requires_review";
                 transaction_hash: string | null;
             } | null;
@@ -64,12 +67,15 @@ export declare class XKOVAMemberResources {
             credit: {
                 amount: string;
                 token_deployment_id: string;
+                token_address: string;
+                token_symbol: string;
+                chain: import("./generated/types.js").components["schemas"]["ChainDescriptor"];
                 status: "pending" | "submitted" | "settled" | "requires_review";
                 transaction_hash: string | null;
             } | null;
         }>;
         actionReadiness: (control?: XKOVARequestControl) => Promise<{
-            authorization_method: "hosted_passkey" | "external_oidc";
+            authorization_method: "hosted_passkey" | "external_oidc" | "xkova_webauthn";
             setup_status: "passkey_required" | "recovery_acknowledgement_required" | "recovery_required" | "ready" | "externally_managed";
             action_authorization_enabled: boolean;
             requires_fresh_proof: true;
@@ -103,10 +109,20 @@ export declare class XKOVAMemberResources {
         }>;
         balance: (control?: XKOVARequestControl) => Promise<{
             balances: import("./generated/types.js").components["schemas"]["AccountHolderSelfBalanceEntry"][];
+            data_freshness: import("./generated/types.js").components["schemas"]["DataFreshness"][];
         }>;
         wallets: (control?: XKOVARequestControl) => Promise<{
             data: import("./generated/types.js").components["schemas"]["Wallet"][];
         }>;
+        walletAuth: (control?: XKOVARequestControl) => Promise<{
+            strategy: "auth_endpoint";
+            payload: string;
+            client_id: string;
+            project_id: string;
+            external_user_id: string;
+            expires_at: string;
+            expected_address?: string;
+        } & Record<string, never>>;
         walletReadiness: (control?: XKOVARequestControl) => Promise<{
             status: "not_registered" | "provisioning" | "ready";
             wallets: import("./generated/types.js").components["schemas"]["Wallet"][];

package/dist/member-resources.js

@@ -31,7 +31,7 @@ export class XKOVAMemberResources {
         return this.client.wallets;
     }
     self = {
-        profile: () => this.client.accountHolders.retrieve(this.accountHolderId),
+        profile: () => this.client.accountHolders.selfProfile(this.context),
         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),
@@ -39,6 +39,7 @@ export class XKOVAMemberResources {
         verification: (control) => this.client.accountHolders.selfVerification(this.context, control),
         balance: (control) => this.client.accountHolders.selfBalance(this.context, control),
         wallets: (control) => this.client.accountHolders.listSelfWallets(this.context, control),
+        walletAuth: (control) => this.client.accountHolders.selfWalletAuth(this.context, control),
         walletReadiness: (control) => this.client.accountHolders.selfWalletReadiness(this.context, control),
         ensureWalletProvisioning: (opts) => this.client.accountHolders.ensureSelfWalletProvisioning(this.context, opts),
         bankBalance: (control) => this.client.accountHolders.selfBankBalance(this.context, control),
@@ -50,10 +51,10 @@ export class XKOVAMemberResources {
         requestDataExport: (opts) => this.client.accountHolders.requestSelfDataExport(this.context, opts),
         dataExport: (id, control) => this.client.accountHolders.selfDataExport(this.context, id, control),
         transactions: (query, control) => this.client.accountHolders.listSelfTransactions(this.context, query, control),
-        avatar: () => this.client.accountHolders.avatarUrl(this.accountHolderId),
-        uploadAvatar: (image, control) => this.client.accountHolders.uploadAvatar(this.accountHolderId, image, control),
-        deleteAvatar: (opts) => this.client.accountHolders.deleteAvatar(this.accountHolderId, opts),
-        confirmAvatar: (body, opts) => this.client.accountHolders.confirmAvatar(this.accountHolderId, body, opts),
-        presignAvatarUpload: (body, opts) => this.client.accountHolders.presignAvatarUpload(this.accountHolderId, body, opts),
+        avatar: () => this.client.accountHolders.selfAvatarUrl(this.context),
+        uploadAvatar: (image, control) => this.client.accountHolders.uploadSelfAvatar(this.context, image, control),
+        deleteAvatar: (opts) => this.client.accountHolders.deleteSelfAvatar(this.context, opts),
+        confirmAvatar: (body, opts) => this.client.accountHolders.confirmSelfAvatar(this.context, body, opts),
+        presignAvatarUpload: (body, opts) => this.client.accountHolders.presignSelfAvatarUpload(this.context, body, opts),
     };
 }

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

@@ -100,6 +100,32 @@ export declare class AccountHoldersResource extends Resource {
         next_cursor?: string | null;
         has_more: boolean;
     }>;
+    selfProfile(context: XKOVAMemberSessionContext, control?: XKOVARequestControl): 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;
+    }>;
     selfVerification(context: XKOVAMemberSessionContext, control?: XKOVARequestControl): Promise<{
         required: boolean;
         status: string;
@@ -126,6 +152,9 @@ export declare class AccountHoldersResource extends Resource {
         credit: {
             amount: string;
             token_deployment_id: string;
+            token_address: string;
+            token_symbol: string;
+            chain: import("../generated/types.js").components["schemas"]["ChainDescriptor"];
             status: "pending" | "submitted" | "settled" | "requires_review";
             transaction_hash: string | null;
         } | null;
@@ -138,16 +167,29 @@ export declare class AccountHoldersResource extends Resource {
         credit: {
             amount: string;
             token_deployment_id: string;
+            token_address: string;
+            token_symbol: string;
+            chain: import("../generated/types.js").components["schemas"]["ChainDescriptor"];
             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"][];
+        data_freshness: import("../generated/types.js").components["schemas"]["DataFreshness"][];
     }>;
     listSelfWallets(context: XKOVAMemberSessionContext, control?: XKOVARequestControl): Promise<{
         data: import("../generated/types.js").components["schemas"]["Wallet"][];
     }>;
+    selfWalletAuth(context: XKOVAMemberSessionContext, control?: XKOVARequestControl): Promise<{
+        strategy: "auth_endpoint";
+        payload: string;
+        client_id: string;
+        project_id: string;
+        external_user_id: string;
+        expires_at: string;
+        expected_address?: string;
+    } & Record<string, never>>;
     selfWalletReadiness(context: XKOVAMemberSessionContext, control?: XKOVARequestControl): Promise<{
         status: "not_registered" | "provisioning" | "ready";
         wallets: import("../generated/types.js").components["schemas"]["Wallet"][];
@@ -173,7 +215,7 @@ export declare class AccountHoldersResource extends Resource {
     selfActionReadiness(context: XKOVAMemberSessionContext & {
         accountHolderId: string;
     }, control?: XKOVARequestControl): Promise<{
-        authorization_method: "hosted_passkey" | "external_oidc";
+        authorization_method: "hosted_passkey" | "external_oidc" | "xkova_webauthn";
         setup_status: "passkey_required" | "recovery_acknowledgement_required" | "recovery_required" | "ready" | "externally_managed";
         action_authorization_enabled: boolean;
         requires_fresh_proof: true;
@@ -253,6 +295,70 @@ export declare class AccountHoldersResource extends Resource {
     uploadAvatar(id: string, image: Blob, control?: XKOVARequestControl): Promise<{
         url: string | null;
     }>;
+    uploadSelfAvatar(context: XKOVAMemberSessionContext, image: Blob, control?: XKOVARequestControl): Promise<{
+        url: string | null;
+    }>;
+    private uploadAvatarImage;
+    selfAvatarUrl(context: XKOVAMemberSessionContext): Promise<{
+        url: string | null;
+    }>;
+    deleteSelfAvatar(context: XKOVAMemberSessionContext, opts?: XKOVAMutationOptions): 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;
+    }>;
+    confirmSelfAvatar(context: XKOVAMemberSessionContext, body: ReqBody<'confirmAccountHolderSelfAvatar'>, opts?: XKOVAMutationOptions): 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;
+    }>;
+    presignSelfAvatarUpload(context: XKOVAMemberSessionContext, body: ReqBody<'presignAccountHolderSelfAvatarUpload'>, opts?: XKOVAMutationOptions): Promise<{
+        upload_url: string;
+        object_key: string;
+        expires_at: import("../generated/types.js").components["schemas"]["TimestampUtc"];
+    }>;
     avatarUrl(id: string): Promise<{
         url: string | null;
     }>;

package/dist/resources/account-holders.js

@@ -28,6 +28,9 @@ export class AccountHoldersResource extends Resource {
     history(id, query = {}) {
         return this.getJson(`/account-holders/${this.enc(id)}/history`, query);
     }
+    selfProfile(context, control) {
+        return this.getJson('/account-holders/self', undefined, control, memberSessionHeaders(context));
+    }
     selfVerification(context, control) {
         return this.getJson('/account-holders/self/verification', undefined, control, memberSessionHeaders(context));
     }
@@ -43,6 +46,9 @@ export class AccountHoldersResource extends Resource {
     listSelfWallets(context, control) {
         return this.getJson('/account-holders/self/wallets', undefined, control, memberSessionHeaders(context));
     }
+    selfWalletAuth(context, control) {
+        return this.postJson('/account-holders/self/wallet-auth', undefined, control, undefined, memberSessionHeaders(context));
+    }
     selfWalletReadiness(context, control) {
         return this.getJson('/account-holders/self/wallet-readiness', undefined, control, memberSessionHeaders(context));
     }
@@ -64,7 +70,7 @@ export class AccountHoldersResource extends Resource {
         }
         const readiness = status.action_readiness;
         if (!readiness ||
-            !['hosted_passkey', 'external_oidc'].includes(readiness.authorization_method) ||
+            !['hosted_passkey', 'external_oidc', 'xkova_webauthn'].includes(readiness.authorization_method) ||
             ![
                 'passkey_required',
                 'recovery_acknowledgement_required',
@@ -109,15 +115,26 @@ export class AccountHoldersResource extends Resource {
      * member context and cookies never follow the presigned URL or a redirect.
      */
     async uploadAvatar(id, image, control = {}) {
+        return this.uploadAvatarImage(image, control, {
+            presign: (body) => this.presignAvatarUpload(id, body, control),
+            confirm: (object_key) => this.confirmAvatar(id, { object_key }, control),
+            read: () => this.avatarUrl(id),
+        });
+    }
+    async uploadSelfAvatar(context, image, control = {}) {
+        return this.uploadAvatarImage(image, control, {
+            presign: (body) => this.presignSelfAvatarUpload(context, body, control),
+            confirm: (object_key) => this.confirmSelfAvatar(context, { object_key }, control),
+            read: () => this.selfAvatarUrl(context),
+        });
+    }
+    async uploadAvatarImage(image, control, operations) {
         if (!['image/png', 'image/jpeg', 'image/webp', 'image/gif'].includes(image.type) ||
             image.size === 0 ||
             image.size > 5 * 1024 * 1024) {
             throw new TypeError('Avatar must be a PNG, JPEG, WebP, or GIF image of at most 5 MiB');
         }
-        const upload = await this.presignAvatarUpload(id, {
-            content_type: image.type,
-            content_length: image.size,
-        }, control);
+        const upload = await operations.presign({ content_type: image.type, content_length: image.size });
         const target = new URL(upload.upload_url);
         if (target.username ||
             target.password ||
@@ -151,8 +168,20 @@ export class AccountHoldersResource extends Resource {
         }
         if (!response.ok)
             throw new XKOVAUploadError('Object storage rejected the avatar upload', response.status);
-        await this.confirmAvatar(id, { object_key: upload.object_key }, control);
-        return this.avatarUrl(id);
+        await operations.confirm(upload.object_key);
+        return operations.read();
+    }
+    selfAvatarUrl(context) {
+        return this.getJson('/account-holders/self/avatar', undefined, {}, memberSessionHeaders(context));
+    }
+    deleteSelfAvatar(context, opts) {
+        return this.deleteJson('/account-holders/self/avatar', opts, undefined, memberSessionHeaders(context));
+    }
+    confirmSelfAvatar(context, body, opts) {
+        return this.postJson('/account-holders/self/avatar/confirm', body, opts, undefined, memberSessionHeaders(context));
+    }
+    presignSelfAvatarUpload(context, body, opts) {
+        return this.postJson('/account-holders/self/avatar/upload-url', body, opts, undefined, memberSessionHeaders(context));
     }
     avatarUrl(id) {
         return this.getJson(`/account-holders/${this.enc(id)}/avatar`);

package/dist/resources/branding.d.ts

@@ -2,6 +2,8 @@ import { Resource, type ReqBody, type Query } from './base.js';
 import type { XKOVAMutationOptions } from '../client.js';
 export declare class BrandingResource extends Resource {
     get(): Promise<{
+        logo_upload_limits: import("../generated/types.js").components["schemas"]["LogoUploadLimits"];
+        has_logo_override: boolean;
         resolved: {
             brand_name: string;
             legal_name: string;
@@ -28,6 +30,8 @@ export declare class BrandingResource extends Resource {
         theme: import("../generated/types.js").components["schemas"]["TenantBrandingTheme"];
     }>;
     upsert(body: ReqBody<'upsertBranding'>, opts?: XKOVAMutationOptions): Promise<{
+        logo_upload_limits: import("../generated/types.js").components["schemas"]["LogoUploadLimits"];
+        has_logo_override: boolean;
         resolved: {
             brand_name: string;
             legal_name: string;
@@ -94,12 +98,16 @@ export declare class BrandingResource extends Resource {
         last_synced_at: string;
         created_at: string;
     }>;
+    /** Upload bytes to the returned URL, then confirm its opaque key as the same tenant. */
     logoUploadUrl(body: ReqBody<'brandingLogoUploadUrl'>, opts?: XKOVAMutationOptions): Promise<{
         upload_url: string;
         object_key: string;
         expires_at: string;
     }>;
+    /** Publish a newly issued upload. Saved logo URLs or keys are not upload keys. */
     confirmLogo(body: ReqBody<'confirmBrandingLogo'>, opts?: XKOVAMutationOptions): Promise<{
+        logo_upload_limits: import("../generated/types.js").components["schemas"]["LogoUploadLimits"];
+        has_logo_override: boolean;
         resolved: {
             brand_name: string;
             legal_name: string;
@@ -126,6 +134,8 @@ export declare class BrandingResource extends Resource {
         theme: import("../generated/types.js").components["schemas"]["TenantBrandingTheme"];
     }>;
     deleteLogo(opts?: XKOVAMutationOptions): Promise<{
+        logo_upload_limits: import("../generated/types.js").components["schemas"]["LogoUploadLimits"];
+        has_logo_override: boolean;
         resolved: {
             brand_name: string;
             legal_name: string;

package/dist/resources/branding.js

@@ -22,9 +22,11 @@ export class BrandingResource extends Resource {
     verifyEmailDomain(id, opts) {
         return this.postJson(`/branding/email-domains/${this.enc(id)}/verify`, undefined, opts);
     }
+    /** Upload bytes to the returned URL, then confirm its opaque key as the same tenant. */
     logoUploadUrl(body, opts) {
         return this.postJson('/branding/logo/upload-url', body, opts);
     }
+    /** Publish a newly issued upload. Saved logo URLs or keys are not upload keys. */
     confirmLogo(body, opts) {
         return this.postJson('/branding/logo', body, opts);
     }

package/dist/resources/escrows.d.ts

@@ -7,6 +7,7 @@ export declare class EscrowsResource extends Resource {
         has_more: boolean;
     }>;
     create(body: ReqBody<'createEscrow'>, opts?: XKOVAMutationOptions): Promise<{
+        notification_status?: "queued" | "sent" | "failed" | "cancelled";
         escrow: import("../generated/types.js").components["schemas"]["Escrow"];
         claim_token: string;
         claim_url: string;
@@ -15,6 +16,7 @@ export declare class EscrowsResource extends Resource {
         signing_expires_at?: import("../generated/types.js").components["schemas"]["TimestampUtc"] | null;
     }>;
     retrieve(id: string, query?: Query<'getEscrow'>): Promise<{
+        notification_status?: "queued" | "sent" | "failed" | "cancelled";
         id: import("../generated/types.js").components["schemas"]["EscrowId"];
         chain: import("../generated/types.js").components["schemas"]["ChainDescriptor"];
         fingerprint: string;
@@ -28,6 +30,7 @@ export declare class EscrowsResource extends Resource {
         on_chain_payment_id?: string | null;
         create_tx_hash?: string | null;
         release_tx_hash?: string | null;
+        data_freshness?: import("../generated/types.js").components["schemas"]["DataFreshness"][];
         fee_accruals?: import("../generated/types.js").components["schemas"]["EscrowFeeAccrual"][];
         net_amount?: import("../generated/types.js").components["schemas"]["Money"] | null;
         claimed_at?: import("../generated/types.js").components["schemas"]["TimestampUtc"] | null;