@partylayer/provider 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,389 @@
+import { CIP0103Provider, CIP0103RequestPayload, CIP0103EventListener, PartyLayerError, CIP0103ConnectResult, CIP0103TxChangedEvent, CIP0103Network, CIP0103RequestParams } from '@partylayer/core';
+export { CIP0103Account, CIP0103AccountStatus, CIP0103ConnectResult, CIP0103Event, CIP0103EventListener, CIP0103LedgerApiRequest, CIP0103LedgerApiResponse, CIP0103Method, CIP0103Network, CIP0103Provider, CIP0103ProviderInfo, CIP0103ProviderRpcError, CIP0103ProviderType, CIP0103RequestParams, CIP0103RequestPayload, CIP0103SignMessageRequest, CIP0103StatusEvent, CIP0103TxChangedEvent, CIP0103TxExecutedPayload, CIP0103TxFailedPayload, CIP0103TxPendingPayload, CIP0103TxSignedPayload, CIP0103TxStatus, CIP0103_EVENTS, CIP0103_MANDATORY_METHODS, CIP0103_METHODS } from '@partylayer/core';
+
+/**
+ * CIP-0103 Wallet Discovery
+ *
+ * Discovers CIP-0103-compliant wallet Providers from the global scope.
+ * Wallet-agnostic: no hardcoded wallet logic, only duck-type checking
+ * for the Provider interface shape.
+ */
+
+/** Metadata about a discovered CIP-0103 wallet provider */
+interface DiscoveredProvider {
+    /** Identifier (e.g. "canton.console", "consoleWallet") */
+    id: string;
+    /** The native CIP-0103 Provider instance */
+    provider: CIP0103Provider;
+    /** How it was discovered */
+    source: 'injected' | 'registry';
+    /** Whether the provider supports async flows (userUrl) */
+    isAsync?: boolean;
+    /** Display name (if discoverable from status) */
+    name?: string;
+}
+/**
+ * Check if an object implements the CIP-0103 Provider interface.
+ *
+ * This is a structural (duck-type) check — it verifies the presence of
+ * the four required methods without checking implementation correctness.
+ */
+declare function isCIP0103Provider(obj: unknown): obj is CIP0103Provider;
+/**
+ * Discover all injected CIP-0103 providers from the global scope.
+ *
+ * Scans well-known window paths and their sub-properties for objects
+ * that implement the Provider interface.
+ */
+declare function discoverInjectedProviders(): DiscoveredProvider[];
+/**
+ * Wait for a specific provider to be injected (with timeout).
+ *
+ * Extensions may inject their provider after page load. This function
+ * polls at 100ms intervals until the provider appears or the timeout
+ * expires.
+ *
+ * @param id - Provider id to match (exact or suffix match)
+ * @param timeoutMs - Maximum wait time (default 3000ms)
+ */
+declare function waitForProvider(id: string, timeoutMs?: number): Promise<DiscoveredProvider | null>;
+
+/**
+ * PartyLayerProvider — CIP-0103 Native Provider Implementation
+ *
+ * This is the core Provider class. It wraps a single native CIP-0103
+ * wallet provider and adds:
+ *
+ * - Method routing with orchestrated overrides (connect, disconnect, etc.)
+ * - Event forwarding from the native wallet to the dApp
+ * - Async wallet support (userUrl flows)
+ * - Error normalization to ProviderRpcError
+ * - Forward compatibility for unknown methods and events
+ *
+ * IMPORTANT: No wallet-specific logic lives here. The Provider is purely
+ * a router and normalizer.
+ */
+
+interface PartyLayerProviderOptions {
+    /** Discovered wallet provider to wrap */
+    walletProvider?: DiscoveredProvider;
+    /** Timeout for async operations (ms). Default 300_000 (5 min). */
+    asyncTimeoutMs?: number;
+    /** Callback when a userUrl is available (for async wallets) */
+    onUserUrl?: (url: string) => void;
+}
+declare class PartyLayerProvider implements CIP0103Provider {
+    private readonly eventBus;
+    private readonly router;
+    private readonly options;
+    private nativeProvider;
+    private connected;
+    /** Event forwarders from the native provider, keyed by event name */
+    private nativeForwarders;
+    constructor(options?: PartyLayerProviderOptions);
+    request<T = unknown>(args: CIP0103RequestPayload): Promise<T>;
+    on<T = unknown>(event: string, listener: CIP0103EventListener<T>): this;
+    emit<T = unknown>(event: string, ...args: T[]): boolean;
+    removeListener<T = unknown>(event: string, listenerToRemove: CIP0103EventListener<T>): this;
+    /** Whether the provider is currently in a connected state */
+    get isConnected(): boolean;
+    /** Switch the underlying wallet provider (e.g. user selects a different wallet) */
+    setWalletProvider(discovered: DiscoveredProvider): void;
+    /** Get the currently attached native provider (if any) */
+    getNativeProvider(): CIP0103Provider | null;
+    /** Tear down: unsubscribe all events and release the native provider */
+    destroy(): void;
+    private registerOrchestratedMethods;
+    private forwardNativeEvents;
+    private unforwardNativeEvents;
+    /** Emit statusChanged by querying the current wallet provider status */
+    private emitStatusChanged;
+}
+
+/**
+ * PartyLayerClient → CIP-0103 Provider Bridge
+ *
+ * Creates a CIP-0103-compliant Provider backed by an existing
+ * PartyLayerClient instance. This is the backward-compatibility path:
+ * existing dApps using PartyLayerClient can obtain a standard Provider
+ * without rewiring their wallet adapter stack.
+ *
+ * Usage:
+ *   const provider = createProviderBridge(client);
+ *   // or (added to PartyLayerClient):
+ *   const provider = client.asProvider();
+ */
+
+/**
+ * Minimal interface for the PartyLayerClient consumed by the bridge.
+ * Using an interface avoids importing the full SDK (prevents circular deps).
+ */
+interface BridgeableClient {
+    connect(options?: unknown): Promise<{
+        sessionId: unknown;
+        walletId: unknown;
+        partyId: unknown;
+        network: string;
+        expiresAt?: number;
+        capabilitiesSnapshot?: string[];
+    }>;
+    disconnect(): Promise<void>;
+    getActiveSession(): Promise<{
+        sessionId: unknown;
+        walletId: unknown;
+        partyId: unknown;
+        network: string;
+        expiresAt?: number;
+        capabilitiesSnapshot?: string[];
+    } | null>;
+    signMessage(params: {
+        message: string;
+        nonce?: string;
+        domain?: string;
+    }): Promise<{
+        signature: unknown;
+    }>;
+    signTransaction(params: {
+        tx: unknown;
+    }): Promise<{
+        transactionHash: unknown;
+        signedTx?: unknown;
+        partyId?: unknown;
+    }>;
+    submitTransaction(params: {
+        signedTx: unknown;
+    }): Promise<{
+        transactionHash: unknown;
+        submittedAt?: number;
+        commandId?: string;
+        updateId?: string;
+    }>;
+    ledgerApi?(params: {
+        requestMethod: string;
+        resource: string;
+        body?: string;
+    }): Promise<{
+        response: string;
+    }>;
+    getRegistryStatus(): unknown;
+    on(event: string, handler: (event: unknown) => void | Promise<void>): () => void;
+}
+/**
+ * Create a CIP-0103 Provider backed by a PartyLayerClient.
+ *
+ * All `request()` calls are mapped to PartyLayerClient methods.
+ * PartyLayer events are forwarded as CIP-0103 events.
+ */
+declare function createProviderBridge(client: BridgeableClient): CIP0103Provider;
+
+/**
+ * CIP-0103 / EIP-1193 / EIP-1474 Error Model
+ *
+ * All errors on the Provider surface MUST be ProviderRpcError instances
+ * with numeric codes. No PartyLayer string-based ErrorCode is ever exposed.
+ *
+ * Reference: https://eips.ethereum.org/EIPS/eip-1193
+ * Reference: https://eips.ethereum.org/EIPS/eip-1474
+ */
+declare class ProviderRpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(message: string, code: number, data?: unknown);
+    toJSON(): Record<string, unknown>;
+}
+declare const RPC_ERRORS: {
+    /** User rejected the request */
+    readonly USER_REJECTED: 4001;
+    /** The requested method/account is not authorized */
+    readonly UNAUTHORIZED: 4100;
+    /** Provider does not support the requested method */
+    readonly UNSUPPORTED_METHOD: 4200;
+    /** Provider is disconnected from all chains */
+    readonly DISCONNECTED: 4900;
+    /** Provider is not connected to the requested chain */
+    readonly CHAIN_DISCONNECTED: 4901;
+};
+declare const JSON_RPC_ERRORS: {
+    /** Invalid JSON (parse error) */
+    readonly PARSE_ERROR: -32700;
+    /** Invalid request object */
+    readonly INVALID_REQUEST: -32600;
+    /** Method not found */
+    readonly METHOD_NOT_FOUND: -32601;
+    /** Invalid method parameters */
+    readonly INVALID_PARAMS: -32602;
+    /** Internal JSON-RPC error */
+    readonly INTERNAL_ERROR: -32603;
+    /** Invalid input / missing or invalid parameters */
+    readonly INVALID_INPUT: -32000;
+    /** Resource not found */
+    readonly RESOURCE_NOT_FOUND: -32001;
+    /** Resource unavailable */
+    readonly RESOURCE_UNAVAILABLE: -32002;
+    /** Transaction rejected */
+    readonly TRANSACTION_REJECTED: -32003;
+    /** Method not supported */
+    readonly METHOD_NOT_SUPPORTED: -32004;
+    /** Rate limit exceeded */
+    readonly RATE_LIMIT_EXCEEDED: -32005;
+};
+declare function userRejected(message?: string, data?: unknown): ProviderRpcError;
+declare function unauthorized(message?: string, data?: unknown): ProviderRpcError;
+declare function unsupportedMethod(method: string): ProviderRpcError;
+declare function disconnected(message?: string): ProviderRpcError;
+declare function chainDisconnected(message?: string): ProviderRpcError;
+declare function internalError(message: string, data?: unknown): ProviderRpcError;
+declare function invalidParams(message: string, data?: unknown): ProviderRpcError;
+declare function methodNotFound(method: string): ProviderRpcError;
+declare function resourceNotFound(message: string, data?: unknown): ProviderRpcError;
+declare function resourceUnavailable(message: string, data?: unknown): ProviderRpcError;
+declare function transactionRejected(message?: string, data?: unknown): ProviderRpcError;
+
+/**
+ * Bidirectional error mapping between PartyLayer ErrorCode and CIP-0103 numeric codes
+ *
+ * This module ensures no PartyLayer internals leak through the Provider surface,
+ * and provides a reverse path for the bridge.
+ */
+
+/**
+ * Convert any error into a ProviderRpcError for the CIP-0103 surface.
+ *
+ * This is the single normalization point — every error that escapes
+ * the Provider MUST pass through this function.
+ */
+declare function toProviderRpcError(err: unknown): ProviderRpcError;
+/**
+ * Convert ProviderRpcError back to a PartyLayerError.
+ *
+ * Used by the bridge path when errors from the Provider surface
+ * need to flow back into the PartyLayerClient world.
+ */
+declare function toPartyLayerError(err: ProviderRpcError): PartyLayerError;
+
+/**
+ * Async Wallet Handling
+ *
+ * CIP-0103 async wallet extensions allow methods like `connect` and
+ * `prepareExecute` to return a `{ userUrl }` instead of completing
+ * synchronously. The user must visit the URL (e.g., mobile wallet
+ * approval screen), and the wallet provider emits an event when the
+ * operation completes.
+ *
+ * This module provides helpers that abstract the wait-for-event pattern
+ * so the Provider implementation can offer a unified surface to dApps.
+ */
+
+interface AsyncConnectOptions {
+    /** Timeout for waiting for the async connect event (ms) */
+    timeoutMs?: number;
+    /** Callback when userUrl is available (for UI to redirect / show QR) */
+    onUserUrl?: (url: string) => void;
+}
+interface AsyncPrepareExecuteOptions {
+    timeoutMs?: number;
+    onUserUrl?: (url: string) => void;
+}
+/**
+ * Handle an async connect flow:
+ *
+ * 1. If connectResult is already isConnected (sync wallet), return immediately.
+ * 2. If connectResult has userUrl, invoke onUserUrl callback for UI.
+ * 3. Wait for 'connected' event from the wallet provider.
+ * 4. Return the final ConnectResult.
+ */
+declare function handleAsyncConnect(walletProvider: CIP0103Provider, connectResult: CIP0103ConnectResult, options?: AsyncConnectOptions): Promise<CIP0103ConnectResult>;
+/**
+ * Handle an async prepareExecute flow:
+ *
+ * 1. If result has userUrl, invoke onUserUrl callback for UI.
+ * 2. Wait for 'txChanged' event with matching commandId.
+ * 3. Return when txChanged reaches a terminal state (executed / failed).
+ */
+declare function handleAsyncPrepareExecute(walletProvider: CIP0103Provider, commandId: string, userUrl: string | undefined, options?: AsyncPrepareExecuteOptions): Promise<CIP0103TxChangedEvent>;
+
+/**
+ * CAIP-2 Network Identity Utilities
+ *
+ * All CIP-0103 network identifiers use CAIP-2 format: "namespace:reference"
+ * e.g. "canton:da-mainnet", "canton:da-devnet"
+ *
+ * Reference: https://github.com/ChainAgnostic/CAIPs/blob/main/CAIPs/caip-2.md
+ */
+
+declare const CANTON_NETWORKS: Record<string, string>;
+/**
+ * Convert a legacy PartyLayer NetworkId (e.g. "devnet") or already-CAIP-2
+ * string to a CIP-0103 Network object.
+ *
+ * @throws {Error} if the resulting network ID is not valid CAIP-2
+ */
+declare function toCAIP2Network(networkId: string): CIP0103Network;
+/**
+ * Extract the short network name from a CAIP-2 ID.
+ * Returns the original string if no reverse mapping exists.
+ */
+declare function fromCAIP2Network(caip2: string): string;
+/**
+ * Validate that a string conforms to CAIP-2 format.
+ *
+ * CAIP-2 format: namespace:reference
+ * - namespace: [-a-z0-9]{3,8}
+ * - reference: [-_a-zA-Z0-9]{1,32}
+ */
+declare function isValidCAIP2(networkId: string): boolean;
+
+/**
+ * CIP-0103 Event Bus
+ *
+ * Minimal, spec-compliant event emitter.
+ * - on() and removeListener() return the Provider (for chaining)
+ * - emit() returns boolean (true if any listener was called)
+ * - Listener errors are swallowed to prevent one handler from
+ *   breaking others
+ */
+
+declare class CIP0103EventBus {
+    private listeners;
+    private owner;
+    /** Set the owning Provider instance (for chaining returns) */
+    setOwner(owner: CIP0103Provider): void;
+    on<T = unknown>(event: string, listener: CIP0103EventListener<T>): CIP0103Provider;
+    emit<T = unknown>(event: string, ...args: T[]): boolean;
+    removeListener<T = unknown>(event: string, listenerToRemove: CIP0103EventListener<T>): CIP0103Provider;
+    /** Remove all listeners, optionally scoped to a single event */
+    removeAllListeners(event?: string): void;
+    /** Number of listeners for a given event */
+    listenerCount(event: string): number;
+}
+
+/**
+ * CIP-0103 Method Router
+ *
+ * Routes request({ method, params }) calls to the correct handler function.
+ * By default, all 10 mandatory CIP-0103 methods are registered as passthrough
+ * handlers that delegate to the native wallet Provider.
+ *
+ * Forward-compatible: unknown methods are passed through to the wallet provider
+ * rather than rejected, allowing support for future CIP extensions.
+ */
+
+type MethodHandler<T = unknown> = (walletProvider: CIP0103Provider, params?: CIP0103RequestParams) => Promise<T>;
+declare class MethodRouter {
+    private handlers;
+    private walletProvider;
+    constructor();
+    /** Set / swap the underlying native wallet provider */
+    setWalletProvider(provider: CIP0103Provider | null): void;
+    /** Get the current wallet provider */
+    getWalletProvider(): CIP0103Provider | null;
+    /** Register (or override) a handler for a method name */
+    register<T>(method: string, handler: MethodHandler<T>): void;
+    /** Route a request to the appropriate handler */
+    route<T>(payload: CIP0103RequestPayload): Promise<T>;
+    /** Check whether a handler is registered for a given method */
+    hasHandler(method: string): boolean;
+    private registerDefaults;
+}
+
+export { type AsyncConnectOptions, type AsyncPrepareExecuteOptions, CANTON_NETWORKS, CIP0103EventBus, type DiscoveredProvider, JSON_RPC_ERRORS, type MethodHandler, MethodRouter, PartyLayerProvider, type PartyLayerProviderOptions, ProviderRpcError, RPC_ERRORS, chainDisconnected, createProviderBridge, disconnected, discoverInjectedProviders, fromCAIP2Network, handleAsyncConnect, handleAsyncPrepareExecute, internalError, invalidParams, isCIP0103Provider, isValidCAIP2, methodNotFound, resourceNotFound, resourceUnavailable, toCAIP2Network, toPartyLayerError, toProviderRpcError, transactionRejected, unauthorized, unsupportedMethod, userRejected, waitForProvider };