@glimt.dev/otel-browser 0.1.0

package/dist/types/exporters/config.d.ts

@@ -0,0 +1,8 @@
+/**
+ * OTLP exporter configuration.
+ */
+export interface OTLPExporterConfig {
+    headers?: Record<string, string>;
+    url?: string;
+    credentials?: RequestCredentials;
+}

package/dist/types/exporters/exporter-logs-otlp-http-fetch.d.ts

@@ -0,0 +1,14 @@
+import type { LogRecordExporter, ReadableLogRecord } from '@opentelemetry/sdk-logs';
+import type { ExportResult } from '@opentelemetry/core';
+import type { OTLPExporterConfig } from './config';
+/**
+ * OTLP exporter for logs over the `http/json` protocol. Browser-compatible.
+ */
+export declare class OTLPHttpJsonLogsExporter implements LogRecordExporter {
+    /** @ignore */
+    private readonly impl;
+    constructor(config?: OTLPExporterConfig, traceUrlForDerivation?: string);
+    export(records: ReadableLogRecord[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}

package/dist/types/exporters/exporter-logs-otlp-proto-fetch.d.ts

@@ -0,0 +1,14 @@
+import type { LogRecordExporter, ReadableLogRecord } from '@opentelemetry/sdk-logs';
+import type { ExportResult } from '@opentelemetry/core';
+import type { OTLPExporterConfig } from './config';
+/**
+ * OTLP exporter for logs over the `http/protobuf` protocol. Browser-compatible.
+ */
+export declare class OTLPHttpProtoLogsExporter implements LogRecordExporter {
+    /** @ignore */
+    private readonly impl;
+    constructor(config?: OTLPExporterConfig, traceUrlForDerivation?: string);
+    export(records: ReadableLogRecord[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}

package/dist/types/exporters/exporter-trace-otlp-http-fetch.d.ts

@@ -0,0 +1,17 @@
+import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
+import type { ExportResult } from '@opentelemetry/core';
+import type { OTLPExporterConfig } from './config';
+/**
+ * OTLP exporter for the `http/json` protocol. Compatible with browser environments.
+ */
+export declare class OTLPHttpJsonTraceExporter implements SpanExporter {
+    /** @ignore */
+    private readonly impl;
+    constructor(config?: OTLPExporterConfig);
+    /** See `SpanExporter#export()` */
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    /** See `SpanExporter#shutdown()` */
+    shutdown(): Promise<void>;
+    /** See `SpanExporter#forceFlush()` */
+    forceFlush(): Promise<void>;
+}

package/dist/types/exporters/exporter-trace-otlp-proto-fetch.d.ts

@@ -0,0 +1,14 @@
+import type { ReadableSpan, SpanExporter } from '@opentelemetry/sdk-trace-base';
+import type { ExportResult } from '@opentelemetry/core';
+import type { OTLPExporterConfig } from './config';
+/**
+ * OTLP exporter for the `http/protobuf` protocol. Compatible with browser environments.
+ */
+export declare class OTLPHttpProtoTraceExporter implements SpanExporter {
+    /** @ignore */
+    private readonly impl;
+    constructor(config?: OTLPExporterConfig);
+    export(spans: ReadableSpan[], resultCallback: (result: ExportResult) => void): void;
+    shutdown(): Promise<void>;
+    forceFlush(): Promise<void>;
+}

package/dist/types/exporters/logs-config.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/exporters/otlp-exporter-base.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/exporters/proto.d.ts

@@ -0,0 +1,13 @@
+/**
+ * This file is constructed by:
+ *
+ * 1. Clone https://github.com/open-telemetry/opentelemetry-js.git
+ * 2. Run `protos:generate` in `experimental/packages/otlp-proto-exporter-base/`
+ * 3. Fork `experimental/packages/otlp-proto-exporter-base/src/generated/root.js` and inline all encode methods. Throw away the rest of the code.
+ *
+ * The OTLP protocol is very stable, so these steps would only need to be done rarely.
+ */
+import type { IExportTraceServiceRequest } from "@opentelemetry/otlp-transformer/build/src/trace/internal-types";
+import { Writer } from "protobufjs/minimal";
+export declare function encodeTraceServiceRequest(message: IExportTraceServiceRequest): Uint8Array;
+export declare function ExportTraceServiceRequest_encode(message: IExportTraceServiceRequest, writer: Writer): Writer;

package/dist/types/exporters/trace-config.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/index.d.ts

@@ -0,0 +1,160 @@
+import { DiagLogLevel } from '@opentelemetry/api';
+import { logs } from '@opentelemetry/api-logs';
+/**
+ * OpenTelemetry semantic convention attribute names for end user identification.
+ * @see https://opentelemetry.io/docs/specs/semconv/attributes-registry/enduser/
+ */
+export declare const ENDUSER_ATTRIBUTES: {
+    /** Unique identifier of an end user in the system */
+    readonly ID: "enduser.id";
+    /** Pseudonymous identifier of an end user (privacy-preserving) */
+    readonly PSEUDO_ID: "enduser.pseudo.id";
+    /** User's email address (PII - use with caution) */
+    readonly EMAIL: "enduser.email";
+    /** User's role or permission scope */
+    readonly ROLE: "enduser.role";
+};
+/**
+ * User context for telemetry correlation.
+ * These values are added as span attributes following OpenTelemetry semantic conventions
+ * and propagated via W3C Baggage headers to downstream services.
+ *
+ * @example
+ * ```ts
+ * const sdk = registerOTelBrowser({
+ *   serviceName: 'my-app',
+ *   user: { userId: 'user_123' }
+ * })
+ *
+ * // Later, update user context
+ * sdk.setUserContext({ userId: 'user_456', role: 'admin' })
+ *
+ * // Clear user context on logout
+ * sdk.setUserContext(null)
+ * ```
+ */
+export type UserContext = {
+    /**
+     * User ID - unique identifier of the end user (e.g., database ID, username).
+     * Set as `enduser.id` span attribute.
+     */
+    userId?: string;
+    /**
+     * Pseudonymous ID - privacy-preserving identifier (e.g., hashed user ID).
+     * Use this instead of userId when privacy is a concern.
+     * Set as `enduser.pseudo.id` span attribute.
+     */
+    pseudoId?: string;
+    /**
+     * User's email address.
+     * ⚠️ Contains PII - only include if necessary and compliant with privacy regulations.
+     * Set as `enduser.email` span attribute.
+     */
+    email?: string;
+    /**
+     * User's role or permission scope (e.g., 'admin', 'user', 'guest').
+     * Set as `enduser.role` span attribute.
+     */
+    role?: string;
+};
+export type BrowserConfig = {
+    serviceName?: string;
+    attributes?: Record<string, unknown>;
+    instrumentations?: Array<'auto' | 'fetch' | 'xhr' | 'document' | 'user'>;
+    exporter?: 'http/protobuf' | 'http/json';
+    exporterUrl?: string;
+    exporterHeaders?: Record<string, string>;
+    credentials?: RequestCredentials;
+    logLevel?: keyof typeof DiagLogLevel;
+    includeUserAgent?: boolean;
+    fetch?: {
+        ignoreUrls?: (string | RegExp)[];
+        propagateContextUrls?: (string | RegExp)[];
+        dontPropagateContextUrls?: (string | RegExp)[];
+        resourceNameTemplate?: string;
+        attributesFromRequestHeaders?: Record<string, string>;
+        attributesFromResponseHeaders?: Record<string, string>;
+    };
+    logs?: {
+        exporter?: 'http/protobuf' | 'http/json';
+        exporterUrl?: string;
+        exporterHeaders?: Record<string, string>;
+        credentials?: RequestCredentials;
+    };
+    errors?: {
+        captureUnhandled?: boolean;
+    };
+    console?: {
+        enabled?: boolean;
+    };
+    /**
+     * Organisation ID for authenticated telemetry.
+     * When set together with publishableKey, telemetry will be sent with Basic authentication.
+     */
+    organisationId?: string;
+    /**
+     * Publishable key for authenticated telemetry.
+     * Used together with organisationId for Basic auth: base64(orgId:publishableKey)
+     */
+    publishableKey?: string;
+    /**
+     * Initial user context for telemetry.
+     * Can be updated later via `sdk.setUserContext()`.
+     * @see UserContext
+     */
+    user?: UserContext;
+};
+export type BrowserSDK = {
+    /** Force flush all pending spans and logs */
+    forceFlush: () => Promise<void>;
+    /** Shutdown the SDK and flush remaining data */
+    shutdown: () => Promise<void>;
+    /** Get a logger instance for emitting structured logs */
+    getLogger: (name: string, version?: string) => ReturnType<typeof logs.getLogger>;
+    /**
+     * Set user context for telemetry correlation.
+     * Updates baggage for propagation and span attributes for all future spans.
+     *
+     * @param user - User context to set, or null to clear
+     * @example
+     * ```ts
+     * // Set user after login
+     * sdk.setUserContext({ userId: 'user_123', role: 'admin' })
+     *
+     * // Clear user on logout
+     * sdk.setUserContext(null)
+     * ```
+     */
+    setUserContext: (user: UserContext | null) => void;
+    /**
+     * Get the current user context.
+     * Returns the user context from module state or extracted from active baggage.
+     */
+    getUserContext: () => UserContext | null;
+};
+/**
+ * Registers the OpenTelemetry browser SDK with automatic user context propagation.
+ *
+ * This function initializes:
+ * - WebTracerProvider for span creation
+ * - W3C Trace Context and Baggage propagators
+ * - Automatic instrumentation (fetch, XHR, document load, user interactions)
+ * - OTLP export for traces and logs
+ * - User context propagation via baggage
+ *
+ * @param config - Configuration options
+ * @returns BrowserSDK instance with control methods
+ *
+ * @example
+ * ```ts
+ * const sdk = registerOTelBrowser({
+ *   serviceName: 'my-app',
+ *   exporterUrl: 'https://otel-collector.example.com/v1/traces',
+ *   user: { userId: 'user_123' }
+ * })
+ *
+ * // Update user context after authentication
+ * sdk.setUserContext({ userId: currentUser.id, role: currentUser.role })
+ * ```
+ */
+export declare function registerOTelBrowser(config?: BrowserConfig): BrowserSDK;

package/dist/types/instrumentations/browser-error.d.ts

@@ -0,0 +1,7 @@
+export declare class BrowserErrorInstrumentation {
+    private onError?;
+    private onRejection?;
+    private enabled;
+    enable(): void;
+    disable(): void;
+}

package/dist/types/instrumentations/console.d.ts

@@ -0,0 +1,6 @@
+export declare class ConsoleInstrumentation {
+    private originals;
+    private enabled;
+    enable(): void;
+    disable(): void;
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@glimt.dev/otel-browser",
+  "version": "0.1.0",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Minimal browser-only OpenTelemetry bootstrap for Glimt.dev",
+  "author": "Glimt.dev",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./cdn": {
+      "default": "./dist/cdn/index.js"
+    }
+  },
+  "types": "./dist/types/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/api-logs": "^0.208.0",
+    "@opentelemetry/context-zone": "^2.2.0",
+    "@opentelemetry/core": "^2.2.0",
+    "@opentelemetry/instrumentation": "^0.208.0",
+    "@opentelemetry/instrumentation-document-load": "^0.54.0",
+    "@opentelemetry/instrumentation-fetch": "^0.208.0",
+    "@opentelemetry/instrumentation-user-interaction": "^0.53.0",
+    "@opentelemetry/instrumentation-xml-http-request": "^0.208.0",
+    "@opentelemetry/otlp-exporter-base": "^0.208.0",
+    "@opentelemetry/otlp-transformer": "^0.208.0",
+    "@opentelemetry/resources": "^2.2.0",
+    "@opentelemetry/sdk-logs": "^0.208.0",
+    "@opentelemetry/sdk-trace-base": "^2.2.0",
+    "@opentelemetry/sdk-trace-web": "^2.2.0",
+    "protobufjs": "^7.5.4"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.1",
+    "esbuild": "^0.27.1",
+    "jsdom": "^27.2.0",
+    "typescript": "^5.9.3",
+    "vitest": "4.0.15",
+    "typescript-config": "1.0.0"
+  },
+  "engines": {
+    "node": ">=18.19.0"
+  },
+  "scripts": {
+    "build": "pnpm clean && tsc --noEmit false --declaration --emitDeclarationOnly --stripInternal --declarationDir dist/types src/index.ts && tsc -p tsconfig.json && node ./build.mjs",
+    "clean": "rm -rf dist",
+    "type-check": "tsc --noEmit",
+    "unit-test": "vitest --run",
+    "unit-test-watch": "vitest",
+    "size": "node -e \"const fs=require('fs');const zlib=require('zlib');const b=fs.readFileSync('dist/cdn/index.js');const gz=zlib.gzipSync(b,{level:9});const kb=(gz.length/1024).toFixed(1);const max=200;console.log('cdn gz',kb+'kb');if(gz.length>max*1024){console.error('Size limit exceeded:'+kb+'kb > '+max+'kb');process.exit(1)}\""
+  }
+}