@glasstrace/sdk 0.20.0 → 1.0.0

package/dist/edge-entry-CFq085RZ.d.ts

@@ -0,0 +1,130 @@
+import { c as SdkDiagnosticCode, e as SessionId, C as CaptureConfig } from './index.d-CYYe3PxB.js';
+import { ReadableSpan } from './export/ReadableSpan';
+import { Span } from './Span';
+import { SpanProcessor } from './SpanProcessor';
+
+/**
+ * Internal SDK error class with a typed diagnostic code.
+ * Caught at the boundary and converted to a log message + diagnostic entry.
+ * Never thrown to the developer.
+ */
+declare class SdkError extends Error {
+    readonly code: SdkDiagnosticCode;
+    constructor(code: SdkDiagnosticCode, message: string, cause?: Error);
+}
+
+/**
+ * Returns the origin string for the current process.
+ * If GLASSTRACE_ENV is set, returns that value.
+ * Otherwise returns `localhost:{PORT}` (PORT defaults to 3000).
+ *
+ * @returns The origin string used as a session derivation input.
+ */
+declare function getOrigin(): string;
+/**
+ * Returns the current UTC date as a YYYY-MM-DD string.
+ *
+ * @returns The UTC date formatted as "YYYY-MM-DD".
+ */
+declare function getDateString(): string;
+/**
+ * Tracks the current session state with 4-hour window tracking.
+ * Instantiated once by the orchestrator.
+ */
+declare class SessionManager {
+    private windowIndex;
+    private lastActivityTimestamp;
+    private lastDate;
+    private lastApiKey;
+    private currentSessionId;
+    /**
+     * Returns the current session ID, deriving a new one if:
+     * - More than 4 hours have elapsed since last activity
+     * - The UTC date has changed (resets window index to 0)
+     * - The API key has changed (e.g., deferred anonymous key swap)
+     * - This is the first call
+     *
+     * @param apiKey - The project's API key used in session derivation.
+     * @returns The current or newly derived SessionId.
+     */
+    getSessionId(apiKey: string): SessionId;
+}
+
+/**
+ * Lightweight SpanProcessor that delegates to a wrapped processor.
+ *
+ * All glasstrace.* attribute enrichment has been moved to {@link GlasstraceExporter}
+ * (see enriching-exporter.ts), which enriches spans at export time. This resolves:
+ * - Cold-start spans are buffered in the exporter, not dropped
+ * - Vercel's CompositeSpanProcessor skips onEnding(); the exporter doesn't need it
+ * - Session ID is computed at export time with the resolved API key
+ *
+ * This class is retained for backward compatibility. New code should use
+ * GlasstraceExporter directly.
+ *
+ * @deprecated Use GlasstraceExporter for span enrichment. This processor is now a pass-through.
+ */
+declare class GlasstraceSpanProcessor implements SpanProcessor {
+    private readonly wrappedProcessor;
+    constructor(wrappedProcessor: SpanProcessor, _sessionManager?: SessionManager, _apiKey?: string | (() => string), _getConfig?: () => CaptureConfig, _environment?: string);
+    onStart(span: Span, parentContext: Parameters<SpanProcessor["onStart"]>[1]): void;
+    onEnd(readableSpan: ReadableSpan): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<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;
+
+export { type CorrelationIdRequest as C, GlasstraceSpanProcessor as G, SdkError as S, SessionManager as a, getOrigin as b, captureCorrelationId as c, getDateString as g };

package/dist/edge-entry-DYl05SJ-.d.cts

@@ -0,0 +1,130 @@
+import { c as SdkDiagnosticCode, e as SessionId, C as CaptureConfig } from './index.d-CYYe3PxB.cjs';
+import { ReadableSpan } from './export/ReadableSpan';
+import { Span } from './Span';
+import { SpanProcessor } from './SpanProcessor';
+
+/**
+ * Internal SDK error class with a typed diagnostic code.
+ * Caught at the boundary and converted to a log message + diagnostic entry.
+ * Never thrown to the developer.
+ */
+declare class SdkError extends Error {
+    readonly code: SdkDiagnosticCode;
+    constructor(code: SdkDiagnosticCode, message: string, cause?: Error);
+}
+
+/**
+ * Returns the origin string for the current process.
+ * If GLASSTRACE_ENV is set, returns that value.
+ * Otherwise returns `localhost:{PORT}` (PORT defaults to 3000).
+ *
+ * @returns The origin string used as a session derivation input.
+ */
+declare function getOrigin(): string;
+/**
+ * Returns the current UTC date as a YYYY-MM-DD string.
+ *
+ * @returns The UTC date formatted as "YYYY-MM-DD".
+ */
+declare function getDateString(): string;
+/**
+ * Tracks the current session state with 4-hour window tracking.
+ * Instantiated once by the orchestrator.
+ */
+declare class SessionManager {
+    private windowIndex;
+    private lastActivityTimestamp;
+    private lastDate;
+    private lastApiKey;
+    private currentSessionId;
+    /**
+     * Returns the current session ID, deriving a new one if:
+     * - More than 4 hours have elapsed since last activity
+     * - The UTC date has changed (resets window index to 0)
+     * - The API key has changed (e.g., deferred anonymous key swap)
+     * - This is the first call
+     *
+     * @param apiKey - The project's API key used in session derivation.
+     * @returns The current or newly derived SessionId.
+     */
+    getSessionId(apiKey: string): SessionId;
+}
+
+/**
+ * Lightweight SpanProcessor that delegates to a wrapped processor.
+ *
+ * All glasstrace.* attribute enrichment has been moved to {@link GlasstraceExporter}
+ * (see enriching-exporter.ts), which enriches spans at export time. This resolves:
+ * - Cold-start spans are buffered in the exporter, not dropped
+ * - Vercel's CompositeSpanProcessor skips onEnding(); the exporter doesn't need it
+ * - Session ID is computed at export time with the resolved API key
+ *
+ * This class is retained for backward compatibility. New code should use
+ * GlasstraceExporter directly.
+ *
+ * @deprecated Use GlasstraceExporter for span enrichment. This processor is now a pass-through.
+ */
+declare class GlasstraceSpanProcessor implements SpanProcessor {
+    private readonly wrappedProcessor;
+    constructor(wrappedProcessor: SpanProcessor, _sessionManager?: SessionManager, _apiKey?: string | (() => string), _getConfig?: () => CaptureConfig, _environment?: string);
+    onStart(span: Span, parentContext: Parameters<SpanProcessor["onStart"]>[1]): void;
+    onEnd(readableSpan: ReadableSpan): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<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;
+
+export { type CorrelationIdRequest as C, GlasstraceSpanProcessor as G, SdkError as S, SessionManager as a, getOrigin as b, captureCorrelationId as c, getDateString as g };