autotel-web 1.1.0

package/dist/index.d.ts

@@ -0,0 +1,310 @@
+/**
+ * Privacy controls for autotel-web
+ *
+ * Provides origin filtering and privacy signal respecting (DNT, GPC)
+ * to ensure compliance with GDPR, CCPA, and user privacy preferences.
+ */
+interface PrivacyConfig {
+    /**
+     * Only inject traceparent headers on requests to these origins (whitelist)
+     *
+     * If specified, traceparent will ONLY be injected on matching origins.
+     * Origins are matched using substring matching (e.g., "example.com" matches "https://api.example.com").
+     *
+     * @example
+     * ```typescript
+     * {
+     *   allowedOrigins: ['api.myapp.com', 'myapp.com']
+     * }
+     * ```
+     */
+    allowedOrigins?: string[];
+    /**
+     * Never inject traceparent headers on requests to these origins (blacklist)
+     *
+     * Takes precedence over allowedOrigins.
+     * Origins are matched using substring matching.
+     *
+     * @example
+     * ```typescript
+     * {
+     *   blockedOrigins: ['analytics.google.com', 'facebook.com']
+     * }
+     * ```
+     */
+    blockedOrigins?: string[];
+    /**
+     * Respect the Do Not Track (DNT) browser setting
+     *
+     * If true and user has DNT enabled, no traceparent headers will be injected.
+     *
+     * @default false
+     * @see https://developer.mozilla.org/en-US/docs/Web/API/Navigator/doNotTrack
+     */
+    respectDoNotTrack?: boolean;
+    /**
+     * Respect the Global Privacy Control (GPC) browser signal
+     *
+     * If true and user has GPC enabled, no traceparent headers will be injected.
+     *
+     * @default false
+     * @see https://globalprivacycontrol.org/
+     */
+    respectGPC?: boolean;
+}
+
+/**
+ * Minimal browser SDK initialization
+ *
+ * Patches fetch() and XMLHttpRequest to automatically inject W3C traceparent headers.
+ * NO OpenTelemetry dependencies - just native browser APIs.
+ *
+ * Bundle size: ~2-5KB gzipped
+ */
+
+interface AutotelWebConfig {
+    /**
+     * Service name for the browser application
+     * Used only for logging/debugging - not sent in headers
+     */
+    service: string;
+    /**
+     * Enable debug logging to console
+     * @default false
+     */
+    debug?: boolean;
+    /**
+     * Enable automatic traceparent injection on fetch calls
+     * @default true
+     */
+    instrumentFetch?: boolean;
+    /**
+     * Enable automatic traceparent injection on XMLHttpRequest
+     * @default true
+     */
+    instrumentXHR?: boolean;
+    /**
+     * Privacy controls for traceparent header injection
+     *
+     * Configure origin filtering and privacy signal respecting (DNT, GPC)
+     * to ensure compliance with GDPR, CCPA, and user privacy preferences.
+     *
+     * @example Basic origin filtering
+     * ```typescript
+     * {
+     *   privacy: {
+     *     allowedOrigins: ['api.myapp.com'],  // Only inject on API calls
+     *     respectDoNotTrack: true              // Respect user's DNT setting
+     *   }
+     * }
+     * ```
+     *
+     * @example Block third-party analytics
+     * ```typescript
+     * {
+     *   privacy: {
+     *     blockedOrigins: ['analytics.google.com', 'facebook.com']
+     *   }
+     * }
+     * ```
+     */
+    privacy?: PrivacyConfig;
+}
+/**
+ * Initialize autotel-web
+ *
+ * Patches fetch() and XMLHttpRequest to auto-inject traceparent headers.
+ *
+ * **SSR-safe:** Safe to call in SSR environments (checks for window).
+ * **Call once:** Subsequent calls are ignored.
+ *
+ * @example
+ * ```typescript
+ * import { init } from 'autotel-web'
+ *
+ * init({ service: 'my-frontend-app' })
+ *
+ * // Now all fetch/XHR calls include traceparent headers!
+ * fetch('/api/users')  // <-- traceparent header automatically injected
+ * ```
+ *
+ * @example With React (client-only)
+ * ```typescript
+ * import { useEffect } from 'react'
+ * import { init } from 'autotel-web'
+ *
+ * function App() {
+ *   useEffect(() => {
+ *     init({ service: 'my-spa' })
+ *   }, [])
+ *
+ *   return <div>...</div>
+ * }
+ * ```
+ */
+declare function init(userConfig: AutotelWebConfig): void;
+
+/**
+ * Minimal functional API for browser tracing
+ *
+ * These are DX wrappers that DON'T create real browser spans.
+ * The real spans and timing happen on the backend via Autotel.
+ *
+ * The browser's job is just to propagate trace context via headers.
+ */
+/**
+ * Minimal trace context (browser-side)
+ *
+ * This is a lightweight version that just holds IDs.
+ * NO actual span object - the real span lives on the backend.
+ */
+interface TraceContext {
+    /** Current trace ID (may be extracted from request) */
+    readonly traceId: string;
+    /** Current span ID (generated for this browser "span") */
+    readonly spanId: string;
+    /** Correlation ID (same as trace ID) */
+    readonly correlationId: string;
+}
+/**
+ * Wrap a function with trace() for better DX
+ *
+ * **Important:** This does NOT create real spans in the browser.
+ * It's purely for API consistency. The real tracing happens on the backend.
+ *
+ * The traceparent header is automatically injected by init() on fetch/XHR calls.
+ *
+ * @example Basic usage
+ * ```typescript
+ * const fetchUser = trace(async (id: string) => {
+ *   const response = await fetch(`/api/users/${id}`)
+ *   return response.json()
+ * })
+ * ```
+ *
+ * @example With context (for accessing trace IDs)
+ * ```typescript
+ * const fetchUser = trace(ctx => async (id: string) => {
+ *   console.log('Trace ID:', ctx.traceId)
+ *   const response = await fetch(`/api/users/${id}`)
+ *   return response.json()
+ * })
+ * ```
+ */
+declare function trace<T extends (...args: any[]) => any>(fn: T | ((ctx: TraceContext) => T)): T;
+/**
+ * Get the current trace context (if any)
+ *
+ * @returns Current trace context or undefined
+ *
+ * @example
+ * ```typescript
+ * const ctx = getActiveContext()
+ * if (ctx) {
+ *   console.log('Trace ID:', ctx.traceId)
+ * }
+ * ```
+ */
+declare function getActiveContext(): TraceContext | undefined;
+/**
+ * Manual helper to create a traceparent header
+ *
+ * Useful if you need to manually set headers or disable auto-instrumentation.
+ *
+ * @returns W3C traceparent header value
+ *
+ * @example
+ * ```typescript
+ * import { init, getTraceparent } from 'autotel-web'
+ *
+ * // Disable auto-instrumentation
+ * init({ service: 'my-app', instrumentFetch: false })
+ *
+ * // Manually inject headers
+ * fetch('/api/data', {
+ *   headers: {
+ *     'traceparent': getTraceparent()
+ *   }
+ * })
+ * ```
+ */
+declare function getTraceparent(): string;
+/**
+ * Extract trace context from a traceparent header
+ *
+ * Useful for SSR scenarios where you want to continue a trace from the server.
+ *
+ * @param traceparent - W3C traceparent header value
+ * @returns Parsed trace context or undefined if invalid
+ *
+ * @example
+ * ```typescript
+ * // In an SSR handler
+ * const traceparent = request.headers.get('traceparent')
+ * if (traceparent) {
+ *   const ctx = extractContext(traceparent)
+ *   console.log('Continuing trace:', ctx?.traceId)
+ * }
+ * ```
+ */
+declare function extractContext(traceparent: string): TraceContext | undefined;
+
+/**
+ * Minimal W3C Trace Context implementation for browser
+ *
+ * Generates traceparent headers in the W3C format:
+ * traceparent: 00-{trace-id}-{span-id}-{flags}
+ *
+ * No OpenTelemetry dependencies - just crypto.getRandomValues()
+ */
+/**
+ * Generate a random 128-bit (16 byte) trace ID
+ * @returns 32 character hex string
+ */
+declare function generateTraceId(): string;
+/**
+ * Generate a random 64-bit (8 byte) span ID
+ * @returns 16 character hex string
+ */
+declare function generateSpanId(): string;
+/**
+ * Create a W3C traceparent header value
+ *
+ * Format: version-traceId-spanId-flags
+ * - version: 00 (W3C Trace Context spec)
+ * - traceId: 128-bit hex (32 chars)
+ * - spanId: 64-bit hex (16 chars)
+ * - flags: 01 (sampled)
+ *
+ * @param traceId - Optional existing trace ID (for continuing traces)
+ * @param parentSpanId - Optional parent span ID (unused in browser, included for API compat)
+ * @returns W3C traceparent header value
+ *
+ * @example
+ * ```typescript
+ * const header = createTraceparent()
+ * // "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
+ * ```
+ */
+declare function createTraceparent(traceId?: string, _parentSpanId?: string): string;
+/**
+ * Parse a traceparent header value
+ * Useful for extracting trace context from incoming headers
+ *
+ * @param traceparent - W3C traceparent header value
+ * @returns Parsed components or null if invalid
+ *
+ * @example
+ * ```typescript
+ * const parsed = parseTraceparent('00-4bf92f...0e4736-00f067...902b7-01')
+ * console.log(parsed?.traceId) // "4bf92f...0e4736"
+ * ```
+ */
+declare function parseTraceparent(traceparent: string): {
+    version: string;
+    traceId: string;
+    spanId: string;
+    flags: string;
+} | null;
+
+export { type AutotelWebConfig, type PrivacyConfig, type TraceContext, createTraceparent, extractContext, generateSpanId, generateTraceId, getActiveContext, getTraceparent, init, parseTraceparent, trace };

package/dist/index.js

@@ -0,0 +1,391 @@
+// src/traceparent.ts
+function randomHex(bytes) {
+  const buffer = new Uint8Array(bytes);
+  crypto.getRandomValues(buffer);
+  return Array.from(buffer).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function generateTraceId() {
+  return randomHex(16);
+}
+function generateSpanId() {
+  return randomHex(8);
+}
+function createTraceparent(traceId, _parentSpanId) {
+  const tid = traceId ?? generateTraceId();
+  const sid = generateSpanId();
+  const flags = "01";
+  return `00-${tid}-${sid}-${flags}`;
+}
+function parseTraceparent(traceparent) {
+  const parts = traceparent.split("-");
+  if (parts.length !== 4) {
+    return null;
+  }
+  const [version, traceId, spanId, flags] = parts;
+  if (version.length !== 2 || traceId.length !== 32 || spanId.length !== 16 || flags.length !== 2) {
+    return null;
+  }
+  return { version, traceId, spanId, flags };
+}
+
+// src/privacy.ts
+var PrivacyManager = class {
+  constructor(config2) {
+    this.config = config2;
+  }
+  /**
+   * Check if traceparent header should be injected for a given URL
+   *
+   * Decision order:
+   * 1. Check Do Not Track (if enabled)
+   * 2. Check Global Privacy Control (if enabled)
+   * 3. Check blockedOrigins (explicit deny)
+   * 4. Check allowedOrigins (explicit allow, if configured)
+   * 5. Default: allow
+   *
+   * @param url - Full URL or relative path of the request
+   * @returns true if traceparent should be injected, false otherwise
+   */
+  shouldInjectTraceparent(url) {
+    if (this.config.respectDoNotTrack && this.isDoNotTrackEnabled()) {
+      return false;
+    }
+    if (this.config.respectGPC && this.isGPCEnabled()) {
+      return false;
+    }
+    const targetOrigin = this.extractOrigin(url);
+    if (this.config.blockedOrigins && this.matchesAnyOrigin(targetOrigin, this.config.blockedOrigins)) {
+      return false;
+    }
+    if (this.config.allowedOrigins && this.config.allowedOrigins.length > 0) {
+      return this.matchesAnyOrigin(targetOrigin, this.config.allowedOrigins);
+    }
+    return true;
+  }
+  /**
+   * Check if Do Not Track is enabled in the browser
+   */
+  isDoNotTrackEnabled() {
+    if (typeof navigator === "undefined") return false;
+    return navigator.doNotTrack === "1";
+  }
+  /**
+   * Check if Global Privacy Control is enabled in the browser
+   */
+  isGPCEnabled() {
+    if (typeof navigator === "undefined") return false;
+    const nav = navigator;
+    return nav.globalPrivacyControl === true;
+  }
+  /**
+   * Extract origin from a URL (handles both absolute and relative URLs)
+   *
+   * @param url - Full URL or relative path
+   * @returns Origin string (e.g., "https://api.example.com")
+   */
+  extractOrigin(url) {
+    try {
+      if (url.startsWith("http://") || url.startsWith("https://")) {
+        return new URL(url).origin;
+      }
+      if (typeof window !== "undefined") {
+        return new URL(url, window.location.href).origin;
+      }
+      return "";
+    } catch {
+      return "";
+    }
+  }
+  /**
+   * Check if a target origin matches any of the configured origins
+   *
+   * Uses substring matching for flexibility (e.g., "example.com" matches "https://api.example.com")
+   *
+   * @param targetOrigin - Origin to check
+   * @param configuredOrigins - List of allowed or blocked origins
+   * @returns true if any origin matches
+   */
+  matchesAnyOrigin(targetOrigin, configuredOrigins) {
+    return configuredOrigins.some((configuredOrigin) => {
+      const normalizedTarget = targetOrigin.toLowerCase();
+      const normalizedConfigured = configuredOrigin.toLowerCase();
+      return normalizedTarget.includes(normalizedConfigured);
+    });
+  }
+};
+function getDenialReason(privacyManager2, url) {
+  const config2 = privacyManager2.config;
+  if (config2.respectDoNotTrack && typeof navigator !== "undefined") {
+    if (navigator.doNotTrack === "1") {
+      return "Do Not Track is enabled";
+    }
+  }
+  if (config2.respectGPC && typeof navigator !== "undefined") {
+    const nav = navigator;
+    if (nav.globalPrivacyControl === true) {
+      return "Global Privacy Control is enabled";
+    }
+  }
+  let targetOrigin = "";
+  try {
+    if (url.startsWith("http://") || url.startsWith("https://")) {
+      targetOrigin = new URL(url).origin;
+    } else if (typeof window !== "undefined") {
+      targetOrigin = new URL(url, window.location.href).origin;
+    }
+  } catch {
+    return "Invalid URL";
+  }
+  if (config2.blockedOrigins) {
+    const blocked = config2.blockedOrigins.some(
+      (origin) => targetOrigin.toLowerCase().includes(origin.toLowerCase())
+    );
+    if (blocked) {
+      return `Origin ${targetOrigin} is in blockedOrigins list`;
+    }
+  }
+  if (config2.allowedOrigins && config2.allowedOrigins.length > 0) {
+    const allowed = config2.allowedOrigins.some(
+      (origin) => targetOrigin.toLowerCase().includes(origin.toLowerCase())
+    );
+    if (!allowed) {
+      return `Origin ${targetOrigin} is not in allowedOrigins list`;
+    }
+  }
+  return null;
+}
+
+// src/init.ts
+var isInitialized = false;
+var config;
+var privacyManager;
+var originalFetch;
+var originalXHROpen;
+var originalXHRSetRequestHeader;
+function init(userConfig) {
+  if (typeof window === "undefined") {
+    return;
+  }
+  if (isInitialized) {
+    if (userConfig.debug) {
+      console.warn("[autotel-web] Already initialized. Skipping.");
+    }
+    return;
+  }
+  validateConfig(userConfig);
+  config = userConfig;
+  if (config.privacy) {
+    privacyManager = new PrivacyManager(config.privacy);
+  }
+  if (config.instrumentFetch !== false) {
+    patchFetch();
+  }
+  if (config.instrumentXHR !== false) {
+    patchXMLHttpRequest();
+  }
+  isInitialized = true;
+  if (config.debug) {
+    console.log("[autotel-web] Initialized successfully", {
+      service: config.service,
+      instrumentFetch: config.instrumentFetch !== false,
+      instrumentXHR: config.instrumentXHR !== false,
+      privacyEnabled: !!config.privacy,
+      privacyConfig: config.privacy ? {
+        allowedOrigins: config.privacy.allowedOrigins?.length ?? 0,
+        blockedOrigins: config.privacy.blockedOrigins?.length ?? 0,
+        respectDoNotTrack: config.privacy.respectDoNotTrack ?? false,
+        respectGPC: config.privacy.respectGPC ?? false
+      } : null
+    });
+  }
+}
+function patchFetch() {
+  originalFetch = window.fetch.bind(window);
+  window.fetch = function(input, init2) {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+    const headers = new Headers(init2?.headers);
+    if (!headers.has("traceparent")) {
+      if (privacyManager && !privacyManager.shouldInjectTraceparent(url)) {
+        if (config?.debug) {
+          const reason = getDenialReason(privacyManager, url);
+          console.log(
+            "[autotel-web] Skipped traceparent on fetch (privacy):",
+            url,
+            reason
+          );
+        }
+      } else {
+        headers.set("traceparent", createTraceparent());
+        if (config?.debug) {
+          console.log(
+            "[autotel-web] Injected traceparent on fetch:",
+            url,
+            headers.get("traceparent")
+          );
+        }
+      }
+    }
+    return originalFetch(input, { ...init2, headers });
+  };
+}
+function patchXMLHttpRequest() {
+  originalXHROpen = XMLHttpRequest.prototype.open;
+  originalXHRSetRequestHeader = XMLHttpRequest.prototype.setRequestHeader;
+  const xhrHasTraceparent = /* @__PURE__ */ new WeakSet();
+  XMLHttpRequest.prototype.setRequestHeader = function(name, value) {
+    if (name.toLowerCase() === "traceparent") {
+      xhrHasTraceparent.add(this);
+    }
+    return originalXHRSetRequestHeader.call(this, name, value);
+  };
+  XMLHttpRequest.prototype.open = function(method, url, async = true, username, password) {
+    const result = originalXHROpen.call(this, method, url, async, username, password);
+    const urlStr = typeof url === "string" ? url : url.toString();
+    const xhr = this;
+    const originalOnReadyStateChange = xhr.onreadystatechange;
+    xhr.onreadystatechange = function(event) {
+      if (xhr.readyState === XMLHttpRequest.OPENED) {
+        if (!xhrHasTraceparent.has(xhr)) {
+          if (privacyManager && !privacyManager.shouldInjectTraceparent(urlStr)) {
+            if (config?.debug) {
+              const reason = getDenialReason(privacyManager, urlStr);
+              console.log(
+                "[autotel-web] Skipped traceparent on XHR (privacy):",
+                urlStr,
+                reason
+              );
+            }
+          } else {
+            try {
+              const traceparent = createTraceparent();
+              originalXHRSetRequestHeader.call(xhr, "traceparent", traceparent);
+              if (config?.debug) {
+                console.log(
+                  "[autotel-web] Injected traceparent on XHR:",
+                  urlStr,
+                  traceparent
+                );
+              }
+            } catch (error) {
+              if (config?.debug) {
+                console.warn(
+                  "[autotel-web] Failed to inject traceparent on XHR:",
+                  error
+                );
+              }
+            }
+          }
+        }
+      }
+      if (originalOnReadyStateChange) {
+        return originalOnReadyStateChange.call(xhr, event);
+      }
+    };
+    return result;
+  };
+}
+function validateConfig(userConfig) {
+  if (!userConfig.service || typeof userConfig.service !== "string") {
+    throw new Error("[autotel-web] service name is required and must be a string");
+  }
+  if (userConfig.service.length === 0) {
+    throw new Error("[autotel-web] service name cannot be empty");
+  }
+  if (userConfig.service.length > 255) {
+    console.warn(
+      "[autotel-web] service name is very long (> 255 chars). Consider using a shorter name."
+    );
+  }
+  if (userConfig.privacy) {
+    const { allowedOrigins, blockedOrigins } = userConfig.privacy;
+    if ((!allowedOrigins || allowedOrigins.length === 0) && (!blockedOrigins || blockedOrigins.length === 0) && !userConfig.privacy.respectDoNotTrack && !userConfig.privacy.respectGPC) {
+      console.warn(
+        "[autotel-web] privacy config provided but all options are empty/disabled. This has no effect."
+      );
+    }
+    if (allowedOrigins && blockedOrigins) {
+      const overlap = allowedOrigins.filter(
+        (allowed) => blockedOrigins.some(
+          (blocked) => allowed.toLowerCase().includes(blocked.toLowerCase())
+        )
+      );
+      if (overlap.length > 0) {
+        console.warn(
+          "[autotel-web] Some allowedOrigins match blockedOrigins. Blocklist takes precedence:",
+          overlap
+        );
+      }
+    }
+    const allOrigins = [
+      ...allowedOrigins ?? [],
+      ...blockedOrigins ?? []
+    ];
+    allOrigins.forEach((origin) => {
+      if (origin.includes("://")) {
+        console.warn(
+          `[autotel-web] Origin "${origin}" includes protocol (://) - this is usually not needed. Just use the domain name.`
+        );
+      }
+    });
+  }
+}
+
+// src/functional.ts
+var currentContext;
+function trace(fn) {
+  const expectsContext = isFactoryPattern(fn);
+  if (expectsContext) {
+    return ((...args) => {
+      const ctx = createContext();
+      const actualFn = fn(ctx);
+      return actualFn(...args);
+    });
+  }
+  return fn;
+}
+function isFactoryPattern(fn) {
+  if (typeof fn !== "function") return false;
+  const fnStr = fn.toString();
+  const contextHints = ["ctx", "context", "traceContext"];
+  return contextHints.some((hint) => {
+    const regex = new RegExp(`^\\s*(?:async\\s+)?(?:function\\s*)?\\(?\\s*${hint}\\s*[,)]`);
+    return regex.test(fnStr);
+  });
+}
+function createContext() {
+  const traceparent = createTraceparent();
+  const parsed = parseTraceparent(traceparent);
+  if (!parsed) {
+    return {
+      traceId: "",
+      spanId: "",
+      correlationId: ""
+    };
+  }
+  const ctx = {
+    traceId: parsed.traceId,
+    spanId: parsed.spanId,
+    correlationId: parsed.traceId
+  };
+  currentContext = ctx;
+  return ctx;
+}
+function getActiveContext() {
+  return currentContext;
+}
+function getTraceparent() {
+  return createTraceparent();
+}
+function extractContext(traceparent) {
+  const parsed = parseTraceparent(traceparent);
+  if (!parsed) return void 0;
+  return {
+    traceId: parsed.traceId,
+    spanId: parsed.spanId,
+    correlationId: parsed.traceId
+  };
+}
+
+export { createTraceparent, extractContext, generateSpanId, generateTraceId, getActiveContext, getTraceparent, init, parseTraceparent, trace };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map