@capxul/sdk 0.1.0-alpha.1 → 0.1.0-alpha.12

package/dist/index.cjs

@@ -70,12 +70,775 @@ function fromConvexError(error) {
   });
 }
 
+// ../observability/src/try-catch.ts
+async function tryCatch(promise) {
+  try {
+    return [null, await promise];
+  } catch (e) {
+    return [e instanceof Error ? e : new Error(String(e)), null];
+  }
+}
+
+// ../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 ?? "")}`);
+}
+
+// ../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 toAccountId = makePrefixedIdConstructor(
+  "acct",
+  "accountId"
+);
+var toOrganizationId = makePrefixedIdConstructor("org", "organizationId");
+var toMemberId = makePrefixedIdConstructor(
+  "mem",
+  "memberId"
+);
+var toSafeId = makePrefixedIdConstructor(
+  "safe",
+  "safeId"
+);
+var toTreasuryId = makePrefixedIdConstructor(
+  "try",
+  "treasuryId"
+);
+var toApiKeyId = makePrefixedIdConstructor(
+  "ak",
+  "apiKeyId"
+);
+var toOperationId = makePrefixedIdConstructor(
+  "op",
+  "operationId"
+);
+var toCorrelationId = makePrefixedIdConstructor("ctx", "correlationId");
+var toKycProfileId = makePrefixedIdConstructor(
+  "kyc",
+  "kycProfileId"
+);
+var toKybProfileId = makePrefixedIdConstructor(
+  "kyb",
+  "kybProfileId"
+);
+var toExternalAccountId = makePrefixedIdConstructor("ext", "externalAccountId");
+var toPaymentId = makePrefixedIdConstructor(
+  "pay",
+  "paymentId"
+);
+var toWithdrawalId = makePrefixedIdConstructor(
+  "wd",
+  "withdrawalId"
+);
+var toWebhookEndpointId = makePrefixedIdConstructor("we", "webhookEndpointId");
+var toWebhookEventId = makePrefixedIdConstructor("evt", "webhookEventId");
+var toSubAccountId = makePrefixedIdConstructor(
+  "sub",
+  "subAccountId"
+);
+var toVirtualAccountId = makePrefixedIdConstructor("va", "virtualAccountId");
+var toVirtualCardId = makePrefixedIdConstructor(
+  "vc",
+  "virtualCardId"
+);
+var toTransferId = makePrefixedIdConstructor(
+  "txfr",
+  "transferId"
+);
+var toDocumentId = makePrefixedIdConstructor(
+  "doc",
+  "documentId"
+);
+var toBalanceLedgerEntryId = makePrefixedIdConstructor("bal", "balanceLedgerEntryId");
+
+// ../platform-kernel/src/value-objects.ts
+var PHONE_NUMBER_RE = /^\+[1-9]\d{1,14}$/;
+function toPhoneNumber(raw) {
+  if (typeof raw !== "string" || !PHONE_NUMBER_RE.test(raw)) {
+    throw new Error(
+      `Invalid phoneNumber: expected E.164 string matching ^\\+[1-9]\\d{1,14}$, got ${String(raw)}`
+    );
+  }
+  return raw;
+}
+var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function toEmail(raw) {
+  if (typeof raw !== "string") {
+    throw new Error(
+      `Invalid email: expected string, got ${String(raw)}`
+    );
+  }
+  const lowered = raw.trim().toLowerCase();
+  if (!EMAIL_RE.test(lowered)) {
+    throw new Error(
+      `Invalid email: expected local@domain.tld, got ${String(raw)}`
+    );
+  }
+  return lowered;
+}
+var USERNAME_RE = /^[a-z][a-z0-9_-]{2,29}$/;
+function toUsername(raw) {
+  if (typeof raw !== "string") {
+    throw new Error(
+      `Invalid username: expected string, got ${String(raw)}`
+    );
+  }
+  const lowered = raw.toLowerCase();
+  if (!USERNAME_RE.test(lowered)) {
+    throw new Error(
+      `Invalid username: expected 3-30 chars, letter-first, [a-z0-9_-], got ${String(raw)}`
+    );
+  }
+  return lowered;
+}
+
+// src/core/external-accounts.ts
+function brandExternalAccount(raw) {
+  return {
+    ...raw,
+    id: toExternalAccountId(raw.id),
+    operation: {
+      id: toOperationId(raw.operation.id),
+      status: raw.operation.status,
+      correlationId: toCorrelationId(raw.operation.correlationId)
+    }
+  };
+}
+function createExternalAccountsClient(config = {}) {
+  return {
+    retrieve: async (externalAccountId) => {
+      if (!config.data) {
+        return stub(
+          "externalAccounts.retrieve"
+        );
+      }
+      const [err, raw] = await tryCatch(
+        config.data.query(api.externalAccounts.queries.retrievePersonal, {
+          externalAccountId
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      if (!raw) {
+        return [
+          new CapxulError({
+            code: "NOT_FOUND",
+            message: `external_account ${externalAccountId} not found`
+          }),
+          null
+        ];
+      }
+      return [null, brandExternalAccount(raw)];
+    },
+    remove: async (externalAccountId) => {
+      if (!config.data) {
+        return stub("externalAccounts.remove");
+      }
+      const [err] = await tryCatch(
+        config.data.mutation(api.externalAccounts.mutations.removePersonal, {
+          externalAccountId
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      return [null, void 0];
+    }
+  };
+}
+
+// src/core/sub-accounts.ts
+function malformedWireError(reason, raw) {
+  return new CapxulError({
+    code: "PROVIDER_ERROR",
+    message: `convex brandSubAccount failed: ${reason}`,
+    details: {
+      provider: "convex",
+      operation: "brandSubAccount",
+      reason,
+      // PII discipline (`.claude/rules/posthog.md`): user-authored
+      // strings on the wire (`name`, `purpose`) are customer-confidential
+      // — sub-account names like "Q3 Acquisition Reserve" or
+      // "Vendor ABC payments" must not flow into telemetry. We emit a
+      // structural keys-only sample via a strict ALLOWLIST so any future
+      // wire-shape addition (e.g. `recipientEmail`, `tags`) is dropped
+      // by construction rather than leaked through a denylist gap.
+      sample: safeSampleShape(raw)
+    }
+  });
+}
+function safeSampleShape(raw) {
+  if (raw === null || typeof raw !== "object") {
+    return { type: typeof raw };
+  }
+  const r = raw;
+  const balance = r.balance;
+  return {
+    object: typeof r.object === "string" ? r.object : typeof r.object,
+    idPresent: typeof r.id === "string" && r.id.length > 0,
+    // First 4 chars only — enough to distinguish "sub_" prefixed IDs
+    // from accidental other resource IDs without leaking the full ID.
+    idPrefix: typeof r.id === "string" ? r.id.slice(0, 4) : void 0,
+    parentKind: r.parent !== null && typeof r.parent === "object" ? r.parent.kind : typeof r.parent,
+    status: r.status,
+    hasName: typeof r.name === "string",
+    hasPurpose: r.purpose !== void 0,
+    balanceShape: balance !== null && typeof balance === "object" ? Object.keys(balance).sort() : typeof balance,
+    createdAtType: typeof r.createdAt,
+    updatedAtType: typeof r.updatedAt
+  };
+}
+function isMoneyShape(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const m = v;
+  return typeof m.value === "string" && typeof m.currency === "string";
+}
+function isParentShape(v) {
+  if (typeof v !== "object" || v === null) return false;
+  const p = v;
+  return (p.kind === "account" || p.kind === "organization") && typeof p.id === "string";
+}
+function isFiniteNonNegativeInteger(v) {
+  return typeof v === "number" && Number.isFinite(v) && Number.isInteger(v) && v >= 0;
+}
+function validateWireSubAccount(raw) {
+  if (typeof raw !== "object" || raw === null) {
+    return { ok: false, reason: "not an object" };
+  }
+  const r = raw;
+  if (r.object !== "sub_account") {
+    return { ok: false, reason: `object must be "sub_account" (got ${String(r.object)})` };
+  }
+  if (typeof r.id !== "string" || r.id.length === 0) {
+    return { ok: false, reason: "id must be a non-empty string" };
+  }
+  if (!isParentShape(r.parent)) {
+    return { ok: false, reason: "parent must be { kind: 'account' | 'organization', id: string }" };
+  }
+  if (typeof r.name !== "string") {
+    return { ok: false, reason: "name must be a string" };
+  }
+  if (r.purpose !== void 0 && typeof r.purpose !== "string") {
+    return { ok: false, reason: "purpose must be a string when present" };
+  }
+  if (r.status !== "active" && r.status !== "archived") {
+    return { ok: false, reason: `status must be "active" | "archived" (got ${String(r.status)})` };
+  }
+  if (!isMoneyShape(r.balance)) {
+    return { ok: false, reason: "balance must be { value: string, currency: string }" };
+  }
+  if (!isFiniteNonNegativeInteger(r.createdAt)) {
+    return { ok: false, reason: "createdAt must be a finite non-negative integer (epoch ms)" };
+  }
+  if (r.updatedAt !== void 0 && !isFiniteNonNegativeInteger(r.updatedAt)) {
+    return { ok: false, reason: "updatedAt must be a finite non-negative integer when present" };
+  }
+  return { ok: true, value: r };
+}
+function brandSubAccount(raw) {
+  const result = validateWireSubAccount(raw);
+  if (!result.ok) {
+    throw malformedWireError(result.reason, raw);
+  }
+  const wire = result.value;
+  return {
+    object: wire.object,
+    id: toSubAccountId(wire.id),
+    parent: wire.parent,
+    name: wire.name,
+    ...wire.purpose !== void 0 ? { purpose: wire.purpose } : {},
+    status: wire.status,
+    balance: wire.balance,
+    createdAt: new Date(wire.createdAt).toISOString()
+  };
+}
+function tryBrandSubAccount(raw) {
+  try {
+    return [null, brandSubAccount(raw)];
+  } catch (err) {
+    if (err instanceof CapxulError && err.code === "PROVIDER_ERROR") {
+      return [err, null];
+    }
+    return [
+      malformedWireError(
+        err instanceof Error ? err.message : String(err),
+        raw
+      ),
+      null
+    ];
+  }
+}
+function createSubAccountsClient(config = {}) {
+  return {
+    retrieve: async (subAccountId) => {
+      if (!config.data) {
+        return stub("subAccounts.retrieve");
+      }
+      const [err, raw] = await tryCatch(
+        config.data.query(api.subAccounts.queries.retrieve, {
+          subAccountId
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      if (!raw) {
+        return [
+          new CapxulError({
+            code: "NOT_FOUND",
+            message: `sub_account ${subAccountId} not found`
+          }),
+          null
+        ];
+      }
+      const [brandErr, branded] = tryBrandSubAccount(raw);
+      if (brandErr) {
+        return [brandErr, null];
+      }
+      return [null, branded];
+    },
+    remove: async (subAccountId) => {
+      if (!config.data) {
+        return stub("subAccounts.remove");
+      }
+      const [err, raw] = await tryCatch(
+        config.data.mutation(api.subAccounts.mutations.archive, {
+          subAccountId
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      if (!raw) {
+        return [
+          new CapxulError({
+            code: "NOT_FOUND",
+            message: `sub_account ${subAccountId} not found`
+          }),
+          null
+        ];
+      }
+      const [brandErr, branded] = tryBrandSubAccount(raw);
+      if (brandErr) {
+        return [brandErr, null];
+      }
+      return [null, branded];
+    }
+  };
+}
+
 // src/core/accounts.ts
+function createAccountExternalAccountsClient(config) {
+  return {
+    create: async (input) => {
+      if (!config.data) {
+        return stub(
+          "accounts.externalAccounts.create"
+        );
+      }
+      const [err, raw] = await tryCatch(
+        config.data.mutation(
+          api.externalAccounts.mutations.createPersonal,
+          {
+            kind: input.kind,
+            label: input.label,
+            address: input.address,
+            iban: input.iban,
+            bic: input.bic,
+            accountHolder: input.accountHolder,
+            network: input.network,
+            panToken: input.panToken,
+            last4: input.last4
+          }
+        )
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      if (!raw) {
+        return [
+          new CapxulError({
+            code: "NOT_FOUND",
+            message: "external_account creation returned no resource"
+          }),
+          null
+        ];
+      }
+      return [
+        null,
+        brandExternalAccount(
+          raw
+        )
+      ];
+    },
+    list: async (input) => {
+      if (!config.data) {
+        return stub(
+          "accounts.externalAccounts.list"
+        );
+      }
+      const [err, result] = await tryCatch(
+        config.data.query(api.externalAccounts.queries.listPersonal, {
+          limit: input.limit,
+          cursor: input.cursor
+        })
+      );
+      if (err) {
+        return [fromConvexError(err), null];
+      }
+      const branded = result.data.map(
+        (row) => brandExternalAccount(
+          row
+        )
+      );
+      return [
+        null,
+        {
+          object: "list",
+          data: branded,
+          page: result.page
+        }
+      ];
+    },
+    retrieve: async (externalAccountId) => {
+      if (!config.data) {
+        return stub(
+          "accounts.externalAccounts.retrieve"
+        );
+      }
+      const [err, raw] = await tryCatch(
+        config.data.query(api.externalAccounts.queries.retrievePersonal, {
+          externalAccountId
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      if (!raw) {
+        return [
+          new CapxulError({
+            code: "NOT_FOUND",
+            message: `external_account ${externalAccountId} not found`
+          }),
+          null
+        ];
+      }
+      return [
+        null,
+        brandExternalAccount(
+          raw
+        )
+      ];
+    },
+    remove: async (externalAccountId) => {
+      if (!config.data) {
+        return stub("accounts.externalAccounts.remove");
+      }
+      const [err] = await tryCatch(
+        config.data.mutation(api.externalAccounts.mutations.removePersonal, {
+          externalAccountId
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      return [null, void 0];
+    }
+  };
+}
+function createAccountSubAccountsClient(config) {
+  return {
+    create: async (input) => {
+      if (!config.data) {
+        return stub(
+          "accounts.subAccounts.create"
+        );
+      }
+      const [err, raw] = await tryCatch(
+        config.data.mutation(api.subAccounts.mutations.create, {
+          parent: { kind: "account", id: input.accountId },
+          name: input.name,
+          purpose: input.purpose
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      if (!raw) {
+        return [
+          new CapxulError({
+            code: "NOT_FOUND",
+            message: "sub_account creation returned no resource"
+          }),
+          null
+        ];
+      }
+      const [brandErr, branded] = tryBrandSubAccount(raw);
+      if (brandErr) {
+        return [
+          brandErr,
+          null
+        ];
+      }
+      return [null, branded];
+    },
+    list: async (input) => {
+      if (!config.data) {
+        return stub(
+          "accounts.subAccounts.list"
+        );
+      }
+      const [err, rows] = await tryCatch(
+        config.data.query(api.subAccounts.queries.listByAccount, {
+          accountId: input.accountId
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      const branded = [];
+      for (const row of rows) {
+        const [brandErr, value] = tryBrandSubAccount(row);
+        if (brandErr) {
+          return [
+            brandErr,
+            null
+          ];
+        }
+        branded.push(value);
+      }
+      return [
+        null,
+        {
+          object: "list",
+          data: branded,
+          page: { hasMore: false }
+        }
+      ];
+    },
+    retrieve: async (subAccountId) => {
+      if (!config.data) {
+        return stub(
+          "accounts.subAccounts.retrieve"
+        );
+      }
+      const [err, raw] = await tryCatch(
+        config.data.query(api.subAccounts.queries.retrieve, {
+          subAccountId
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      if (!raw) {
+        return [
+          new CapxulError({
+            code: "NOT_FOUND",
+            message: `sub_account ${subAccountId} not found`
+          }),
+          null
+        ];
+      }
+      const [brandErr, branded] = tryBrandSubAccount(raw);
+      if (brandErr) {
+        return [
+          brandErr,
+          null
+        ];
+      }
+      return [null, branded];
+    },
+    remove: async (subAccountId) => {
+      if (!config.data) {
+        return stub(
+          "accounts.subAccounts.remove"
+        );
+      }
+      const [err, raw] = await tryCatch(
+        config.data.mutation(api.subAccounts.mutations.archive, {
+          subAccountId
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      if (!raw) {
+        return [
+          new CapxulError({
+            code: "NOT_FOUND",
+            message: `sub_account ${subAccountId} not found`
+          }),
+          null
+        ];
+      }
+      const [brandErr, branded] = tryBrandSubAccount(raw);
+      if (brandErr) {
+        return [
+          brandErr,
+          null
+        ];
+      }
+      return [null, branded];
+    }
+  };
+}
 function createAccountsClient(config = {}) {
   return {
-    retrieve: async () => stub("accounts.retrieve"),
+    retrieve: async (accountId) => {
+      if (!config.data) {
+        return stub("accounts.retrieve");
+      }
+      try {
+        const account = await config.data.query(
+          api.openfort.queries.getMyAccount,
+          {}
+        );
+        if (account.id !== accountId) {
+          return [
+            new CapxulError({
+              code: "PERMISSION_DENIED",
+              message: "accounts.retrieve currently supports the authenticated caller's own account only.",
+              details: {
+                requestedAccountId: accountId,
+                authenticatedAccountId: account.id
+              }
+            }),
+            null
+          ];
+        }
+        return [null, account];
+      } catch (cause) {
+        return [fromConvexError(cause), null];
+      }
+    },
     lookup: async () => stub("accounts.lookup"),
-    update: async () => stub("accounts.update"),
+    update: async (input) => {
+      if (!config.data) {
+        return stub("accounts.update");
+      }
+      if (input.countryCode !== void 0) {
+        return [
+          new CapxulError({
+            code: "INVALID_INPUT",
+            message: "accounts.update does not support countryCode yet \u2014 backend mutation only patches displayName and username.",
+            details: { field: "countryCode" }
+          }),
+          null
+        ];
+      }
+      try {
+        const current = await config.data.query(
+          api.openfort.queries.getMyAccount,
+          {}
+        );
+        if (current.id !== input.accountId) {
+          return [
+            new CapxulError({
+              code: "PERMISSION_DENIED",
+              message: "accounts.update currently supports the authenticated caller's own account only.",
+              details: {
+                requestedAccountId: input.accountId,
+                authenticatedAccountId: current.id
+              }
+            }),
+            null
+          ];
+        }
+        await config.data.mutation(api.openfort.mutations.updateProfile, {
+          displayName: input.name,
+          username: input.username
+        });
+        const updated = await config.data.query(
+          api.openfort.queries.getMyAccount,
+          {}
+        );
+        return [null, updated];
+      } catch (cause) {
+        return [fromConvexError(cause), null];
+      }
+    },
     provisionPersonal: async (input) => {
       if (!config.data) {
         return stub(
@@ -155,24 +918,8 @@ function createAccountsClient(config = {}) {
       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")
-    },
+    externalAccounts: createAccountExternalAccountsClient(config),
+    subAccounts: createAccountSubAccountsClient(config),
     balanceLedger: {
       list: async () => stub(
         "accounts.balanceLedger.list"
@@ -232,10 +979,16 @@ var Errors = {
     `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 } }
+  providerError: (provider, operation, cause) => (
+    // Public `message` is redacted to a fixed shape so provider-side
+    // exception text never leaks to the client. The original `cause`
+    // is preserved on `Error.cause` for server-side debugging via
+    // observability sinks (Sentry, console traces).
+    new CapxulError2(
+      "PROVIDER_ERROR",
+      `Provider error: ${provider} ${operation}`,
+      { cause, details: { provider, operation } }
+    )
   ),
   invalidInput: (field, reason) => new CapxulError2(
     "INVALID_INPUT",
@@ -261,8 +1014,35 @@ var Errors = {
     "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}`)
+  emailDeliveryFailed: (detail, details) => new CapxulError2("EMAIL_DELIVERY_FAILED", `Failed to send email: ${detail}`, {
+    details
+  }),
+  rateLimited: (details) => new CapxulError2("RATE_LIMITED", "Request was rate limited", {
+    details: { ...details }
+  }),
+  internalError: (reason) => new CapxulError2("INTERNAL_ERROR", `Internal error: ${reason}`),
+  /**
+   * Verification gate. Surfaced when a request hits a verification
+   * boundary the actor cannot cross under their current state. Two
+   * variants share this code:
+   *
+   * - Rail gate (Withdrawals v1 W2, #465): the resolved
+   *   `external_account.kind` routes to a withdrawal rail (e.g.
+   *   `fiat_offramp`, `card_payout`) that is not yet supported. Carries
+   *   `details.rail` + `details.currentKind`.
+   * - KYC tier gate (legacy / future): the actor's KYC tier is below
+   *   the required tier. Carries `details.requiredTier`.
+   *
+   * Code is shared because both expose the same UX shape ("you cannot
+   * proceed until verification advances"); the `details.*` keys
+   * differentiate the route.
+   */
+  verificationRequired: (details) => {
+    const message = "rail" in details ? `Withdrawal rail "${details.rail}" (kind=${details.currentKind}) is not yet supported.` : `Verification tier ${details.requiredTier} is required.`;
+    return new CapxulError2("VERIFICATION_REQUIRED", message, {
+      details: { ...details }
+    });
+  }
 };
 
 // ../config/src/safe.ts
@@ -312,13 +1092,13 @@ function createLifecycle(initial) {
 }
 function makeBuildTimeUrlsTransport(config) {
   if (!config.authBaseUrl || config.authBaseUrl.trim().length === 0) {
-    throw Errors.invalidInput(
+    throw invalidConfigError(
       "authBaseUrl",
       "build-time-urls transport requires a non-empty authBaseUrl."
     );
   }
   if (!config.convexUrl || config.convexUrl.trim().length === 0) {
-    throw Errors.invalidInput(
+    throw invalidConfigError(
       "convexUrl",
       "build-time-urls transport requires a non-empty convexUrl."
     );
@@ -332,6 +1112,7 @@ function makeBuildTimeUrlsTransport(config) {
   return {
     authBaseUrl,
     convexUrl,
+    ensureRuntime: async () => runtime,
     fetch: (path, init) => fetchImpl(resolveUrl(authBaseUrl, path), init),
     getState: lifecycle.getState,
     subscribe: lifecycle.subscribe,
@@ -347,14 +1128,15 @@ function makeBuildTimeUrlsTransport(config) {
   };
 }
 function makePublishableKeyTransport(config) {
-  if (!config.publishableKey || config.publishableKey.trim().length === 0) {
-    throw Errors.invalidInput(
+  const publishableKey = config.publishableKey?.trim();
+  if (!publishableKey) {
+    throw invalidConfigError(
       "publishableKey",
       "publishable-key transport requires a non-empty publishableKey."
     );
   }
   const fetchImpl = config.fetchImpl ?? globalThis.fetch;
-  const bootstrapUrl = stripTrailingSlash(
+  const bootstrapUrl = normalizeBootstrapUrl(
     config.bootstrapUrl ?? `${CAPXUL_API_BASE_URL}/v1/client/bootstrap`
   );
   let authBaseUrl = "";
@@ -369,23 +1151,20 @@ function makePublishableKeyTransport(config) {
       const response = await fetchImpl(bootstrapUrl, {
         method: "POST",
         headers: { "content-type": "application/json" },
-        body: JSON.stringify({ publishableKey: config.publishableKey })
+        body: JSON.stringify({ publishableKey })
       });
       if (!response.ok) {
-        throw Errors.invalidInput(
-          "publishableKey",
-          `${bootstrapUrl} failed with HTTP ${response.status}.`
-        );
+        throw await bootstrapResponseError(response, bootstrapUrl);
       }
-      const body = await response.json();
+      const body = await readBootstrapSuccessBody(response);
       if (typeof body.authBaseUrl !== "string" || body.authBaseUrl.trim().length === 0) {
-        throw Errors.invalidInput(
+        throw bootstrapContractError(
           "authBaseUrl",
           "/v1/client/bootstrap returned no authBaseUrl."
         );
       }
       if (typeof body.convexUrl !== "string" || body.convexUrl.trim().length === 0) {
-        throw Errors.invalidInput(
+        throw bootstrapContractError(
           "convexUrl",
           "/v1/client/bootstrap returned no convexUrl."
         );
@@ -397,16 +1176,13 @@ function makePublishableKeyTransport(config) {
       return runtime;
     })();
     bootstrapPromise = attempt.catch((err) => {
+      const error = normalizeBootstrapThrownError(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
-        })
+        error
       });
-      throw err;
+      throw error;
     });
     return await bootstrapPromise;
   }
@@ -417,6 +1193,7 @@ function makePublishableKeyTransport(config) {
     get convexUrl() {
       return convexUrl;
     },
+    ensureRuntime: ensureBootstrap,
     fetch: async (path, init) => {
       const resolved = await ensureBootstrap();
       return await fetchImpl(resolveUrl(resolved.authBaseUrl, path), init);
@@ -427,7 +1204,7 @@ function makePublishableKeyTransport(config) {
     markAuthenticated: ({ dataClient: nextDataClient }) => {
       const current = lifecycle.getState();
       if (current.status !== "ready" && current.status !== "authenticated") {
-        throw Errors.internalError(
+        throw internalTransportError(
           `markAuthenticated() called from status="${current.status}". Expected "ready" or "authenticated".`
         );
       }
@@ -449,6 +1226,24 @@ function makePublishableKeyTransport(config) {
 function stripTrailingSlash(url) {
   return url.replace(/\/+$/, "");
 }
+function normalizeBootstrapUrl(url) {
+  const normalized = stripTrailingSlash(url.trim());
+  if (!isAbsoluteHttpUrl(normalized)) {
+    throw invalidConfigError(
+      "bootstrapUrl",
+      "publishable-key transport requires an absolute http(s) bootstrapUrl."
+    );
+  }
+  return normalized;
+}
+function isAbsoluteHttpUrl(url) {
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
 function resolveUrl(authBaseUrl, path) {
   if (path.startsWith("http://") || path.startsWith("https://")) {
     return path;
@@ -456,10 +1251,142 @@ function resolveUrl(authBaseUrl, path) {
   return `${authBaseUrl}${path}`;
 }
 function assertNever(value) {
-  throw Errors.internalError(
+  throw internalTransportError(
     `Unhandled BrowserCapxulConfig.mode: ${String(value.mode)}.`
   );
 }
+function invalidConfigError(field, reason) {
+  return new CapxulError({
+    code: "INVALID_INPUT",
+    message: `Invalid ${field}: ${reason}`,
+    details: { source: "sdk-config", field, reason }
+  });
+}
+function bootstrapContractError(field, message) {
+  return new CapxulError({
+    code: "INVALID_INPUT",
+    message,
+    details: {
+      source: "backend-bootstrap",
+      phase: "publishable-key-bootstrap",
+      field,
+      reason: message
+    }
+  });
+}
+function internalTransportError(reason) {
+  return new CapxulError({
+    code: "INTERNAL_ERROR",
+    message: `Internal error: ${reason}`,
+    details: { source: "sdk-transport", reason }
+  });
+}
+async function bootstrapResponseError(response, bootstrapUrl) {
+  const envelope = await readBootstrapErrorEnvelope(response);
+  const wireCode = readNonEmptyString(envelope?.error?.code);
+  const normalized = normalizeBootstrapErrorCode(wireCode);
+  const message = readNonEmptyString(envelope?.error?.message) ?? `${bootstrapUrl} failed with HTTP ${response.status}.`;
+  const backendDetails = readRecord(envelope?.error?.details);
+  return new CapxulError({
+    code: normalized.code,
+    message,
+    details: {
+      ...backendDetails,
+      source: "backend-bootstrap",
+      phase: "publishable-key-bootstrap",
+      httpStatus: response.status,
+      ...normalized.wireCode ? { wireCode: normalized.wireCode } : {}
+    },
+    operationId: readNonEmptyString(envelope?.error?.operationId),
+    correlationId: readNonEmptyString(envelope?.error?.correlationId),
+    retryable: typeof envelope?.error?.retryable === "boolean" ? envelope.error.retryable : void 0
+  });
+}
+async function readBootstrapErrorEnvelope(response) {
+  try {
+    const parsed = await response.json();
+    return typeof parsed === "object" && parsed !== null ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+async function readBootstrapSuccessBody(response) {
+  try {
+    const parsed = await response.json();
+    return typeof parsed === "object" && parsed !== null ? parsed : {};
+  } catch {
+    throw bootstrapContractError(
+      "body",
+      "/v1/client/bootstrap returned invalid JSON."
+    );
+  }
+}
+function normalizeBootstrapThrownError(error) {
+  if (error instanceof CapxulError) return error;
+  return new CapxulError({
+    code: "NETWORK_ERROR",
+    message: "Publishable-key bootstrap network failure.",
+    cause: error,
+    details: {
+      source: "bootstrap-network",
+      phase: "publishable-key-bootstrap"
+    }
+  });
+}
+function normalizeBootstrapErrorCode(wireCode) {
+  if (wireCode === "INTERNAL_SERVER_ERROR") {
+    return { code: "INTERNAL_ERROR", wireCode };
+  }
+  if (wireCode && isCapxulErrorCode(wireCode)) {
+    return { code: wireCode };
+  }
+  return wireCode ? { code: "UNKNOWN", wireCode } : { code: "UNKNOWN" };
+}
+var CAPXUL_ERROR_CODES = /* @__PURE__ */ new Set([
+  "NOT_AUTHENTICATED",
+  "EMAIL_DELIVERY_FAILED",
+  "PROFILE_NOT_FOUND",
+  "SMART_ACCOUNT_MISSING",
+  "PLAYER_NOT_FOUND",
+  "ACCOUNT_NOT_FOUND",
+  "PROVIDER_ERROR",
+  "INVALID_INPUT",
+  "ENV_MISSING",
+  "NOT_IMPLEMENTED",
+  "VERIFICATION_REQUIRED",
+  "INSUFFICIENT_BALANCE",
+  "INVALID_RECIPIENT",
+  "TRANSACTION_FAILED",
+  "RATE_LIMITED",
+  "NETWORK_ERROR",
+  "UNKNOWN",
+  "PERMISSION_DENIED",
+  "API_KEY_INVALID",
+  "API_KEY_EXPIRED",
+  "IDEMPOTENCY_CONFLICT",
+  "NOT_FOUND",
+  "OPERATION_CANCELED",
+  "OPERATION_TIMEOUT",
+  "ACTION_REQUIRED",
+  "KYC_REQUIRED",
+  "POLICY_DENIED",
+  "SAFE_NOT_READY",
+  "PROVIDER_UNAVAILABLE",
+  "PROVIDER_REJECTED",
+  "RECONCILIATION_FAILED",
+  "INTERNAL_ERROR",
+  "QUOTE_EXPIRED",
+  "QUOTE_NOT_FOUND"
+]);
+function isCapxulErrorCode(value) {
+  return CAPXUL_ERROR_CODES.has(value);
+}
+function readRecord(value) {
+  return typeof value === "object" && value !== null ? value : null;
+}
+function readNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
 
 // src/core/auth.ts
 function createAuthClient(config = {}) {
@@ -514,13 +1441,16 @@ function createAuthClient(config = {}) {
         email: signIn.user.email,
         token: signIn.token,
         convexJwt,
-        expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1e3).toISOString()
+        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;
+          transport.markAuthenticated({ dataClient });
         } catch (cause) {
           return [
             new CapxulError({
@@ -532,13 +1462,76 @@ function createAuthClient(config = {}) {
           ];
         }
       }
-      return [null, session];
+      if (!dataClient) {
+        return [
+          new CapxulError({
+            code: "NOT_AUTHENTICATED",
+            message: "Auth bootstrap requires an authenticated Convex data client."
+          }),
+          null
+        ];
+      }
+      try {
+        const resolution = await dataClient.mutation(
+          api.authBootstrap.resolveAfterOtp,
+          {
+            email: session.email,
+            sessionToken: session.token
+          }
+        );
+        if (resolution.kind === "existing_member") {
+          return [null, { ...resolution, session }];
+        }
+        return [null, { ...resolution, session }];
+      } catch (cause) {
+        return [fromConvexError(cause), null];
+      }
+    },
+    completeBootstrap: async (input) => {
+      const session = sessionStore.get();
+      const data = dataClient ?? config.data;
+      if (!session || !data) {
+        return [
+          new CapxulError({
+            code: "INVALID_INPUT",
+            message: "completeBootstrap requires the OTP-verified session that issued the bootstrap token."
+          }),
+          null
+        ];
+      }
+      if (input.signerProvider.kind !== "local-private-key") {
+        return [
+          new CapxulError({
+            code: "INVALID_INPUT",
+            message: "completeBootstrap currently supports local-private-key signer providers only."
+          }),
+          null
+        ];
+      }
+      try {
+        const result = await data.mutation(api.authBootstrap.completeBootstrap, {
+          bootstrapToken: input.bootstrapToken,
+          sessionToken: session.token,
+          username: input.username,
+          displayName: input.displayName,
+          countryCode: input.countryCode,
+          signerProvider: input.signerProvider
+        });
+        return [null, { kind: "authenticated", session, ...result }];
+      } catch (cause) {
+        return [
+          fromConvexError(cause),
+          null
+        ];
+      }
     },
     getSession: async () => [null, sessionStore.get()],
     signOut: async () => {
       sessionStore.clear();
       dataClient = null;
       mutableConfig(config).data = void 0;
+      const transport = getTransport();
+      transport?.clearAuth();
       return [null, void 0];
     },
     serviceTokenMint: async () => stub("auth.serviceTokenMint"),
@@ -592,16 +1585,19 @@ async function postBetterAuth(transport, path, body, code, signal) {
       body: JSON.stringify(body),
       signal
     });
+    const text = await response.text();
     if (!response.ok) {
+      const parsedError = parseBetterAuthError(text);
       return [
         new CapxulError({
-          code,
-          message: `BetterAuth ${path} failed with HTTP ${response.status}.`
+          code: parsedError.code ?? code,
+          message: parsedError.message ?? `BetterAuth ${path} failed with HTTP ${response.status}.`,
+          details: parsedError.details,
+          retryable: parsedError.retryable
         }),
         null
       ];
     }
-    const text = await response.text();
     return [null, text ? JSON.parse(text) : void 0];
   } catch (cause) {
     return [
@@ -614,6 +1610,36 @@ async function postBetterAuth(transport, path, body, code, signal) {
     ];
   }
 }
+function parseBetterAuthError(text) {
+  if (!text.trim()) {
+    return {};
+  }
+  try {
+    const body = JSON.parse(text);
+    if (!body || typeof body !== "object") {
+      return {};
+    }
+    const record = body;
+    const nested = record.error && typeof record.error === "object" ? record.error : record;
+    const code = typeof nested.code === "string" ? nested.code : void 0;
+    const message = typeof nested.message === "string" ? nested.message : void 0;
+    const details = nested.details && typeof nested.details === "object" ? nested.details : void 0;
+    const correlationId = typeof nested.correlationId === "string" ? nested.correlationId : void 0;
+    const retryable = typeof nested.retryable === "boolean" ? nested.retryable : void 0;
+    return {
+      code: isCapxulErrorCode2(code) ? code : void 0,
+      message,
+      details,
+      correlationId,
+      retryable
+    };
+  } catch {
+    return {};
+  }
+}
+function isCapxulErrorCode2(code) {
+  return code === "NOT_AUTHENTICATED" || code === "EMAIL_DELIVERY_FAILED" || code === "INVALID_INPUT" || code === "RATE_LIMITED" || code === "NETWORK_ERROR" || code === "API_KEY_INVALID" || code === "API_KEY_EXPIRED" || code === "INTERNAL_ERROR" || code === "ENV_MISSING" || code === "UNKNOWN" || code === "PROVIDER_ERROR";
+}
 async function exchangeConvexToken(transport, config, token, signal) {
   const path = config.auth?.convexTokenUrl ?? "/convex/token";
   try {
@@ -674,14 +1700,6 @@ function createOrgDocumentsClient() {
   };
 }
 
-// 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 {
@@ -699,7 +1717,34 @@ function createMeClient(config = {}) {
         return [fromConvexError(cause), null];
       }
     },
-    update: async () => stub("me.update")
+    update: async (input) => {
+      if (!config.data) {
+        return stub("me.update");
+      }
+      if (input.countryCode !== void 0) {
+        return [
+          new CapxulError({
+            code: "INVALID_INPUT",
+            message: "me.update does not support countryCode yet \u2014 backend mutation only patches displayName and username.",
+            details: { field: "countryCode" }
+          }),
+          null
+        ];
+      }
+      try {
+        await config.data.mutation(api.openfort.mutations.updateProfile, {
+          displayName: input.name,
+          username: input.username
+        });
+        const account = await config.data.query(
+          api.openfort.queries.getMyAccount,
+          {}
+        );
+        return [null, account];
+      } catch (cause) {
+        return [fromConvexError(cause), null];
+      }
+    }
   };
 }
 
@@ -1003,70 +2048,464 @@ function createPaymentsClient(config = {}) {
         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];
+            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")
+  };
+}
+function createWithdrawalsClient(config = {}) {
+  return {
+    create: async (input) => {
+      if (!config.data) {
+        return stub("withdrawals.create");
+      }
+      const [createErr, createdRaw] = await tryCatch(
+        config.data.mutation(api.withdrawals.mutations.create, {
+          amount: input.amount,
+          destination: {
+            externalAccountId: input.destination.externalAccountId
+          },
+          source: input.source,
+          reference: input.reference,
+          idempotencyKey: input.idempotencyKey
+        })
+      );
+      if (createErr) {
+        return [mapCreateError2(fromConvexError(createErr)), null];
+      }
+      const created = createdRaw;
+      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 (!config.signer || !config.signing) {
+        return [null, created];
+      }
+      const [signerErr, currentSigner] = await tryCatch(
+        config.data.query(api.safe.queries.getMySignerAddress, {})
+      );
+      if (signerErr) {
+        return await handleSubmissionFailure(
+          { data: config.data },
+          created.id,
+          mapCreateError2(fromConvexError(signerErr))
+        );
+      }
+      if (!currentSigner?.address) {
+        return await handleSubmissionFailure(
+          { data: config.data },
+          created.id,
+          new CapxulError({
+            code: "PERMISSION_DENIED",
+            message: "No signer is registered for the authenticated account.",
+            details: { withdrawalId: created.id }
+          })
+        );
+      }
+      if (viem.getAddress(currentSigner.address) !== viem.getAddress(config.signer.address)) {
+        return await handleSubmissionFailure(
+          { data: config.data },
+          created.id,
+          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 [prepErr, submission] = await tryCatch(
+        config.data.query(api.withdrawals.queries.prepareSubmission, {
+          withdrawalId: created.id
+        })
+      );
+      if (prepErr) {
+        return await handleSubmissionFailure(
+          { data: config.data },
+          created.id,
+          mapCreateError2(fromConvexError(prepErr))
+        );
+      }
+      const destinationAddress = submission?.destinationAddress;
+      if (!submission || !destinationAddress) {
+        return await handleSubmissionFailure(
+          { data: config.data },
+          created.id,
+          new CapxulError({
+            code: "NETWORK_ERROR",
+            message: "withdrawals.prepareSubmission returned no destination.",
+            details: { withdrawalId: created.id }
+          })
+        );
+      }
+      const [transferErr, transferOk] = await tryCatch(
+        transferAsOwner(
+          {
+            signer: config.signer,
+            signing: config.signing
+          },
+          {
+            tokenAddress: resolvePaymentTokenAddress(submission.amount.currency),
+            recipientAddress: destinationAddress,
+            amount: toTokenUnits(submission.amount.value, 6)
+          }
+        )
+      );
+      if (transferErr) {
+        return await handleSubmissionFailure(
+          { data: config.data },
+          created.id,
+          mapCreateError2(fromConvexError(transferErr))
+        );
+      }
+      if (!transferOk.success) {
+        return await handleSubmissionFailure(
+          { data: config.data },
+          created.id,
+          new CapxulError({
+            code: "NETWORK_ERROR",
+            message: "Bundler submission did not succeed.",
+            details: {
+              withdrawalId: created.id,
+              txHash: transferOk.txHash,
+              userOpHash: transferOk.userOpHash
+            }
+          })
+        );
+      }
+      const [recordErr] = await tryCatch(
+        config.data.mutation(api.withdrawals.mutations.recordSubmitted, {
+          withdrawalId: created.id,
+          txHash: transferOk.txHash,
+          userOpHash: transferOk.userOpHash
+        })
+      );
+      if (recordErr) {
+        return [
+          new CapxulError({
+            code: "NETWORK_ERROR",
+            message: "Withdrawal was submitted on-chain, but backend submission tracking failed.",
+            cause: recordErr,
+            details: {
+              withdrawalId: created.id,
+              txHash: transferOk.txHash,
+              userOpHash: transferOk.userOpHash
+            }
+          }),
+          null
+        ];
+      }
+      return [null, created];
+    },
+    retrieve: async (withdrawalId) => {
+      if (!config.data) {
+        return stub("withdrawals.retrieve");
+      }
+      const [err, raw] = await tryCatch(
+        config.data.query(api.withdrawals.queries.retrieve, { withdrawalId })
+      );
+      if (err) {
+        return [fromConvexError(err), null];
+      }
+      const withdrawal = raw;
+      if (!withdrawal) {
+        return [
+          new CapxulError({
+            code: "NOT_FOUND",
+            message: `withdrawal ${withdrawalId} not found`
+          }),
+          null
+        ];
+      }
+      return [null, withdrawal];
+    },
+    list: async (input) => {
+      if (!config.data) {
+        return stub("withdrawals.list");
+      }
+      const [err, raw] = await tryCatch(
+        config.data.query(api.withdrawals.queries.list, {
+          limit: input?.limit,
+          cursor: input?.cursor
+        })
+      );
+      if (err) {
+        return [fromConvexError(err), null];
+      }
+      return [null, raw];
+    },
+    recordCompleted: async (input) => {
+      if (!config.data) {
+        return stub(
+          "withdrawals.recordCompleted"
+        );
+      }
+      const [err] = await tryCatch(
+        config.data.mutation(api.withdrawals.mutations.recordCompleted, {
+          withdrawalId: input.withdrawalId,
+          txHash: input.txHash
+        })
+      );
+      if (err) {
+        return [
+          mapRecordCompletedError(fromConvexError(err)),
+          null
+        ];
+      }
+      return [null, null];
+    }
+  };
+}
+function createOrgWithdrawalsClient(config = {}) {
+  return {
+    /**
+     * Org-scope create (Withdrawals v1 W2, #465).
+     *
+     * D6 — returns the `processing` row only. No `transferAsOwner`
+     * tail, no `recordSubmitted` call. Org Safe + Zodiac submission
+     * orchestration ships in W3+.
+     */
+    create: async (input) => {
+      if (!config.data) {
+        return stub(
+          "organizations.withdrawals.create"
+        );
+      }
+      const [err, raw] = await tryCatch(
+        config.data.mutation(api.withdrawals.mutations.createOrg, {
+          organizationId: input.organizationId,
+          amount: input.amount,
+          destination: {
+            externalAccountId: input.destination.externalAccountId
+          },
+          source: input.source,
+          reference: input.reference,
+          idempotencyKey: input.idempotencyKey
+        })
+      );
+      if (err) {
+        return [mapCreateError2(fromConvexError(err)), null];
+      }
+      const created = raw;
+      if (!created) {
+        return [
+          new CapxulError({
+            code: "NETWORK_ERROR",
+            message: "organizations.withdrawals.create returned no withdrawal resource"
+          }),
+          null
+        ];
       }
+      return [null, created];
     },
-    retrieve: async (paymentId) => {
+    retrieve: async (input) => {
       if (!config.data) {
-        return stub("payments.retrieve");
+        return stub(
+          "organizations.withdrawals.retrieve"
+        );
       }
-      try {
-        const payment = await config.data.query(api.payments.queries.retrieve, {
-          paymentId
-        });
-        if (!payment) {
-          return [new CapxulError({
+      const [err, raw] = await tryCatch(
+        config.data.query(api.withdrawals.queries.retrieve, {
+          withdrawalId: input.withdrawalId
+        })
+      );
+      if (err) {
+        return [fromConvexError(err), null];
+      }
+      const withdrawal = raw;
+      if (!withdrawal) {
+        return [
+          new CapxulError({
             code: "NOT_FOUND",
-            message: `payment ${paymentId} not found`
-          }), null];
-        }
-        return [null, payment];
-      } catch (cause) {
-        return [fromConvexError(cause), null];
+            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];
     },
-    list: async () => stub("payments.list")
+    list: async (input) => {
+      if (!config.data) {
+        return stub(
+          "organizations.withdrawals.list"
+        );
+      }
+      const [err, raw] = await tryCatch(
+        config.data.query(api.withdrawals.queries.listOrg, {
+          organizationId: input.organizationId,
+          limit: input.limit,
+          cursor: input.cursor
+        })
+      );
+      if (err) {
+        return [fromConvexError(err), null];
+      }
+      return [null, raw];
+    }
   };
 }
-function createOrgPaymentsClient() {
-  return {
-    create: async () => stub(
-      "organizations.payments.create"
-    ),
-    retrieve: async () => stub("organizations.payments.retrieve"),
-    list: async () => stub("organizations.payments.list")
-  };
+async function handleSubmissionFailure(config, withdrawalId, error) {
+  await bestEffortMarkFailed2(config, withdrawalId, error);
+  return [error, null];
 }
-async function bestEffortMarkFailed(config, paymentId, error) {
-  try {
-    await config.data.mutation(api.payments.mutations.markFailed, {
-      paymentId,
+async function bestEffortMarkFailed2(config, withdrawalId, error) {
+  await tryCatch(
+    config.data.mutation(api.withdrawals.mutations.markFailed, {
+      withdrawalId,
       errorCode: error.code,
-      errorMessage: error.message,
-      source: "sdk"
-    });
-  } catch {
-  }
+      errorMessage: error.message
+    })
+  );
 }
-function mapCreateError(error) {
+function mapCreateError2(error) {
   switch (error.code) {
     case "NOT_AUTHENTICATED":
     case "PERMISSION_DENIED":
     case "INVALID_INPUT":
-    case "INVALID_RECIPIENT":
     case "INSUFFICIENT_BALANCE":
     case "IDEMPOTENCY_CONFLICT":
+    case "KYC_REQUIRED":
+    case "POLICY_DENIED":
     case "RATE_LIMITED":
     case "NETWORK_ERROR":
+    case "NOT_FOUND":
+    case "VERIFICATION_REQUIRED":
+      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
+      });
+  }
+}
+function mapRecordCompletedError(error) {
+  switch (error.code) {
+    case "NOT_AUTHENTICATED":
+    case "PERMISSION_DENIED":
+    case "INVALID_INPUT":
+    case "NOT_FOUND":
+    case "NETWORK_ERROR":
+    case "INTERNAL_ERROR":
       return error;
     default:
       return new CapxulError({
@@ -1081,508 +2520,785 @@ function mapCreateError(error) {
   }
 }
 
-// src/core/transfers.ts
-function createTransfersClient() {
+// src/core/webhook-endpoints.ts
+function createWebhookEndpointsClient() {
   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")
+    create: async () => stub(
+      "webhookEndpoints.create"
+    ),
+    retrieve: async () => stub("webhookEndpoints.retrieve"),
+    list: async () => stub("webhookEndpoints.list"),
+    remove: async () => stub("webhookEndpoints.remove")
   };
 }
-function createOrgTransfersClient() {
+
+// src/core/webhook-events.ts
+function createWebhookEventsClient() {
   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")
+    retrieve: async () => stub("webhookEvents.retrieve"),
+    list: async () => stub("webhookEvents.list")
   };
 }
-var EVM_ADDRESS_RE = /^0x[0-9a-fA-F]{40}$/;
-function createWithdrawalsClient(config = {}) {
+
+// src/core/organizations.ts
+function createOrgExternalAccountsClient(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 (viem.getAddress(currentSigner.address) !== viem.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];
+      if (!config.data) {
+        return stub(
+          "organizations.externalAccounts.create"
+        );
+      }
+      const [err, raw] = await tryCatch(
+        config.data.mutation(api.externalAccounts.mutations.createOrg, {
+          organizationId: input.organizationId,
+          kind: input.kind,
+          label: input.label,
+          address: input.address,
+          iban: input.iban,
+          bic: input.bic,
+          accountHolder: input.accountHolder,
+          network: input.network,
+          panToken: input.panToken,
+          last4: input.last4
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      if (!raw) {
+        return [
+          new CapxulError({
+            code: "NOT_FOUND",
+            message: "external_account creation returned no resource"
+          }),
+          null
+        ];
       }
+      return [
+        null,
+        brandExternalAccount(
+          raw
+        )
+      ];
     },
-    retrieve: async (withdrawalId) => {
+    list: async (input) => {
       if (!config.data) {
-        return stub("withdrawals.retrieve");
-      }
-      try {
-        const withdrawal = await config.data.query(
-          api.withdrawals.queries.retrieve,
-          { withdrawalId }
+        return stub(
+          "organizations.externalAccounts.list"
         );
-        if (!withdrawal) {
-          return [
-            new CapxulError({
-              code: "NOT_FOUND",
-              message: `withdrawal ${withdrawalId} not found`
-            }),
-            null
-          ];
+      }
+      const [err, result] = await tryCatch(
+        config.data.query(api.externalAccounts.queries.listOrg, {
+          organizationId: input.organizationId,
+          limit: input.limit,
+          cursor: input.cursor
+        })
+      );
+      if (err) {
+        return [fromConvexError(err), null];
+      }
+      const branded = result.data.map(
+        (row) => brandExternalAccount(
+          row
+        )
+      );
+      return [
+        null,
+        {
+          object: "list",
+          data: branded,
+          page: result.page
         }
-        return [null, withdrawal];
-      } catch (cause) {
+      ];
+    },
+    retrieve: async (input) => {
+      if (!config.data) {
+        return stub(
+          "organizations.externalAccounts.retrieve"
+        );
+      }
+      const [err, raw] = await tryCatch(
+        config.data.query(api.externalAccounts.queries.retrieveOrg, {
+          organizationId: input.organizationId,
+          externalAccountId: input.externalAccountId
+        })
+      );
+      if (err) {
         return [
-          fromConvexError(cause),
+          fromConvexError(err),
+          null
+        ];
+      }
+      if (!raw) {
+        return [
+          new CapxulError({
+            code: "NOT_FOUND",
+            message: `external_account ${input.externalAccountId} not found`
+          }),
           null
         ];
       }
+      return [
+        null,
+        brandExternalAccount(
+          raw
+        )
+      ];
     },
-    list: async (input) => {
+    remove: 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 stub(
+          "organizations.externalAccounts.remove"
         );
-        return [null, result];
-      } catch (cause) {
+      }
+      const [err] = await tryCatch(
+        config.data.mutation(api.externalAccounts.mutations.removeOrg, {
+          organizationId: input.organizationId,
+          externalAccountId: input.externalAccountId
+        })
+      );
+      if (err) {
         return [
-          fromConvexError(cause),
+          fromConvexError(err),
           null
         ];
       }
+      return [null, void 0];
     }
   };
 }
-function createOrgWithdrawalsClient(config = {}) {
+function createOrgSubAccountsClient(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"
-    ),
+    create: async (input) => {
+      if (!config.data) {
+        return stub(
+          "organizations.subAccounts.create"
+        );
+      }
+      const [err, raw] = await tryCatch(
+        config.data.mutation(api.subAccounts.mutations.create, {
+          parent: {
+            kind: "organization",
+            id: input.organizationId
+          },
+          name: input.name,
+          purpose: input.purpose
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      if (!raw) {
+        return [
+          new CapxulError({
+            code: "NOT_FOUND",
+            message: "sub_account creation returned no resource"
+          }),
+          null
+        ];
+      }
+      const [brandErr, branded] = tryBrandSubAccount(raw);
+      if (brandErr) {
+        return [
+          brandErr,
+          null
+        ];
+      }
+      return [null, branded];
+    },
+    list: async (input) => {
+      if (!config.data) {
+        return stub(
+          "organizations.subAccounts.list"
+        );
+      }
+      const [err, rows] = await tryCatch(
+        config.data.query(api.subAccounts.queries.listByOrganization, {
+          organizationId: input.organizationId
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      const branded = [];
+      for (const row of rows) {
+        const [brandErr, value] = tryBrandSubAccount(row);
+        if (brandErr) {
+          return [
+            brandErr,
+            null
+          ];
+        }
+        branded.push(value);
+      }
+      return [
+        null,
+        {
+          object: "list",
+          data: branded,
+          page: { hasMore: false }
+        }
+      ];
+    },
     retrieve: async (input) => {
       if (!config.data) {
         return stub(
-          "organizations.withdrawals.retrieve"
+          "organizations.subAccounts.retrieve"
         );
       }
-      try {
-        const withdrawal = await config.data.query(
-          api.withdrawals.queries.retrieve,
-          { withdrawalId: input.withdrawalId }
+      const [err, raw] = await tryCatch(
+        config.data.query(api.subAccounts.queries.retrieve, {
+          subAccountId: input.subAccountId
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      if (!raw) {
+        return [
+          new CapxulError({
+            code: "NOT_FOUND",
+            message: `sub_account ${input.subAccountId} not found`
+          }),
+          null
+        ];
+      }
+      const [brandErr, branded] = tryBrandSubAccount(raw);
+      if (brandErr) {
+        return [
+          brandErr,
+          null
+        ];
+      }
+      return [null, branded];
+    },
+    remove: async (input) => {
+      if (!config.data) {
+        return stub(
+          "organizations.subAccounts.remove"
         );
-        if (!withdrawal) {
+      }
+      const [err, raw] = await tryCatch(
+        config.data.mutation(api.subAccounts.mutations.archive, {
+          subAccountId: input.subAccountId
+        })
+      );
+      if (err) {
+        return [
+          fromConvexError(err),
+          null
+        ];
+      }
+      if (!raw) {
+        return [
+          new CapxulError({
+            code: "NOT_FOUND",
+            message: `sub_account ${input.subAccountId} not found`
+          }),
+          null
+        ];
+      }
+      const [brandErr, branded] = tryBrandSubAccount(raw);
+      if (brandErr) {
+        return [
+          brandErr,
+          null
+        ];
+      }
+      return [null, branded];
+    }
+  };
+}
+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 [
-            new CapxulError({
-              code: "NOT_FOUND",
-              message: `withdrawal ${input.withdrawalId} not found`
-            }),
+            fromConvexError(cause),
             null
           ];
         }
-        const ownerCheck = withdrawal.owner;
-        if (ownerCheck?.type !== "organization" || ownerCheck.id !== input.organizationId) {
+      }
+    },
+    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: createOrgSubAccountsClient(config),
+    externalAccounts: createOrgExternalAccountsClient(config),
+    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/token-transfers.ts
+var toTokenTransferId = (raw) => {
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error(
+      `Invalid tokenTransferId: expected non-empty string, got ${String(raw)}`
+    );
+  }
+  return raw;
+};
+function brandRow(row) {
+  return {
+    ...row,
+    id: toTokenTransferId(row.id)
+  };
+}
+function createTokenTransfersClient(config = {}) {
+  return {
+    list: async (input) => {
+      if (!config.data) {
+        return stub("tokenTransfers.list");
+      }
+      try {
+        const raw = await config.data.query(
+          api.tokenTransfers.queries.list,
+          {
+            limit: input?.limit,
+            cursor: input?.cursor,
+            direction: input?.direction
+          }
+        );
+        if (!raw) {
           return [
             new CapxulError({
-              code: "NOT_FOUND",
-              message: `withdrawal ${input.withdrawalId} does not belong to organization ${input.organizationId}`
+              code: "NOT_AUTHENTICATED",
+              message: "tokenTransfers.list requires an authenticated session."
             }),
             null
           ];
         }
-        return [null, withdrawal];
-      } catch (cause) {
         return [
-          fromConvexError(cause),
-          null
+          null,
+          {
+            object: "list",
+            data: raw.items.map(brandRow),
+            page: {
+              hasMore: raw.hasMore,
+              nextCursor: raw.nextCursor
+            },
+            displayCurrency: raw.displayCurrency
+          }
         ];
+      } catch (cause) {
+        return [fromConvexError(cause), null];
       }
     },
-    list: async (input) => {
-      if (!config.data) {
-        return stub(
-          "organizations.withdrawals.list"
-        );
+    retrieve: async (input) => {
+      if (!config.data) {
+        return stub("tokenTransfers.retrieve");
       }
       try {
-        const result = await config.data.query(
-          api.withdrawals.queries.listOrg,
+        const raw = await config.data.query(
+          api.tokenTransfers.queries.getByTxLogIndex,
           {
-            organizationId: input.organizationId,
-            limit: input.limit,
-            cursor: input.cursor
+            txHash: input.txHash,
+            logIndex: input.logIndex,
+            chainId: input.chainId
           }
         );
-        return [null, result];
+        if (!raw) {
+          return [
+            new CapxulError({
+              code: "NOT_FOUND",
+              message: `tokenTransfer (txHash=${input.txHash}, logIndex=${input.logIndex}) not found or not visible to caller.`,
+              details: {
+                txHash: input.txHash,
+                logIndex: input.logIndex,
+                chainId: input.chainId
+              }
+            }),
+            null
+          ];
+        }
+        return [null, brandRow(raw)];
       } catch (cause) {
-        return [
-          fromConvexError(cause),
-          null
-        ];
+        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() {
+// src/core/virtual-accounts.ts
+function createVirtualAccountsClient() {
   return {
-    create: async () => stub(
-      "webhookEndpoints.create"
-    ),
-    retrieve: async () => stub("webhookEndpoints.retrieve"),
-    list: async () => stub("webhookEndpoints.list"),
-    remove: async () => stub("webhookEndpoints.remove")
+    create: async () => stub("virtualAccounts.create"),
+    retrieve: async () => stub("virtualAccounts.retrieve"),
+    list: async () => stub("virtualAccounts.list"),
+    remove: async () => stub("virtualAccounts.remove")
   };
 }
 
-// src/core/webhook-events.ts
-function createWebhookEventsClient() {
+// src/core/virtual-cards.ts
+function createVirtualCardsClient() {
   return {
-    retrieve: async () => stub("webhookEvents.retrieve"),
-    list: async () => stub("webhookEvents.list")
+    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")
   };
 }
-
-// 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");
+function createAuthFlowMachine(client) {
+  return xstate.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: xstate.fromPromise(async ({ input, signal }) => {
+        const [error] = await client.auth.sendOtp(
+          { email: input.email },
+          { signal }
+        );
+        if (error) throw error;
+      }),
+      verifyOtp: xstate.fromPromise(
+        async ({ input, signal }) => {
+          const [error, result] = await client.auth.verifyOtp(
+            {
+              email: input.email,
+              otp: input.code
+            },
+            { signal }
+          );
+          if (error) throw error;
+          if (result.kind === "bootstrap_required") {
+            throw new CapxulError({
+              code: "ACTION_REQUIRED",
+              message: "OTP verified but auth bootstrap is required. Use createAuthBootstrapFlowMachine for product sign-up.",
+              details: { reason: result.reason }
+            });
+          }
+          return result.session;
+        }
+      ),
+      signOut: xstate.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: xstate.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: [
+              xstate.assign({ error: ({ event }) => errorFromEvent(event) }),
+              "trackOtpFailed"
+            ]
+          }
+        },
+        after: {
+          [FLOW_INVOKE_TIMEOUT_MS]: {
+            target: "error",
+            actions: [
+              xstate.assign({
+                error: () => timeoutError("sending_otp")
+              }),
+              "trackTimeoutFailed"
+            ]
+          }
+        }
+      },
+      otp_requested: {
+        on: {
+          VERIFY: { target: "verifying" },
+          RESET: {
+            target: "idle",
+            actions: xstate.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.
+              xstate.assign({
+                session: ({ event }) => event.output,
+                email: () => null
+              }),
+              "trackVerified",
+              "identifyAndTrack"
+            ]
+          },
+          onError: {
+            target: "error",
+            actions: [
+              xstate.assign({ error: ({ event }) => errorFromEvent(event) }),
+              "trackOtpFailed"
+            ]
+          }
+        },
+        after: {
+          [FLOW_INVOKE_TIMEOUT_MS]: {
+            target: "error",
+            actions: [
+              xstate.assign({
+                error: () => timeoutError("verifying")
+              }),
+              "trackTimeoutFailed"
+            ]
+          }
+        }
+      },
+      authenticated: {
+        on: {
+          SIGN_OUT: { target: "signing_out" }
         }
-        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`
+      },
+      signing_out: {
+        invoke: {
+          src: "signOut",
+          onDone: {
+            target: "idle",
+            actions: [
+              xstate.assign({
+                session: () => null,
+                email: () => null,
+                error: () => null
               }),
-              null
-            ];
+              "trackSignedOut"
+            ]
+          },
+          onError: {
+            target: "error",
+            actions: xstate.assign({ error: ({ event }) => errorFromEvent(event) })
+          }
+        }
+      },
+      error: {
+        on: {
+          RESET: {
+            target: "idle",
+            actions: xstate.assign({ error: () => 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;
+function requireEmail(context) {
+  if (!context.email) {
+    throw Errors.invalidInput(
+      "email",
+      "Auth flow advanced without an email captured in context."
+    );
   }
-  return process.env?.NODE_ENV === "development" || process.env?.NODE_ENV === "test";
+  return context.email;
 }
-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 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 formatDebugValue(value) {
-  if (value === void 0 || value === "") return "";
-  if (typeof value === "string") return value;
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return String(value);
+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));
 }
-function track(...args) {
-  const [name, props] = args;
-  debugLog(`[TRACK] ${name} ${formatDebugValue(props ?? "")}`);
+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 formatDebugValue2(value) {
-  if (value === void 0 || value === "") return "";
-  if (typeof value === "string") return value;
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return String(value);
+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 identify(userId, traits) {
-  debugLog(`[IDENTIFY] ${userId} ${formatDebugValue2(traits ?? "")}`);
+function timeoutError(state) {
+  return Errors.providerError(
+    "auth",
+    "flow",
+    new Error(`timeout: ${state} exceeded ${FLOW_INVOKE_TIMEOUT_MS}ms`)
+  );
 }
-function createAuthFlowMachine(client) {
+function emailDomain(email) {
+  const domain = email.split("@")[1]?.trim().toLowerCase();
+  return domain || "unknown";
+}
+var initialContext = {
+  email: null,
+  code: null,
+  username: null,
+  signerProvider: null,
+  bootstrapToken: null,
+  bootstrapReason: null,
+  session: null,
+  account: null,
+  safe: null,
+  error: null
+};
+function createAuthBootstrapFlowMachine(client) {
   return xstate.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: xstate.fromPromise(async ({ input, signal }) => {
         const [error] = await client.auth.sendOtp(
           { email: input.email },
@@ -1592,17 +3308,19 @@ function createAuthFlowMachine(client) {
       }),
       verifyOtp: xstate.fromPromise(
         async ({ input, signal }) => {
-          const [error, session] = await client.auth.verifyOtp(
-            {
-              email: input.email,
-              otp: input.code
-            },
+          const [error, result] = await client.auth.verifyOtp(
+            { email: input.email, otp: input.code },
             { signal }
           );
           if (error) throw error;
-          return session;
+          return result;
         }
       ),
+      completeBootstrap: xstate.fromPromise(async ({ input }) => {
+        const [error, result] = await client.auth.completeBootstrap(input);
+        if (error) throw error;
+        return result;
+      }),
       signOut: xstate.fromPromise(async () => {
         const [error] = await client.auth.signOut();
         if (error) throw error;
@@ -1612,14 +3330,13 @@ function createAuthFlowMachine(client) {
       trackOtpRequested: ({ context }) => {
         if (!context.email) return;
         track("auth_otp_requested", {
-          email_domain: emailDomain(context.email)
+          email_domain: emailDomain2(context.email)
         });
       },
-      trackOtpFailed: ({ event }) => {
-        const error = errorFromEvent(event);
+      trackFailed: ({ event }) => {
         track("auth_failed", {
           auth_type: "email_otp",
-          reason: error.code
+          reason: errorFromEvent2(event).code
         });
       },
       trackTimeoutFailed: () => {
@@ -1631,13 +3348,19 @@ function createAuthFlowMachine(client) {
       trackVerified: () => {
         track("auth_verified", { auth_type: "email_otp" });
       },
+      trackBootstrapRequired: ({ context }) => {
+        track("auth_verified", {
+          auth_type: "email_otp",
+          auth_mode: context.bootstrapReason ?? "bootstrap_required"
+        });
+      },
       identifyAndTrack: ({ context }) => {
         if (!context.session) return;
         identify(context.session.authUserId, {
-          email_domain: emailDomain(context.session.email)
+          email_domain: emailDomain2(context.session.email)
         });
         track("auth_identified", {
-          email_domain: emailDomain(context.session.email)
+          email_domain: emailDomain2(context.session.email)
         });
       },
       trackSignedOut: () => {
@@ -1645,97 +3368,172 @@ function createAuthFlowMachine(client) {
       }
     }
   }).createMachine({
-    id: "auth",
-    initial: "idle",
-    context: { email: null, session: null, error: null },
+    id: "authBootstrap",
+    initial: "email",
+    context: initialContext,
     states: {
-      idle: {
+      email: {
         on: {
-          REQUEST_OTP: {
-            target: "sending_otp",
+          ENTER_EMAIL: {
             actions: xstate.assign({
               email: ({ event }) => event.email,
               error: () => null
             })
-          }
+          },
+          REQUEST_OTP: { target: "sending_otp" }
         }
       },
       sending_otp: {
         invoke: {
           src: "sendOtp",
-          input: ({ context }) => ({ email: requireEmail(context) }),
-          onDone: {
+          input: ({ context }) => ({ email: requireEmail2(context) }),
+          onDone: { target: "otp_requested", actions: "trackOtpRequested" },
+          onError: {
             target: "otp_requested",
-            actions: ["trackOtpRequested"]
+            actions: [
+              xstate.assign({ error: ({ event }) => errorFromEvent2(event) }),
+              "trackFailed"
+            ]
+          }
+        },
+        after: {
+          [FLOW_INVOKE_TIMEOUT_MS]: {
+            target: "otp_requested",
+            actions: [
+              xstate.assign({ error: () => timeoutError2("sending_otp") }),
+              "trackTimeoutFailed"
+            ]
+          }
+        }
+      },
+      otp_requested: {
+        on: {
+          ENTER_OTP: {
+            actions: xstate.assign({
+              code: ({ event }) => event.code,
+              error: () => null
+            })
           },
+          VERIFY_OTP: { target: "verifying_otp" },
+          BACK: { target: "email" },
+          RESET: { target: "email", actions: xstate.assign(() => initialContext) }
+        }
+      },
+      verifying_otp: {
+        invoke: {
+          src: "verifyOtp",
+          input: ({ context }) => ({
+            email: requireEmail2(context),
+            code: requireCode(context)
+          }),
+          onDone: [
+            {
+              guard: ({ event }) => event.output.kind === "existing_member",
+              target: "authenticated",
+              actions: [
+                xstate.assign({
+                  session: ({ event }) => event.output.session,
+                  account: ({ event }) => event.output.kind === "existing_member" ? event.output.account : null,
+                  username: ({ event }) => event.output.kind === "existing_member" ? event.output.username : null,
+                  safe: ({ event }) => event.output.kind === "existing_member" ? event.output.safe : null,
+                  email: () => null,
+                  error: () => null
+                }),
+                "trackVerified",
+                "identifyAndTrack"
+              ]
+            },
+            {
+              target: "bootstrap_required",
+              actions: [
+                xstate.assign({
+                  session: ({ event }) => event.output.session,
+                  bootstrapToken: ({ event }) => event.output.kind === "bootstrap_required" ? event.output.bootstrapToken : null,
+                  bootstrapReason: ({ event }) => event.output.kind === "bootstrap_required" ? event.output.reason : null,
+                  username: ({ event }) => event.output.kind === "bootstrap_required" ? event.output.username ?? null : null,
+                  email: ({ event }) => event.output.kind === "bootstrap_required" ? event.output.email : null,
+                  error: () => null
+                }),
+                "trackVerified",
+                "trackBootstrapRequired"
+              ]
+            }
+          ],
           onError: {
-            target: "error",
+            target: "otp_requested",
             actions: [
-              xstate.assign({ error: ({ event }) => errorFromEvent(event) }),
-              "trackOtpFailed"
+              xstate.assign({ error: ({ event }) => errorFromEvent2(event) }),
+              "trackFailed"
             ]
           }
         },
         after: {
           [FLOW_INVOKE_TIMEOUT_MS]: {
-            target: "error",
+            target: "otp_requested",
             actions: [
-              xstate.assign({
-                error: () => timeoutError("sending_otp")
-              }),
+              xstate.assign({ error: () => timeoutError2("verifying_otp") }),
               "trackTimeoutFailed"
             ]
           }
         }
       },
-      otp_requested: {
+      bootstrap_required: {
         on: {
-          VERIFY: { target: "verifying" },
-          RESET: {
-            target: "idle",
-            actions: xstate.assign({ email: () => null, error: () => null })
-          }
+          ENTER_USERNAME: {
+            actions: xstate.assign({
+              username: ({ event }) => event.username,
+              error: () => null
+            })
+          },
+          ENTER_SIGNER_PROVIDER: {
+            actions: xstate.assign({
+              signerProvider: ({ event }) => event.signerProvider,
+              error: () => null
+            })
+          },
+          COMPLETE_BOOTSTRAP: { target: "completing_bootstrap" },
+          BACK: { target: "otp_requested" },
+          RESET: { target: "email", actions: xstate.assign(() => initialContext) }
         }
       },
-      verifying: {
+      completing_bootstrap: {
         invoke: {
-          src: "verifyOtp",
-          input: ({ context, event }) => ({
-            email: requireEmail(context),
-            code: requireCodeFromEvent(event)
+          src: "completeBootstrap",
+          input: ({ context }) => ({
+            bootstrapToken: requireBootstrapToken(context),
+            username: requireUsername(context),
+            signerProvider: requireSignerProvider(context)
           }),
           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.
               xstate.assign({
-                session: ({ event }) => event.output,
-                email: () => null
+                session: ({ event }) => event.output.session,
+                account: ({ event }) => event.output.account,
+                username: ({ event }) => event.output.username,
+                safe: ({ event }) => event.output.safe,
+                bootstrapToken: () => null,
+                bootstrapReason: () => null,
+                signerProvider: () => null,
+                email: () => null,
+                error: () => null
               }),
-              "trackVerified",
               "identifyAndTrack"
             ]
           },
           onError: {
-            target: "error",
+            target: "bootstrap_required",
             actions: [
-              xstate.assign({ error: ({ event }) => errorFromEvent(event) }),
-              "trackOtpFailed"
+              xstate.assign({ error: ({ event }) => errorFromEvent2(event) }),
+              "trackFailed"
             ]
           }
         },
         after: {
           [FLOW_INVOKE_TIMEOUT_MS]: {
-            target: "error",
+            target: "bootstrap_required",
             actions: [
-              xstate.assign({
-                error: () => timeoutError("verifying")
-              }),
+              xstate.assign({ error: () => timeoutError2("completing_bootstrap") }),
               "trackTimeoutFailed"
             ]
           }
@@ -1750,220 +3548,80 @@ function createAuthFlowMachine(client) {
         invoke: {
           src: "signOut",
           onDone: {
-            target: "idle",
+            target: "email",
             actions: [
-              xstate.assign({
-                session: () => null,
-                email: () => null,
-                error: () => null
-              }),
+              xstate.assign(() => initialContext),
               "trackSignedOut"
             ]
           },
           onError: {
             target: "error",
-            actions: xstate.assign({ error: ({ event }) => errorFromEvent(event) })
+            actions: xstate.assign({ error: ({ event }) => errorFromEvent2(event) })
           }
         }
       },
       error: {
         on: {
-          RESET: {
-            target: "idle",
-            actions: xstate.assign({ error: () => null })
-          }
+          RESET: { target: "email", actions: xstate.assign(() => initialContext) }
         }
       }
     }
   });
 }
-function requireEmail(context) {
+function requireEmail2(context) {
   if (!context.email) {
-    throw Errors.invalidInput(
-      "email",
-      "Auth flow advanced without an email captured in context."
-    );
+    throw Errors.invalidInput("email", "Auth bootstrap requires an email.");
   }
   return context.email;
 }
-function requireCodeFromEvent(event) {
-  if (event.type !== "VERIFY") {
+function requireCode(context) {
+  if (!context.code) {
+    throw Errors.invalidInput("code", "Auth bootstrap requires an OTP code.");
+  }
+  return context.code;
+}
+function requireBootstrapToken(context) {
+  if (!context.bootstrapToken) {
     throw Errors.invalidInput(
-      "code",
-      `Auth flow's verifying state requires a VERIFY event, got ${event.type}.`
+      "bootstrapToken",
+      "Auth bootstrap requires a continuation token."
     );
   }
-  return event.code;
+  return context.bootstrapToken;
 }
-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
-    });
+function requireUsername(context) {
+  if (!context.username) {
+    throw Errors.invalidInput("username", "Auth bootstrap requires a username.");
   }
-  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>");
+  return context.username;
 }
-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;
+function requireSignerProvider(context) {
+  if (!context.signerProvider) {
+    throw Errors.invalidInput(
+      "signerProvider",
+      "Auth bootstrap requires a signer provider."
+    );
   }
-  if (typeof cause === "string") {
-    return redactEmail(cause);
+  return context.signerProvider;
+}
+function errorFromEvent2(event) {
+  const cause = typeof event === "object" && event !== null && "error" in event ? event.error : event;
+  if (cause instanceof CapxulError || cause instanceof CapxulError2) {
+    return cause;
   }
-  return cause;
+  return Errors.providerError("auth", "bootstrap", cause);
 }
-function timeoutError(state) {
+function timeoutError2(state) {
   return Errors.providerError(
     "auth",
-    "flow",
+    "bootstrap",
     new Error(`timeout: ${state} exceeded ${FLOW_INVOKE_TIMEOUT_MS}ms`)
   );
 }
-function emailDomain(email) {
+function emailDomain2(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 toAccountId = makePrefixedIdConstructor(
-  "acct",
-  "accountId"
-);
-var toOrganizationId = makePrefixedIdConstructor("org", "organizationId");
-var toMemberId = makePrefixedIdConstructor(
-  "mem",
-  "memberId"
-);
-var toSafeId = makePrefixedIdConstructor(
-  "safe",
-  "safeId"
-);
-var toTreasuryId = makePrefixedIdConstructor(
-  "try",
-  "treasuryId"
-);
-var toApiKeyId = makePrefixedIdConstructor(
-  "ak",
-  "apiKeyId"
-);
-var toOperationId = makePrefixedIdConstructor(
-  "op",
-  "operationId"
-);
-var toKycProfileId = makePrefixedIdConstructor(
-  "kyc",
-  "kycProfileId"
-);
-var toKybProfileId = makePrefixedIdConstructor(
-  "kyb",
-  "kybProfileId"
-);
-var toExternalAccountId = makePrefixedIdConstructor("ext", "externalAccountId");
-var toPaymentId = makePrefixedIdConstructor(
-  "pay",
-  "paymentId"
-);
-var toWithdrawalId = makePrefixedIdConstructor(
-  "wd",
-  "withdrawalId"
-);
-var toWebhookEndpointId = makePrefixedIdConstructor("we", "webhookEndpointId");
-var toWebhookEventId = makePrefixedIdConstructor("evt", "webhookEventId");
-var toSubAccountId = makePrefixedIdConstructor(
-  "sub",
-  "subAccountId"
-);
-var toVirtualAccountId = makePrefixedIdConstructor("va", "virtualAccountId");
-var toVirtualCardId = makePrefixedIdConstructor(
-  "vc",
-  "virtualCardId"
-);
-var toTransferId = makePrefixedIdConstructor(
-  "txfr",
-  "transferId"
-);
-var toDocumentId = makePrefixedIdConstructor(
-  "doc",
-  "documentId"
-);
-var toBalanceLedgerEntryId = makePrefixedIdConstructor("bal", "balanceLedgerEntryId");
-
-// ../platform-kernel/src/value-objects.ts
-var PHONE_NUMBER_RE = /^\+[1-9]\d{1,14}$/;
-function toPhoneNumber(raw) {
-  if (typeof raw !== "string" || !PHONE_NUMBER_RE.test(raw)) {
-    throw new Error(
-      `Invalid phoneNumber: expected E.164 string matching ^\\+[1-9]\\d{1,14}$, got ${String(raw)}`
-    );
-  }
-  return raw;
-}
-var EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-function toEmail(raw) {
-  if (typeof raw !== "string") {
-    throw new Error(
-      `Invalid email: expected string, got ${String(raw)}`
-    );
-  }
-  const lowered = raw.trim().toLowerCase();
-  if (!EMAIL_RE.test(lowered)) {
-    throw new Error(
-      `Invalid email: expected local@domain.tld, got ${String(raw)}`
-    );
-  }
-  return lowered;
-}
-var USERNAME_RE = /^[a-z][a-z0-9_-]{2,29}$/;
-function toUsername(raw) {
-  if (typeof raw !== "string") {
-    throw new Error(
-      `Invalid username: expected string, got ${String(raw)}`
-    );
-  }
-  const lowered = raw.toLowerCase();
-  if (!USERNAME_RE.test(lowered)) {
-    throw new Error(
-      `Invalid username: expected 3-30 chars, letter-first, [a-z0-9_-], got ${String(raw)}`
-    );
-  }
-  return lowered;
-}
 function createProvisioningMachine(client) {
   return xstate.setup({
     types: {},
@@ -2036,13 +3694,13 @@ function createProvisioningMachine(client) {
           },
           onError: {
             target: "error",
-            actions: xstate.assign({ error: ({ event }) => errorFromEvent2(event) })
+            actions: xstate.assign({ error: ({ event }) => errorFromEvent3(event) })
           }
         },
         after: {
           [FLOW_INVOKE_TIMEOUT_MS]: {
             target: "error",
-            actions: xstate.assign({ error: () => timeoutError2() })
+            actions: xstate.assign({ error: () => timeoutError3() })
           }
         }
       },
@@ -2060,7 +3718,7 @@ function createProvisioningMachine(client) {
      * 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() }
+    output: ({ context }) => context.error ? { error: context.error } : context.account ? { account: context.account } : { error: timeoutError3() }
   });
 }
 function requireProvisionInput(context) {
@@ -2072,13 +3730,13 @@ function requireProvisionInput(context) {
   }
   return context.input;
 }
-function errorFromEvent2(event) {
+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("provisioning", "flow", cause);
 }
-function timeoutError2() {
+function timeoutError3() {
   return Errors.providerError(
     "provisioning",
     "flow",
@@ -2171,7 +3829,7 @@ function createOnboardingFlowMachine(client) {
         error: ({ event }) => extractChildErrorOrFallback(event)
       }),
       assignChildThrown: xstate.assign({
-        error: ({ event }) => errorFromEvent3(event)
+        error: ({ event }) => errorFromEvent4(event)
       }),
       assignAccountFromChild: xstate.assign({
         account: ({ event }) => extractChildAccountOrNull(event)
@@ -2333,7 +3991,7 @@ function extractChildAccountOrNull(event) {
   if (output && "account" in output && output.account) return output.account;
   return null;
 }
-function errorFromEvent3(event) {
+function errorFromEvent4(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;
@@ -2350,12 +4008,13 @@ function createCapxulClient(config = {}) {
     organizations: createOrganizationsClient(config),
     payments: createPaymentsClient(config),
     transfers: createTransfersClient(),
+    tokenTransfers: createTokenTransfersClient(config),
     withdrawals: createWithdrawalsClient(config),
     documents: createDocumentsClient(),
-    subAccounts: createSubAccountsClient(),
+    subAccounts: createSubAccountsClient(config),
     virtualAccounts: createVirtualAccountsClient(),
     virtualCards: createVirtualCardsClient(),
-    externalAccounts: createExternalAccountsClient(),
+    externalAccounts: createExternalAccountsClient(config),
     operations: createOperationsClient(config),
     webhookEndpoints: createWebhookEndpointsClient(),
     webhookEvents: createWebhookEventsClient(),
@@ -2364,6 +4023,7 @@ function createCapxulClient(config = {}) {
   const client = clientWithoutFlows;
   client.flows = {
     auth: () => createAuthFlowMachine(client),
+    authBootstrap: () => createAuthBootstrapFlowMachine(client),
     onboarding: () => createOnboardingFlowMachine(client),
     provisioning: () => createProvisioningMachine(client)
   };
@@ -2469,6 +4129,7 @@ function isWebhookEvent(value) {
 }
 
 exports.CapxulError = CapxulError;
+exports.createAuthBootstrapFlowMachine = createAuthBootstrapFlowMachine;
 exports.createAuthFlowMachine = createAuthFlowMachine;
 exports.createCapxulClient = createCapxulClient;
 exports.createLocalSigner = createLocalSigner;
@@ -2493,6 +4154,7 @@ exports.toPaymentId = toPaymentId;
 exports.toPhoneNumber = toPhoneNumber;
 exports.toSafeId = toSafeId;
 exports.toSubAccountId = toSubAccountId;
+exports.toTokenTransferId = toTokenTransferId;
 exports.toTransferId = toTransferId;
 exports.toTreasuryId = toTreasuryId;
 exports.toUsername = toUsername;
@@ -2501,4 +4163,5 @@ exports.toVirtualCardId = toVirtualCardId;
 exports.toWebhookEndpointId = toWebhookEndpointId;
 exports.toWebhookEventId = toWebhookEventId;
 exports.toWithdrawalId = toWithdrawalId;
+exports.tryCatch = tryCatch;
 exports.verifyWebhook = verifyWebhook;