@bootnodedev/canton-connect 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,342 @@
+import { a as Party, c as WalletSdk, i as ConnectionSubscription, l as ConnectionInput, n as CantonConnectContextValue, o as PartyType, r as ConnectionStatus, s as TxStatusSnapshot, t as CantonConnectConfig, u as InitOptions } from "./types-Deu_03jh.js";
+import { LedgerApiParams, PrepareExecuteParams, ProviderAdapter } from "@canton-network/dapp-sdk";
+import { JSX, ReactNode } from "react";
+//#region src/CantonConnectProvider/index.d.ts
+/**
+ * The whole context in one read, and the escape hatch behind every other hook here. Reach for a
+ * narrower hook unless a component needs several slices at once; this one hands back the config,
+ * the connection to select off, and the three actions.
+ *
+ * @throws with no {@link CantonConnectProvider} above it.
+ *
+ * @example
+ * const { config, connection } = useCantonConnectContext()
+ * const snapshot = connection.getSnapshot()
+ *
+ * @category Hooks
+ */
+declare const useCantonConnectContext: () => CantonConnectContextValue;
+/**
+ * Props for {@link CantonConnectProvider}. `config` is read once, when the connection actor is
+ * created: a `walletPicker` or `additionalAdapters` swapped later reaches `config` on the context,
+ * never the connection, which keeps the adapters it booted with. Pass the final values first.
+ *
+ * @example
+ * <CantonConnectProvider config={{ appName: 'Vesting' }}>{children}</CantonConnectProvider>
+ *
+ * @category Components
+ */
+interface CantonConnectProviderProps {
+  config: CantonConnectConfig;
+  children: ReactNode;
+}
+/**
+ * Hands the connection machine what it needs to build its own `DappSDK`, and publishes the actor
+ * that goes through the states, plus the two bridges that drive it. Nothing here selects: a
+ * provider that pre-selected the whole session re-rendered every consumer on every tick of it.
+ * The hooks mirror wagmi's naming, not its TanStack Query result shapes.
+ *
+ * @example
+ * <CantonConnectProvider config={{ appName: 'Vesting', networkId: 'canton:local' }}>
+ *   <App />
+ * </CantonConnectProvider>
+ *
+ * @category Components
+ */
+declare const CantonConnectProvider: ({ config, children }: CantonConnectProviderProps) => JSX.Element;
+//#endregion
+//#region src/connectError.d.ts
+/**
+ * A connect the user walked away from: the picker was closed rather than a wallet failing.
+ *
+ * @example
+ * if (error !== undefined && !(error instanceof ConnectCancelledError)) {
+ *   toast.error(error.message)
+ * }
+ *
+ * @category Errors
+ */
+declare class ConnectCancelledError extends Error {
+  constructor(cause?: unknown);
+}
+//#endregion
+//#region src/hooks/useConnect.d.ts
+/**
+ * Return shape of {@link useConnect}.
+ *
+ * `connect` resolves once the party lands; `cancelConnect` abandons one in flight, rejecting it
+ * with {@link ConnectCancelledError}; `reset` forgets the error.
+ *
+ * @category Hooks
+ */
+interface UseConnectResult {
+  cancelConnect: () => void;
+  connect: () => Promise<void>;
+  isPending: boolean;
+  isConnected: boolean;
+  error: Error | undefined;
+  reset: () => void;
+}
+/**
+ * Connects the wallet and reports that transition. `connect` takes no argument: the picker chooses
+ * the wallet, so there is no mode to pass. Gate a pending face on `isPending` and
+ * session-dependent content on `useParty().party`, not on `isConnected`.
+ *
+ * @throws with no {@link CantonConnectProvider} above it, as every hook here does.
+ *
+ * @example
+ * const { connect, isPending } = useConnect()
+ * <button onClick={() => void connect().catch(() => undefined)} disabled={isPending}>
+ *   Connect
+ * </button>
+ *
+ * @category Hooks
+ */
+declare const useConnect: () => UseConnectResult;
+//#endregion
+//#region src/hooks/useDisconnect.d.ts
+/**
+ * Return shape of {@link useDisconnect}. `disconnect` settles within 10 s even unanswered.
+ *
+ * @category Hooks
+ */
+interface UseDisconnectResult {
+  disconnect: () => Promise<void>;
+  isPending: boolean;
+}
+/**
+ * Disconnects the wallet and reports that transition. No `error`: a disconnect always settles, by
+ * the timeout if the wallet never answers.
+ *
+ * @throws with no {@link CantonConnectProvider} above it, as every hook here does.
+ *
+ * @example
+ * const { disconnect, isPending } = useDisconnect()
+ * <button onClick={() => void disconnect()} disabled={isPending}>
+ *   Disconnect
+ * </button>
+ *
+ * @category Hooks
+ */
+declare const useDisconnect: () => UseDisconnectResult;
+//#endregion
+//#region src/hooks/useExecute.d.ts
+/**
+ * Return shape of {@link useExecute}. `execute` resolves once the ledger has executed rather than
+ * at submission, and throws when nothing is connected or no party is reported; `lastTx` follows
+ * the wallet's own `txChanged` pushes, so it moves even while `execute` is still pending.
+ *
+ * @category Hooks
+ */
+interface UseExecuteResult {
+  execute: (params: PrepareExecuteParams) => Promise<unknown>;
+  lastTx: TxStatusSnapshot | undefined;
+  isPending: boolean;
+  error: Error | undefined;
+  reset: () => void;
+}
+/**
+ * Submits ledger commands and tracks the transaction in `lastTx`, fed by the SDK's `txChanged`
+ * event. `actAs` defaults to the party `useParty` reports, so a submit acts as the party the UI
+ * shows rather than the wallet's own primary.
+ *
+ * @throws with no {@link CantonConnectProvider} above it, and from `execute` where nothing is
+ * connected or no party is reported. A command that fails throws too, and lands in `error`.
+ *
+ * @example
+ * const { execute, lastTx } = useExecute()
+ * await execute({ commandId: 'claim-1', commands })
+ * lastTx?.status // 'pending' | 'signed' | 'executed' | 'failed'
+ *
+ * @category Hooks
+ */
+declare const useExecute: () => UseExecuteResult;
+//#endregion
+//#region src/hooks/useLedger.d.ts
+/**
+ * Return shape of {@link useLedger}. `ledgerApi` throws when nothing is connected, which `isReady`
+ * is there to check first.
+ *
+ * @category Hooks
+ */
+interface UseLedgerResult {
+  ledgerApi: (params: LedgerApiParams) => Promise<unknown>;
+  isReady: boolean;
+}
+/**
+ * Escape hatch for ledger reads `useExecute` and `useSignMessage` do not cover: the participant's
+ * JSON API, passed through untyped.
+ *
+ * @throws with no {@link CantonConnectProvider} above it, and from `ledgerApi` itself where nothing
+ * is connected, which `isReady` is there to check first.
+ *
+ * @example
+ * const { ledgerApi } = useLedger()
+ * await ledgerApi({ requestMethod: 'get', resource: '/v2/state/ledger-end' })
+ *
+ * @category Hooks
+ */
+declare const useLedger: () => UseLedgerResult;
+//#endregion
+//#region src/hooks/useParty.d.ts
+/**
+ * Return shape of {@link useParty}. `party` is the primary among the accounts that can act on the
+ * ledger, so it need not be the one the wallet flags primary, and it changes under a live session.
+ *
+ * @category Hooks
+ */
+interface UsePartyResult {
+  party: Party | undefined;
+  status: ConnectionStatus;
+  isConnected: boolean;
+}
+/**
+ * The connected account and status. `party` is `undefined` until a connect succeeds, and again
+ * whenever a restored session is locked.
+ *
+ * @throws with no {@link CantonConnectProvider} above it.
+ *
+ * @example
+ * const { party, isConnected } = useParty()
+ * isConnected && <span>{party?.partyId}</span>
+ *
+ * @category Hooks
+ */
+declare const useParty: () => UsePartyResult;
+//#endregion
+//#region src/hooks/usePartyType.d.ts
+/**
+ * Return shape of {@link usePartyType}. `readPartyType` throws when nothing is connected or no
+ * party is reported, which `isReady` is there to check first.
+ *
+ * @category Hooks
+ */
+interface UsePartyTypeResult {
+  readPartyType: () => Promise<PartyType>;
+  isReady: boolean;
+}
+/**
+ * Tells a local party from an external one when asked. Each `readPartyType` call is one
+ * `ledgerApi` read of the participant id, its namespace compared with the party's; nothing is
+ * cached, so hold the answer where several components need it. Reach for it before an action a
+ * local party cannot take, such as `signMessage`, which the reference gateway refuses.
+ *
+ * @throws with no {@link CantonConnectProvider} above it, and from `readPartyType` where nothing
+ * is connected or no party is reported, which `isReady` is there to check first.
+ *
+ * @example
+ * const { readPartyType } = usePartyType()
+ * if ((await readPartyType()) === 'local') {
+ *   toast.error('This wallet cannot sign messages for a local party')
+ * }
+ *
+ * @category Hooks
+ */
+declare const usePartyType: () => UsePartyTypeResult;
+//#endregion
+//#region src/hooks/useSignMessage.d.ts
+/**
+ * Return shape of {@link useSignMessage}. `signMessage` throws when nothing is connected or no
+ * party is reported, and `reset` clears the last signature and error without touching the session.
+ *
+ * @category Hooks
+ */
+interface UseSignMessageResult {
+  signMessage: (message: string) => Promise<string>;
+  signature: string | undefined;
+  isPending: boolean;
+  error: Error | undefined;
+  reset: () => void;
+}
+/**
+ * Signs an arbitrary message with the connected wallet; the SDK owns the encoding.
+ *
+ * @throws with no {@link CantonConnectProvider} above it, and from `signMessage` where nothing is
+ * connected or no party is reported. A wallet refusal throws too, and lands in `error`.
+ *
+ * @example
+ * const { signMessage } = useSignMessage()
+ * const signed = await signMessage('Approve vesting claim')
+ *
+ * @category Hooks
+ */
+declare const useSignMessage: () => UseSignMessageResult;
+//#endregion
+//#region src/hooks/useWalletStatus.d.ts
+/**
+ * Return shape of {@link useWalletStatus}: connected-but-locked is a real pair.
+ *
+ * In CIP-0103 terms, locked is an unauthenticated session: it stands, but the wallet pushed
+ * `isConnected: false` and answers no requests until it pushes true again.
+ *
+ * @category Hooks
+ */
+interface UseWalletStatusResult {
+  isLocked: boolean;
+  isConnected: boolean;
+}
+/**
+ * Reports the session and lock state from the wallet's own pushes. A wallet that disconnected on
+ * its own pushed the same thing as a lock, so `isLocked` cannot tell them apart.
+ *
+ * @throws with no {@link CantonConnectProvider} above it.
+ *
+ * @example
+ * const { isConnected, isLocked } = useWalletStatus()
+ * if (!isConnected) return <p>No session.</p>
+ * return isLocked ? <p>Unlock your wallet to continue.</p> : <p>Ready.</p>
+ *
+ * @category Hooks
+ */
+declare const useWalletStatus: () => UseWalletStatusResult;
+//#endregion
+//#region src/mock/mockAdapter.d.ts
+/**
+ * One canned account the mock adapter reports. Only `partyId` is required; the rest is filled with
+ * obviously fake values, so nothing downstream mistakes a mock account for a real one.
+ *
+ * @category Utilities
+ */
+interface MockAccount {
+  partyId: string;
+  name?: string;
+  publicKey?: string;
+}
+/**
+ * Wiring for {@link createMockAdapter}. `id` defaults to `'mock'`, which is the provider id
+ * `createAutoPicker('mock')` matches; `accounts` defaults to one generated account and treats the
+ * first entry as primary; omitting `networkId` lets `CantonConnectConfig.networkId` apply instead.
+ *
+ * @example
+ * const options: CreateMockAdapterOptions = { id: 'mock', accounts: [{ partyId }] }
+ *
+ * @category Utilities
+ */
+interface CreateMockAdapterOptions {
+  id?: string;
+  accounts?: MockAccount[];
+  networkId?: string;
+}
+/**
+ * What {@link createMockAdapter} returns: a `ProviderAdapter` plus `emit`, which simulates the
+ * wallet pushing an event to subscribers of `provider().on(...)`.
+ *
+ * @category Utilities
+ */
+interface MockAdapter extends ProviderAdapter {
+  emit: (event: string, payload: unknown) => void;
+}
+/**
+ * Answers the connect flow with canned data, so `CantonConnectProvider` runs with no wallet
+ * installed; pass it via `CantonConnectConfig.additionalAdapters`. Anything outside that flow
+ * throws naming the method; a canned result would be indistinguishable from a real one. Reach for
+ * `createFakeWallet` instead to exercise the SDK's real extension transport.
+ *
+ * @example
+ * const config = { appName: 'Vesting', additionalAdapters: [createMockAdapter()] }
+ *
+ * @category Utilities
+ */
+declare const createMockAdapter: (options?: CreateMockAdapterOptions) => MockAdapter;
+//#endregion
+export { type CantonConnectConfig, type CantonConnectContextValue, CantonConnectProvider, type CantonConnectProviderProps, ConnectCancelledError, type ConnectionInput, type ConnectionStatus, type ConnectionSubscription, type CreateMockAdapterOptions, type InitOptions, type LedgerApiParams, type MockAccount, type MockAdapter, type Party, type PartyType, type PrepareExecuteParams, type TxStatusSnapshot, type UseConnectResult, type UseDisconnectResult, type UseExecuteResult, type UseLedgerResult, type UsePartyResult, type UsePartyTypeResult, type UseSignMessageResult, type UseWalletStatusResult, type WalletSdk, createMockAdapter, useCantonConnectContext, useConnect, useDisconnect, useExecute, useLedger, useParty, usePartyType, useSignMessage, useWalletStatus };