@thesight/sdk 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -1,7 +1,114 @@
-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 {
+import { Connection, ConnectionConfig, Commitment, Transaction, VersionedTransaction, SendOptions } from '@solana/web3.js';
+import { Tracer } from '@opentelemetry/api';
+import { AnchorIdl, CpiTree, DecodedError } 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 SightConfig {
     /** OTel tracer. Get via trace.getTracer('your-service') */
     tracer?: Tracer;
     /** Override RPC endpoint for IDL fetching (defaults to same as connection) */
@@ -24,7 +131,7 @@ export interface SightConfig {
      */
     allowOnChainIdlFetch?: boolean;
 }
-export interface SightSpanAttributes {
+interface SightSpanAttributes {
     'solana.tx.signature': string;
     'solana.tx.status': 'confirmed' | 'failed' | 'timeout';
     'solana.tx.slot'?: number;
@@ -55,7 +162,7 @@ export interface SightSpanAttributes {
  * is active when sendAndConfirmTransaction is called — so it automatically
  * nests inside your HTTP handler or background job span.
  */
-export declare class InstrumentedConnection extends Connection {
+declare class InstrumentedConnection extends Connection {
     private sightConfig;
     private idlResolver;
     private tracer;
@@ -83,10 +190,5 @@ export declare class InstrumentedConnection extends Connection {
         error?: DecodedError;
     }>;
 }
-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, initSight };