@capxul/sdk-react 0.1.0-alpha.0

package/dist/index.cjs

@@ -0,0 +1,618 @@
+"use client";
+'use strict';
+
+var react = require('react');
+var sdk = require('@capxul/sdk');
+var reactQuery = require('@tanstack/react-query');
+var jsxRuntime = require('react/jsx-runtime');
+var errors = require('@capxul/sdk/errors');
+var react$1 = require('@xstate/react');
+var viem = require('viem');
+var accounts = require('viem/accounts');
+
+// src/provider.tsx
+
+// ../config/src/errors.ts
+var CapxulError = class extends Error {
+  code;
+  details;
+  correlationId;
+  layer;
+  constructor(code, message, options) {
+    super(message, options?.cause ? { cause: options.cause } : void 0);
+    this.code = code;
+    this.details = options?.details;
+    this.correlationId = options?.correlationId;
+    this.layer = options?.layer;
+  }
+};
+var Errors = {
+  notAuthenticated: () => new CapxulError("NOT_AUTHENTICATED", "Not authenticated"),
+  profileNotFound: (authUserId) => new CapxulError("PROFILE_NOT_FOUND", `Profile not found for user ${authUserId}`),
+  smartAccountMissing: (authUserId) => new CapxulError("SMART_ACCOUNT_MISSING", `Smart account not provisioned for user ${authUserId}`),
+  envMissing: (name) => new CapxulError("ENV_MISSING", `Environment variable ${name} not configured`),
+  openfortApi: (operation, cause) => new CapxulError(
+    "PROVIDER_ERROR",
+    `Openfort ${operation} failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+    { cause, details: { provider: "openfort", operation } }
+  ),
+  shieldApi: (status, detail) => new CapxulError(
+    "PROVIDER_ERROR",
+    `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 } }
+  ),
+  invalidInput: (field, reason) => new CapxulError(
+    "INVALID_INPUT",
+    `Invalid ${field}: ${reason}`,
+    { details: { field, reason } }
+  ),
+  playerNotFound: (playerId) => new CapxulError(
+    "PLAYER_NOT_FOUND",
+    playerId ? `Openfort player ${playerId} not found` : "Openfort player not found"
+  ),
+  accountNotFound: (accountId) => new CapxulError(
+    "ACCOUNT_NOT_FOUND",
+    accountId ? `Openfort account ${accountId} not found` : "Openfort smart account not found"
+  ),
+  invalidRecipient: (reason) => new CapxulError("INVALID_RECIPIENT", reason),
+  permissionDenied: (reason = "Permission denied") => new CapxulError("PERMISSION_DENIED", reason),
+  notFound: (resource, id) => new CapxulError(
+    "NOT_FOUND",
+    id ? `${resource} ${id} not found` : `${resource} not found`
+  ),
+  idempotencyConflict: (details) => new CapxulError(
+    "IDEMPOTENCY_CONFLICT",
+    "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}`)
+};
+
+// ../config/src/org-roles.ts
+function roleKeyFromLabel(label) {
+  const bytes = new TextEncoder().encode(label);
+  const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+  return "0x" + hex.padEnd(64, "0");
+}
+roleKeyFromLabel("OWNER");
+roleKeyFromLabel("FINANCE_MANAGER");
+roleKeyFromLabel("TEAM_LEAD");
+var CapxulClientContext = react.createContext(null);
+function CapxulClientProvider({
+  client,
+  children
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsx(CapxulClientContext.Provider, { value: client, children });
+}
+function useCapxul() {
+  const client = react.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 = react.createContext(null);
+function CapxulTransportProvider({
+  transport,
+  children
+}) {
+  return /* @__PURE__ */ jsxRuntime.jsx(CapxulTransportContext.Provider, { value: transport, children });
+}
+function useCapxulStatus() {
+  const transport = react.useContext(CapxulTransportContext);
+  return react.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: "" }
+});
+function CapxulProvider({
+  config,
+  publishableKey,
+  browserConfig,
+  queryClient,
+  children
+}) {
+  const wiring = react.useMemo(
+    () => buildWiring({ config, publishableKey, browserConfig }),
+    [config, publishableKey, browserConfig]
+  );
+  const defaultClient = react.useMemo(
+    () => new reactQuery.QueryClient({
+      defaultOptions: { queries: { staleTime: 3e4 } }
+    }),
+    []
+  );
+  const effectiveClient = queryClient ?? defaultClient;
+  const inner = /* @__PURE__ */ jsxRuntime.jsx(CapxulClientProvider, { client: wiring.client, children });
+  return /* @__PURE__ */ jsxRuntime.jsx(reactQuery.QueryClientProvider, { client: effectiveClient, children: wiring.transport ? /* @__PURE__ */ jsxRuntime.jsx(CapxulTransportProvider, { transport: wiring.transport, children: inner }) : inner });
+}
+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: sdk.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 = sdk.makeHttpTransport(browserCfg);
+  const sdkConfig = {
+    _transport: transport,
+    publishableKey: browserCfg.mode === "publishable-key" ? browserCfg.publishableKey : void 0
+  };
+  return {
+    client: sdk.createCapxulClient(sdkConfig),
+    transport
+  };
+}
+function notImplementedQuery(hookName) {
+  return {
+    status: "error",
+    error: new errors.CapxulError({
+      code: "NOT_IMPLEMENTED",
+      message: `${hookName} is not yet implemented in @capxul/sdk-react. The hook remains a reset placeholder until its vertical lands per sdk-surface.md \xA73b.`
+    })
+  };
+}
+function useSdkQuery(read, dependencies) {
+  const [state, setState] = react.useState({
+    dependencies,
+    result: { status: "loading" }
+  });
+  const dependenciesChanged = didDependenciesChange(
+    state.dependencies,
+    dependencies
+  );
+  react.useEffect(() => {
+    let active = true;
+    setState({ dependencies, result: { status: "loading" } });
+    void read().then(([error, data]) => {
+      if (!active) {
+        return;
+      }
+      if (error) {
+        setState({ dependencies, result: { status: "error", error } });
+        return;
+      }
+      setState({ dependencies, result: { status: "data", data } });
+    }).catch((cause) => {
+      if (!active) {
+        return;
+      }
+      setState({
+        dependencies,
+        result: {
+          status: "error",
+          error: cause instanceof errors.CapxulError ? cause : new errors.CapxulError({
+            code: "UNKNOWN",
+            message: "SDK read failed before returning a CapxulResult.",
+            cause
+          })
+        }
+      });
+    });
+    return () => {
+      active = false;
+    };
+  }, dependencies);
+  if (dependenciesChanged) {
+    return { status: "loading" };
+  }
+  return state.result;
+}
+function didDependenciesChange(previous, next) {
+  if (previous.length !== next.length) {
+    return true;
+  }
+  return previous.some((previousDependency, index) => {
+    return !Object.is(previousDependency, next[index]);
+  });
+}
+
+// src/hooks/singular.ts
+function useMe() {
+  const capxul = useCapxul();
+  return reactQuery.useQuery({
+    queryKey: [capxul.id, "capxul", "me"],
+    queryFn: () => capxul.me.get().then(([error, data]) => {
+      if (error) {
+        throw error;
+      }
+      return data;
+    }).catch((cause) => {
+      if (cause instanceof sdk.CapxulError) {
+        throw cause;
+      }
+      throw new sdk.CapxulError({
+        code: "UNKNOWN",
+        message: "SDK read failed before returning a CapxulResult.",
+        cause
+      });
+    }),
+    staleTime: 3e4
+  });
+}
+function useAccount(_accountId) {
+  return notImplementedQuery("useAccount");
+}
+function useOrganization(_organizationId) {
+  return notImplementedQuery("useOrganization");
+}
+function useMember(_args) {
+  return notImplementedQuery("useMember");
+}
+function useSafe(_safeId) {
+  return notImplementedQuery("useSafe");
+}
+function useTreasury(_organizationId) {
+  return notImplementedQuery("useTreasury");
+}
+function useApiKey(_args) {
+  return notImplementedQuery("useApiKey");
+}
+function useKycProfile(_accountId) {
+  return notImplementedQuery("useKycProfile");
+}
+function useKybProfile(_organizationId) {
+  return notImplementedQuery("useKybProfile");
+}
+function useExternalAccount(_args) {
+  return notImplementedQuery("useExternalAccount");
+}
+function useSubAccount(_subAccountId) {
+  return notImplementedQuery("useSubAccount");
+}
+function useVirtualAccount(_virtualAccountId) {
+  return notImplementedQuery("useVirtualAccount");
+}
+function useVirtualCard(_virtualCardId) {
+  return notImplementedQuery("useVirtualCard");
+}
+function usePayment(_paymentId) {
+  return notImplementedQuery("usePayment");
+}
+function useTransfer(_transferId) {
+  return notImplementedQuery("useTransfer");
+}
+function useBalanceLedgerEntry(_args) {
+  return notImplementedQuery("useBalanceLedgerEntry");
+}
+function useDocument(_documentId) {
+  return notImplementedQuery("useDocument");
+}
+function useWithdrawal(withdrawalId) {
+  const capxul = useCapxul();
+  return useSdkQuery(() => capxul.withdrawals.retrieve(withdrawalId), [
+    capxul,
+    withdrawalId
+  ]);
+}
+function useOperation(operationId) {
+  const capxul = useCapxul();
+  return useSdkQuery(() => capxul.operations.retrieve(operationId), [
+    capxul,
+    operationId
+  ]);
+}
+function useWebhookEndpoint(_endpointId) {
+  return notImplementedQuery("useWebhookEndpoint");
+}
+function useWebhookEvent(_eventId) {
+  return notImplementedQuery("useWebhookEvent");
+}
+
+// src/hooks/list.ts
+function useOrganizations() {
+  return notImplementedQuery("useOrganizations");
+}
+function useMembers(_organizationId) {
+  return notImplementedQuery("useMembers");
+}
+function useExternalAccounts(_args) {
+  return notImplementedQuery("useExternalAccounts");
+}
+function useSubAccounts(_args) {
+  return notImplementedQuery("useSubAccounts");
+}
+function useVirtualAccounts(_filters) {
+  return notImplementedQuery("useVirtualAccounts");
+}
+function useVirtualCards(_filters) {
+  return notImplementedQuery("useVirtualCards");
+}
+function usePayments(_filters) {
+  return notImplementedQuery("usePayments");
+}
+function useOrgPayments(_args) {
+  return notImplementedQuery("useOrgPayments");
+}
+function useTransfers(_filters) {
+  return notImplementedQuery("useTransfers");
+}
+function useOrgTransfers(_args) {
+  return notImplementedQuery("useOrgTransfers");
+}
+function useBalanceLedger(_args) {
+  return notImplementedQuery("useBalanceLedger");
+}
+function useDocuments(_filters) {
+  return notImplementedQuery("useDocuments");
+}
+function useOrgDocuments(_args) {
+  return notImplementedQuery("useOrgDocuments");
+}
+function useWithdrawals(filters) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => capxul.withdrawals.list(filters),
+    [capxul, filters?.limit, filters?.cursor]
+  );
+}
+function useOrgWithdrawals(args) {
+  const capxul = useCapxul();
+  return useSdkQuery(
+    () => capxul.organizations.withdrawals.list(args),
+    [capxul, args.organizationId, args.limit, args.cursor]
+  );
+}
+function useApiKeys(_organizationId) {
+  return notImplementedQuery("useApiKeys");
+}
+function useWebhookEndpoints() {
+  return notImplementedQuery("useWebhookEndpoints");
+}
+function useAuthFlow() {
+  const client = useCapxul();
+  const machine = react.useMemo(() => client.flows.auth(), [client]);
+  const [snapshot, send] = react$1.useActor(machine);
+  return { snapshot, send };
+}
+function useOnboardingFlow() {
+  const client = useCapxul();
+  const machine = react.useMemo(() => client.flows.onboarding(), [client]);
+  const [snapshot, send] = react$1.useActor(machine);
+  return { snapshot, send };
+}
+function useProvisioningFlow() {
+  const client = useCapxul();
+  const machine = react.useMemo(() => client.flows.provisioning(), [client]);
+  const [snapshot, send] = react$1.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 = {}) {
+  const id = options.id ?? "injected";
+  return {
+    id,
+    name: options.name ?? "Injected wallet",
+    kind: "injected",
+    async connect() {
+      const provider = readInjectedProvider();
+      const result = await provider.request({
+        method: "eth_requestAccounts"
+      });
+      const accounts = Array.isArray(result) ? result : void 0;
+      const rawSignerAddress = accounts?.[0];
+      if (rawSignerAddress === void 0 || rawSignerAddress === null) {
+        throw Errors.providerError(
+          "connector",
+          "injected",
+          new Error("Injected wallet did not return an account.")
+        );
+      }
+      const signerAddress = validateAndNormalizeEvmAddress(
+        "signerAddress",
+        rawSignerAddress
+      );
+      return {
+        connectorId: id,
+        connectorKind: "injected",
+        signerAddress
+      };
+    }
+  };
+}
+function localPrivateKeyConnector(options) {
+  if (!options.privateKey || !PRIVATE_KEY_PATTERN.test(options.privateKey)) {
+    throw Errors.invalidInput(
+      "privateKey",
+      "must be a 0x-prefixed 32-byte (64 hex chars) string."
+    );
+  }
+  const safeAddress = validateAndNormalizeEvmAddress(
+    "safeAddress",
+    options.safeAddress
+  );
+  const id = options.id ?? "local-private-key";
+  return {
+    id,
+    name: options.name ?? "Local private key",
+    kind: "local-private-key",
+    autoConnect: true,
+    async connect() {
+      const account = accounts.privateKeyToAccount(options.privateKey);
+      return {
+        connectorId: id,
+        connectorKind: "local-private-key",
+        signerAddress: account.address,
+        safeAddress,
+        signerProvider: {
+          kind: "local-private-key",
+          signerAddress: account.address,
+          safeAddress
+        }
+      };
+    }
+  };
+}
+function readInjectedProvider() {
+  const provider = globalThis.ethereum;
+  if (!provider || typeof provider.request !== "function") {
+    throw Errors.providerError(
+      "connector",
+      "injected",
+      new Error("No injected EIP-1193 wallet was found.")
+    );
+  }
+  return provider;
+}
+function validateAndNormalizeEvmAddress(field, raw) {
+  if (typeof raw !== "string" || !EVM_ADDRESS_PATTERN.test(raw)) {
+    const display = typeof raw === "string" ? raw.slice(0, 64) : String(raw);
+    throw Errors.invalidInput(
+      field,
+      `must be a 0x-prefixed 40 hex char address, got ${display}.`
+    );
+  }
+  try {
+    return viem.getAddress(raw);
+  } catch (cause) {
+    throw Errors.invalidInput(
+      field,
+      `failed EIP-55 checksum: ${cause instanceof Error ? cause.message : String(cause)}.`
+    );
+  }
+}
+
+exports.CapxulClientProvider = CapxulClientProvider;
+exports.CapxulProvider = CapxulProvider;
+exports.CapxulTransportProvider = CapxulTransportProvider;
+exports.createCapxulConfig = createCapxulConfig;
+exports.injectedConnector = injectedConnector;
+exports.localPrivateKeyConnector = localPrivateKeyConnector;
+exports.useAccount = useAccount;
+exports.useApiKey = useApiKey;
+exports.useApiKeys = useApiKeys;
+exports.useAuthFlow = useAuthFlow;
+exports.useBalanceLedger = useBalanceLedger;
+exports.useBalanceLedgerEntry = useBalanceLedgerEntry;
+exports.useCapxul = useCapxul;
+exports.useCapxulStatus = useCapxulStatus;
+exports.useDocument = useDocument;
+exports.useDocuments = useDocuments;
+exports.useExternalAccount = useExternalAccount;
+exports.useExternalAccounts = useExternalAccounts;
+exports.useKybProfile = useKybProfile;
+exports.useKycProfile = useKycProfile;
+exports.useMe = useMe;
+exports.useMember = useMember;
+exports.useMembers = useMembers;
+exports.useOnboardingFlow = useOnboardingFlow;
+exports.useOperation = useOperation;
+exports.useOrgDocuments = useOrgDocuments;
+exports.useOrgPayments = useOrgPayments;
+exports.useOrgTransfers = useOrgTransfers;
+exports.useOrgWithdrawals = useOrgWithdrawals;
+exports.useOrganization = useOrganization;
+exports.useOrganizations = useOrganizations;
+exports.usePayment = usePayment;
+exports.usePayments = usePayments;
+exports.useProvisioningFlow = useProvisioningFlow;
+exports.useSafe = useSafe;
+exports.useSubAccount = useSubAccount;
+exports.useSubAccounts = useSubAccounts;
+exports.useTransfer = useTransfer;
+exports.useTransfers = useTransfers;
+exports.useTreasury = useTreasury;
+exports.useVirtualAccount = useVirtualAccount;
+exports.useVirtualAccounts = useVirtualAccounts;
+exports.useVirtualCard = useVirtualCard;
+exports.useVirtualCards = useVirtualCards;
+exports.useWebhookEndpoint = useWebhookEndpoint;
+exports.useWebhookEndpoints = useWebhookEndpoints;
+exports.useWebhookEvent = useWebhookEvent;
+exports.useWithdrawal = useWithdrawal;
+exports.useWithdrawals = useWithdrawals;