@usearete/sdk 0.23.1 → 0.25.0

package/dist/testing.d.ts

@@ -0,0 +1,482 @@
+import { TransactionSimulationResult, TransactionSignatureStatus, TransactionTransport, BuiltInstruction, WalletExecutionContext, SendResult, TransactionFailureOutcome, TransactionVersion, TransactionInspectionResult, WalletAdapter, SendOptions, TransactionInspectionOptions, TransactionExecutionError, ConfirmedTransactionOutcome, SubscriptionQuery, FrameMode, SortConfig, ReplayWindow, Schema, FrameValidationDiagnostic, MemoryAdapter, QueryStore, FrameProcessor, Subscription, QuerySnapshot, WebSocketFactoryInit } from '@usearete/sdk';
+
+/** Every relay route, as recorded in {@link FakeTransactionTransport.calls}. */
+type FakeTransactionCall = 'latest-blockhash' | 'fee' | 'simulate' | 'send' | 'status' | 'height';
+interface FakeTransactionTransportOptions {
+    /** Blockhash returned by `getLatestBlockhash` (default: 32 zero bytes). */
+    readonly blockhash?: string;
+    readonly lastValidBlockHeight?: bigint;
+    /** Height returned by `getBlockHeight` (default `10n`). */
+    readonly blockHeight?: bigint;
+    /** Fee returned by `getFeeForMessage` (default `5000n`). */
+    readonly feeLamports?: bigint | null;
+    /** Fields merged over the default successful simulation. */
+    readonly simulation?: Partial<TransactionSimulationResult>;
+    /**
+     * Signature `sendTransaction` answers with. Defaults to the first signature
+     * carried by the submitted wire transaction, as a real relay echoes it.
+     */
+    readonly signature?: string | ((transaction: string) => string);
+    /** Fail the submission with this value, after recording the dispatch. */
+    readonly sendError?: unknown;
+    /** Record the dispatch, then never answer: a stalled relay. */
+    readonly stallSend?: boolean;
+    /**
+     * Status answered by `getSignatureStatus`. Defaults to confirmed at slot
+     * `42n`; `null` means the relay does not know the signature (yet).
+     */
+    readonly status?: Partial<Omit<TransactionSignatureStatus, 'signature'>> | null;
+    /** Fail every status poll with this value. */
+    readonly statusError?: unknown;
+    /** Answer the submission, then never answer a status poll. */
+    readonly stallStatus?: boolean;
+}
+/**
+ * A recording {@link TransactionTransport}. `calls` is how a test asserts
+ * "never sent": inspection records `fee` and `simulate`, and only a submission
+ * records `send`.
+ */
+interface FakeTransactionTransport extends TransactionTransport {
+    readonly calls: FakeTransactionCall[];
+    /** Wire transactions passed to `simulateTransaction`, in order. */
+    readonly simulated: string[];
+    /** Wire transactions passed to `sendTransaction`, in order. */
+    readonly sent: string[];
+    /** Messages passed to `getFeeForMessage`, in order. */
+    readonly feeMessages: string[];
+    /** Forget every recorded call. */
+    reset(): void;
+}
+/**
+ * The first signature a base64 wire transaction carries (compact-u16 count,
+ * then 64-byte signatures), or `undefined` when the bytes are not one.
+ */
+declare function firstSignatureOfWireTransaction(transaction: string): string | undefined;
+/**
+ * Create a recording, scriptable {@link TransactionTransport} for tests: pass
+ * it as `ConnectOptions.transactions`, `useArete(stack, { transactions })`, or
+ * an adapter's `transport`. Nothing reaches a network.
+ */
+declare function createFakeTransactionTransport(options?: FakeTransactionTransportOptions): FakeTransactionTransport;
+
+/** A deterministic, well-formed wallet address for fixtures. */
+declare const FIXTURE_WALLET_ADDRESS: string;
+interface WalletFixtureCall<TOptions> {
+    readonly instructions: readonly BuiltInstruction[];
+    readonly options: TOptions | undefined;
+    readonly context: WalletExecutionContext | undefined;
+}
+/** What one `signAndSend` call does. */
+type WalletFixtureResponse = SendResult | TransactionFailureOutcome | Error | 'stall';
+interface WalletFixtureOptions {
+    /** Wallet address (default {@link FIXTURE_WALLET_ADDRESS}). */
+    readonly publicKey?: string;
+    /** Additional signer addresses the wallet can satisfy. */
+    readonly signerAddresses?: readonly string[];
+    /** Advertised versions; omitted means unknown, as for a real adapter. */
+    readonly supportedTransactionVersions?: readonly TransactionVersion[];
+    /**
+     * Responses for successive sends; the last one repeats. A failure outcome
+     * is thrown as a `TransactionExecutionError`, `'stall'` never settles.
+     * Default: confirmed, with a distinct signature and slot per call.
+     */
+    readonly responses?: readonly WalletFixtureResponse[];
+    /**
+     * Result of `inspectTransaction`, or `false` for a wallet without the
+     * inspection capability. Default: a successful simulation.
+     */
+    readonly inspection?: TransactionInspectionResult | false;
+}
+interface WalletFixture extends WalletAdapter {
+    /** Every `signAndSend` call, in order. */
+    readonly sent: WalletFixtureCall<SendOptions>[];
+    /** Every `inspectTransaction` call, in order. */
+    readonly inspected: WalletFixtureCall<TransactionInspectionOptions>[];
+    /** Forget every recorded call. */
+    reset(): void;
+}
+/**
+ * A recording {@link WalletAdapter} for tests. It holds no keys and builds no
+ * transactions: `signAndSend` answers from `responses`, so a test can drive a
+ * mutation through every outcome without a chain.
+ */
+declare function createWalletFixture(options?: WalletFixtureOptions): WalletFixture;
+
+/** A deterministic, well-formed transaction signature for fixtures. */
+declare const FIXTURE_SIGNATURE: string;
+/** The slot fixture outcomes land in. */
+declare const FIXTURE_SLOT = 4242;
+/** Every status/phase pair the outcome model defines. */
+type TransactionOutcomeFixtureName = 'confirmed' | 'not-submitted:build' | 'not-submitted:wallet' | 'not-submitted:send' | 'submitted-unknown:send' | 'submitted-unknown:confirmation' | 'chain-failed:confirmation' | 'chain-failed:chain';
+declare function fixtures(): {
+    confirmed: ConfirmedTransactionOutcome;
+    'not-submitted:build': {
+        status: "not-submitted";
+        phase: "build" | "wallet" | "send";
+        cause: Error;
+    };
+    'not-submitted:wallet': {
+        status: "not-submitted";
+        phase: "build" | "wallet" | "send";
+        cause: Error;
+    };
+    'not-submitted:send': {
+        status: "not-submitted";
+        phase: "build" | "wallet" | "send";
+        cause: Error;
+    };
+    'submitted-unknown:send': {
+        status: "submitted-unknown";
+        phase: "send" | "confirmation";
+        signature: string;
+        cause: Error;
+    };
+    'submitted-unknown:confirmation': {
+        status: "submitted-unknown";
+        phase: "send" | "confirmation";
+        signature: string;
+        cause: Error;
+    };
+    'chain-failed:confirmation': {
+        status: "chain-failed";
+        phase: "confirmation" | "chain";
+        signature: string;
+        slot: number;
+        programError: {
+            code: number;
+            name: string;
+            message: string;
+        };
+        cause: {
+            InstructionError: (number | {
+                Custom: number;
+            })[];
+        };
+    };
+    'chain-failed:chain': {
+        status: "chain-failed";
+        phase: "confirmation" | "chain";
+        signature: string;
+        slot: number;
+        programError: {
+            code: number;
+            name: string;
+            message: string;
+        };
+        cause: {
+            InstructionError: (number | {
+                Custom: number;
+            })[];
+        };
+    };
+};
+/**
+ * One fresh outcome per status/phase pair of the transaction outcome model:
+ * `confirmed`, `not-submitted`, `submitted-unknown` and `chain-failed`.
+ */
+declare function createTransactionOutcomeFixtures(): ReturnType<typeof fixtures>;
+/** One outcome by name, with optional field overrides. */
+declare function transactionOutcomeFixture<TName extends TransactionOutcomeFixtureName>(name: TName, overrides?: Partial<ReturnType<typeof fixtures>[TName]>): ReturnType<typeof fixtures>[TName];
+/**
+ * The structured error an adapter throws for a failure outcome, as
+ * `useMutation`, `execute` and `getTransactionFailureOutcome` classify it.
+ */
+declare function transactionFailureError(outcome: TransactionFailureOutcome): TransactionExecutionError;
+
+/** The subscription a frame answers: a client `subscribe` message, or its id and query. */
+interface FrameTarget {
+    readonly subscriptionId: string;
+    readonly query: SubscriptionQuery;
+}
+interface LiveFrameOptions {
+    /** Defaults to `'state'` for keyed queries and `'list'` otherwise. */
+    readonly mode?: FrameMode;
+    /** `"<slot>:<index>"` sequence. */
+    readonly seq?: string;
+    /** Tape offset, for replayable append views. */
+    readonly offset?: number;
+}
+/**
+ * Builders for WebSocket protocol v2 server frames, addressed to a
+ * subscription. Payloads use the wire shape (snake_case, u64 as decimal
+ * strings); the SDK's generated schemas normalize them as they would live.
+ */
+declare const frames: {
+    subscribed(target: FrameTarget, options?: {
+        readonly mode?: FrameMode;
+        readonly sort?: SortConfig;
+        readonly replayWindow?: ReplayWindow;
+        /**
+         * Advertise the whole-entity guarantee, as current servers do (the
+         * default). Pass `false` to act as an older server, whose patches for
+         * keys the client does not hold are kept.
+         */
+        readonly wholeEntities?: boolean;
+    }): {
+        wholeEntities?: boolean | undefined;
+        replayWindow?: ReplayWindow | undefined;
+        sort?: SortConfig | undefined;
+        protocolVersion: 2;
+        subscriptionId: string;
+        op: "subscribed";
+        query: SubscriptionQuery;
+        mode: FrameMode;
+    };
+    snapshot(target: FrameTarget, rows: readonly {
+        readonly key: string;
+        readonly data: unknown;
+    }[], options?: {
+        readonly mode?: FrameMode;
+        readonly snapshotId?: string;
+        readonly authoritative?: boolean;
+        readonly complete?: boolean;
+    }): {
+        data: {
+            key: string;
+            data: unknown;
+        }[];
+        complete: boolean;
+        key?: string | undefined;
+        protocolVersion: 2;
+        subscriptionId: string;
+        snapshotId: string;
+        authoritative: boolean;
+        mode: FrameMode;
+        entity: string;
+        op: "snapshot";
+    };
+    upsert(target: FrameTarget, key: string, data: unknown, options?: LiveFrameOptions): {
+        append?: string[] | undefined;
+        offset?: number | undefined;
+        seq?: string | undefined;
+        protocolVersion: 2;
+        subscriptionId: string;
+        mode: FrameMode;
+        entity: string;
+        op: "upsert" | "patch" | "remove" | "delete";
+        key: string;
+        data: unknown;
+    };
+    patch(target: FrameTarget, key: string, data: unknown, options?: LiveFrameOptions & {
+        readonly append?: readonly string[];
+    }): {
+        append?: string[] | undefined;
+        offset?: number | undefined;
+        seq?: string | undefined;
+        protocolVersion: 2;
+        subscriptionId: string;
+        mode: FrameMode;
+        entity: string;
+        op: "upsert" | "patch" | "remove" | "delete";
+        key: string;
+        data: unknown;
+    };
+    remove(target: FrameTarget, key: string, options?: LiveFrameOptions): {
+        append?: string[] | undefined;
+        offset?: number | undefined;
+        seq?: string | undefined;
+        protocolVersion: 2;
+        subscriptionId: string;
+        mode: FrameMode;
+        entity: string;
+        op: "upsert" | "patch" | "remove" | "delete";
+        key: string;
+        data: unknown;
+    };
+    delete(target: FrameTarget, key: string, options?: LiveFrameOptions): {
+        append?: string[] | undefined;
+        offset?: number | undefined;
+        seq?: string | undefined;
+        protocolVersion: 2;
+        subscriptionId: string;
+        mode: FrameMode;
+        entity: string;
+        op: "upsert" | "patch" | "remove" | "delete";
+        key: string;
+        data: unknown;
+    };
+    error(target: FrameTarget | null, code: string, options?: {
+        readonly message?: string;
+        readonly fatal?: boolean;
+        readonly retryable?: boolean;
+    }): {
+        type: "error";
+        protocolVersion: 2;
+        subscriptionId: string | null;
+        code: string;
+        message: string;
+        fatal: boolean;
+        retryable: boolean;
+    };
+};
+interface FrameHarnessOptions {
+    readonly maxEntriesPerView?: number | null;
+    readonly schemas?: Record<string, Schema<unknown>>;
+    readonly patchSchemas?: Record<string, Schema<unknown>>;
+    readonly onValidationError?: (diagnostic: FrameValidationDiagnostic) => void;
+}
+interface FrameHarness {
+    readonly storage: MemoryAdapter;
+    readonly queries: QueryStore;
+    readonly processor: FrameProcessor;
+    /** Register a local subscription, as a view lease would, and return it. */
+    subscribe(subscriptionId: string, query: SubscriptionQuery, options?: {
+        readonly snapshot?: boolean;
+    }): Subscription;
+    /** Process one server frame exactly as it would arrive on the wire. */
+    process(frame: unknown): void;
+    /** The query's current snapshot, as view verbs read it. */
+    snapshot<T = unknown>(subscriptionId: string): QuerySnapshot<T> | undefined;
+}
+/**
+ * The client store engine without a socket: feed it protocol v2 frames and
+ * read query snapshots. Every frame is serialized and parsed as it would be
+ * on the wire, so malformed fixtures fail the same way live frames do.
+ */
+declare function createFrameHarness(options?: FrameHarnessOptions): FrameHarness;
+
+type Listener = ((event: never) => void) | null;
+/**
+ * An in-memory WebSocket the SDK connects to through `auth.websocketFactory`.
+ * The client side is the standard `WebSocket` surface the SDK uses; the
+ * server side is `deliver`, `serverClose` and `fail`.
+ */
+declare class FakeWebSocket {
+    readonly url: string;
+    readonly init?: WebSocketFactoryInit | undefined;
+    static readonly CONNECTING = 0;
+    static readonly OPEN = 1;
+    static readonly CLOSING = 2;
+    static readonly CLOSED = 3;
+    readonly CONNECTING = 0;
+    readonly OPEN = 1;
+    readonly CLOSING = 2;
+    readonly CLOSED = 3;
+    readyState: number;
+    binaryType: 'blob' | 'arraybuffer';
+    onopen: Listener;
+    onmessage: ((event: {
+        data: unknown;
+    }) => void | Promise<void>) | null;
+    onerror: Listener;
+    onclose: ((event: {
+        code: number;
+        reason: string;
+        wasClean: boolean;
+    }) => void) | null;
+    /** Raw messages the client sent, in order. */
+    readonly sent: string[];
+    constructor(url: string, init?: WebSocketFactoryInit | undefined, autoOpen?: boolean);
+    /** Client side: queue an outgoing message. */
+    send(data: string): void;
+    /** Client side: close the socket. */
+    close(code?: number, reason?: string): void;
+    /** Server side: accept the connection (automatic unless disabled). */
+    open(): void;
+    /** Server side: deliver one message (objects are sent as JSON text). */
+    deliver(message: unknown): void;
+    /** Server side: close the connection with a code and reason. */
+    serverClose(code?: number, reason?: string): void;
+    /** Server side: fail the socket as a network error would. */
+    fail(): void;
+    /** Parsed `subscribe` messages this socket received. */
+    subscriptions(): Subscription[];
+}
+interface WebSocketHarnessOptions {
+    /** Open sockets automatically on the next microtask (default `true`). */
+    readonly autoOpen?: boolean;
+    /**
+     * Install {@link FakeWebSocket} as `globalThis.WebSocket` when the runtime has
+     * none (Node 20 and older), because the SDK reads the standard readyState
+     * constants from it. Default `true`; `restore()` removes it again.
+     */
+    readonly installGlobal?: boolean;
+}
+interface WebSocketHarness {
+    /** Pass as `auth.websocketFactory` (core) or `<AreteProvider auth={…}>`. */
+    readonly websocketFactory: (url: string, init?: WebSocketFactoryInit) => WebSocket;
+    /** Every socket the client opened, oldest first. */
+    readonly sockets: readonly FakeWebSocket[];
+    /** The most recent socket; throws if the client never connected. */
+    latest(): FakeWebSocket;
+    /** Subscriptions sent on the latest socket, oldest first. */
+    subscriptions(): Subscription[];
+    /**
+     * The latest subscription for a view (or matching a predicate); throws when
+     * the client has not subscribed yet.
+     */
+    subscription(match?: string | ((subscription: Subscription) => boolean)): Subscription;
+    /**
+     * Resolve with the latest subscription for a view (or matching a
+     * predicate) once the client has sent it; rejects after `timeoutMs`
+     * (default 1000). Subscribing is asynchronous, so tests usually await this.
+     */
+    waitForSubscription(match?: string | ((subscription: Subscription) => boolean), timeoutMs?: number): Promise<Subscription>;
+    /** Deliver a server frame on the latest socket. */
+    send(frame: unknown): void;
+    /** Acknowledge a subscription and answer it with an authoritative snapshot. */
+    serve(target: FrameTarget, rows: readonly {
+        readonly key: string;
+        readonly data: unknown;
+    }[], options?: Parameters<typeof frames.subscribed>[1]): void;
+    /** Remove the global installed by `installGlobal`, if any. */
+    restore(): void;
+}
+/**
+ * A scripted WebSocket server for tests. The SDK connects to it through
+ * `auth.websocketFactory`, so views, snapshots, live frames, reconnects and
+ * errors run through the real client without a network.
+ */
+declare function createWebSocketHarness(options?: WebSocketHarnessOptions): WebSocketHarness;
+
+interface FetchStubRequest {
+    readonly url: string;
+    readonly method: string;
+    readonly headers: Headers;
+    /** Request body as text, when one was sent. */
+    readonly body: string | undefined;
+}
+/** A route's answer: a `Response`, or a value serialized as JSON with status 200. */
+type FetchStubReply = Response | unknown;
+interface FetchStubRoute {
+    /** Substring of the URL, a pattern, or a predicate. */
+    readonly match: string | RegExp | ((request: FetchStubRequest) => boolean);
+    /** Only match this HTTP method (case-insensitive). */
+    readonly method?: string;
+    /** Static reply, or a function computing one per request. */
+    readonly reply: FetchStubReply | ((request: FetchStubRequest) => FetchStubReply | Promise<FetchStubReply>);
+    /** Status for non-`Response` replies (default 200). */
+    readonly status?: number;
+}
+interface FetchStubOptions {
+    /** Answer for requests no route matches (default: a 404 JSON error). */
+    readonly fallback?: (request: FetchStubRequest) => FetchStubReply | Promise<FetchStubReply>;
+}
+interface FetchStub {
+    (input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    /** Every request, in order. */
+    readonly calls: FetchStubRequest[];
+    /** Forget every recorded request. */
+    reset(): void;
+}
+/**
+ * JSON with the SDK's wire rule for integers: `bigint` values are written as
+ * decimal strings, as the server sends u64 fields.
+ */
+declare function jsonResponse(body: unknown, init?: ResponseInit): Response;
+/**
+ * A routed, recording `fetch` for tests: pass it as `ConnectOptions.fetch`,
+ * `createSession(…, { fetch })` or `<AreteProvider fetch={…}>`. Routes are
+ * tried in order; the first match answers.
+ *
+ * ```ts
+ * const fetch = createFetchStub([
+ *   { match: '/accounts/Miner/', reply: { authority: 'wallet', rewards_ore: '12' } },
+ *   { match: '/chain/exists/', reply: { exists: true } },
+ * ]);
+ * ```
+ */
+declare function createFetchStub(routes?: readonly FetchStubRoute[], options?: FetchStubOptions): FetchStub;
+
+export { FIXTURE_SIGNATURE, FIXTURE_SLOT, FIXTURE_WALLET_ADDRESS, FakeWebSocket, createFakeTransactionTransport, createFetchStub, createFrameHarness, createTransactionOutcomeFixtures, createWalletFixture, createWebSocketHarness, firstSignatureOfWireTransaction, frames, jsonResponse, transactionFailureError, transactionOutcomeFixture };
+export type { FakeTransactionCall, FakeTransactionTransport, FakeTransactionTransportOptions, FetchStub, FetchStubOptions, FetchStubReply, FetchStubRequest, FetchStubRoute, FrameHarness, FrameHarnessOptions, FrameTarget, TransactionOutcomeFixtureName, WalletFixture, WalletFixtureCall, WalletFixtureOptions, WalletFixtureResponse, WebSocketHarness, WebSocketHarnessOptions };