@geeqdev/geeq-sdk 0.1.0 → 0.2.0

package/dist/src/socket/geeq-socket.d.ts

@@ -0,0 +1,232 @@
+import type { AccountRef } from '../crypto/account-id';
+import type { GeeqWebSocketFactory } from '../net/websocket';
+import { GeeqTrackedTx } from './tracked-tx';
+import type { GeeqTxStatusEvent } from './tx-status';
+/**
+ * - `connecting` — the first handshake, inside {@link GeeqSocket.connect}.
+ * - `open` — subscribed and receiving.
+ * - `reconnecting` — dropped after being open; retrying with backoff. Anything the node
+ *   sends meanwhile is lost.
+ * - `closed` — disposed. Final.
+ */
+export type GeeqSocketState = 'connecting' | 'open' | 'reconnecting' | 'closed';
+/** One JSON frame from the node, as `{ event, payload }`. */
+export interface GeeqSocketMessage {
+    readonly event: string;
+    readonly payload: unknown;
+}
+export interface GeeqSocketOptions {
+    /**
+     * The node the socket belongs to — normally `chain.endpoint`, which is also where the
+     * transactions go. Its socket is derived: `https://ip:2082` becomes
+     * `wss://ip:2082/ws/`.
+     *
+     * Supply this or {@link url}, not both. Use the node you submit to: only that node
+     * reports a `nonsane` refusal, though every node reports the final verdicts.
+     */
+    readonly endpoint?: string | URL;
+    /**
+     * The socket URL itself, when it is not the one derived from the node — a local
+     * harness reaching the socket server directly on its own port, for instance.
+     */
+    readonly url?: string | URL;
+    /** Defaults to `new globalThis.WebSocket(url)`. Supply one on Node 20 — see README. */
+    readonly webSocket?: GeeqWebSocketFactory;
+    /**
+     * How long a handshake, or a send waiting on one, may take. Defaults to 15000. 0 waits
+     * for ever — including a first handshake that neither opens nor fails.
+     */
+    readonly openTimeoutMs?: number;
+    /** How often to send the keepalive `'ping'`. Defaults to 25000; 0 disables it. */
+    readonly heartbeatMs?: number;
+    /** Reconnect after a drop. Defaults to true. */
+    readonly reconnect?: boolean;
+    /** The first reconnect delay, doubled on each failure. Defaults to 1000. */
+    readonly reconnectDelayMs?: number;
+    /** The ceiling on that delay. Defaults to 30000. */
+    readonly maxReconnectDelayMs?: number;
+    /** Abandons the first handshake. Once connected, use {@link GeeqSocket.dispose}. */
+    readonly signal?: AbortSignal;
+}
+export interface GeeqSendOptions {
+    /**
+     * Re-send the frame on every reconnect. A node forgets a connection's subscriptions
+     * when it drops, so anything that subscribes should set this. Only the latest frame for
+     * each event name is kept.
+     */
+    readonly replay?: boolean;
+}
+export interface GeeqListenOptions {
+    readonly blockNumber?: number;
+    /** Defaults to true. */
+    readonly now?: boolean;
+}
+export interface GeeqTrackOptions {
+    /** How long to wait for a final status. Defaults to 300000. 0 waits for ever. */
+    readonly timeoutMs?: number;
+    /** How long a `nonsane` may be overturned by a real verdict. Defaults to 30000. */
+    readonly nonsaneGraceMs?: number;
+    /** More accounts to subscribe alongside the signer. */
+    readonly accounts?: readonly (AccountRef | string)[];
+}
+/**
+ * Anything with the hash a status event names. Every transaction this SDK builds fits,
+ * and brings its signer's `publicKey` for the subscription.
+ */
+export interface GeeqTrackable {
+    readonly transactionHash: Uint8Array;
+    readonly publicKey?: Uint8Array;
+}
+/**
+ * A node's WebSocket: the channel through which it reports what happened to the
+ * transactions you sent, and pushes account and chain updates.
+ *
+ * One class for every use an application has for the socket:
+ *
+ * - {@link track} a transaction you are about to submit, and get its verdict;
+ * - {@link subscribe} to accounts and read their events with {@link on};
+ * - {@link send} any frame the node understands, and receive any it sends.
+ *
+ * The protocol's hazards are handled here, once: subscriptions replace rather than add,
+ * so the full set of keys is always sent; the node forgets a connection's subscriptions
+ * when it drops, so they are replayed on every reconnect before anything is announced;
+ * the edge proxy drops an idle socket, so it is kept alive; a transaction's first status
+ * is not always its last, so {@link GeeqTrackedTx} decides when it is final.
+ *
+ * ```ts
+ * const socket = await GeeqSocket.connect({ endpoint: chain.endpoint })
+ * const tx = await chain.createTransfer({ from, to, amount })
+ * const tracked = await socket.track(tx)          // before submitting — always
+ * const response = await fetch(submitRoute(tx.nodeUrl), { … })
+ * if (!response.ok) tracked.refused({ status: response.status })
+ * const outcome = await tracked.settled()
+ * ```
+ *
+ * In a reactive framework, mark an instance raw (Vue's `markRaw`) rather than letting it
+ * be proxied — a proxied native WebSocket throws on every call.
+ */
+export declare class GeeqSocket {
+    /** The socket URL, normalised. */
+    readonly url: string;
+    private readonly factory;
+    private readonly openTimeoutMs;
+    private readonly heartbeatMs;
+    private readonly reconnects;
+    private readonly reconnectDelayMs;
+    private readonly maxReconnectDelayMs;
+    /** The frames in force, by event name, replayed on every connection. */
+    private readonly persisted;
+    /** What this connection has already been told, so a repeat is not sent twice. */
+    private readonly told;
+    private readonly keys;
+    private readonly tracked;
+    private readonly eventListeners;
+    private readonly messageListeners;
+    private readonly statusListeners;
+    private readonly stateListeners;
+    private readonly waiters;
+    private socket;
+    private current;
+    private everOpened;
+    private attempts;
+    private openTimer;
+    private reconnectTimer;
+    private heartbeatTimer;
+    /** @internal */
+    constructor(init: {
+        url: string;
+        factory: GeeqWebSocketFactory;
+        openTimeoutMs: number;
+        heartbeatMs: number;
+        reconnect: boolean;
+        reconnectDelayMs: number;
+        maxReconnectDelayMs: number;
+    });
+    /**
+     * Open a node's socket and resolve once it is open.
+     *
+     * Throws `socket-unreachable` if the first handshake fails, rather than retrying
+     * quietly: a socket that never opened is almost always a certificate, a mixed-content
+     * page or a wrong URL, and retrying hides which. After that first open, a drop is
+     * retried automatically and reported through {@link onConnectionChange}.
+     */
+    static connect(options: GeeqSocketOptions): Promise<GeeqSocket>;
+    /** Where the connection stands. See {@link GeeqSocketState}. */
+    get state(): GeeqSocketState;
+    /** Every account key subscribed so far, base64. The set only grows. */
+    get subscriptions(): readonly string[];
+    /**
+     * Subscribe to accounts' events: their transactions' statuses and record updates.
+     *
+     * Takes a keypair, a `{ publicKey }`, a 32-byte account id, a base64 key, or a list of
+     * them. The node has no unsubscribe and treats every subscription as a replacement, so
+     * this adds to the set this socket holds and sends all of it — calling it for one
+     * account never silences another. Resolves once the node has been told.
+     */
+    subscribe(accounts: AccountRef | string | readonly (AccountRef | string)[]): Promise<void>;
+    /** Ask for events from now, or from a block. Replayed on reconnect. */
+    listen(options?: GeeqListenOptions): Promise<void>;
+    /**
+     * Subscribe to the whole chain's record feed — every account, fee and parameter update.
+     * What a block explorer or an indexer wants; an ordinary application does not.
+     */
+    subscribeBlockExplorer(): Promise<void>;
+    /**
+     * Send a frame, `{ event, payload }`, waiting for the connection if it is down.
+     *
+     * The escape hatch for anything the node understands that this class has no method
+     * for. Rejects with `socket-unreachable` if the socket does not reopen within
+     * `openTimeoutMs` — a replayed frame is still kept, and goes out when it does.
+     */
+    send(event: string, payload?: unknown, options?: GeeqSendOptions): Promise<void>;
+    /**
+     * Follow a transaction to its verdict. Call it **before** submitting.
+     *
+     * Subscribes the signer — the node pushes a transaction's statuses only to connections
+     * subscribed to its account — and resolves once the node has been told, so a status
+     * cannot arrive before anyone is listening for it. If this throws, do not submit: a
+     * transaction sent with no way to hear its verdict leaves the user guessing.
+     *
+     * Tracking the same transaction twice returns the same handle.
+     */
+    track(tx: GeeqTrackable, options?: GeeqTrackOptions): Promise<GeeqTrackedTx>;
+    /**
+     * Call `listener` with the payload of every frame named `event`, whatever it is —
+     * `'uut_status'`, `'coin-account-update'`, `'fee-update'`, or one this SDK has never
+     * heard of. Returns the function that removes it.
+     */
+    on(event: string, listener: (payload: unknown) => void): () => void;
+    /** Call `listener` with every JSON frame the node sends. */
+    onMessage(listener: (message: GeeqSocketMessage) => void): () => void;
+    /** Call `listener` with every transaction status, tracked or not, already parsed. */
+    onTxStatus(listener: (event: GeeqTxStatusEvent) => void): () => void;
+    /** Call `listener` whenever {@link state} changes. */
+    onConnectionChange(listener: (state: GeeqSocketState) => void): () => void;
+    /**
+     * Close for good. Pending sends reject with `socket-closed`, and every transaction still
+     * being tracked settles `unknown` with reason `closed` — it may yet be decided, just
+     * not heard about here.
+     */
+    dispose(): void;
+    toJSON(): Record<string, unknown>;
+    toString(): string;
+    private assertOpenable;
+    private setState;
+    /** Resolves when the socket is open, or rejects after `openTimeoutMs` or on dispose. */
+    private whenOpen;
+    private dial;
+    private opened;
+    /** A handshake failed, or an open socket dropped. */
+    private attemptFailed;
+    /**
+     * Put one frame on the current connection. True once it is there — or already was.
+     *
+     * False means the connection is gone. If our books still said it was open, it is
+     * treated as the drop it is, here and now, so the caller waits for the next connection
+     * instead of spinning on this one.
+     */
+    private transmit;
+    private receive;
+    private startHeartbeat;
+    private stopHeartbeat;
+}