@thesight/sdk 0.1.1 → 0.3.0

package/dist/index.d.ts

@@ -1,14 +1,21 @@
-import { Connection, ConnectionConfig, Commitment, Transaction, VersionedTransaction, SendOptions } from '@solana/web3.js';
+import { TransactionSignature, Connection, Finality, ConnectionConfig, Commitment, SendOptions } from '@solana/web3.js';
 import { Tracer } from '@opentelemetry/api';
-import { AnchorIdl, CpiTree, DecodedError } from '@thesight/core';
+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;
+    /**
+     * Sight DSN — one string encoding both the ingest endpoint and the API key.
+     *
+     * Format: `https://<apiKey>@<host>/ingest`
+     *
+     * Get yours from the Sight dashboard when you create a project. For local
+     * dev against a Docker compose stack: `http://sk_live_xxx@localhost:3001/ingest`
+     */
+    dsn: string;
     /**
      * Human-readable service name that shows up on every span. Pick something
      * that identifies this process — `'swap-bot'`, `'market-maker'`,
@@ -17,12 +24,6 @@ interface InitSightConfig {
     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. */
@@ -37,44 +38,30 @@ interface SightTracerHandle {
 }
 /**
  * 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.
+ * process entry point.
  *
  *     import { initSight, InstrumentedConnection } from '@thesight/sdk';
  *
  *     initSight({
- *       apiKey:      process.env.SIGHT_API_KEY!,
+ *       dsn:         process.env.SIGHT_DSN!,
  *       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:
+ *     // Every sendRawTransaction call now emits a span automatically.
  *
- *     const sight = initSight({ ... });
- *     process.on('SIGTERM', async () => {
- *       await sight.shutdown();
- *       process.exit(0);
- *     });
+ * Registers a NodeTracerProvider as the global OTel tracer. Context
+ * propagation uses Node async hooks so spans nest correctly across
+ * await boundaries.
  */
 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).
+     * Sight DSN — one string encoding both the ingest endpoint and the API key.
+     * Format: https://<apiKey>@<host>/ingest
      */
-    ingestUrl: string;
+    dsn: 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. */
@@ -108,14 +95,128 @@ declare class SightSpanExporter implements SpanExporter {
     private convertSpan;
 }
 
+/**
+ * Parse a Sight DSN into its constituent parts.
+ *
+ * DSN format:
+ *   https://<apiKey>@<host>[:<port>]/<path>
+ *
+ * Examples:
+ *   https://sk_live_abc123@ingest.thesight.dev/ingest     (production)
+ *   http://sk_live_abc123@localhost:3001/ingest            (local dev)
+ *
+ * The API key sits in the URL's username position. The SDK extracts it
+ * and sends it as a Bearer token to the ingest URL (with the key removed
+ * from the URL). This mirrors the Sentry DSN model — one string encodes
+ * both "where to send" and "who you are", so there's no separate
+ * apiKey + ingestUrl to misconfig independently.
+ */
+interface ParsedDsn {
+    /** The API key extracted from the DSN's username position. */
+    apiKey: string;
+    /** The ingest endpoint URL with the API key stripped out. */
+    ingestUrl: string;
+}
+/**
+ * Parse a DSN string into `{ apiKey, ingestUrl }`.
+ *
+ * Throws with a clear message on:
+ * - Malformed URL
+ * - Missing API key (no username in the URL)
+ */
+declare function parseDsn(dsn: string): ParsedDsn;
+/**
+ * Build a DSN from its parts. Used by the dashboard when generating the
+ * DSN for a newly-created project.
+ */
+declare function buildDsn(apiKey: string, ingestHost: string): string;
+
+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. Get via trace.getTracer('your-service') */
+    /** 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
@@ -126,18 +227,35 @@ 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;
 }
 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;
@@ -150,17 +268,41 @@ 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({ dsn: process.env.SIGHT_DSN!, 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
  */
 declare class InstrumentedConnection extends Connection {
     private sightConfig;
@@ -179,16 +321,41 @@ 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 { type InitSightConfig, InstrumentedConnection, type SightConfig, type SightExporterConfig, type SightSpanAttributes, SightSpanExporter, type SightTracerHandle, initSight };
+export { type InitSightConfig, InstrumentedConnection, type ParsedDsn, type SightConfig, type SightExporterConfig, type SightSpanAttributes, SightSpanExporter, type SightTracerHandle, type TrackTransactionOptions, buildDsn, initSight, parseDsn, trackSolanaTransaction };