@icp-sdk/signer 5.2.0

package/lib/esm/web/heartbeat/client.d.ts

@@ -0,0 +1,60 @@
+export interface HeartbeatClientOptions {
+    /**
+     * Signer window to send and receive heartbeat messages from
+     */
+    signerWindow: Window;
+    /**
+     * Callback when first heartbeat has been received
+     */
+    onEstablish: (origin: string, status: 'pending' | 'ready') => void;
+    /**
+     * Reasonable time in milliseconds in which the communication channel needs to be established
+     * @default 10000
+     */
+    establishTimeout?: number;
+    /**
+     * Callback when no heartbeats have been received for `establishTimeout` milliseconds
+     */
+    onEstablishTimeout: () => void;
+    /**
+     * Callback when status response has changed
+     */
+    onStatusChange: (status: 'pending' | 'ready') => void;
+    /**
+     * Reasonable time in milliseconds in which the communication channel can be pending
+     * @default 300000
+     */
+    pendingTimeout?: number;
+    /**
+     * Callback when no heartbeats have been received for `pendingTimeout` milliseconds
+     */
+    onPendingTimeout: () => void;
+    /**
+     * Time in milliseconds of not receiving heartbeat responses after which the communication channel is disconnected
+     * @default 5000
+     */
+    disconnectTimeout?: number;
+    /**
+     * Callback when no heartbeats have been received for `disconnectTimeout` milliseconds
+     */
+    onDisconnect: () => void;
+    /**
+     * Status polling rate in ms
+     * @default 300
+     */
+    statusPollingRate?: number;
+    /**
+     * Relying party window, used to listen for incoming message events
+     * @default globalThis.window
+     */
+    window?: Window;
+    /**
+     * Get random uuid implementation for status messages
+     * @default globalThis.crypto
+     */
+    crypto?: Pick<Crypto, 'randomUUID'>;
+}
+export declare class HeartbeatClient {
+    #private;
+    constructor(options: HeartbeatClientOptions);
+}

package/lib/esm/web/heartbeat/client.js

@@ -0,0 +1,112 @@
+import { isJsonRpcResponse } from '../../transport.js';
+export class HeartbeatClient {
+    #options;
+    #status;
+    constructor(options) {
+        this.#options = {
+            establishTimeout: 10000,
+            pendingTimeout: 300000,
+            disconnectTimeout: 5000,
+            statusPollingRate: 300,
+            window: globalThis.window,
+            crypto: globalThis.crypto,
+            ...options,
+        };
+        this.#establish();
+    }
+    #establish() {
+        let pending = [];
+        // Create new pending entry that's waiting for a response
+        const create = () => {
+            const id = this.#options.crypto.randomUUID();
+            pending.push(id);
+            return id;
+        };
+        // Establish communication channel if a response is received for any pending id
+        const listener = this.#receiveStatusResponse(response => {
+            if ('result' in response.data &&
+                response.data.id !== null &&
+                pending.includes(response.data.id)) {
+                pending = [];
+                listener();
+                clearInterval(interval);
+                clearTimeout(timeout);
+                this.#status = response.data.result;
+                this.#options.onEstablish(response.origin, response.data.result);
+                this.#maintain(response.origin, response.data.result);
+            }
+        });
+        // Init timeout
+        const timeout = setTimeout(() => {
+            listener();
+            clearInterval(interval);
+            this.#options.onEstablishTimeout();
+        }, this.#options.establishTimeout);
+        // Start sending requests
+        const interval = setInterval(() => this.#sendStatusRequest(create()), this.#options.statusPollingRate);
+    }
+    #maintain(origin, status) {
+        let timeout;
+        let pending = [];
+        // Consume a pending entry if it exists
+        const consume = (id) => {
+            const index = pending.findIndex(entry => entry.id === id);
+            if (index > -1) {
+                pending.splice(index, 1);
+            }
+            return index > -1;
+        };
+        // Create new pending entry that's waiting for a response
+        const create = () => {
+            const id = this.#options.crypto.randomUUID();
+            const time = Date.now();
+            // Cleanup ids outside disconnect window
+            pending = pending.filter(entry => time - this.#options.disconnectTimeout > entry.time);
+            // Insert and return new id
+            pending.push({ id, time });
+            return id;
+        };
+        // Clear existing timeout (if any) and create a new one
+        const resetTimeout = (status) => {
+            clearTimeout(timeout);
+            timeout = setTimeout(() => {
+                listener();
+                this.#options.onDisconnect();
+            }, status === 'pending' ? this.#options.pendingTimeout : this.#options.disconnectTimeout);
+        };
+        // Reset disconnect timeout if a response is received to an id within disconnect window
+        const listener = this.#receiveStatusResponse(response => {
+            if ('result' in response.data &&
+                response.data.id !== null &&
+                response.origin === origin &&
+                consume(response.data.id)) {
+                resetTimeout(response.data.result);
+                if (this.#status !== response.data.result) {
+                    this.#status = response.data.result;
+                    this.#options.onStatusChange(response.data.result);
+                }
+            }
+            setTimeout(() => this.#sendStatusRequest(create()), this.#options.statusPollingRate);
+        });
+        // Init timeout and start sending requests
+        resetTimeout(status);
+        this.#sendStatusRequest(create());
+    }
+    #receiveStatusResponse(handler) {
+        const listener = (event) => {
+            if ((event.source === this.#options.signerWindow &&
+                isJsonRpcResponse(event.data) &&
+                'result' in event.data &&
+                event.data.result === 'pending') ||
+                event.data.result === 'ready') {
+                handler(event);
+            }
+        };
+        this.#options.window.addEventListener('message', listener);
+        return () => this.#options.window.removeEventListener('message', listener);
+    }
+    #sendStatusRequest(id) {
+        this.#options.signerWindow.postMessage({ jsonrpc: '2.0', id, method: 'icrc29_status' }, '*');
+    }
+}
+//# sourceMappingURL=client.js.map

package/lib/esm/web/heartbeat/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../../src/web/heartbeat/client.ts"],"names":[],"mappings":"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"}

package/lib/esm/web/heartbeat/server.d.ts

@@ -0,0 +1,43 @@
+export interface HeartbeatServerOptions {
+    /**
+     * The initial server status to return to the client
+     * @default "ready"
+     */
+    status?: 'pending' | 'ready';
+    /**
+     * The allowed origin that the communication channel can be established with, recommended for secure re-establishment
+     */
+    allowedOrigin?: string | null;
+    /**
+     * Callback when first heartbeat has been received
+     */
+    onEstablish: (origin: string, source: WindowProxy) => void;
+    /**
+     * Reasonable time in milliseconds in which the communication channel needs to be established
+     * @default 10000
+     */
+    establishTimeout?: number;
+    /**
+     * Callback when no heartbeats have been received for `establishTimeout` milliseconds
+     */
+    onEstablishTimeout: () => void;
+    /**
+     * Time in milliseconds of not receiving heartbeat requests after which the communication channel is disconnected
+     * @default 2000
+     */
+    disconnectTimeout?: number;
+    /**
+     * Callback when no heartbeats have been received for `disconnectTimeout` milliseconds
+     */
+    onDisconnect: () => void;
+    /**
+     * Signer window, used to listen for incoming message events
+     * @default globalThis.window
+     */
+    window?: Window;
+}
+export declare class HeartbeatServer {
+    #private;
+    constructor(options: HeartbeatServerOptions);
+    changeStatus(status: 'pending' | 'ready'): void;
+}

package/lib/esm/web/heartbeat/server.js

@@ -0,0 +1,82 @@
+import { isJsonRpcRequest } from '../../transport.js';
+export class HeartbeatServer {
+    #options;
+    constructor(options) {
+        this.#options = {
+            status: 'ready',
+            establishTimeout: 10000,
+            disconnectTimeout: 2000,
+            window: globalThis.window,
+            ...options,
+            allowedOrigin: options.allowedOrigin ?? null,
+        };
+        this.#establish();
+    }
+    changeStatus(status) {
+        this.#options.status = status;
+    }
+    #establish() {
+        // Establish communication channel if a request is received
+        const listener = this.#receiveStatusRequest(request => {
+            if (request.source === null || request.data.id === undefined) {
+                return;
+            }
+            listener();
+            clearTimeout(timeout);
+            this.#options.onEstablish(request.origin, request.source);
+            this.#sendStatusResponse(request.data.id, request.origin, request.source);
+            this.#maintain(request.origin, request.source);
+        });
+        // Send initial status response to kickstart the process
+        // in case the client is already waiting for responses.
+        //
+        // This resumes the client page from sleep in the case
+        // of browsers like Safari that unload background pages
+        // after a certain idle time and requiring an event to
+        // wake them up again (e.g. by sending a message to them).
+        if (this.#options.allowedOrigin !== null && this.#options.window.opener !== null) {
+            this.#sendStatusResponse('wake-up-client', this.#options.allowedOrigin, this.#options.window.opener);
+        }
+        // Init timeout
+        const timeout = setTimeout(() => {
+            listener();
+            this.#options.onEstablishTimeout();
+        }, this.#options.establishTimeout);
+    }
+    #maintain(origin, source) {
+        let timeout;
+        // Clear existing timeout (if any) and create a new one
+        const resetTimeout = () => {
+            clearTimeout(timeout);
+            timeout = setTimeout(() => {
+                listener();
+                this.#options.onDisconnect();
+            }, this.#options.disconnectTimeout);
+        };
+        // Init timeout and start sending messages
+        resetTimeout();
+        // Reset disconnect timeout and send response if a request is received
+        const listener = this.#receiveStatusRequest(request => {
+            if (request.origin === origin && request.source === source && request.data.id !== undefined) {
+                resetTimeout();
+                this.#sendStatusResponse(request.data.id, request.origin, request.source);
+            }
+        });
+    }
+    #receiveStatusRequest(handler) {
+        const listener = (event) => {
+            if (!isJsonRpcRequest(event.data) ||
+                event.data.method !== 'icrc29_status' ||
+                (this.#options.allowedOrigin !== null && event.origin !== this.#options.allowedOrigin)) {
+                return;
+            }
+            handler(event);
+        };
+        this.#options.window.addEventListener('message', listener);
+        return () => this.#options.window.removeEventListener('message', listener);
+    }
+    #sendStatusResponse(id, origin, source) {
+        source.postMessage({ jsonrpc: '2.0', id, result: this.#options.status }, origin);
+    }
+}
+//# sourceMappingURL=server.js.map

package/lib/esm/web/heartbeat/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../../src/web/heartbeat/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAyCtD,MAAM,OAAO,eAAe;IACjB,QAAQ,CAAmC;IAEpD,YAAY,OAA+B;QACzC,IAAI,CAAC,QAAQ,GAAG;YACd,MAAM,EAAE,OAAO;YACf,gBAAgB,EAAE,KAAK;YACvB,iBAAiB,EAAE,IAAI;YACvB,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,GAAG,OAAO;YACV,aAAa,EAAE,OAAO,CAAC,aAAa,IAAI,IAAI;SAC7C,CAAC;QAEF,IAAI,CAAC,UAAU,EAAE,CAAC;IACpB,CAAC;IAED,YAAY,CAAC,MAA2B;QACtC,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC;IAChC,CAAC;IAED,UAAU;QACR,2DAA2D;QAC3D,MAAM,QAAQ,GAAG,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAAE;YACpD,IAAI,OAAO,CAAC,MAAM,KAAK,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;gBAC7D,OAAO;YACT,CAAC;YACD,QAAQ,EAAE,CAAC;YACX,YAAY,CAAC,OAAO,CAAC,CAAC;YAEtB,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAqB,CAAC,CAAC;YACzE,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YAC1E,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;QAEH,wDAAwD;QACxD,uDAAuD;QACvD,EAAE;QACF,sDAAsD;QACtD,uDAAuD;QACvD,sDAAsD;QACtD,0DAA0D;QAC1D,IAAI,IAAI,CAAC,QAAQ,CAAC,aAAa,KAAK,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YACjF,IAAI,CAAC,mBAAmB,CACtB,gBAAgB,EAChB,IAAI,CAAC,QAAQ,CAAC,aAAa,EAC3B,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAC5B,CAAC;QACJ,CAAC;QAED,eAAe;QACf,MAAM,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE;YAC9B,QAAQ,EAAE,CAAC;YAEX,IAAI,CAAC,QAAQ,CAAC,kBAAkB,EAAE,CAAC;QACrC,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC;IACrC,CAAC;IAED,SAAS,CAAC,MAAc,EAAE,MAA0B;QAClD,IAAI,OAAsC,CAAC;QAE3C,uDAAuD;QACvD,MAAM,YAAY,GAAG,GAAG,EAAE;YACxB,YAAY,CAAC,OAAO,CAAC,CAAC;YACtB,OAAO,GAAG,UAAU,CAAC,GAAG,EAAE;gBACxB,QAAQ,EAAE,CAAC;gBAEX,IAAI,CAAC,QAAQ,CAAC,YAAY,EAAE,CAAC;YAC/B,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;QACtC,CAAC,CAAC;QAEF,0CAA0C;QAC1C,YAAY,EAAE,CAAC;QAEf,sEAAsE;QACtE,MAAM,QAAQ,GAAG,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC,EAAE;YACpD,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,IAAI,OAAO,CAAC,MAAM,KAAK,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;gBAC5F,YAAY,EAAE,CAAC;gBACf,IAAI,CAAC,mBAAmB,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;YAC5E,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,qBAAqB,CAAC,OAAsC;QAC1D,MAAM,QAAQ,GAAG,CAAC,KAAmB,EAAE,EAAE;YACvC,IACE,CAAC,gBAAgB,CAAC,KAAK,CAAC,IAAI,CAAC;gBAC7B,KAAK,CAAC,IAAI,CAAC,MAAM,KAAK,eAAe;gBACrC,CAAC,IAAI,CAAC,QAAQ,CAAC,aAAa,KAAK,IAAI,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,EACtF,CAAC;gBACD,OAAO;YACT,CAAC;YACD,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC,CAAC;QACF,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,gBAAgB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;QAC3D,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,mBAAmB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC7E,CAAC;IAED,mBAAmB,CAAC,EAAmB,EAAE,MAAc,EAAE,MAA0B;QAChF,MAAsB,CAAC,WAAW,CACjC,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,EACpD,MAAM,CACP,CAAC;IACJ,CAAC;CACF"}

package/lib/esm/web/index.d.ts

@@ -0,0 +1,4 @@
+export { HeartbeatClient, type HeartbeatClientOptions } from './heartbeat/client.js';
+export { HeartbeatServer, type HeartbeatServerOptions } from './heartbeat/server.js';
+export { PostMessageChannel, type PostMessageChannelOptions } from './postMessageChannel.js';
+export { PostMessageTransport, PostMessageTransportError, type PostMessageTransportOptions, } from './postMessageTransport.js';

package/lib/esm/web/index.js

@@ -0,0 +1,5 @@
+export { HeartbeatClient } from './heartbeat/client.js';
+export { HeartbeatServer } from './heartbeat/server.js';
+export { PostMessageChannel } from './postMessageChannel.js';
+export { PostMessageTransport, PostMessageTransportError, } from './postMessageTransport.js';
+//# sourceMappingURL=index.js.map

package/lib/esm/web/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/web/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAA+B,MAAM,uBAAuB,CAAC;AACrF,OAAO,EAAE,eAAe,EAA+B,MAAM,uBAAuB,CAAC;AACrF,OAAO,EAAE,kBAAkB,EAAkC,MAAM,yBAAyB,CAAC;AAC7F,OAAO,EACL,oBAAoB,EACpB,yBAAyB,GAE1B,MAAM,2BAA2B,CAAC"}

package/lib/esm/web/postMessageChannel.d.ts

@@ -0,0 +1,55 @@
+import { type Channel, type JsonRpcRequest, type JsonRpcResponse } from '../transport.js';
+/** Options for creating a {@link PostMessageChannel}. */
+export interface PostMessageChannelOptions {
+    /** The signer window that this channel communicates with. */
+    signerWindow: Window;
+    /** The verified origin of the signer window. */
+    signerOrigin: string;
+    /**
+     * Initial status of the signer. When `"pending"`, messages are queued
+     * until the status changes to `"ready"`.
+     * @default "ready"
+     */
+    signerStatus?: 'pending' | 'ready';
+    /**
+     * The relying party window, used to listen for incoming `postMessage` events.
+     * @default globalThis.window
+     */
+    window?: Window;
+    /**
+     * Manage focus between the relying party and signer windows.
+     * @default true
+     */
+    manageFocus?: boolean;
+}
+/**
+ * A {@link Channel} implementation that communicates with a signer
+ * via `window.postMessage`. Created by {@link PostMessageTransport}
+ * after the ICRC-29 heartbeat handshake completes.
+ *
+ * Messages are filtered by source window and origin to prevent
+ * cross-origin interference. When the signer status is `"pending"`,
+ * outgoing messages are queued and flushed when it becomes `"ready"`.
+ */
+export declare class PostMessageChannel implements Channel {
+    #private;
+    constructor(options: PostMessageChannelOptions);
+    /** Whether this channel has been closed. */
+    get closed(): boolean;
+    addEventListener(...[event, listener]: [event: 'close', listener: () => void] | [event: 'response', listener: (response: JsonRpcResponse) => void]): () => void;
+    /**
+     * Sends a JSON-RPC request to the signer. If the signer status is
+     * `"pending"`, the request is queued until {@link changeStatus} is
+     * called with `"ready"`.
+     * @param request - The JSON-RPC request to send.
+     */
+    send(request: JsonRpcRequest): Promise<void>;
+    /** Closes the signer window and notifies all close listeners. */
+    close(): Promise<void>;
+    /**
+     * Updates the signer status. When transitioning to `"ready"`,
+     * all queued messages are flushed to the signer window.
+     * @param status - The new signer status.
+     */
+    changeStatus(status: 'pending' | 'ready'): void;
+}

package/lib/esm/web/postMessageChannel.js

@@ -0,0 +1,109 @@
+import { isJsonRpcResponse, } from '../transport.js';
+import { PostMessageTransportError } from './postMessageTransport.js';
+/**
+ * A {@link Channel} implementation that communicates with a signer
+ * via `window.postMessage`. Created by {@link PostMessageTransport}
+ * after the ICRC-29 heartbeat handshake completes.
+ *
+ * Messages are filtered by source window and origin to prevent
+ * cross-origin interference. When the signer status is `"pending"`,
+ * outgoing messages are queued and flushed when it becomes `"ready"`.
+ */
+export class PostMessageChannel {
+    #closeListeners = new Set();
+    #options;
+    #closed = false;
+    #pendingQueue = [];
+    constructor(options) {
+        this.#options = {
+            signerStatus: 'ready',
+            window: globalThis.window,
+            manageFocus: true,
+            ...options,
+        };
+    }
+    /** Whether this channel has been closed. */
+    get closed() {
+        return this.#closed;
+    }
+    addEventListener(...[event, listener]) {
+        switch (event) {
+            case 'close':
+                this.#closeListeners.add(listener);
+                return () => {
+                    this.#closeListeners.delete(listener);
+                };
+            case 'response': {
+                const messageListener = (event) => {
+                    // Only accept messages from the signer's window and origin
+                    if (event.source !== this.#options.signerWindow ||
+                        event.origin !== this.#options.signerOrigin ||
+                        !isJsonRpcResponse(event.data)) {
+                        return;
+                    }
+                    listener(event.data);
+                };
+                this.#options.window.addEventListener('message', messageListener);
+                return () => {
+                    this.#options.window.removeEventListener('message', messageListener);
+                };
+            }
+        }
+    }
+    /**
+     * Sends a JSON-RPC request to the signer. If the signer status is
+     * `"pending"`, the request is queued until {@link changeStatus} is
+     * called with `"ready"`.
+     * @param request - The JSON-RPC request to send.
+     */
+    send(request) {
+        if (this.#closed) {
+            return Promise.reject(new PostMessageTransportError('Communication channel is closed'));
+        }
+        if (this.#options.signerStatus === 'pending') {
+            this.#pendingQueue.push(request);
+            return Promise.resolve();
+        }
+        try {
+            this.#options.signerWindow.postMessage(request, this.#options.signerOrigin);
+            if (this.#options.manageFocus) {
+                this.#options.signerWindow.focus();
+            }
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+        return Promise.resolve();
+    }
+    /** Closes the signer window and notifies all close listeners. */
+    close() {
+        if (this.#closed) {
+            return Promise.resolve();
+        }
+        this.#closed = true;
+        this.#options.signerWindow.close();
+        if (this.#options.manageFocus) {
+            this.#options.window.focus();
+        }
+        for (const listener of this.#closeListeners) {
+            listener();
+        }
+        return Promise.resolve();
+    }
+    /**
+     * Updates the signer status. When transitioning to `"ready"`,
+     * all queued messages are flushed to the signer window.
+     * @param status - The new signer status.
+     */
+    changeStatus(status) {
+        this.#options.signerStatus = status;
+        if (status === 'ready') {
+            const requests = this.#pendingQueue;
+            this.#pendingQueue = [];
+            requests.forEach(request => {
+                this.#options.signerWindow.postMessage(request, this.#options.signerOrigin);
+            });
+        }
+    }
+}
+//# sourceMappingURL=postMessageChannel.js.map

package/lib/esm/web/postMessageChannel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"postMessageChannel.js","sourceRoot":"","sources":["../../../src/web/postMessageChannel.ts"],"names":[],"mappings":"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"}

package/lib/esm/web/postMessageTransport.d.ts

@@ -0,0 +1,96 @@
+import type { Transport } from '../transport.js';
+import { PostMessageChannel } from './postMessageChannel.js';
+/** Error thrown by {@link PostMessageTransport} for transport-level failures. */
+export declare class PostMessageTransportError extends Error {
+}
+/** Options for creating a {@link PostMessageTransport}. */
+export interface PostMessageTransportOptions {
+    /** The signer's RPC URL. Must be a secure context (HTTPS, localhost, or 127.0.0.1). */
+    url: string;
+    /**
+     * Window features string passed to `window.open()`.
+     * @example "toolbar=0,location=0,menubar=0,width=500,height=500,left=100,top=100"
+     */
+    windowOpenerFeatures?: string;
+    /**
+     * The relying party window, used to listen for incoming `postMessage` events.
+     * @default globalThis.window
+     */
+    window?: Window;
+    /**
+     * Time in milliseconds to wait for the ICRC-29 heartbeat handshake to complete.
+     * @default 120000
+     */
+    establishTimeout?: number;
+    /**
+     * Time in milliseconds the channel can remain in "pending" status
+     * before the connection is considered failed.
+     * @default 300000
+     */
+    pendingTimeout?: number;
+    /**
+     * Time in milliseconds without a heartbeat response after which
+     * the channel is considered disconnected.
+     * @default 2000
+     */
+    disconnectTimeout?: number;
+    /**
+     * Interval in milliseconds between ICRC-29 heartbeat status polls.
+     * @default 300
+     */
+    statusPollingRate?: number;
+    /**
+     * Source of random UUIDs for heartbeat request IDs.
+     * @default globalThis.crypto
+     */
+    crypto?: Pick<Crypto, 'randomUUID'>;
+    /**
+     * Manage focus between the relying party and signer windows.
+     * When true, the signer window is focused on send and the relying
+     * party window is focused on close.
+     * @default true
+     */
+    manageFocus?: boolean;
+    /**
+     * Close the signer window if the heartbeat handshake times out.
+     * @default true
+     */
+    closeOnEstablishTimeout?: boolean;
+    /**
+     * Close the signer window if it stays in "pending" status too long.
+     * @default true
+     */
+    closeOnPendingTimeout?: boolean;
+    /**
+     * Detect and reject attempts to open the signer window outside a
+     * click handler. Browsers like Safari block popups opened without
+     * user interaction.
+     * @default true
+     */
+    detectNonClickEstablishment?: boolean;
+}
+/**
+ * ICRC-29 post message transport for communicating with web-based signers.
+ *
+ * Opens a window to the signer's URL and establishes a communication channel
+ * using the ICRC-29 heartbeat protocol (`icrc29_status` polling). Messages
+ * are exchanged via `window.postMessage`.
+ * @see https://github.com/dfinity/wg-identity-authentication/blob/main/topics/icrc_29_window_post_message_transport.md
+ * @example
+ * ```ts
+ * const transport = new PostMessageTransport({ url: "https://oisy.com/sign" });
+ * const signer = new Signer({ transport });
+ * ```
+ */
+export declare class PostMessageTransport implements Transport {
+    #private;
+    constructor(options: PostMessageTransportOptions);
+    /**
+     * Opens the signer window and establishes a communication channel
+     * via the ICRC-29 heartbeat handshake.
+     * @throws {PostMessageTransportError} If called outside a click handler
+     *   (when `detectNonClickEstablishment` is enabled), if the window
+     *   cannot be opened, or if the handshake times out.
+     */
+    establishChannel(): Promise<PostMessageChannel>;
+}