@glasstrace/sdk 0.13.5 → 0.14.0

package/dist/index.d.cts

@@ -38,6 +38,7 @@ declare const CaptureConfigSchema: z.ZodObject<{
     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(). */
@@ -102,6 +103,7 @@ declare const SdkInitResponseSchema: z.ZodObject<{
         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>;
@@ -361,7 +363,7 @@ interface GlasstraceExporterOptions {
     environment: string | undefined;
     endpointUrl: string;
     createDelegate: ((url: string, headers: Record<string, string>) => SpanExporter) | null;
-    /** @deprecated No-op retained for backward compatibility. Will be removed in a future major. */
+    /** When true, logs diagnostic details about enrichment decisions via sdkLog. */
     verbose?: boolean;
 }
 /**
@@ -383,6 +385,7 @@ declare class GlasstraceExporter implements SpanExporter {
     private readonly environment;
     private readonly endpointUrl;
     private readonly createDelegateFn;
+    private readonly verbose;
     private delegate;
     private delegateKey;
     private pendingBatches;
@@ -498,6 +501,72 @@ type NextConfig = Record<string, unknown>;
  */
 declare function withGlasstraceConfig(nextConfig: NextConfig): NextConfig;
 
+/**
+ * Returns true when the SDK is in ACTIVE or ACTIVE_DEGRADED state.
+ */
+declare function isReady(): boolean;
+/**
+ * Resolves when the SDK reaches ACTIVE or ACTIVE_DEGRADED.
+ * Rejects on PRODUCTION_DISABLED, REGISTRATION_FAILED, or timeout.
+ *
+ * Checks current state synchronously first — resolves/rejects immediately
+ * if the SDK has already reached a terminal or ready state.
+ */
+declare function waitForReady(timeoutMs?: number): Promise<void>;
+/**
+ * Simplified public state query for external consumers.
+ * Hides implementation details like coexistence scenarios.
+ */
+declare function getStatus(): {
+    ready: boolean;
+    mode: "anonymous" | "authenticated" | "claiming" | "disabled";
+    tracing: "active" | "degraded" | "not-configured" | "coexistence";
+};
+
+/**
+ * OTel Coexistence Public API
+ *
+ * Provides createGlasstraceSpanProcessor() for developers who want to
+ * manually integrate Glasstrace with their existing OTel provider
+ * (e.g., Sentry's openTelemetrySpanProcessors config option).
+ *
+ * Also provides nudge messaging that guides developers toward this
+ * clean integration path when auto-attach is used.
+ *
+ * Design: sdk-otel-coexistence.md Sections 3, 5, 6
+ */
+
+/**
+ * Creates a Glasstrace span processor for manual integration with an
+ * existing OTel provider.
+ *
+ * Use this when another tool (e.g., Sentry) owns the OTel provider and
+ * you want to add Glasstrace to their processor list:
+ *
+ * @example
+ * ```ts
+ * import * as Sentry from "@sentry/nextjs";
+ * import { createGlasstraceSpanProcessor } from "@glasstrace/sdk";
+ *
+ * Sentry.init({
+ *   dsn: "...",
+ *   openTelemetrySpanProcessors: [createGlasstraceSpanProcessor()],
+ * });
+ * ```
+ *
+ * **Important:** `registerGlasstrace()` is still required even when using
+ * this function. The processor handles span transport (enrichment and
+ * export). `registerGlasstrace()` handles everything else: init calls,
+ * config sync, session management, anonymous key generation, discovery
+ * endpoint, and health reporting.
+ *
+ * @param options - Optional SDK configuration. If omitted, uses the same
+ *   config as registerGlasstrace() (environment variables).
+ * @returns A BatchSpanProcessor wrapping a GlasstraceExporter with the
+ *   branded Symbol.for('glasstrace.exporter') for coexistence detection.
+ */
+declare function createGlasstraceSpanProcessor(options?: GlasstraceOptions): SpanProcessor;
+
 interface SourceMapEntry {
     filePath: string;
     content: string;
@@ -658,4 +727,4 @@ declare function extractImports(fileContent: string): string[];
  */
 declare function buildImportGraph(projectRoot: string): Promise<ImportGraphPayload>;
 
-export { type AutoUploadOptions, type BlobUploader, type ClaimState, type FetchTarget, GlasstraceExporter, type GlasstraceExporterOptions, GlasstraceSpanProcessor, type InitClaimResult, PRESIGNED_THRESHOLD_BYTES, type ResolvedConfig, SdkError, SessionManager, type SourceMapEntry, type SourceMapFileInfo, buildImportGraph, captureError, classifyFetchTarget, collectSourceMaps, computeBuildHash, createDiscoveryHandler, deriveSessionId, discoverSourceMapFiles, discoverTestFiles, extractImports, getActiveConfig, getDateString, getDiscoveryHandler, getLinkedAccountId, getOrCreateAnonKey, getOrigin, isAnonymousMode, isProductionDisabled, loadCachedConfig, performInit, readAnonKey, readEnvVars, registerGlasstrace, resolveConfig, saveCachedConfig, sendInitRequest, uploadSourceMaps, uploadSourceMapsAuto, uploadSourceMapsPresigned, withGlasstraceConfig };
+export { type AutoUploadOptions, type BlobUploader, type ClaimState, type FetchTarget, GlasstraceExporter, type GlasstraceExporterOptions, GlasstraceSpanProcessor, type InitClaimResult, PRESIGNED_THRESHOLD_BYTES, type ResolvedConfig, SdkError, SessionManager, type SourceMapEntry, type SourceMapFileInfo, buildImportGraph, 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 };

package/dist/index.d.ts

@@ -38,6 +38,7 @@ declare const CaptureConfigSchema: z.ZodObject<{
     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(). */
@@ -102,6 +103,7 @@ declare const SdkInitResponseSchema: z.ZodObject<{
         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>;
@@ -361,7 +363,7 @@ interface GlasstraceExporterOptions {
     environment: string | undefined;
     endpointUrl: string;
     createDelegate: ((url: string, headers: Record<string, string>) => SpanExporter) | null;
-    /** @deprecated No-op retained for backward compatibility. Will be removed in a future major. */
+    /** When true, logs diagnostic details about enrichment decisions via sdkLog. */
     verbose?: boolean;
 }
 /**
@@ -383,6 +385,7 @@ declare class GlasstraceExporter implements SpanExporter {
     private readonly environment;
     private readonly endpointUrl;
     private readonly createDelegateFn;
+    private readonly verbose;
     private delegate;
     private delegateKey;
     private pendingBatches;
@@ -498,6 +501,72 @@ type NextConfig = Record<string, unknown>;
  */
 declare function withGlasstraceConfig(nextConfig: NextConfig): NextConfig;
 
+/**
+ * Returns true when the SDK is in ACTIVE or ACTIVE_DEGRADED state.
+ */
+declare function isReady(): boolean;
+/**
+ * Resolves when the SDK reaches ACTIVE or ACTIVE_DEGRADED.
+ * Rejects on PRODUCTION_DISABLED, REGISTRATION_FAILED, or timeout.
+ *
+ * Checks current state synchronously first — resolves/rejects immediately
+ * if the SDK has already reached a terminal or ready state.
+ */
+declare function waitForReady(timeoutMs?: number): Promise<void>;
+/**
+ * Simplified public state query for external consumers.
+ * Hides implementation details like coexistence scenarios.
+ */
+declare function getStatus(): {
+    ready: boolean;
+    mode: "anonymous" | "authenticated" | "claiming" | "disabled";
+    tracing: "active" | "degraded" | "not-configured" | "coexistence";
+};
+
+/**
+ * OTel Coexistence Public API
+ *
+ * Provides createGlasstraceSpanProcessor() for developers who want to
+ * manually integrate Glasstrace with their existing OTel provider
+ * (e.g., Sentry's openTelemetrySpanProcessors config option).
+ *
+ * Also provides nudge messaging that guides developers toward this
+ * clean integration path when auto-attach is used.
+ *
+ * Design: sdk-otel-coexistence.md Sections 3, 5, 6
+ */
+
+/**
+ * Creates a Glasstrace span processor for manual integration with an
+ * existing OTel provider.
+ *
+ * Use this when another tool (e.g., Sentry) owns the OTel provider and
+ * you want to add Glasstrace to their processor list:
+ *
+ * @example
+ * ```ts
+ * import * as Sentry from "@sentry/nextjs";
+ * import { createGlasstraceSpanProcessor } from "@glasstrace/sdk";
+ *
+ * Sentry.init({
+ *   dsn: "...",
+ *   openTelemetrySpanProcessors: [createGlasstraceSpanProcessor()],
+ * });
+ * ```
+ *
+ * **Important:** `registerGlasstrace()` is still required even when using
+ * this function. The processor handles span transport (enrichment and
+ * export). `registerGlasstrace()` handles everything else: init calls,
+ * config sync, session management, anonymous key generation, discovery
+ * endpoint, and health reporting.
+ *
+ * @param options - Optional SDK configuration. If omitted, uses the same
+ *   config as registerGlasstrace() (environment variables).
+ * @returns A BatchSpanProcessor wrapping a GlasstraceExporter with the
+ *   branded Symbol.for('glasstrace.exporter') for coexistence detection.
+ */
+declare function createGlasstraceSpanProcessor(options?: GlasstraceOptions): SpanProcessor;
+
 interface SourceMapEntry {
     filePath: string;
     content: string;
@@ -658,4 +727,4 @@ declare function extractImports(fileContent: string): string[];
  */
 declare function buildImportGraph(projectRoot: string): Promise<ImportGraphPayload>;
 
-export { type AutoUploadOptions, type BlobUploader, type ClaimState, type FetchTarget, GlasstraceExporter, type GlasstraceExporterOptions, GlasstraceSpanProcessor, type InitClaimResult, PRESIGNED_THRESHOLD_BYTES, type ResolvedConfig, SdkError, SessionManager, type SourceMapEntry, type SourceMapFileInfo, buildImportGraph, captureError, classifyFetchTarget, collectSourceMaps, computeBuildHash, createDiscoveryHandler, deriveSessionId, discoverSourceMapFiles, discoverTestFiles, extractImports, getActiveConfig, getDateString, getDiscoveryHandler, getLinkedAccountId, getOrCreateAnonKey, getOrigin, isAnonymousMode, isProductionDisabled, loadCachedConfig, performInit, readAnonKey, readEnvVars, registerGlasstrace, resolveConfig, saveCachedConfig, sendInitRequest, uploadSourceMaps, uploadSourceMapsAuto, uploadSourceMapsPresigned, withGlasstraceConfig };
+export { type AutoUploadOptions, type BlobUploader, type ClaimState, type FetchTarget, GlasstraceExporter, type GlasstraceExporterOptions, GlasstraceSpanProcessor, type InitClaimResult, PRESIGNED_THRESHOLD_BYTES, type ResolvedConfig, SdkError, SessionManager, type SourceMapEntry, type SourceMapFileInfo, buildImportGraph, 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 };