@glasstrace/sdk 0.20.0 → 1.0.0

package/dist/index.d-CYYe3PxB.d.cts

@@ -0,0 +1,191 @@
+import * as z from './v4/classic/external.cjs';
+
+/**
+ * Anonymous API key: `gt_anon_` + 48 hex chars.
+ *
+ * @drift-check ../glasstrace-product/docs/component-designs/sdk-2.0.md §1.2 Lens B — SDK-Facing Security Primitives (row `Anon API key gt_anon_[a-f0-9]{48}`)
+ */
+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).
+ *
+ * @drift-check ../glasstrace-product/docs/product-spec.md §4.5 Session Lifecycle
+ */
+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>>;
+    errorResponseBodies: 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)
+ * - Presigned source map upload (POST /v1/source-maps/presign, POST /v1/source-maps/manifest)
+ */
+
+/** 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>>;
+        errorResponseBodies: 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>;
+    claimResult: z.ZodOptional<z.ZodObject<{
+        newApiKey: z.core.$ZodBranded<z.ZodString, "DevApiKey", "out">;
+        accountId: z.ZodString;
+        graceExpiresAt: 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>;
+/** Response confirming source map manifest activation. */
+declare const SourceMapManifestResponseSchema: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    buildHash: z.core.$ZodBranded<z.ZodString, "BuildHash", "out">;
+    fileCount: z.ZodNumber;
+    totalSizeBytes: z.ZodNumber;
+    activatedAt: z.ZodNumber;
+}, z.core.$strip>;
+type SourceMapManifestResponse = z.infer<typeof SourceMapManifestResponseSchema>;
+
+/**
+ * Session ID derivation — part of the public Glasstrace wire contract.
+ *
+ * Deriving the session ID is deterministic: given the same inputs,
+ * every runtime that implements this module produces the same
+ * 16-character hex identifier. That determinism is the contract — it
+ * lets independent clients (SDK, browser extension, server tooling)
+ * agree on the same session without coordination.
+ *
+ * This module is pure: it has no module-level state and no
+ * runtime-dependent branches. It is safe to import from Node 20+,
+ * modern browsers, Vercel Edge, and Cloudflare Workers. The SHA-256
+ * implementation is pure JavaScript; no `node:crypto`, no Web Crypto,
+ * no bundler-specific shims.
+ */
+
+/**
+ * Derives a deterministic session ID from the inputs that define a
+ * Glasstrace session. The output is a 16-character lowercase hex
+ * string validated through {@link SessionIdSchema}.
+ *
+ * This function is part of the Glasstrace wire contract: any consumer
+ * (SDK, browser extension, server tooling) that calls it with the same
+ * arguments receives the same `SessionId`. That property is what lets
+ * independent clients agree on a session without coordination.
+ *
+ * Uses a pure-JavaScript SHA-256 so the output is identical across
+ * every runtime this package supports (Node 20+, modern browsers,
+ * Vercel Edge, Cloudflare Workers).
+ *
+ * Security note: the session ID is an **identifier**, not a secret or
+ * an authentication token. It is never used for authorization.
+ *
+ * @param apiKey - The project's API key (or anonymous placeholder).
+ * @param origin - The origin string identifying the deployment
+ *   environment (for example `localhost:3000` or `production`).
+ * @param date - UTC date as `YYYY-MM-DD`.
+ * @param windowIndex - Zero-based index of the 4-hour activity window
+ *   within the day.
+ * @returns A 16-character hex {@link SessionId}.
+ *
+ * @drift-check ../glasstrace-product/docs/product-spec.md §4.5 Session Lifecycle
+ */
+declare function deriveSessionId(apiKey: string, origin: string, date: string, windowIndex: number): SessionId;
+
+export { type AnonApiKey as A, type CaptureConfig as C, type GlasstraceEnvVars as G, type ImportGraphPayload as I, type SdkInitResponse as S, type GlasstraceOptions as a, type SdkHealthReport as b, type SdkDiagnosticCode as c, deriveSessionId as d, type SessionId as e, type SourceMapUploadResponse as f, type SourceMapManifestResponse as g };

package/dist/index.d-CYYe3PxB.d.ts

@@ -0,0 +1,191 @@
+import * as z from './v4/classic/external.cjs';
+
+/**
+ * Anonymous API key: `gt_anon_` + 48 hex chars.
+ *
+ * @drift-check ../glasstrace-product/docs/component-designs/sdk-2.0.md §1.2 Lens B — SDK-Facing Security Primitives (row `Anon API key gt_anon_[a-f0-9]{48}`)
+ */
+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).
+ *
+ * @drift-check ../glasstrace-product/docs/product-spec.md §4.5 Session Lifecycle
+ */
+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>>;
+    errorResponseBodies: 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)
+ * - Presigned source map upload (POST /v1/source-maps/presign, POST /v1/source-maps/manifest)
+ */
+
+/** 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>>;
+        errorResponseBodies: 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>;
+    claimResult: z.ZodOptional<z.ZodObject<{
+        newApiKey: z.core.$ZodBranded<z.ZodString, "DevApiKey", "out">;
+        accountId: z.ZodString;
+        graceExpiresAt: 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>;
+/** Response confirming source map manifest activation. */
+declare const SourceMapManifestResponseSchema: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    buildHash: z.core.$ZodBranded<z.ZodString, "BuildHash", "out">;
+    fileCount: z.ZodNumber;
+    totalSizeBytes: z.ZodNumber;
+    activatedAt: z.ZodNumber;
+}, z.core.$strip>;
+type SourceMapManifestResponse = z.infer<typeof SourceMapManifestResponseSchema>;
+
+/**
+ * Session ID derivation — part of the public Glasstrace wire contract.
+ *
+ * Deriving the session ID is deterministic: given the same inputs,
+ * every runtime that implements this module produces the same
+ * 16-character hex identifier. That determinism is the contract — it
+ * lets independent clients (SDK, browser extension, server tooling)
+ * agree on the same session without coordination.
+ *
+ * This module is pure: it has no module-level state and no
+ * runtime-dependent branches. It is safe to import from Node 20+,
+ * modern browsers, Vercel Edge, and Cloudflare Workers. The SHA-256
+ * implementation is pure JavaScript; no `node:crypto`, no Web Crypto,
+ * no bundler-specific shims.
+ */
+
+/**
+ * Derives a deterministic session ID from the inputs that define a
+ * Glasstrace session. The output is a 16-character lowercase hex
+ * string validated through {@link SessionIdSchema}.
+ *
+ * This function is part of the Glasstrace wire contract: any consumer
+ * (SDK, browser extension, server tooling) that calls it with the same
+ * arguments receives the same `SessionId`. That property is what lets
+ * independent clients agree on a session without coordination.
+ *
+ * Uses a pure-JavaScript SHA-256 so the output is identical across
+ * every runtime this package supports (Node 20+, modern browsers,
+ * Vercel Edge, Cloudflare Workers).
+ *
+ * Security note: the session ID is an **identifier**, not a secret or
+ * an authentication token. It is never used for authorization.
+ *
+ * @param apiKey - The project's API key (or anonymous placeholder).
+ * @param origin - The origin string identifying the deployment
+ *   environment (for example `localhost:3000` or `production`).
+ * @param date - UTC date as `YYYY-MM-DD`.
+ * @param windowIndex - Zero-based index of the 4-hour activity window
+ *   within the day.
+ * @returns A 16-character hex {@link SessionId}.
+ *
+ * @drift-check ../glasstrace-product/docs/product-spec.md §4.5 Session Lifecycle
+ */
+declare function deriveSessionId(apiKey: string, origin: string, date: string, windowIndex: number): SessionId;
+
+export { type AnonApiKey as A, type CaptureConfig as C, type GlasstraceEnvVars as G, type ImportGraphPayload as I, type SdkInitResponse as S, type GlasstraceOptions as a, type SdkHealthReport as b, type SdkDiagnosticCode as c, deriveSessionId as d, type SessionId as e, type SourceMapUploadResponse as f, type SourceMapManifestResponse as g };