@caatinga/client 2.0.2 → 2.2.0

package/dist/index.js

@@ -1,3 +1,9 @@
+import {
+  WALLET_SESSION_STORAGE_KEY,
+  createWalletSession,
+  withWalletTimeout
+} from "./chunk-HKAMQDUV.js";
+
 // src/artifacts/resolve-contract-id.ts
 import { CaatingaError, CaatingaErrorCode } from "@caatinga/core/browser";
 function resolveContractId(input) {
@@ -46,6 +52,13 @@ import { CaatingaError as CaatingaError2, CaatingaErrorCode as CaatingaErrorCode
 function createDefaultBindingAdapter(binding) {
   return {
     createClient({ contractId, publicKey, rpcUrl, networkPassphrase }) {
+      if (binding.__caatingaPlaceholder) {
+        throw new CaatingaError2(
+          "Placeholder bindings are still in use; the app cannot reach the contract.",
+          CaatingaErrorCode2.PLACEHOLDER_BINDING,
+          "Run `caatinga generate <contract> --network <network>`, then restart the dev server."
+        );
+      }
       if (!binding.Client) {
         throw new CaatingaError2(
           "Generated binding does not export Client.",
@@ -76,10 +89,10 @@ function createDefaultBindingAdapter(binding) {
 }
 
 // src/client/create-caatinga-client.ts
-import { CaatingaError as CaatingaError8, CaatingaErrorCode as CaatingaErrorCode8 } from "@caatinga/core/browser";
+import { CaatingaError as CaatingaError7, CaatingaErrorCode as CaatingaErrorCode7 } from "@caatinga/core/browser";
 
 // src/client/caatinga-contract-client.ts
-import { CaatingaError as CaatingaError7, CaatingaErrorCode as CaatingaErrorCode7 } from "@caatinga/core/browser";
+import { CaatingaError as CaatingaError6, CaatingaErrorCode as CaatingaErrorCode6 } from "@caatinga/core/browser";
 
 // src/xdr/build-xdr.ts
 import { CaatingaError as CaatingaError3, CaatingaErrorCode as CaatingaErrorCode3 } from "@caatinga/core/browser";
@@ -138,43 +151,6 @@ function readXdr(transaction) {
   return candidate.toXDR();
 }
 
-// src/wallet/with-wallet-timeout.ts
-import { CaatingaError as CaatingaError4, CaatingaErrorCode as CaatingaErrorCode4 } 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 CaatingaError4(
-          `Wallet "${label}" timed out after ${timeoutMs}ms.`,
-          CaatingaErrorCode4.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 {
@@ -214,7 +190,7 @@ function splitReadArgsAndOptions(argsOrOptions, maybeOptions) {
 }
 
 // src/client/transaction-simulate.ts
-import { CaatingaError as CaatingaError5, CaatingaErrorCode as CaatingaErrorCode5 } from "@caatinga/core/browser";
+import { CaatingaError as CaatingaError4, CaatingaErrorCode as CaatingaErrorCode4 } from "@caatinga/core/browser";
 async function prepareReadTransaction(transaction, contractName, method, rpcUrl) {
   const candidate = transaction;
   if (typeof candidate.prepare !== "function") {
@@ -223,12 +199,12 @@ async function prepareReadTransaction(transaction, contractName, method, rpcUrl)
   try {
     return await candidate.prepare.call(transaction);
   } catch (error) {
-    if (error instanceof CaatingaError5) {
+    if (error instanceof CaatingaError4) {
       throw error;
     }
-    throw new CaatingaError5(
+    throw new CaatingaError4(
       `Failed to prepare XDR for "${contractName}.${method}".`,
-      CaatingaErrorCode5.XDR_PREPARE_FAILED,
+      CaatingaErrorCode4.XDR_PREPARE_FAILED,
       `RPC: ${rpcUrl}. Check connectivity, simulation errors, and binding compatibility.`,
       error
     );
@@ -241,15 +217,15 @@ function readSimulationResult(raw, contractName, method) {
       return result;
     }
   }
-  throw new CaatingaError5(
+  throw new CaatingaError4(
     `Simulation for "${contractName}.${method}" did not return a result.`,
-    CaatingaErrorCode5.READ_RESULT_MISSING,
+    CaatingaErrorCode4.READ_RESULT_MISSING,
     `Expected "${contractName}.${method}" to expose a simulation result. Use debugRaw to inspect the generated binding output.`
   );
 }
 
 // src/client/transaction-submit.ts
-import { CaatingaError as CaatingaError6, CaatingaErrorCode as CaatingaErrorCode6 } from "@caatinga/core/browser";
+import { CaatingaError as CaatingaError5, CaatingaErrorCode as CaatingaErrorCode5 } from "@caatinga/core/browser";
 async function submitTransaction(transaction, signTransaction, contractName, method, rpcUrl) {
   const candidate = transaction;
   if (typeof candidate.signAndSend === "function") {
@@ -258,12 +234,12 @@ async function submitTransaction(transaction, signTransaction, contractName, met
       assertSubmitResultRecognized(raw, contractName, method);
       return raw;
     } catch (error) {
-      if (error instanceof CaatingaError6) {
+      if (error instanceof CaatingaError5) {
         throw error;
       }
-      throw new CaatingaError6(
+      throw new CaatingaError5(
         `Failed to submit XDR for "${contractName}.${method}".`,
-        CaatingaErrorCode6.XDR_SUBMIT_FAILED,
+        CaatingaErrorCode5.XDR_SUBMIT_FAILED,
         `RPC: ${rpcUrl}. Check wallet signature and RPC connectivity.`,
         error
       );
@@ -275,20 +251,20 @@ async function submitTransaction(transaction, signTransaction, contractName, met
       assertSubmitResultRecognized(raw, contractName, method);
       return raw;
     } catch (error) {
-      if (error instanceof CaatingaError6) {
+      if (error instanceof CaatingaError5) {
         throw error;
       }
-      throw new CaatingaError6(
+      throw new CaatingaError5(
         `Failed to submit XDR for "${contractName}.${method}".`,
-        CaatingaErrorCode6.XDR_SUBMIT_FAILED,
+        CaatingaErrorCode5.XDR_SUBMIT_FAILED,
         `RPC: ${rpcUrl}. Check wallet signature and RPC connectivity.`,
         error
       );
     }
   }
-  throw new CaatingaError6(
+  throw new CaatingaError5(
     `Binding transaction for "${contractName}.${method}" cannot be submitted.`,
-    CaatingaErrorCode6.XDR_SUBMIT_FAILED,
+    CaatingaErrorCode5.XDR_SUBMIT_FAILED,
     "Regenerate bindings or provide a compatible binding adapter."
   );
 }
@@ -302,9 +278,9 @@ function assertSubmitResultRecognized(raw, contractName, method) {
   if (hasTransactionId || hasResult) {
     return;
   }
-  throw new CaatingaError6(
+  throw new CaatingaError5(
     `Submit returned an unrecognized payload for "${contractName}.${method}".`,
-    CaatingaErrorCode6.XDR_RESULT_FAILED,
+    CaatingaErrorCode5.XDR_RESULT_FAILED,
     "Expected txHash, transactionHash, hash, sendTransactionResponse.hash, or result on the submit response. Use debugRaw to inspect the binding output."
   );
 }
@@ -369,20 +345,20 @@ var CaatingaContractClient = class {
           })
         );
       } catch (error) {
-        if (error instanceof CaatingaError7) {
+        if (error instanceof CaatingaError6) {
           throw error;
         }
-        throw new CaatingaError7(
+        throw new CaatingaError6(
           `Failed to sign XDR for "${this.contractName}.${method}".`,
-          CaatingaErrorCode7.XDR_SIGN_FAILED,
+          CaatingaErrorCode6.XDR_SIGN_FAILED,
           "Connect a wallet and approve the transaction.",
           error
         );
       }
       if (typeof signedXdr !== "string" || signedXdr.trim().length === 0) {
-        throw new CaatingaError7(
+        throw new CaatingaError6(
           `Failed to sign XDR for "${this.contractName}.${method}".`,
-          CaatingaErrorCode7.XDR_SIGN_FAILED,
+          CaatingaErrorCode6.XDR_SIGN_FAILED,
           "Wallet returned an empty or invalid signed XDR. The user may have dismissed the signing prompt.",
           signedXdr
         );
@@ -397,9 +373,9 @@ var CaatingaContractClient = class {
       this.config.network.rpcUrl
     );
     if (typeof transaction.signAndSend === "function" && signedXdr === void 0) {
-      throw new CaatingaError7(
+      throw new CaatingaError6(
         `Failed to sign XDR for "${this.contractName}.${method}".`,
-        CaatingaErrorCode7.XDR_SIGN_FAILED,
+        CaatingaErrorCode6.XDR_SIGN_FAILED,
         "Wallet returned an empty or invalid signed XDR. The generated transaction did not request a wallet signature."
       );
     }
@@ -459,12 +435,12 @@ var CaatingaContractClient = class {
         () => this.config.wallet.getPublicKey()
       );
     } catch (error) {
-      if (error instanceof CaatingaError7) {
+      if (error instanceof CaatingaError6) {
         throw error;
       }
-      throw new CaatingaError7(
+      throw new CaatingaError6(
         `Wallet is not connected or the public key is unavailable for "${this.contractName}".`,
-        CaatingaErrorCode7.WALLET_NOT_CONNECTED,
+        CaatingaErrorCode6.WALLET_NOT_CONNECTED,
         "Connect the wallet and grant account access, then retry.",
         error
       );
@@ -486,9 +462,9 @@ function createCaatingaClient(config) {
     contract(contractName) {
       const registration = config.contracts[contractName];
       if (!registration) {
-        throw new CaatingaError8(
+        throw new CaatingaError7(
           `Contract "${contractName}" is not registered.`,
-          CaatingaErrorCode8.CONTRACT_NOT_FOUND,
+          CaatingaErrorCode7.CONTRACT_NOT_FOUND,
           "Add the contract binding to createCaatingaClient()."
         );
       }
@@ -498,8 +474,10 @@ function createCaatingaClient(config) {
 }
 export {
   CaatingaContractClient,
+  WALLET_SESSION_STORAGE_KEY,
   buildXdr,
   createCaatingaClient,
   createDefaultBindingAdapter,
+  createWalletSession,
   resolveContractId
 };

package/dist/react.cjs

@@ -0,0 +1,252 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react.ts
+var react_exports = {};
+__export(react_exports, {
+  WALLET_SESSION_STORAGE_KEY: () => WALLET_SESSION_STORAGE_KEY,
+  WalletProvider: () => WalletProvider,
+  createWalletSession: () => createWalletSession,
+  useWallet: () => useWallet,
+  useWalletSession: () => useWalletSession
+});
+module.exports = __toCommonJS(react_exports);
+
+// src/react/wallet-provider.ts
+var import_react = require("react");
+
+// 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/react/wallet-provider.ts
+var WalletSessionContext = (0, import_react.createContext)(null);
+function WalletProvider(props) {
+  const { adapter, session: providedSession, autoConnect, children } = props;
+  const initialOptions = (0, import_react.useRef)(props.options);
+  const session = (0, import_react.useMemo)(() => {
+    if (providedSession) {
+      return providedSession;
+    }
+    if (!adapter) {
+      throw new Error("WalletProvider requires an `adapter` or a `session` prop.");
+    }
+    return createWalletSession(adapter, initialOptions.current);
+  }, [providedSession, adapter]);
+  const shouldAutoConnect = autoConnect ?? initialOptions.current?.persist ?? false;
+  const restoredFor = (0, import_react.useRef)(null);
+  (0, import_react.useEffect)(() => {
+    if (!shouldAutoConnect || restoredFor.current === session) {
+      return;
+    }
+    restoredFor.current = session;
+    void session.restore();
+  }, [session, shouldAutoConnect]);
+  return (0, import_react.createElement)(WalletSessionContext.Provider, { value: session }, children);
+}
+function useWalletSession() {
+  const session = (0, import_react.useContext)(WalletSessionContext);
+  if (!session) {
+    throw new Error("useWalletSession must be used within a <WalletProvider>.");
+  }
+  return session;
+}
+function useWallet() {
+  const session = useWalletSession();
+  const state = (0, import_react.useSyncExternalStore)(session.subscribe, session.getState, session.getState);
+  return (0, import_react.useMemo)(
+    () => ({
+      ...state,
+      connected: state.status === "connected",
+      connecting: state.status === "connecting",
+      connect: session.connect,
+      disconnect: session.disconnect,
+      session
+    }),
+    [session, state]
+  );
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  WALLET_SESSION_STORAGE_KEY,
+  WalletProvider,
+  createWalletSession,
+  useWallet,
+  useWalletSession
+});

package/dist/react.d.cts

@@ -0,0 +1,32 @@
+import { ReactNode, ReactElement } from 'react';
+import { C as CaatingaWalletAdapter } from './types-D4XEyX4J.cjs';
+import { c as WalletSessionState, a as WalletSession, b as WalletSessionOptions } from './wallet-session-ed2Dgs9A.cjs';
+export { C as CaatingaWalletCapabilities, W as WALLET_SESSION_STORAGE_KEY, d as WalletSessionStatus, e as WalletSessionStorage, f as createWalletSession } from './wallet-session-ed2Dgs9A.cjs';
+import '@caatinga/core/browser';
+
+interface WalletProviderProps {
+    /** Adapter the provider wraps in a session. Ignored when `session` is given. */
+    adapter?: CaatingaWalletAdapter;
+    /** Pre-built session (e.g. shared with non-React code). Takes precedence over `adapter`. */
+    session?: WalletSession;
+    /** Session options applied when the provider creates the session from `adapter`. */
+    options?: WalletSessionOptions;
+    /**
+     * Run `session.restore()` on mount for silent reconnect.
+     * Defaults to true when persistence is enabled, false otherwise.
+     */
+    autoConnect?: boolean;
+    children?: ReactNode;
+}
+declare function WalletProvider(props: WalletProviderProps): ReactElement;
+declare function useWalletSession(): WalletSession;
+interface UseWalletResult extends WalletSessionState {
+    connected: boolean;
+    connecting: boolean;
+    connect(): Promise<string>;
+    disconnect(): Promise<void>;
+    session: WalletSession;
+}
+declare function useWallet(): UseWalletResult;
+
+export { type UseWalletResult, WalletProvider, type WalletProviderProps, WalletSession, WalletSessionOptions, WalletSessionState, useWallet, useWalletSession };

package/dist/react.d.ts

@@ -0,0 +1,32 @@
+import { ReactNode, ReactElement } from 'react';
+import { C as CaatingaWalletAdapter } from './types-D4XEyX4J.js';
+import { c as WalletSessionState, a as WalletSession, b as WalletSessionOptions } from './wallet-session-DeLp8S1c.js';
+export { C as CaatingaWalletCapabilities, W as WALLET_SESSION_STORAGE_KEY, d as WalletSessionStatus, e as WalletSessionStorage, f as createWalletSession } from './wallet-session-DeLp8S1c.js';
+import '@caatinga/core/browser';
+
+interface WalletProviderProps {
+    /** Adapter the provider wraps in a session. Ignored when `session` is given. */
+    adapter?: CaatingaWalletAdapter;
+    /** Pre-built session (e.g. shared with non-React code). Takes precedence over `adapter`. */
+    session?: WalletSession;
+    /** Session options applied when the provider creates the session from `adapter`. */
+    options?: WalletSessionOptions;
+    /**
+     * Run `session.restore()` on mount for silent reconnect.
+     * Defaults to true when persistence is enabled, false otherwise.
+     */
+    autoConnect?: boolean;
+    children?: ReactNode;
+}
+declare function WalletProvider(props: WalletProviderProps): ReactElement;
+declare function useWalletSession(): WalletSession;
+interface UseWalletResult extends WalletSessionState {
+    connected: boolean;
+    connecting: boolean;
+    connect(): Promise<string>;
+    disconnect(): Promise<void>;
+    session: WalletSession;
+}
+declare function useWallet(): UseWalletResult;
+
+export { type UseWalletResult, WalletProvider, type WalletProviderProps, WalletSession, WalletSessionOptions, WalletSessionState, useWallet, useWalletSession };

package/dist/react.js

@@ -0,0 +1,68 @@
+import {
+  WALLET_SESSION_STORAGE_KEY,
+  createWalletSession
+} from "./chunk-HKAMQDUV.js";
+
+// src/react/wallet-provider.ts
+import {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useSyncExternalStore
+} from "react";
+var WalletSessionContext = createContext(null);
+function WalletProvider(props) {
+  const { adapter, session: providedSession, autoConnect, children } = props;
+  const initialOptions = useRef(props.options);
+  const session = useMemo(() => {
+    if (providedSession) {
+      return providedSession;
+    }
+    if (!adapter) {
+      throw new Error("WalletProvider requires an `adapter` or a `session` prop.");
+    }
+    return createWalletSession(adapter, initialOptions.current);
+  }, [providedSession, adapter]);
+  const shouldAutoConnect = autoConnect ?? initialOptions.current?.persist ?? false;
+  const restoredFor = useRef(null);
+  useEffect(() => {
+    if (!shouldAutoConnect || restoredFor.current === session) {
+      return;
+    }
+    restoredFor.current = session;
+    void session.restore();
+  }, [session, shouldAutoConnect]);
+  return createElement(WalletSessionContext.Provider, { value: session }, children);
+}
+function useWalletSession() {
+  const session = useContext(WalletSessionContext);
+  if (!session) {
+    throw new Error("useWalletSession must be used within a <WalletProvider>.");
+  }
+  return session;
+}
+function useWallet() {
+  const session = useWalletSession();
+  const state = useSyncExternalStore(session.subscribe, session.getState, session.getState);
+  return useMemo(
+    () => ({
+      ...state,
+      connected: state.status === "connected",
+      connecting: state.status === "connecting",
+      connect: session.connect,
+      disconnect: session.disconnect,
+      session
+    }),
+    [session, state]
+  );
+}
+export {
+  WALLET_SESSION_STORAGE_KEY,
+  WalletProvider,
+  createWalletSession,
+  useWallet,
+  useWalletSession
+};