@capxul/sdk 0.1.0-alpha.0

package/dist/client.js

@@ -0,0 +1,2270 @@
+import { componentsGeneric, anyApi } from 'convex/server';
+import { getAddress, parseUnits, createPublicClient, http, encodeFunctionData } from 'viem';
+import { toSafeSmartAccount } from 'permissionless/accounts';
+import { entryPoint07Address, createPaymasterClient, createBundlerClient } from 'viem/account-abstraction';
+import { baseSepolia } from 'viem/chains';
+import { setup, fromPromise, assign } from 'xstate';
+
+// src/_generated/api.js
+var api = anyApi;
+componentsGeneric();
+
+// src/errors.ts
+var CapxulError = class extends Error {
+  code;
+  details;
+  operationId;
+  correlationId;
+  retryable;
+  constructor(init) {
+    super(
+      init.message,
+      init.cause !== void 0 ? { cause: init.cause } : void 0
+    );
+    this.name = "CapxulError";
+    this.code = init.code;
+    this.details = init.details;
+    this.operationId = init.operationId;
+    this.correlationId = init.correlationId;
+    this.retryable = init.retryable;
+  }
+};
+function notImplemented(method) {
+  return new CapxulError({
+    code: "NOT_IMPLEMENTED",
+    message: `${method} is not yet implemented in @capxul/sdk (Slice C scaffold).`
+  });
+}
+function stub(method) {
+  return [notImplemented(method), null];
+}
+
+// src/internal/convex-error.ts
+function isConvexClientError(error) {
+  if (typeof error !== "object" || error === null || !("data" in error)) {
+    return false;
+  }
+  const data = error.data;
+  return typeof data === "object" && data !== null;
+}
+function fromConvexError(error) {
+  if (error instanceof CapxulError) {
+    return error;
+  }
+  if (isConvexClientError(error)) {
+    return new CapxulError({
+      code: error.data.code ?? "UNKNOWN",
+      message: error.data.message ?? error.message,
+      details: error.data.details,
+      correlationId: error.data.correlationId,
+      cause: error
+    });
+  }
+  return new CapxulError({
+    code: "UNKNOWN",
+    message: error instanceof Error ? error.message : String(error),
+    cause: error
+  });
+}
+
+// src/core/accounts.ts
+function createAccountsClient(config = {}) {
+  return {
+    retrieve: async () => stub("accounts.retrieve"),
+    lookup: async () => stub("accounts.lookup"),
+    update: async () => stub("accounts.update"),
+    provisionPersonal: async (input) => {
+      if (!config.data) {
+        return stub(
+          "accounts.provisionPersonal"
+        );
+      }
+      if (input.signerProvider.kind !== "local-private-key") {
+        return [
+          new CapxulError({
+            code: "INVALID_INPUT",
+            message: "accounts.provisionPersonal currently supports local-private-key signer providers only."
+          }),
+          null
+        ];
+      }
+      try {
+        await config.data.mutation(
+          api.safe.mutations.provisionLocalPersonalAccount,
+          {
+            displayName: input.displayName,
+            username: input.username,
+            countryCode: input.countryCode,
+            eoaAddress: input.signerProvider.signerAddress,
+            safeAddress: input.signerProvider.safeAddress
+          }
+        );
+        const account = await config.data.query(
+          api.openfort.queries.getMyAccount,
+          {}
+        );
+        if (!account) {
+          return [
+            new CapxulError({
+              code: "NOT_FOUND",
+              message: "accounts.provisionPersonal completed but no account resource was readable."
+            }),
+            null
+          ];
+        }
+        return [null, account];
+      } catch (cause) {
+        return [
+          fromConvexError(cause),
+          null
+        ];
+      }
+    },
+    safes: {
+      retrieve: async (safeId) => {
+        if (!config.data) {
+          return stub("accounts.safes.retrieve");
+        }
+        try {
+          const safe = await config.data.query(
+            api.safe.queries.retrieveAccountSafe,
+            { safeId }
+          );
+          if (!safe) {
+            return [
+              new CapxulError({
+                code: "NOT_FOUND",
+                message: `safe ${safeId} not found`
+              }),
+              null
+            ];
+          }
+          return [null, safe];
+        } catch (cause) {
+          return [
+            fromConvexError(cause),
+            null
+          ];
+        }
+      }
+    },
+    kycProfiles: {
+      create: async () => stub("accounts.kycProfiles.create"),
+      retrieve: async () => stub("accounts.kycProfiles.retrieve")
+    },
+    externalAccounts: {
+      create: async () => stub(
+        "accounts.externalAccounts.create"
+      ),
+      list: async () => stub(
+        "accounts.externalAccounts.list"
+      ),
+      retrieve: async () => stub(
+        "accounts.externalAccounts.retrieve"
+      ),
+      remove: async () => stub("accounts.externalAccounts.remove")
+    },
+    subAccounts: {
+      create: async () => stub("accounts.subAccounts.create"),
+      list: async () => stub("accounts.subAccounts.list"),
+      retrieve: async () => stub("accounts.subAccounts.retrieve"),
+      remove: async () => stub("accounts.subAccounts.remove")
+    },
+    balanceLedger: {
+      list: async () => stub(
+        "accounts.balanceLedger.list"
+      ),
+      retrieve: async () => stub(
+        "accounts.balanceLedger.retrieve"
+      )
+    }
+  };
+}
+
+// src/core/api-keys.ts
+function createApiKeysClient() {
+  return {
+    create: async () => stub("apiKeys.create"),
+    retrieve: async () => stub("apiKeys.retrieve"),
+    list: async () => stub("apiKeys.list"),
+    revoke: async () => stub("apiKeys.revoke")
+  };
+}
+
+// ../config/src/chain.ts
+var CAPXUL_PAYMENTS_ADDRESS = "0xe740ea65521edc9bef0ea75d30b5334711db99f4";
+var TEST_USDC_ADDRESS = "0xf09fcbb6df9f8f918e58f9c8ab15a76ade862b77";
+var CAPXUL_API_BASE_URL = "https://elated-oyster-269.convex.site";
+
+// ../config/src/timing.ts
+var FLOW_INVOKE_TIMEOUT_MS = 3e4;
+
+// ../config/src/errors.ts
+var CapxulError2 = class extends Error {
+  code;
+  details;
+  correlationId;
+  layer;
+  constructor(code, message, options) {
+    super(message, options?.cause ? { cause: options.cause } : void 0);
+    this.code = code;
+    this.details = options?.details;
+    this.correlationId = options?.correlationId;
+    this.layer = options?.layer;
+  }
+};
+var Errors = {
+  notAuthenticated: () => new CapxulError2("NOT_AUTHENTICATED", "Not authenticated"),
+  profileNotFound: (authUserId) => new CapxulError2("PROFILE_NOT_FOUND", `Profile not found for user ${authUserId}`),
+  smartAccountMissing: (authUserId) => new CapxulError2("SMART_ACCOUNT_MISSING", `Smart account not provisioned for user ${authUserId}`),
+  envMissing: (name) => new CapxulError2("ENV_MISSING", `Environment variable ${name} not configured`),
+  openfortApi: (operation, cause) => new CapxulError2(
+    "PROVIDER_ERROR",
+    `Openfort ${operation} failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+    { cause, details: { provider: "openfort", operation } }
+  ),
+  shieldApi: (status, detail) => new CapxulError2(
+    "PROVIDER_ERROR",
+    `Shield API error (${status}): ${detail}`,
+    { details: { provider: "shield", status } }
+  ),
+  providerError: (provider, operation, cause) => new CapxulError2(
+    "PROVIDER_ERROR",
+    `${provider} ${operation} failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+    { cause, details: { provider, operation } }
+  ),
+  invalidInput: (field, reason) => new CapxulError2(
+    "INVALID_INPUT",
+    `Invalid ${field}: ${reason}`,
+    { details: { field, reason } }
+  ),
+  playerNotFound: (playerId) => new CapxulError2(
+    "PLAYER_NOT_FOUND",
+    playerId ? `Openfort player ${playerId} not found` : "Openfort player not found"
+  ),
+  accountNotFound: (accountId) => new CapxulError2(
+    "ACCOUNT_NOT_FOUND",
+    accountId ? `Openfort account ${accountId} not found` : "Openfort smart account not found"
+  ),
+  invalidRecipient: (reason) => new CapxulError2("INVALID_RECIPIENT", reason),
+  permissionDenied: (reason = "Permission denied") => new CapxulError2("PERMISSION_DENIED", reason),
+  notFound: (resource, id) => new CapxulError2(
+    "NOT_FOUND",
+    id ? `${resource} ${id} not found` : `${resource} not found`
+  ),
+  idempotencyConflict: (details) => new CapxulError2(
+    "IDEMPOTENCY_CONFLICT",
+    "Idempotency key was already used for a different request",
+    { details }
+  ),
+  emailDeliveryFailed: (detail) => new CapxulError2("EMAIL_DELIVERY_FAILED", `Failed to send email: ${detail}`),
+  internalError: (reason) => new CapxulError2("INTERNAL_ERROR", `Internal error: ${reason}`)
+};
+
+// ../config/src/safe.ts
+var SAFE_PROXY_FACTORY = "0x4e1dcf7ad4e460cfd30791ccc4f9c8a4f820ec67";
+var SAFE_L2_SINGLETON = "0x29fcb43b46531bca003ddc8fcb67ffe91900c762";
+var SAFE_MODULE_SETUP = "0x2dd68b007b46fbe91b9a7c3eda5a7a1063cb5b47";
+var SAFE_4337_MODULE = "0x75cf11467937ce3f2f357ce24ffc3dbf8fd5c226";
+
+// ../config/src/org-roles.ts
+function roleKeyFromLabel(label) {
+  const bytes = new TextEncoder().encode(label);
+  const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+  return "0x" + hex.padEnd(64, "0");
+}
+roleKeyFromLabel("OWNER");
+roleKeyFromLabel("FINANCE_MANAGER");
+roleKeyFromLabel("TEAM_LEAD");
+
+// src/transport.ts
+function makeHttpTransport(config) {
+  switch (config.mode) {
+    case "build-time-urls":
+      return makeBuildTimeUrlsTransport(config);
+    case "publishable-key":
+      return makePublishableKeyTransport(config);
+    default:
+      return assertNever(config);
+  }
+}
+function createLifecycle(initial) {
+  let state = initial;
+  const listeners = /* @__PURE__ */ new Set();
+  return {
+    getState: () => state,
+    setState: (next) => {
+      if (Object.is(state, next)) return;
+      state = next;
+      for (const listener of listeners) listener();
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    }
+  };
+}
+function makeBuildTimeUrlsTransport(config) {
+  if (!config.authBaseUrl || config.authBaseUrl.trim().length === 0) {
+    throw Errors.invalidInput(
+      "authBaseUrl",
+      "build-time-urls transport requires a non-empty authBaseUrl."
+    );
+  }
+  if (!config.convexUrl || config.convexUrl.trim().length === 0) {
+    throw Errors.invalidInput(
+      "convexUrl",
+      "build-time-urls transport requires a non-empty convexUrl."
+    );
+  }
+  const authBaseUrl = stripTrailingSlash(config.authBaseUrl);
+  const convexUrl = config.convexUrl;
+  const fetchImpl = config.fetchImpl ?? globalThis.fetch;
+  const runtime = { authBaseUrl, convexUrl };
+  const lifecycle = createLifecycle({ status: "ready", runtime });
+  let dataClient = null;
+  return {
+    authBaseUrl,
+    convexUrl,
+    fetch: (path, init) => fetchImpl(resolveUrl(authBaseUrl, path), init),
+    getState: lifecycle.getState,
+    subscribe: lifecycle.subscribe,
+    getDataClient: () => dataClient,
+    markAuthenticated: ({ dataClient: nextDataClient }) => {
+      if (nextDataClient !== void 0) dataClient = nextDataClient;
+      lifecycle.setState({ status: "authenticated", runtime });
+    },
+    clearAuth: () => {
+      dataClient = null;
+      lifecycle.setState({ status: "ready", runtime });
+    }
+  };
+}
+function makePublishableKeyTransport(config) {
+  if (!config.publishableKey || config.publishableKey.trim().length === 0) {
+    throw Errors.invalidInput(
+      "publishableKey",
+      "publishable-key transport requires a non-empty publishableKey."
+    );
+  }
+  const fetchImpl = config.fetchImpl ?? globalThis.fetch;
+  const bootstrapUrl = stripTrailingSlash(
+    config.bootstrapUrl ?? `${CAPXUL_API_BASE_URL}/v1/client/bootstrap`
+  );
+  let authBaseUrl = "";
+  let convexUrl = "";
+  let bootstrapPromise = null;
+  let dataClient = null;
+  const lifecycle = createLifecycle({ status: "idle" });
+  async function ensureBootstrap() {
+    if (bootstrapPromise) return await bootstrapPromise;
+    lifecycle.setState({ status: "bootstrapping" });
+    const attempt = (async () => {
+      const response = await fetchImpl(bootstrapUrl, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ publishableKey: config.publishableKey })
+      });
+      if (!response.ok) {
+        throw Errors.invalidInput(
+          "publishableKey",
+          `${bootstrapUrl} failed with HTTP ${response.status}.`
+        );
+      }
+      const body = await response.json();
+      if (typeof body.authBaseUrl !== "string" || body.authBaseUrl.trim().length === 0) {
+        throw Errors.invalidInput(
+          "authBaseUrl",
+          "/v1/client/bootstrap returned no authBaseUrl."
+        );
+      }
+      if (typeof body.convexUrl !== "string" || body.convexUrl.trim().length === 0) {
+        throw Errors.invalidInput(
+          "convexUrl",
+          "/v1/client/bootstrap returned no convexUrl."
+        );
+      }
+      authBaseUrl = stripTrailingSlash(body.authBaseUrl);
+      convexUrl = body.convexUrl;
+      const runtime = { authBaseUrl, convexUrl };
+      lifecycle.setState({ status: "ready", runtime });
+      return runtime;
+    })();
+    bootstrapPromise = attempt.catch((err) => {
+      bootstrapPromise = null;
+      lifecycle.setState({
+        status: "error",
+        error: err instanceof CapxulError ? err : new CapxulError({
+          code: "UNKNOWN",
+          message: "Bootstrap failed without a typed CapxulError.",
+          cause: err
+        })
+      });
+      throw err;
+    });
+    return await bootstrapPromise;
+  }
+  return {
+    get authBaseUrl() {
+      return authBaseUrl;
+    },
+    get convexUrl() {
+      return convexUrl;
+    },
+    fetch: async (path, init) => {
+      const resolved = await ensureBootstrap();
+      return await fetchImpl(resolveUrl(resolved.authBaseUrl, path), init);
+    },
+    getState: lifecycle.getState,
+    subscribe: lifecycle.subscribe,
+    getDataClient: () => dataClient,
+    markAuthenticated: ({ dataClient: nextDataClient }) => {
+      const current = lifecycle.getState();
+      if (current.status !== "ready" && current.status !== "authenticated") {
+        throw Errors.internalError(
+          `markAuthenticated() called from status="${current.status}". Expected "ready" or "authenticated".`
+        );
+      }
+      if (nextDataClient !== void 0) dataClient = nextDataClient;
+      lifecycle.setState({
+        status: "authenticated",
+        runtime: current.runtime
+      });
+    },
+    clearAuth: () => {
+      const current = lifecycle.getState();
+      dataClient = null;
+      if (current.status === "authenticated") {
+        lifecycle.setState({ status: "ready", runtime: current.runtime });
+      }
+    }
+  };
+}
+function stripTrailingSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+function resolveUrl(authBaseUrl, path) {
+  if (path.startsWith("http://") || path.startsWith("https://")) {
+    return path;
+  }
+  return `${authBaseUrl}${path}`;
+}
+function assertNever(value) {
+  throw Errors.internalError(
+    `Unhandled BrowserCapxulConfig.mode: ${String(value.mode)}.`
+  );
+}
+
+// src/core/auth.ts
+function createAuthClient(config = {}) {
+  let dataClient = config.data ?? null;
+  const sessionStore = config.auth?.sessionStore ?? createMemorySessionStore();
+  const getTransport = createTransportProvider(config);
+  return {
+    sendOtp: async (input, options) => {
+      const transport = getTransport();
+      if (!transport) {
+        return stub("auth.sendOtp");
+      }
+      return await postBetterAuth(
+        transport,
+        "/email-otp/send-verification-otp",
+        { email: input.email, type: "sign-in" },
+        "EMAIL_DELIVERY_FAILED",
+        options?.signal
+      );
+    },
+    verifyOtp: async (input, options) => {
+      const transport = getTransport();
+      if (!transport) {
+        return stub("auth.verifyOtp");
+      }
+      const [signInError, signIn] = await postBetterAuth(
+        transport,
+        "/sign-in/email-otp",
+        { email: input.email, otp: input.otp },
+        "NOT_AUTHENTICATED",
+        options?.signal
+      );
+      if (signInError) return [signInError, null];
+      if (!signIn?.token || !signIn.user?.id) {
+        return [
+          new CapxulError({
+            code: "NOT_AUTHENTICATED",
+            message: "BetterAuth did not return a usable session."
+          }),
+          null
+        ];
+      }
+      const [convexError, convexJwt] = await exchangeConvexToken(
+        transport,
+        config,
+        signIn.token,
+        options?.signal
+      );
+      if (convexError) return [convexError, null];
+      const session = {
+        authUserId: signIn.user.id,
+        email: signIn.user.email,
+        token: signIn.token,
+        convexJwt,
+        expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1e3).toISOString()
+      };
+      sessionStore.set(session);
+      if (config.auth?.createDataClient) {
+        try {
+          dataClient = await config.auth.createDataClient(session);
+          mutableConfig(config).data = dataClient;
+        } catch (cause) {
+          return [
+            new CapxulError({
+              code: "NETWORK_ERROR",
+              message: "Authenticated data client creation failed.",
+              cause
+            }),
+            null
+          ];
+        }
+      }
+      return [null, session];
+    },
+    getSession: async () => [null, sessionStore.get()],
+    signOut: async () => {
+      sessionStore.clear();
+      dataClient = null;
+      mutableConfig(config).data = void 0;
+      return [null, void 0];
+    },
+    serviceTokenMint: async () => stub("auth.serviceTokenMint"),
+    getDataClient: () => dataClient
+  };
+}
+function createMemorySessionStore() {
+  let current = null;
+  return {
+    get: () => current,
+    set: (session) => {
+      current = session;
+    },
+    clear: () => {
+      current = null;
+    }
+  };
+}
+function createTransportProvider(config) {
+  let cached = config._transport ?? null;
+  return () => {
+    if (cached) return cached;
+    const baseUrl = config.auth?.baseUrl;
+    if (baseUrl) {
+      cached = makeHttpTransport({
+        mode: "build-time-urls",
+        authBaseUrl: betterAuthRoot(baseUrl),
+        convexUrl: baseUrl,
+        fetchImpl: config.fetch
+      });
+      return cached;
+    }
+    if (!config.publishableKey) return null;
+    cached = makeHttpTransport({
+      mode: "publishable-key",
+      publishableKey: config.publishableKey,
+      fetchImpl: config.fetch
+    });
+    return cached;
+  };
+}
+function betterAuthRoot(rawBaseUrl) {
+  const trimmed = rawBaseUrl.replace(/\/+$/, "");
+  return trimmed.endsWith("/api/auth") ? trimmed : `${trimmed}/api/auth`;
+}
+async function postBetterAuth(transport, path, body, code, signal) {
+  try {
+    const response = await transport.fetch(path, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal
+    });
+    if (!response.ok) {
+      return [
+        new CapxulError({
+          code,
+          message: `BetterAuth ${path} failed with HTTP ${response.status}.`
+        }),
+        null
+      ];
+    }
+    const text = await response.text();
+    return [null, text ? JSON.parse(text) : void 0];
+  } catch (cause) {
+    return [
+      new CapxulError({
+        code: "NETWORK_ERROR",
+        message: `BetterAuth ${path} network failure.`,
+        cause
+      }),
+      null
+    ];
+  }
+}
+async function exchangeConvexToken(transport, config, token, signal) {
+  const path = config.auth?.convexTokenUrl ?? "/convex/token";
+  try {
+    const response = await transport.fetch(path, {
+      headers: { authorization: `Bearer ${token}` },
+      signal
+    });
+    if (!response.ok) {
+      return [
+        new CapxulError({
+          code: "NOT_AUTHENTICATED",
+          message: `Convex token exchange failed with HTTP ${response.status}.`
+        }),
+        null
+      ];
+    }
+    const body = await response.json();
+    if (typeof body.token !== "string") {
+      return [
+        new CapxulError({
+          code: "NOT_AUTHENTICATED",
+          message: "Convex token exchange returned no token."
+        }),
+        null
+      ];
+    }
+    return [null, body.token];
+  } catch (cause) {
+    return [
+      new CapxulError({
+        code: "NETWORK_ERROR",
+        message: "Convex token exchange network failure.",
+        cause
+      }),
+      null
+    ];
+  }
+}
+function mutableConfig(config) {
+  return config;
+}
+
+// src/core/documents.ts
+function createDocumentsClient() {
+  return {
+    create: async () => stub("documents.create"),
+    retrieve: async () => stub("documents.retrieve"),
+    list: async () => stub("documents.list"),
+    cancel: async () => stub("documents.cancel")
+  };
+}
+function createOrgDocumentsClient() {
+  return {
+    create: async () => stub("organizations.documents.create"),
+    retrieve: async () => stub("organizations.documents.retrieve"),
+    list: async () => stub("organizations.documents.list"),
+    cancel: async () => stub("organizations.documents.cancel")
+  };
+}
+
+// src/core/external-accounts.ts
+function createExternalAccountsClient() {
+  return {
+    retrieve: async () => stub("externalAccounts.retrieve"),
+    remove: async () => stub("externalAccounts.remove")
+  };
+}
+
+// src/core/me.ts
+function createMeClient(config = {}) {
+  return {
+    get: async () => {
+      if (!config.data) {
+        return stub("me.get");
+      }
+      try {
+        const account = await config.data.query(
+          api.openfort.queries.getMyAccount,
+          {}
+        );
+        return [null, account];
+      } catch (cause) {
+        return [fromConvexError(cause), null];
+      }
+    },
+    update: async () => stub("me.update")
+  };
+}
+
+// src/core/operations.ts
+function createOperationsClient(config = {}) {
+  const retrieve = async (operationId) => {
+    if (!config.data) {
+      return stub("operations.retrieve");
+    }
+    try {
+      const operation = await config.data.query(api.operations.queries.retrieve, {
+        operationId
+      });
+      if (!operation) {
+        return [new CapxulError({
+          code: "NOT_FOUND",
+          message: `operation ${operationId} not found`
+        }), null];
+      }
+      return [null, operation];
+    } catch (cause) {
+      return [fromConvexError(cause), null];
+    }
+  };
+  return {
+    retrieve,
+    wait: async (operationId, input = {}) => {
+      if (!config.data) {
+        return stub("operations.wait");
+      }
+      const until = new Set(
+        input.until ?? ["succeeded", "failed", "canceled", "indexed"]
+      );
+      const timeoutMs = (input.timeoutSeconds ?? 60) * 1e3;
+      const pollIntervalMs = input.pollIntervalMs ?? 1e3;
+      const deadline = Date.now() + timeoutMs;
+      while (Date.now() <= deadline) {
+        const [error, operation] = await retrieve(operationId);
+        if (error) {
+          return [error, null];
+        }
+        if (until.has(operation.status)) {
+          return [null, operation];
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+      }
+      return [new CapxulError({
+        code: "OPERATION_TIMEOUT",
+        message: `operation ${operationId} did not reach a terminal state before the timeout`,
+        details: {
+          operationId,
+          timeoutSeconds: input.timeoutSeconds ?? 60,
+          pollIntervalMs
+        }
+      }), null];
+    }
+  };
+}
+function toTokenUnits(value, decimals = 6) {
+  return parseUnits(value, decimals);
+}
+
+// src/internal/payment-token.ts
+function resolvePaymentTokenAddress(currency) {
+  const normalized = currency.trim().toUpperCase();
+  if (normalized === "USD" || normalized === "USDC") {
+    return TEST_USDC_ADDRESS.toLowerCase();
+  }
+  throw new CapxulError({
+    code: "NETWORK_ERROR",
+    message: `Currency ${currency} is not configured for on-chain payment submission.`,
+    details: { currency: normalized }
+  });
+}
+async function buildSafeAccount(signer, chain) {
+  try {
+    const publicClient = createPublicClient({
+      chain: baseSepolia,
+      transport: http(chain.rpcUrl)
+    });
+    return await toSafeSmartAccount({
+      client: publicClient,
+      entryPoint: { address: entryPoint07Address, version: "0.7" },
+      version: "1.4.1",
+      owners: [signer],
+      saltNonce: computeSaltNonce(signer.address),
+      safeSingletonAddress: SAFE_L2_SINGLETON,
+      safeProxyFactoryAddress: SAFE_PROXY_FACTORY,
+      safeModuleSetupAddress: SAFE_MODULE_SETUP,
+      safe4337ModuleAddress: SAFE_4337_MODULE,
+      safeModules: [],
+      setupTransactions: []
+    });
+  } catch (cause) {
+    throw new CapxulError({
+      code: "NETWORK_ERROR",
+      message: cause instanceof Error ? cause.message : String(cause),
+      cause,
+      details: { chainId: chain.chainId }
+    });
+  }
+}
+function computeSaltNonce(ownerAddress) {
+  return BigInt(`0x${ownerAddress.toLowerCase().slice(2).padEnd(64, "0")}`);
+}
+function createCapxulBundler(config) {
+  const paymaster = createPaymasterClient({
+    transport: http(config.rpcUrl)
+  });
+  return createBundlerClient({
+    chain: baseSepolia,
+    transport: http(config.rpcUrl),
+    paymaster,
+    paymasterContext: { policyId: config.gasPolicyId }
+  });
+}
+var CAPXUL_PAYMENTS_SEND_ABI = [
+  {
+    name: "send",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "token", type: "address" },
+      { name: "recipient", type: "address" },
+      { name: "amount", type: "uint256" },
+      { name: "documentHash", type: "bytes32" },
+      { name: "paymentType", type: "uint8" }
+    ],
+    outputs: []
+  }
+];
+var ERC20_APPROVE_ABI = [
+  {
+    name: "approve",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "spender", type: "address" },
+      { name: "amount", type: "uint256" }
+    ],
+    outputs: [{ name: "", type: "bool" }]
+  }
+];
+function encodeOwnerTransferCalls(params) {
+  const documentHash = params.documentHash ?? "0x" + "0".repeat(64);
+  const paymentType = params.paymentType ?? 0;
+  const approve = encodeFunctionData({
+    abi: ERC20_APPROVE_ABI,
+    functionName: "approve",
+    args: [CAPXUL_PAYMENTS_ADDRESS, params.amount]
+  });
+  const send = encodeFunctionData({
+    abi: CAPXUL_PAYMENTS_SEND_ABI,
+    functionName: "send",
+    args: [
+      params.tokenAddress,
+      params.recipientAddress,
+      params.amount,
+      documentHash,
+      paymentType
+    ]
+  });
+  return [
+    {
+      to: params.tokenAddress.toLowerCase(),
+      data: approve,
+      value: 0n
+    },
+    {
+      to: CAPXUL_PAYMENTS_ADDRESS,
+      data: send,
+      value: 0n
+    }
+  ];
+}
+
+// src/internal/safe/operations.ts
+var USER_OP_RECEIPT_TIMEOUT_MS = 12e4;
+async function transferAsOwner(config, params) {
+  try {
+    const safeAccount = await buildSafeAccount(config.signer, config.signing);
+    const bundler = createCapxulBundler(config.signing);
+    const calls = encodeOwnerTransferCalls(params);
+    const userOpHash = await bundler.sendUserOperation({
+      account: safeAccount,
+      calls
+    });
+    const receipt = await bundler.waitForUserOperationReceipt({
+      hash: userOpHash,
+      timeout: USER_OP_RECEIPT_TIMEOUT_MS
+    });
+    return {
+      txHash: receipt.receipt.transactionHash,
+      userOpHash,
+      blockNumber: Number(receipt.receipt.blockNumber),
+      success: receipt.success,
+      logs: receipt.receipt.logs
+    };
+  } catch (cause) {
+    throw new CapxulError({
+      code: "NETWORK_ERROR",
+      message: cause instanceof Error ? cause.message : String(cause),
+      cause
+    });
+  }
+}
+
+// src/core/payments.ts
+function createPaymentsClient(config = {}) {
+  return {
+    create: async (input) => {
+      if (!config.data || !config.signer || !config.signing) {
+        return stub("payments.create");
+      }
+      let created = null;
+      let submitted = null;
+      try {
+        created = await config.data.mutation(api.payments.mutations.create, {
+          to: input.to,
+          amount: input.amount,
+          reference: input.reference,
+          idempotencyKey: input.idempotencyKey,
+          source: input.source
+        });
+        if (!created) {
+          return [new CapxulError({
+            code: "NETWORK_ERROR",
+            message: "payments.create returned no payment resource"
+          }), null];
+        }
+        if (created.status !== "processing" || created.operation.status !== "processing") {
+          return [null, created];
+        }
+        const currentSigner = await config.data.query(api.safe.queries.getMySignerAddress, {});
+        if (!currentSigner?.address) {
+          throw new CapxulError({
+            code: "PERMISSION_DENIED",
+            message: "No signer is registered for the authenticated account.",
+            details: { paymentId: created.id }
+          });
+        }
+        if (getAddress(currentSigner.address) !== getAddress(config.signer.address)) {
+          throw new CapxulError({
+            code: "PERMISSION_DENIED",
+            message: "Configured signer does not match the authenticated account signer.",
+            details: {
+              paymentId: created.id,
+              expectedSignerAddress: currentSigner.address,
+              actualSignerAddress: config.signer.address
+            }
+          });
+        }
+        const submission = await config.data.query(api.payments.queries.prepareSubmission, {
+          paymentId: created.id
+        });
+        if (!submission?.recipientAddress) {
+          throw new CapxulError({
+            code: "NETWORK_ERROR",
+            message: "payments.prepareSubmission returned no recipient address.",
+            details: { paymentId: created.id }
+          });
+        }
+        const transfer = await transferAsOwner(
+          {
+            signer: config.signer,
+            signing: config.signing
+          },
+          {
+            tokenAddress: resolvePaymentTokenAddress(submission.amount.currency),
+            recipientAddress: submission.recipientAddress,
+            amount: toTokenUnits(submission.amount.value, 6)
+          }
+        );
+        if (!transfer.success) {
+          throw new CapxulError({
+            code: "NETWORK_ERROR",
+            message: "Bundler submission did not succeed.",
+            details: {
+              paymentId: created.id,
+              txHash: transfer.txHash,
+              userOpHash: transfer.userOpHash
+            }
+          });
+        }
+        submitted = {
+          txHash: transfer.txHash,
+          userOpHash: transfer.userOpHash
+        };
+        await config.data.mutation(api.payments.mutations.recordSubmitted, {
+          paymentId: created.id,
+          txHash: transfer.txHash,
+          userOpHash: transfer.userOpHash,
+          source: "sdk"
+        });
+        return [null, created];
+      } catch (cause) {
+        const error = mapCreateError(fromConvexError(cause));
+        if (created?.id && created.status === "processing" && !submitted) {
+          await bestEffortMarkFailed({ data: config.data }, created.id, error);
+        }
+        if (submitted && created?.id) {
+          return [new CapxulError({
+            code: "NETWORK_ERROR",
+            message: "Payment was submitted on-chain, but backend submission tracking failed.",
+            cause,
+            details: {
+              paymentId: created.id,
+              txHash: submitted.txHash,
+              userOpHash: submitted.userOpHash
+            }
+          }), null];
+        }
+        return [error, null];
+      }
+    },
+    retrieve: async (paymentId) => {
+      if (!config.data) {
+        return stub("payments.retrieve");
+      }
+      try {
+        const payment = await config.data.query(api.payments.queries.retrieve, {
+          paymentId
+        });
+        if (!payment) {
+          return [new CapxulError({
+            code: "NOT_FOUND",
+            message: `payment ${paymentId} not found`
+          }), null];
+        }
+        return [null, payment];
+      } catch (cause) {
+        return [fromConvexError(cause), null];
+      }
+    },
+    list: async () => stub("payments.list")
+  };
+}
+function createOrgPaymentsClient() {
+  return {
+    create: async () => stub(
+      "organizations.payments.create"
+    ),
+    retrieve: async () => stub("organizations.payments.retrieve"),
+    list: async () => stub("organizations.payments.list")
+  };
+}
+async function bestEffortMarkFailed(config, paymentId, error) {
+  try {
+    await config.data.mutation(api.payments.mutations.markFailed, {
+      paymentId,
+      errorCode: error.code,
+      errorMessage: error.message,
+      source: "sdk"
+    });
+  } catch {
+  }
+}
+function mapCreateError(error) {
+  switch (error.code) {
+    case "NOT_AUTHENTICATED":
+    case "PERMISSION_DENIED":
+    case "INVALID_INPUT":
+    case "INVALID_RECIPIENT":
+    case "INSUFFICIENT_BALANCE":
+    case "IDEMPOTENCY_CONFLICT":
+    case "RATE_LIMITED":
+    case "NETWORK_ERROR":
+      return error;
+    default:
+      return new CapxulError({
+        code: "NETWORK_ERROR",
+        message: error.message,
+        cause: error,
+        details: error.details,
+        operationId: error.operationId,
+        correlationId: error.correlationId,
+        retryable: error.retryable
+      });
+  }
+}
+
+// src/core/transfers.ts
+function createTransfersClient() {
+  return {
+    create: async () => stub("transfers.create"),
+    retrieve: async () => stub("transfers.retrieve"),
+    list: async () => stub("transfers.list"),
+    confirm: async () => stub("transfers.confirm"),
+    cancel: async () => stub("transfers.cancel")
+  };
+}
+function createOrgTransfersClient() {
+  return {
+    create: async () => stub(
+      "organizations.transfers.create"
+    ),
+    retrieve: async () => stub("organizations.transfers.retrieve"),
+    list: async () => stub("organizations.transfers.list"),
+    confirm: async () => stub("organizations.transfers.confirm"),
+    cancel: async () => stub("organizations.transfers.cancel")
+  };
+}
+var EVM_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
+function createWithdrawalsClient(config = {}) {
+  return {
+    create: async (input) => {
+      if (!config.data) {
+        return stub("withdrawals.create");
+      }
+      let created = null;
+      let submitted = null;
+      try {
+        created = await config.data.mutation(
+          api.withdrawals.mutations.create,
+          {
+            amount: input.amount,
+            destination: {
+              externalAccountId: input.destination.externalAccountId,
+              kind: input.destination.kind
+            },
+            source: input.source,
+            reference: input.reference,
+            idempotencyKey: input.idempotencyKey
+          }
+        );
+        if (!created) {
+          return [
+            new CapxulError({
+              code: "NETWORK_ERROR",
+              message: "withdrawals.create returned no withdrawal resource"
+            }),
+            null
+          ];
+        }
+        if (created.status !== "processing" || created.operation.status !== "processing") {
+          return [null, created];
+        }
+        if (input.destination.kind !== "evm") {
+          return [null, created];
+        }
+        if (!config.signer || !config.signing) {
+          return [null, created];
+        }
+        if (!EVM_ADDRESS_RE.test(input.destination.externalAccountId)) {
+          throw new CapxulError({
+            code: "INVALID_INPUT",
+            message: "destination.externalAccountId must be a 0x-prefixed EVM address while external_accounts resolution is pending (slice 1).",
+            details: { field: "destination.externalAccountId" }
+          });
+        }
+        const currentSigner = await config.data.query(
+          api.safe.queries.getMySignerAddress,
+          {}
+        );
+        if (!currentSigner?.address) {
+          throw new CapxulError({
+            code: "PERMISSION_DENIED",
+            message: "No signer is registered for the authenticated account.",
+            details: { withdrawalId: created.id }
+          });
+        }
+        if (getAddress(currentSigner.address) !== getAddress(config.signer.address)) {
+          throw new CapxulError({
+            code: "PERMISSION_DENIED",
+            message: "Configured signer does not match the authenticated account signer.",
+            details: {
+              withdrawalId: created.id,
+              expectedSignerAddress: currentSigner.address,
+              actualSignerAddress: config.signer.address
+            }
+          });
+        }
+        const submission = await config.data.query(
+          api.withdrawals.queries.prepareSubmission,
+          { withdrawalId: created.id }
+        );
+        if (!submission?.externalAccountId) {
+          throw new CapxulError({
+            code: "NETWORK_ERROR",
+            message: "withdrawals.prepareSubmission returned no destination.",
+            details: { withdrawalId: created.id }
+          });
+        }
+        const transfer = await transferAsOwner(
+          {
+            signer: config.signer,
+            signing: config.signing
+          },
+          {
+            tokenAddress: resolvePaymentTokenAddress(submission.amount.currency),
+            recipientAddress: submission.externalAccountId,
+            amount: toTokenUnits(submission.amount.value, 6)
+          }
+        );
+        if (!transfer.success) {
+          throw new CapxulError({
+            code: "NETWORK_ERROR",
+            message: "Bundler submission did not succeed.",
+            details: {
+              withdrawalId: created.id,
+              txHash: transfer.txHash,
+              userOpHash: transfer.userOpHash
+            }
+          });
+        }
+        submitted = {
+          txHash: transfer.txHash,
+          userOpHash: transfer.userOpHash
+        };
+        await config.data.mutation(
+          api.withdrawals.mutations.recordSubmitted,
+          {
+            withdrawalId: created.id,
+            txHash: transfer.txHash,
+            userOpHash: transfer.userOpHash
+          }
+        );
+        return [null, created];
+      } catch (cause) {
+        const error = mapCreateError2(fromConvexError(cause));
+        if (created?.id && created.status === "processing" && !submitted) {
+          await bestEffortMarkFailed2({ data: config.data }, created.id, error);
+        }
+        if (submitted && created?.id) {
+          return [
+            new CapxulError({
+              code: "NETWORK_ERROR",
+              message: "Withdrawal was submitted on-chain, but backend submission tracking failed.",
+              cause,
+              details: {
+                withdrawalId: created.id,
+                txHash: submitted.txHash,
+                userOpHash: submitted.userOpHash
+              }
+            }),
+            null
+          ];
+        }
+        return [error, null];
+      }
+    },
+    retrieve: async (withdrawalId) => {
+      if (!config.data) {
+        return stub("withdrawals.retrieve");
+      }
+      try {
+        const withdrawal = await config.data.query(
+          api.withdrawals.queries.retrieve,
+          { withdrawalId }
+        );
+        if (!withdrawal) {
+          return [
+            new CapxulError({
+              code: "NOT_FOUND",
+              message: `withdrawal ${withdrawalId} not found`
+            }),
+            null
+          ];
+        }
+        return [null, withdrawal];
+      } catch (cause) {
+        return [
+          fromConvexError(cause),
+          null
+        ];
+      }
+    },
+    list: async (input) => {
+      if (!config.data) {
+        return stub("withdrawals.list");
+      }
+      try {
+        const result = await config.data.query(
+          api.withdrawals.queries.list,
+          {
+            limit: input?.limit,
+            cursor: input?.cursor
+          }
+        );
+        return [null, result];
+      } catch (cause) {
+        return [
+          fromConvexError(cause),
+          null
+        ];
+      }
+    }
+  };
+}
+function createOrgWithdrawalsClient(config = {}) {
+  return {
+    // Slice 1 ships personal-scope only end-to-end; org-scope create
+    // remains stubbed pending org-scoped backend mutation. List + retrieve
+    // are wired through the org-aware query.
+    create: async () => stub(
+      "organizations.withdrawals.create"
+    ),
+    retrieve: async (input) => {
+      if (!config.data) {
+        return stub(
+          "organizations.withdrawals.retrieve"
+        );
+      }
+      try {
+        const withdrawal = await config.data.query(
+          api.withdrawals.queries.retrieve,
+          { withdrawalId: input.withdrawalId }
+        );
+        if (!withdrawal) {
+          return [
+            new CapxulError({
+              code: "NOT_FOUND",
+              message: `withdrawal ${input.withdrawalId} not found`
+            }),
+            null
+          ];
+        }
+        const ownerCheck = withdrawal.owner;
+        if (ownerCheck?.type !== "organization" || ownerCheck.id !== input.organizationId) {
+          return [
+            new CapxulError({
+              code: "NOT_FOUND",
+              message: `withdrawal ${input.withdrawalId} does not belong to organization ${input.organizationId}`
+            }),
+            null
+          ];
+        }
+        return [null, withdrawal];
+      } catch (cause) {
+        return [
+          fromConvexError(cause),
+          null
+        ];
+      }
+    },
+    list: async (input) => {
+      if (!config.data) {
+        return stub(
+          "organizations.withdrawals.list"
+        );
+      }
+      try {
+        const result = await config.data.query(
+          api.withdrawals.queries.listOrg,
+          {
+            organizationId: input.organizationId,
+            limit: input.limit,
+            cursor: input.cursor
+          }
+        );
+        return [null, result];
+      } catch (cause) {
+        return [
+          fromConvexError(cause),
+          null
+        ];
+      }
+    }
+  };
+}
+async function bestEffortMarkFailed2(config, withdrawalId, error) {
+  try {
+    await config.data.mutation(api.withdrawals.mutations.markFailed, {
+      withdrawalId,
+      errorCode: error.code,
+      errorMessage: error.message
+    });
+  } catch {
+  }
+}
+function mapCreateError2(error) {
+  switch (error.code) {
+    case "NOT_AUTHENTICATED":
+    case "PERMISSION_DENIED":
+    case "INVALID_INPUT":
+    case "INSUFFICIENT_BALANCE":
+    case "IDEMPOTENCY_CONFLICT":
+    case "KYC_REQUIRED":
+    case "POLICY_DENIED":
+    case "RATE_LIMITED":
+    case "NETWORK_ERROR":
+      return error;
+    default:
+      return new CapxulError({
+        code: "NETWORK_ERROR",
+        message: error.message,
+        cause: error,
+        details: error.details,
+        operationId: error.operationId,
+        correlationId: error.correlationId,
+        retryable: error.retryable
+      });
+  }
+}
+
+// src/core/webhook-endpoints.ts
+function createWebhookEndpointsClient() {
+  return {
+    create: async () => stub(
+      "webhookEndpoints.create"
+    ),
+    retrieve: async () => stub("webhookEndpoints.retrieve"),
+    list: async () => stub("webhookEndpoints.list"),
+    remove: async () => stub("webhookEndpoints.remove")
+  };
+}
+
+// src/core/webhook-events.ts
+function createWebhookEventsClient() {
+  return {
+    retrieve: async () => stub("webhookEvents.retrieve"),
+    list: async () => stub("webhookEvents.list")
+  };
+}
+
+// src/core/organizations.ts
+function createOrganizationsClient(config = {}) {
+  return {
+    create: async () => stub("organizations.create"),
+    retrieve: async () => stub("organizations.retrieve"),
+    list: async () => stub("organizations.list"),
+    update: async () => stub("organizations.update"),
+    safes: {
+      retrieve: async (input) => {
+        if (!config.data) {
+          return stub("organizations.safes.retrieve");
+        }
+        try {
+          const safe = await config.data.query(
+            api.safe.queries.retrieveOrganizationSafe,
+            input
+          );
+          if (!safe) {
+            return [
+              new CapxulError({
+                code: "NOT_FOUND",
+                message: `safe ${input.safeId} not found`
+              }),
+              null
+            ];
+          }
+          return [null, safe];
+        } catch (cause) {
+          return [
+            fromConvexError(cause),
+            null
+          ];
+        }
+      }
+    },
+    treasury: {
+      retrieve: async () => stub("organizations.treasury.retrieve")
+    },
+    members: {
+      list: async () => stub("organizations.members.list"),
+      retrieve: async () => stub("organizations.members.retrieve"),
+      invite: async () => stub("organizations.members.invite"),
+      updateRole: async () => stub("organizations.members.updateRole"),
+      remove: async () => stub("organizations.members.remove")
+    },
+    apiKeys: createApiKeysClient(),
+    kybProfile: {
+      start: async () => stub("organizations.kybProfile.start"),
+      retrieve: async () => stub("organizations.kybProfile.retrieve")
+    },
+    subAccounts: {
+      create: async () => stub("organizations.subAccounts.create"),
+      list: async () => stub("organizations.subAccounts.list"),
+      retrieve: async () => stub("organizations.subAccounts.retrieve"),
+      remove: async () => stub("organizations.subAccounts.remove")
+    },
+    externalAccounts: {
+      create: async () => stub(
+        "organizations.externalAccounts.create"
+      ),
+      list: async () => stub(
+        "organizations.externalAccounts.list"
+      ),
+      retrieve: async () => stub(
+        "organizations.externalAccounts.retrieve"
+      ),
+      remove: async () => stub("organizations.externalAccounts.remove")
+    },
+    balanceLedger: {
+      list: async () => stub(
+        "organizations.balanceLedger.list"
+      ),
+      retrieve: async () => stub(
+        "organizations.balanceLedger.retrieve"
+      )
+    },
+    payments: createOrgPaymentsClient(),
+    transfers: createOrgTransfersClient(),
+    withdrawals: createOrgWithdrawalsClient(config),
+    documents: createOrgDocumentsClient(),
+    webhookEndpoints: createWebhookEndpointsClient(),
+    webhookEvents: createWebhookEventsClient()
+  };
+}
+
+// src/core/sub-accounts.ts
+function createSubAccountsClient() {
+  return {
+    retrieve: async () => stub("subAccounts.retrieve"),
+    remove: async () => stub("subAccounts.remove")
+  };
+}
+
+// src/core/virtual-accounts.ts
+function createVirtualAccountsClient() {
+  return {
+    create: async () => stub("virtualAccounts.create"),
+    retrieve: async () => stub("virtualAccounts.retrieve"),
+    list: async () => stub("virtualAccounts.list"),
+    remove: async () => stub("virtualAccounts.remove")
+  };
+}
+
+// src/core/virtual-cards.ts
+function createVirtualCardsClient() {
+  return {
+    create: async () => stub("virtualCards.create"),
+    retrieve: async () => stub("virtualCards.retrieve"),
+    list: async () => stub("virtualCards.list"),
+    freeze: async () => stub("virtualCards.freeze"),
+    unfreeze: async () => stub("virtualCards.unfreeze"),
+    cancel: async () => stub("virtualCards.cancel")
+  };
+}
+
+// ../observability/src/debug-log.ts
+function isDevelopmentBuild() {
+  if (typeof process === "undefined") {
+    return false;
+  }
+  return process.env?.NODE_ENV === "development" || process.env?.NODE_ENV === "test";
+}
+function debugLog(line) {
+  if (!isDevelopmentBuild()) return;
+  if (typeof globalThis !== "undefined" && "window" in globalThis && typeof console?.info === "function") {
+    console.info(line);
+    return;
+  }
+  if (typeof process !== "undefined" && typeof process.stderr?.write === "function") {
+    process.stderr.write(`${line}
+`);
+  }
+}
+function formatDebugValue(value) {
+  if (value === void 0 || value === "") return "";
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+function track(...args) {
+  const [name, props] = args;
+  debugLog(`[TRACK] ${name} ${formatDebugValue(props ?? "")}`);
+}
+function formatDebugValue2(value) {
+  if (value === void 0 || value === "") return "";
+  if (typeof value === "string") return value;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+function identify(userId, traits) {
+  debugLog(`[IDENTIFY] ${userId} ${formatDebugValue2(traits ?? "")}`);
+}
+function createAuthFlowMachine(client) {
+  return setup({
+    types: {},
+    actors: {
+      // XState v5's `fromPromise` injects an `AbortSignal` that aborts
+      // when the actor is stopped (parent transition fires, machine is
+      // disposed, etc.). Plumbing it through `client.auth.sendOtp` /
+      // `client.auth.verifyOtp` makes the in-flight HTTP request
+      // cancellable: stale responses can't race a state machine
+      // that's already moved on. See PR #406 S5.
+      sendOtp: fromPromise(async ({ input, signal }) => {
+        const [error] = await client.auth.sendOtp(
+          { email: input.email },
+          { signal }
+        );
+        if (error) throw error;
+      }),
+      verifyOtp: fromPromise(
+        async ({ input, signal }) => {
+          const [error, session] = await client.auth.verifyOtp(
+            {
+              email: input.email,
+              otp: input.code
+            },
+            { signal }
+          );
+          if (error) throw error;
+          return session;
+        }
+      ),
+      signOut: fromPromise(async () => {
+        const [error] = await client.auth.signOut();
+        if (error) throw error;
+      })
+    },
+    actions: {
+      trackOtpRequested: ({ context }) => {
+        if (!context.email) return;
+        track("auth_otp_requested", {
+          email_domain: emailDomain(context.email)
+        });
+      },
+      trackOtpFailed: ({ event }) => {
+        const error = errorFromEvent(event);
+        track("auth_failed", {
+          auth_type: "email_otp",
+          reason: error.code
+        });
+      },
+      trackTimeoutFailed: () => {
+        track("auth_failed", {
+          auth_type: "email_otp",
+          reason: "timeout"
+        });
+      },
+      trackVerified: () => {
+        track("auth_verified", { auth_type: "email_otp" });
+      },
+      identifyAndTrack: ({ context }) => {
+        if (!context.session) return;
+        identify(context.session.authUserId, {
+          email_domain: emailDomain(context.session.email)
+        });
+        track("auth_identified", {
+          email_domain: emailDomain(context.session.email)
+        });
+      },
+      trackSignedOut: () => {
+        track("auth_signed_out");
+      }
+    }
+  }).createMachine({
+    id: "auth",
+    initial: "idle",
+    context: { email: null, session: null, error: null },
+    states: {
+      idle: {
+        on: {
+          REQUEST_OTP: {
+            target: "sending_otp",
+            actions: assign({
+              email: ({ event }) => event.email,
+              error: () => null
+            })
+          }
+        }
+      },
+      sending_otp: {
+        invoke: {
+          src: "sendOtp",
+          input: ({ context }) => ({ email: requireEmail(context) }),
+          onDone: {
+            target: "otp_requested",
+            actions: ["trackOtpRequested"]
+          },
+          onError: {
+            target: "error",
+            actions: [
+              assign({ error: ({ event }) => errorFromEvent(event) }),
+              "trackOtpFailed"
+            ]
+          }
+        },
+        after: {
+          [FLOW_INVOKE_TIMEOUT_MS]: {
+            target: "error",
+            actions: [
+              assign({
+                error: () => timeoutError("sending_otp")
+              }),
+              "trackTimeoutFailed"
+            ]
+          }
+        }
+      },
+      otp_requested: {
+        on: {
+          VERIFY: { target: "verifying" },
+          RESET: {
+            target: "idle",
+            actions: assign({ email: () => null, error: () => null })
+          }
+        }
+      },
+      verifying: {
+        invoke: {
+          src: "verifyOtp",
+          input: ({ context, event }) => ({
+            email: requireEmail(context),
+            code: requireCodeFromEvent(event)
+          }),
+          onDone: {
+            target: "authenticated",
+            actions: [
+              // Scrub the duplicate `context.email` (input value
+              // captured during sendOtp) since the verified
+              // `session.email` is now the canonical source
+              // post-authentication. The session's email is
+              // intentionally retained — it's the auth result, not
+              // lingering input. See PR #406 S2.
+              assign({
+                session: ({ event }) => event.output,
+                email: () => null
+              }),
+              "trackVerified",
+              "identifyAndTrack"
+            ]
+          },
+          onError: {
+            target: "error",
+            actions: [
+              assign({ error: ({ event }) => errorFromEvent(event) }),
+              "trackOtpFailed"
+            ]
+          }
+        },
+        after: {
+          [FLOW_INVOKE_TIMEOUT_MS]: {
+            target: "error",
+            actions: [
+              assign({
+                error: () => timeoutError("verifying")
+              }),
+              "trackTimeoutFailed"
+            ]
+          }
+        }
+      },
+      authenticated: {
+        on: {
+          SIGN_OUT: { target: "signing_out" }
+        }
+      },
+      signing_out: {
+        invoke: {
+          src: "signOut",
+          onDone: {
+            target: "idle",
+            actions: [
+              assign({
+                session: () => null,
+                email: () => null,
+                error: () => null
+              }),
+              "trackSignedOut"
+            ]
+          },
+          onError: {
+            target: "error",
+            actions: assign({ error: ({ event }) => errorFromEvent(event) })
+          }
+        }
+      },
+      error: {
+        on: {
+          RESET: {
+            target: "idle",
+            actions: assign({ error: () => null })
+          }
+        }
+      }
+    }
+  });
+}
+function requireEmail(context) {
+  if (!context.email) {
+    throw Errors.invalidInput(
+      "email",
+      "Auth flow advanced without an email captured in context."
+    );
+  }
+  return context.email;
+}
+function requireCodeFromEvent(event) {
+  if (event.type !== "VERIFY") {
+    throw Errors.invalidInput(
+      "code",
+      `Auth flow's verifying state requires a VERIFY event, got ${event.type}.`
+    );
+  }
+  return event.code;
+}
+function errorFromEvent(event) {
+  const cause = typeof event === "object" && event !== null && "error" in event ? event.error : event;
+  if (cause instanceof CapxulError) {
+    if (!EMAIL_MATCH_PATTERN.test(cause.message)) return cause;
+    return new CapxulError({
+      code: cause.code,
+      message: redactEmail(cause.message),
+      cause,
+      details: cause.details,
+      operationId: cause.operationId,
+      correlationId: cause.correlationId,
+      retryable: cause.retryable
+    });
+  }
+  if (cause instanceof CapxulError2) {
+    if (!EMAIL_MATCH_PATTERN.test(cause.message)) return cause;
+    return new CapxulError2(cause.code, redactEmail(cause.message), {
+      cause,
+      details: cause.details,
+      correlationId: cause.correlationId,
+      layer: cause.layer
+    });
+  }
+  return Errors.providerError("auth", "flow", redactCauseEmail(cause));
+}
+var EMAIL_MATCH_PATTERN = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/;
+var EMAIL_REDACT_PATTERN = /[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+function redactEmail(message) {
+  return message.replace(EMAIL_REDACT_PATTERN, "<redacted>");
+}
+function redactCauseEmail(cause) {
+  if (cause instanceof Error) {
+    if (!EMAIL_MATCH_PATTERN.test(cause.message)) return cause;
+    const redacted = new Error(redactEmail(cause.message));
+    redacted.cause = cause;
+    return redacted;
+  }
+  if (typeof cause === "string") {
+    return redactEmail(cause);
+  }
+  return cause;
+}
+function timeoutError(state) {
+  return Errors.providerError(
+    "auth",
+    "flow",
+    new Error(`timeout: ${state} exceeded ${FLOW_INVOKE_TIMEOUT_MS}ms`)
+  );
+}
+function emailDomain(email) {
+  const domain = email.split("@")[1]?.trim().toLowerCase();
+  return domain || "unknown";
+}
+
+// ../platform-kernel/src/ids.ts
+function makePrefixedIdConstructor(prefix, fieldName) {
+  const re = new RegExp(`^${prefix}_[A-Za-z0-9_\\-]+$`);
+  return (raw) => {
+    if (typeof raw !== "string" || !re.test(raw)) {
+      throw new Error(
+        `Invalid ${fieldName}: expected string matching ^${prefix}_[A-Za-z0-9_\\-]+$, got ${String(raw)}`
+      );
+    }
+    return raw;
+  };
+}
+var toOperationId = makePrefixedIdConstructor(
+  "op",
+  "operationId"
+);
+function createProvisioningMachine(client) {
+  return setup({
+    types: {},
+    actors: {
+      provisionPersonal: fromPromise(async ({ input }) => {
+        const [error, account] = await client.accounts.provisionPersonal(
+          input.input
+        );
+        if (error) throw error;
+        return account;
+      })
+    },
+    guards: {
+      hasInput: ({ context }) => context.input !== null
+    },
+    actions: {
+      trackWalletCreated: ({ context }) => {
+        const provider = context.input?.signerProvider;
+        if (!provider) return;
+        track("provisioning_wallet_created", {
+          eoa_address: provider.signerAddress
+        });
+      },
+      trackSafeCreated: ({ context }) => {
+        const provider = context.input?.signerProvider;
+        if (!provider) return;
+        track("provisioning_safe_created", {
+          safe_address: provider.safeAddress
+        });
+      }
+    }
+  }).createMachine({
+    id: "provisioning",
+    initial: "starting",
+    context: ({ input }) => ({
+      input: input?.input ?? null,
+      account: null,
+      error: null
+    }),
+    states: {
+      // Transient routing state: skip `idle` when input was provided
+      // at creation time (the invoked-by-parent path).
+      starting: {
+        always: [
+          { guard: "hasInput", target: "running" },
+          { target: "idle" }
+        ]
+      },
+      idle: {
+        on: {
+          START: {
+            target: "running",
+            actions: assign({
+              input: ({ event }) => event.input,
+              account: () => null,
+              error: () => null
+            })
+          }
+        }
+      },
+      running: {
+        invoke: {
+          src: "provisionPersonal",
+          input: ({ context }) => ({
+            input: requireProvisionInput(context)
+          }),
+          onDone: {
+            target: "done",
+            actions: assign({ account: ({ event }) => event.output })
+          },
+          onError: {
+            target: "error",
+            actions: assign({ error: ({ event }) => errorFromEvent2(event) })
+          }
+        },
+        after: {
+          [FLOW_INVOKE_TIMEOUT_MS]: {
+            target: "error",
+            actions: assign({ error: () => timeoutError2() })
+          }
+        }
+      },
+      done: {
+        type: "final",
+        entry: ["trackWalletCreated", "trackSafeCreated"]
+      },
+      error: {
+        type: "final"
+      }
+    },
+    /**
+     * Root-level output mapper — fires when the machine reaches any
+     * top-level `final` state (`done` or `error`). The parent receives
+     * this payload on its `onDone` transition and branches via guards
+     * on `event.output.error`.
+     */
+    output: ({ context }) => context.error ? { error: context.error } : context.account ? { account: context.account } : { error: timeoutError2() }
+  });
+}
+function requireProvisionInput(context) {
+  if (!context.input) {
+    throw Errors.invalidInput(
+      "input",
+      "Provisioning flow advanced to running without input captured in context."
+    );
+  }
+  return context.input;
+}
+function errorFromEvent2(event) {
+  const cause = typeof event === "object" && event !== null && "error" in event ? event.error : event;
+  if (cause instanceof CapxulError) return cause;
+  if (cause instanceof CapxulError2) return cause;
+  return Errors.providerError("provisioning", "flow", cause);
+}
+function timeoutError2() {
+  return Errors.providerError(
+    "provisioning",
+    "flow",
+    new Error(`timeout: running exceeded ${FLOW_INVOKE_TIMEOUT_MS}ms`)
+  );
+}
+
+// src/flows/onboarding.ts
+function createOnboardingFlowMachine(client) {
+  const provisioningMachine = createProvisioningMachine(client);
+  return setup({
+    types: {},
+    actors: {
+      provisioningMachine
+    },
+    guards: {
+      isOrg: ({ event }) => event.type === "START_PROVISIONING" && event.input.kind !== "account",
+      missingSigner: ({ event }) => event.type === "START_PROVISIONING" && event.input.kind === "account" && !event.input.signerProvider,
+      childReportedError: ({ event }) => {
+        if (typeof event !== "object" || event === null || !("output" in event)) {
+          return false;
+        }
+        const output = event.output;
+        return typeof output === "object" && output !== null && "error" in output && output.error != null;
+      }
+    },
+    actions: {
+      // Always-on for any START_PROVISIONING transition.
+      assignOperationIdAndInput: assign({
+        operationId: () => generateOperationId(),
+        input: ({ event }) => event.type === "START_PROVISIONING" ? event.input : null,
+        error: () => null,
+        account: () => null
+      }),
+      // Pre-actor rejection branches stamp the synchronous error.
+      assignOrgNotImplemented: assign({
+        error: () => new CapxulError({
+          code: "NOT_IMPLEMENTED",
+          message: "useOnboardingFlow organization onboarding is not implemented in this local-private-key slice."
+        })
+      }),
+      assignMissingSigner: assign({
+        error: () => new CapxulError({
+          code: "INVALID_INPUT",
+          message: "useOnboardingFlow requires a signerProvider for account onboarding."
+        })
+      }),
+      // Telemetry actions — order matters; the source fires the
+      // "submitted" track BEFORE the rejection track on validation
+      // errors, and the happy path follows the documented sequence.
+      trackOrgSubmitted: ({ event }) => {
+        if (event.type !== "START_PROVISIONING") return;
+        track("onboarding_org_submitted", {
+          country: event.input.country ?? "unknown"
+        });
+      },
+      trackPersonalSubmitted: ({ event }) => {
+        if (event.type !== "START_PROVISIONING") return;
+        track("onboarding_personal_submitted", {
+          country: event.input.country ?? "unknown",
+          wallet_count: event.input.signerProvider ? 1 : 0
+        });
+      },
+      trackOrgNotImplementedError: () => {
+        track("onboarding_wallet_error", {
+          step: "profile",
+          reason: "organization_not_implemented"
+        });
+      },
+      trackMissingSignerError: () => {
+        track("onboarding_wallet_error", {
+          step: "profile",
+          reason: "missing_signer_provider"
+        });
+      },
+      trackWalletCreating: () => {
+        track("onboarding_wallet_creating");
+      },
+      trackOnboardingCompleted: () => {
+        track("onboarding_completed", { account_type: "personal" });
+      },
+      trackProvisioningFailed: ({ context }) => {
+        const code = context.error?.code ?? "UNKNOWN";
+        track("onboarding_wallet_error", {
+          step: "provision_personal",
+          reason: code
+        });
+      },
+      assignChildReportedError: assign({
+        error: ({ event }) => extractChildErrorOrFallback(event)
+      }),
+      assignChildThrown: assign({
+        error: ({ event }) => errorFromEvent3(event)
+      }),
+      assignAccountFromChild: assign({
+        account: ({ event }) => extractChildAccountOrNull(event)
+      }),
+      resetContext: assign({
+        input: () => null,
+        operationId: () => null,
+        account: () => null,
+        error: () => null
+      })
+    }
+  }).createMachine({
+    id: "onboarding",
+    initial: "profile",
+    context: {
+      input: null,
+      operationId: null,
+      account: null,
+      error: null
+    },
+    states: {
+      profile: {
+        on: {
+          START_PROVISIONING: [
+            {
+              guard: "isOrg",
+              target: "error",
+              actions: [
+                "assignOperationIdAndInput",
+                "trackOrgSubmitted",
+                "assignOrgNotImplemented",
+                "trackOrgNotImplementedError"
+              ]
+            },
+            {
+              guard: "missingSigner",
+              target: "error",
+              actions: [
+                "assignOperationIdAndInput",
+                "trackPersonalSubmitted",
+                "assignMissingSigner",
+                "trackMissingSignerError"
+              ]
+            },
+            {
+              target: "provisioning",
+              actions: [
+                "assignOperationIdAndInput",
+                "trackPersonalSubmitted"
+              ]
+            }
+          ]
+        }
+      },
+      provisioning: {
+        entry: ["trackWalletCreating"],
+        invoke: {
+          src: "provisioningMachine",
+          input: ({ context }) => ({
+            input: requireProvisionInput2(context)
+          }),
+          // The child machine reaches a top-level `final` state for
+          // both success and failure, so the parent's `onDone` fires
+          // in both cases. We branch via a guard on
+          // `event.output.error`. The child machine has its own
+          // `FLOW_INVOKE_TIMEOUT_MS` timer that ends in a final
+          // `error` state on timeout — that signal flows back through
+          // `onDone` + the `childReportedError` guard. The previous
+          // duplicate parent `after: FLOW_INVOKE_TIMEOUT_MS` was
+          // removed in PR #406 (X1+G3) so the child's `output.error`
+          // is the single source of provisioning failure.
+          onDone: [
+            {
+              guard: "childReportedError",
+              target: "error",
+              actions: [
+                "assignChildReportedError",
+                "trackProvisioningFailed"
+              ]
+            },
+            {
+              target: "complete",
+              actions: [
+                "assignAccountFromChild",
+                "trackOnboardingCompleted"
+              ]
+            }
+          ],
+          // `onError` is the safety net for an unexpected throw from
+          // inside the child machine itself (not the spawned actor's
+          // `error` final state, which goes through `onDone`). In
+          // normal flow this never fires.
+          onError: {
+            target: "error",
+            actions: ["assignChildThrown", "trackProvisioningFailed"]
+          }
+        }
+      },
+      // TODO(stack-1): wire `action_required` once the KYC gate /
+      // async-resume `NextAction` path is lifted from
+      // `useOperation(operationId)`. PROCEED → provisioning re-enters
+      // the actor with the resumed input. Currently unreachable from
+      // any transition; declared for parity with the public type.
+      action_required: {
+        on: {
+          PROCEED: { target: "provisioning" },
+          RESET: { target: "profile", actions: "resetContext" }
+        }
+      },
+      complete: {
+        on: {
+          RESET: { target: "profile", actions: "resetContext" }
+        }
+      },
+      error: {
+        on: {
+          RESET: { target: "profile", actions: "resetContext" }
+        }
+      }
+    }
+  });
+}
+function generateOperationId() {
+  return toOperationId(`op_onboarding_local_${Date.now().toString(36)}`);
+}
+function requireProvisionInput2(context) {
+  if (!context.input || !context.input.signerProvider) {
+    throw Errors.invalidInput(
+      "signerProvider",
+      "Onboarding flow advanced to provisioning without a signerProvider in context."
+    );
+  }
+  return {
+    displayName: context.input.displayName,
+    username: context.input.username,
+    countryCode: context.input.country,
+    signerProvider: context.input.signerProvider
+  };
+}
+function extractChildOutput(event) {
+  if (typeof event !== "object" || event === null || !("output" in event)) {
+    return null;
+  }
+  const output = event.output;
+  if (typeof output !== "object" || output === null) return null;
+  return output;
+}
+function extractChildErrorOrFallback(event) {
+  const output = extractChildOutput(event);
+  if (output && "error" in output && output.error) return output.error;
+  return Errors.providerError(
+    "onboarding",
+    "flow",
+    new Error("provisioning child reported error without payload")
+  );
+}
+function extractChildAccountOrNull(event) {
+  const output = extractChildOutput(event);
+  if (output && "account" in output && output.account) return output.account;
+  return null;
+}
+function errorFromEvent3(event) {
+  const cause = typeof event === "object" && event !== null && "error" in event ? event.error : event;
+  if (cause instanceof CapxulError) return cause;
+  if (cause instanceof CapxulError2) return cause;
+  return Errors.providerError("onboarding", "flow", cause);
+}
+
+// src/client.ts
+function createCapxulClient(config = {}) {
+  const clientWithoutFlows = {
+    id: crypto.randomUUID(),
+    auth: createAuthClient(config),
+    me: createMeClient(config),
+    accounts: createAccountsClient(config),
+    organizations: createOrganizationsClient(config),
+    payments: createPaymentsClient(config),
+    transfers: createTransfersClient(),
+    withdrawals: createWithdrawalsClient(config),
+    documents: createDocumentsClient(),
+    subAccounts: createSubAccountsClient(),
+    virtualAccounts: createVirtualAccountsClient(),
+    virtualCards: createVirtualCardsClient(),
+    externalAccounts: createExternalAccountsClient(),
+    operations: createOperationsClient(config),
+    webhookEndpoints: createWebhookEndpointsClient(),
+    webhookEvents: createWebhookEventsClient(),
+    apiKeys: createApiKeysClient()
+  };
+  const client = clientWithoutFlows;
+  client.flows = {
+    auth: () => createAuthFlowMachine(client),
+    onboarding: () => createOnboardingFlowMachine(client),
+    provisioning: () => createProvisioningMachine(client)
+  };
+  return client;
+}
+
+export { createCapxulClient };