@glasstrace/sdk 0.0.1 → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,389 @@
+import { SdkDiagnosticCode, GlasstraceEnvVars, GlasstraceOptions, SessionId, AnonApiKey, CaptureConfig, SdkInitResponse, ImportGraphPayload, SdkHealthReport, SourceMapUploadResponse } from '@glasstrace/protocol';
+import { Context } from '@opentelemetry/api';
+import { SpanProcessor, Span, ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
+import { ExportResult } from '@opentelemetry/core';
+
+/**
+ * Internal SDK error class with a typed diagnostic code.
+ * Caught at the boundary and converted to a log message + diagnostic entry.
+ * Never thrown to the developer.
+ */
+declare class SdkError extends Error {
+    readonly code: SdkDiagnosticCode;
+    constructor(code: SdkDiagnosticCode, message: string, cause?: Error);
+}
+
+/**
+ * Resolved configuration after merging explicit options with environment variables.
+ */
+interface ResolvedConfig {
+    apiKey: string | undefined;
+    endpoint: string;
+    forceEnable: boolean;
+    verbose: boolean;
+    environment: string | undefined;
+    coverageMapEnabled: boolean;
+    nodeEnv: string | undefined;
+    vercelEnv: string | undefined;
+}
+/**
+ * Reads all recognized Glasstrace environment variables from process.env.
+ * Returns undefined for any variable not set. Never throws.
+ */
+declare function readEnvVars(): GlasstraceEnvVars;
+/**
+ * Merges explicit GlasstraceOptions with environment variables.
+ * Explicit options take precedence over environment variables.
+ */
+declare function resolveConfig(options?: GlasstraceOptions): ResolvedConfig;
+/**
+ * Returns true when the SDK should be inactive (production detected without force-enable).
+ * Logic order:
+ *   1. forceEnable === true → return false (override)
+ *   2. NODE_ENV === 'production' → return true
+ *   3. VERCEL_ENV === 'production' → return true
+ *   4. Otherwise → return false
+ */
+declare function isProductionDisabled(config: ResolvedConfig): boolean;
+/**
+ * Returns true when no API key is configured (anonymous mode).
+ * Treats undefined, empty string, whitespace-only, and gt_anon_* keys as anonymous.
+ */
+declare function isAnonymousMode(config: ResolvedConfig): boolean;
+
+/**
+ * Derives a deterministic session ID from the given inputs using SHA-256.
+ * The hash is truncated to 16 hex characters and parsed through SessionIdSchema.
+ *
+ * @param apiKey - The project's API key (or anonymous placeholder).
+ * @param origin - The origin string identifying the deployment environment.
+ * @param date - UTC date as YYYY-MM-DD.
+ * @param windowIndex - Zero-based index of the 4-hour activity window within the day.
+ * @returns A 16-character hex SessionId.
+ */
+declare function deriveSessionId(apiKey: string, origin: string, date: string, windowIndex: number): SessionId;
+/**
+ * Returns the origin string for the current process.
+ * If GLASSTRACE_ENV is set, returns that value.
+ * Otherwise returns `localhost:{PORT}` (PORT defaults to 3000).
+ *
+ * @returns The origin string used as a session derivation input.
+ */
+declare function getOrigin(): string;
+/**
+ * Returns the current UTC date as a YYYY-MM-DD string.
+ *
+ * @returns The UTC date formatted as "YYYY-MM-DD".
+ */
+declare function getDateString(): string;
+/**
+ * Tracks the current session state with 4-hour window tracking.
+ * Instantiated once by the orchestrator.
+ */
+declare class SessionManager {
+    private windowIndex;
+    private lastActivityTimestamp;
+    private lastDate;
+    private lastApiKey;
+    private currentSessionId;
+    /**
+     * Returns the current session ID, deriving a new one if:
+     * - More than 4 hours have elapsed since last activity
+     * - The UTC date has changed (resets window index to 0)
+     * - The API key has changed (e.g., deferred anonymous key swap)
+     * - This is the first call
+     *
+     * @param apiKey - The project's API key used in session derivation.
+     * @returns The current or newly derived SessionId.
+     */
+    getSessionId(apiKey: string): SessionId;
+}
+
+/**
+ * The set of recognized fetch target categories.
+ */
+type FetchTarget = "supabase" | "stripe" | "internal" | "unknown";
+/**
+ * Classifies an outbound fetch target URL into a known category.
+ * Classification is case-insensitive and based on the URL hostname.
+ * Uses dot-boundary matching to avoid false positives (e.g. evilstripe.com).
+ *
+ * Returns one of: 'supabase', 'stripe', 'internal', or 'unknown'.
+ */
+declare function classifyFetchTarget(url: string): FetchTarget;
+
+/**
+ * Reads an existing anonymous key from the filesystem.
+ * Returns the key if valid, or null if:
+ * - The file does not exist
+ * - The file content is invalid
+ * - An I/O error occurs
+ */
+declare function readAnonKey(projectRoot?: string): Promise<AnonApiKey | null>;
+/**
+ * Gets an existing anonymous key from the filesystem, or creates a new one.
+ *
+ * - If file exists and contains a valid key, returns it
+ * - If file does not exist or content is invalid, generates a new key via createAnonApiKey()
+ * - Writes the new key to `.glasstrace/anon_key`, creating the directory if needed
+ * - On file write failure: logs a warning, caches an ephemeral in-memory key so
+ *   repeated calls in the same process return the same key
+ */
+declare function getOrCreateAnonKey(projectRoot?: string): Promise<AnonApiKey>;
+
+/**
+ * Reads and validates a cached config file from `.glasstrace/config`.
+ * Returns the parsed `SdkInitResponse` or `null` on any failure.
+ */
+declare function loadCachedConfig(projectRoot?: string): SdkInitResponse | null;
+/**
+ * Persists the init response to `.glasstrace/config`.
+ * On failure, logs a warning and continues.
+ */
+declare function saveCachedConfig(response: SdkInitResponse, projectRoot?: string): Promise<void>;
+/**
+ * Sends a POST request to `/v1/sdk/init`.
+ * Validates the response against `SdkInitResponseSchema`.
+ */
+declare function sendInitRequest(config: ResolvedConfig, anonKey: AnonApiKey | null, sdkVersion: string, importGraph?: ImportGraphPayload, healthReport?: SdkHealthReport, diagnostics?: Array<{
+    code: SdkDiagnosticCode;
+    message: string;
+    timestamp: number;
+}>, signal?: AbortSignal): Promise<SdkInitResponse>;
+/**
+ * Orchestrates the full init flow: send request, update config, cache result.
+ * This function MUST NOT throw.
+ */
+declare function performInit(config: ResolvedConfig, anonKey: AnonApiKey | null, sdkVersion: string): Promise<void>;
+/**
+ * Returns the current capture config from the three-tier fallback chain:
+ * 1. In-memory config from latest init response
+ * 2. File cache
+ * 3. DEFAULT_CAPTURE_CONFIG
+ */
+declare function getActiveConfig(): CaptureConfig;
+
+/**
+ * Lightweight SpanProcessor that delegates to a wrapped processor.
+ *
+ * All glasstrace.* attribute enrichment has been moved to {@link GlasstraceExporter}
+ * (see enriching-exporter.ts), which enriches spans at export time. This resolves:
+ * - Cold-start spans are buffered in the exporter, not dropped
+ * - Vercel's CompositeSpanProcessor skips onEnding(); the exporter doesn't need it
+ * - Session ID is computed at export time with the resolved API key
+ *
+ * This class is retained for backward compatibility. New code should use
+ * GlasstraceExporter directly.
+ *
+ * @deprecated Use GlasstraceExporter for span enrichment. This processor is now a pass-through.
+ */
+declare class GlasstraceSpanProcessor implements SpanProcessor {
+    private readonly wrappedProcessor;
+    constructor(wrappedProcessor: SpanProcessor, _sessionManager?: SessionManager, _apiKey?: string | (() => string), _getConfig?: () => CaptureConfig, _environment?: string);
+    onStart(span: Span, parentContext: Context): void;
+    onEnd(readableSpan: ReadableSpan): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}
+
+/**
+ * Options for constructing a {@link GlasstraceExporter}.
+ */
+interface GlasstraceExporterOptions {
+    getApiKey: () => string;
+    sessionManager: SessionManager;
+    getConfig: () => CaptureConfig;
+    environment: string | undefined;
+    endpointUrl: string;
+    createDelegate: ((url: string, headers: Record<string, string>) => SpanExporter) | null;
+}
+/**
+ * A SpanExporter that enriches spans with glasstrace.* attributes at export
+ * time, then delegates to a real OTLP exporter.
+ *
+ * This design resolves three issues:
+ * - Spans emitted before the API key resolves are buffered (not dropped)
+ *   and flushed once the key is available.
+ * - Enrichment happens in the exporter (not onEnding), so it works
+ *   on Vercel where CompositeSpanProcessor does not forward onEnding().
+ * - Session ID is computed at export time using the resolved API key,
+ *   not the "pending" placeholder.
+ */
+declare class GlasstraceExporter implements SpanExporter {
+    private readonly getApiKey;
+    private readonly sessionManager;
+    private readonly getConfig;
+    private readonly environment;
+    private readonly endpointUrl;
+    private readonly createDelegateFn;
+    private delegate;
+    private delegateKey;
+    private pendingBatches;
+    private pendingSpanCount;
+    private overflowLogged;
+    constructor(options: GlasstraceExporterOptions);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    /**
+     * Called when the API key transitions from "pending" to a resolved value.
+     * Creates the delegate exporter and flushes all buffered spans.
+     */
+    notifyKeyResolved(): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+    /**
+     * Enriches a ReadableSpan with all glasstrace.* attributes.
+     * Returns a new ReadableSpan wrapper; the original span is not mutated.
+     *
+     * External function calls (getSessionId, deriveErrorCategory,
+     * deriveOrmProvider, classifyFetchTarget) are individually guarded so a
+     * failure in one does not prevent the remaining attributes from being set.
+     * On total failure, returns the original span unchanged.
+     */
+    private enrichSpan;
+    /**
+     * Lazily creates the delegate OTLP exporter once the API key is resolved.
+     * Recreates the delegate if the key has changed (e.g., after key rotation)
+     * so the Authorization header stays current.
+     */
+    private ensureDelegate;
+    /**
+     * Buffers raw (unenriched) spans while the API key is pending.
+     * Evicts oldest batches if the buffer exceeds MAX_PENDING_SPANS.
+     * Re-checks the key after buffering to close the race window where
+     * the key resolves between the caller's check and this buffer call.
+     */
+    private bufferSpans;
+    /**
+     * Flushes all buffered spans through the delegate exporter.
+     * Enriches spans at flush time (not buffer time) so that session IDs
+     * are computed with the resolved API key instead of the "pending" sentinel.
+     */
+    private flushPending;
+}
+
+/**
+ * Creates a request handler for the `/__glasstrace/config` discovery endpoint.
+ *
+ * The returned handler checks if the request URL path is `/__glasstrace/config`.
+ * If not, returns `null` (pass-through). If it matches, returns a `DiscoveryResponse`
+ * with the anonymous key and current session ID.
+ *
+ * The triple guard (anonymous + dev + active) is enforced by the caller,
+ * not by this module. If the handler is registered, it serves.
+ */
+declare function createDiscoveryHandler(getAnonKey: () => Promise<AnonApiKey | null>, getSessionId: () => SessionId): (request: Request) => Promise<Response | null>;
+
+/**
+ * The primary SDK entry point called by developers in their `instrumentation.ts`.
+ * Orchestrates OTel setup, span processor, init client, anon key, and discovery endpoint.
+ *
+ * This function is synchronous and MUST NOT throw. The developer's server is never blocked.
+ * Background work (key resolution, init call) happens via fire-and-forget promises.
+ *
+ * @param options - Optional SDK configuration. Environment variables are used as fallbacks.
+ *
+ * @example
+ * ```ts
+ * // instrumentation.ts
+ * import { registerGlasstrace } from "@glasstrace/sdk";
+ * registerGlasstrace(); // uses env vars
+ * ```
+ */
+declare function registerGlasstrace(options?: GlasstraceOptions): void;
+/**
+ * Returns the registered discovery handler, or null if not registered.
+ */
+declare function getDiscoveryHandler(): ((request: Request) => Promise<Response | null>) | null;
+
+type NextConfig = Record<string, unknown>;
+/**
+ * Wraps the developer's Next.js config to enable source map generation
+ * and upload .map files to the ingestion API at build time.
+ *
+ * The build NEVER fails because of Glasstrace — all errors are caught
+ * and logged as warnings.
+ *
+ * @param nextConfig - The developer's existing Next.js configuration object.
+ * @returns A new config object with source map generation and upload enabled.
+ */
+declare function withGlasstraceConfig(nextConfig: NextConfig): NextConfig;
+
+interface SourceMapEntry {
+    filePath: string;
+    content: string;
+}
+/**
+ * Recursively finds all .map files in the given build directory.
+ * Returns relative paths and file contents.
+ */
+declare function collectSourceMaps(buildDir: string): Promise<SourceMapEntry[]>;
+/**
+ * Computes a build hash for source map uploads.
+ *
+ * First tries `git rev-parse HEAD` to get the git commit SHA.
+ * On failure, falls back to a deterministic content hash:
+ * sort source map file paths alphabetically, concatenate each as
+ * `{relativePath}\n{fileLength}\n{fileContent}`, then SHA-256 the result.
+ */
+declare function computeBuildHash(maps?: SourceMapEntry[]): Promise<string>;
+/**
+ * Uploads source maps to the ingestion API.
+ *
+ * POSTs to `{endpoint}/v1/source-maps` with the API key, build hash,
+ * and file entries. Validates the response against SourceMapUploadResponseSchema.
+ */
+declare function uploadSourceMaps(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[]): Promise<SourceMapUploadResponse>;
+
+/**
+ * Records an error as a span event on the currently active OTel span.
+ *
+ * Works regardless of the `consoleErrors` configuration — this is an
+ * explicit, opt-in API for manual error reporting. If no span is active
+ * or OTel is not available, the call is silently ignored.
+ *
+ * @param error - The error to capture. Accepts `Error` objects, strings, or any value.
+ *
+ * @example
+ * ```ts
+ * import { captureError } from "@glasstrace/sdk";
+ *
+ * try {
+ *   await riskyOperation();
+ * } catch (err) {
+ *   captureError(err);
+ *   // handle error normally...
+ * }
+ * ```
+ */
+declare function captureError(error: unknown): void;
+
+/**
+ * Discovers test files by scanning the project directory for conventional
+ * test file patterns. Also reads vitest/jest config files for custom include
+ * patterns and merges them with the defaults. Excludes node_modules/ and .next/.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @returns Relative POSIX paths from projectRoot, capped at {@link MAX_TEST_FILES}.
+ */
+declare function discoverTestFiles(projectRoot: string): Promise<string[]>;
+/**
+ * Extracts import paths from file content using regex.
+ * Handles ES module imports, CommonJS requires, and dynamic imports.
+ *
+ * @param fileContent - The full text content of a TypeScript/JavaScript file.
+ * @returns An array of import path strings as written in the source (e.g. "./foo", "react").
+ */
+declare function extractImports(fileContent: string): string[];
+/**
+ * Builds an import graph mapping test file paths to their imported module paths.
+ *
+ * Discovers test files, reads each, extracts imports, and builds a graph.
+ * Computes a deterministic buildHash from the serialized graph content.
+ * Individual file read failures are silently skipped.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @returns An {@link ImportGraphPayload} containing the graph and a deterministic buildHash.
+ */
+declare function buildImportGraph(projectRoot: string): Promise<ImportGraphPayload>;
+
+export { type FetchTarget, GlasstraceExporter, type GlasstraceExporterOptions, GlasstraceSpanProcessor, type ResolvedConfig, SdkError, SessionManager, type SourceMapEntry, buildImportGraph, captureError, classifyFetchTarget, collectSourceMaps, computeBuildHash, createDiscoveryHandler, deriveSessionId, discoverTestFiles, extractImports, getActiveConfig, getDateString, getDiscoveryHandler, getOrCreateAnonKey, getOrigin, isAnonymousMode, isProductionDisabled, loadCachedConfig, performInit, readAnonKey, readEnvVars, registerGlasstrace, resolveConfig, saveCachedConfig, sendInitRequest, uploadSourceMaps, withGlasstraceConfig };