madeonsol-x402 4.2.0 → 4.4.0

package/dist/terminal-watch.d.ts

@@ -0,0 +1,175 @@
+/**
+ * Framework-agnostic terminal snapshot/stream bridge (#534).
+ *
+ * A shared SDK socket supplies push frames. Snapshot reads happen once after
+ * the named subscription is ACKED, then only on coalesced, named invalidations.
+ * This deliberately NEVER patches REST module data from unrelated clocks.
+ *
+ * Instantiate once per selected token, reusing one existing stream connection.
+ * The controller never closes that shared stream on dispose().
+ */
+import { type TerminalWatchPlan, type TerminalModule, type TerminalChain, type TerminalTier } from "./terminal-policy.js";
+export interface TerminalStreamFrame {
+    channel?: string;
+    event?: string;
+    sub_id?: string;
+    id?: string;
+    data?: unknown;
+    ts?: number;
+    replayed?: boolean;
+    snapshot?: boolean;
+}
+/** Adaptable to the existing MadeOnSolStream / RobinhoodChainStream overloads. */
+export interface TerminalStreamPort {
+    subscribe(opts: {
+        subId: string;
+        channels: string[];
+        filters: Record<string, unknown>;
+    }): unknown;
+    unsubscribe(subId: string): unknown;
+    on(event: string, listener: (...args: unknown[]) => unknown): unknown;
+    off(event: string, listener: (...args: unknown[]) => unknown): unknown;
+}
+export interface TerminalModuleResponse {
+    status: "ready" | "partial_history" | "unverified" | "unavailable" | "timeout";
+    reason: string | null;
+    as_of: string | null;
+    data?: Record<string, unknown>;
+}
+export interface TerminalSnapshotResponse {
+    chain: TerminalChain;
+    address: string;
+    generated_at: string;
+    modules: Partial<Record<TerminalModule, TerminalModuleResponse>>;
+}
+export type TerminalPhase = "idle" | "awaiting_subscribe" | "bootstrapping" | "live" | "degraded" | "stopped";
+/**
+ * Stream delivery truth only: "replay_complete" establishes what the SDK
+ * replayed for THIS subscription, not full market/trade/archive coverage.
+ * "initial" means no reconnect has needed proof during this widget's life.
+ */
+export type TerminalContinuityStatus = "initial" | "snapshot_only" | "replay_pending" | "replay_complete" | "replay_unverified" | "historical_gap" | "externally_reconciled";
+export interface TerminalContinuity {
+    status: TerminalContinuityStatus;
+    /** Client monotonic/now() time at the latest socket close, if any. */
+    last_disconnected_at_ms: number | null;
+    /** Client receipt time for a completed replay of THIS named subscription. */
+    last_replay_at_ms: number | null;
+    /** An SDK replay ending for another widget is not proof for this one. */
+    this_subscription_replay_complete: boolean;
+}
+export interface TerminalView {
+    phase: TerminalPhase;
+    address: string;
+    chain: TerminalChain;
+    /** Untouched REST modules; use the latest live frame as a separate overlay. */
+    snapshot: TerminalSnapshotResponse | null;
+    live: Partial<Record<TerminalModule, TerminalStreamFrame>>;
+    /** A known event or gap may have made a cached module stale. */
+    stale: TerminalModule[];
+    /** A module without an adequate existing WS source is snapshot-only. */
+    no_push: TerminalModule[];
+    /** A stream interruption or refusal must be visible to the terminal. */
+    incomplete: boolean;
+    last_error: string | null;
+    /** Reconnect/replay diagnostics; never a historical coverage certification. */
+    continuity: TerminalContinuity;
+}
+export interface TerminalViewOptions {
+    chain: TerminalChain;
+    address: string;
+    tier: TerminalTier;
+    include: readonly TerminalModule[];
+    /** Full RHC DEX firehose (all tokens) is high-bandwidth; opt in explicitly. */
+    includeRhcFirehose?: boolean;
+    /** KOL channels are unscoped broadcasts; opt in only with bandwidth budget. */
+    includeKolBroadcast?: boolean;
+    subId: string;
+    stream: TerminalStreamPort;
+    /** The existing keyed REST .tokenIntelligence(address, {include}) call. */
+    read: (include: readonly TerminalModule[]) => Promise<TerminalSnapshotResponse>;
+    onChange?: (view: TerminalView) => void;
+    onLive?: (frame: TerminalStreamFrame, module: TerminalModule) => void;
+    /** Min seconds per module before another HTTP refresh (default 15s). */
+    minModuleRefreshMs?: number;
+    /** Debounce and coalesce changed modules (default 750ms). */
+    debounceMs?: number;
+    now?: () => number;
+}
+/** Bounded by nine modules and one frame per live overlay; never a trade queue. */
+export declare class TerminalTokenView {
+    readonly plan: TerminalWatchPlan;
+    private readonly opts;
+    private readonly listeners;
+    private readonly dirty;
+    private readonly stale;
+    private readonly seen;
+    private readonly live;
+    private readonly gen;
+    private readonly lastRead;
+    private readonly now;
+    private timer;
+    private timerAt;
+    private busy;
+    /** If the socket ACK arrives while a prior REST read is still unresolved,
+     * the latest post-ACK snapshot must run after that read settles. */
+    private pendingBootstrap;
+    private subscribed;
+    private epoch;
+    private phase;
+    private incomplete;
+    /** An observed historical gap survives a new REST snapshot and reconnect. */
+    private gapUnresolved;
+    /** A named subscription ACK never proves that its resume finished. */
+    private replayPending;
+    private replayUnverified;
+    private replayComplete;
+    private continuityStatus;
+    private lastDisconnectedAt;
+    private lastReplayAt;
+    private lastError;
+    private snapshot;
+    /**
+     * Modules not yet successfully re-read since the latest ACK/disconnect. A
+     * replay_end or a targeted refresh of ONE module must not report "live"
+     * while another module still shows its pre-disconnect REST value.
+     */
+    private readonly baselineMissing;
+    constructor(options: TerminalViewOptions);
+    getView(): TerminalView;
+    /** Registers handlers BEFORE opening the stream; first REST read waits for ACK. */
+    start(): void;
+    /** Consumer-initiated refresh, useful after a known unrecoverable gap. */
+    refresh(): void;
+    /**
+     * The caller must independently reconcile an unrecoverable event interval
+     * BEFORE clearing the visible gap. A fresh snapshot is not that evidence.
+     */
+    acknowledgeHistoricalRecovery(): void;
+    dispose(): void;
+    private isStopped;
+    private requireBaseline;
+    /** Phase after a continuity change; never "live" on a partial baseline. */
+    private settledPhase;
+    private clearLive;
+    private emit;
+    private listen;
+    private onSubscribed;
+    /**
+     * A successful SDK aggregate replay is relevant only when its per-subscribe
+     * replay_end for OUR named subscription says complete=true. REST freshness
+     * alone cannot certify recovered KOL/trade/risk events.
+     */
+    private onReplay;
+    private onWarning;
+    private onGap;
+    private onFrame;
+    private markStale;
+    private clearTimer;
+    private schedule;
+    private flush;
+    private fetchModules;
+}
+/** A named subscription prevents overwriting an integrator's other filters. */
+export declare function createTerminalTokenView(options: TerminalViewOptions): TerminalTokenView;
+//# sourceMappingURL=terminal-watch.d.ts.map

package/dist/terminal-watch.d.ts.map

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