@caatinga/client 2.0.2 → 2.2.0

package/README.md

@@ -49,6 +49,8 @@ Supported runtime root exports:
 - `createDefaultBindingAdapter`
 - `CaatingaContractClient`
 - `buildXdr`
+- `createWalletSession`
+- `WALLET_SESSION_STORAGE_KEY`
 
 Supported type-only root exports:
 
@@ -62,12 +64,15 @@ Supported type-only root exports:
 - `CaatingaReadOptions`
 - `CaatingaReadResult`
 - `CaatingaWalletAdapter`
+- `CaatingaWalletCapabilities`
 - `CaatingaXdrBuildResult`
+- `WalletSession`, `WalletSessionOptions`, `WalletSessionState`, `WalletSessionStatus`, `WalletSessionStorage`
 
-Supported subpath export:
+Supported subpath exports:
 
 - `@caatinga/client/freighter` -> `freighterWalletAdapter` (optional)
 - `@caatinga/client/stellar-wallets-kit` -> `createStellarWalletsKitAdapter` (optional)
+- `@caatinga/client/react` -> `WalletProvider`, `useWallet`, `useWalletSession` (optional, needs `react >= 18`)
 
 Primary flow:
 
@@ -122,6 +127,33 @@ export interface CaatingaWalletAdapter {
 
 The default Freighter adapter is exported from `@caatinga/client/freighter`.
 
+## Wallet Session and React Hooks
+
+Wrap any adapter with connection state, persistence, and silent restore:
+
+```ts
+import { createWalletSession } from "@caatinga/client";
+
+const session = createWalletSession(wallet, { persist: true });
+await session.connect();   // modal when available, else getPublicKey()
+await session.restore();   // silent reconnect on page load — never throws
+session.subscribe(() => console.log(session.getState()));
+```
+
+React apps (optional `react >= 18` peer) use the `react` subpath instead of a hand-rolled context:
+
+```tsx
+import { WalletProvider, useWallet } from "@caatinga/client/react";
+
+<WalletProvider adapter={wallet} options={{ persist: true }}>
+  <App />
+</WalletProvider>;
+
+const { publicKey, connected, connecting, error, connect, disconnect } = useWallet();
+```
+
+Full guide: [docs/wallets.md](https://github.com/Dione-b/caatinga/blob/main/docs/wallets.md).
+
 ## Debug Output Rules
 
 - XDR data is omitted by default
@@ -151,5 +183,5 @@ Common codes include:
 
 - this package does not replace Stellar CLI, Stellar SDK, Soroban SDK, or generated bindings
 - manual SCVal serialization and manual XDR parsing are out of scope
-- React hooks, multisig orchestration, backend signing, and non-documented wallet integrations are not part of the supported contract
+- multisig orchestration, backend signing, and non-documented wallet integrations are not part of the supported contract
 - private module paths and undocumented helpers are less stable than the exports listed above

package/dist/chunk-HKAMQDUV.js

@@ -0,0 +1,169 @@
+// src/wallet/with-wallet-timeout.ts
+import { CaatingaError, CaatingaErrorCode } from "@caatinga/core/browser";
+function withWalletTimeout(label, timeoutMs, fn) {
+  if (timeoutMs === void 0 || timeoutMs <= 0) {
+    return fn();
+  }
+  let timedOut = false;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      timedOut = true;
+      reject(
+        new CaatingaError(
+          `Wallet "${label}" timed out after ${timeoutMs}ms.`,
+          CaatingaErrorCode.WALLET_TIMEOUT,
+          "Ensure the wallet adapter rejects on user dismissal, or increase walletTimeout."
+        )
+      );
+    }, timeoutMs);
+    fn().then(
+      (value) => {
+        if (timedOut) {
+          return;
+        }
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        if (timedOut) {
+          return;
+        }
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+
+// src/wallet/wallet-session.ts
+var WALLET_SESSION_STORAGE_KEY = "caatinga:wallet-session";
+function defaultStorage() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  try {
+    return window.localStorage;
+  } catch {
+    return void 0;
+  }
+}
+function toError(value) {
+  return value instanceof Error ? value : new Error(String(value));
+}
+function createWalletSession(adapter, options = {}) {
+  const capabilities = adapter;
+  const storage = options.persist ? options.storage ?? defaultStorage() : void 0;
+  const storageKey = options.storageKey ?? WALLET_SESSION_STORAGE_KEY;
+  const listeners = /* @__PURE__ */ new Set();
+  let state = {
+    status: "disconnected",
+    publicKey: null,
+    error: null
+  };
+  function setState(next) {
+    state = next;
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+  function persistConnection() {
+    if (!storage) {
+      return;
+    }
+    const payload = { v: 1 };
+    const walletId = capabilities.getWalletId?.();
+    if (walletId) {
+      payload.walletId = walletId;
+    }
+    try {
+      storage.setItem(storageKey, JSON.stringify(payload));
+    } catch {
+    }
+  }
+  function clearPersisted() {
+    try {
+      storage?.removeItem(storageKey);
+    } catch {
+    }
+  }
+  function readPersisted() {
+    if (!storage) {
+      return null;
+    }
+    try {
+      const raw = storage.getItem(storageKey);
+      if (!raw) {
+        return null;
+      }
+      const parsed = JSON.parse(raw);
+      return parsed && parsed.v === 1 ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+  async function requestPublicKey(label, viaModal) {
+    const request = viaModal && capabilities.openModal ? () => capabilities.openModal() : () => adapter.getPublicKey();
+    return withWalletTimeout(label, options.timeout, request);
+  }
+  async function connect() {
+    setState({ status: "connecting", publicKey: null, error: null });
+    try {
+      const publicKey = await requestPublicKey("connect", true);
+      setState({ status: "connected", publicKey, error: null });
+      persistConnection();
+      return publicKey;
+    } catch (error) {
+      setState({ status: "disconnected", publicKey: null, error: toError(error) });
+      throw error;
+    }
+  }
+  async function disconnect() {
+    try {
+      await capabilities.disconnect?.();
+    } finally {
+      clearPersisted();
+      setState({ status: "disconnected", publicKey: null, error: null });
+    }
+  }
+  async function restore() {
+    if (state.status === "connected") {
+      return state.publicKey;
+    }
+    const persisted = readPersisted();
+    if (!persisted) {
+      return null;
+    }
+    setState({ status: "connecting", publicKey: null, error: null });
+    try {
+      if (persisted.walletId) {
+        capabilities.setWallet?.(persisted.walletId);
+      }
+      const publicKey = await requestPublicKey("restore", false);
+      setState({ status: "connected", publicKey, error: null });
+      return publicKey;
+    } catch {
+      clearPersisted();
+      setState({ status: "disconnected", publicKey: null, error: null });
+      return null;
+    }
+  }
+  return {
+    adapter,
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    connect,
+    disconnect,
+    restore
+  };
+}
+
+export {
+  withWalletTimeout,
+  WALLET_SESSION_STORAGE_KEY,
+  createWalletSession
+};

package/dist/index.cjs

@@ -21,15 +21,181 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CaatingaContractClient: () => CaatingaContractClient,
+  WALLET_SESSION_STORAGE_KEY: () => WALLET_SESSION_STORAGE_KEY,
   buildXdr: () => buildXdr,
   createCaatingaClient: () => createCaatingaClient,
   createDefaultBindingAdapter: () => createDefaultBindingAdapter,
+  createWalletSession: () => createWalletSession,
   resolveContractId: () => resolveContractId
 });
 module.exports = __toCommonJS(index_exports);
 
-// src/artifacts/resolve-contract-id.ts
+// src/wallet/with-wallet-timeout.ts
 var import_browser = require("@caatinga/core/browser");
+function withWalletTimeout(label, timeoutMs, fn) {
+  if (timeoutMs === void 0 || timeoutMs <= 0) {
+    return fn();
+  }
+  let timedOut = false;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      timedOut = true;
+      reject(
+        new import_browser.CaatingaError(
+          `Wallet "${label}" timed out after ${timeoutMs}ms.`,
+          import_browser.CaatingaErrorCode.WALLET_TIMEOUT,
+          "Ensure the wallet adapter rejects on user dismissal, or increase walletTimeout."
+        )
+      );
+    }, timeoutMs);
+    fn().then(
+      (value) => {
+        if (timedOut) {
+          return;
+        }
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error) => {
+        if (timedOut) {
+          return;
+        }
+        clearTimeout(timer);
+        reject(error);
+      }
+    );
+  });
+}
+
+// src/wallet/wallet-session.ts
+var WALLET_SESSION_STORAGE_KEY = "caatinga:wallet-session";
+function defaultStorage() {
+  if (typeof window === "undefined") {
+    return void 0;
+  }
+  try {
+    return window.localStorage;
+  } catch {
+    return void 0;
+  }
+}
+function toError(value) {
+  return value instanceof Error ? value : new Error(String(value));
+}
+function createWalletSession(adapter, options = {}) {
+  const capabilities = adapter;
+  const storage = options.persist ? options.storage ?? defaultStorage() : void 0;
+  const storageKey = options.storageKey ?? WALLET_SESSION_STORAGE_KEY;
+  const listeners = /* @__PURE__ */ new Set();
+  let state = {
+    status: "disconnected",
+    publicKey: null,
+    error: null
+  };
+  function setState(next) {
+    state = next;
+    for (const listener of listeners) {
+      listener();
+    }
+  }
+  function persistConnection() {
+    if (!storage) {
+      return;
+    }
+    const payload = { v: 1 };
+    const walletId = capabilities.getWalletId?.();
+    if (walletId) {
+      payload.walletId = walletId;
+    }
+    try {
+      storage.setItem(storageKey, JSON.stringify(payload));
+    } catch {
+    }
+  }
+  function clearPersisted() {
+    try {
+      storage?.removeItem(storageKey);
+    } catch {
+    }
+  }
+  function readPersisted() {
+    if (!storage) {
+      return null;
+    }
+    try {
+      const raw = storage.getItem(storageKey);
+      if (!raw) {
+        return null;
+      }
+      const parsed = JSON.parse(raw);
+      return parsed && parsed.v === 1 ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+  async function requestPublicKey(label, viaModal) {
+    const request = viaModal && capabilities.openModal ? () => capabilities.openModal() : () => adapter.getPublicKey();
+    return withWalletTimeout(label, options.timeout, request);
+  }
+  async function connect() {
+    setState({ status: "connecting", publicKey: null, error: null });
+    try {
+      const publicKey = await requestPublicKey("connect", true);
+      setState({ status: "connected", publicKey, error: null });
+      persistConnection();
+      return publicKey;
+    } catch (error) {
+      setState({ status: "disconnected", publicKey: null, error: toError(error) });
+      throw error;
+    }
+  }
+  async function disconnect() {
+    try {
+      await capabilities.disconnect?.();
+    } finally {
+      clearPersisted();
+      setState({ status: "disconnected", publicKey: null, error: null });
+    }
+  }
+  async function restore() {
+    if (state.status === "connected") {
+      return state.publicKey;
+    }
+    const persisted = readPersisted();
+    if (!persisted) {
+      return null;
+    }
+    setState({ status: "connecting", publicKey: null, error: null });
+    try {
+      if (persisted.walletId) {
+        capabilities.setWallet?.(persisted.walletId);
+      }
+      const publicKey = await requestPublicKey("restore", false);
+      setState({ status: "connected", publicKey, error: null });
+      return publicKey;
+    } catch {
+      clearPersisted();
+      setState({ status: "disconnected", publicKey: null, error: null });
+      return null;
+    }
+  }
+  return {
+    adapter,
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    connect,
+    disconnect,
+    restore
+  };
+}
+
+// src/artifacts/resolve-contract-id.ts
+var import_browser2 = require("@caatinga/core/browser");
 function resolveContractId(input) {
   if (input.explicitContractId) {
     return input.explicitContractId;
@@ -39,9 +205,9 @@ function resolveContractId(input) {
     return contractId;
   }
   const hint = formatMissingContractArtifactHint(input.artifacts, input.network, input.contract);
-  throw new import_browser.CaatingaError(
+  throw new import_browser2.CaatingaError(
     `No contract artifact found for "${input.contract}" on "${input.network}".`,
-    import_browser.CaatingaErrorCode.CONTRACT_ARTIFACT_NOT_FOUND,
+    import_browser2.CaatingaErrorCode.CONTRACT_ARTIFACT_NOT_FOUND,
     hint
   );
 }
@@ -72,14 +238,21 @@ function formatMissingContractArtifactHint(artifacts, network, contract) {
 }
 
 // src/bindings/default-binding-adapter.ts
-var import_browser2 = require("@caatinga/core/browser");
+var import_browser3 = require("@caatinga/core/browser");
 function createDefaultBindingAdapter(binding) {
   return {
     createClient({ contractId, publicKey, rpcUrl, networkPassphrase }) {
+      if (binding.__caatingaPlaceholder) {
+        throw new import_browser3.CaatingaError(
+          "Placeholder bindings are still in use; the app cannot reach the contract.",
+          import_browser3.CaatingaErrorCode.PLACEHOLDER_BINDING,
+          "Run `caatinga generate <contract> --network <network>`, then restart the dev server."
+        );
+      }
       if (!binding.Client) {
-        throw new import_browser2.CaatingaError(
+        throw new import_browser3.CaatingaError(
           "Generated binding does not export Client.",
-          import_browser2.CaatingaErrorCode.BINDING_CLIENT_NOT_FOUND,
+          import_browser3.CaatingaErrorCode.BINDING_CLIENT_NOT_FOUND,
           "Regenerate bindings with Stellar CLI."
         );
       }
@@ -94,9 +267,9 @@ function createDefaultBindingAdapter(binding) {
       const candidate = client;
       const fn = candidate[method];
       if (typeof fn !== "function") {
-        throw new import_browser2.CaatingaError(
+        throw new import_browser3.CaatingaError(
           `Binding method "${method}" was not found.`,
-          import_browser2.CaatingaErrorCode.BINDING_METHOD_NOT_FOUND,
+          import_browser3.CaatingaErrorCode.BINDING_METHOD_NOT_FOUND,
           "Check the contract method name or regenerate bindings."
         );
       }
@@ -112,7 +285,7 @@ var import_browser8 = require("@caatinga/core/browser");
 var import_browser7 = require("@caatinga/core/browser");
 
 // src/xdr/build-xdr.ts
-var import_browser3 = require("@caatinga/core/browser");
+var import_browser4 = require("@caatinga/core/browser");
 async function buildXdr(input) {
   try {
     const transaction = input.transaction;
@@ -122,12 +295,12 @@ async function buildXdr(input) {
       try {
         preparedTransaction = await transaction.prepare();
       } catch (error) {
-        if (error instanceof import_browser3.CaatingaError) {
+        if (error instanceof import_browser4.CaatingaError) {
           throw error;
         }
-        throw new import_browser3.CaatingaError(
+        throw new import_browser4.CaatingaError(
           `Failed to prepare XDR for "${input.contractName}.${input.method}".`,
-          import_browser3.CaatingaErrorCode.XDR_PREPARE_FAILED,
+          import_browser4.CaatingaErrorCode.XDR_PREPARE_FAILED,
           `RPC: ${input.rpcUrl}. Check connectivity, simulation errors, and binding compatibility.`,
           error
         );
@@ -145,12 +318,12 @@ async function buildXdr(input) {
       ...input.debug ? { raw: preparedTransaction } : {}
     };
   } catch (error) {
-    if (error instanceof import_browser3.CaatingaError) {
+    if (error instanceof import_browser4.CaatingaError) {
       throw error;
     }
-    throw new import_browser3.CaatingaError(
+    throw new import_browser4.CaatingaError(
       `Failed to build XDR for "${input.contractName}.${input.method}".`,
-      import_browser3.CaatingaErrorCode.XDR_BUILD_FAILED,
+      import_browser4.CaatingaErrorCode.XDR_BUILD_FAILED,
       "Check the generated binding transaction object.",
       error
     );
@@ -159,52 +332,15 @@ async function buildXdr(input) {
 function readXdr(transaction) {
   const candidate = transaction;
   if (typeof candidate.toXDR !== "function") {
-    throw new import_browser3.CaatingaError(
+    throw new import_browser4.CaatingaError(
       "Binding transaction object does not expose toXDR().",
-      import_browser3.CaatingaErrorCode.XDR_BUILD_FAILED,
+      import_browser4.CaatingaErrorCode.XDR_BUILD_FAILED,
       "Regenerate bindings or provide a compatible binding adapter."
     );
   }
   return candidate.toXDR();
 }
 
-// src/wallet/with-wallet-timeout.ts
-var import_browser4 = require("@caatinga/core/browser");
-function withWalletTimeout(label, timeoutMs, fn) {
-  if (timeoutMs === void 0 || timeoutMs <= 0) {
-    return fn();
-  }
-  let timedOut = false;
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => {
-      timedOut = true;
-      reject(
-        new import_browser4.CaatingaError(
-          `Wallet "${label}" timed out after ${timeoutMs}ms.`,
-          import_browser4.CaatingaErrorCode.WALLET_TIMEOUT,
-          "Ensure the wallet adapter rejects on user dismissal, or increase walletTimeout."
-        )
-      );
-    }, timeoutMs);
-    fn().then(
-      (value) => {
-        if (timedOut) {
-          return;
-        }
-        clearTimeout(timer);
-        resolve(value);
-      },
-      (error) => {
-        if (timedOut) {
-          return;
-        }
-        clearTimeout(timer);
-        reject(error);
-      }
-    );
-  });
-}
-
 // src/client/invoke-args.ts
 function splitArgsAndOptions(argsOrOptions, maybeOptions) {
   return {
@@ -529,8 +665,10 @@ function createCaatingaClient(config) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CaatingaContractClient,
+  WALLET_SESSION_STORAGE_KEY,
   buildXdr,
   createCaatingaClient,
   createDefaultBindingAdapter,
+  createWalletSession,
   resolveContractId
 });

package/dist/index.d.cts

@@ -1,5 +1,6 @@
 import { a as CaatingaBindingAdapter, b as CaatingaClientConfig, c as CaatingaContractRegistration, d as CaatingaXdrBuildResult, e as CaatingaInvokeOptions, f as CaatingaInvokeResult, g as CaatingaReadOptions, h as CaatingaReadResult } from './types-D4XEyX4J.cjs';
 export { i as CaatingaInvokeStatus, j as CaatingaNetwork, C as CaatingaWalletAdapter } from './types-D4XEyX4J.cjs';
+export { C as CaatingaWalletCapabilities, W as WALLET_SESSION_STORAGE_KEY, a as WalletSession, b as WalletSessionOptions, c as WalletSessionState, d as WalletSessionStatus, e as WalletSessionStorage, f as createWalletSession } from './wallet-session-ed2Dgs9A.cjs';
 import { CaatingaArtifacts } from '@caatinga/core/browser';
 
 declare function resolveContractId(input: {
@@ -16,6 +17,12 @@ interface BindingWithClient {
         rpcUrl: string;
         networkPassphrase: string;
     }) => unknown;
+    /**
+     * Set by the scaffolded placeholder binding (`src/contracts/generated/.../index.ts`)
+     * that ships with templates so they type-check before `caatinga generate`. Real
+     * Stellar CLI bindings never set this, so its presence means generate hasn't run.
+     */
+    __caatingaPlaceholder?: boolean;
 }
 declare function createDefaultBindingAdapter(binding: BindingWithClient): CaatingaBindingAdapter;
 

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 import { a as CaatingaBindingAdapter, b as CaatingaClientConfig, c as CaatingaContractRegistration, d as CaatingaXdrBuildResult, e as CaatingaInvokeOptions, f as CaatingaInvokeResult, g as CaatingaReadOptions, h as CaatingaReadResult } from './types-D4XEyX4J.js';
 export { i as CaatingaInvokeStatus, j as CaatingaNetwork, C as CaatingaWalletAdapter } from './types-D4XEyX4J.js';
+export { C as CaatingaWalletCapabilities, W as WALLET_SESSION_STORAGE_KEY, a as WalletSession, b as WalletSessionOptions, c as WalletSessionState, d as WalletSessionStatus, e as WalletSessionStorage, f as createWalletSession } from './wallet-session-DeLp8S1c.js';
 import { CaatingaArtifacts } from '@caatinga/core/browser';
 
 declare function resolveContractId(input: {
@@ -16,6 +17,12 @@ interface BindingWithClient {
         rpcUrl: string;
         networkPassphrase: string;
     }) => unknown;
+    /**
+     * Set by the scaffolded placeholder binding (`src/contracts/generated/.../index.ts`)
+     * that ships with templates so they type-check before `caatinga generate`. Real
+     * Stellar CLI bindings never set this, so its presence means generate hasn't run.
+     */
+    __caatingaPlaceholder?: boolean;
 }
 declare function createDefaultBindingAdapter(binding: BindingWithClient): CaatingaBindingAdapter;