@glasstrace/sdk 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -217,6 +217,7 @@ declare class GlasstraceExporter implements SpanExporter {
     private readonly endpointUrl;
     private readonly createDelegateFn;
     private delegate;
+    private delegateKey;
     private pendingBatches;
     private pendingSpanCount;
     private overflowLogged;
@@ -232,22 +233,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 +334,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 +386,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

@@ -217,6 +217,7 @@ declare class GlasstraceExporter implements SpanExporter {
     private readonly endpointUrl;
     private readonly createDelegateFn;
     private delegate;
+    private delegateKey;
     private pendingBatches;
     private pendingSpanCount;
     private overflowLogged;
@@ -232,22 +233,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 +334,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 +386,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 };