@capxul/sdk-react 0.1.0-alpha.1 → 0.1.0-alpha.11

package/dist/index.js

@@ -1,14 +1,54 @@
 "use client";
-import { createContext, useContext, useSyncExternalStore, useMemo, useState, useEffect } from 'react';
-import { createCapxulClient, makeHttpTransport, CapxulError as CapxulError$1 } from '@capxul/sdk';
+import { createContext, useContext, useSyncExternalStore, useMemo, useEffect, useState } from 'react';
+import { makeHttpTransport, createCapxulClient, CapxulError as CapxulError$1 } from '@capxul/sdk';
 import { QueryClient, QueryClientProvider, useQuery } from '@tanstack/react-query';
 import { jsx } from 'react/jsx-runtime';
+import { ConvexReactClient } from 'convex/react';
 import { CapxulError as CapxulError$2 } from '@capxul/sdk/errors';
 import { useActor } from '@xstate/react';
 import { getAddress } from 'viem';
 import { privateKeyToAccount } from 'viem/accounts';
 
 // src/provider.tsx
+var CapxulClientContext = createContext(null);
+function CapxulClientProvider({
+  client,
+  children
+}) {
+  return /* @__PURE__ */ jsx(CapxulClientContext.Provider, { value: client, children });
+}
+function useCapxul() {
+  const client = useContext(CapxulClientContext);
+  if (!client) {
+    throw new Error(
+      "useCapxul() was called outside a <CapxulProvider>. Wrap your app in <CapxulProvider config={...}> before rendering hooks from @capxul/sdk-react."
+    );
+  }
+  return client;
+}
+var CapxulTransportContext = createContext(null);
+function CapxulTransportProvider({
+  transport,
+  children
+}) {
+  return /* @__PURE__ */ jsx(CapxulTransportContext.Provider, { value: transport, children });
+}
+function useCapxulStatus() {
+  const transport = useContext(CapxulTransportContext);
+  return useSyncExternalStore(
+    (listener) => {
+      if (!transport) return () => {
+      };
+      return transport.subscribe(listener);
+    },
+    () => transport?.getState() ?? FALLBACK_READY,
+    () => transport?.getState() ?? FALLBACK_READY
+  );
+}
+var FALLBACK_READY = Object.freeze({
+  status: "ready",
+  runtime: { authBaseUrl: "", convexUrl: "" }
+});
 
 // ../config/src/errors.ts
 var CapxulError = class extends Error {
@@ -39,10 +79,16 @@ var Errors = {
     `Shield API error (${status}): ${detail}`,
     { details: { provider: "shield", status } }
   ),
-  providerError: (provider, operation, cause) => new CapxulError(
-    "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 CapxulError(
+      "PROVIDER_ERROR",
+      `Provider error: ${provider} ${operation}`,
+      { cause, details: { provider, operation } }
+    )
   ),
   invalidInput: (field, reason) => new CapxulError(
     "INVALID_INPUT",
@@ -68,8 +114,35 @@ var Errors = {
     "Idempotency key was already used for a different request",
     { details }
   ),
-  emailDeliveryFailed: (detail) => new CapxulError("EMAIL_DELIVERY_FAILED", `Failed to send email: ${detail}`),
-  internalError: (reason) => new CapxulError("INTERNAL_ERROR", `Internal error: ${reason}`)
+  emailDeliveryFailed: (detail, details) => new CapxulError("EMAIL_DELIVERY_FAILED", `Failed to send email: ${detail}`, {
+    details
+  }),
+  rateLimited: (details) => new CapxulError("RATE_LIMITED", "Request was rate limited", {
+    details: { ...details }
+  }),
+  internalError: (reason) => new CapxulError("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 CapxulError("VERIFICATION_REQUIRED", message, {
+      details: { ...details }
+    });
+  }
 };
 
 // ../config/src/org-roles.ts
@@ -81,56 +154,137 @@ function roleKeyFromLabel(label) {
 roleKeyFromLabel("OWNER");
 roleKeyFromLabel("FINANCE_MANAGER");
 roleKeyFromLabel("TEAM_LEAD");
-var CapxulClientContext = createContext(null);
-function CapxulClientProvider({
-  client,
-  children
-}) {
-  return /* @__PURE__ */ jsx(CapxulClientContext.Provider, { value: client, children });
+
+// src/config.ts
+function createCapxulConfig(input) {
+  assertOnlyKnownKeys(input);
+  assertModeRequiredFields(input);
+  return Object.freeze({ ...input });
 }
-function useCapxul() {
-  const client = useContext(CapxulClientContext);
-  if (!client) {
-    throw new Error(
-      "useCapxul() was called outside a <CapxulProvider>. Wrap your app in <CapxulProvider config={...}> before rendering hooks from @capxul/sdk-react."
-    );
+var ALLOWED_BROWSER_CONFIG_KEYS = [
+  "mode",
+  "authBaseUrl",
+  "convexUrl",
+  "publishableKey",
+  "bootstrapUrl",
+  "fetchImpl"
+];
+function assertOnlyKnownKeys(input) {
+  const candidate = input;
+  const allowed = new Set(ALLOWED_BROWSER_CONFIG_KEYS);
+  const unknown = Object.keys(candidate).filter((key) => !allowed.has(key));
+  if (unknown.length === 0) return;
+  throw Errors.invalidInput(
+    "config",
+    `Browser Capxul config contains unknown or secret/server-only fields: ${unknown.join(", ")}. Allowed keys: ${ALLOWED_BROWSER_CONFIG_KEYS.join(", ")}.`
+  );
+}
+function assertModeRequiredFields(input) {
+  switch (input.mode) {
+    case "build-time-urls": {
+      if (!input.authBaseUrl || input.authBaseUrl.trim().length === 0) {
+        throw Errors.invalidInput("authBaseUrl", "non-empty string required.");
+      }
+      if (!input.convexUrl || input.convexUrl.trim().length === 0) {
+        throw Errors.invalidInput("convexUrl", "non-empty string required.");
+      }
+      return;
+    }
+    case "publishable-key": {
+      if (!input.publishableKey || input.publishableKey.trim().length === 0) {
+        throw Errors.invalidInput("publishableKey", "non-empty string required.");
+      }
+      return;
+    }
+    default: {
+      const value = input;
+      throw Errors.internalError(
+        `Unhandled BrowserCapxulConfig.mode: ${String(value.mode)}.`
+      );
+    }
   }
-  return client;
 }
-var CapxulTransportContext = createContext(null);
-function CapxulTransportProvider({
-  transport,
-  children
-}) {
-  return /* @__PURE__ */ jsx(CapxulTransportContext.Provider, { value: transport, children });
+function createReactDataClient(convexUrl, sessionStore) {
+  const client = new ConvexReactClient(convexUrl);
+  const refreshAuth = () => {
+    const session = sessionStore.get();
+    const jwt = session?.convexJwt;
+    if (jwt) {
+      client.setAuth(() => Promise.resolve(jwt));
+    } else {
+      client.clearAuth();
+    }
+  };
+  refreshAuth();
+  return {
+    query: (name, args) => client.query(name, args),
+    mutation: (name, args) => client.mutation(name, args),
+    action: (name, args) => client.action(name, args),
+    refreshAuth,
+    close: () => {
+      void client.close();
+    }
+  };
 }
-function useCapxulStatus() {
-  const transport = useContext(CapxulTransportContext);
-  return useSyncExternalStore(
-    (listener) => {
-      if (!transport) return () => {
-      };
-      return transport.subscribe(listener);
+function createLazyReactDataClient(transport, sessionStore, createClient = createReactDataClient) {
+  let client = null;
+  let initializeClient = null;
+  let closed = false;
+  function closedError() {
+    return new Error("Capxul React data client is closed");
+  }
+  async function getClient() {
+    if (closed) throw closedError();
+    if (client) return client;
+    initializeClient ??= (async () => {
+      const runtime = await transport.ensureRuntime();
+      if (closed) throw closedError();
+      const nextClient = createClient(runtime.convexUrl, sessionStore);
+      if (closed) {
+        nextClient.close();
+        throw closedError();
+      }
+      client = nextClient;
+      return nextClient;
+    })().catch((error) => {
+      if (!closed) {
+        initializeClient = null;
+      }
+      throw error;
+    });
+    return initializeClient;
+  }
+  return {
+    query: async (name, args) => (await getClient()).query(name, args),
+    mutation: async (name, args) => (await getClient()).mutation(name, args),
+    action: async (name, args) => (await getClient()).action?.(name, args),
+    refreshAuth: () => {
+      client?.refreshAuth();
     },
-    () => transport?.getState() ?? FALLBACK_READY,
-    () => transport?.getState() ?? FALLBACK_READY
-  );
+    close: () => {
+      closed = true;
+      client?.close();
+      client = null;
+    }
+  };
 }
-var FALLBACK_READY = Object.freeze({
-  status: "ready",
-  runtime: { authBaseUrl: "", convexUrl: "" }
-});
 function CapxulProvider({
   config,
-  publishableKey,
-  browserConfig,
+  sessionStore,
   queryClient,
   children
 }) {
+  const defaultSessionStore = useMemo(() => createMemorySessionStore(), []);
+  const effectiveSessionStore = sessionStore ?? defaultSessionStore;
   const wiring = useMemo(
-    () => buildWiring({ config, publishableKey, browserConfig }),
-    [config, publishableKey, browserConfig]
+    () => buildWiring(config, effectiveSessionStore),
+    [config, effectiveSessionStore]
   );
+  useEffect(() => {
+    return () => {
+      wiring.dataClient?.close();
+    };
+  }, [wiring]);
   const defaultClient = useMemo(
     () => new QueryClient({
       defaultOptions: { queries: { staleTime: 3e4 } }
@@ -138,51 +292,60 @@ function CapxulProvider({
     []
   );
   const effectiveClient = queryClient ?? defaultClient;
-  const inner = /* @__PURE__ */ jsx(CapxulClientProvider, { client: wiring.client, children });
-  return /* @__PURE__ */ jsx(QueryClientProvider, { client: effectiveClient, children: wiring.transport ? /* @__PURE__ */ jsx(CapxulTransportProvider, { transport: wiring.transport, children: inner }) : inner });
+  return /* @__PURE__ */ jsx(QueryClientProvider, { client: effectiveClient, children: /* @__PURE__ */ jsx(CapxulTransportProvider, { transport: wiring.transport, children: /* @__PURE__ */ jsx(CapxulClientProvider, { client: wiring.client, children }) }) });
 }
-function buildWiring({
-  config,
-  publishableKey,
-  browserConfig
-}) {
-  const sources = [
-    config !== void 0,
-    publishableKey !== void 0,
-    browserConfig !== void 0
-  ].filter(Boolean).length;
-  if (sources === 0) {
-    throw Errors.invalidInput(
-      "CapxulProvider",
-      "Pass exactly one of `config`, `publishableKey`, or `browserConfig`."
-    );
-  }
-  if (sources > 1) {
-    throw Errors.invalidInput(
-      "CapxulProvider",
-      "`config`, `publishableKey`, and `browserConfig` are mutually exclusive \u2014 pass exactly one."
-    );
-  }
-  if (config !== void 0) {
-    return {
-      client: createCapxulClient(config),
-      transport: null
-    };
-  }
-  const browserCfg = browserConfig ?? {
-    mode: "publishable-key",
-    // The narrowing above (`sources === 0` rejected; `config` not
-    // present) guarantees `publishableKey` is set on this branch.
-    publishableKey
-  };
-  const transport = makeHttpTransport(browserCfg);
+function buildWiring(config, sessionStore) {
+  const validated = createCapxulConfig(config);
+  const transport = makeHttpTransport(validated);
+  const dataClient = validated.mode === "build-time-urls" ? createReactDataClient(validated.convexUrl, sessionStore) : createLazyReactDataClient(transport, sessionStore);
   const sdkConfig = {
     _transport: transport,
-    publishableKey: browserCfg.mode === "publishable-key" ? browserCfg.publishableKey : void 0
+    publishableKey: validated.mode === "publishable-key" ? validated.publishableKey : void 0,
+    data: dataClient ?? void 0,
+    auth: validated.mode === "build-time-urls" || validated.mode === "publishable-key" ? {
+      // The auth client builds the BetterAuth root URL from this
+      // value. Convex's `.cloud` URL is the wrong host (BetterAuth
+      // is mounted on the `.site` URL), but the build-time-urls
+      // transport already encodes the correct `authBaseUrl` via
+      // its discriminated union. We pass `convexUrl` here only so
+      // `core/auth.ts`'s `createTransportProvider` short-circuits
+      // to the externally-injected `_transport` cache slot.
+      baseUrl: transport.authBaseUrl,
+      sessionStore,
+      createDataClient: async (_session) => {
+        dataClient.refreshAuth();
+        return dataClient;
+      }
+    } : void 0
+  };
+  const client = createCapxulClient(sdkConfig);
+  if (dataClient) {
+    const originalSignOut = client.auth.signOut;
+    Object.assign(client.auth, {
+      signOut: async () => {
+        const result = await originalSignOut();
+        dataClient.refreshAuth();
+        sdkConfig.data = dataClient;
+        return result;
+      }
+    });
+  }
+  return {
+    client,
+    transport,
+    dataClient
   };
+}
+function createMemorySessionStore() {
+  let current = null;
   return {
-    client: createCapxulClient(sdkConfig),
-    transport
+    get: () => current,
+    set: (session) => {
+      current = session;
+    },
+    clear: () => {
+      current = null;
+    }
   };
 }
 function notImplementedQuery(hookName) {
@@ -272,8 +435,12 @@ function useMe() {
     staleTime: 3e4
   });
 }
-function useAccount(_accountId) {
-  return notImplementedQuery("useAccount");
+function useAccount(accountId) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => accountId !== void 0 ? capxul.accounts.retrieve(accountId) : capxul.me.get(),
+    [capxul, accountId]
+  );
 }
 function useOrganization(_organizationId) {
   return notImplementedQuery("useOrganization");
@@ -281,8 +448,12 @@ function useOrganization(_organizationId) {
 function useMember(_args) {
   return notImplementedQuery("useMember");
 }
-function useSafe(_safeId) {
-  return notImplementedQuery("useSafe");
+function useSafe(safeId) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => capxul.accounts.safes.retrieve(safeId),
+    [capxul, safeId]
+  );
 }
 function useTreasury(_organizationId) {
   return notImplementedQuery("useTreasury");
@@ -296,11 +467,22 @@ function useKycProfile(_accountId) {
 function useKybProfile(_organizationId) {
   return notImplementedQuery("useKybProfile");
 }
-function useExternalAccount(_args) {
-  return notImplementedQuery("useExternalAccount");
+function useExternalAccount(args) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => args.ownerKind === "account" ? capxul.externalAccounts.retrieve(args.externalAccountId) : capxul.organizations.externalAccounts.retrieve({
+      organizationId: args.ownerId,
+      externalAccountId: args.externalAccountId
+    }),
+    [capxul, args.ownerKind, args.ownerId, args.externalAccountId]
+  );
 }
-function useSubAccount(_subAccountId) {
-  return notImplementedQuery("useSubAccount");
+function useSubAccount(subAccountId) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => capxul.subAccounts.retrieve(subAccountId),
+    [capxul, subAccountId]
+  );
 }
 function useVirtualAccount(_virtualAccountId) {
   return notImplementedQuery("useVirtualAccount");
@@ -314,6 +496,13 @@ function usePayment(_paymentId) {
 function useTransfer(_transferId) {
   return notImplementedQuery("useTransfer");
 }
+function useTokenTransfer(args) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => capxul.tokenTransfers.retrieve(args),
+    [capxul, args.txHash, args.logIndex, args.chainId]
+  );
+}
 function useBalanceLedgerEntry(_args) {
   return notImplementedQuery("useBalanceLedgerEntry");
 }
@@ -348,11 +537,23 @@ function useOrganizations() {
 function useMembers(_organizationId) {
   return notImplementedQuery("useMembers");
 }
-function useExternalAccounts(_args) {
-  return notImplementedQuery("useExternalAccounts");
+function useExternalAccounts(args) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => args.ownerKind === "account" ? capxul.accounts.externalAccounts.list({ accountId: args.ownerId }) : capxul.organizations.externalAccounts.list({
+      organizationId: args.ownerId
+    }),
+    [capxul, args.ownerKind, args.ownerId]
+  );
 }
-function useSubAccounts(_args) {
-  return notImplementedQuery("useSubAccounts");
+function useSubAccounts(args) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => args.ownerKind === "account" ? capxul.accounts.subAccounts.list({ accountId: args.ownerId }) : capxul.organizations.subAccounts.list({
+      organizationId: args.ownerId
+    }),
+    [capxul, args.ownerKind, args.ownerId]
+  );
 }
 function useVirtualAccounts(_filters) {
   return notImplementedQuery("useVirtualAccounts");
@@ -372,6 +573,13 @@ function useTransfers(_filters) {
 function useOrgTransfers(_args) {
   return notImplementedQuery("useOrgTransfers");
 }
+function useTokenTransfers(filters) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => capxul.tokenTransfers.list(filters),
+    [capxul, filters?.limit, filters?.cursor, filters?.direction]
+  );
+}
 function useBalanceLedger(_args) {
   return notImplementedQuery("useBalanceLedger");
 }
@@ -407,6 +615,12 @@ function useAuthFlow() {
   const [snapshot, send] = useActor(machine);
   return { snapshot, send };
 }
+function useAuthBootstrapFlow() {
+  const client = useCapxul();
+  const machine = useMemo(() => client.flows.authBootstrap(), [client]);
+  const [snapshot, send] = useActor(machine);
+  return { snapshot, send };
+}
 function useOnboardingFlow() {
   const client = useCapxul();
   const machine = useMemo(() => client.flows.onboarding(), [client]);
@@ -419,56 +633,6 @@ function useProvisioningFlow() {
   const [snapshot, send] = useActor(machine);
   return { snapshot, send };
 }
-
-// src/config.ts
-function createCapxulConfig(input) {
-  assertOnlyKnownKeys(input);
-  assertModeRequiredFields(input);
-  return Object.freeze({ ...input });
-}
-var ALLOWED_BROWSER_CONFIG_KEYS = [
-  "mode",
-  "authBaseUrl",
-  "convexUrl",
-  "publishableKey",
-  "bootstrapUrl",
-  "fetchImpl"
-];
-function assertOnlyKnownKeys(input) {
-  const candidate = input;
-  const allowed = new Set(ALLOWED_BROWSER_CONFIG_KEYS);
-  const unknown = Object.keys(candidate).filter((key) => !allowed.has(key));
-  if (unknown.length === 0) return;
-  throw Errors.invalidInput(
-    "config",
-    `Browser Capxul config contains unknown or secret/server-only fields: ${unknown.join(", ")}. Allowed keys: ${ALLOWED_BROWSER_CONFIG_KEYS.join(", ")}.`
-  );
-}
-function assertModeRequiredFields(input) {
-  switch (input.mode) {
-    case "build-time-urls": {
-      if (!input.authBaseUrl || input.authBaseUrl.trim().length === 0) {
-        throw Errors.invalidInput("authBaseUrl", "non-empty string required.");
-      }
-      if (!input.convexUrl || input.convexUrl.trim().length === 0) {
-        throw Errors.invalidInput("convexUrl", "non-empty string required.");
-      }
-      return;
-    }
-    case "publishable-key": {
-      if (!input.publishableKey || input.publishableKey.trim().length === 0) {
-        throw Errors.invalidInput("publishableKey", "non-empty string required.");
-      }
-      return;
-    }
-    default: {
-      const value = input;
-      throw Errors.internalError(
-        `Unhandled BrowserCapxulConfig.mode: ${String(value.mode)}.`
-      );
-    }
-  }
-}
 var PRIVATE_KEY_PATTERN = /^0x[0-9a-fA-F]{64}$/;
 var EVM_ADDRESS_PATTERN = /^0x[0-9a-fA-F]{40}$/;
 function injectedConnector(options = {}) {
@@ -565,4 +729,4 @@ function validateAndNormalizeEvmAddress(field, raw) {
   }
 }
 
-export { CapxulClientProvider, CapxulProvider, CapxulTransportProvider, createCapxulConfig, injectedConnector, localPrivateKeyConnector, useAccount, useApiKey, useApiKeys, useAuthFlow, useBalanceLedger, useBalanceLedgerEntry, useCapxul, useCapxulStatus, useDocument, useDocuments, useExternalAccount, useExternalAccounts, useKybProfile, useKycProfile, useMe, useMember, useMembers, useOnboardingFlow, useOperation, useOrgDocuments, useOrgPayments, useOrgTransfers, useOrgWithdrawals, useOrganization, useOrganizations, usePayment, usePayments, useProvisioningFlow, useSafe, useSubAccount, useSubAccounts, useTransfer, useTransfers, useTreasury, useVirtualAccount, useVirtualAccounts, useVirtualCard, useVirtualCards, useWebhookEndpoint, useWebhookEndpoints, useWebhookEvent, useWithdrawal, useWithdrawals };
+export { CapxulClientProvider, CapxulProvider, CapxulTransportProvider, createCapxulConfig, injectedConnector, localPrivateKeyConnector, useAccount, useApiKey, useApiKeys, useAuthBootstrapFlow, useAuthFlow, useBalanceLedger, useBalanceLedgerEntry, useCapxul, useCapxulStatus, useDocument, useDocuments, useExternalAccount, useExternalAccounts, useKybProfile, useKycProfile, useMe, useMember, useMembers, useOnboardingFlow, useOperation, useOrgDocuments, useOrgPayments, useOrgTransfers, useOrgWithdrawals, useOrganization, useOrganizations, usePayment, usePayments, useProvisioningFlow, useSafe, useSubAccount, useSubAccounts, useTokenTransfer, useTokenTransfers, useTransfer, useTransfers, useTreasury, useVirtualAccount, useVirtualAccounts, useVirtualCard, useVirtualCards, useWebhookEndpoint, useWebhookEndpoints, useWebhookEvent, useWithdrawal, useWithdrawals };