@glasstrace/sdk 0.14.2 → 0.16.0

package/dist/index.d.cts

@@ -278,14 +278,27 @@ declare function getOrCreateAnonKey(projectRoot?: string): Promise<AnonApiKey>;
  */
 declare function loadCachedConfig(projectRoot?: string): SdkInitResponse | null;
 /**
- * Persists the init response to `.glasstrace/config`.
- * Silently skipped when `node:fs` is unavailable (non-Node environments).
- * On I/O failure, logs a warning and continues.
+ * Persists the init response to `.glasstrace/config` using atomic
+ * write-temp + rename semantics. Silently skipped when `node:fs` is
+ * unavailable (non-Node environments). On I/O failure, logs a warning.
+ *
+ * Atomicity: the payload is written to `.glasstrace/config.tmp` and then
+ * renamed into place. `rename` is atomic on POSIX filesystems, so readers
+ * either see the previous valid config or the new valid config — never a
+ * truncated or partially-written file (DISC-1247 Scenario 5). If the
+ * rename fails, the temp file is cleaned up on a best-effort basis.
  */
 declare function saveCachedConfig(response: SdkInitResponse, projectRoot?: string): Promise<void>;
 /**
  * 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;
@@ -514,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
@@ -564,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
  */
 
 /**

package/dist/index.d.ts

@@ -278,14 +278,27 @@ declare function getOrCreateAnonKey(projectRoot?: string): Promise<AnonApiKey>;
  */
 declare function loadCachedConfig(projectRoot?: string): SdkInitResponse | null;
 /**
- * Persists the init response to `.glasstrace/config`.
- * Silently skipped when `node:fs` is unavailable (non-Node environments).
- * On I/O failure, logs a warning and continues.
+ * Persists the init response to `.glasstrace/config` using atomic
+ * write-temp + rename semantics. Silently skipped when `node:fs` is
+ * unavailable (non-Node environments). On I/O failure, logs a warning.
+ *
+ * Atomicity: the payload is written to `.glasstrace/config.tmp` and then
+ * renamed into place. `rename` is atomic on POSIX filesystems, so readers
+ * either see the previous valid config or the new valid config — never a
+ * truncated or partially-written file (DISC-1247 Scenario 5). If the
+ * rename fails, the temp file is cleaned up on a best-effort basis.
  */
 declare function saveCachedConfig(response: SdkInitResponse, projectRoot?: string): Promise<void>;
 /**
  * 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;
@@ -514,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
@@ -564,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
  */
 
 /**