@glasstrace/sdk 0.20.0 → 1.0.0

package/dist/index.d.ts

@@ -1,197 +1,13 @@
-import * as z from './v4/classic/external.cjs';
+import { a as SessionManager } from './edge-entry-CFq085RZ.js';
+export { C as CorrelationIdRequest, G as GlasstraceSpanProcessor, S as SdkError, c as captureCorrelationId, g as getDateString, b as getOrigin } from './edge-entry-CFq085RZ.js';
+import { G as GlasstraceEnvVars, a as GlasstraceOptions, A as AnonApiKey, S as SdkInitResponse, C as CaptureConfig, b as SdkHealthReport, I as ImportGraphPayload, c as SdkDiagnosticCode } from './index.d-CYYe3PxB.js';
+export { d as deriveSessionId } from './index.d-CYYe3PxB.js';
 import { ReadableSpan } from './export/ReadableSpan';
-import { Span } from './Span';
-import { SpanProcessor } from './SpanProcessor';
 import { SpanExporter } from './export/SpanExporter';
 import { ExportResult } from './ExportResult';
-
-/** Anonymous API key: `gt_anon_` + 48 hex chars. */
-declare const AnonApiKeySchema: z.core.$ZodBranded<z.ZodString, "AnonApiKey", "out">;
-type AnonApiKey = z.infer<typeof AnonApiKeySchema>;
-/** Session ID: 16 hex chars (deterministic, derived from API key + time window). */
-declare const SessionIdSchema: z.core.$ZodBranded<z.ZodString, "SessionId", "out">;
-type SessionId = z.infer<typeof SessionIdSchema>;
-
-/**
- * SDK-specific enums.
- */
-
-/** Diagnostic codes the SDK can report during health checks. */
-declare const SdkDiagnosticCodeSchema: z.ZodEnum<{
-    ingestion_unreachable: "ingestion_unreachable";
-    ingestion_auth_failed: "ingestion_auth_failed";
-    ingestion_rate_limited: "ingestion_rate_limited";
-    config_sync_failed: "config_sync_failed";
-    source_map_upload_failed: "source_map_upload_failed";
-}>;
-type SdkDiagnosticCode = z.infer<typeof SdkDiagnosticCodeSchema>;
-
-/**
- * SDK configuration types.
- */
-
-/** SDK capture configuration: which events to capture. */
-declare const CaptureConfigSchema: z.ZodObject<{
-    requestBodies: z.ZodBoolean;
-    queryParamValues: z.ZodBoolean;
-    envVarValues: z.ZodBoolean;
-    fullConsoleOutput: z.ZodBoolean;
-    importGraph: z.ZodBoolean;
-    consoleErrors: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    errorResponseBodies: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-}, z.core.$strip>;
-type CaptureConfig = z.infer<typeof CaptureConfigSchema>;
-/** Developer-facing config for registerGlasstrace(). */
-declare const GlasstraceOptionsSchema: z.ZodObject<{
-    apiKey: z.ZodOptional<z.ZodString>;
-    endpoint: z.ZodOptional<z.ZodString>;
-    forceEnable: z.ZodOptional<z.ZodBoolean>;
-    verbose: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>;
-type GlasstraceOptions = z.infer<typeof GlasstraceOptionsSchema>;
-/** All recognized SDK environment variables. */
-declare const GlasstraceEnvVarsSchema: z.ZodObject<{
-    GLASSTRACE_API_KEY: z.ZodOptional<z.ZodString>;
-    GLASSTRACE_FORCE_ENABLE: z.ZodOptional<z.ZodString>;
-    GLASSTRACE_ENV: z.ZodOptional<z.ZodString>;
-    GLASSTRACE_COVERAGE_MAP: z.ZodOptional<z.ZodString>;
-    NODE_ENV: z.ZodOptional<z.ZodString>;
-    VERCEL_ENV: z.ZodOptional<z.ZodString>;
-}, z.core.$strip>;
-type GlasstraceEnvVars = z.infer<typeof GlasstraceEnvVarsSchema>;
-
-/**
- * Wire format types for SDK ↔ backend communication.
- *
- * These schemas define the request/response shapes for:
- * - SDK initialization (POST /v1/sdk/init)
- * - SDK health diagnostics (embedded in init requests)
- * - Discovery endpoint (GET /__glasstrace/config)
- * - Source map upload (POST /v1/source-maps)
- * - Presigned source map upload (POST /v1/source-maps/presign, POST /v1/source-maps/manifest)
- */
-
-/** Test file import relationships, embedded in SDK init request. */
-declare const ImportGraphPayloadSchema: z.ZodObject<{
-    buildHash: z.core.$ZodBranded<z.ZodString, "BuildHash", "out">;
-    graph: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
-type ImportGraphPayload = z.infer<typeof ImportGraphPayloadSchema>;
-/** SDK health diagnostics included in init requests. */
-declare const SdkHealthReportSchema: z.ZodObject<{
-    tracesExportedSinceLastInit: z.ZodNumber;
-    tracesDropped: z.ZodNumber;
-    initFailures: z.ZodNumber;
-    configAge: z.ZodNumber;
-    sdkVersion: z.ZodString;
-}, z.core.$strip>;
-type SdkHealthReport = z.infer<typeof SdkHealthReportSchema>;
-/**
- * Response from POST /v1/sdk/init.
- *
- * Note: SdkInitRequest is intentionally NOT in the protocol package.
- * The request schema includes backend-specific types (TierLimits,
- * SubscriptionStatus) that are not part of the public contract.
- * The backend owns the request validation; the SDK only needs to
- * understand the response.
- */
-declare const SdkInitResponseSchema: z.ZodObject<{
-    config: z.ZodObject<{
-        requestBodies: z.ZodBoolean;
-        queryParamValues: z.ZodBoolean;
-        envVarValues: z.ZodBoolean;
-        fullConsoleOutput: z.ZodBoolean;
-        importGraph: z.ZodBoolean;
-        consoleErrors: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-        errorResponseBodies: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    }, z.core.$strip>;
-    subscriptionStatus: z.ZodString;
-    linkedAccountId: z.ZodOptional<z.ZodString>;
-    minimumSdkVersion: z.ZodString;
-    apiVersion: z.ZodString;
-    tierLimits: z.ZodObject<{
-        tracesPerMinute: z.ZodNumber;
-        storageTtlHours: z.ZodNumber;
-        maxTraceSizeBytes: z.ZodNumber;
-        maxConcurrentSessions: z.ZodNumber;
-    }, z.core.$strip>;
-    claimResult: z.ZodOptional<z.ZodObject<{
-        newApiKey: z.core.$ZodBranded<z.ZodString, "DevApiKey", "out">;
-        accountId: z.ZodString;
-        graceExpiresAt: z.ZodNumber;
-    }, z.core.$strip>>;
-}, z.core.$strip>;
-type SdkInitResponse = z.infer<typeof SdkInitResponseSchema>;
-/** Response from POST /v1/source-maps. */
-declare const SourceMapUploadResponseSchema: z.ZodObject<{
-    success: z.ZodLiteral<true>;
-    buildHash: z.core.$ZodBranded<z.ZodString, "BuildHash", "out">;
-    fileCount: z.ZodNumber;
-    totalSizeBytes: z.ZodNumber;
-}, z.core.$strip>;
-type SourceMapUploadResponse = z.infer<typeof SourceMapUploadResponseSchema>;
-/** Response confirming source map manifest activation. */
-declare const SourceMapManifestResponseSchema: z.ZodObject<{
-    success: z.ZodLiteral<true>;
-    buildHash: z.core.$ZodBranded<z.ZodString, "BuildHash", "out">;
-    fileCount: z.ZodNumber;
-    totalSizeBytes: z.ZodNumber;
-    activatedAt: z.ZodNumber;
-}, z.core.$strip>;
-type SourceMapManifestResponse = z.infer<typeof SourceMapManifestResponseSchema>;
-
-/**
- * Session ID derivation — part of the public Glasstrace wire contract.
- *
- * Deriving the session ID is deterministic: given the same inputs,
- * every runtime that implements this module produces the same
- * 16-character hex identifier. That determinism is the contract — it
- * lets independent clients (SDK, browser extension, server tooling)
- * agree on the same session without coordination.
- *
- * This module is pure: it has no module-level state and no
- * runtime-dependent branches. It is safe to import from Node 20+,
- * modern browsers, Vercel Edge, and Cloudflare Workers. The SHA-256
- * implementation is pure JavaScript; no `node:crypto`, no Web Crypto,
- * no bundler-specific shims.
- */
-
-/**
- * Derives a deterministic session ID from the inputs that define a
- * Glasstrace session. The output is a 16-character lowercase hex
- * string validated through {@link SessionIdSchema}.
- *
- * This function is part of the Glasstrace wire contract: any consumer
- * (SDK, browser extension, server tooling) that calls it with the same
- * arguments receives the same `SessionId`. That property is what lets
- * independent clients agree on a session without coordination.
- *
- * Uses a pure-JavaScript SHA-256 so the output is identical across
- * every runtime this package supports (Node 20+, modern browsers,
- * Vercel Edge, Cloudflare Workers).
- *
- * Security note: the session ID is an **identifier**, not a secret or
- * an authentication token. It is never used for authorization.
- *
- * @param apiKey - The project's API key (or anonymous placeholder).
- * @param origin - The origin string identifying the deployment
- *   environment (for example `localhost:3000` or `production`).
- * @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 {@link SessionId}.
- */
-declare function deriveSessionId(apiKey: string, origin: string, date: string, windowIndex: number): SessionId;
-
-/**
- * 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);
-}
+import { SpanProcessor } from './SpanProcessor';
+import './Span';
+import './v4/classic/external.cjs';
 
 /**
  * Resolved configuration after merging explicit options with environment variables.
@@ -231,43 +47,6 @@ declare function isProductionDisabled(config: ResolvedConfig): boolean;
  */
 declare function isAnonymousMode(config: ResolvedConfig): boolean;
 
-/**
- * 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.
  */
@@ -374,29 +153,6 @@ declare function getActiveConfig(): CaptureConfig;
  */
 declare function getLinkedAccountId(): string | undefined;
 
-/**
- * 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: Parameters<SpanProcessor["onStart"]>[1]): void;
-    onEnd(readableSpan: ReadableSpan): void;
-    shutdown(): Promise<void>;
-    forceFlush(): Promise<void>;
-}
-
 /**
  * Options for constructing a {@link GlasstraceExporter}.
  */
@@ -483,33 +239,6 @@ declare class GlasstraceExporter implements SpanExporter {
     private flushPending;
 }
 
-/**
- * Claim state returned by the `getClaimState` callback.
- *
- * - `claimed` — `true` when the anonymous key has been linked to an account.
- * - `accountHint` — optional masked identifier (e.g. `"er***@example.com"`)
- *   for the browser extension to display to the user.
- */
-interface ClaimState {
-    claimed: boolean;
-    accountHint?: string;
-}
-/**
- * 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.
- *
- * When `getClaimState` returns a non-null value with `claimed: true`, the
- * response includes `claimed` and (optionally) `accountHint` so the browser
- * extension can prompt the user to sign in.
- *
- * 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, getClaimState?: () => ClaimState | null): (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.
@@ -673,105 +402,6 @@ declare function getStatus(): {
  */
 declare function createGlasstraceSpanProcessor(options?: GlasstraceOptions): SpanProcessor;
 
-interface SourceMapEntry {
-    filePath: string;
-    content: string;
-}
-/**
- * Metadata for a discovered source map file, without its content loaded.
- * Used by the streaming upload flow to defer file reads until upload time.
- */
-interface SourceMapFileInfo {
-    /** Relative path to the compiled JS file (`.map` extension stripped). */
-    filePath: string;
-    /** Absolute path on disk for reading the file content on demand. */
-    absolutePath: string;
-    /** File size in bytes. */
-    sizeBytes: number;
-}
-/**
- * Recursively discovers all `.map` files in the given build directory.
- * Returns metadata only — file content is NOT read into memory.
- */
-declare function discoverSourceMapFiles(buildDir: string): Promise<SourceMapFileInfo[]>;
-/**
- * Recursively finds all .map files in the given build directory.
- * Returns relative paths and file contents.
- *
- * @deprecated Prefer {@link discoverSourceMapFiles} to avoid loading all
- * source maps into memory simultaneously.
- */
-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.
- *
- * Accepts either `SourceMapEntry[]` (legacy, in-memory) or
- * `SourceMapFileInfo[]` (streaming, reads on demand).
- */
-declare function computeBuildHash(maps?: SourceMapEntry[] | SourceMapFileInfo[]): 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.
- *
- * Accepts either `SourceMapEntry[]` (legacy, in-memory) or
- * `SourceMapFileInfo[]` (deferred reads). With `SourceMapFileInfo[]`,
- * file content is read at upload time rather than at discovery time.
- * Note: the legacy endpoint sends all files in a single JSON body, so
- * peak memory is similar — the benefit is deferring reads past discovery.
- */
-declare function uploadSourceMaps(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[] | SourceMapFileInfo[]): Promise<SourceMapUploadResponse>;
-/** Builds at or above this byte size route to the presigned upload flow. */
-declare const PRESIGNED_THRESHOLD_BYTES = 4500000;
-/** Signature for the blob upload function, injectable for testing. */
-type BlobUploader = (clientToken: string, pathname: string, content: string) => Promise<{
-    url: string;
-    size: number;
-}>;
-/**
- * Orchestrates the 3-phase presigned upload flow.
- *
- * 1. Requests presigned tokens for all source map files
- * 2. Uploads each file to blob storage with a concurrency limit of 5,
- *    reading file content from disk just before each upload
- * 3. Submits the manifest to finalize the upload
- *
- * Accepts either `SourceMapEntry[]` (legacy, in-memory) or
- * `SourceMapFileInfo[]` (streaming, reads on demand).
- *
- * Accepts an optional `blobUploader` for test injection; defaults to
- * {@link uploadToBlob}.
- */
-declare function uploadSourceMapsPresigned(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[] | SourceMapFileInfo[], blobUploader?: BlobUploader): Promise<SourceMapManifestResponse>;
-/**
- * Options for {@link uploadSourceMapsAuto}, primarily used for test injection.
- */
-interface AutoUploadOptions {
-    /** Override blob availability check (for testing). */
-    checkBlobAvailable?: () => Promise<boolean>;
-    /** Override blob uploader (for testing). */
-    blobUploader?: BlobUploader;
-}
-/**
- * Automatically routes source map uploads based on total build size.
- *
- * - Below {@link PRESIGNED_THRESHOLD_BYTES}: uses the legacy single-request
- *   {@link uploadSourceMaps} endpoint.
- * - At or above the threshold: checks if `@vercel/blob` is available and
- *   uses the presigned 3-phase flow. Falls back to legacy with a warning
- *   if the package is not installed.
- *
- * Accepts either `SourceMapEntry[]` (legacy, in-memory) or
- * `SourceMapFileInfo[]` (streaming, reads on demand).
- */
-declare function uploadSourceMapsAuto(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[] | SourceMapFileInfo[], options?: AutoUploadOptions): Promise<SourceMapUploadResponse | SourceMapManifestResponse>;
-
 /**
  * Manual error capture API.
  *
@@ -804,87 +434,4 @@ declare function uploadSourceMapsAuto(apiKey: string, endpoint: string, buildHas
  */
 declare function captureError(error: unknown): void;
 
-/**
- * Minimal Fetch-API `Headers`-like interface supporting case-insensitive
- * single-value lookup. Matches `Headers` from `undici` / the Web Fetch API.
- */
-interface FetchHeadersLike {
-    get(name: string): string | null;
-}
-/**
- * Minimal Node `IncomingMessage.headers`-like shape: a dictionary mapping
- * (typically lower-cased) header names to a value, a list of values, or
- * `undefined`.
- */
-type NodeHeadersLike = Record<string, string | string[] | undefined>;
-/**
- * Accepted request shape for {@link captureCorrelationId}. Intentionally
- * loose so callers can pass either a Fetch `Request` (or `NextRequest`)
- * or a Node `IncomingMessage` without adapting the type.
- */
-interface CorrelationIdRequest {
-    headers: FetchHeadersLike | NodeHeadersLike | undefined;
-}
-/**
- * Captures the Glasstrace correlation ID header (`x-gt-cid`) from an
- * incoming request and materializes it as the
- * `glasstrace.correlation.id` attribute on the currently active OTel span
- * (DISC-1253).
- *
- * The SDK does not own any HTTP instrumentation, so it cannot read this
- * header itself. Users opt in by calling this helper from a hook that
- * runs inside the request's OTel context — typically a Next.js
- * `middleware.ts` or a custom server request handler.
- *
- * The function is intentionally forgiving:
- * - No active span → no-op.
- * - Missing / empty header → no-op.
- * - Array header values (Node IncomingMessage) → the first non-empty
- *   value is used; subsequent values are ignored because a correlation
- *   ID is a single logical value.
- * - Malformed or unexpected `headers` shapes → caught and ignored; the
- *   helper never throws.
- *
- * @example
- * ```ts
- * // Next.js middleware.ts
- * import { captureCorrelationId } from "@glasstrace/sdk";
- *
- * export function middleware(req: Request) {
- *   captureCorrelationId(req);
- *   return NextResponse.next();
- * }
- * ```
- */
-declare function captureCorrelationId(req: CorrelationIdRequest | null | undefined): 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 AutoUploadOptions, type BlobUploader, type ClaimState, type CorrelationIdRequest, type FetchTarget, GlasstraceExporter, type GlasstraceExporterOptions, GlasstraceSpanProcessor, type InitClaimResult, PRESIGNED_THRESHOLD_BYTES, type ResolvedConfig, SdkError, SessionManager, type SourceMapEntry, type SourceMapFileInfo, buildImportGraph, captureCorrelationId, captureError, classifyFetchTarget, collectSourceMaps, computeBuildHash, createDiscoveryHandler, createGlasstraceSpanProcessor, deriveSessionId, discoverSourceMapFiles, discoverTestFiles, extractImports, getActiveConfig, getDateString, getDiscoveryHandler, getLinkedAccountId, getOrCreateAnonKey, getOrigin, getStatus, isAnonymousMode, isProductionDisabled, isReady, loadCachedConfig, performInit, readAnonKey, readEnvVars, registerGlasstrace, resolveConfig, saveCachedConfig, sendInitRequest, uploadSourceMaps, uploadSourceMapsAuto, uploadSourceMapsPresigned, waitForReady, withGlasstraceConfig };
+export { type FetchTarget, GlasstraceExporter, type GlasstraceExporterOptions, type InitClaimResult, type ResolvedConfig, SessionManager, captureError, classifyFetchTarget, createGlasstraceSpanProcessor, getActiveConfig, getDiscoveryHandler, getLinkedAccountId, getOrCreateAnonKey, getStatus, isAnonymousMode, isProductionDisabled, isReady, loadCachedConfig, performInit, readAnonKey, readEnvVars, registerGlasstrace, resolveConfig, saveCachedConfig, sendInitRequest, waitForReady, withGlasstraceConfig };