@squasher-ai/browser-logger 0.2.0 → 0.3.0

package/dist/_vendor/result-runtime/attempt.d.ts

@@ -0,0 +1,17 @@
+export interface AttemptFailure<TCause = Error> {
+    cause: TCause;
+    error: Error;
+}
+export interface AttemptOptions<TTry, TCatch = TTry, TCause = Error> {
+    try: () => TTry;
+    catch: (failure: AttemptFailure<TCause>) => TCatch;
+    finally?: () => void;
+}
+export interface AttemptAsyncOptions<TTry, TCatch = TTry, TCause = Error> {
+    try: () => Promise<TTry>;
+    catch: (failure: AttemptFailure<TCause>) => Promise<TCatch> | TCatch;
+    finally?: () => Promise<void> | void;
+}
+export declare function toError<T>(cause: T, fallbackMessage?: string): Error;
+export declare function attempt<TTry, TCatch = TTry, TCause = Error>(options: AttemptOptions<TTry, TCatch, TCause>): TTry | TCatch;
+export declare function attemptAsync<TTry, TCatch = TTry, TCause = Error>(options: AttemptAsyncOptions<TTry, TCatch, TCause>): Promise<TTry | TCatch>;

package/dist/_vendor/result-runtime/attempt.js

@@ -0,0 +1,62 @@
+export function toError(cause, fallbackMessage = "Unexpected error") {
+    if (cause instanceof Error)
+        return cause;
+    const nestedError = readProperty(cause, "error");
+    if (nestedError instanceof Error)
+        return nestedError;
+    const messageValue = readProperty(cause, "message");
+    if (Object.prototype.toString.call(messageValue) === "[object String]") {
+        const message = String(messageValue);
+        if (message.length > 0)
+            return new Error(message);
+    }
+    if (Object.prototype.toString.call(cause) === "[object String]") {
+        const message = String(cause);
+        if (message.length > 0)
+            return new Error(message);
+    }
+    return new Error(fallbackMessage, { cause });
+}
+function readProperty(owner, key) {
+    try {
+        const target = Object(owner);
+        let cursor = target;
+        while (cursor) {
+            const descriptor = Object.getOwnPropertyDescriptor(cursor, key);
+            if (descriptor) {
+                return "value" in descriptor ? descriptor.value : descriptor.get?.call(target);
+            }
+            cursor = Object.getPrototypeOf(cursor);
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function attempt(options) {
+    try {
+        return options.try();
+    }
+    catch (cause) {
+        // SAFETY: `TCause` is the caller-selected type for the catch channel.
+        const preservedCause = cause;
+        return options.catch({ cause: preservedCause, error: toError(preservedCause) });
+    }
+    finally {
+        options.finally?.();
+    }
+}
+export async function attemptAsync(options) {
+    try {
+        return await options.try();
+    }
+    catch (cause) {
+        // SAFETY: `TCause` is the caller-selected type for the catch channel.
+        const preservedCause = cause;
+        return await options.catch({ cause: preservedCause, error: toError(preservedCause) });
+    }
+    finally {
+        await options.finally?.();
+    }
+}

package/dist/_vendor/sdk-runtime/batching/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Batching primitives used by Squasher SDKs.
+ *
+ * The 1 MB default keeps request bodies bounded while amortizing per-request
+ * overhead. Callers may choose a lower limit when their runtime requires one.
+ */
+/** Maximum serialized SDK batch body, in bytes. */
+export declare const MAX_BATCH_BODY_BYTES = 1000000;
+export interface BuildBatchesOptions<TItem> {
+    /**
+     * Static JSON immediately before the comma-separated serialized items.
+     * Keeping the envelope split lets the builder serialize each item once
+     * instead of repeatedly serializing a growing candidate array.
+     */
+    batchPrefix: string;
+    /** Static JSON immediately after the serialized items. */
+    batchSuffix: string;
+    /**
+     * Serialize a single item (no wrapper). Called when a batch of size 1 is
+     * flushed. Lets SDKs send `{...event}` instead of `{events: [{...}]}` for
+     * single-event flushes — half the bytes for the common case.
+     */
+    serializeSingle: (item: TItem) => string;
+    /** Override the default 1_000_000-byte ceiling (for tests). */
+    maxBatchBodyBytes?: number;
+}
+export interface BuiltBatch {
+    /** The exact request body (already serialized). */
+    body: string;
+    /** Number of items in this batch. */
+    itemCount: number;
+}
+/**
+ * Greedy batching: walk the items in order, adding each to the current batch
+ * unless doing so would exceed `MAX_BATCH_BODY_BYTES`. When it would, flush
+ * the current batch and start a new one with the offending item.
+ *
+ * An item that is itself larger than the limit becomes a single-item batch
+ * regardless — callers are expected to drop or split oversized items at a
+ * higher layer; this function does not silently drop data.
+ */
+export declare function buildBatches<TItem>(items: TItem[], options: BuildBatchesOptions<TItem>): BuiltBatch[];

package/dist/_vendor/sdk-runtime/batching/index.js

@@ -0,0 +1,48 @@
+/**
+ * Batching primitives used by Squasher SDKs.
+ *
+ * The 1 MB default keeps request bodies bounded while amortizing per-request
+ * overhead. Callers may choose a lower limit when their runtime requires one.
+ */
+/** Maximum serialized SDK batch body, in bytes. */
+export const MAX_BATCH_BODY_BYTES = 1_000_000;
+const BODY_ENCODER = new TextEncoder();
+/**
+ * Greedy batching: walk the items in order, adding each to the current batch
+ * unless doing so would exceed `MAX_BATCH_BODY_BYTES`. When it would, flush
+ * the current batch and start a new one with the offending item.
+ *
+ * An item that is itself larger than the limit becomes a single-item batch
+ * regardless — callers are expected to drop or split oversized items at a
+ * higher layer; this function does not silently drop data.
+ */
+export function buildBatches(items, options) {
+    const max = options.maxBatchBodyBytes ?? MAX_BATCH_BODY_BYTES;
+    const batches = [];
+    let current = [];
+    const envelopeBytes = BODY_ENCODER.encode(options.batchPrefix).length +
+        BODY_ENCODER.encode(options.batchSuffix).length;
+    let currentBodyBytes = envelopeBytes;
+    const flush = () => {
+        if (current.length === 0)
+            return;
+        const body = current.length === 1
+            ? current[0]
+            : `${options.batchPrefix}${current.join(",")}${options.batchSuffix}`;
+        batches.push({ body, itemCount: current.length });
+        current = [];
+        currentBodyBytes = envelopeBytes;
+    };
+    for (const item of items) {
+        const serialized = options.serializeSingle(item);
+        const serializedBytes = BODY_ENCODER.encode(serialized).length;
+        const separatorBytes = current.length === 0 ? 0 : 1;
+        if (current.length > 0 && currentBodyBytes + separatorBytes + serializedBytes > max) {
+            flush();
+        }
+        currentBodyBytes += (current.length === 0 ? 0 : 1) + serializedBytes;
+        current.push(serialized);
+    }
+    flush();
+    return batches;
+}

package/dist/_vendor/sdk-runtime/errors/headers.d.ts

@@ -0,0 +1,6 @@
+export type HeaderMap = Record<string, string>;
+export interface HeaderLike {
+    get(name: string): string | null;
+}
+export type HeaderSource = HeaderLike | HeaderMap;
+export declare function readHeader(headers: HeaderSource | undefined, name: string): string | undefined;

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

@@ -0,0 +1,44 @@
+export function readHeader(headers, name) {
+    if (!headers)
+        return undefined;
+    const get = readProperty(headers, "get");
+    if (isHeaderGetter(get)) {
+        try {
+            const value = get.call(headers, name);
+            return Object.prototype.toString.call(value) === "[object String]"
+                ? String(value)
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const normalizedName = name.toLowerCase();
+    for (const [key, value] of Object.entries(Object(headers))) {
+        if (key.toLowerCase() === normalizedName &&
+            Object.prototype.toString.call(value) === "[object String]") {
+            return String(value);
+        }
+    }
+    return undefined;
+}
+function isHeaderGetter(value) {
+    return Object.prototype.toString.call(value) === "[object Function]";
+}
+function readProperty(owner, key) {
+    try {
+        const target = Object(owner);
+        let cursor = target;
+        while (cursor) {
+            const descriptor = Object.getOwnPropertyDescriptor(cursor, key);
+            if (descriptor) {
+                return "value" in descriptor ? descriptor.value : descriptor.get?.call(target);
+            }
+            cursor = Object.getPrototypeOf(cursor);
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/_vendor/sdk-runtime/errors/index.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Typed error hierarchy for Squasher SDKs. Status-specific subclasses retain
+ * `SquasherApiError` as their common parent.
+ */
+import { type HeaderSource } from "./headers.js";
+export type { HeaderLike } from "./headers.js";
+export interface ParsedErrorBody {
+    /** Squasher API convention: `{ error: "human readable message" }`. */
+    error?: string;
+    /** Optional structured message supplied by an API response. */
+    message?: string;
+    /** Optional structured error code supplied by an API response. */
+    code?: string;
+}
+/**
+ * Lookup that works for both the WHATWG `Headers` instance and a plain
+ * `Record<string, string>`. The api-client used to be Headers-only; SDK code
+ * sometimes hands us a plain object, so accept both.
+ */
+/** Root of every Squasher SDK error. Lets callers `catch (e: SquasherError)`. */
+export declare class SquasherError extends Error {
+    constructor(message: string);
+}
+/**
+ * Base class for every error returned by the Squasher API. Status-specific
+ * subclasses extend this; checks against `SquasherApiError` continue to match
+ * any of them.
+ */
+export declare class SquasherApiError extends SquasherError {
+    readonly status: number;
+    readonly body: ParsedErrorBody | null;
+    readonly requestId: string | undefined;
+    constructor(status: number, body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+    /**
+     * Map an HTTP status to the most specific subclass. Falls back to the
+     * generic `SquasherApiError` for unrecognised statuses (e.g. 418).
+     * Network/abort failures throw `SquasherConnectionError` /
+     * `SquasherUserAbortError` instead — those never go through here.
+     */
+    static generate(status: number, body: ParsedErrorBody | null, fallbackMessage: string, headers?: HeaderSource): SquasherApiError;
+}
+export declare class BadRequestError extends SquasherApiError {
+    readonly status: 400;
+    constructor(body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+export declare class AuthenticationError extends SquasherApiError {
+    readonly status: 401;
+    constructor(body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+export declare class PermissionDeniedError extends SquasherApiError {
+    readonly status: 403;
+    constructor(body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+export declare class NotFoundError extends SquasherApiError {
+    readonly status: 404;
+    constructor(body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+export declare class ConflictError extends SquasherApiError {
+    readonly status: 409;
+    constructor(body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+export declare class UnprocessableEntityError extends SquasherApiError {
+    readonly status: 422;
+    constructor(body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+export declare class RateLimitError extends SquasherApiError {
+    readonly status: 429;
+    constructor(body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+/** 5xx — keeps the actual status because the spread is too wide for a const. */
+export declare class InternalServerError extends SquasherApiError {
+    constructor(status: number, body: ParsedErrorBody | null, message: string, headers?: HeaderSource);
+}
+/** Network-level failure (DNS, connection refused, TLS). */
+export declare class SquasherConnectionError extends SquasherError {
+    readonly cause?: Error | undefined;
+    constructor(message: string, cause?: Error | undefined);
+}
+/** Specifically a connect-or-read timeout. Subclasses ConnectionError on purpose. */
+export declare class SquasherConnectionTimeoutError extends SquasherConnectionError {
+    constructor(message?: string);
+}
+/** AbortController.abort() raised; surfaced separately so retry loops skip it. */
+export declare class SquasherUserAbortError extends SquasherError {
+    constructor(message?: string);
+}
+/**
+ * Thrown when a Standard Webhooks payload fails signature verification —
+ * unknown or rotated secret, tampered body, replayed/expired timestamp,
+ * or malformed signature header. Extends SquasherError directly (not
+ * SquasherApiError) because webhook failures are not HTTP responses.
+ */
+export declare class InvalidWebhookSignatureError extends SquasherError {
+    constructor(message: string);
+}

package/dist/_vendor/sdk-runtime/errors/index.js

@@ -0,0 +1,157 @@
+/**
+ * Typed error hierarchy for Squasher SDKs. Status-specific subclasses retain
+ * `SquasherApiError` as their common parent.
+ */
+import { readHeader } from "./headers.js";
+/**
+ * Lookup that works for both the WHATWG `Headers` instance and a plain
+ * `Record<string, string>`. The api-client used to be Headers-only; SDK code
+ * sometimes hands us a plain object, so accept both.
+ */
+/** Root of every Squasher SDK error. Lets callers `catch (e: SquasherError)`. */
+export class SquasherError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SquasherError";
+    }
+}
+/**
+ * Base class for every error returned by the Squasher API. Status-specific
+ * subclasses extend this; checks against `SquasherApiError` continue to match
+ * any of them.
+ */
+export class SquasherApiError extends SquasherError {
+    status;
+    body;
+    requestId;
+    constructor(status, body, message, headers) {
+        super(buildMessage(body, message));
+        this.name = "SquasherApiError";
+        this.status = status;
+        this.body = body;
+        this.requestId = readHeader(headers, "x-request-id");
+    }
+    /**
+     * Map an HTTP status to the most specific subclass. Falls back to the
+     * generic `SquasherApiError` for unrecognised statuses (e.g. 418).
+     * Network/abort failures throw `SquasherConnectionError` /
+     * `SquasherUserAbortError` instead — those never go through here.
+     */
+    static generate(status, body, fallbackMessage, headers) {
+        if (status === 400)
+            return new BadRequestError(body, fallbackMessage, headers);
+        if (status === 401)
+            return new AuthenticationError(body, fallbackMessage, headers);
+        if (status === 403)
+            return new PermissionDeniedError(body, fallbackMessage, headers);
+        if (status === 404)
+            return new NotFoundError(body, fallbackMessage, headers);
+        if (status === 409)
+            return new ConflictError(body, fallbackMessage, headers);
+        if (status === 422)
+            return new UnprocessableEntityError(body, fallbackMessage, headers);
+        if (status === 429)
+            return new RateLimitError(body, fallbackMessage, headers);
+        if (status >= 500)
+            return new InternalServerError(status, body, fallbackMessage, headers);
+        return new SquasherApiError(status, body, fallbackMessage, headers);
+    }
+}
+function buildMessage(body, fallback) {
+    if (body?.error)
+        return body.error;
+    if (body?.message)
+        return body.message;
+    return fallback;
+}
+export class BadRequestError extends SquasherApiError {
+    status = 400;
+    constructor(body, message, headers) {
+        super(400, body, message, headers);
+        this.name = "BadRequestError";
+    }
+}
+export class AuthenticationError extends SquasherApiError {
+    status = 401;
+    constructor(body, message, headers) {
+        super(401, body, message, headers);
+        this.name = "AuthenticationError";
+    }
+}
+export class PermissionDeniedError extends SquasherApiError {
+    status = 403;
+    constructor(body, message, headers) {
+        super(403, body, message, headers);
+        this.name = "PermissionDeniedError";
+    }
+}
+export class NotFoundError extends SquasherApiError {
+    status = 404;
+    constructor(body, message, headers) {
+        super(404, body, message, headers);
+        this.name = "NotFoundError";
+    }
+}
+export class ConflictError extends SquasherApiError {
+    status = 409;
+    constructor(body, message, headers) {
+        super(409, body, message, headers);
+        this.name = "ConflictError";
+    }
+}
+export class UnprocessableEntityError extends SquasherApiError {
+    status = 422;
+    constructor(body, message, headers) {
+        super(422, body, message, headers);
+        this.name = "UnprocessableEntityError";
+    }
+}
+export class RateLimitError extends SquasherApiError {
+    status = 429;
+    constructor(body, message, headers) {
+        super(429, body, message, headers);
+        this.name = "RateLimitError";
+    }
+}
+/** 5xx — keeps the actual status because the spread is too wide for a const. */
+export class InternalServerError extends SquasherApiError {
+    constructor(status, body, message, headers) {
+        super(status, body, message, headers);
+        this.name = "InternalServerError";
+    }
+}
+/** Network-level failure (DNS, connection refused, TLS). */
+export class SquasherConnectionError extends SquasherError {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "SquasherConnectionError";
+    }
+}
+/** Specifically a connect-or-read timeout. Subclasses ConnectionError on purpose. */
+export class SquasherConnectionTimeoutError extends SquasherConnectionError {
+    constructor(message = "Request timed out") {
+        super(message);
+        this.name = "SquasherConnectionTimeoutError";
+    }
+}
+/** AbortController.abort() raised; surfaced separately so retry loops skip it. */
+export class SquasherUserAbortError extends SquasherError {
+    constructor(message = "Request was aborted") {
+        super(message);
+        this.name = "SquasherUserAbortError";
+    }
+}
+/**
+ * Thrown when a Standard Webhooks payload fails signature verification —
+ * unknown or rotated secret, tampered body, replayed/expired timestamp,
+ * or malformed signature header. Extends SquasherError directly (not
+ * SquasherApiError) because webhook failures are not HTTP responses.
+ */
+export class InvalidWebhookSignatureError extends SquasherError {
+    constructor(message) {
+        super(message);
+        this.name = "InvalidWebhookSignatureError";
+    }
+}

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

@@ -0,0 +1,48 @@
+/**
+ * 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.
+ */
+export interface DefaultHeadersOptions {
+    /** npm package name (e.g. "@squasher-ai/client", "@squasher-ai/node"). */
+    packageName: string;
+    /** Semver of the package shipping the request. */
+    packageVersion: string;
+}
+export interface RequestHeaderOptions {
+    /** Retry attempt count. Set to 0 on first attempt; incremented per retry. */
+    retryCount?: number;
+    /** Per-request timeout in milliseconds, surfaced as seconds in the header. */
+    timeoutMs?: number;
+}
+export interface TelemetryHeaders {
+    [name: string]: string;
+}
+/**
+ * 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 declare function getDefaultHeaders(opts: DefaultHeadersOptions): TelemetryHeaders;
+/**
+ * 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 declare function getRequestHeaders(opts: RequestHeaderOptions): TelemetryHeaders;
+/** Build the SDK User-Agent string used by standard HTTP access logs. */
+export declare function getUserAgent(opts: DefaultHeadersOptions): string;
+/** Header names used by SDK tests and request integrations. */
+export declare const HEADER_NAMES: {
+    readonly lang: "X-Squasher-Lang";
+    readonly package: "X-Squasher-Package";
+    readonly packageVersion: "X-Squasher-Package-Version";
+    readonly os: "X-Squasher-OS";
+    readonly arch: "X-Squasher-Arch";
+    readonly runtime: "X-Squasher-Runtime";
+    readonly runtimeVersion: "X-Squasher-Runtime-Version";
+    readonly retryCount: "X-Squasher-Retry-Count";
+    readonly timeout: "X-Squasher-Timeout";
+};

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;