@bootnodedev/canton-connect 0.3.0

package/dist/index.js

@@ -0,0 +1,444 @@
+import { a as toConnectionStatus, c as toError, n as CantonConnectProvider, o as ConnectCancelledError, r as useCantonConnectContext, s as toConnectError } from "./CantonConnectProvider-CJ1yWGXz.js";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { useSelector } from "@xstate/react";
+//#region src/hooks/useConnect.ts
+/**
+* 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
+*/
+const useConnect = () => {
+	const { cancelConnect, connect, connection, resetConnectError } = useCantonConnectContext();
+	const status = useSelector(connection, toConnectionStatus);
+	const isPending = useSelector(connection, (snapshot) => snapshot.hasTag("connecting"));
+	const lastConnectError = useSelector(connection, (snapshot) => snapshot.context.lastConnectError);
+	const error = useMemo(() => lastConnectError === void 0 ? void 0 : toConnectError(lastConnectError), [lastConnectError]);
+	return {
+		cancelConnect,
+		connect,
+		isPending,
+		isConnected: status === "connected",
+		error,
+		reset: resetConnectError
+	};
+};
+//#endregion
+//#region src/hooks/useDisconnect.ts
+/**
+* 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
+*/
+const useDisconnect = () => {
+	const { connection, disconnect } = useCantonConnectContext();
+	return {
+		disconnect,
+		isPending: useSelector(connection, toConnectionStatus) === "disconnecting"
+	};
+};
+//#endregion
+//#region src/hooks/useTxFeed.ts
+/** Tracks the SDK's `txChanged` pushes while a session is active, clearing on session end. */
+const useTxFeed = (sdk, connection) => {
+	const [lastTx, setLastTx] = useState(void 0);
+	const sessionActive = useSelector(connection, (snapshot) => snapshot.matches("session"));
+	useEffect(() => {
+		if (!sessionActive) {
+			setLastTx(void 0);
+			return;
+		}
+		const onTx = (event) => {
+			setLastTx({
+				status: event.status,
+				commandId: event.commandId,
+				payload: "payload" in event ? event.payload : void 0
+			});
+		};
+		sdk.onTxChanged(onTx).catch(() => void 0);
+		return () => {
+			sdk.removeOnTxChanged(onTx).catch(() => void 0);
+		};
+	}, [sessionActive, sdk]);
+	return lastTx;
+};
+//#endregion
+//#region src/hooks/useWalletCall.ts
+/** The resting state, hoisted so a hook that never called keeps one identity across renders. */
+const IDLE = {
+	isPending: false,
+	error: void 0
+};
+/** Throws when the wallet is disconnected or locked, the guard every SDK-calling hook shares. */
+const assertUsable = (status, isLocked) => {
+	if (status !== "connected") throw new Error("wallet is not connected - call useConnect().connect() first");
+	if (isLocked) throw new Error("wallet is locked - unlock it in the wallet");
+};
+/** Throws when the session reports no party, which a connected one can. */
+function assertPartyId(partyId) {
+	if (partyId === void 0) throw new Error("wallet reports no usable party - allocate one in the wallet");
+}
+/**
+* Selects the session and wraps one SDK call with the connect, lock and party guards plus the
+* pending/error bookkeeping `useExecute` and `useSignMessage` share.
+*/
+const useWalletCall = () => {
+	const { connection } = useCantonConnectContext();
+	const sdk = useSelector(connection, (snapshot) => snapshot.context.sdk);
+	const partyId = useSelector(connection, (snapshot) => snapshot.context.party?.partyId);
+	const status = useSelector(connection, toConnectionStatus);
+	const isLocked = useSelector(connection, (snapshot) => snapshot.hasTag("unauthenticated"));
+	const [state, setState] = useState(IDLE);
+	const call = useCallback(async (run) => {
+		assertUsable(status, isLocked);
+		assertPartyId(partyId);
+		setState({
+			isPending: true,
+			error: void 0
+		});
+		try {
+			const result = await run(sdk, partyId);
+			setState(IDLE);
+			return result;
+		} catch (err) {
+			const error = toError(err);
+			setState({
+				isPending: false,
+				error
+			});
+			throw error;
+		}
+	}, [
+		isLocked,
+		partyId,
+		sdk,
+		status
+	]);
+	const reset = useCallback(() => setState(IDLE), []);
+	return {
+		call,
+		isPending: state.isPending,
+		error: state.error,
+		reset,
+		connection,
+		sdk,
+		status,
+		isLocked
+	};
+};
+//#endregion
+//#region src/hooks/useExecute.ts
+/** Defaults `actAs` to the connected party, leaving a caller's own `actAs` untouched. */
+const withActAs = (params, partyId) => params.actAs === void 0 ? {
+	...params,
+	actAs: [partyId]
+} : params;
+/**
+* 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
+*/
+const useExecute = () => {
+	const { call, isPending, error, reset, connection, sdk } = useWalletCall();
+	const lastTx = useTxFeed(sdk, connection);
+	return {
+		execute: useCallback((params) => call((walletSdk, actingPartyId) => walletSdk.prepareExecuteAndWait(withActAs(params, actingPartyId))), [call]),
+		lastTx,
+		isPending,
+		error,
+		reset
+	};
+};
+//#endregion
+//#region src/hooks/useLedger.ts
+/**
+* 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
+*/
+const useLedger = () => {
+	const { sdk, status, isLocked } = useWalletCall();
+	return {
+		ledgerApi: useCallback(async (params) => {
+			assertUsable(status, isLocked);
+			return await sdk.ledgerApi(params);
+		}, [
+			isLocked,
+			sdk,
+			status
+		]),
+		isReady: status === "connected" && !isLocked
+	};
+};
+//#endregion
+//#region src/hooks/useParty.ts
+/**
+* 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
+*/
+const useParty = () => {
+	const { connection } = useCantonConnectContext();
+	const party = useSelector(connection, (snapshot) => snapshot.context.party);
+	const status = useSelector(connection, toConnectionStatus);
+	return {
+		party,
+		status,
+		isConnected: status === "connected"
+	};
+};
+//#endregion
+//#region src/hooks/usePartyType.ts
+const namespaceOf = (id) => /::(.+)$/.exec(id)?.[1];
+const readParticipantNamespace = async (sdk) => {
+	const answer = await sdk.ledgerApi({
+		requestMethod: "get",
+		resource: "/v2/parties/participant-id"
+	});
+	const namespace = typeof answer.participantId === "string" ? namespaceOf(answer.participantId) : void 0;
+	if (namespace === void 0) throw new Error(`participant id not found in ${JSON.stringify(answer)}`);
+	return namespace;
+};
+/**
+* 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
+*/
+const usePartyType = () => {
+	const { connection, sdk, status, isLocked } = useWalletCall();
+	const party = useSelector(connection, (snapshot) => snapshot.context.party);
+	return {
+		readPartyType: useCallback(async () => {
+			assertUsable(status, isLocked);
+			if (party === void 0) throw new Error("wallet reports no usable party - allocate one in the wallet");
+			const participantNamespace = await readParticipantNamespace(sdk);
+			return party.namespace === participantNamespace ? "local" : "external";
+		}, [
+			isLocked,
+			party,
+			sdk,
+			status
+		]),
+		isReady: status === "connected" && !isLocked && party !== void 0
+	};
+};
+//#endregion
+//#region src/hooks/useSignMessage.ts
+/**
+* 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
+*/
+const useSignMessage = () => {
+	const { call, isPending, error, reset: resetCall } = useWalletCall();
+	const [signature, setSignature] = useState(void 0);
+	return {
+		signMessage: useCallback(async (message) => {
+			setSignature(void 0);
+			const result = await call((walletSdk) => walletSdk.signMessage({ message }));
+			setSignature(result.signature);
+			return result.signature;
+		}, [call]),
+		signature,
+		isPending,
+		error,
+		reset: useCallback(() => {
+			setSignature(void 0);
+			resetCall();
+		}, [resetCall])
+	};
+};
+//#endregion
+//#region src/hooks/useWalletStatus.ts
+/**
+* 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
+*/
+const useWalletStatus = () => {
+	const { connection } = useCantonConnectContext();
+	return {
+		isLocked: useSelector(connection, (snapshot) => snapshot.hasTag("unauthenticated")),
+		isConnected: useSelector(connection, toConnectionStatus) === "connected"
+	};
+};
+//#endregion
+//#region src/mock/mockAdapter.ts
+const DEFAULT_PROVIDER_ID = "mock";
+const DEFAULT_NAME = "Mock Wallet";
+const DEFAULT_DESCRIPTION = "Mock wallet for dev and tests — no real signing, never a live wallet";
+const MOCK_WALLET_STATUS = "allocated";
+const MOCK_SIGNING_PROVIDER_ID = "mock";
+const MOCK_PUBLIC_KEY = "mock-public-key";
+/** The single mock account `createMockAdapter` reports when the caller supplies none. */
+const defaultAccounts = (providerId) => [{ partyId: `${providerId}::1220abcd` }];
+/** Shapes one `MockAccount` into the `Wallet` the mock adapter's `listAccounts` returns. */
+const toWallet = (account, primary, networkId) => ({
+	primary,
+	partyId: account.partyId,
+	status: MOCK_WALLET_STATUS,
+	hint: account.name ?? account.partyId,
+	publicKey: account.publicKey ?? MOCK_PUBLIC_KEY,
+	namespace: account.partyId.split("::")[1] ?? account.partyId,
+	signingProviderId: MOCK_SIGNING_PROVIDER_ID,
+	...networkId === void 0 ? {} : { networkId }
+});
+/**
+* The adapter `createMockAdapter` returns: it announces itself like an installed wallet and
+* answers the connect flow from canned accounts, with no wallet present.
+*/
+var MockProviderAdapter = class {
+	providerId;
+	name = DEFAULT_NAME;
+	type = "browser";
+	wallets;
+	connected = false;
+	listenerMap = {};
+	constructor(options) {
+		this.providerId = options.id ?? DEFAULT_PROVIDER_ID;
+		const accounts = options.accounts ?? defaultAccounts(this.providerId);
+		this.wallets = accounts.map((account, index) => toWallet(account, index === 0, options.networkId));
+	}
+	getInfo() {
+		return {
+			providerId: this.providerId,
+			name: this.name,
+			type: this.type,
+			description: DEFAULT_DESCRIPTION
+		};
+	}
+	async detect() {
+		return true;
+	}
+	provider() {
+		return this;
+	}
+	teardown() {}
+	handlers = {
+		connect: () => {
+			this.connected = true;
+			return {
+				isConnected: true,
+				isNetworkConnected: true
+			};
+		},
+		disconnect: () => {
+			this.connected = false;
+			return null;
+		},
+		status: () => ({
+			provider: {
+				id: this.providerId,
+				providerType: this.type
+			},
+			connection: {
+				isConnected: this.connected,
+				isNetworkConnected: true
+			}
+		}),
+		listAccounts: () => this.wallets
+	};
+	async request(args) {
+		const handler = this.handlers[args.method];
+		if (handler === void 0) throw new Error(`mock adapter does not implement '${args.method}'`);
+		return handler();
+	}
+	on = (event, listener) => {
+		const listeners = this.listenerMap[event] ?? [];
+		listeners.push(listener);
+		this.listenerMap[event] = listeners;
+		return this;
+	};
+	emit = (event, ...args) => {
+		for (const listener of this.listenerMap[event] ?? []) listener(...args);
+		return true;
+	};
+	removeListener = (event, listenerToRemove) => {
+		this.listenerMap[event] = (this.listenerMap[event] ?? []).filter((listener) => listener !== listenerToRemove);
+		return this;
+	};
+};
+/**
+* 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
+*/
+const createMockAdapter = (options = {}) => new MockProviderAdapter(options);
+//#endregion
+export { CantonConnectProvider, ConnectCancelledError, createMockAdapter, useCantonConnectContext, useConnect, useDisconnect, useExecute, useLedger, useParty, usePartyType, useSignMessage, useWalletStatus };

package/dist/testing/index.d.ts

@@ -0,0 +1,127 @@
+import { a as Party, c as WalletSdk, r as ConnectionStatus } from "../types-Deu_03jh.js";
+import { WalletPickerFn } from "@canton-network/dapp-sdk";
+import { JSX, ReactNode } from "react";
+//#region src/testing/autoPicker.d.ts
+/**
+ * A `walletPicker` that selects with no UI, for tests and headless dev flows: the entry whose
+ * `providerId` matches `pick`, or the first discovered one.
+ *
+ * @throws when no discovered entry matches `pick`, so a test naming a wallet that never registered
+ * fails at the picker rather than at the connect.
+ *
+ * @example
+ * const config = { appName: 'Vesting', walletPicker: createAutoPicker('mock') }
+ *
+ * @category Utilities
+ */
+declare const createAutoPicker: (pick?: string) => WalletPickerFn;
+//#endregion
+//#region src/testing/fakeSession.d.ts
+/**
+ * Props for {@link FakeSessionProvider}. `status` starts the session mid-flight and `party` is
+ * what a connect resolves to; `readingAccounts` reaches the pending face over a live session, and
+ * `sdk` drives a hook's own pending, error and `reset()`, never what a wallet returns.
+ *
+ * @category Components
+ */
+interface FakeSessionProviderProps {
+  children: ReactNode;
+  connectError?: Error;
+  isLocked?: boolean;
+  party?: Party;
+  readingAccounts?: boolean;
+  sdk?: Partial<WalletSdk>;
+  status?: ConnectionStatus;
+}
+/**
+ * Stands in for `CantonConnectProvider` with the session already in a given shape, so a component
+ * test asserts on markup without paying the SDK's discovery sleeps or its connect flow. The shape
+ * is a real `connectionMachine` actor rehydrated at the state the props ask for, so the hooks
+ * select from it exactly as they do in the app. `connect` and `disconnect` move the session, but
+ * reach for the real provider plus `createMockAdapter` to test connecting itself — the intermediate
+ * states here are not the SDK's.
+ *
+ * @example
+ * render(
+ *   <FakeSessionProvider status="connected" party={party}>
+ *     <ConnectButton />
+ *   </FakeSessionProvider>,
+ * )
+ *
+ * @category Components
+ */
+declare const FakeSessionProvider: ({ children, connectError, isLocked, party, readingAccounts, sdk, status: initialStatus }: FakeSessionProviderProps) => JSX.Element;
+//#endregion
+//#region src/testing/fakeWallet.d.ts
+/**
+ * One account the fake wallet reports from `listAccounts`. Mark exactly one `primary`: that is the
+ * entry `selectPrimaryAccount` resolves to `Party`.
+ *
+ * @category Utilities
+ */
+interface FakeWalletAccount {
+  partyId: string;
+  primary?: boolean;
+  name?: string;
+  publicKey?: string;
+  networkId?: string;
+}
+/**
+ * Wiring for {@link createFakeWallet}. `id` is announced to `window` and doubles as the postMessage
+ * target and the display name unless `target` or `name` override it, and `accounts` defaults to one
+ * account with `id` as its party prefix. `statusResponses` is `isConnected` per successive `status`
+ * call, last entry repeating, which is how a test restores a session and then reports it locked.
+ *
+ * @example
+ * const options: FakeWalletOptions = { id: 'mock', statusResponses: [true, false] }
+ *
+ * @category Utilities
+ */
+interface FakeWalletOptions {
+  id: string;
+  name?: string;
+  target?: string;
+  accounts?: FakeWalletAccount[];
+  statusResponses?: boolean[];
+}
+/**
+ * Handles on a running fake wallet: `announce` re-announces it as if the extension had just loaded,
+ * `push` sends an unsolicited notification the way a real one does (`'statusChanged'`, say), and
+ * `dispose` removes the `window` listeners it installed, which every test must do in teardown.
+ *
+ * @category Utilities
+ */
+interface FakeWallet {
+  announce: () => void;
+  push: (method: string, params: unknown) => void;
+  dispose: () => void;
+}
+/**
+ * A fake CIP-0103 extension wallet for tests. It speaks the real postMessage protocol, so it
+ * exercises the SDK's genuine `ExtensionAdapter` rather than a stub. Answers `connect`, `status`,
+ * `listAccounts` and `disconnect`; anything else rejects naming the method. Reach for
+ * `createMockAdapter` instead where the transport is not what is under test.
+ *
+ * @example
+ * const wallet = createFakeWallet({ id: 'mock' })
+ * wallet.push('statusChanged', { connection: { isConnected: false } })
+ * wallet.dispose()
+ *
+ * @category Utilities
+ */
+declare const createFakeWallet: (options: FakeWalletOptions) => FakeWallet;
+//#endregion
+//#region src/testing/pause.d.ts
+/**
+ * Real-timer sleep, which is how a suite awaits a promise-settling send; `pause(0)` flushes the
+ * pending macrotasks. Reach for it over `waitFor`, whose retry window turns a genuine red into a
+ * timeout rather than a failed assertion.
+ *
+ * @example
+ * await pause(0) // one macrotask on, so the send above has settled
+ *
+ * @category Utilities
+ */
+declare const pause: (ms: number) => Promise<unknown>;
+//#endregion
+export { FakeSessionProvider, type FakeSessionProviderProps, type FakeWallet, type FakeWalletAccount, type FakeWalletOptions, createAutoPicker, createFakeWallet, pause };