@glasstrace/sdk 0.1.0 → 0.2.1

package/dist/index.d.cts

@@ -1,8 +1,126 @@
-import { SdkDiagnosticCode, GlasstraceEnvVars, GlasstraceOptions, SessionId, AnonApiKey, CaptureConfig, SdkInitResponse, ImportGraphPayload, SdkHealthReport, SourceMapUploadResponse } from '@glasstrace/protocol';
+import * as z from './v4/classic/external.cjs';
 import { Context } from '@opentelemetry/api';
 import { SpanProcessor, Span, ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
 import { ExportResult } from '@opentelemetry/core';
 
+/** 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>>;
+}, 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)
+ */
+
+/** 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>>;
+    }, 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>;
+}, 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>;
+
 /**
  * Internal SDK error class with a typed diagnostic code.
  * Caught at the boundary and converted to a log message + diagnostic entry.
@@ -217,6 +335,7 @@ declare class GlasstraceExporter implements SpanExporter {
     private readonly endpointUrl;
     private readonly createDelegateFn;
     private delegate;
+    private delegateKey;
     private pendingBatches;
     private pendingSpanCount;
     private overflowLogged;
@@ -232,22 +351,30 @@ declare class GlasstraceExporter implements SpanExporter {
     /**
      * Enriches a ReadableSpan with all glasstrace.* attributes.
      * Returns a new ReadableSpan wrapper; the original span is not mutated.
-     * Each attribute derivation is wrapped in its own try-catch for partial
-     * enrichment resilience.
+     *
+     * 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 enriched spans while the API key is pending.
+     * 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.
-     * Called when the API key resolves.
+     * 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;
 }
@@ -325,6 +452,29 @@ declare function computeBuildHash(maps?: SourceMapEntry[]): Promise<string>;
  */
 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
@@ -354,4 +504,4 @@ declare function extractImports(fileContent: string): string[];
  */
 declare function buildImportGraph(projectRoot: string): Promise<ImportGraphPayload>;
 
-export { type FetchTarget, GlasstraceExporter, type GlasstraceExporterOptions, GlasstraceSpanProcessor, type ResolvedConfig, SdkError, SessionManager, type SourceMapEntry, buildImportGraph, classifyFetchTarget, collectSourceMaps, computeBuildHash, createDiscoveryHandler, deriveSessionId, discoverTestFiles, extractImports, getActiveConfig, getDateString, getDiscoveryHandler, getOrCreateAnonKey, getOrigin, isAnonymousMode, isProductionDisabled, loadCachedConfig, performInit, readAnonKey, readEnvVars, registerGlasstrace, resolveConfig, saveCachedConfig, sendInitRequest, uploadSourceMaps, withGlasstraceConfig };
+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 };

package/dist/index.d.ts

@@ -1,8 +1,126 @@
-import { SdkDiagnosticCode, GlasstraceEnvVars, GlasstraceOptions, SessionId, AnonApiKey, CaptureConfig, SdkInitResponse, ImportGraphPayload, SdkHealthReport, SourceMapUploadResponse } from '@glasstrace/protocol';
+import * as z from './v4/classic/external.cjs';
 import { Context } from '@opentelemetry/api';
 import { SpanProcessor, Span, ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
 import { ExportResult } from '@opentelemetry/core';
 
+/** 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>>;
+}, 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)
+ */
+
+/** 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>>;
+    }, 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>;
+}, 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>;
+
 /**
  * Internal SDK error class with a typed diagnostic code.
  * Caught at the boundary and converted to a log message + diagnostic entry.
@@ -217,6 +335,7 @@ declare class GlasstraceExporter implements SpanExporter {
     private readonly endpointUrl;
     private readonly createDelegateFn;
     private delegate;
+    private delegateKey;
     private pendingBatches;
     private pendingSpanCount;
     private overflowLogged;
@@ -232,22 +351,30 @@ declare class GlasstraceExporter implements SpanExporter {
     /**
      * Enriches a ReadableSpan with all glasstrace.* attributes.
      * Returns a new ReadableSpan wrapper; the original span is not mutated.
-     * Each attribute derivation is wrapped in its own try-catch for partial
-     * enrichment resilience.
+     *
+     * 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 enriched spans while the API key is pending.
+     * 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.
-     * Called when the API key resolves.
+     * 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;
 }
@@ -325,6 +452,29 @@ declare function computeBuildHash(maps?: SourceMapEntry[]): Promise<string>;
  */
 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
@@ -354,4 +504,4 @@ declare function extractImports(fileContent: string): string[];
  */
 declare function buildImportGraph(projectRoot: string): Promise<ImportGraphPayload>;
 
-export { type FetchTarget, GlasstraceExporter, type GlasstraceExporterOptions, GlasstraceSpanProcessor, type ResolvedConfig, SdkError, SessionManager, type SourceMapEntry, buildImportGraph, classifyFetchTarget, collectSourceMaps, computeBuildHash, createDiscoveryHandler, deriveSessionId, discoverTestFiles, extractImports, getActiveConfig, getDateString, getDiscoveryHandler, getOrCreateAnonKey, getOrigin, isAnonymousMode, isProductionDisabled, loadCachedConfig, performInit, readAnonKey, readEnvVars, registerGlasstrace, resolveConfig, saveCachedConfig, sendInitRequest, uploadSourceMaps, withGlasstraceConfig };
+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 };