whisp-js 0.0.0-stage → 0.3.0

package/dist/esm/refs.js

@@ -0,0 +1,33 @@
+/**
+ * Number references the SDK checks before any request (phase2-design 12.2):
+ * `phone` and `number(...)` take a phone in international form, as people
+ * write it (`+972 50-123-4567`), or a number id (`num_7Hq2kD3x`). The API
+ * takes the canonical form only (core's `parseNumberRef`: digits, or the id),
+ * so the SDK normalizes and a typo throws at construction instead of
+ * answering 404 NUMBER_NOT_IN_PROJECT on the first send.
+ */
+import { NUMBER_ID_PATTERN } from './constants.js';
+import { localError } from './errors.js';
+/** What people put between a phone's digits. Anything else is refused, not cleaned. */
+const SEPARATORS = /[\s\-.()]/g;
+/** E.164 digits: a country code first (never 0), 8 to 15 digits in all (parseNumberRef's range). */
+const PHONE_DIGITS = /^[1-9]\d{7,14}$/;
+/** The canonical reference (`972501234567` or `num_7Hq2kD3x`), or null for anything else. */
+export const normalizeNumberRef = (ref) => {
+    if (typeof ref !== 'string')
+        return null;
+    const trimmed = ref.trim();
+    if (NUMBER_ID_PATTERN.test(trimmed))
+        return trimmed;
+    const stripped = trimmed.replace(SEPARATORS, '');
+    const digits = stripped.startsWith('+') ? stripped.slice(1) : stripped;
+    return PHONE_DIGITS.test(digits) ? digits : null;
+};
+/** Like normalizeNumberRef, but throws PHONE_INVALID naming the value. */
+export const requireNumberRef = (ref, where) => {
+    const normalized = normalizeNumberRef(ref);
+    if (normalized !== null)
+        return normalized;
+    const shown = typeof ref === 'string' ? `'${ref.slice(0, 40)}'` : String(typeof ref);
+    throw localError('PHONE_INVALID', `${where}: ${shown} is not a phone in international form (972501234567) or a number id (num_7Hq2kD3x)`);
+};

package/dist/esm/runtime.d.ts

@@ -0,0 +1,24 @@
+/**
+ * An environment variable, trimmed, or undefined where there is none (Deno
+ * without `--allow-env` throws on access). Read when a call needs it, never at
+ * import (12.1), so a value set after import still counts.
+ */
+export declare const readEnv: (name: string) => string | undefined;
+/** A page with a DOM (5.3). Node, Bun, Deno and workers have neither global. */
+export declare const isBrowser: () => boolean;
+/** `bun/1.4.2`, `node/22.14.0`, `deno/2.1.0`. Bun also sets `process.versions.node`, so it is asked first. */
+export declare const runtimeTag: () => string;
+/** `whisp-sdk/<version> (<runtime>/<version>)`, the only identifying header the SDK sends (12.3). */
+export declare const userAgent: () => string;
+/** A v4 UUID: the default `Idempotency-Key` of a send (5.9). */
+export declare const randomId: () => string;
+/** Timers and randomness, injectable so tests can drive reconnects, backoff and watchdogs without waiting. */
+export interface Timers {
+    now(): number;
+    setTimeout(callback: () => void, ms: number): unknown;
+    clearTimeout(handle: unknown): void;
+    random(): number;
+}
+export declare const realTimers: Timers;
+/** Resolves after `ms`, or at once when `signal` aborts (it never rejects). */
+export declare const sleep: (timers: Timers, ms: number, signal?: AbortSignal) => Promise<void>;

package/dist/esm/runtime.js

@@ -0,0 +1,84 @@
+/**
+ * The few runtime facts the SDK needs, read from globals that Node 22.12+,
+ * Bun and Deno all have (phase2-design 12.1): no `node:` built-ins, so the
+ * same build runs everywhere `fetch`, Web Streams and Web Crypto exist.
+ */
+import { USER_AGENT_PREFIX } from './constants.js';
+import { SDK_VERSION } from './version.js';
+const runtimeGlobals = () => globalThis;
+/**
+ * An environment variable, trimmed, or undefined where there is none (Deno
+ * without `--allow-env` throws on access). Read when a call needs it, never at
+ * import (12.1), so a value set after import still counts.
+ */
+export const readEnv = (name) => {
+    try {
+        const value = runtimeGlobals().process?.env?.[name];
+        const trimmed = typeof value === 'string' ? value.trim() : '';
+        return trimmed || undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** A page with a DOM (5.3). Node, Bun, Deno and workers have neither global. */
+export const isBrowser = () => {
+    const g = runtimeGlobals();
+    return typeof g.window !== 'undefined' && typeof g.document !== 'undefined';
+};
+/** `bun/1.4.2`, `node/22.14.0`, `deno/2.1.0`. Bun also sets `process.versions.node`, so it is asked first. */
+export const runtimeTag = () => {
+    const g = runtimeGlobals();
+    try {
+        if (typeof g.Bun?.version === 'string')
+            return `bun/${g.Bun.version}`;
+        if (typeof g.Deno?.version?.deno === 'string')
+            return `deno/${g.Deno.version.deno}`;
+        const node = g.process?.versions?.node;
+        if (typeof node === 'string')
+            return `node/${node}`;
+    }
+    catch {
+        // A locked-down global: fall through.
+    }
+    return 'unknown';
+};
+/** `whisp-sdk/<version> (<runtime>/<version>)`, the only identifying header the SDK sends (12.3). */
+export const userAgent = () => `${USER_AGENT_PREFIX}/${SDK_VERSION} (${runtimeTag()})`;
+const hex = (bytes) => {
+    let out = '';
+    for (const byte of bytes)
+        out += byte.toString(16).padStart(2, '0');
+    return out;
+};
+/** A v4 UUID: the default `Idempotency-Key` of a send (5.9). */
+export const randomId = () => {
+    const webCrypto = globalThis.crypto;
+    if (typeof webCrypto?.randomUUID === 'function')
+        return webCrypto.randomUUID();
+    // randomUUID is missing on insecure (http) pages, where getRandomValues still works.
+    const bytes = new Uint8Array(16);
+    webCrypto.getRandomValues(bytes);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40;
+    bytes[8] = (bytes[8] & 0x3f) | 0x80;
+    const h = hex(bytes);
+    return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
+};
+export const realTimers = {
+    now: () => Date.now(),
+    setTimeout: (callback, ms) => setTimeout(callback, ms),
+    clearTimeout: handle => clearTimeout(handle),
+    random: () => Math.random(),
+};
+/** Resolves after `ms`, or at once when `signal` aborts (it never rejects). */
+export const sleep = (timers, ms, signal) => new Promise(resolve => {
+    if (signal?.aborted)
+        return resolve();
+    const done = () => {
+        timers.clearTimeout(handle);
+        signal?.removeEventListener('abort', done);
+        resolve();
+    };
+    const handle = timers.setTimeout(done, Math.max(0, ms));
+    signal?.addEventListener('abort', done, { once: true });
+});

package/dist/esm/sse.d.ts

@@ -0,0 +1,32 @@
+/**
+ * A small parser for `text/event-stream` (WHATWG HTML, "Server-sent events"),
+ * fed with the bytes of a fetch body (phase2-design 12.4). Not `EventSource`:
+ * Node doesn't ship one unflagged, and it can't send an `Authorization`
+ * header.
+ *
+ * Lines end with CRLF, LF or CR, and a chunk can end anywhere, between the CR
+ * and the LF of one break included. `id` here is the field of the event's own
+ * block, not the spec's sticky "last event id": the stream's `error` carries
+ * no `id`, `ready`'s is where the stream starts, a `ping`'s how far it has
+ * covered, and only a frame that carries one moves the SDK's cursor (6.5).
+ */
+export interface SseEvent {
+    /** `event:`, or `message` when the block had none. */
+    event: string;
+    /** The `data:` lines joined with LF. */
+    data: string;
+    /** The block's own `id:`, or undefined. */
+    id: string | undefined;
+}
+/** A line longer than this is not from our API (an event is at most about 130 KB); the stream is dropped. */
+export declare const MAX_LINE_CHARS: number;
+export declare class SseLineTooLongError extends Error {
+    readonly name = "SseLineTooLongError";
+}
+export interface SseParser {
+    /** The events completed by this chunk, in order. */
+    push(chunk: Uint8Array | string): SseEvent[];
+    /** The end of the stream: a block without its blank line is dropped, as the spec says. */
+    end(): SseEvent[];
+}
+export declare const createSseParser: () => SseParser;

package/dist/esm/sse.js

@@ -0,0 +1,100 @@
+/**
+ * A small parser for `text/event-stream` (WHATWG HTML, "Server-sent events"),
+ * fed with the bytes of a fetch body (phase2-design 12.4). Not `EventSource`:
+ * Node doesn't ship one unflagged, and it can't send an `Authorization`
+ * header.
+ *
+ * Lines end with CRLF, LF or CR, and a chunk can end anywhere, between the CR
+ * and the LF of one break included. `id` here is the field of the event's own
+ * block, not the spec's sticky "last event id": the stream's `error` carries
+ * no `id`, `ready`'s is where the stream starts, a `ping`'s how far it has
+ * covered, and only a frame that carries one moves the SDK's cursor (6.5).
+ */
+/** A line longer than this is not from our API (an event is at most about 130 KB); the stream is dropped. */
+export const MAX_LINE_CHARS = 4 * 1024 * 1024;
+export class SseLineTooLongError extends Error {
+    name = 'SseLineTooLongError';
+}
+export const createSseParser = () => {
+    // The default decoder drops a leading BOM, which the spec tells parsers to ignore.
+    const decoder = new TextDecoder();
+    let buffer = '';
+    let eventType = '';
+    let data = [];
+    let id;
+    const dispatch = (out) => {
+        if (data.length > 0)
+            out.push({ event: eventType || 'message', data: data.join('\n'), id });
+        eventType = '';
+        data = [];
+        id = undefined;
+    };
+    const processLine = (line, out) => {
+        if (line === '')
+            return dispatch(out);
+        if (line.startsWith(':'))
+            return; // a comment
+        const colon = line.indexOf(':');
+        const field = colon === -1 ? line : line.slice(0, colon);
+        let value = colon === -1 ? '' : line.slice(colon + 1);
+        if (value.startsWith(' '))
+            value = value.slice(1);
+        switch (field) {
+            case 'event':
+                eventType = value;
+                break;
+            case 'data':
+                data.push(value);
+                break;
+            case 'id':
+                // The spec ignores an id with a NULL in it.
+                if (!value.includes('\0'))
+                    id = value;
+                break;
+            default:
+            // `retry` and unknown fields: the SDK keeps its own reconnect schedule (12.4).
+        }
+    };
+    const drain = (final) => {
+        const out = [];
+        let start = 0;
+        for (;;) {
+            const lf = buffer.indexOf('\n', start);
+            const cr = buffer.indexOf('\r', start);
+            const at = lf === -1 ? cr : cr === -1 ? lf : Math.min(lf, cr);
+            if (at === -1)
+                break;
+            if (buffer[at] === '\r') {
+                // A CR at the end of the chunk may be half of a CRLF: wait for the next chunk to say.
+                if (at === buffer.length - 1 && !final)
+                    break;
+                processLine(buffer.slice(start, at), out);
+                start = buffer[at + 1] === '\n' ? at + 2 : at + 1;
+            }
+            else {
+                processLine(buffer.slice(start, at), out);
+                start = at + 1;
+            }
+        }
+        buffer = buffer.slice(start);
+        if (buffer.length > MAX_LINE_CHARS)
+            throw new SseLineTooLongError('An event stream line is too long');
+        return out;
+    };
+    return {
+        push(chunk) {
+            buffer += typeof chunk === 'string' ? chunk : decoder.decode(chunk, { stream: true });
+            return drain(false);
+        },
+        end() {
+            buffer += decoder.decode();
+            const out = drain(true);
+            // What is left is a line without its end, and the block it belongs to never got its blank line.
+            buffer = '';
+            eventType = '';
+            data = [];
+            id = undefined;
+            return out;
+        },
+    };
+};

package/dist/esm/transport.d.ts

@@ -0,0 +1,61 @@
+/**
+ * One API call with a timeout and retries (phase2-design 12.3).
+ *
+ * Retried: network errors, timeouts, 408, 429 and 5xx (but 501, which never
+ * changes), with full-jitter backoff (0.5 s base, 8 s cap), or exactly
+ * `Retry-After` when the API sends one, up to 60 s; a longer `Retry-After`
+ * fails at once with `retryAfter` set, rather than holding the caller for
+ * minutes. Never on other 4xx. Every attempt sends the same bytes and the
+ * same `Idempotency-Key`, so a retried send can't send twice (5.9).
+ *
+ * The token goes only to the API's origin: redirects are never followed
+ * (`redirect: 'manual'`), so a 3xx is an error, not a hop that might carry
+ * the `Authorization` header somewhere else.
+ */
+import { WhispError } from './errors.js';
+import { type Timers } from './runtime.js';
+/** Any WHATWG fetch: the global one, undici's, or a test's. */
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+export declare const BACKOFF_BASE_MS = 500;
+export declare const BACKOFF_CAP_MS = 8000;
+export declare const RETRY_AFTER_MAX_SECONDS = 60;
+export interface TransportConfig {
+    baseUrl: string;
+    token: string;
+    fetch: FetchLike;
+    userAgent: string;
+    /** Per attempt, the answer's body included. */
+    timeoutMs: number;
+    /** Attempts after the first. */
+    maxRetries: number;
+    timers: Timers;
+    /** Aborted by `close()`: a retry waiting for its turn gives up and throws the last error. */
+    retrySignal?: AbortSignal;
+}
+export type QueryValue = string | number | boolean | undefined | null;
+export interface ApiRequest {
+    method: 'GET' | 'POST';
+    /** Starts with `/`; path segments already encoded. */
+    path: string;
+    query?: Record<string, QueryValue>;
+    body?: unknown;
+    idempotencyKey?: string;
+    /** Overrides the config's per-attempt timeout (a send with `wait` runs longer). */
+    timeoutMs?: number;
+}
+export interface ApiResponse {
+    status: number;
+    headers: Headers;
+    body: unknown;
+}
+/** Full jitter (AWS's "Exponential Backoff and Jitter"): uniform in [0, min(cap, base * 2^attempt)). */
+export declare const backoffDelay: (attempt: number, random: () => number) => number;
+/** `Retry-After` in seconds: a number of seconds or an HTTP date. Undefined when absent or unreadable. */
+export declare const parseRetryAfter: (value: string | null, nowMs: number) => number | undefined;
+export declare const isRetryableStatus: (status: number) => boolean;
+/** `https://host/base` + `/path` + `?query`. `new URL(path, base)` would drop a path prefix on the base. */
+export declare const buildUrl: (baseUrl: string, path: string, query?: Record<string, QueryValue>) => string;
+/** The WhispError for a non-2xx answer, with the API's code and the request id. */
+export declare const errorFromResponse: (response: Response, text: string, nowMs: number) => WhispError;
+/** The 2xx answer, or throws the last WhispError (or WhispConnectionError) once retries are spent. */
+export declare const request: (config: TransportConfig, call: ApiRequest) => Promise<ApiResponse>;

package/dist/esm/transport.js

@@ -0,0 +1,172 @@
+/**
+ * One API call with a timeout and retries (phase2-design 12.3).
+ *
+ * Retried: network errors, timeouts, 408, 429 and 5xx (but 501, which never
+ * changes), with full-jitter backoff (0.5 s base, 8 s cap), or exactly
+ * `Retry-After` when the API sends one, up to 60 s; a longer `Retry-After`
+ * fails at once with `retryAfter` set, rather than holding the caller for
+ * minutes. Never on other 4xx. Every attempt sends the same bytes and the
+ * same `Idempotency-Key`, so a retried send can't send twice (5.9).
+ *
+ * The token goes only to the API's origin: redirects are never followed
+ * (`redirect: 'manual'`), so a 3xx is an error, not a hop that might carry
+ * the `Authorization` header somewhere else.
+ */
+import { readApiError, WhispConnectionError, WhispError } from './errors.js';
+import { sleep } from './runtime.js';
+export const BACKOFF_BASE_MS = 500;
+export const BACKOFF_CAP_MS = 8_000;
+export const RETRY_AFTER_MAX_SECONDS = 60;
+/** Full jitter (AWS's "Exponential Backoff and Jitter"): uniform in [0, min(cap, base * 2^attempt)). */
+export const backoffDelay = (attempt, random) => Math.floor(random() * Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** attempt));
+/** `Retry-After` in seconds: a number of seconds or an HTTP date. Undefined when absent or unreadable. */
+export const parseRetryAfter = (value, nowMs) => {
+    if (!value)
+        return undefined;
+    const text = value.trim();
+    if (/^\d+(?:\.\d+)?$/.test(text))
+        return Math.ceil(Number(text));
+    // An HTTP date names a weekday and a month; Date.parse alone reads "-5" as a year.
+    if (!/[a-z]/i.test(text))
+        return undefined;
+    const at = Date.parse(text);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, Math.ceil((at - nowMs) / 1_000));
+};
+export const isRetryableStatus = (status) => status === 408 || status === 429 || (status >= 500 && status !== 501);
+/** `https://host/base` + `/path` + `?query`. `new URL(path, base)` would drop a path prefix on the base. */
+export const buildUrl = (baseUrl, path, query) => {
+    let url = `${baseUrl.replace(/\/+$/, '')}${path}`;
+    if (query) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined && value !== null)
+                params.set(key, String(value));
+        }
+        const search = params.toString();
+        if (search)
+            url += `?${search}`;
+    }
+    return url;
+};
+const parseJson = (text) => {
+    if (!text)
+        return { ok: true, value: null };
+    try {
+        return { ok: true, value: JSON.parse(text) };
+    }
+    catch {
+        return { ok: false };
+    }
+};
+const describe = (cause) => cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause);
+/** The WhispError for a non-2xx answer, with the API's code and the request id. */
+export const errorFromResponse = (response, text, nowMs) => {
+    const parsed = parseJson(text);
+    const api = parsed.ok ? readApiError(parsed.value) : null;
+    const requestId = response.headers.get('x-request-id');
+    const retryAfter = parseRetryAfter(response.headers.get('retry-after'), nowMs) ?? null;
+    if (response.status >= 300 && response.status < 400) {
+        const location = response.headers.get('location');
+        return new WhispError({
+            code: 'INVALID_RESPONSE',
+            status: response.status,
+            message: `The API answered ${response.status}${location ? ` (a redirect to ${location.slice(0, 200)})` : ''}; the SDK never follows redirects with your token. Check baseUrl.`,
+            requestId,
+        });
+    }
+    return new WhispError({
+        code: api?.code ?? `HTTP_${response.status}`,
+        message: api?.message ?? `The API answered ${response.status}`,
+        status: response.status,
+        params: api?.params ?? null,
+        requestId,
+        retryAfter,
+    });
+};
+const attemptOnce = async (config, call, url, payload) => {
+    const controller = new AbortController();
+    const timeoutMs = call.timeoutMs ?? config.timeoutMs;
+    let timedOut = false;
+    const timer = config.timers.setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    const headers = {
+        authorization: `Bearer ${config.token}`,
+        accept: 'application/json',
+        'user-agent': config.userAgent,
+    };
+    if (payload !== undefined)
+        headers['content-type'] = 'application/json';
+    if (call.idempotencyKey !== undefined)
+        headers['idempotency-key'] = call.idempotencyKey;
+    try {
+        const response = await config.fetch(url, {
+            method: call.method,
+            headers,
+            // Always a string: the runtime sends its Content-Length, which public routes require (5.2 step 2).
+            ...(payload !== undefined ? { body: payload } : {}),
+            redirect: 'manual',
+            signal: controller.signal,
+        });
+        // Read inside the timeout: an answer whose body never ends is a hung request too.
+        const text = await response.text();
+        if (response.status >= 200 && response.status < 300) {
+            const parsed = parseJson(text);
+            if (!parsed.ok) {
+                return {
+                    done: false,
+                    retryable: false,
+                    error: new WhispError({
+                        code: 'INVALID_RESPONSE',
+                        status: response.status,
+                        message: `The API answered ${response.status} with a body that is not JSON`,
+                        requestId: response.headers.get('x-request-id'),
+                    }),
+                };
+            }
+            return { done: true, response: { status: response.status, headers: response.headers, body: parsed.value } };
+        }
+        const error = errorFromResponse(response, text, config.timers.now());
+        return { done: false, error, retryable: isRetryableStatus(response.status) };
+    }
+    catch (cause) {
+        if (timedOut) {
+            return {
+                done: false,
+                retryable: true,
+                error: new WhispConnectionError('TIMEOUT', `No answer from the API within ${timeoutMs} ms`, cause),
+            };
+        }
+        return {
+            done: false,
+            retryable: true,
+            error: new WhispConnectionError('NETWORK_ERROR', `The request failed (${describe(cause)})`, cause),
+        };
+    }
+    finally {
+        config.timers.clearTimeout(timer);
+    }
+};
+/** The 2xx answer, or throws the last WhispError (or WhispConnectionError) once retries are spent. */
+export const request = async (config, call) => {
+    const url = buildUrl(config.baseUrl, call.path, call.query);
+    // Serialized once: every retry sends exactly these bytes.
+    const payload = call.body === undefined ? undefined : JSON.stringify(call.body);
+    for (let attempt = 0;; attempt++) {
+        const outcome = await attemptOnce(config, call, url, payload);
+        if (outcome.done)
+            return outcome.response;
+        const { error } = outcome;
+        if (!outcome.retryable || attempt >= config.maxRetries || config.retrySignal?.aborted)
+            throw error;
+        if (error.retryAfter !== null && error.retryAfter > RETRY_AFTER_MAX_SECONDS)
+            throw error;
+        const delay = error.retryAfter !== null ? error.retryAfter * 1_000 : backoffDelay(attempt, () => config.timers.random());
+        await sleep(config.timers, delay, config.retrySignal);
+        if (config.retrySignal?.aborted)
+            throw error;
+    }
+};