@partylayer/adapter-send 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,447 @@
+import * as _partylayer_core from '@partylayer/core';
+import { ProviderDetection, WalletAdapter, CapabilityKey, AdapterDetectResult, AdapterContext, PartyId, AdapterConnectResult, Session, PersistedSession, SignMessageParams, SignedMessage, SignTransactionParams, SignedTransaction, SubmitTransactionParams, TxReceipt, LedgerApiParams, LedgerApiResult, AdapterEventName, WalletNotInstalledError, ErrorMappingContext, PartyLayerError } from '@partylayer/core';
+
+/**
+ * Local Sigilry-shape types.
+ *
+ * The Send extension speaks the splice-wallet-kernel OpenRPC protocol via
+ * `window.canton`. We could pull these definitions from `@sigilry/dapp`,
+ * but pinning that dependency would couple us to Sigilry's release cadence
+ * and force consumers to install Zod transitively. Instead we model the
+ * minimal shapes we actually consume — fields verified against
+ * `@sigilry/dapp@1.0.1` `.d.ts` files and live runtime inspection of the
+ * extension's provider object.
+ */
+/** Methods Send exposes via `window.canton.request({ method, params })`. */
+type SendRpcMethod = 'status' | 'connect' | 'disconnect' | 'isConnected' | 'getActiveNetwork' | 'getPrimaryAccount' | 'listAccounts' | 'prepareExecute' | 'prepareExecuteAndWait' | 'signMessage' | 'ledgerApi';
+/** Events emitted on the provider via `.on(event, listener)`. */
+type SendEventName = 'accountsChanged' | 'txChanged';
+interface SendKernelInfo {
+    /** Chrome extension ID for the running wallet kernel. */
+    id: string;
+    clientType: 'browser' | 'desktop' | 'mobile' | 'remote';
+    url?: string;
+    userUrl?: string;
+}
+interface SendNetwork {
+    networkId: string;
+    ledgerApi?: {
+        baseUrl: string;
+    };
+}
+interface SendStatusResponse {
+    kernel: SendKernelInfo;
+    isConnected: boolean;
+    isNetworkConnected: boolean;
+    networkReason?: string;
+    network?: SendNetwork;
+    session?: {
+        accessToken: string;
+        userId: string;
+    };
+}
+interface SendAccount {
+    primary: boolean;
+    partyId: string;
+    status: 'allocated' | 'initialized' | string;
+    hint: string;
+    /** Base64 SPKI of the account's P-256 ECDSA public key. */
+    publicKey: string;
+    namespace: string;
+    networkId: string;
+    /** Always 'webauthn-prf' for Send today. */
+    signingProviderId: string;
+    externalTxId?: string;
+    topologyTransactions?: string;
+    disabled?: boolean;
+    reason?: string;
+}
+interface SendDisclosedContract {
+    templateId?: string;
+    contractId?: string;
+    createdEventBlob: string;
+    synchronizerId?: string;
+}
+interface SendPrepareSubmissionRequest {
+    commandId?: string;
+    commands: Record<string, unknown>;
+    actAs?: string[];
+    readAs?: string[];
+    disclosedContracts?: SendDisclosedContract[];
+    synchronizerId?: string;
+    packageIdSelectionPreference?: string[];
+}
+interface SendTxExecutedEvent {
+    status: 'executed';
+    commandId: string;
+    payload: {
+        updateId: string;
+        completionOffset: number;
+    };
+}
+interface SendPrepareExecuteAndWaitResult {
+    tx: SendTxExecutedEvent;
+}
+/** Discriminated union surfaced via the `txChanged` event. */
+type SendTxChangedEvent = {
+    status: 'pending';
+    commandId: string;
+} | {
+    status: 'signed';
+    commandId: string;
+    payload: {
+        signature: string;
+        signedBy: string;
+        party: string;
+    };
+} | SendTxExecutedEvent | {
+    status: 'failed';
+    commandId: string;
+};
+interface SendLedgerApiRequest {
+    requestMethod: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    resource: string;
+    body?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, unknown>;
+    path?: Record<string, string>;
+}
+interface SendLedgerApiResult {
+    /** JSON-encoded response body; preserve verbatim. */
+    response: string;
+}
+interface SendSignMessageRequest {
+    message: string;
+}
+interface SendSignMessageResult {
+    signature: string;
+}
+type SendEventListener = (...args: unknown[]) => void;
+/**
+ * The provider injected at `window.canton` by Send.
+ *
+ * Strictly typed `request()` is intentionally narrowed to the methods
+ * Send actually implements — passing any other method name is a compile
+ * error here, even though the underlying provider would simply reject it
+ * at runtime with `METHOD_NOT_FOUND`.
+ */
+interface SendCantonProvider {
+    request<M extends SendRpcMethod>(args: SendRpcRequest<M>): Promise<SendRpcResult<M>>;
+    on(event: SendEventName, listener: SendEventListener): unknown;
+    off?(event: SendEventName, listener: SendEventListener): unknown;
+    removeListener?(event: SendEventName, listener: SendEventListener): unknown;
+}
+/** Method-name-keyed map of params + result shapes. */
+interface SendRpcSchemas {
+    status: {
+        params: void;
+        result: SendStatusResponse;
+    };
+    connect: {
+        params: void;
+        result: SendStatusResponse;
+    };
+    disconnect: {
+        params: void;
+        result: null;
+    };
+    isConnected: {
+        params: void;
+        result: SendStatusResponse;
+    };
+    getActiveNetwork: {
+        params: void;
+        result: SendNetwork;
+    };
+    getPrimaryAccount: {
+        params: void;
+        result: SendAccount;
+    };
+    listAccounts: {
+        params: void;
+        result: SendAccount[];
+    };
+    prepareExecute: {
+        params: SendPrepareSubmissionRequest;
+        result: null;
+    };
+    prepareExecuteAndWait: {
+        params: SendPrepareSubmissionRequest;
+        result: SendPrepareExecuteAndWaitResult;
+    };
+    signMessage: {
+        params: SendSignMessageRequest;
+        result: SendSignMessageResult;
+    };
+    ledgerApi: {
+        params: SendLedgerApiRequest;
+        result: SendLedgerApiResult;
+    };
+}
+/** Method-name → `params` field shape (omitted entirely when params is void). */
+type SendRpcRequest<M extends SendRpcMethod> = SendRpcSchemas[M]['params'] extends void ? {
+    method: M;
+    params?: undefined;
+} : {
+    method: M;
+    params: SendRpcSchemas[M]['params'];
+};
+/** Method-name → result type. */
+type SendRpcResult<M extends SendRpcMethod> = SendRpcSchemas[M]['result'];
+declare global {
+    interface Window {
+        canton?: SendCantonProvider;
+    }
+}
+
+/**
+ * Typed wrapper around the `window.canton` provider exposed by Send.
+ *
+ * Detection is **registry-driven** via `matchesProviderDetection`. The
+ * adapter accepts an optional `ProviderDetection` rule set at construction
+ * (sourced from the registry's `providerDetection` field for the Send
+ * entry); when omitted, it falls back to `SEND_BUILTIN_DETECTION` which
+ * mirrors the canonical registry rule. Every public RPC method goes
+ * through `guardedRequest`, which checks the live `status` response
+ * against those rules before forwarding the call. The result: if a
+ * non-Send wallet is sitting at `window.canton`, every Send call resolves
+ * to a `SendKernelMismatchError` (treated by the SDK as "Send is not
+ * installed"), and Send only ever acts on its own provider.
+ */
+
+declare class SendProvider {
+    private readonly detection;
+    private cachedStatus;
+    /**
+     * @param detection Optional. Used to match the running `window.canton`
+     *   provider against Send's identity. When omitted, falls back to
+     *   `SEND_BUILTIN_DETECTION` (canonical registry rule mirror).
+     */
+    constructor(detection?: ProviderDetection);
+    /**
+     * True when `window.canton` is present AND its self-reported status
+     * matches Send's detection rules. Performs an actual `status` round-trip
+     * on first call and caches the response for subsequent ones.
+     */
+    isInstalled(): Promise<boolean>;
+    /**
+     * Synchronous best-effort presence check. Used for fast picker rendering
+     * before any async status introspection. May report `true` for a
+     * non-Send provider — callers must follow up with `isInstalled()` (or
+     * any guarded request) before assuming Send is wired in.
+     */
+    isPotentiallyAvailable(): boolean;
+    /**
+     * Read the cached `kernel.id` from the running provider, fetching status
+     * on demand. Diagnostic helper kept public for back-compat — detection
+     * itself no longer hinges on this single field.
+     */
+    getKernelId(): Promise<string>;
+    /**
+     * Read the latest cached status object. Resolves the underlying RPC on
+     * demand if no cached value is present.
+     */
+    getStatus(): Promise<SendStatusResponse>;
+    /**
+     * Reset the cached status (e.g. after the user uninstalls and reinstalls
+     * the extension, or you suspect kernel identity changed mid-session).
+     * Kept under both names to avoid breaking existing test imports.
+     */
+    resetKernelCache(): void;
+    resetStatusCache(): void;
+    private fetchStatus;
+    /** Internal — bypasses the detection guard. */
+    private rawRequest;
+    /** Public dispatch — guards every call with a registry-driven detection check. */
+    private guardedRequest;
+    status(): Promise<SendStatusResponse>;
+    connect(): Promise<SendStatusResponse>;
+    disconnect(): Promise<null>;
+    isConnected(): Promise<SendStatusResponse>;
+    getActiveNetwork(): Promise<SendNetwork>;
+    listAccounts(): Promise<SendAccount[]>;
+    getPrimaryAccount(): Promise<SendAccount>;
+    signMessage(message: string): Promise<{
+        signature: string;
+    }>;
+    prepareExecute(params: SendPrepareSubmissionRequest): Promise<null>;
+    prepareExecuteAndWait(params: SendPrepareSubmissionRequest): Promise<SendPrepareExecuteAndWaitResult>;
+    ledgerApi(req: SendLedgerApiRequest): Promise<SendLedgerApiResult>;
+    on(event: SendEventName, listener: SendEventListener): void;
+    off(event: SendEventName, listener: SendEventListener): void;
+}
+
+declare class SendAdapter implements WalletAdapter {
+    readonly walletId: _partylayer_core.WalletId;
+    readonly name = "Send";
+    private readonly provider;
+    /**
+     * @param options.detection Optional. When supplied, the adapter uses
+     *   these matcher rules to decide whether the running `window.canton`
+     *   belongs to Send. Inject this from the registry entry's
+     *   `providerDetection` field for canonical behaviour. Omitting it
+     *   falls back to the built-in pattern that mirrors the canonical
+     *   registry rule (parity is verified by tests).
+     * @param options.provider Optional. Pre-built provider instance, used
+     *   primarily by tests; takes precedence over `options.detection`.
+     */
+    constructor(options?: {
+        detection?: ProviderDetection;
+        provider?: SendProvider;
+    });
+    getCapabilities(): CapabilityKey[];
+    detectInstalled(): Promise<AdapterDetectResult>;
+    connect(ctx: AdapterContext, _opts?: {
+        timeoutMs?: number;
+        partyId?: PartyId;
+        preferInstalled?: boolean;
+    }): Promise<AdapterConnectResult>;
+    disconnect(ctx: AdapterContext, _session: Session): Promise<void>;
+    restore(ctx: AdapterContext, persisted: PersistedSession): Promise<Session | null>;
+    signMessage(ctx: AdapterContext, session: Session, params: SignMessageParams): Promise<SignedMessage>;
+    signTransaction(_ctx: AdapterContext, _session: Session, _params: SignTransactionParams): Promise<SignedTransaction>;
+    submitTransaction(ctx: AdapterContext, session: Session, params: SubmitTransactionParams): Promise<TxReceipt>;
+    ledgerApi(ctx: AdapterContext, session: Session, params: LedgerApiParams): Promise<LedgerApiResult>;
+    /**
+     * Subscribe to PartyLayer adapter events. Currently bridges only
+     * `txStatus` from Send's native `txChanged` event. Other PartyLayer
+     * adapter events (`connect` / `disconnect` / `sessionExpired` / `error`)
+     * are emitted by the SDK itself, not the wallet, so we no-op them.
+     */
+    on(event: AdapterEventName, handler: (payload: unknown) => void): () => void;
+}
+
+/**
+ * Send-specific error helpers.
+ *
+ * PartyLayer's `ErrorCode` union (in `@partylayer/core/errors.ts`) is the
+ * canonical taxonomy. We do NOT introduce new codes here — instead, the
+ * Send-specific error classes subclass the closest existing PartyLayer
+ * error and carry the diagnostic detail (kernel id, RPC code) in
+ * `details`. That way existing telemetry pipelines and `code`-based
+ * branches in dApp code continue to work without modification.
+ */
+
+/** JSON-RPC 2.0 + EIP-1193 error codes Sigilry surfaces. */
+declare const SendRpcErrorCode: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+    readonly USER_REJECTED: 4001;
+    readonly UNAUTHORIZED: 4100;
+    readonly UNSUPPORTED_METHOD: 4200;
+    readonly DISCONNECTED: 4900;
+    readonly CHAIN_DISCONNECTED: 4901;
+    readonly INVALID_INPUT: -32000;
+    readonly RESOURCE_NOT_FOUND: -32001;
+    readonly RESOURCE_UNAVAILABLE: -32002;
+    readonly TRANSACTION_REJECTED: -32003;
+    readonly METHOD_NOT_SUPPORTED: -32004;
+    readonly LIMIT_EXCEEDED: -32005;
+};
+/**
+ * Send isn't installed — `window.canton` is unavailable entirely.
+ *
+ * Subclasses `WalletNotInstalledError` so existing capability gates and
+ * UI ("install Send") light up automatically. Carries the install URL in
+ * `details` for one-click prompts.
+ */
+declare class SendNotInstalledError extends WalletNotInstalledError {
+    constructor(reason?: string);
+}
+/**
+ * `window.canton` is present but `kernel.id` does not match Send.
+ *
+ * Treated as "Send not installed" from the SDK's perspective so that
+ * other adapters get a chance to claim the active provider — but the
+ * runtime kernel id is preserved in `details` for diagnostics.
+ *
+ * The wording avoids the keywords "rejected"/"denied"/"cancelled" so
+ * `mapUnknownErrorToPartyLayerError` won't silently rewrite this as a
+ * `UserRejectedError` when re-thrown through error mapping.
+ */
+declare class SendKernelMismatchError extends WalletNotInstalledError {
+    constructor(actualKernelId: string);
+}
+/**
+ * Send's authentication backend (auth.cantonwallet.com) timed out or was
+ * otherwise unreachable. This is an external, intermittent issue on
+ * Send's side — not a PartyLayer issue, not a wallet-not-installed
+ * issue, and not a user rejection. Surfaced as a typed error so the UI
+ * can offer a "Try again" affordance + link to Send's status page.
+ *
+ * Subclasses `WalletNotInstalledError` to reuse the existing core error
+ * code (`'WALLET_NOT_INSTALLED'`) without expanding the canonical
+ * `ErrorCode` union — but the class identity (`name`) plus
+ * `details.cause = 'send-auth-timeout'` give consumers enough signal to
+ * route the retry UX without a code-level change.
+ */
+declare class SendAuthTimeoutError extends WalletNotInstalledError {
+    constructor(originalMessage?: string);
+}
+/**
+ * Recognise Send-side authentication-timeout signatures in arbitrary
+ * error payloads. Covers the wording variants the Send wallet surfaces
+ * today (the wallet UI itself uses both "Authentication timed out" and
+ * "Cannot reach authentication server"; the underlying domain
+ * `auth.cantonwallet.com` shows up in stack traces / fetch errors when
+ * the network is at fault).
+ */
+declare function detectSendAuthTimeout(err: unknown): boolean;
+/**
+ * Translate a Sigilry RPC error to the closest PartyLayer error class.
+ *
+ * Falls back to `mapUnknownErrorToPartyLayerError` when the error doesn't
+ * carry a recognisable JSON-RPC `code`. Note that `mapUnknownErrorToPartyLayerError`
+ * itself rewrites messages containing "rejected"/"denied"/"cancelled" into
+ * `UserRejectedError`, so we explicitly route the 4001 code first to make
+ * the user-rejection path stable across wording changes in the wallet.
+ */
+declare function mapSigilryError(err: unknown, context: ErrorMappingContext): PartyLayerError;
+/**
+ * Build a hint string when the developer passes a short-form Canton
+ * template ID OR the legacy pre-Token-Standard `Amulet_Transfer` choice.
+ *
+ * Mirrors `loop-adapter.templateIdHint` so Send produces the same
+ * actionable error text for the same payload bug class. Returns an empty
+ * string when no problem is detected — callers can append this to a base
+ * error message unconditionally.
+ */
+declare function templateIdHint(payload: unknown): string;
+/**
+ * Bound preview of an arbitrary value for inclusion in error messages.
+ * Keeps logs small when a payload is large or contains binary blobs.
+ */
+declare function safePreview(value: unknown, maxLen?: number): string;
+
+/**
+ * Chrome Web Store extension ID for Send Canton Wallet.
+ *
+ * Kept as a public export for diagnostics and back-compat (downstream
+ * consumers still import this constant), but it is **not** the primary
+ * detection signal anymore. Detection is registry-driven via
+ * `SEND_BUILTIN_DETECTION` below; the kernel.id is one of three matchers
+ * (the URL-domain matchers carry stable identity, including for
+ * developer-mode builds whose kernel.id varies per install).
+ */
+declare const SEND_KERNEL_ID = "ldmohiccoioolenadmogclhoklmanpgi";
+/**
+ * Network IDs Send currently supports. Send is mainnet-only as of v0.2.0.
+ * Listed in Canton long-form so it stays distinguishable from PartyLayer's
+ * generic 'mainnet' alias.
+ */
+declare const SEND_SUPPORTED_NETWORKS: readonly ["canton:mainnet"];
+declare const SEND_INSTALL_URL = "https://sigilry.org";
+declare const SEND_HOMEPAGE = "https://cantonwallet.com";
+declare const SEND_DOCS_URL = "https://sigilry.org";
+/**
+ * Send signs every transaction via the WebAuthn PRF extension (passkey).
+ * Surfaced through session metadata so dApps can adapt copy ("approve in
+ * Touch ID / Face ID prompt") rather than show a generic "open extension"
+ * hint.
+ */
+declare const SEND_SIGNING_METHOD: "webauthn-prf";
+
+export { SEND_DOCS_URL, SEND_HOMEPAGE, SEND_INSTALL_URL, SEND_KERNEL_ID, SEND_SIGNING_METHOD, SEND_SUPPORTED_NETWORKS, type SendAccount, SendAdapter, SendAuthTimeoutError, type SendCantonProvider, type SendDisclosedContract, type SendEventListener, type SendEventName, type SendKernelInfo, SendKernelMismatchError, type SendLedgerApiRequest, type SendLedgerApiResult, type SendNetwork, SendNotInstalledError, type SendPrepareExecuteAndWaitResult, type SendPrepareSubmissionRequest, SendProvider, SendRpcErrorCode, type SendRpcMethod, type SendRpcRequest, type SendRpcResult, type SendRpcSchemas, type SendSignMessageRequest, type SendSignMessageResult, type SendStatusResponse, type SendTxChangedEvent, type SendTxExecutedEvent, detectSendAuthTimeout, mapSigilryError, safePreview, templateIdHint };