@capxul/sdk-react 0.1.0-alpha.0

package/dist/index.js

@@ -0,0 +1,568 @@
+"use client";
+import { createContext, useContext, useSyncExternalStore, useMemo, useState, useEffect } from 'react';
+import { createCapxulClient, makeHttpTransport, CapxulError as CapxulError$1 } from '@capxul/sdk';
+import { QueryClient, QueryClientProvider, useQuery } from '@tanstack/react-query';
+import { jsx } from 'react/jsx-runtime';
+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
+
+// ../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 = 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: "" }
+});
+function CapxulProvider({
+  config,
+  publishableKey,
+  browserConfig,
+  queryClient,
+  children
+}) {
+  const wiring = useMemo(
+    () => buildWiring({ config, publishableKey, browserConfig }),
+    [config, publishableKey, browserConfig]
+  );
+  const defaultClient = useMemo(
+    () => new QueryClient({
+      defaultOptions: { queries: { staleTime: 3e4 } }
+    }),
+    []
+  );
+  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 });
+}
+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);
+  const sdkConfig = {
+    _transport: transport,
+    publishableKey: browserCfg.mode === "publishable-key" ? browserCfg.publishableKey : void 0
+  };
+  return {
+    client: createCapxulClient(sdkConfig),
+    transport
+  };
+}
+function notImplementedQuery(hookName) {
+  return {
+    status: "error",
+    error: new CapxulError$2({
+      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] = useState({
+    dependencies,
+    result: { status: "loading" }
+  });
+  const dependenciesChanged = didDependenciesChange(
+    state.dependencies,
+    dependencies
+  );
+  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 CapxulError$2 ? cause : new CapxulError$2({
+            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 useQuery({
+    queryKey: [capxul.id, "capxul", "me"],
+    queryFn: () => capxul.me.get().then(([error, data]) => {
+      if (error) {
+        throw error;
+      }
+      return data;
+    }).catch((cause) => {
+      if (cause instanceof CapxulError$1) {
+        throw cause;
+      }
+      throw new CapxulError$1({
+        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 = useMemo(() => client.flows.auth(), [client]);
+  const [snapshot, send] = useActor(machine);
+  return { snapshot, send };
+}
+function useOnboardingFlow() {
+  const client = useCapxul();
+  const machine = useMemo(() => client.flows.onboarding(), [client]);
+  const [snapshot, send] = useActor(machine);
+  return { snapshot, send };
+}
+function useProvisioningFlow() {
+  const client = useCapxul();
+  const machine = useMemo(() => client.flows.provisioning(), [client]);
+  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 = {}) {
+  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 = 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 getAddress(raw);
+  } catch (cause) {
+    throw Errors.invalidInput(
+      field,
+      `failed EIP-55 checksum: ${cause instanceof Error ? cause.message : String(cause)}.`
+    );
+  }
+}
+
+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 };

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@capxul/sdk-react",
+  "version": "0.1.0-alpha.0",
+  "description": "React provider + hooks for the @capxul/sdk headless client.",
+  "license": "UNLICENSED",
+  "private": false,
+  "type": "module",
+  "homepage": "https://capxul.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Xelmar-tech/Capxul.git",
+    "directory": "packages/sdk-react"
+  },
+  "bugs": {
+    "url": "https://github.com/Xelmar-tech/Capxul/issues"
+  },
+  "author": "Capxul (Xelmar Tech Ltd.)",
+  "keywords": [
+    "capxul",
+    "sdk",
+    "react",
+    "hooks",
+    "stablecoin",
+    "payments",
+    "typescript"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@capxul/sdk": "0.1.0-alpha.0",
+    "@repo/config": "0.0.0",
+    "@repo/observability": "0.0.0",
+    "@repo/platform-kernel": "0.0.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5",
+    "@xstate/react": "^5",
+    "react": ">=19.0.0",
+    "viem": ">=2.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5",
+    "@testing-library/react": "^16.3.2",
+    "@xstate/react": "^5",
+    "@types/node": "^22.15.3",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.3",
+    "jsdom": "^29.0.1",
+    "react": "19.2.5",
+    "react-dom": "19.2.5",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "5.9.2",
+    "viem": "2.47.10",
+    "vitest": "^4.1.2",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "check-types": "tsc --noEmit",
+    "proof:contract": "vitest run ops/proof/sdk-contract.test.ts",
+    "proof:drift": "vitest run ops/proof/reset-contract-drift.test.ts",
+    "proof:evidence": "tsx ops/proof/evidence-cli.ts",
+    "proof:plan": "tsx ops/proof/plan-cli.ts",
+    "proof:react-headless": "vitest run ops/proof/react-headless.test.tsx",
+    "test": "vitest run",
+    "test:types": "vitest run --typecheck"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}