@thesight/sdk 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,14 +1,199 @@
-import { Connection, type ConnectionConfig, type Transaction, type VersionedTransaction, type SendOptions, type Commitment } from '@solana/web3.js';
-import { type Tracer } from '@opentelemetry/api';
-import type { AnchorIdl, DecodedError, CpiTree } from '@thesight/core';
-export interface SightConfig {
-    /** OTel tracer. Get via trace.getTracer('your-service') */
+import { TransactionSignature, Connection, Finality, ConnectionConfig, Commitment, SendOptions } from '@solana/web3.js';
+import { Tracer } from '@opentelemetry/api';
+import { IdlResolver, AnchorIdl } from '@thesight/core';
+export { AnchorIdl, CpiTree, CuAttribution, DecodedError, FlamegraphItem, IdlResolver } from '@thesight/core';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { SpanExporter, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import { ExportResult } from '@opentelemetry/core';
+
+interface InitSightConfig {
+    /** Project API key (`sk_live_...`) from the Sight dashboard. */
+    apiKey: string;
+    /**
+     * Human-readable service name that shows up on every span. Pick something
+     * that identifies this process — `'swap-bot'`, `'market-maker'`,
+     * `'trade-settler'`, etc.
+     */
+    serviceName: string;
+    /** Optional version string for the service. Useful for correlating spans with a deploy. */
+    serviceVersion?: string;
+    /**
+     * Full ingest URL. Defaults to the hosted Sight ingest. Override for
+     * local development (e.g. `http://localhost:3001/ingest`) or self-hosted
+     * deployments.
+     */
+    ingestUrl?: string;
+    /** BatchSpanProcessor flush interval, in ms. Defaults to 5s. */
+    batchDelayMs?: number;
+    /** Max spans per HTTP POST. Clamped to 100 by the exporter. */
+    maxBatchSize?: number;
+    /** Inject a fetch implementation for tests. Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+interface SightTracerHandle {
+    provider: NodeTracerProvider;
+    /** Flush any pending spans and release the batch processor. */
+    shutdown: () => Promise<void>;
+}
+/**
+ * Initialize Sight tracing. Call this **once** near the top of your
+ * process entry point — typically in the same file that boots your
+ * HTTP server or worker.
+ *
+ *     import { initSight, InstrumentedConnection } from '@thesight/sdk';
+ *
+ *     initSight({
+ *       apiKey:      process.env.SIGHT_API_KEY!,
+ *       serviceName: 'swap-bot',
+ *       ingestUrl:   process.env.SIGHT_INGEST_URL, // optional, defaults to prod
+ *     });
+ *
+ *     const connection = new InstrumentedConnection(process.env.RPC_URL!);
+ *     const { signature } = await connection.sendAndConfirmInstrumented(tx);
+ *
+ * Registers a NodeTracerProvider as the global OTel tracer, so any call to
+ * `trace.getTracer(...)` (including the ones inside `InstrumentedConnection`)
+ * routes spans through the Sight exporter. Context propagation uses the
+ * Node async hooks manager so spans nest correctly across await boundaries.
+ *
+ * Returns a handle with a `shutdown()` method. Call it at graceful shutdown
+ * time so pending spans are flushed before the process exits:
+ *
+ *     const sight = initSight({ ... });
+ *     process.on('SIGTERM', async () => {
+ *       await sight.shutdown();
+ *       process.exit(0);
+ *     });
+ */
+declare function initSight(config: InitSightConfig): SightTracerHandle;
+
+interface SightExporterConfig {
+    /** Project API key (`sk_live_...`). Sent as Bearer auth on every POST. */
+    apiKey: string;
+    /**
+     * Full ingest URL including the path (e.g. `https://ingest.thesight.dev/ingest`
+     * or `http://localhost:3001/ingest` for local dev).
+     */
+    ingestUrl: string;
+    /** Inject a fake fetch in tests. Defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Max spans per POST. Ingest enforces an upper bound of 100. */
+    maxBatchSize?: number;
+}
+/**
+ * An OTel `SpanExporter` that translates OTel spans to Sight's custom
+ * ingest payload shape and POSTs them to `/ingest`.
+ *
+ * Each span becomes one object in the `spans` array. Solana-specific
+ * attributes flow through as-is (the set that `InstrumentedConnection`
+ * already populates — `solana.tx.signature`, `solana.tx.cu_used`,
+ * `solana.tx.program`, etc). The exporter intentionally does not attempt
+ * to translate span events or links — the ingest schema doesn't have
+ * slots for those, and we prefer dropping silently over guessing.
+ *
+ * The BatchSpanProcessor upstream handles retries, timeouts, and batching;
+ * this exporter stays a thin wire-format translator.
+ */
+declare class SightSpanExporter implements SpanExporter {
+    private readonly apiKey;
+    private readonly ingestUrl;
+    private readonly fetchImpl;
+    private readonly maxBatchSize;
+    private shuttingDown;
+    constructor(config: SightExporterConfig);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): Promise<void>;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+    private sendChunk;
+    private convertSpan;
+}
+
+interface TrackTransactionOptions {
+    /** The signature returned from a prior `sendRawTransaction` / `sendTransaction` call. */
+    signature: TransactionSignature;
+    /**
+     * Any `@solana/web3.js` Connection — plain or instrumented. Used to fetch
+     * the on-chain transaction via `getTransaction` for enrichment. Does
+     * **not** need to be an `InstrumentedConnection`; this helper intentionally
+     * never touches the transaction-send path.
+     */
+    connection: Connection;
+    /**
+     * Service name used for the span. Falls back to the service name
+     * configured by `initSight`. Useful when you want a different service
+     * name for a specific subsystem's spans.
+     */
+    serviceName?: string;
+    /** OTel tracer override. Defaults to `trace.getTracer('@thesight/sdk')`. */
+    tracer?: Tracer;
+    /** Optional IDL resolver for program/error decoding. A fresh one is built if omitted. */
+    idlResolver?: IdlResolver;
+    /**
+     * Pre-registered IDLs to hand to a freshly-built resolver. Ignored when
+     * `idlResolver` is provided.
+     */
+    idls?: Record<string, AnchorIdl>;
+    /** Finality commitment used for the enrichment fetch. Default 'confirmed'. */
+    commitment?: Finality;
+    /** Max wall-time before the span is ended with status=timeout. Default 30000ms. */
+    timeoutMs?: number;
+    /** Base poll interval for retrying getTransaction. Default 500ms. */
+    pollIntervalMs?: number;
+}
+/**
+ * **Non-wrapping observation helper.** Given a transaction signature that
+ * was already sent through any `Connection`, fetch the on-chain record,
+ * parse the logs, and emit a single OpenTelemetry span describing the
+ * transaction.
+ *
+ * Unlike `InstrumentedConnection`, this helper **never touches the send
+ * path** — it only observes after the fact via `getTransaction(signature)`.
+ * Use this when:
+ *
+ * - You want observability for wallet-adapter flows where the send path
+ *   goes through the wallet and you can't easily override the Connection
+ * - You're security-conscious and don't want any SDK code on the critical
+ *   transaction path
+ * - You want to instrument a handful of high-value transactions rather
+ *   than every call a Connection makes
+ *
+ * Usage:
+ *
+ *     import { trackSolanaTransaction } from '@thesight/sdk';
+ *     import { Connection } from '@solana/web3.js';
+ *
+ *     const connection = new Connection(rpcUrl);
+ *     const signature  = await wallet.sendTransaction(tx, connection);
+ *
+ *     // Fire-and-forget. Span flushes on its own.
+ *     void trackSolanaTransaction({
+ *       signature,
+ *       connection,
+ *       serviceName: 'checkout',
+ *       idls: { [programId]: idl },
+ *     });
+ *
+ * Returns a `Promise<void>` — typically not awaited, but callers who want
+ * to wait for the span to export (e.g. short-lived scripts) can await it.
+ */
+declare function trackSolanaTransaction(opts: TrackTransactionOptions): Promise<void>;
+
+interface SightConfig {
+    /** OTel tracer. Defaults to `trace.getTracer('@thesight/sdk')`. */
     tracer?: Tracer;
     /** Override RPC endpoint for IDL fetching (defaults to same as connection) */
     idlRpcEndpoint?: string;
-    /** Commitment to use when fetching confirmed tx details */
+    /**
+     * Commitment used when fetching confirmed tx details for enrichment.
+     * Defaults to 'confirmed'.
+     */
     commitment?: Commitment;
-    /** Skip IDL resolution (faster, no program names or error decoding) */
+    /**
+     * Skip IDL resolution entirely. Spans will still emit with signature and
+     * timing attributes, but program names, instruction names, CPI trees, and
+     * decoded errors will all be omitted. Useful when you want minimal
+     * overhead and don't care about the richer observability.
+     */
     skipIdlResolution?: boolean;
     /**
      * Pre-register IDLs at construction time. Keys are program IDs, values are
@@ -19,18 +204,35 @@ export interface SightConfig {
     /**
      * Opt into reading Anchor IDL accounts from the on-chain PDA as a fallback
      * when a program is not explicitly registered. Defaults to **false** —
-     * Sight's model is that IDLs are explicitly provided by the application
-     * (via this option or `registerIdl`), not silently guessed from chain.
+     * Sight's model is that IDLs are explicitly provided by the application,
+     * not silently guessed from chain.
      */
     allowOnChainIdlFetch?: boolean;
+    /**
+     * Max wall-time the background enrichment task will wait for a
+     * transaction to show up in `getTransaction`. After this expires the
+     * span is ended with `solana.tx.status = 'timeout'`. Default 30000 (30s).
+     */
+    enrichmentTimeoutMs?: number;
+    /**
+     * How often the enrichment task polls `getTransaction`. Each retry backs
+     * off by 1.5x up to a cap. Default 500ms base.
+     */
+    enrichmentPollIntervalMs?: number;
+    /**
+     * Disable automatic span creation in the overridden `sendRawTransaction`.
+     * When true, InstrumentedConnection behaves like a plain Connection. You
+     * probably don't want this — it's here as an escape hatch for tests and
+     * rare cases where you need the class hierarchy but not the tracing.
+     */
+    disableAutoSpan?: boolean;
 }
-export interface SightSpanAttributes {
+interface SightSpanAttributes {
     'solana.tx.signature': string;
-    'solana.tx.status': 'confirmed' | 'failed' | 'timeout';
+    'solana.tx.status': 'submitted' | 'confirmed' | 'failed' | 'timeout';
     'solana.tx.slot'?: number;
     'solana.tx.fee_lamports'?: number;
     'solana.tx.submit_ms': number;
-    'solana.tx.confirmation_ms'?: number;
     'solana.tx.enrichment_ms'?: number;
     'solana.tx.cu_used'?: number;
     'solana.tx.cu_budget'?: number;
@@ -43,19 +245,43 @@ export interface SightSpanAttributes {
     'solana.tx.error_msg'?: string;
 }
 /**
- * Drop-in replacement for @solana/web3.js Connection that instruments
- * every transaction with OpenTelemetry spans.
+ * Drop-in replacement for `@solana/web3.js`'s `Connection` that emits an
+ * OpenTelemetry span for **every** call to `sendRawTransaction` —
+ * regardless of whether the caller is your own code, an Anchor provider's
+ * `sendAndConfirm`, `@solana/web3.js`'s top-level `sendAndConfirmTransaction`,
+ * a wallet adapter, or anything else.
+ *
+ * Internally it overrides the parent class's `sendRawTransaction`, so the
+ * span covers the same surface web3.js already mediates. No mutation of
+ * the transaction bytes — we call `super.sendRawTransaction(rawTx, opts)`
+ * verbatim and observe the signature it returns.
+ *
+ * After the signature is returned (synchronously from the caller's point
+ * of view), a background task polls `getTransaction` until the on-chain
+ * record is available, parses the program logs via `@thesight/core`, and
+ * enriches the span with CU attribution, per-CPI events, program + instruction
+ * names, and decoded error details. The background task never blocks the
+ * caller — if it fails or times out, the span ends with status=timeout and
+ * whatever partial data was collected.
  *
  * Usage:
- *   const connection = new InstrumentedConnection(rpcUrl, {
- *     tracer: trace.getTracer('my-service'),
- *   });
  *
- * The Solana transaction becomes a child span of whatever OTel context
- * is active when sendAndConfirmTransaction is called — so it automatically
- * nests inside your HTTP handler or background job span.
+ *     import { initSight, InstrumentedConnection } from '@thesight/sdk';
+ *
+ *     initSight({ apiKey, serviceName: 'swap-bot' });
+ *
+ *     // Anywhere you currently construct a Connection, construct this instead:
+ *     const connection = new InstrumentedConnection(rpcUrl, {
+ *       commitment: 'confirmed',
+ *     });
+ *
+ *     // All of the following now emit spans automatically:
+ *     await connection.sendRawTransaction(tx.serialize());
+ *     await sendAndConfirmTransaction(connection, tx, signers); // web3.js
+ *     await program.methods.foo().rpc();                        // Anchor
+ *     await wallet.sendTransaction(tx, connection);             // wallet adapter
  */
-export declare class InstrumentedConnection extends Connection {
+declare class InstrumentedConnection extends Connection {
     private sightConfig;
     private idlResolver;
     private tracer;
@@ -72,21 +298,41 @@ export declare class InstrumentedConnection extends Connection {
     /** Bulk-register multiple IDLs. */
     registerIdls(idls: Record<string, AnchorIdl>): void;
     /**
-     * Sends and confirms a transaction, wrapped in an OTel span.
-     * The span is a child of the current active context.
+     * Overrides the parent `Connection.sendRawTransaction` so every submit —
+     * including those made by Anchor's `provider.sendAndConfirm`, web3.js's
+     * top-level `sendAndConfirmTransaction`, and wallet adapter flows — is
+     * observed by an OTel span automatically.
+     *
+     * The span is a child of whatever OTel context is active when the call
+     * fires, so app-level parent spans (HTTP handlers, job runs, wallet flow
+     * spans from another SDK) nest the Sight span correctly.
+     */
+    sendRawTransaction(rawTransaction: Buffer | Uint8Array | Array<number>, options?: SendOptions): Promise<TransactionSignature>;
+    /**
+     * Poll `getTransaction` until the on-chain record is available, then
+     * enrich the span with CU attribution, program names, decoded errors,
+     * and per-CPI events.
+     *
+     * This runs async and is never awaited by callers of `sendRawTransaction`.
+     * Failures inside this method attach to the span via recordException
+     * rather than throwing.
+     */
+    private enrichSpanInBackground;
+    /**
+     * Poll `getTransaction(signature)` until either the on-chain record is
+     * returned or the deadline passes. Exponential backoff (1.5x) capped at
+     * 2 seconds to balance responsiveness against RPC load.
+     */
+    private pollForTransaction;
+    /** Attach the flat fields (slot, fee, CU, status) from a tx response to a span. */
+    private attachTxDetailsToSpan;
+    /**
+     * Parse program logs into a CPI tree, enrich with registered IDLs, and
+     * emit one `cpi.invoke` event per invocation onto the span. Root
+     * program/instruction names are copied onto span attributes so dashboards
+     * can filter by them without walking events.
      */
-    sendAndConfirmInstrumented(transaction: Transaction | VersionedTransaction, options?: SendOptions & {
-        commitment?: Commitment;
-    }): Promise<{
-        signature: string;
-        cpiTree?: CpiTree;
-        error?: DecodedError;
-    }>;
+    private attachParsedLogsToSpan;
 }
-export { IdlResolver } from '@thesight/core';
-export type { CpiTree, CuAttribution, FlamegraphItem, DecodedError, AnchorIdl } from '@thesight/core';
-export { initSight } from './init.js';
-export type { InitSightConfig, SightTracerHandle } from './init.js';
-export { SightSpanExporter } from './exporter.js';
-export type { SightExporterConfig } from './exporter.js';
-//# sourceMappingURL=index.d.ts.map
+
+export { type InitSightConfig, InstrumentedConnection, type SightConfig, type SightExporterConfig, type SightSpanAttributes, SightSpanExporter, type SightTracerHandle, type TrackTransactionOptions, initSight, trackSolanaTransaction };