@squasher-ai/browser 0.1.1 → 0.3.0

package/dist/_vendor/sdk-runtime/headers.js

@@ -0,0 +1,67 @@
+/**
+ * Default telemetry headers attached to every SDK-originated HTTP request.
+ *
+ * Every request identifies the language, package, package version, OS,
+ * architecture, and runtime. Retry count and timeout are added per request.
+ */
+import { getPlatform } from "./platform.js";
+const HEADER_LANG = "X-Squasher-Lang";
+const HEADER_PACKAGE = "X-Squasher-Package";
+const HEADER_PACKAGE_VERSION = "X-Squasher-Package-Version";
+const HEADER_OS = "X-Squasher-OS";
+const HEADER_ARCH = "X-Squasher-Arch";
+const HEADER_RUNTIME = "X-Squasher-Runtime";
+const HEADER_RUNTIME_VERSION = "X-Squasher-Runtime-Version";
+const HEADER_RETRY_COUNT = "X-Squasher-Retry-Count";
+const HEADER_TIMEOUT = "X-Squasher-Timeout";
+/**
+ * Build the constant-per-process header set: lang, package, OS, arch, runtime.
+ * Cache the return value at the SDK-construction site rather than calling per
+ * request — platform detection is cached but header construction still
+ * allocates a fresh object.
+ */
+export function getDefaultHeaders(opts) {
+    const platform = getPlatform();
+    return {
+        [HEADER_LANG]: platform.lang,
+        [HEADER_PACKAGE]: opts.packageName,
+        [HEADER_PACKAGE_VERSION]: opts.packageVersion,
+        [HEADER_OS]: platform.os,
+        [HEADER_ARCH]: platform.arch,
+        [HEADER_RUNTIME]: platform.runtime,
+        [HEADER_RUNTIME_VERSION]: platform.runtimeVersion,
+    };
+}
+/**
+ * Build the per-request header overlay: retry count and timeout. Returned as
+ * a separate object so callers can spread it on top of `getDefaultHeaders()`.
+ * Omits any field whose source is undefined so we don't ship empty headers.
+ */
+export function getRequestHeaders(opts) {
+    const out = {};
+    if (opts.retryCount !== undefined && opts.retryCount > 0) {
+        out[HEADER_RETRY_COUNT] = String(opts.retryCount);
+    }
+    if (opts.timeoutMs !== undefined && opts.timeoutMs > 0) {
+        // Express the timeout in seconds with millisecond precision.
+        out[HEADER_TIMEOUT] = (opts.timeoutMs / 1000).toString();
+    }
+    return out;
+}
+/** Build the SDK User-Agent string used by standard HTTP access logs. */
+export function getUserAgent(opts) {
+    const { runtime, runtimeVersion, os, arch } = getPlatform();
+    return `${opts.packageName}/${opts.packageVersion} (${runtime}/${runtimeVersion}; ${os} ${arch})`;
+}
+/** Header names used by SDK tests and request integrations. */
+export const HEADER_NAMES = {
+    lang: HEADER_LANG,
+    package: HEADER_PACKAGE,
+    packageVersion: HEADER_PACKAGE_VERSION,
+    os: HEADER_OS,
+    arch: HEADER_ARCH,
+    runtime: HEADER_RUNTIME,
+    runtimeVersion: HEADER_RUNTIME_VERSION,
+    retryCount: HEADER_RETRY_COUNT,
+    timeout: HEADER_TIMEOUT,
+};

package/dist/_vendor/sdk-runtime/platform.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Runtime, OS, and architecture detection used by SDK request headers.
+ *
+ * Probes are wrapped in try/catch because locked-down runtimes can throw when
+ * global properties are read. Unknown values remain explicit.
+ */
+export type PlatformRuntime = "node" | "deno" | "bun" | "edge" | "workerd" | `browser:${string}` | "unknown";
+export type PlatformOs = "MacOS" | "Linux" | "Windows" | "FreeBSD" | "OpenBSD" | "iOS" | "Android" | "Unknown";
+export type PlatformArch = "x32" | "x64" | "arm" | "arm64" | "Unknown";
+export interface PlatformProperties {
+    /** Language family. Always "js" for any TypeScript/JavaScript SDK. */
+    lang: "js";
+    /** Concrete runtime identifier. */
+    runtime: PlatformRuntime;
+    /** Best-effort runtime version string ("20.10.0", "1.0.30", etc.) or "unknown". */
+    runtimeVersion: string;
+    /** Operating system. */
+    os: PlatformOs;
+    /** CPU architecture. */
+    arch: PlatformArch;
+}
+/**
+ * Detect the runtime, OS, arch, and version of the host JS environment.
+ *
+ * Detection order: Deno → Bun → Cloudflare workerd → generic Edge → Node →
+ * Browser → unknown. Earlier checks take precedence because some runtimes
+ * (Bun, Deno) also expose a `process` global for compatibility — we want the
+ * native identifier to win.
+ */
+export declare function detectPlatform(): PlatformProperties;
+export declare function getPlatform(): PlatformProperties;
+/** Reset cached detection for deterministic tests. */
+export declare function resetPlatformCacheForTesting(): void;

package/dist/_vendor/sdk-runtime/platform.js

@@ -0,0 +1,173 @@
+/**
+ * Runtime, OS, and architecture detection used by SDK request headers.
+ *
+ * Probes are wrapped in try/catch because locked-down runtimes can throw when
+ * global properties are read. Unknown values remain explicit.
+ */
+import { readGlobalProperty, readRuntimeProperty, readRuntimeString, } from "./runtime/environment.js";
+function nestedString(value, ...path) {
+    let current = value;
+    for (const name of path)
+        current = readRuntimeProperty(current, name);
+    return readRuntimeString(current);
+}
+function normalizeOs(platform) {
+    if (!platform)
+        return "Unknown";
+    if (platform === "darwin")
+        return "MacOS";
+    if (platform === "linux")
+        return "Linux";
+    if (platform === "win32")
+        return "Windows";
+    if (platform === "freebsd")
+        return "FreeBSD";
+    if (platform === "openbsd")
+        return "OpenBSD";
+    if (platform === "android")
+        return "Android";
+    return "Unknown";
+}
+function normalizeArch(arch) {
+    if (!arch)
+        return "Unknown";
+    if (arch === "x32" || arch === "ia32")
+        return "x32";
+    if (arch === "x64" || arch === "amd64")
+        return "x64";
+    if (arch === "arm")
+        return "arm";
+    if (arch === "arm64" || arch === "aarch64")
+        return "arm64";
+    return "Unknown";
+}
+const BROWSER_UA_PATTERNS = [
+    { key: "edge", re: /Edg(?:e|A|iOS)?\/(\d+(?:\.\d+)?)/ },
+    { key: "ie", re: /MSIE (\d+(?:\.\d+)?)/ },
+    { key: "ie", re: /Trident\/.*; rv:(\d+(?:\.\d+)?)/ },
+    { key: "chrome", re: /Chrome\/(\d+(?:\.\d+)?)/ },
+    { key: "firefox", re: /Firefox\/(\d+(?:\.\d+)?)/ },
+    { key: "safari", re: /Version\/(\d+(?:\.\d+)?).*Safari/ },
+];
+function detectBrowserFromUserAgent(ua) {
+    let os = "Unknown";
+    if (/Mac OS X/.test(ua))
+        os = "MacOS";
+    else if (/Windows/.test(ua))
+        os = "Windows";
+    else if (/Linux/.test(ua))
+        os = "Linux";
+    else if (/Android/.test(ua))
+        os = "Android";
+    else if (/iP(hone|ad|od)/.test(ua))
+        os = "iOS";
+    for (const { key, re } of BROWSER_UA_PATTERNS) {
+        const match = re.exec(ua);
+        if (match) {
+            return { runtime: `browser:${key}`, version: match[1] ?? "unknown", os };
+        }
+    }
+    return undefined;
+}
+/**
+ * Detect the runtime, OS, arch, and version of the host JS environment.
+ *
+ * Detection order: Deno → Bun → Cloudflare workerd → generic Edge → Node →
+ * Browser → unknown. Earlier checks take precedence because some runtimes
+ * (Bun, Deno) also expose a `process` global for compatibility — we want the
+ * native identifier to win.
+ */
+export function detectPlatform() {
+    // Deno
+    const deno = readGlobalProperty("Deno");
+    if (deno !== undefined && deno !== null) {
+        return {
+            lang: "js",
+            runtime: "deno",
+            runtimeVersion: nestedString(deno, "version", "deno") ?? "unknown",
+            os: normalizeOs(nestedString(deno, "build", "os")),
+            arch: normalizeArch(nestedString(deno, "build", "arch")),
+        };
+    }
+    // Bun
+    const bun = readGlobalProperty("Bun");
+    if (bun !== undefined && bun !== null) {
+        const process = readGlobalProperty("process");
+        return {
+            lang: "js",
+            runtime: "bun",
+            runtimeVersion: nestedString(bun, "version") ?? "unknown",
+            os: normalizeOs(nestedString(process, "platform")),
+            arch: normalizeArch(nestedString(process, "arch")),
+        };
+    }
+    // Cloudflare workerd (preferred over generic edge — gives us version when present)
+    const navigatorUserAgent = nestedString(readGlobalProperty("navigator"), "userAgent");
+    if (navigatorUserAgent && /Cloudflare-Workers/.test(navigatorUserAgent)) {
+        return {
+            lang: "js",
+            runtime: "workerd",
+            runtimeVersion: "unknown",
+            os: "Unknown",
+            arch: "Unknown",
+        };
+    }
+    // Generic edge (Vercel Edge, Next.js edge runtime, etc.)
+    const edgeRuntime = readGlobalProperty("EdgeRuntime");
+    if (edgeRuntime !== undefined) {
+        return {
+            lang: "js",
+            runtime: "edge",
+            runtimeVersion: readRuntimeString(edgeRuntime) ?? "unknown",
+            os: "Unknown",
+            arch: "Unknown",
+        };
+    }
+    // Node.js — duck-typed via release.name to avoid false positives on
+    // bundlers that polyfill `process` for browser code.
+    const process = readGlobalProperty("process");
+    if (nestedString(process, "release", "name") === "node") {
+        return {
+            lang: "js",
+            runtime: "node",
+            runtimeVersion: nestedString(process, "versions", "node") ?? nestedString(process, "version") ?? "unknown",
+            os: normalizeOs(nestedString(process, "platform")),
+            arch: normalizeArch(nestedString(process, "arch")),
+        };
+    }
+    // Browser
+    if (navigatorUserAgent) {
+        const match = detectBrowserFromUserAgent(navigatorUserAgent);
+        if (match) {
+            return {
+                lang: "js",
+                runtime: match.runtime,
+                runtimeVersion: match.version,
+                os: match.os,
+                arch: "Unknown",
+            };
+        }
+    }
+    return {
+        lang: "js",
+        runtime: "unknown",
+        runtimeVersion: "unknown",
+        os: "Unknown",
+        arch: "Unknown",
+    };
+}
+/**
+ * Cached platform properties — detection is stable across a process lifetime,
+ * so probing once and reusing the result keeps the per-request cost at zero.
+ * Tests that need a fresh probe can call `resetPlatformCacheForTesting()`.
+ */
+let cached;
+export function getPlatform() {
+    if (!cached)
+        cached = detectPlatform();
+    return cached;
+}
+/** Reset cached detection for deterministic tests. */
+export function resetPlatformCacheForTesting() {
+    cached = undefined;
+}

package/dist/_vendor/sdk-runtime/retry.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Retry primitives shared across Squasher SDKs.
+ *
+ * Server retry hints take precedence over exponential backoff with downward
+ * jitter. Aborts are never retried; network failures, timeouts, 408, 429, and
+ * 5xx responses are retryable by default.
+ */
+import { type HeaderSource } from "./errors/headers.js";
+export interface RetryDecisionInput {
+    /** HTTP response status, if a response was received. */
+    status?: number;
+    /** Response headers — supports either a fetch `Headers` or plain object. */
+    headers?: HeaderSource;
+    /** Error thrown by `fetch` itself (network failure / abort). */
+    thrown?: Error;
+}
+export type HeadersLike = Headers;
+/**
+ * Decide whether a response (or thrown error) should trigger a retry.
+ *
+ * Aborts always opt out — `AbortController.abort()` is user intent, not a
+ * transient failure. Connection errors always opt in. Status-code logic
+ * mirrors Stainless: 408/409/429 plus any 5xx, with `X-Should-Retry`
+ * override.
+ */
+export declare function shouldRetry(input: RetryDecisionInput): boolean;
+export interface BackoffOptions {
+    /** Zero-indexed retry attempt number. The first retry uses attempt = 0. */
+    attempt: number;
+    /** Response headers, used to honor Retry-After / Retry-After-Ms. */
+    headers?: HeaderSource;
+    /** Random source — injected for deterministic tests. Defaults to Math.random. */
+    random?: () => number;
+    /** Max sleep in ms. Defaults to 8000 to match Stainless. */
+    maxSleepMs?: number;
+    /** Reference time used to interpret HTTP-date `Retry-After` values. Tests inject. */
+    now?: () => number;
+}
+/**
+ * Compute the delay in milliseconds before the next attempt. Server-supplied
+ * hints win when present, otherwise falls back to exponential backoff with
+ * downward jitter.
+ *
+ * Returned value is always non-negative. Capped at `maxSleepMs` (default 8s)
+ * even when the server requests a longer retry — long sleeps almost always
+ * indicate the caller should reach for queueing instead of in-process retries.
+ */
+export declare function nextBackoffMs(opts: BackoffOptions): number;
+/** Promise-friendly setTimeout. Resolves after `ms` milliseconds. */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;

package/dist/_vendor/sdk-runtime/retry.js

@@ -0,0 +1,104 @@
+/**
+ * Retry primitives shared across Squasher SDKs.
+ *
+ * Server retry hints take precedence over exponential backoff with downward
+ * jitter. Aborts are never retried; network failures, timeouts, 408, 429, and
+ * 5xx responses are retryable by default.
+ */
+import { readHeader } from "./errors/headers.js";
+import { SquasherConnectionError, SquasherUserAbortError } from "./errors/index.js";
+// 408 = Request Timeout, 429 = Too Many Requests. 409 (Conflict) is
+// intentionally NOT included — for Squasher's ingest path, 409 means
+// "duplicate event detected by server dedup", and retrying creates extra
+// writes that re-trip the dedup. Servers that genuinely want a transient
+// 409 retried (e.g. optimistic-locking conflicts) can opt back in via
+// the `X-Should-Retry: true` response header.
+const RETRYABLE_STATUSES = new Set([408, 429]);
+/**
+ * Decide whether a response (or thrown error) should trigger a retry.
+ *
+ * Aborts always opt out — `AbortController.abort()` is user intent, not a
+ * transient failure. Connection errors always opt in. Status-code logic
+ * mirrors Stainless: 408/409/429 plus any 5xx, with `X-Should-Retry`
+ * override.
+ */
+export function shouldRetry(input) {
+    if (input.thrown instanceof SquasherUserAbortError)
+        return false;
+    if (input.thrown instanceof SquasherConnectionError)
+        return true;
+    if (input.thrown && input.status === undefined) {
+        // Unknown thrown value with no response — treat as transport failure.
+        return true;
+    }
+    const override = readHeader(input.headers, "x-should-retry");
+    if (override === "true")
+        return true;
+    if (override === "false")
+        return false;
+    if (input.status === undefined)
+        return false;
+    if (RETRYABLE_STATUSES.has(input.status))
+        return true;
+    if (input.status >= 500)
+        return true;
+    return false;
+}
+const DEFAULT_MAX_SLEEP_MS = 8_000;
+/**
+ * Compute the delay in milliseconds before the next attempt. Server-supplied
+ * hints win when present, otherwise falls back to exponential backoff with
+ * downward jitter.
+ *
+ * Returned value is always non-negative. Capped at `maxSleepMs` (default 8s)
+ * even when the server requests a longer retry — long sleeps almost always
+ * indicate the caller should reach for queueing instead of in-process retries.
+ */
+export function nextBackoffMs(opts) {
+    const max = opts.maxSleepMs ?? DEFAULT_MAX_SLEEP_MS;
+    const random = opts.random ?? Math.random;
+    const retryAfterMsHeader = readHeader(opts.headers, "retry-after-ms");
+    if (retryAfterMsHeader !== undefined) {
+        const ms = Number.parseFloat(retryAfterMsHeader);
+        if (Number.isFinite(ms) && ms >= 0)
+            return Math.min(ms, max);
+    }
+    const retryAfterHeader = readHeader(opts.headers, "retry-after");
+    if (retryAfterHeader !== undefined) {
+        const seconds = Number.parseFloat(retryAfterHeader);
+        if (Number.isFinite(seconds) && seconds >= 0) {
+            return Math.min(seconds * 1000, max);
+        }
+        // HTTP-date form (RFC 7231)
+        const dateMs = Date.parse(retryAfterHeader);
+        if (!Number.isNaN(dateMs)) {
+            const now = opts.now ? opts.now() : Date.now();
+            const delta = dateMs - now;
+            if (delta > 0)
+                return Math.min(delta, max);
+            return 0;
+        }
+    }
+    // Exponential backoff with downward jitter.
+    const baseSeconds = Math.min(0.5 * Math.pow(2, opts.attempt), max / 1000);
+    const jitter = 1 - random() * 0.25;
+    return Math.min(baseSeconds * 1000 * jitter, max);
+}
+/** Promise-friendly setTimeout. Resolves after `ms` milliseconds. */
+export function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(new SquasherUserAbortError());
+            return;
+        }
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new SquasherUserAbortError());
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/dist/_vendor/sdk-runtime/runtime/actionable-error.d.ts

@@ -0,0 +1,37 @@
+import { SquasherError } from "../errors/index.js";
+export type ActionableErrorValue = boolean | null | number | string;
+export type ActionableErrorInternal = Record<string, ActionableErrorValue | ActionableErrorValue[]>;
+interface ActionableErrorJson extends ActionableErrorContext {
+    message: string;
+    name: string;
+}
+export interface ActionableErrorContext {
+    status?: number | string;
+    why?: string;
+    fix?: string;
+    link?: string;
+    internal?: ActionableErrorInternal;
+}
+export interface ActionableErrorOptions extends ActionableErrorContext {
+    cause?: Error;
+    name?: string;
+}
+export interface ActionableErrorTelemetry {
+    attributes: Record<string, number | string>;
+    extra: {
+        squasher_error: ActionableErrorContext;
+    };
+}
+export declare class ActionableError extends SquasherError {
+    readonly status: number | string | undefined;
+    readonly why: string | undefined;
+    readonly fix: string | undefined;
+    readonly link: string | undefined;
+    readonly internal: ActionableErrorInternal | undefined;
+    constructor(message: string, options?: ActionableErrorOptions);
+    toJSON(): ActionableErrorJson;
+}
+export declare function createActionableError(message: string, options?: ActionableErrorOptions): ActionableError;
+export declare function getActionableErrorContext(error: Error): ActionableErrorContext | undefined;
+export declare function getActionableErrorTelemetry(error: Error): ActionableErrorTelemetry | undefined;
+export {};

package/dist/_vendor/sdk-runtime/runtime/actionable-error.js

@@ -0,0 +1,123 @@
+import { SquasherError } from "../errors/index.js";
+export class ActionableError extends SquasherError {
+    status;
+    why;
+    fix;
+    link;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = options.name ?? "ActionableError";
+        this.status = options.status;
+        this.why = options.why;
+        this.fix = options.fix;
+        this.link = options.link;
+        if (options.cause) {
+            Object.defineProperty(this, "cause", { value: options.cause });
+        }
+        Object.defineProperty(this, "internal", {
+            enumerable: false,
+            value: readInternal(options.internal),
+        });
+    }
+    toJSON() {
+        const result = { message: this.message, name: this.name };
+        if (this.status !== undefined)
+            result.status = this.status;
+        if (this.why)
+            result.why = this.why;
+        if (this.fix)
+            result.fix = this.fix;
+        if (this.link)
+            result.link = this.link;
+        return result;
+    }
+}
+export function createActionableError(message, options = {}) {
+    return new ActionableError(message, options);
+}
+export function getActionableErrorContext(error) {
+    const internal = readInternal(readProperty(error, "internal"));
+    const context = {
+        status: readStatus(readProperty(error, "status")),
+        why: readText(readProperty(error, "why")),
+        fix: readText(readProperty(error, "fix")),
+        link: readText(readProperty(error, "link")),
+        internal,
+    };
+    return context.status !== undefined || context.why || context.fix || context.link || internal
+        ? context
+        : undefined;
+}
+export function getActionableErrorTelemetry(error) {
+    const context = getActionableErrorContext(error);
+    if (!context)
+        return undefined;
+    const attributes = {};
+    if (context.status !== undefined)
+        attributes["error.status"] = context.status;
+    if (context.why)
+        attributes["error.why"] = context.why;
+    if (context.fix)
+        attributes["error.fix"] = context.fix;
+    if (context.link)
+        attributes["error.link"] = context.link;
+    return { attributes, extra: { squasher_error: context } };
+}
+function readProperty(error, name) {
+    try {
+        const owner = Object(error);
+        let cursor = owner;
+        while (cursor) {
+            const descriptor = Object.getOwnPropertyDescriptor(cursor, name);
+            if (descriptor) {
+                return "value" in descriptor ? descriptor.value : descriptor.get?.call(owner);
+            }
+            cursor = Object.getPrototypeOf(cursor);
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readText(value) {
+    if (Object.prototype.toString.call(value) !== "[object String]")
+        return undefined;
+    const text = String(value).trim();
+    return text.length > 0 ? text : undefined;
+}
+function readStatus(value) {
+    const tag = Object.prototype.toString.call(value);
+    if (tag === "[object Number]") {
+        const number = Number(value);
+        return Number.isFinite(number) ? number : undefined;
+    }
+    if (tag === "[object String]")
+        return readText(value);
+    return undefined;
+}
+function readInternal(value) {
+    if (Object.prototype.toString.call(value) !== "[object Object]")
+        return undefined;
+    const internal = {};
+    for (const [key, entry] of Object.entries(Object(value))) {
+        const parsed = readInternalValue(entry);
+        if (parsed !== undefined)
+            internal[key] = parsed;
+    }
+    return Object.keys(internal).length > 0 ? internal : undefined;
+}
+function readInternalValue(value) {
+    if (Array.isArray(value)) {
+        const values = value.filter(isActionableValue);
+        return values.length > 0 ? values : undefined;
+    }
+    return isActionableValue(value) ? value : undefined;
+}
+function isActionableValue(value) {
+    const tag = Object.prototype.toString.call(value);
+    return (value === null ||
+        tag === "[object Boolean]" ||
+        tag === "[object Number]" ||
+        tag === "[object String]");
+}

package/dist/_vendor/sdk-runtime/runtime/environment.d.ts

@@ -0,0 +1,18 @@
+export type RuntimePrimitive = boolean | null | number | string;
+export type RuntimeValue = RuntimePrimitive | RuntimeValue[] | RuntimeRecord | undefined;
+export interface RuntimeRecord {
+    [key: string]: RuntimeValue;
+}
+export interface RuntimeMethod<TResult> {
+    (): TResult;
+}
+export interface RuntimeEnvironment {
+    [name: string]: string | undefined;
+}
+export declare function readGlobalProperty(name: string): RuntimeValue;
+export declare function readRuntimeProperty<T>(value: T, name: string): RuntimeValue;
+export declare function readRuntimeString<T>(value: T): string | undefined;
+export declare function readRuntimeNumber<T>(value: T): number | undefined;
+export declare function readRuntimeMethod<TResult, T = RuntimeValue>(value: T, name: PropertyKey): RuntimeMethod<TResult> | undefined;
+export declare function readProcessEnvironment(): RuntimeEnvironment;
+export declare function readGlobalEnvironmentValue(name: string): string | undefined;