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

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # @capxul/sdk-react
 
-## 0.1.0-alpha.6
+## 0.1.0-alpha.8
 
 ### Minor Changes
 
@@ -32,21 +32,7 @@
 ### Patch Changes
 
 - Updated dependencies [57203a4]
-  - @capxul/sdk@0.1.0-alpha.6
-
-## 0.1.0-alpha.5
-
-### Patch Changes
-
-- Widen the React peer dependency to `>=18.2.0 <20` so React 18-era Ink 5
-  CLI apps can install `@capxul/sdk-react` without forcing React 19 into
-  Ink's React reconciler. The provider and hooks only use React 18-compatible
-  APIs (`createContext`, `useContext`, `useMemo`, `useEffect`, `useState`, and
-  `useSyncExternalStore`), preserving React 19 compatibility while unblocking
-  React 18 hosts.
-
-- Updated dependencies
-  - @capxul/sdk@0.1.0-alpha.5
+  - @capxul/sdk@0.1.0-alpha.8
 
 ## 0.1.0-alpha.4
 

package/README.md

@@ -40,7 +40,12 @@ import { CapxulProvider } from "@capxul/sdk-react";
 
 export default function RootLayout({ children }) {
   return (
-    <CapxulProvider publishableKey={process.env.NEXT_PUBLIC_CAPXUL_KEY!}>
+    <CapxulProvider
+      config={{
+        mode: "publishable-key",
+        publishableKey: process.env.NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY!,
+      }}
+    >
       {children}
     </CapxulProvider>
   );
@@ -119,6 +124,21 @@ subscription against the transport singleton — only the components
 that actually call it re-render when state changes. The provider
 itself never re-renders.
 
+## Publishable-key proof status
+
+The publishable-key path is runtime-proven where the repo can run it
+without secrets:
+
+| Surface | Runtime proof | Expected safe signal |
+|---|---|---|
+| Provider + `useMe()` | `corepack pnpm --filter @capxul/sdk-react check-types` plus the headless proof tests under `packages/sdk-react/ops/proof` | provider reaches `useCapxulStatus().status === "ready"` after one bootstrap request |
+| Reference CLI mock | `corepack pnpm --filter @capxul/reference-cli build && node apps/reference-cli/dist/cli.js bootstrap probe --mock --json` | `ok:true`, `mode:"publishable-key"`, `bootstrapRequests:1`, `authRequests:1`, `keyLengthClass:"provided"` |
+| Reference CLI live | same command without `--mock`, with `CAPXUL_REF_PUBLISHABLE_KEY` and optional `CAPXUL_REF_BOOTSTRAP_URL` set locally | success only when the key/origin/runtime are valid; otherwise sanitized SDK error JSON |
+
+Do not paste or commit publishable keys, session tokens, Convex JWTs,
+cookies, or provider payloads. Proof output reports only
+`keyLengthClass`.
+
 ## Hooks catalogue
 
 | Surface | Hook |

package/dist/index.cjs

@@ -110,7 +110,12 @@ var Errors = {
     "Idempotency key was already used for a different request",
     { details }
   ),
-  emailDeliveryFailed: (detail) => new CapxulError("EMAIL_DELIVERY_FAILED", `Failed to send email: ${detail}`),
+  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
@@ -217,6 +222,48 @@ function createReactDataClient(convexUrl, sessionStore) {
     }
   };
 }
+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();
+    },
+    close: () => {
+      closed = true;
+      client?.close();
+      client = null;
+    }
+  };
+}
 function CapxulProvider({
   config,
   sessionStore,
@@ -246,12 +293,12 @@ function CapxulProvider({
 function buildWiring(config, sessionStore) {
   const validated = createCapxulConfig(config);
   const transport = sdk.makeHttpTransport(validated);
-  const dataClient = validated.mode === "build-time-urls" ? createReactDataClient(validated.convexUrl, sessionStore) : null;
+  const dataClient = validated.mode === "build-time-urls" ? createReactDataClient(validated.convexUrl, sessionStore) : createLazyReactDataClient(transport, sessionStore);
   const sdkConfig = {
     _transport: transport,
     publishableKey: validated.mode === "publishable-key" ? validated.publishableKey : void 0,
     data: dataClient ?? void 0,
-    auth: dataClient ? {
+    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

package/dist/index.js

@@ -108,7 +108,12 @@ var Errors = {
     "Idempotency key was already used for a different request",
     { details }
   ),
-  emailDeliveryFailed: (detail) => new CapxulError("EMAIL_DELIVERY_FAILED", `Failed to send email: ${detail}`),
+  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
@@ -215,6 +220,48 @@ function createReactDataClient(convexUrl, sessionStore) {
     }
   };
 }
+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();
+    },
+    close: () => {
+      closed = true;
+      client?.close();
+      client = null;
+    }
+  };
+}
 function CapxulProvider({
   config,
   sessionStore,
@@ -244,12 +291,12 @@ function CapxulProvider({
 function buildWiring(config, sessionStore) {
   const validated = createCapxulConfig(config);
   const transport = makeHttpTransport(validated);
-  const dataClient = validated.mode === "build-time-urls" ? createReactDataClient(validated.convexUrl, sessionStore) : null;
+  const dataClient = validated.mode === "build-time-urls" ? createReactDataClient(validated.convexUrl, sessionStore) : createLazyReactDataClient(transport, sessionStore);
   const sdkConfig = {
     _transport: transport,
     publishableKey: validated.mode === "publishable-key" ? validated.publishableKey : void 0,
     data: dataClient ?? void 0,
-    auth: dataClient ? {
+    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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/sdk-react",
-  "version": "0.1.0-alpha.6",
+  "version": "0.1.0-alpha.8",
   "description": "React provider + hooks for the @capxul/sdk headless client.",
   "license": "UNLICENSED",
   "private": false,
@@ -46,13 +46,13 @@
     "access": "public"
   },
   "dependencies": {
-    "@capxul/sdk": "0.1.0-alpha.6"
+    "@capxul/sdk": "0.1.0-alpha.8"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5",
     "@xstate/react": "^5",
     "convex": ">=1.0.0",
-    "react": ">=18.2.0 <20",
+    "react": ">=19.0.0",
     "viem": ">=2.0.0"
   },
   "devDependencies": {