@dash0/sdk-web 0.6.2

package/dist/types/utils/otel/attributes.d.ts

@@ -0,0 +1,9 @@
+import { AnyValue, KeyValue } from "../../../types/otlp";
+type PrimitiveAttributeValue = string | number | boolean;
+export type AttributeValueType = PrimitiveAttributeValue | Array<PrimitiveAttributeValue> | Record<string, PrimitiveAttributeValue>;
+export declare function toAnyValue(value: AttributeValueType | AnyValue): AnyValue;
+export declare function toAnyValue(value?: AttributeValueType | AnyValue): AnyValue | undefined;
+export declare function toKeyValue(key: string, value: AttributeValueType | AnyValue): KeyValue;
+export declare function addAttribute(attributes: KeyValue[], key: string, value: AttributeValueType | AnyValue): void;
+export declare function removeAttribute(attributes: KeyValue[], key: string): void;
+export {};

package/dist/types/utils/otel/attributes_test.d.ts

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

package/dist/types/utils/otel/error.d.ts

@@ -0,0 +1,24 @@
+import { InProgressSpan } from "./span";
+import { SpanStatus } from "../../../types/otlp";
+interface ExceptionWithCode {
+    code: string | number;
+    name?: string;
+    message?: string;
+    stack?: string;
+}
+interface ExceptionWithMessage {
+    code?: string | number;
+    message: string;
+    name?: string;
+    stack?: string;
+}
+interface ExceptionWithName {
+    code?: string | number;
+    message?: string;
+    name: string;
+    stack?: string;
+}
+export type Exception = ExceptionWithCode | ExceptionWithMessage | ExceptionWithName | string;
+export declare function recordException(span: InProgressSpan, exception: Exception): void;
+export declare function errorToSpanStatus(e: Exception): SpanStatus;
+export {};

package/dist/types/utils/otel/http.d.ts

@@ -0,0 +1,2 @@
+export declare function httpRequestHeaderKey(key: string): string;
+export declare function httpResponseHeaderKey(key: string): string;

package/dist/types/utils/otel/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./attributes";
+export * from "./trace-context";
+export * from "./span";
+export * from "./error";

package/dist/types/utils/otel/span.d.ts

@@ -0,0 +1,10 @@
+import { KeyValue, Span, SpanStatus } from "../../../types/otlp";
+export type InProgressSpan = Omit<Span, "endTimeUnixNano">;
+export declare function startSpan(name: string): InProgressSpan;
+export declare function endSpan(span: InProgressSpan, status: SpanStatus | undefined, durationNano: number | undefined): Span;
+/**
+ * Adds an event to a span. Can optionally accept the events timestamp and attributes for the event.
+ * The timestamp needs to be specified as nanoseconds since unix epoch in string format.
+ */
+export declare function addSpanEvent(span: InProgressSpan, name: string, attributesOrTs?: string | KeyValue[] | undefined, attributes?: KeyValue[] | undefined): void;
+export declare function setSpanStatus(span: InProgressSpan, code: SpanStatus["code"], message?: string): void;

package/dist/types/utils/otel/trace-context.d.ts

@@ -0,0 +1,8 @@
+import { InProgressSpan } from "./span";
+type TraceContext = {
+    traceId?: string;
+    spanId?: string;
+};
+export declare function getTraceContextForPageLoad(): TraceContext | undefined;
+export declare function addTraceContextHttpHeaders(fn: (name: string, value: string) => void, ctx: unknown, span: InProgressSpan): void;
+export {};

package/dist/types/utils/performance.d.ts

@@ -0,0 +1,45 @@
+export declare const isResourceTimingAvailable: boolean;
+export declare const isPerformanceObserverAvailable: any;
+export declare const PerformanceTimingNames: Readonly<{
+    CONNECT_END: "connectEnd";
+    CONNECT_START: "connectStart";
+    DECODED_BODY_SIZE: "decodedBodySize";
+    DOM_COMPLETE: "domComplete";
+    DOM_CONTENT_LOADED_EVENT_END: "domContentLoadedEventEnd";
+    DOM_CONTENT_LOADED_EVENT_START: "domContentLoadedEventStart";
+    DOM_INTERACTIVE: "domInteractive";
+    DOMAIN_LOOKUP_END: "domainLookupEnd";
+    DOMAIN_LOOKUP_START: "domainLookupStart";
+    ENCODED_BODY_SIZE: "encodedBodySize";
+    FETCH_START: "fetchStart";
+    LOAD_EVENT_END: "loadEventEnd";
+    LOAD_EVENT_START: "loadEventStart";
+    NAVIGATION_START: "navigationStart";
+    REDIRECT_END: "redirectEnd";
+    REDIRECT_START: "redirectStart";
+    REQUEST_START: "requestStart";
+    RESPONSE_END: "responseEnd";
+    RESPONSE_START: "responseStart";
+    SECURE_CONNECTION_START: "secureConnectionStart";
+    START_TIME: "startTime";
+    UNLOAD_EVENT_END: "unloadEventEnd";
+    UNLOAD_EVENT_START: "unloadEventStart";
+}>;
+export type ObserveResourcePerformanceResult = {
+    duration: number;
+    resource?: PerformanceResourceTiming | null;
+};
+type ObserveResourcePerformanceResultCallback = (arg: ObserveResourcePerformanceResult) => any;
+type ObserveResourcePerformanceOptions = {
+    resourceMatcher: (arg: PerformanceResourceTiming) => boolean;
+    maxWaitForResourceMillis: number;
+    maxToleranceForResourceTimingsMillis: number;
+    onEnd: ObserveResourcePerformanceResultCallback;
+};
+type PerformanceObservationContoller = {
+    start: () => void;
+    end: () => void;
+    cancel: () => void;
+};
+export declare function observeResourcePerformance(opts: ObserveResourcePerformanceOptions): PerformanceObservationContoller;
+export {};

package/dist/types/utils/pick.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Creates a new object by picking specified properties from the source object.
+ * Similar to TypeScript's Pick<T, K> utility type but as a runtime function.
+ *
+ * @param obj - The source object to pick properties from
+ * @param keys - Array of property keys to pick from the source object
+ * @returns A new object containing only the specified properties
+ */
+export declare function pick<T extends Record<string, any>, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;

package/dist/types/utils/pick_test.d.ts

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

package/dist/types/utils/rate-limit.d.ts

@@ -0,0 +1,5 @@
+export declare function createRateLimiter(opts: {
+    maxCalls?: number;
+    maxCallsPerTenMinutes: number;
+    maxCallsPerTenSeconds: number;
+}): () => boolean;

package/dist/types/utils/session-storage.d.ts

@@ -0,0 +1,4 @@
+export declare const isSupported: boolean;
+export declare function getItem(k: string): string | null | undefined;
+export declare function setItem(k: string, v: string): void;
+export declare function removeItem(k: string): void;

package/dist/types/utils/tab-id.d.ts

@@ -0,0 +1,8 @@
+export declare let tabId: string | null;
+/**
+ * We want to be able to identify what browser tab the user is looking at. We do this by identifying tabs through
+ * random-generated IDs that are kept in session storage. To quote MDN:
+ *
+ * > sessionStorage is partitioned by both origin and browser tabs (top-level browsing contexts)
+ */
+export declare function initializeTabId(): void;

package/dist/types/utils/time.d.ts

@@ -0,0 +1,6 @@
+export type TimeInput = number | Date;
+export declare function now(): number;
+export declare function nowNanos(): string;
+export declare function toNanosTs(time: TimeInput): string;
+export declare function getTimeOrigin(): number;
+export declare function domHRTimestampToNanos(ts: number): string;

package/dist/types/utils/timers.d.ts

@@ -0,0 +1,6 @@
+import { WindowType } from "./globals";
+export declare const isRunningZoneJs: boolean;
+export declare function setTimeout(..._: Parameters<WindowType["setTimeout"]>): ReturnType<WindowType["setTimeout"]>;
+export declare function clearTimeout(..._: Parameters<WindowType["clearTimeout"]>): ReturnType<WindowType["clearTimeout"]>;
+export declare function setInterval(..._: Parameters<WindowType["setInterval"]>): ReturnType<WindowType["setInterval"]>;
+export declare function clearInterval(..._: Parameters<WindowType["clearInterval"]>): ReturnType<WindowType["clearInterval"]>;

package/dist/types/utils/url.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parses url using URL constructor. Supports URL objects as passthrough input to simplify implementations
+ * May throw if parsing fails
+ * @param url
+ */
+export declare function parseUrl(url: string | URL): URL;

package/dist/types/utils/wrap.d.ts

@@ -0,0 +1 @@
+export declare function wrap<ModuleType extends object, TargetNameType extends keyof ModuleType>(module: ModuleType, target: TargetNameType, wrapper: (original: ModuleType[TargetNameType]) => ModuleType[TargetNameType]): void;

package/dist/types/vars.d.ts

@@ -0,0 +1,123 @@
+import { AnyValue, InstrumentationScope, KeyValue, Resource } from "../types/otlp";
+import { AttributeValueType } from "./utils/otel";
+export type Endpoint = {
+    /**
+     * OTLP HTTP URL excluding the /v1/* prefix
+     */
+    url: string;
+    /**
+     * Will be placed into `Authorization: Bearer {auth_token}` header. Has the form
+     * `auth_abc123`.
+     */
+    authToken: string;
+    /**
+     * Optionally specify what dataset should be placed into. Can also be configured within Dash0
+     * through the auth token.
+     */
+    dataset?: string;
+};
+export type PageViewMeta = {
+    /**
+     * Defaults to document.title
+     */
+    title?: string;
+    attributes?: Record<string, AttributeValueType | AnyValue>;
+};
+export type PageViewInstrumentationSettings = {
+    /**
+     * Allows the selection of custom page metadata, falls back to default behaviour if undefined is returned.
+     */
+    generateMetadata?: (url: URL) => PageViewMeta | undefined;
+    /**
+     * Whether the sdk should track virtual page views by instrumenting the history api.
+     * Only relevant for websites utilizing virtual navigation.
+     * Defaults to true.
+     */
+    trackVirtualPageViews?: boolean;
+    /**
+     * Additionally generate virtual page views when these url parts change.
+     * - "HASH" include changes to the urls hash / fragment
+     * - "SEARCH" include changes to the urls search / query parameters
+     */
+    includeParts?: Array<"HASH" | "SEARCH">;
+};
+export type Vars = {
+    /**
+     * Telemetry endpoints to which the generated telemetry should be sent
+     */
+    endpoints: Endpoint[];
+    /**
+     * OpenTelemetry resource used for all the telemetry we emit.
+     */
+    resource: Resource;
+    /**
+     * OpenTelemetry scope used for all the telemetry we emit.
+     */
+    scope: InstrumentationScope;
+    /**
+     * Attributes that are supposed to be added to all outgoing signals
+     * at the time they are **added** to the transport layer.
+     */
+    signalAttributes: KeyValue[];
+    /**
+     * An array of URL regular expression for which no data should be
+     * collected. These regular expressions are evaluated against
+     * the document, XMLHttpRequest, fetch and resource URLs.
+     */
+    ignoreUrls: RegExp[];
+    /**
+     * An array of error message regular expressions for which no data
+     * should be collected.
+     */
+    ignoreErrorMessages: RegExp[];
+    /**
+     * Whether we should automatically wrap DOM event handlers
+     * added via addEventlistener for improved uncaught error tracking.
+     * This results in improved uncaught error tracking for cross-origin
+     * errors, but may have adverse effects on website performance and
+     * stability.
+     *
+     * @default true
+     */
+    wrapEventHandlers: boolean;
+    /**
+     * Whether we should automatically wrap timers
+     * added via setTimeout / setInterval for improved uncaught error tracking.
+     * This results in improved uncaught error tracking for cross-origin
+     * errors, but may have adverse effects on website performance and
+     * stability.
+     *
+     * @default true
+     */
+    wrapTimers: boolean;
+    /**
+     * An array of URL regular expressions
+     * for which trace context headers should be sent across origins by http client instrumentations.
+     */
+    propagateTraceHeadersCorsURLs: RegExp[];
+    /**
+     * How long to wait after an XMLHttpRequest or fetch request has finished
+     * for the retrieval of resource timing data. Performance timeline events
+     * are placed on the low priority task queue and therefore high values
+     * might be necessary.
+     *
+     * @default 10000
+     */
+    maxWaitForResourceTimingsMillis: number;
+    /**
+     * The number of milliseconds of tolerance between resolution of a http request promise and the end time of performanceEntries
+     * applied when matching a request to its respective performance entry. A higher value might increase match frequency at
+     * the cost of potential incorrect matches. Matching is performed based on request timing and url.
+     *
+     * @default 3000
+     */
+    maxToleranceForResourceTimingsMillis: number;
+    /**
+     * A set of regular expressions that will be matched against HTTP request headers to be
+     * captured in `XMLHttpRequest` and `fetch` Instrumentations.
+     * These headers will be transferred as span attributes
+     */
+    headersToCapture: RegExp[];
+    pageViewInstrumentation: PageViewInstrumentationSettings;
+};
+export declare const vars: Vars;

package/package.json

@@ -0,0 +1,124 @@
+{
+  "name": "@dash0/sdk-web",
+  "version": "0.6.2",
+  "description": "Dash0's Web SDK to collect telemetry from end-users' web browsers",
+  "type": "module",
+  "main": "dist/dash0.umd.cjs",
+  "module": "dist/dash0.js",
+  "unpkg": "dist/dash0.iife.js",
+  "exports": {
+    ".": {
+      "types": "./dist/types/entrypoint/npm-package.d.ts",
+      "require": "./dist/dash0.umd.cjs",
+      "default": "./dist/dash0.js"
+    }
+  },
+  "types": "./dist/types/entrypoint/npm-package.d.ts",
+  "scripts": {
+    "build": "run-s build:clean build:typescript build:rollup build:stats",
+    "build:clean": "rm -rf dist",
+    "build:typescript": "tsc -b",
+    "build:rollup": "rollup -c -m",
+    "build:stats": "echo \"\nFile Stats:\" && ls dist/*.js | xargs -I '%' bash -c 'echo \"%: $(./node_modules/.bin/gzip-size % --include-original) (gzip)\"'",
+    "prettier:all": "prettier . --write --cache --list-different",
+    "prettier:check": "prettier . --check",
+    "lint": "eslint 'src/**/*.ts'",
+    "lint:fix": "eslint 'src/**/*.ts' --fix",
+    "test": "run-s test:unit test:e2e",
+    "test:unit": "vitest run",
+    "test:unit:watch": "vitest",
+    "test:e2e": "wdio run ./test/e2e/wdio.conf.ts",
+    "test:e2e:local": "pnpm run build && wdio run ./test/e2e/wdio.local.conf.ts",
+    "test:e2e:server": "SERVER_PORTS='8010,8011,8012' node test/e2e/server/index.mjs",
+    "test:e2e:tunnel": "dotenv -- bash -c './.lambdatest/v3/LT --user $LT_USERNAME --key $LT_ACCESS_KEY'",
+    "test:e2e:live": "run-p test:e2e:server test:e2e:tunnel",
+    "test:coverage": "vitest run --coverage",
+    "ci": "run-s lint prettier:check test:unit build",
+    "prepare": "husky",
+    "release": "release-it"
+  },
+  "keywords": [
+    "performance",
+    "observability",
+    "opentelemetry",
+    "otel",
+    "logs",
+    "spans",
+    "tracing",
+    "Core Web Vitals",
+    "CLS",
+    "INP",
+    "LCP"
+  ],
+  "files": [
+    "src",
+    "dist",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "author": "Dash0 Inc.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dash0hq/dash0-sdk-web.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dash0hq/dash0-sdk-web/issues"
+  },
+  "dependencies": {
+    "@babel/core": "^7.26.10",
+    "@babel/preset-env": "^7.26.9",
+    "@rollup/plugin-babel": "^6.0.4",
+    "@rollup/plugin-terser": "^0.4.4",
+    "web-vitals": "^4.2.4",
+    "ts-deepmerge": "^7.0.3"
+  },
+  "devDependencies": {
+    "dotenv-cli": "^8.0.0",
+    "@release-it/conventional-changelog": "^10.0.1",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-replace": "^6.0.2",
+    "@types/body-parser": "^1.19.5",
+    "@types/express": "^5.0.1",
+    "@types/mocha": "^10.0.10",
+    "@types/multiparty": "^4.2.1",
+    "@types/node": "^22.14.1",
+    "@types/serve-index": "^1.9.4",
+    "@typescript-eslint/eslint-plugin": "^8.29.1",
+    "@typescript-eslint/parser": "^8.29.1",
+    "@wdio/cli": "^9.12.5",
+    "@wdio/globals": "^9.12.5",
+    "@wdio/local-runner": "^9.12.5",
+    "@wdio/mocha-framework": "^9.12.5",
+    "@wdio/sauce-service": "^9.12.5",
+    "@wdio/spec-reporter": "^9.12.3",
+    "wdio-lambdatest-service": "^4.0.0",
+    "body-parser": "^2.2.0",
+    "eslint": "^9.24.0",
+    "express": "^5.1.0",
+    "google-closure-compiler": "^20240317.0.0",
+    "gzip-size-cli": "^5.1.0",
+    "husky": "^9.1.7",
+    "jsdom": "^26.0.0",
+    "multiparty": "^4.2.3",
+    "npm-run-all": "^4.1.5",
+    "prettier": "^3.5.3",
+    "release-it": "^19.0.1",
+    "rollup": "^4.39.0",
+    "serve-index": "^1.9.1",
+    "tsx": "^4.19.4",
+    "typescript": "^5.8.3",
+    "uuid": "^11.1.0",
+    "vitest": "^3.1.1",
+    "webdriverio": "^9.12.5"
+  },
+  "resolutions": {
+    "conventional-changelog-conventionalcommits": "8.0.0"
+  },
+  "packageManager": "pnpm@9.15.1",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api/attributes.ts

@@ -0,0 +1,19 @@
+import { AnyValue } from "../../types/otlp";
+import { addAttribute, AttributeValueType, removeAttribute } from "../utils/otel";
+import { vars } from "../vars";
+
+/**
+ * Adds a signal attribute to be transmitted with every signal.
+ * Note: if you need to ensure attributes are included with signals transmitted on initial page load, you should use
+ * the "additionalSignalAttributes" property of the init call instead
+ */
+export function addSignalAttribute(name: string, value: AttributeValueType | AnyValue) {
+  addAttribute(vars.signalAttributes, name, value);
+}
+
+/**
+ * Removes a previously added signal attribute
+ */
+export function removeSignalAttribute(name: string) {
+  removeAttribute(vars.signalAttributes, name);
+}

package/src/api/debug.ts

@@ -0,0 +1,6 @@
+import { vars } from "../vars";
+import { debug as debugLogger } from "../utils/debug";
+
+export function debug() {
+  debugLogger("Dash0 Web SDK configuration state:", vars);
+}

package/src/api/events.ts

@@ -0,0 +1,67 @@
+import { AnyValue, KeyValue } from "../../types/otlp";
+import { EVENT_NAME, EVENT_NAMES, EVENT_TITLE, LOG_SEVERITIES, LOG_SEVERITY_TEXT } from "../semantic-conventions";
+import { sendLog } from "../transport";
+import { addCommonAttributes } from "../attributes";
+import { addAttribute, AttributeValueType, toAnyValue } from "../utils/otel";
+import { nowNanos, TimeInput, toNanosTs, warn } from "../utils";
+
+type EventOptions = {
+  /**
+   * Human readable title for the event.
+   * Should summarize the event in a single short sentence.
+   * Transmitted via the `dash0.event.title` attribute.
+   */
+  title?: string;
+
+  /**
+   * The timestamp at which the event happened.
+   * Defaults to now
+   */
+  timestamp?: TimeInput;
+
+  /**
+   * The event body
+   */
+  data?: AttributeValueType | AnyValue;
+
+  /**
+   * Attributes to include with the event
+   */
+  attributes?: Record<string, AttributeValueType | AnyValue>;
+
+  /**
+   * The events log severity
+   */
+  severity?: LOG_SEVERITY_TEXT;
+};
+
+/**
+ * Sends a custom event.
+ * @param name The event name. Can not be any of the internal event names. See: EVENT_NAMES in src/semantic-conventions.
+ * @param opts Additional event details.
+ */
+export function sendEvent(name: string, opts?: EventOptions) {
+  if (Object.values(EVENT_NAMES).includes(name)) {
+    warn(
+      `Unable to send custom event ${name}. You are not allowed to use an internal event name while sending a custom event. Dropping event...`
+    );
+    return;
+  }
+
+  const attributes: KeyValue[] = [];
+  addCommonAttributes(attributes);
+  Object.entries(opts?.attributes ?? {}).forEach(([key, value]) => addAttribute(attributes, key, value));
+
+  addAttribute(attributes, EVENT_NAME, name);
+  if (opts?.title) {
+    addAttribute(attributes, EVENT_TITLE, opts.title);
+  }
+
+  sendLog({
+    timeUnixNano: opts?.timestamp != null ? toNanosTs(opts.timestamp) : nowNanos(),
+    attributes,
+    body: toAnyValue(opts?.data),
+    severityText: opts?.severity,
+    severityNumber: opts?.severity ? LOG_SEVERITIES[opts.severity] : undefined,
+  });
+}

package/src/api/identify.ts

@@ -0,0 +1,43 @@
+import { vars } from "../vars";
+import { addAttribute, removeAttribute } from "../utils/otel";
+import { USER_EMAIL, USER_FULL_NAME, USER_HASH, USER_ID, USER_NAME, USER_ROLES } from "../semantic-conventions";
+
+type IdentifyOpts = {
+  name?: string;
+  fullName?: string;
+  email?: string;
+  hash?: string;
+  roles?: string[];
+};
+
+export function identify(id?: string, opts?: IdentifyOpts) {
+  removeAttribute(vars.signalAttributes, USER_ID);
+  if (id != null) {
+    addAttribute(vars.signalAttributes, USER_ID, id);
+  }
+
+  removeAttribute(vars.signalAttributes, USER_NAME);
+  if (opts?.name != null) {
+    addAttribute(vars.signalAttributes, USER_NAME, opts.name);
+  }
+
+  removeAttribute(vars.signalAttributes, USER_FULL_NAME);
+  if (opts?.fullName != null) {
+    addAttribute(vars.signalAttributes, USER_FULL_NAME, opts.fullName);
+  }
+
+  removeAttribute(vars.signalAttributes, USER_EMAIL);
+  if (opts?.email != null) {
+    addAttribute(vars.signalAttributes, USER_EMAIL, opts.email);
+  }
+
+  removeAttribute(vars.signalAttributes, USER_HASH);
+  if (opts?.hash != null) {
+    addAttribute(vars.signalAttributes, USER_HASH, opts.hash);
+  }
+
+  removeAttribute(vars.signalAttributes, USER_ROLES);
+  if (opts?.roles != null) {
+    addAttribute(vars.signalAttributes, USER_ROLES, opts.roles);
+  }
+}