@glasstrace/sdk 0.15.1 → 0.17.0

package/dist/index.d.cts

@@ -292,6 +292,13 @@ declare function saveCachedConfig(response: SdkInitResponse, projectRoot?: strin
 /**
  * Sends a POST request to `/v1/sdk/init`.
  * Validates the response against `SdkInitResponseSchema`.
+ *
+ * Uses `node:https` via {@link httpsPostJson} rather than the global
+ * `fetch` because Next.js 16 patches `fetch` for caching/revalidation
+ * and can cause the init request to silently hang (DISC-493 Issue 3).
+ * Retries transport-level failures (DNS, TCP, TLS) twice with 500ms +
+ * 1500ms backoff, capped at a 20-second total deadline. Server responses
+ * (HTTP 4xx/5xx) are never retried and are surfaced immediately.
  */
 declare function sendInitRequest(config: ResolvedConfig, anonKey: AnonApiKey | null, sdkVersion: string, importGraph?: ImportGraphPayload, healthReport?: SdkHealthReport, diagnostics?: Array<{
     code: SdkDiagnosticCode;
@@ -520,6 +527,31 @@ type NextConfig = object;
  * The build NEVER fails because of Glasstrace — all errors are caught
  * and logged as warnings.
  *
+ * ## What the wrapper configures for you
+ *
+ * - `experimental.serverSourceMaps: true` — enables server-side source maps
+ *   so Glasstrace can resolve stack traces back to your source.
+ * - `serverExternalPackages: ["@glasstrace/sdk"]` — tells Next to load the
+ *   SDK via Node's `require()` at runtime instead of bundling it through
+ *   webpack or Turbopack on the RSC / Route Handler paths. This is the same
+ *   pattern Prisma, `@vercel/otel`, Sentry, `sharp`, and `bcrypt` ship with.
+ * - A webpack `externals` entry that marks every Node.js built-in import
+ *   (both `node:*` and bare forms like `zlib` or `stream`) as a runtime
+ *   `commonjs` require. `serverExternalPackages` does not apply to the
+ *   instrumentation path under `next dev --webpack`
+ *   (vercel/next.js#58003, #28774), so any bundled SDK chunk that imports
+ *   `node:child_process` or the bare `zlib` specifier used by
+ *   `@opentelemetry/otlp-exporter-base` would otherwise crash with
+ *   `UnhandledSchemeError` or `Can't resolve 'zlib'`. This entry is the
+ *   actual DISC-1257 fix for the dev-webpack path. Turbopack is
+ *   unaffected — it ignores `config.webpack` and resolves Node built-ins
+ *   natively.
+ * - An empty `turbopack: {}` when none is set, so Next 16 does not reject
+ *   the config for setting `webpack` without a companion `turbopack` key
+ *   (DISC-1256).
+ * - A `webpack` hook that collects and uploads `.map` files on client-side
+ *   production builds.
+ *
  * ## Turbopack
  *
  * Next.js 16 made Turbopack the default bundler for `next build`, and Next
@@ -570,10 +602,13 @@ declare function getStatus(): {
  * 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.
+ * Also provides the auto-attach path (tryAutoAttachGlasstraceProcessor)
+ * that configureOtel() uses when it detects a pre-registered provider
+ * at runtime (Next.js 16 production, Sentry, Datadog, New Relic). Both
+ * entry points reuse the same span-processor factory so the manual and
+ * automatic paths stay in lockstep.
  *
- * Design: sdk-otel-coexistence.md Sections 3, 5, 6
+ * Design: sdk-otel-coexistence.md Sections 3, 4, 5, 6
  */
 
 /**
@@ -738,6 +773,60 @@ 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
@@ -767,4 +856,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, 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 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 };

package/dist/index.d.ts

@@ -292,6 +292,13 @@ declare function saveCachedConfig(response: SdkInitResponse, projectRoot?: strin
 /**
  * Sends a POST request to `/v1/sdk/init`.
  * Validates the response against `SdkInitResponseSchema`.
+ *
+ * Uses `node:https` via {@link httpsPostJson} rather than the global
+ * `fetch` because Next.js 16 patches `fetch` for caching/revalidation
+ * and can cause the init request to silently hang (DISC-493 Issue 3).
+ * Retries transport-level failures (DNS, TCP, TLS) twice with 500ms +
+ * 1500ms backoff, capped at a 20-second total deadline. Server responses
+ * (HTTP 4xx/5xx) are never retried and are surfaced immediately.
  */
 declare function sendInitRequest(config: ResolvedConfig, anonKey: AnonApiKey | null, sdkVersion: string, importGraph?: ImportGraphPayload, healthReport?: SdkHealthReport, diagnostics?: Array<{
     code: SdkDiagnosticCode;
@@ -520,6 +527,31 @@ type NextConfig = object;
  * The build NEVER fails because of Glasstrace — all errors are caught
  * and logged as warnings.
  *
+ * ## What the wrapper configures for you
+ *
+ * - `experimental.serverSourceMaps: true` — enables server-side source maps
+ *   so Glasstrace can resolve stack traces back to your source.
+ * - `serverExternalPackages: ["@glasstrace/sdk"]` — tells Next to load the
+ *   SDK via Node's `require()` at runtime instead of bundling it through
+ *   webpack or Turbopack on the RSC / Route Handler paths. This is the same
+ *   pattern Prisma, `@vercel/otel`, Sentry, `sharp`, and `bcrypt` ship with.
+ * - A webpack `externals` entry that marks every Node.js built-in import
+ *   (both `node:*` and bare forms like `zlib` or `stream`) as a runtime
+ *   `commonjs` require. `serverExternalPackages` does not apply to the
+ *   instrumentation path under `next dev --webpack`
+ *   (vercel/next.js#58003, #28774), so any bundled SDK chunk that imports
+ *   `node:child_process` or the bare `zlib` specifier used by
+ *   `@opentelemetry/otlp-exporter-base` would otherwise crash with
+ *   `UnhandledSchemeError` or `Can't resolve 'zlib'`. This entry is the
+ *   actual DISC-1257 fix for the dev-webpack path. Turbopack is
+ *   unaffected — it ignores `config.webpack` and resolves Node built-ins
+ *   natively.
+ * - An empty `turbopack: {}` when none is set, so Next 16 does not reject
+ *   the config for setting `webpack` without a companion `turbopack` key
+ *   (DISC-1256).
+ * - A `webpack` hook that collects and uploads `.map` files on client-side
+ *   production builds.
+ *
  * ## Turbopack
  *
  * Next.js 16 made Turbopack the default bundler for `next build`, and Next
@@ -570,10 +602,13 @@ declare function getStatus(): {
  * 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.
+ * Also provides the auto-attach path (tryAutoAttachGlasstraceProcessor)
+ * that configureOtel() uses when it detects a pre-registered provider
+ * at runtime (Next.js 16 production, Sentry, Datadog, New Relic). Both
+ * entry points reuse the same span-processor factory so the manual and
+ * automatic paths stay in lockstep.
  *
- * Design: sdk-otel-coexistence.md Sections 3, 5, 6
+ * Design: sdk-otel-coexistence.md Sections 3, 4, 5, 6
  */
 
 /**
@@ -738,6 +773,60 @@ 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
@@ -767,4 +856,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, 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 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 };