@capxul/sdk 0.1.0-alpha.0

package/dist/index.d.cts

@@ -0,0 +1,495 @@
+import { S as Session, C as CapxulClient, A as AccountProvisionPersonalInput } from './client-BNGGubL2.cjs';
+export { a as AccountsClient, b as ApiKeyCreateResult, c as ApiKeysClient, d as AuthClient, e as AuthSessionStore, B as BrowserCapxulConfig, f as CapxulAuthConfig, g as CapxulConfig, h as CapxulDataClient, i as CapxulFlowFactories, j as CapxulSigningConfig, D as DocumentsClient, E as ExternalAccountsClient, H as HttpTransport, L as LocalPrivateKeySignerProvider, M as MeClient, O as OperationsClient, k as OrgDocumentsClient, l as OrgPaymentsClient, m as OrgSafesClient, n as OrgTransfersClient, o as OrgTreasuryClient, p as OrgWithdrawalsClient, q as OrganizationsClient, P as PaymentsClient, r as SubAccountsClient, T as TransfersClient, s as TransportRuntime, t as TransportState, V as VirtualAccountsClient, u as VirtualCardsClient, W as WebhookEndpointCreateResult, v as WebhookEndpointsClient, w as WebhookEventsClient, x as WithdrawalsClient, y as createCapxulClient, z as makeHttpTransport } from './client-BNGGubL2.cjs';
+import * as xstate from 'xstate';
+import { CapxulError as CapxulError$1 } from '@repo/config';
+import { Email, Username, OperationId, NextAction, CapxulErrorCode } from '@repo/platform-kernel';
+export { AccountId, ApiKeyId, BalanceLedgerEntryId, CapxulErrorCode, CapxulErrorDetails, CapxulErrorEnvelope, CorrelationId, DocumentId, Email, ExternalAccountId, KybProfileId, KycProfileId, MemberId, NextAction, OperationId, OrganizationId, PaymentId, PhoneNumber, SafeId, SubAccountId, TransactionIntentId, TransferId, TreasuryId, Username, VirtualAccountId, VirtualCardId, WebhookEndpointId, WebhookEventId, WithdrawalId, toAccountId, toApiKeyId, toBalanceLedgerEntryId, toDocumentId, toEmail, toExternalAccountId, toKybProfileId, toKycProfileId, toMemberId, toOperationId, toOrganizationId, toPaymentId, toPhoneNumber, toSafeId, toSubAccountId, toTransferId, toTreasuryId, toUsername, toVirtualAccountId, toVirtualCardId, toWebhookEndpointId, toWebhookEventId, toWithdrawalId } from '@repo/platform-kernel';
+import { CapxulError } from './errors.cjs';
+export { CapxulResult } from './errors.cjs';
+import { A as Account } from './types-Cokyqgwm.cjs';
+export { a as AccountLookupResult, b as ApiKey, c as ApiKeyEnvironment, d as ApiKeyType, B as BalanceLedgerEntry, e as BankStatementDocument, C as CreatePaymentResult, f as CreateTransferResult, g as CreateWithdrawalResult, D as Document, E as ExternalAccount, h as ExternalAccountKind, I as InvoiceDocument, K as KybProfile, i as KycProfile, j as KycUploadDocument, L as List, M as Member, k as Money, O as Operation, l as OperationStatus, m as OperationSummary, n as Organization, P as PageInfo, o as Payment, p as PaymentParty, q as PaymentStatus, r as PayrollRunDocument, s as PayrollScheduleDocument, R as ReceiptDocument, S as Safe, t as Scope, u as Settlement, v as SubAccount, w as SubAccountOwnerKind, T as TaxFormDocument, x as TimestampIso, y as Transfer, z as TransferCustody, F as TransferEndpoint, G as TransferFx, H as TransferStatus, J as Treasury, U as UserIdentifier, V as VirtualAccount, N as VirtualAccountOwnerKind, Q as VirtualCard, W as VirtualCardLimits, X as VirtualCardOwnerKind, Y as WebhookEndpoint, Z as WebhookEvent, _ as Withdrawal, $ as WithdrawalStatus } from './types-Cokyqgwm.cjs';
+import { Account as Account$1 } from 'viem';
+export { WebhookVerificationOptions, WebhookVerificationResult, verifyWebhook } from './webhooks.cjs';
+import '@repo/api-contract/gen/types';
+
+/**
+ * Auth flow errors may originate from two CapxulError surfaces:
+ *  - the SDK-local generic `CapxulError<Codes>` returned by
+ *    `client.auth.*` tuple methods
+ *  - the `@repo/config` `CapxulError` produced by the `Errors.xxx()`
+ *    factory family (per `error-handling.md`)
+ *
+ * Both share `.code`, `.message`, `.details`, and extend `Error`. The
+ * union keeps either origin assignable to `context.error` without an
+ * `as` cast at the call site.
+ */
+type AuthFlowError = CapxulError | CapxulError$1;
+type AuthFlowContext = {
+    readonly email: Email | null;
+    readonly session: Session | null;
+    readonly error: AuthFlowError | null;
+};
+type AuthFlowEvent = {
+    readonly type: "REQUEST_OTP";
+    readonly email: Email;
+} | {
+    readonly type: "VERIFY";
+    readonly code: string;
+} | {
+    readonly type: "RESET";
+} | {
+    readonly type: "SIGN_OUT";
+};
+/**
+ * Build the auth state machine bound to a `CapxulClient` instance.
+ *
+ * States: `idle -> sending_otp -> otp_requested -> verifying ->
+ * authenticated -> signing_out -> idle`, with `error` as a sidecar
+ * from any async step.
+ */
+declare function createAuthFlowMachine(client: CapxulClient): xstate.StateMachine<AuthFlowContext, {
+    readonly type: "REQUEST_OTP";
+    readonly email: Email;
+} | {
+    readonly type: "VERIFY";
+    readonly code: string;
+} | {
+    readonly type: "RESET";
+} | {
+    readonly type: "SIGN_OUT";
+}, {
+    [x: string]: xstate.ActorRefFromLogic<xstate.PromiseActorLogic<void, {
+        email: Email;
+    }, xstate.EventObject>> | xstate.ActorRefFromLogic<xstate.PromiseActorLogic<Session, {
+        email: Email;
+        code: string;
+    }, xstate.EventObject>> | xstate.ActorRefFromLogic<xstate.PromiseActorLogic<void, void, xstate.EventObject>> | undefined;
+}, {
+    src: "sendOtp";
+    logic: xstate.PromiseActorLogic<void, {
+        email: Email;
+    }, xstate.EventObject>;
+    id: string | undefined;
+} | {
+    src: "verifyOtp";
+    logic: xstate.PromiseActorLogic<Session, {
+        email: Email;
+        code: string;
+    }, xstate.EventObject>;
+    id: string | undefined;
+} | {
+    src: "signOut";
+    logic: xstate.PromiseActorLogic<void, void, xstate.EventObject>;
+    id: string | undefined;
+}, {
+    type: "trackOtpRequested";
+    params: unknown;
+} | {
+    type: "trackOtpFailed";
+    params: unknown;
+} | {
+    type: "trackTimeoutFailed";
+    params: unknown;
+} | {
+    type: "trackVerified";
+    params: unknown;
+} | {
+    type: "identifyAndTrack";
+    params: unknown;
+} | {
+    type: "trackSignedOut";
+    params: unknown;
+}, never, never, "idle" | "authenticated" | "error" | "sending_otp" | "otp_requested" | "verifying" | "signing_out", string, xstate.NonReducibleUnknown, xstate.NonReducibleUnknown, xstate.EventObject, xstate.MetaObject, {
+    id: "auth";
+    states: {
+        readonly idle: {};
+        readonly sending_otp: {};
+        readonly otp_requested: {};
+        readonly verifying: {};
+        readonly authenticated: {};
+        readonly signing_out: {};
+        readonly error: {};
+    };
+}>;
+
+/**
+ * Provisioning flow errors may originate from two CapxulError surfaces:
+ *  - the SDK-local generic `CapxulError<Codes>` returned by
+ *    `client.accounts.provisionPersonal`
+ *  - the `@repo/config` `CapxulError` produced by the `Errors.xxx()`
+ *    factory family (per `error-handling.md`) used for non-CapxulError
+ *    cause wrapping and the timeout error
+ *
+ * Both share `.code`, `.message`, `.details`, and extend `Error`.
+ */
+type ProvisioningFlowError = CapxulError | CapxulError$1;
+type ProvisioningFlowContext = {
+    readonly input: AccountProvisionPersonalInput | null;
+    readonly account: Account | null;
+    readonly error: ProvisioningFlowError | null;
+};
+type ProvisioningFlowEvent = {
+    readonly type: "START";
+    readonly input: AccountProvisionPersonalInput;
+};
+/**
+ * Input accepted at machine startup. Optional — when present the
+ * machine seeds context from it and skips `idle`. When absent the
+ * machine sits in `idle` and waits for a `START` event.
+ *
+ * The `| undefined` half of this union is what lets standalone
+ * callers write `createActor(machine, { input: undefined })` (or pass
+ * no input via `{}`), because XState v5's `RequiredActorOptionsKeys`
+ * computes `undefined extends InputFrom<TLogic> ? never : 'input'`
+ * and standalone callers need that to resolve to `never`. Invoked-by-
+ * parent callsites pass the populated `{ input }` shape via
+ * `invoke.input` and the `context` factory below narrows it.
+ */
+type ProvisioningFlowInput = {
+    readonly input: AccountProvisionPersonalInput;
+} | undefined;
+/**
+ * Output emitted when the machine reaches a top-level final state
+ * (`done` or `error`). Parents that invoke this machine (e.g.
+ * onboarding) read this via `event.output` on their `onDone`
+ * transition and branch with a guard on `event.output.error`.
+ */
+type ProvisioningFlowOutput = {
+    readonly account: Account;
+    readonly error?: undefined;
+} | {
+    readonly account?: undefined;
+    readonly error: ProvisioningFlowError;
+};
+/**
+ * Build the provisioning state machine bound to a `CapxulClient`
+ * instance.
+ *
+ * States: `starting -> idle | running -> done | error`. `starting` is
+ * a transient routing state: if the machine was created with input,
+ * it goes straight to `running`; otherwise it falls back to `idle`
+ * and waits for a `START` event. Both `done` and `error` are
+ * top-level XState v5 `final` states; the machine's root-level
+ * `output` mapper inspects `context` to produce
+ * `{ account } | { error }` for the parent's `onDone` event.
+ *
+ * Per-state-node `output` is not supported in XState v5 — only the
+ * machine root has an `output` mapper, which is why this file derives
+ * the discriminated payload from `context.error` vs `context.account`.
+ */
+declare function createProvisioningMachine(client: CapxulClient): xstate.StateMachine<ProvisioningFlowContext, {
+    readonly type: "START";
+    readonly input: AccountProvisionPersonalInput;
+}, {
+    [x: string]: xstate.ActorRefFromLogic<xstate.PromiseActorLogic<Account, {
+        input: AccountProvisionPersonalInput;
+    }, xstate.EventObject>> | undefined;
+}, {
+    src: "provisionPersonal";
+    logic: xstate.PromiseActorLogic<Account, {
+        input: AccountProvisionPersonalInput;
+    }, xstate.EventObject>;
+    id: string | undefined;
+}, {
+    type: "trackWalletCreated";
+    params: unknown;
+} | {
+    type: "trackSafeCreated";
+    params: unknown;
+}, {
+    type: "hasInput";
+    params: unknown;
+}, never, "idle" | "error" | "done" | "starting" | "running", string, {
+    readonly input: AccountProvisionPersonalInput;
+}, {
+    readonly account: Account;
+    readonly error?: undefined;
+} | {
+    readonly account?: undefined;
+    readonly error: ProvisioningFlowError;
+}, xstate.EventObject, xstate.MetaObject, {
+    id: "provisioning";
+    states: {
+        readonly starting: {};
+        readonly idle: {};
+        readonly running: {};
+        readonly done: {};
+        readonly error: {};
+    };
+}>;
+
+/**
+ * Onboarding flow errors may originate from two CapxulError surfaces:
+ *  - the SDK-local generic `CapxulError<Codes>` returned by
+ *    `client.accounts.provisionPersonal` and constructed for synchronous
+ *    pre-actor rejections (NOT_IMPLEMENTED, INVALID_INPUT)
+ *  - the `@repo/config` `CapxulError` produced by the `Errors.xxx()`
+ *    factory family (per `error-handling.md`) used for non-CapxulError
+ *    cause wrapping and the timeout error
+ *
+ * Both share `.code`, `.message`, `.details`, and extend `Error`.
+ */
+type OnboardingFlowError = CapxulError | CapxulError$1;
+/** Subjects supported by the onboarding flow. */
+type OnboardingSubjectKind = "account" | "organization";
+/**
+ * Input captured by the "profile" step before Safe provisioning.
+ *
+ * For `kind: "organization"`, `organizationName` is required (this lift
+ * does not implement the org branch — see `error.code = "NOT_IMPLEMENTED"`).
+ */
+type OnboardingProfileInput = {
+    readonly kind: OnboardingSubjectKind;
+    readonly username?: Username;
+    readonly displayName?: string;
+    readonly country?: string;
+    readonly organizationName?: string;
+    readonly signerProvider?: AccountProvisionPersonalInput["signerProvider"];
+};
+type OnboardingFlowContext = {
+    readonly input: OnboardingProfileInput | null;
+    readonly operationId: OperationId | null;
+    readonly account: Account | null;
+    readonly error: OnboardingFlowError | null;
+};
+type OnboardingFlowEvent = {
+    readonly type: "START_PROVISIONING";
+    readonly input: OnboardingProfileInput;
+} | {
+    readonly type: "PROCEED";
+} | {
+    readonly type: "RESET";
+};
+/**
+ * Build the onboarding state machine bound to a `CapxulClient`
+ * instance.
+ *
+ * States: `profile -> provisioning -> complete` on the happy path,
+ * with `error` reachable from `profile` (validation rejections) or
+ * `provisioning` (spawned-machine reported error / outer timeout /
+ * unhandled child throw). `action_required` is declared for parity
+ * with the public `OnboardingFlowState` type but is unreachable in
+ * this lift.
+ *
+ * The `provisioning` state invokes a spawned `provisioningMachine`
+ * (built from `createProvisioningMachine(client)`) rather than the
+ * `provisionPersonal` actor directly. The child machine reports its
+ * outcome via its root-level `output` (`{ account } | { error }`),
+ * which the parent observes on `onDone` and branches on via guards.
+ */
+declare function createOnboardingFlowMachine(client: CapxulClient): xstate.StateMachine<OnboardingFlowContext, {
+    readonly type: "START_PROVISIONING";
+    readonly input: OnboardingProfileInput;
+} | {
+    readonly type: "PROCEED";
+} | {
+    readonly type: "RESET";
+}, {
+    [x: string]: xstate.ActorRefFromLogic<xstate.StateMachine<ProvisioningFlowContext, {
+        readonly type: "START";
+        readonly input: AccountProvisionPersonalInput;
+    }, {
+        [x: string]: xstate.ActorRefFromLogic<xstate.PromiseActorLogic<Account, {
+            input: AccountProvisionPersonalInput;
+        }, xstate.EventObject>> | undefined;
+    }, {
+        src: "provisionPersonal";
+        logic: xstate.PromiseActorLogic<Account, {
+            input: AccountProvisionPersonalInput;
+        }, xstate.EventObject>;
+        id: string | undefined;
+    }, {
+        type: "trackWalletCreated";
+        params: unknown;
+    } | {
+        type: "trackSafeCreated";
+        params: unknown;
+    }, {
+        type: "hasInput";
+        params: unknown;
+    }, never, "idle" | "error" | "done" | "starting" | "running", string, {
+        readonly input: AccountProvisionPersonalInput;
+    }, {
+        readonly account: Account;
+        readonly error?: undefined;
+    } | {
+        readonly account?: undefined;
+        readonly error: ProvisioningFlowError;
+    }, xstate.EventObject, xstate.MetaObject, {
+        id: "provisioning";
+        states: {
+            readonly starting: {};
+            readonly idle: {};
+            readonly running: {};
+            readonly done: {};
+            readonly error: {};
+        };
+    }>> | undefined;
+}, {
+    src: "provisioningMachine";
+    logic: xstate.StateMachine<ProvisioningFlowContext, {
+        readonly type: "START";
+        readonly input: AccountProvisionPersonalInput;
+    }, {
+        [x: string]: xstate.ActorRefFromLogic<xstate.PromiseActorLogic<Account, {
+            input: AccountProvisionPersonalInput;
+        }, xstate.EventObject>> | undefined;
+    }, {
+        src: "provisionPersonal";
+        logic: xstate.PromiseActorLogic<Account, {
+            input: AccountProvisionPersonalInput;
+        }, xstate.EventObject>;
+        id: string | undefined;
+    }, {
+        type: "trackWalletCreated";
+        params: unknown;
+    } | {
+        type: "trackSafeCreated";
+        params: unknown;
+    }, {
+        type: "hasInput";
+        params: unknown;
+    }, never, "idle" | "error" | "done" | "starting" | "running", string, {
+        readonly input: AccountProvisionPersonalInput;
+    }, {
+        readonly account: Account;
+        readonly error?: undefined;
+    } | {
+        readonly account?: undefined;
+        readonly error: ProvisioningFlowError;
+    }, xstate.EventObject, xstate.MetaObject, {
+        id: "provisioning";
+        states: {
+            readonly starting: {};
+            readonly idle: {};
+            readonly running: {};
+            readonly done: {};
+            readonly error: {};
+        };
+    }>;
+    id: string | undefined;
+}, {
+    type: "assignOperationIdAndInput";
+    params: unknown;
+} | {
+    type: "assignOrgNotImplemented";
+    params: unknown;
+} | {
+    type: "assignMissingSigner";
+    params: unknown;
+} | {
+    type: "trackOrgSubmitted";
+    params: unknown;
+} | {
+    type: "trackPersonalSubmitted";
+    params: unknown;
+} | {
+    type: "trackOrgNotImplementedError";
+    params: unknown;
+} | {
+    type: "trackMissingSignerError";
+    params: unknown;
+} | {
+    type: "trackWalletCreating";
+    params: unknown;
+} | {
+    type: "trackOnboardingCompleted";
+    params: unknown;
+} | {
+    type: "trackProvisioningFailed";
+    params: unknown;
+} | {
+    type: "assignChildReportedError";
+    params: unknown;
+} | {
+    type: "assignChildThrown";
+    params: unknown;
+} | {
+    type: "assignAccountFromChild";
+    params: unknown;
+} | {
+    type: "resetContext";
+    params: unknown;
+}, {
+    type: "isOrg";
+    params: unknown;
+} | {
+    type: "missingSigner";
+    params: unknown;
+} | {
+    type: "childReportedError";
+    params: unknown;
+}, never, "action_required" | "provisioning" | "error" | "profile" | "complete", string, xstate.NonReducibleUnknown, xstate.NonReducibleUnknown, xstate.EventObject, xstate.MetaObject, {
+    id: "onboarding";
+    states: {
+        readonly profile: {};
+        readonly provisioning: {};
+        readonly action_required: {};
+        readonly complete: {};
+        readonly error: {};
+    };
+}>;
+
+/**
+ * Exhaustive error-code dispatch per CANON.md §4.44.
+ *
+ * Given a `CapxulError<Codes>` and a handlers object keyed by `Codes`,
+ * routes to the matching arm. TypeScript enforces exhaustiveness via
+ * the mapped-key union: missing a code the method can produce is a
+ * compile error, and handling a code the method CANNOT produce is a
+ * compile error (the handler key isn't assignable to `Codes`).
+ *
+ * No `default:` arm needed — the compile-time exhaustiveness check is
+ * the contract.
+ */
+declare function matchError<Codes extends CapxulErrorCode, R>(err: CapxulError<Codes>, handlers: {
+    [K in Codes]: (err: CapxulError<K>) => R;
+}): R;
+/**
+ * Exhaustive resource-status dispatch per CANON.md §4.44.
+ *
+ * The generic `T extends { status: string }` lets downstream callers
+ * pass any discriminated-union resource (Payment, Safe, Transfer,
+ * Operation, etc.). Handlers are keyed on the literal `status` values
+ * declared by `T`, so passing a status not in `T["status"]` is a
+ * compile error.
+ */
+declare function matchStatus<T extends {
+    status: string;
+}, R>(value: T, handlers: {
+    [K in T["status"]]: (value: Extract<T, {
+        status: K;
+    }>) => R;
+}): R;
+/**
+ * Exhaustive NextAction.kind dispatch per CANON.md §4.44.
+ *
+ * Handlers must cover every `kind` in the union `A`. `A` defaults to
+ * `NextAction` from `@repo/platform-kernel` — the 8-variant canonical
+ * union. CANON.md §4.58 adds a 9th variant (`confirm_fx_quote`); once
+ * the kernel's `NextAction` grows, this helper automatically picks it
+ * up via the generic default.
+ *
+ * Pass `A extends NextAction` explicitly when you need a narrower
+ * variant subset (e.g. a per-method narrowing that excludes
+ * `contact_support`).
+ */
+declare function matchAction<A extends NextAction, R>(action: A, handlers: {
+    [K in A["kind"]]: (action: Extract<A, {
+        kind: K;
+    }>) => R;
+}): R;
+
+/**
+ * Convenience constructor for a viem `Account` backed by a raw private
+ * key — the CLI / server-side signer per CANON.md §4.28.
+ *
+ * The SDK accepts `viem.Account` directly; this helper just saves the
+ * caller an import. For Openfort / MetaMask / other browser signers,
+ * use `@capxul/sdk-react` (follow-up slice).
+ *
+ * @param privateKey `0x`-prefixed 32-byte hex string (64 hex chars).
+ */
+declare function createLocalSigner(privateKey: `0x${string}`): Account$1;
+
+export { Account, AccountProvisionPersonalInput, type AuthFlowContext, type AuthFlowError, type AuthFlowEvent, CapxulClient, CapxulError, type OnboardingFlowContext, type OnboardingFlowError, type OnboardingFlowEvent, type OnboardingProfileInput, type OnboardingSubjectKind, type ProvisioningFlowContext, type ProvisioningFlowError, type ProvisioningFlowEvent, type ProvisioningFlowInput, type ProvisioningFlowOutput, Session, createAuthFlowMachine, createLocalSigner, createOnboardingFlowMachine, createProvisioningMachine as createProvisioningFlowMachine, matchAction, matchError, matchStatus };