@glasstrace/sdk 0.2.0 → 0.2.3

package/dist/index.d.cts

@@ -1,7 +1,127 @@
-import { SdkDiagnosticCode, GlasstraceEnvVars, GlasstraceOptions, SessionId, AnonApiKey, CaptureConfig, SdkInitResponse, ImportGraphPayload, SdkHealthReport, SourceMapUploadResponse } from '@glasstrace/protocol';
-import { Context } from '@opentelemetry/api';
-import { SpanProcessor, Span, ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
-import { ExportResult } from '@opentelemetry/core';
+import * as z from './v4/classic/external.cjs';
+import { ReadableSpan } from './export/ReadableSpan';
+import { Span } from './Span';
+import { SpanProcessor } from './SpanProcessor';
+import { SpanExporter } from './export/SpanExporter';
+import { ExportResult } from './ExportResult';
+
+/** Anonymous API key: `gt_anon_` + 48 hex chars. */
+declare const AnonApiKeySchema: z.core.$ZodBranded<z.ZodString, "AnonApiKey", "out">;
+type AnonApiKey = z.infer<typeof AnonApiKeySchema>;
+/** Session ID: 16 hex chars (deterministic, derived from API key + time window). */
+declare const SessionIdSchema: z.core.$ZodBranded<z.ZodString, "SessionId", "out">;
+type SessionId = z.infer<typeof SessionIdSchema>;
+
+/**
+ * SDK-specific enums.
+ */
+
+/** Diagnostic codes the SDK can report during health checks. */
+declare const SdkDiagnosticCodeSchema: z.ZodEnum<{
+    ingestion_unreachable: "ingestion_unreachable";
+    ingestion_auth_failed: "ingestion_auth_failed";
+    ingestion_rate_limited: "ingestion_rate_limited";
+    config_sync_failed: "config_sync_failed";
+    source_map_upload_failed: "source_map_upload_failed";
+}>;
+type SdkDiagnosticCode = z.infer<typeof SdkDiagnosticCodeSchema>;
+
+/**
+ * SDK configuration types.
+ */
+
+/** SDK capture configuration: which events to capture. */
+declare const CaptureConfigSchema: z.ZodObject<{
+    requestBodies: z.ZodBoolean;
+    queryParamValues: z.ZodBoolean;
+    envVarValues: z.ZodBoolean;
+    fullConsoleOutput: z.ZodBoolean;
+    importGraph: z.ZodBoolean;
+    consoleErrors: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+type CaptureConfig = z.infer<typeof CaptureConfigSchema>;
+/** Developer-facing config for registerGlasstrace(). */
+declare const GlasstraceOptionsSchema: z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    forceEnable: z.ZodOptional<z.ZodBoolean>;
+    verbose: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type GlasstraceOptions = z.infer<typeof GlasstraceOptionsSchema>;
+/** All recognized SDK environment variables. */
+declare const GlasstraceEnvVarsSchema: z.ZodObject<{
+    GLASSTRACE_API_KEY: z.ZodOptional<z.ZodString>;
+    GLASSTRACE_FORCE_ENABLE: z.ZodOptional<z.ZodString>;
+    GLASSTRACE_ENV: z.ZodOptional<z.ZodString>;
+    GLASSTRACE_COVERAGE_MAP: z.ZodOptional<z.ZodString>;
+    NODE_ENV: z.ZodOptional<z.ZodString>;
+    VERCEL_ENV: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type GlasstraceEnvVars = z.infer<typeof GlasstraceEnvVarsSchema>;
+
+/**
+ * Wire format types for SDK ↔ backend communication.
+ *
+ * These schemas define the request/response shapes for:
+ * - SDK initialization (POST /v1/sdk/init)
+ * - SDK health diagnostics (embedded in init requests)
+ * - Discovery endpoint (GET /__glasstrace/config)
+ * - Source map upload (POST /v1/source-maps)
+ */
+
+/** Test file import relationships, embedded in SDK init request. */
+declare const ImportGraphPayloadSchema: z.ZodObject<{
+    buildHash: z.core.$ZodBranded<z.ZodString, "BuildHash", "out">;
+    graph: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type ImportGraphPayload = z.infer<typeof ImportGraphPayloadSchema>;
+/** SDK health diagnostics included in init requests. */
+declare const SdkHealthReportSchema: z.ZodObject<{
+    tracesExportedSinceLastInit: z.ZodNumber;
+    tracesDropped: z.ZodNumber;
+    initFailures: z.ZodNumber;
+    configAge: z.ZodNumber;
+    sdkVersion: z.ZodString;
+}, z.core.$strip>;
+type SdkHealthReport = z.infer<typeof SdkHealthReportSchema>;
+/**
+ * Response from POST /v1/sdk/init.
+ *
+ * Note: SdkInitRequest is intentionally NOT in the protocol package.
+ * The request schema includes backend-specific types (TierLimits,
+ * SubscriptionStatus) that are not part of the public contract.
+ * The backend owns the request validation; the SDK only needs to
+ * understand the response.
+ */
+declare const SdkInitResponseSchema: z.ZodObject<{
+    config: z.ZodObject<{
+        requestBodies: z.ZodBoolean;
+        queryParamValues: z.ZodBoolean;
+        envVarValues: z.ZodBoolean;
+        fullConsoleOutput: z.ZodBoolean;
+        importGraph: z.ZodBoolean;
+        consoleErrors: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, z.core.$strip>;
+    subscriptionStatus: z.ZodString;
+    linkedAccountId: z.ZodOptional<z.ZodString>;
+    minimumSdkVersion: z.ZodString;
+    apiVersion: z.ZodString;
+    tierLimits: z.ZodObject<{
+        tracesPerMinute: z.ZodNumber;
+        storageTtlHours: z.ZodNumber;
+        maxTraceSizeBytes: z.ZodNumber;
+        maxConcurrentSessions: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type SdkInitResponse = z.infer<typeof SdkInitResponseSchema>;
+/** Response from POST /v1/source-maps. */
+declare const SourceMapUploadResponseSchema: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    buildHash: z.core.$ZodBranded<z.ZodString, "BuildHash", "out">;
+    fileCount: z.ZodNumber;
+    totalSizeBytes: z.ZodNumber;
+}, z.core.$strip>;
+type SourceMapUploadResponse = z.infer<typeof SourceMapUploadResponseSchema>;
 
 /**
  * Internal SDK error class with a typed diagnostic code.
@@ -180,7 +300,7 @@ declare function getActiveConfig(): CaptureConfig;
 declare class GlasstraceSpanProcessor implements SpanProcessor {
     private readonly wrappedProcessor;
     constructor(wrappedProcessor: SpanProcessor, _sessionManager?: SessionManager, _apiKey?: string | (() => string), _getConfig?: () => CaptureConfig, _environment?: string);
-    onStart(span: Span, parentContext: Context): void;
+    onStart(span: Span, parentContext: Parameters<SpanProcessor["onStart"]>[1]): void;
     onEnd(readableSpan: ReadableSpan): void;
     shutdown(): Promise<void>;
     forceFlush(): Promise<void>;
@@ -334,6 +454,12 @@ declare function computeBuildHash(maps?: SourceMapEntry[]): Promise<string>;
  */
 declare function uploadSourceMaps(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[]): Promise<SourceMapUploadResponse>;
 
+/**
+ * Manual error capture API.
+ *
+ * Provides a simple function for developers to manually record errors
+ * as span events, independent of the `consoleErrors` config flag.
+ */
 /**
  * Records an error as a span event on the currently active OTel span.
  *

package/dist/index.d.ts

@@ -1,7 +1,127 @@
-import { SdkDiagnosticCode, GlasstraceEnvVars, GlasstraceOptions, SessionId, AnonApiKey, CaptureConfig, SdkInitResponse, ImportGraphPayload, SdkHealthReport, SourceMapUploadResponse } from '@glasstrace/protocol';
-import { Context } from '@opentelemetry/api';
-import { SpanProcessor, Span, ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
-import { ExportResult } from '@opentelemetry/core';
+import * as z from './v4/classic/external.cjs';
+import { ReadableSpan } from './export/ReadableSpan';
+import { Span } from './Span';
+import { SpanProcessor } from './SpanProcessor';
+import { SpanExporter } from './export/SpanExporter';
+import { ExportResult } from './ExportResult';
+
+/** Anonymous API key: `gt_anon_` + 48 hex chars. */
+declare const AnonApiKeySchema: z.core.$ZodBranded<z.ZodString, "AnonApiKey", "out">;
+type AnonApiKey = z.infer<typeof AnonApiKeySchema>;
+/** Session ID: 16 hex chars (deterministic, derived from API key + time window). */
+declare const SessionIdSchema: z.core.$ZodBranded<z.ZodString, "SessionId", "out">;
+type SessionId = z.infer<typeof SessionIdSchema>;
+
+/**
+ * SDK-specific enums.
+ */
+
+/** Diagnostic codes the SDK can report during health checks. */
+declare const SdkDiagnosticCodeSchema: z.ZodEnum<{
+    ingestion_unreachable: "ingestion_unreachable";
+    ingestion_auth_failed: "ingestion_auth_failed";
+    ingestion_rate_limited: "ingestion_rate_limited";
+    config_sync_failed: "config_sync_failed";
+    source_map_upload_failed: "source_map_upload_failed";
+}>;
+type SdkDiagnosticCode = z.infer<typeof SdkDiagnosticCodeSchema>;
+
+/**
+ * SDK configuration types.
+ */
+
+/** SDK capture configuration: which events to capture. */
+declare const CaptureConfigSchema: z.ZodObject<{
+    requestBodies: z.ZodBoolean;
+    queryParamValues: z.ZodBoolean;
+    envVarValues: z.ZodBoolean;
+    fullConsoleOutput: z.ZodBoolean;
+    importGraph: z.ZodBoolean;
+    consoleErrors: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, z.core.$strip>;
+type CaptureConfig = z.infer<typeof CaptureConfigSchema>;
+/** Developer-facing config for registerGlasstrace(). */
+declare const GlasstraceOptionsSchema: z.ZodObject<{
+    apiKey: z.ZodOptional<z.ZodString>;
+    endpoint: z.ZodOptional<z.ZodString>;
+    forceEnable: z.ZodOptional<z.ZodBoolean>;
+    verbose: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+type GlasstraceOptions = z.infer<typeof GlasstraceOptionsSchema>;
+/** All recognized SDK environment variables. */
+declare const GlasstraceEnvVarsSchema: z.ZodObject<{
+    GLASSTRACE_API_KEY: z.ZodOptional<z.ZodString>;
+    GLASSTRACE_FORCE_ENABLE: z.ZodOptional<z.ZodString>;
+    GLASSTRACE_ENV: z.ZodOptional<z.ZodString>;
+    GLASSTRACE_COVERAGE_MAP: z.ZodOptional<z.ZodString>;
+    NODE_ENV: z.ZodOptional<z.ZodString>;
+    VERCEL_ENV: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type GlasstraceEnvVars = z.infer<typeof GlasstraceEnvVarsSchema>;
+
+/**
+ * Wire format types for SDK ↔ backend communication.
+ *
+ * These schemas define the request/response shapes for:
+ * - SDK initialization (POST /v1/sdk/init)
+ * - SDK health diagnostics (embedded in init requests)
+ * - Discovery endpoint (GET /__glasstrace/config)
+ * - Source map upload (POST /v1/source-maps)
+ */
+
+/** Test file import relationships, embedded in SDK init request. */
+declare const ImportGraphPayloadSchema: z.ZodObject<{
+    buildHash: z.core.$ZodBranded<z.ZodString, "BuildHash", "out">;
+    graph: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type ImportGraphPayload = z.infer<typeof ImportGraphPayloadSchema>;
+/** SDK health diagnostics included in init requests. */
+declare const SdkHealthReportSchema: z.ZodObject<{
+    tracesExportedSinceLastInit: z.ZodNumber;
+    tracesDropped: z.ZodNumber;
+    initFailures: z.ZodNumber;
+    configAge: z.ZodNumber;
+    sdkVersion: z.ZodString;
+}, z.core.$strip>;
+type SdkHealthReport = z.infer<typeof SdkHealthReportSchema>;
+/**
+ * Response from POST /v1/sdk/init.
+ *
+ * Note: SdkInitRequest is intentionally NOT in the protocol package.
+ * The request schema includes backend-specific types (TierLimits,
+ * SubscriptionStatus) that are not part of the public contract.
+ * The backend owns the request validation; the SDK only needs to
+ * understand the response.
+ */
+declare const SdkInitResponseSchema: z.ZodObject<{
+    config: z.ZodObject<{
+        requestBodies: z.ZodBoolean;
+        queryParamValues: z.ZodBoolean;
+        envVarValues: z.ZodBoolean;
+        fullConsoleOutput: z.ZodBoolean;
+        importGraph: z.ZodBoolean;
+        consoleErrors: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    }, z.core.$strip>;
+    subscriptionStatus: z.ZodString;
+    linkedAccountId: z.ZodOptional<z.ZodString>;
+    minimumSdkVersion: z.ZodString;
+    apiVersion: z.ZodString;
+    tierLimits: z.ZodObject<{
+        tracesPerMinute: z.ZodNumber;
+        storageTtlHours: z.ZodNumber;
+        maxTraceSizeBytes: z.ZodNumber;
+        maxConcurrentSessions: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+type SdkInitResponse = z.infer<typeof SdkInitResponseSchema>;
+/** Response from POST /v1/source-maps. */
+declare const SourceMapUploadResponseSchema: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    buildHash: z.core.$ZodBranded<z.ZodString, "BuildHash", "out">;
+    fileCount: z.ZodNumber;
+    totalSizeBytes: z.ZodNumber;
+}, z.core.$strip>;
+type SourceMapUploadResponse = z.infer<typeof SourceMapUploadResponseSchema>;
 
 /**
  * Internal SDK error class with a typed diagnostic code.
@@ -180,7 +300,7 @@ declare function getActiveConfig(): CaptureConfig;
 declare class GlasstraceSpanProcessor implements SpanProcessor {
     private readonly wrappedProcessor;
     constructor(wrappedProcessor: SpanProcessor, _sessionManager?: SessionManager, _apiKey?: string | (() => string), _getConfig?: () => CaptureConfig, _environment?: string);
-    onStart(span: Span, parentContext: Context): void;
+    onStart(span: Span, parentContext: Parameters<SpanProcessor["onStart"]>[1]): void;
     onEnd(readableSpan: ReadableSpan): void;
     shutdown(): Promise<void>;
     forceFlush(): Promise<void>;
@@ -334,6 +454,12 @@ declare function computeBuildHash(maps?: SourceMapEntry[]): Promise<string>;
  */
 declare function uploadSourceMaps(apiKey: string, endpoint: string, buildHash: string, maps: SourceMapEntry[]): Promise<SourceMapUploadResponse>;
 
+/**
+ * Manual error capture API.
+ *
+ * Provides a simple function for developers to manually record errors
+ * as span events, independent of the `consoleErrors` config flag.
+ */
 /**
  * Records an error as a span event on the currently active OTel span.
  *