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

package/dist/index.js

@@ -677,7 +677,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
@@ -750,13 +755,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."
     );
@@ -770,6 +775,7 @@ function makeBuildTimeUrlsTransport(config) {
   return {
     authBaseUrl,
     convexUrl,
+    ensureRuntime: async () => runtime,
     fetch: (path, init) => fetchImpl(resolveUrl(authBaseUrl, path), init),
     getState: lifecycle.getState,
     subscribe: lifecycle.subscribe,
@@ -785,14 +791,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 = "";
@@ -807,23 +814,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."
         );
@@ -835,16 +839,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;
   }
@@ -855,6 +856,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);
@@ -865,7 +867,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".`
         );
       }
@@ -887,6 +889,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;
@@ -894,10 +914,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 = {}) {
@@ -952,13 +1104,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({
@@ -970,13 +1125,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"),
@@ -1030,16 +1248,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 [
@@ -1052,6 +1273,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 {
@@ -2294,7 +2545,7 @@ function createAuthFlowMachine(client) {
       }),
       verifyOtp: fromPromise(
         async ({ input, signal }) => {
-          const [error, session] = await client.auth.verifyOtp(
+          const [error, result] = await client.auth.verifyOtp(
             {
               email: input.email,
               otp: input.code
@@ -2302,7 +2553,14 @@ function createAuthFlowMachine(client) {
             { signal }
           );
           if (error) throw error;
-          return session;
+          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: fromPromise(async () => {
@@ -2550,6 +2808,345 @@ 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 setup({
+    types: {},
+    actors: {
+      sendOtp: fromPromise(async ({ input, signal }) => {
+        const [error] = await client.auth.sendOtp(
+          { email: input.email },
+          { signal }
+        );
+        if (error) throw error;
+      }),
+      verifyOtp: fromPromise(
+        async ({ input, signal }) => {
+          const [error, result] = await client.auth.verifyOtp(
+            { email: input.email, otp: input.code },
+            { signal }
+          );
+          if (error) throw error;
+          return result;
+        }
+      ),
+      completeBootstrap: fromPromise(async ({ input }) => {
+        const [error, result] = await client.auth.completeBootstrap(input);
+        if (error) throw error;
+        return result;
+      }),
+      signOut: fromPromise(async () => {
+        const [error] = await client.auth.signOut();
+        if (error) throw error;
+      })
+    },
+    actions: {
+      trackOtpRequested: ({ context }) => {
+        if (!context.email) return;
+        track("auth_otp_requested", {
+          email_domain: emailDomain2(context.email)
+        });
+      },
+      trackFailed: ({ event }) => {
+        track("auth_failed", {
+          auth_type: "email_otp",
+          reason: errorFromEvent2(event).code
+        });
+      },
+      trackTimeoutFailed: () => {
+        track("auth_failed", {
+          auth_type: "email_otp",
+          reason: "timeout"
+        });
+      },
+      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: emailDomain2(context.session.email)
+        });
+        track("auth_identified", {
+          email_domain: emailDomain2(context.session.email)
+        });
+      },
+      trackSignedOut: () => {
+        track("auth_signed_out");
+      }
+    }
+  }).createMachine({
+    id: "authBootstrap",
+    initial: "email",
+    context: initialContext,
+    states: {
+      email: {
+        on: {
+          ENTER_EMAIL: {
+            actions: assign({
+              email: ({ event }) => event.email,
+              error: () => null
+            })
+          },
+          REQUEST_OTP: { target: "sending_otp" }
+        }
+      },
+      sending_otp: {
+        invoke: {
+          src: "sendOtp",
+          input: ({ context }) => ({ email: requireEmail2(context) }),
+          onDone: { target: "otp_requested", actions: "trackOtpRequested" },
+          onError: {
+            target: "otp_requested",
+            actions: [
+              assign({ error: ({ event }) => errorFromEvent2(event) }),
+              "trackFailed"
+            ]
+          }
+        },
+        after: {
+          [FLOW_INVOKE_TIMEOUT_MS]: {
+            target: "otp_requested",
+            actions: [
+              assign({ error: () => timeoutError2("sending_otp") }),
+              "trackTimeoutFailed"
+            ]
+          }
+        }
+      },
+      otp_requested: {
+        on: {
+          ENTER_OTP: {
+            actions: assign({
+              code: ({ event }) => event.code,
+              error: () => null
+            })
+          },
+          VERIFY_OTP: { target: "verifying_otp" },
+          BACK: { target: "email" },
+          RESET: { target: "email", actions: 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: [
+                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: [
+                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: "otp_requested",
+            actions: [
+              assign({ error: ({ event }) => errorFromEvent2(event) }),
+              "trackFailed"
+            ]
+          }
+        },
+        after: {
+          [FLOW_INVOKE_TIMEOUT_MS]: {
+            target: "otp_requested",
+            actions: [
+              assign({ error: () => timeoutError2("verifying_otp") }),
+              "trackTimeoutFailed"
+            ]
+          }
+        }
+      },
+      bootstrap_required: {
+        on: {
+          ENTER_USERNAME: {
+            actions: assign({
+              username: ({ event }) => event.username,
+              error: () => null
+            })
+          },
+          ENTER_SIGNER_PROVIDER: {
+            actions: assign({
+              signerProvider: ({ event }) => event.signerProvider,
+              error: () => null
+            })
+          },
+          COMPLETE_BOOTSTRAP: { target: "completing_bootstrap" },
+          BACK: { target: "otp_requested" },
+          RESET: { target: "email", actions: assign(() => initialContext) }
+        }
+      },
+      completing_bootstrap: {
+        invoke: {
+          src: "completeBootstrap",
+          input: ({ context }) => ({
+            bootstrapToken: requireBootstrapToken(context),
+            username: requireUsername(context),
+            signerProvider: requireSignerProvider(context)
+          }),
+          onDone: {
+            target: "authenticated",
+            actions: [
+              assign({
+                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
+              }),
+              "identifyAndTrack"
+            ]
+          },
+          onError: {
+            target: "bootstrap_required",
+            actions: [
+              assign({ error: ({ event }) => errorFromEvent2(event) }),
+              "trackFailed"
+            ]
+          }
+        },
+        after: {
+          [FLOW_INVOKE_TIMEOUT_MS]: {
+            target: "bootstrap_required",
+            actions: [
+              assign({ error: () => timeoutError2("completing_bootstrap") }),
+              "trackTimeoutFailed"
+            ]
+          }
+        }
+      },
+      authenticated: {
+        on: {
+          SIGN_OUT: { target: "signing_out" }
+        }
+      },
+      signing_out: {
+        invoke: {
+          src: "signOut",
+          onDone: {
+            target: "email",
+            actions: [
+              assign(() => initialContext),
+              "trackSignedOut"
+            ]
+          },
+          onError: {
+            target: "error",
+            actions: assign({ error: ({ event }) => errorFromEvent2(event) })
+          }
+        }
+      },
+      error: {
+        on: {
+          RESET: { target: "email", actions: assign(() => initialContext) }
+        }
+      }
+    }
+  });
+}
+function requireEmail2(context) {
+  if (!context.email) {
+    throw Errors.invalidInput("email", "Auth bootstrap requires an email.");
+  }
+  return context.email;
+}
+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(
+      "bootstrapToken",
+      "Auth bootstrap requires a continuation token."
+    );
+  }
+  return context.bootstrapToken;
+}
+function requireUsername(context) {
+  if (!context.username) {
+    throw Errors.invalidInput("username", "Auth bootstrap requires a username.");
+  }
+  return context.username;
+}
+function requireSignerProvider(context) {
+  if (!context.signerProvider) {
+    throw Errors.invalidInput(
+      "signerProvider",
+      "Auth bootstrap requires a signer provider."
+    );
+  }
+  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 Errors.providerError("auth", "bootstrap", cause);
+}
+function timeoutError2(state) {
+  return Errors.providerError(
+    "auth",
+    "bootstrap",
+    new Error(`timeout: ${state} exceeded ${FLOW_INVOKE_TIMEOUT_MS}ms`)
+  );
+}
+function emailDomain2(email) {
+  const domain = email.split("@")[1]?.trim().toLowerCase();
+  return domain || "unknown";
+}
 function createProvisioningMachine(client) {
   return setup({
     types: {},
@@ -2622,13 +3219,13 @@ function createProvisioningMachine(client) {
           },
           onError: {
             target: "error",
-            actions: assign({ error: ({ event }) => errorFromEvent2(event) })
+            actions: assign({ error: ({ event }) => errorFromEvent3(event) })
           }
         },
         after: {
           [FLOW_INVOKE_TIMEOUT_MS]: {
             target: "error",
-            actions: assign({ error: () => timeoutError2() })
+            actions: assign({ error: () => timeoutError3() })
           }
         }
       },
@@ -2646,7 +3243,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) {
@@ -2658,13 +3255,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",
@@ -2757,7 +3354,7 @@ function createOnboardingFlowMachine(client) {
         error: ({ event }) => extractChildErrorOrFallback(event)
       }),
       assignChildThrown: assign({
-        error: ({ event }) => errorFromEvent3(event)
+        error: ({ event }) => errorFromEvent4(event)
       }),
       assignAccountFromChild: assign({
         account: ({ event }) => extractChildAccountOrNull(event)
@@ -2919,7 +3516,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;
@@ -2951,6 +3548,7 @@ function createCapxulClient(config = {}) {
   const client = clientWithoutFlows;
   client.flows = {
     auth: () => createAuthFlowMachine(client),
+    authBootstrap: () => createAuthBootstrapFlowMachine(client),
     onboarding: () => createOnboardingFlowMachine(client),
     provisioning: () => createProvisioningMachine(client)
   };
@@ -3055,4 +3653,4 @@ function isWebhookEvent(value) {
   return typeof candidate.id === "string" && typeof candidate.type === "string" && typeof candidate.createdAt === "string" && (candidate.operationId === void 0 || typeof candidate.operationId === "string") && (candidate.correlationId === void 0 || typeof candidate.correlationId === "string") && !!candidate.data && typeof candidate.data === "object" && !Array.isArray(candidate.data);
 }
 
-export { CapxulError, createAuthFlowMachine, createCapxulClient, createLocalSigner, createOnboardingFlowMachine, createProvisioningMachine as createProvisioningFlowMachine, makeHttpTransport, matchAction, matchError, matchStatus, toAccountId, toApiKeyId, toBalanceLedgerEntryId, toDocumentId, toEmail, toExternalAccountId, toKybProfileId, toKycProfileId, toMemberId, toOperationId, toOrganizationId, toPaymentId, toPhoneNumber, toSafeId, toSubAccountId, toTokenTransferId, toTransferId, toTreasuryId, toUsername, toVirtualAccountId, toVirtualCardId, toWebhookEndpointId, toWebhookEventId, toWithdrawalId, tryCatch, verifyWebhook };
+export { CapxulError, createAuthBootstrapFlowMachine, createAuthFlowMachine, createCapxulClient, createLocalSigner, createOnboardingFlowMachine, createProvisioningMachine as createProvisioningFlowMachine, makeHttpTransport, matchAction, matchError, matchStatus, toAccountId, toApiKeyId, toBalanceLedgerEntryId, toDocumentId, toEmail, toExternalAccountId, toKybProfileId, toKycProfileId, toMemberId, toOperationId, toOrganizationId, toPaymentId, toPhoneNumber, toSafeId, toSubAccountId, toTokenTransferId, toTransferId, toTreasuryId, toUsername, toVirtualAccountId, toVirtualCardId, toWebhookEndpointId, toWebhookEventId, toWithdrawalId, tryCatch, verifyWebhook };