@glasstrace/sdk 0.10.0 → 0.12.0

package/dist/index.d.cts

@@ -187,8 +187,9 @@ declare function isProductionDisabled(config: ResolvedConfig): boolean;
 declare function isAnonymousMode(config: ResolvedConfig): boolean;
 
 /**
- * Derives a deterministic session ID from the given inputs using SHA-256.
- * The hash is truncated to 16 hex characters and parsed through SessionIdSchema.
+ * Derives a deterministic session ID from the given inputs.
+ * Uses SHA-256 (truncated to 16 hex chars) when `node:crypto` is available,
+ * or a deterministic FNV-1a hash as a fallback in non-Node environments.
  *
  * @param apiKey - The project's API key (or anonymous placeholder).
  * @param origin - The origin string identifying the deployment environment.
@@ -253,6 +254,7 @@ declare function classifyFetchTarget(url: string): FetchTarget;
  * - The file does not exist
  * - The file content is invalid
  * - An I/O error occurs
+ * - `node:fs` is unavailable (non-Node environment)
  */
 declare function readAnonKey(projectRoot?: string): Promise<AnonApiKey | null>;
 /**
@@ -263,17 +265,20 @@ declare function readAnonKey(projectRoot?: string): Promise<AnonApiKey | null>;
  * - Writes the new key to `.glasstrace/anon_key`, creating the directory if needed
  * - On file write failure: logs a warning, caches an ephemeral in-memory key so
  *   repeated calls in the same process return the same key
+ * - In non-Node environments: returns an ephemeral in-memory key
  */
 declare function getOrCreateAnonKey(projectRoot?: string): Promise<AnonApiKey>;
 
 /**
  * Reads and validates a cached config file from `.glasstrace/config`.
- * Returns the parsed `SdkInitResponse` or `null` on any failure.
+ * Returns the parsed `SdkInitResponse` or `null` on any failure,
+ * including when `node:fs` is unavailable (non-Node environments).
  */
 declare function loadCachedConfig(projectRoot?: string): SdkInitResponse | null;
 /**
  * Persists the init response to `.glasstrace/config`.
- * On failure, logs a warning and continues.
+ * Silently skipped when `node:fs` is unavailable (non-Node environments).
+ * On I/O failure, logs a warning and continues.
  */
 declare function saveCachedConfig(response: SdkInitResponse, projectRoot?: string): Promise<void>;
 /**
@@ -314,6 +319,14 @@ declare function performInit(config: ResolvedConfig, anonKey: AnonApiKey | null,
  * every span export batch).
  */
 declare function getActiveConfig(): CaptureConfig;
+/**
+ * Returns the `linkedAccountId` from the current in-memory init response,
+ * or `undefined` if no init response is available or no account is linked.
+ *
+ * Used by the discovery endpoint to determine whether `claimed: true`
+ * should be included in the response.
+ */
+declare function getLinkedAccountId(): string | undefined;
 
 /**
  * Lightweight SpanProcessor that delegates to a wrapped processor.
@@ -417,6 +430,17 @@ declare class GlasstraceExporter implements SpanExporter {
     private flushPending;
 }
 
+/**
+ * Claim state returned by the `getClaimState` callback.
+ *
+ * - `claimed` — `true` when the anonymous key has been linked to an account.
+ * - `accountHint` — optional masked identifier (e.g. `"er***@example.com"`)
+ *   for the browser extension to display to the user.
+ */
+interface ClaimState {
+    claimed: boolean;
+    accountHint?: string;
+}
 /**
  * Creates a request handler for the `/__glasstrace/config` discovery endpoint.
  *
@@ -424,10 +448,14 @@ declare class GlasstraceExporter implements SpanExporter {
  * If not, returns `null` (pass-through). If it matches, returns a `DiscoveryResponse`
  * with the anonymous key and current session ID.
  *
+ * When `getClaimState` returns a non-null value with `claimed: true`, the
+ * response includes `claimed` and (optionally) `accountHint` so the browser
+ * extension can prompt the user to sign in.
+ *
  * The triple guard (anonymous + dev + active) is enforced by the caller,
  * not by this module. If the handler is registered, it serves.
  */
-declare function createDiscoveryHandler(getAnonKey: () => Promise<AnonApiKey | null>, getSessionId: () => SessionId): (request: Request) => Promise<Response | null>;
+declare function createDiscoveryHandler(getAnonKey: () => Promise<AnonApiKey | null>, getSessionId: () => SessionId, getClaimState?: () => ClaimState | null): (request: Request) => Promise<Response | null>;
 
 /**
  * The primary SDK entry point called by developers in their `instrumentation.ts`.
@@ -468,9 +496,29 @@ interface SourceMapEntry {
     filePath: string;
     content: string;
 }
+/**
+ * Metadata for a discovered source map file, without its content loaded.
+ * Used by the streaming upload flow to defer file reads until upload time.
+ */
+interface SourceMapFileInfo {
+    /** Relative path to the compiled JS file (`.map` extension stripped). */
+    filePath: string;
+    /** Absolute path on disk for reading the file content on demand. */
+    absolutePath: string;
+    /** File size in bytes. */
+    sizeBytes: number;
+}
+/**
+ * Recursively discovers all `.map` files in the given build directory.
+ * Returns metadata only — file content is NOT read into memory.
+ */
+declare function discoverSourceMapFiles(buildDir: string): Promise<SourceMapFileInfo[]>;
 /**
  * Recursively finds all .map files in the given build directory.
  * Returns relative paths and file contents.
+ *
+ * @deprecated Prefer {@link discoverSourceMapFiles} to avoid loading all
+ * source maps into memory simultaneously.
  */
 declare function collectSourceMaps(buildDir: string): Promise<SourceMapEntry[]>;
 /**
@@ -480,15 +528,24 @@ declare function collectSourceMaps(buildDir: string): Promise<SourceMapEntry[]>;
  * On failure, falls back to a deterministic content hash:
  * sort source map file paths alphabetically, concatenate each as
  * `{relativePath}\n{fileLength}\n{fileContent}`, then SHA-256 the result.
+ *
+ * Accepts either `SourceMapEntry[]` (legacy, in-memory) or
+ * `SourceMapFileInfo[]` (streaming, reads on demand).
  */
-declare function computeBuildHash(maps?: SourceMapEntry[]): Promise<string>;
+declare function computeBuildHash(maps?: SourceMapEntry[] | SourceMapFileInfo[]): Promise<string>;
 /**
  * Uploads source maps to the ingestion API.
  *
  * POSTs to `{endpoint}/v1/source-maps` with the API key, build hash,
  * and file entries. Validates the response against SourceMapUploadResponseSchema.
+ *
+ * Accepts either `SourceMapEntry[]` (legacy, in-memory) or
+ * `SourceMapFileInfo[]` (deferred reads). With `SourceMapFileInfo[]`,
+ * file content is read at upload time rather than at discovery time.
+ * Note: the legacy endpoint sends all files in a single JSON body, so
+ * peak memory is similar — the benefit is deferring reads past discovery.
  */
-declare function uploadSourceMaps(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[]): Promise<SourceMapUploadResponse>;
+declare function uploadSourceMaps(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[] | SourceMapFileInfo[]): Promise<SourceMapUploadResponse>;
 /** Builds at or above this byte size route to the presigned upload flow. */
 declare const PRESIGNED_THRESHOLD_BYTES = 4500000;
 /** Signature for the blob upload function, injectable for testing. */
@@ -500,13 +557,17 @@ type BlobUploader = (clientToken: string, pathname: string, content: string) =>
  * Orchestrates the 3-phase presigned upload flow.
  *
  * 1. Requests presigned tokens for all source map files
- * 2. Uploads each file to blob storage with a concurrency limit of 5
+ * 2. Uploads each file to blob storage with a concurrency limit of 5,
+ *    reading file content from disk just before each upload
  * 3. Submits the manifest to finalize the upload
  *
+ * Accepts either `SourceMapEntry[]` (legacy, in-memory) or
+ * `SourceMapFileInfo[]` (streaming, reads on demand).
+ *
  * Accepts an optional `blobUploader` for test injection; defaults to
  * {@link uploadToBlob}.
  */
-declare function uploadSourceMapsPresigned(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[], blobUploader?: BlobUploader): Promise<SourceMapManifestResponse>;
+declare function uploadSourceMapsPresigned(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[] | SourceMapFileInfo[], blobUploader?: BlobUploader): Promise<SourceMapManifestResponse>;
 /**
  * Options for {@link uploadSourceMapsAuto}, primarily used for test injection.
  */
@@ -524,8 +585,11 @@ interface AutoUploadOptions {
  * - At or above the threshold: checks if `@vercel/blob` is available and
  *   uses the presigned 3-phase flow. Falls back to legacy with a warning
  *   if the package is not installed.
+ *
+ * Accepts either `SourceMapEntry[]` (legacy, in-memory) or
+ * `SourceMapFileInfo[]` (streaming, reads on demand).
  */
-declare function uploadSourceMapsAuto(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[], options?: AutoUploadOptions): Promise<SourceMapUploadResponse | SourceMapManifestResponse>;
+declare function uploadSourceMapsAuto(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[] | SourceMapFileInfo[], options?: AutoUploadOptions): Promise<SourceMapUploadResponse | SourceMapManifestResponse>;
 
 /**
  * Manual error capture API.
@@ -588,4 +652,4 @@ declare function extractImports(fileContent: string): string[];
  */
 declare function buildImportGraph(projectRoot: string): Promise<ImportGraphPayload>;
 
-export { type AutoUploadOptions, type BlobUploader, type FetchTarget, GlasstraceExporter, type GlasstraceExporterOptions, GlasstraceSpanProcessor, type InitClaimResult, PRESIGNED_THRESHOLD_BYTES, 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, 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, deriveSessionId, discoverSourceMapFiles, discoverTestFiles, extractImports, getActiveConfig, getDateString, getDiscoveryHandler, getLinkedAccountId, getOrCreateAnonKey, getOrigin, isAnonymousMode, isProductionDisabled, loadCachedConfig, performInit, readAnonKey, readEnvVars, registerGlasstrace, resolveConfig, saveCachedConfig, sendInitRequest, uploadSourceMaps, uploadSourceMapsAuto, uploadSourceMapsPresigned, withGlasstraceConfig };

package/dist/index.d.ts

@@ -187,8 +187,9 @@ declare function isProductionDisabled(config: ResolvedConfig): boolean;
 declare function isAnonymousMode(config: ResolvedConfig): boolean;
 
 /**
- * Derives a deterministic session ID from the given inputs using SHA-256.
- * The hash is truncated to 16 hex characters and parsed through SessionIdSchema.
+ * Derives a deterministic session ID from the given inputs.
+ * Uses SHA-256 (truncated to 16 hex chars) when `node:crypto` is available,
+ * or a deterministic FNV-1a hash as a fallback in non-Node environments.
  *
  * @param apiKey - The project's API key (or anonymous placeholder).
  * @param origin - The origin string identifying the deployment environment.
@@ -253,6 +254,7 @@ declare function classifyFetchTarget(url: string): FetchTarget;
  * - The file does not exist
  * - The file content is invalid
  * - An I/O error occurs
+ * - `node:fs` is unavailable (non-Node environment)
  */
 declare function readAnonKey(projectRoot?: string): Promise<AnonApiKey | null>;
 /**
@@ -263,17 +265,20 @@ declare function readAnonKey(projectRoot?: string): Promise<AnonApiKey | null>;
  * - Writes the new key to `.glasstrace/anon_key`, creating the directory if needed
  * - On file write failure: logs a warning, caches an ephemeral in-memory key so
  *   repeated calls in the same process return the same key
+ * - In non-Node environments: returns an ephemeral in-memory key
  */
 declare function getOrCreateAnonKey(projectRoot?: string): Promise<AnonApiKey>;
 
 /**
  * Reads and validates a cached config file from `.glasstrace/config`.
- * Returns the parsed `SdkInitResponse` or `null` on any failure.
+ * Returns the parsed `SdkInitResponse` or `null` on any failure,
+ * including when `node:fs` is unavailable (non-Node environments).
  */
 declare function loadCachedConfig(projectRoot?: string): SdkInitResponse | null;
 /**
  * Persists the init response to `.glasstrace/config`.
- * On failure, logs a warning and continues.
+ * Silently skipped when `node:fs` is unavailable (non-Node environments).
+ * On I/O failure, logs a warning and continues.
  */
 declare function saveCachedConfig(response: SdkInitResponse, projectRoot?: string): Promise<void>;
 /**
@@ -314,6 +319,14 @@ declare function performInit(config: ResolvedConfig, anonKey: AnonApiKey | null,
  * every span export batch).
  */
 declare function getActiveConfig(): CaptureConfig;
+/**
+ * Returns the `linkedAccountId` from the current in-memory init response,
+ * or `undefined` if no init response is available or no account is linked.
+ *
+ * Used by the discovery endpoint to determine whether `claimed: true`
+ * should be included in the response.
+ */
+declare function getLinkedAccountId(): string | undefined;
 
 /**
  * Lightweight SpanProcessor that delegates to a wrapped processor.
@@ -417,6 +430,17 @@ declare class GlasstraceExporter implements SpanExporter {
     private flushPending;
 }
 
+/**
+ * Claim state returned by the `getClaimState` callback.
+ *
+ * - `claimed` — `true` when the anonymous key has been linked to an account.
+ * - `accountHint` — optional masked identifier (e.g. `"er***@example.com"`)
+ *   for the browser extension to display to the user.
+ */
+interface ClaimState {
+    claimed: boolean;
+    accountHint?: string;
+}
 /**
  * Creates a request handler for the `/__glasstrace/config` discovery endpoint.
  *
@@ -424,10 +448,14 @@ declare class GlasstraceExporter implements SpanExporter {
  * If not, returns `null` (pass-through). If it matches, returns a `DiscoveryResponse`
  * with the anonymous key and current session ID.
  *
+ * When `getClaimState` returns a non-null value with `claimed: true`, the
+ * response includes `claimed` and (optionally) `accountHint` so the browser
+ * extension can prompt the user to sign in.
+ *
  * The triple guard (anonymous + dev + active) is enforced by the caller,
  * not by this module. If the handler is registered, it serves.
  */
-declare function createDiscoveryHandler(getAnonKey: () => Promise<AnonApiKey | null>, getSessionId: () => SessionId): (request: Request) => Promise<Response | null>;
+declare function createDiscoveryHandler(getAnonKey: () => Promise<AnonApiKey | null>, getSessionId: () => SessionId, getClaimState?: () => ClaimState | null): (request: Request) => Promise<Response | null>;
 
 /**
  * The primary SDK entry point called by developers in their `instrumentation.ts`.
@@ -468,9 +496,29 @@ interface SourceMapEntry {
     filePath: string;
     content: string;
 }
+/**
+ * Metadata for a discovered source map file, without its content loaded.
+ * Used by the streaming upload flow to defer file reads until upload time.
+ */
+interface SourceMapFileInfo {
+    /** Relative path to the compiled JS file (`.map` extension stripped). */
+    filePath: string;
+    /** Absolute path on disk for reading the file content on demand. */
+    absolutePath: string;
+    /** File size in bytes. */
+    sizeBytes: number;
+}
+/**
+ * Recursively discovers all `.map` files in the given build directory.
+ * Returns metadata only — file content is NOT read into memory.
+ */
+declare function discoverSourceMapFiles(buildDir: string): Promise<SourceMapFileInfo[]>;
 /**
  * Recursively finds all .map files in the given build directory.
  * Returns relative paths and file contents.
+ *
+ * @deprecated Prefer {@link discoverSourceMapFiles} to avoid loading all
+ * source maps into memory simultaneously.
  */
 declare function collectSourceMaps(buildDir: string): Promise<SourceMapEntry[]>;
 /**
@@ -480,15 +528,24 @@ declare function collectSourceMaps(buildDir: string): Promise<SourceMapEntry[]>;
  * On failure, falls back to a deterministic content hash:
  * sort source map file paths alphabetically, concatenate each as
  * `{relativePath}\n{fileLength}\n{fileContent}`, then SHA-256 the result.
+ *
+ * Accepts either `SourceMapEntry[]` (legacy, in-memory) or
+ * `SourceMapFileInfo[]` (streaming, reads on demand).
  */
-declare function computeBuildHash(maps?: SourceMapEntry[]): Promise<string>;
+declare function computeBuildHash(maps?: SourceMapEntry[] | SourceMapFileInfo[]): Promise<string>;
 /**
  * Uploads source maps to the ingestion API.
  *
  * POSTs to `{endpoint}/v1/source-maps` with the API key, build hash,
  * and file entries. Validates the response against SourceMapUploadResponseSchema.
+ *
+ * Accepts either `SourceMapEntry[]` (legacy, in-memory) or
+ * `SourceMapFileInfo[]` (deferred reads). With `SourceMapFileInfo[]`,
+ * file content is read at upload time rather than at discovery time.
+ * Note: the legacy endpoint sends all files in a single JSON body, so
+ * peak memory is similar — the benefit is deferring reads past discovery.
  */
-declare function uploadSourceMaps(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[]): Promise<SourceMapUploadResponse>;
+declare function uploadSourceMaps(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[] | SourceMapFileInfo[]): Promise<SourceMapUploadResponse>;
 /** Builds at or above this byte size route to the presigned upload flow. */
 declare const PRESIGNED_THRESHOLD_BYTES = 4500000;
 /** Signature for the blob upload function, injectable for testing. */
@@ -500,13 +557,17 @@ type BlobUploader = (clientToken: string, pathname: string, content: string) =>
  * Orchestrates the 3-phase presigned upload flow.
  *
  * 1. Requests presigned tokens for all source map files
- * 2. Uploads each file to blob storage with a concurrency limit of 5
+ * 2. Uploads each file to blob storage with a concurrency limit of 5,
+ *    reading file content from disk just before each upload
  * 3. Submits the manifest to finalize the upload
  *
+ * Accepts either `SourceMapEntry[]` (legacy, in-memory) or
+ * `SourceMapFileInfo[]` (streaming, reads on demand).
+ *
  * Accepts an optional `blobUploader` for test injection; defaults to
  * {@link uploadToBlob}.
  */
-declare function uploadSourceMapsPresigned(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[], blobUploader?: BlobUploader): Promise<SourceMapManifestResponse>;
+declare function uploadSourceMapsPresigned(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[] | SourceMapFileInfo[], blobUploader?: BlobUploader): Promise<SourceMapManifestResponse>;
 /**
  * Options for {@link uploadSourceMapsAuto}, primarily used for test injection.
  */
@@ -524,8 +585,11 @@ interface AutoUploadOptions {
  * - At or above the threshold: checks if `@vercel/blob` is available and
  *   uses the presigned 3-phase flow. Falls back to legacy with a warning
  *   if the package is not installed.
+ *
+ * Accepts either `SourceMapEntry[]` (legacy, in-memory) or
+ * `SourceMapFileInfo[]` (streaming, reads on demand).
  */
-declare function uploadSourceMapsAuto(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[], options?: AutoUploadOptions): Promise<SourceMapUploadResponse | SourceMapManifestResponse>;
+declare function uploadSourceMapsAuto(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[] | SourceMapFileInfo[], options?: AutoUploadOptions): Promise<SourceMapUploadResponse | SourceMapManifestResponse>;
 
 /**
  * Manual error capture API.
@@ -588,4 +652,4 @@ declare function extractImports(fileContent: string): string[];
  */
 declare function buildImportGraph(projectRoot: string): Promise<ImportGraphPayload>;
 
-export { type AutoUploadOptions, type BlobUploader, type FetchTarget, GlasstraceExporter, type GlasstraceExporterOptions, GlasstraceSpanProcessor, type InitClaimResult, PRESIGNED_THRESHOLD_BYTES, 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, 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, deriveSessionId, discoverSourceMapFiles, discoverTestFiles, extractImports, getActiveConfig, getDateString, getDiscoveryHandler, getLinkedAccountId, getOrCreateAnonKey, getOrigin, isAnonymousMode, isProductionDisabled, loadCachedConfig, performInit, readAnonKey, readEnvVars, registerGlasstrace, resolveConfig, saveCachedConfig, sendInitRequest, uploadSourceMaps, uploadSourceMapsAuto, uploadSourceMapsPresigned, withGlasstraceConfig };