@capxul/sdk 0.1.0-alpha.6 → 0.1.0-alpha.8

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # @capxul/sdk
 
-## 0.1.0-alpha.6
+## 0.1.0-alpha.8
 
 ### Minor Changes
 
@@ -21,13 +21,6 @@
   `capxul.withdrawals.create({ destination: { kind, externalAccountId } })`
   call sites. Pass only `externalAccountId`.
 
-## 0.1.0-alpha.5
-
-### Patch Changes
-
-- Version sync with `@capxul/sdk-react@0.1.0-alpha.5`; no headless SDK runtime
-  changes.
-
 ## 0.1.0-alpha.4
 
 ### Minor Changes

package/README.md

@@ -19,9 +19,9 @@ pnpm add @capxul/sdk @capxul/sdk-react
 React-flavored entry point lives in `@capxul/sdk-react`. Pick:
 
 - **Browser apps (recommended).** Install both. Use
-  `<CapxulProvider publishableKey="cap_pk_…">` from `@capxul/sdk-react`
-  and the `useMe` / `useCapxulStatus` hooks. See that package's
-  README for the lazy-DX example.
+  `<CapxulProvider config={{ mode: "publishable-key", publishableKey }}>`
+  from `@capxul/sdk-react` and the `useMe` / `useCapxulStatus` hooks.
+  See that package's README for the lazy-DX example.
 - **Server / CLI / scripts.** Install only `@capxul/sdk`. Build a
   `CapxulClient` directly with your own auth and Convex adapters
   (see "Server-side construction" below).
@@ -76,11 +76,93 @@ runtime URLs lazily — no need to ship secrets to the client:
 ```tsx
 import { CapxulProvider, useMe, useCapxulStatus } from "@capxul/sdk-react";
 
-<CapxulProvider publishableKey="cap_pk_live_…">
+<CapxulProvider
+  config={{
+    mode: "publishable-key",
+    publishableKey: process.env.NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY!,
+  }}
+>
   <App />
 </CapxulProvider>;
 ```
 
+## Publishable-key transport
+
+The browser transport accepts a publishable key, then lazily resolves
+runtime URLs by POSTing to `/v1/client/bootstrap` on the first auth or
+`ensureRuntime()` call. The successful backend response is intentionally
+small:
+
+```json
+{ "authBaseUrl": "https://<deployment>.convex.site/api/auth", "convexUrl": "https://<deployment>.convex.cloud" }
+```
+
+The resolved runtime is cached for the lifetime of the transport. Concurrent
+callers share one bootstrap request, successful resolutions are reused, and
+failed bootstrap attempts reset so the next call can retry. Tests and
+non-default deployments can inject both `fetchImpl` and an absolute
+`bootstrapUrl`:
+
+```ts
+import { makeHttpTransport, CapxulError } from "@capxul/sdk";
+
+const transport = makeHttpTransport({
+  mode: "publishable-key",
+  publishableKey: process.env.NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY!,
+  bootstrapUrl: "https://api.capxul.com/v1/client/bootstrap",
+  fetchImpl: fetch,
+});
+
+await transport.ensureRuntime();
+```
+
+Local setup errors and backend bootstrap errors both use `CapxulError`, but
+carry different `details.source` values:
+
+```ts
+try {
+  await transport.ensureRuntime();
+} catch (error) {
+  if (error instanceof CapxulError) {
+    if (error.details?.source === "sdk-config") {
+      // Missing or malformed local config, such as publishableKey or bootstrapUrl.
+    }
+    if (error.details?.source === "backend-bootstrap") {
+      // Sanitized backend refusal, such as NOT_AUTHENTICATED or PERMISSION_DENIED.
+    }
+  }
+}
+```
+
+Runtime proof status:
+
+| Surface | Source support | Runtime proof | Status |
+|---|---|---|---|
+| SDK transport | `makeHttpTransport({ mode: "publishable-key", publishableKey })` | `packages/sdk/tests/unit/transport.test.ts` proves config validation, singleflight bootstrap, retry after failure, lifecycle transitions, and sanitized backend errors. | Proven with mocked fetch |
+| React provider | `CapxulProvider config={{ mode: "publishable-key", ... }}` | `packages/sdk-react/ops/proof/react-headless.test.tsx` proves bootstrap before a real `useMe()` read through the provider and lazy Convex data client. | Proven with mocked fetch + headless React |
+| Reference CLI | `bootstrap probe --mock --json` | `apps/reference-cli/scripts/agent-driver.ts` phase 0 and the direct CLI command prove provider/bootstrap/auth ordering and sanitized output. | Proven locally; live endpoint remains manual-key gated |
+
+Copy-paste local replication:
+
+```bash
+corepack pnpm --filter @capxul/sdk check-types
+corepack pnpm --filter @capxul/sdk build
+corepack pnpm --filter @capxul/sdk-react check-types
+corepack pnpm --filter @capxul/sdk-react build
+corepack pnpm --filter @capxul/reference-cli check-types
+corepack pnpm --filter @capxul/reference-cli build
+node apps/reference-cli/dist/cli.js bootstrap probe --mock --json
+```
+
+Run the SDK and React SDK builds before the reference CLI typecheck in a
+fresh checkout; the CLI depends on their generated declaration outputs.
+
+Expected sanitized pass signal:
+
+```json
+{"command":"bootstrap.probe","ok":true,"mode":"publishable-key","status":"ready","bootstrapRequests":1,"authRequests":1,"keyLengthClass":"provided","mocked":true}
+```
+
 ## Public surface (alpha)
 
 ```ts

package/dist/{client-ChfXWMzO.d.ts → client-ByzDfG98.d.ts}

@@ -2,8 +2,7 @@ import { Account as Account$1 } from 'viem';
 import { AnyStateMachine } from 'xstate';
 import { A as AccountId, S as SafeId, c as KycProfileId, b as ExternalAccountId, f as SubAccountId, d as OrganizationId, a as ApiKeyId, X as TimestampIso, D as DocumentId, O as OperationId, P as PaymentId, g as TransferId, k as WithdrawalId, W as WebhookEndpointId, j as WebhookEventId, M as MemberId, K as KybProfileId, V as VirtualAccountId, i as VirtualCardId } from './next-action-DkrwXYay.js';
 import { d as CapxulResult, C as CapxulError } from './errors-QHD5Tlok.js';
-import { A as Account, U as UserIdentifier, a as AccountLookupResult, S as Safe, i as KycProfile, E as ExternalAccount, L as List, v as SubAccount, B as BalanceLedgerEntry, b as ApiKey, D as Document, O as Operation, l as OperationStatus, k as Money, C as CreatePaymentResult, o as Payment, F as TransferEndpoint, f as CreateTransferResult, y as Transfer, g as CreateWithdrawalResult, _ as Withdrawal, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, V as VirtualAccount, Q as VirtualCard } from './types-CYvLP5pP.js';
-import * as types from '@repo/api-contract/gen/types';
+import { A as Account, U as UserIdentifier, a as AccountLookupResult, S as Safe, i as KycProfile, E as ExternalAccount, L as List, v as SubAccount, B as BalanceLedgerEntry, b as ApiKey, a0 as CreateApiKeyRequest, a1 as CreateDocumentRequest, D as Document, O as Operation, l as OperationStatus, k as Money, C as CreatePaymentResult, o as Payment, F as TransferEndpoint, f as CreateTransferResult, y as Transfer, g as CreateWithdrawalResult, _ as Withdrawal, a2 as CreateWebhookEndpointRequest, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, a3 as CreateVirtualAccountRequest, V as VirtualAccount, a4 as CreateVirtualCardRequest, Q as VirtualCard } from './types-PM4AQRLP.js';
 
 /**
  * Accounts domain — individual user accounts per sdk-surface.md §1a.
@@ -111,7 +110,7 @@ type AccountsClient = {
  * on `create` only; subsequent reads omit it.
  */
 
-type ApiKeysCreateInput = types.CreateApiKeyRequest & {
+type ApiKeysCreateInput = CreateApiKeyRequest & {
     readonly organizationId: OrganizationId;
 };
 type ApiKeysRetrieveInput = {
@@ -236,7 +235,7 @@ type AuthClient = {
  * bank_statement | tax_form`.
  */
 
-type DocumentsCreateInput = types.CreateDocumentRequest;
+type DocumentsCreateInput = CreateDocumentRequest;
 type DocumentsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
@@ -589,7 +588,7 @@ type OrgWithdrawalsClient = {
  * variant at call time and require `organizationId` explicitly.
  */
 
-type WebhookEndpointsCreateInput = types.CreateWebhookEndpointRequest & {
+type WebhookEndpointsCreateInput = CreateWebhookEndpointRequest & {
     readonly organizationId: OrganizationId;
 };
 type WebhookEndpointsRetrieveInput = {
@@ -911,6 +910,7 @@ type TransportRuntime = {
  */
 type HttpTransport = {
     readonly fetch: (path: string, init?: RequestInit) => Promise<Response>;
+    readonly ensureRuntime: () => Promise<TransportRuntime>;
     readonly authBaseUrl: string;
     readonly convexUrl: string;
     readonly getState: () => TransportState;
@@ -924,8 +924,11 @@ type HttpTransport = {
 /**
  * Build an `HttpTransport` from a `BrowserCapxulConfig`.
  *
- * Throws `Errors.invalidInput("authBaseUrl" | "convexUrl", reason)`
- * when the build-time-urls variant is missing required URLs.
+ * Throws `CapxulError<"INVALID_INPUT">` with
+ * `details.source === "sdk-config"` when local transport config is
+ * malformed. Backend bootstrap failures also throw `CapxulError`, but
+ * carry `details.source === "backend-bootstrap"` so consumers can
+ * distinguish setup mistakes from server-side bootstrap refusals.
  */
 declare function makeHttpTransport(config: BrowserCapxulConfig): HttpTransport;
 
@@ -1055,7 +1058,7 @@ type TokenTransfersClient = {
  * in the create payload rather than nesting the route under the owner.
  */
 
-type VirtualAccountsCreateInput = types.CreateVirtualAccountRequest;
+type VirtualAccountsCreateInput = CreateVirtualAccountRequest;
 type VirtualAccountsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
@@ -1080,7 +1083,7 @@ type VirtualAccountsClient = {
  * Uses Pattern C (ownerKind in body).
  */
 
-type VirtualCardsCreateInput = types.CreateVirtualCardRequest;
+type VirtualCardsCreateInput = CreateVirtualCardRequest;
 type VirtualCardsListInput = {
     readonly limit?: number;
     readonly cursor?: string;

package/dist/{client-DW_fW9DC.d.cts → client-DDAVWtzJ.d.cts}

@@ -2,8 +2,7 @@ import { Account as Account$1 } from 'viem';
 import { AnyStateMachine } from 'xstate';
 import { A as AccountId, S as SafeId, c as KycProfileId, b as ExternalAccountId, f as SubAccountId, d as OrganizationId, a as ApiKeyId, X as TimestampIso, D as DocumentId, O as OperationId, P as PaymentId, g as TransferId, k as WithdrawalId, W as WebhookEndpointId, j as WebhookEventId, M as MemberId, K as KybProfileId, V as VirtualAccountId, i as VirtualCardId } from './next-action-DkrwXYay.cjs';
 import { d as CapxulResult, C as CapxulError } from './errors-GgKrSUKp.cjs';
-import { A as Account, U as UserIdentifier, a as AccountLookupResult, S as Safe, i as KycProfile, E as ExternalAccount, L as List, v as SubAccount, B as BalanceLedgerEntry, b as ApiKey, D as Document, O as Operation, l as OperationStatus, k as Money, C as CreatePaymentResult, o as Payment, F as TransferEndpoint, f as CreateTransferResult, y as Transfer, g as CreateWithdrawalResult, _ as Withdrawal, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, V as VirtualAccount, Q as VirtualCard } from './types-X02RbQ2u.cjs';
-import * as types from '@repo/api-contract/gen/types';
+import { A as Account, U as UserIdentifier, a as AccountLookupResult, S as Safe, i as KycProfile, E as ExternalAccount, L as List, v as SubAccount, B as BalanceLedgerEntry, b as ApiKey, a0 as CreateApiKeyRequest, a1 as CreateDocumentRequest, D as Document, O as Operation, l as OperationStatus, k as Money, C as CreatePaymentResult, o as Payment, F as TransferEndpoint, f as CreateTransferResult, y as Transfer, g as CreateWithdrawalResult, _ as Withdrawal, a2 as CreateWebhookEndpointRequest, Y as WebhookEndpoint, Z as WebhookEvent, n as Organization, J as Treasury, M as Member, K as KybProfile, a3 as CreateVirtualAccountRequest, V as VirtualAccount, a4 as CreateVirtualCardRequest, Q as VirtualCard } from './types-hfcOE7Oi.cjs';
 
 /**
  * Accounts domain — individual user accounts per sdk-surface.md §1a.
@@ -111,7 +110,7 @@ type AccountsClient = {
  * on `create` only; subsequent reads omit it.
  */
 
-type ApiKeysCreateInput = types.CreateApiKeyRequest & {
+type ApiKeysCreateInput = CreateApiKeyRequest & {
     readonly organizationId: OrganizationId;
 };
 type ApiKeysRetrieveInput = {
@@ -236,7 +235,7 @@ type AuthClient = {
  * bank_statement | tax_form`.
  */
 
-type DocumentsCreateInput = types.CreateDocumentRequest;
+type DocumentsCreateInput = CreateDocumentRequest;
 type DocumentsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
@@ -589,7 +588,7 @@ type OrgWithdrawalsClient = {
  * variant at call time and require `organizationId` explicitly.
  */
 
-type WebhookEndpointsCreateInput = types.CreateWebhookEndpointRequest & {
+type WebhookEndpointsCreateInput = CreateWebhookEndpointRequest & {
     readonly organizationId: OrganizationId;
 };
 type WebhookEndpointsRetrieveInput = {
@@ -911,6 +910,7 @@ type TransportRuntime = {
  */
 type HttpTransport = {
     readonly fetch: (path: string, init?: RequestInit) => Promise<Response>;
+    readonly ensureRuntime: () => Promise<TransportRuntime>;
     readonly authBaseUrl: string;
     readonly convexUrl: string;
     readonly getState: () => TransportState;
@@ -924,8 +924,11 @@ type HttpTransport = {
 /**
  * Build an `HttpTransport` from a `BrowserCapxulConfig`.
  *
- * Throws `Errors.invalidInput("authBaseUrl" | "convexUrl", reason)`
- * when the build-time-urls variant is missing required URLs.
+ * Throws `CapxulError<"INVALID_INPUT">` with
+ * `details.source === "sdk-config"` when local transport config is
+ * malformed. Backend bootstrap failures also throw `CapxulError`, but
+ * carry `details.source === "backend-bootstrap"` so consumers can
+ * distinguish setup mistakes from server-side bootstrap refusals.
  */
 declare function makeHttpTransport(config: BrowserCapxulConfig): HttpTransport;
 
@@ -1055,7 +1058,7 @@ type TokenTransfersClient = {
  * in the create payload rather than nesting the route under the owner.
  */
 
-type VirtualAccountsCreateInput = types.CreateVirtualAccountRequest;
+type VirtualAccountsCreateInput = CreateVirtualAccountRequest;
 type VirtualAccountsListInput = {
     readonly limit?: number;
     readonly cursor?: string;
@@ -1080,7 +1083,7 @@ type VirtualAccountsClient = {
  * Uses Pattern C (ownerKind in body).
  */
 
-type VirtualCardsCreateInput = types.CreateVirtualCardRequest;
+type VirtualCardsCreateInput = CreateVirtualCardRequest;
 type VirtualCardsListInput = {
     readonly limit?: number;
     readonly cursor?: string;

package/dist/client.cjs

@@ -579,7 +579,12 @@ var Errors = {
     "Idempotency key was already used for a different request",
     { details }
   ),
-  emailDeliveryFailed: (detail) => new CapxulError2("EMAIL_DELIVERY_FAILED", `Failed to send email: ${detail}`),
+  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
@@ -652,13 +657,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."
     );
@@ -672,6 +677,7 @@ function makeBuildTimeUrlsTransport(config) {
   return {
     authBaseUrl,
     convexUrl,
+    ensureRuntime: async () => runtime,
     fetch: (path, init) => fetchImpl(resolveUrl(authBaseUrl, path), init),
     getState: lifecycle.getState,
     subscribe: lifecycle.subscribe,
@@ -687,14 +693,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 = "";
@@ -709,23 +716,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."
         );
@@ -737,16 +741,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;
   }
@@ -757,6 +758,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);
@@ -767,7 +769,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".`
         );
       }
@@ -789,6 +791,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;
@@ -796,10 +816,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 = {}) {
@@ -854,13 +1006,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({
@@ -879,6 +1034,8 @@ function createAuthClient(config = {}) {
       sessionStore.clear();
       dataClient = null;
       mutableConfig(config).data = void 0;
+      const transport = getTransport();
+      transport?.clearAuth();
       return [null, void 0];
     },
     serviceTokenMint: async () => stub("auth.serviceTokenMint"),
@@ -932,16 +1089,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 [
@@ -954,6 +1114,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";
+}
 async function exchangeConvexToken(transport, config, token, signal) {
   const path = config.auth?.convexTokenUrl ?? "/convex/token";
   try {

package/dist/client.d.cts

@@ -1,7 +1,6 @@
 import 'viem';
 import 'xstate';
-export { f as CapxulAuthConfig, C as CapxulClient, g as CapxulConfig, h as CapxulDataClient, i as CapxulFlowFactories, j as CapxulSigningConfig, K as createCapxulClient } from './client-DW_fW9DC.cjs';
+export { f as CapxulAuthConfig, C as CapxulClient, g as CapxulConfig, h as CapxulDataClient, i as CapxulFlowFactories, j as CapxulSigningConfig, K as createCapxulClient } from './client-DDAVWtzJ.cjs';
 import './next-action-DkrwXYay.cjs';
 import './errors-GgKrSUKp.cjs';
-import './types-X02RbQ2u.cjs';
-import '@repo/api-contract/gen/types';
+import './types-hfcOE7Oi.cjs';

package/dist/client.d.ts

@@ -1,7 +1,6 @@
 import 'viem';
 import 'xstate';
-export { f as CapxulAuthConfig, C as CapxulClient, g as CapxulConfig, h as CapxulDataClient, i as CapxulFlowFactories, j as CapxulSigningConfig, K as createCapxulClient } from './client-ChfXWMzO.js';
+export { f as CapxulAuthConfig, C as CapxulClient, g as CapxulConfig, h as CapxulDataClient, i as CapxulFlowFactories, j as CapxulSigningConfig, K as createCapxulClient } from './client-ByzDfG98.js';
 import './next-action-DkrwXYay.js';
 import './errors-QHD5Tlok.js';
-import './types-CYvLP5pP.js';
-import '@repo/api-contract/gen/types';
+import './types-PM4AQRLP.js';