whisp-js 0.0.0-stage → 0.3.0

package/dist/esm/listener.js

@@ -0,0 +1,452 @@
+/**
+ * `on(event, handler)` over `GET /events/stream` (phase2-design 6.5, 12.4).
+ *
+ * - One stream per `Whisp` instance, opened by its first event handler and
+ *   closed with its last, filtered by the instance's numbers and never by
+ *   type: handlers are matched here, so adding one never reconnects.
+ * - Every connection sends `Last-Event-ID` = the cursor: the SSE `id` of the
+ *   last event whose handlers finished, or of a later `ping` (how far the
+ *   stream has covered), or, before the first one, the `id` of `ready` (where
+ *   the stream started). The cursor is a position, so a resume after a
+ *   pruned `presence.updated` loses nothing; a resume the server can't
+ *   honour comes back as `ready { resumed: false, reason }`, reported once as
+ *   `'gap'`, and the cursor moves to that `ready`'s `id`.
+ * - Reconnects after 1, 2, 4, 8, 15 s, then every 15 s; the schedule starts
+ *   over once a connection reaches `ready`. A watchdog drops a connection that
+ *   sent no byte for 45 s (the server pings every 20 s). A 429 waits 30 s. A
+ *   4xx that a retry can't fix (401 TOKEN_INVALID or TOKEN_REVOKED, 403, 404
+ *   NUMBER_NOT_IN_PROJECT, a 400) stops the listener for good with `'error'`,
+ *   as does the server's own `error` frame with TOKEN_REVOKED.
+ * - Handlers run one at a time, in order. The body isn't read while they run,
+ *   so a slow handler slows the stream down instead of piling events up here;
+ *   past 1000 events behind, the server ends the stream and the reconnect
+ *   catches up from Postgres with the cursor. A handler that throws emits
+ *   `'error'` and the stream goes on. The cursor moves when an event's
+ *   handlers have settled, and at once for an event nobody listens to.
+ */
+import { PUBLIC_EVENT_TYPES } from './constants.js';
+import { localError, readApiError, WhispConnectionError, WhispError } from './errors.js';
+import { sleep } from './runtime.js';
+import { createSseParser } from './sse.js';
+import { errorFromResponse, isRetryableStatus } from './transport.js';
+/** Wait before reconnect attempt N (0-based); the last value repeats. */
+export const RECONNECT_DELAYS_MS = [1_000, 2_000, 4_000, 8_000, 15_000];
+/** No byte for this long and the connection is dropped (the server pings every 20 s). */
+export const WATCHDOG_MS = 45_000;
+/** The wait after a 429 (TOO_MANY_STREAMS or RATE_LIMITED), unless `Retry-After` asks for longer (up to a minute). */
+export const RATE_LIMITED_WAIT_MS = 30_000;
+const RATE_LIMITED_MAX_WAIT_MS = 60_000;
+/** The types this version delivers; any other is skipped (its cursor still moves). */
+const KNOWN_TYPES = new Set(PUBLIC_EVENT_TYPES);
+const LIFECYCLE = new Set(['open', 'close', 'gap', 'error']);
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const asError = (value) => (value instanceof Error ? value : new Error(String(value)));
+/** The handler's argument: `data` plus the envelope (12.4). */
+export const toListenerEvent = (envelope, cursor) => {
+    const data = isRecord(envelope.data) ? envelope.data : {};
+    return {
+        ...data,
+        number: envelope.number.phone,
+        numberId: envelope.number.id,
+        event: { id: envelope.id, type: envelope.type, createdAt: envelope.createdAt, cursor },
+    };
+};
+const isEnvelope = (value) => isRecord(value) &&
+    typeof value.id === 'string' &&
+    typeof value.type === 'string' &&
+    typeof value.createdAt === 'string' &&
+    isRecord(value.number) &&
+    typeof value.number.id === 'string' &&
+    typeof value.number.phone === 'string';
+export class Listener {
+    #config;
+    #handlers = new Map();
+    #cursor;
+    /** Bumped by every start and stop, so a loop from before a stop never acts after it. */
+    #generation = 0;
+    #running = false;
+    /** Ends the current connection: aborts its fetch and cancels its body. */
+    #cancel = null;
+    #wait = null;
+    #attempt = 0;
+    constructor(config) {
+        this.#config = config;
+        this.#cursor = config.cursor;
+    }
+    get cursor() {
+        return this.#cursor;
+    }
+    get running() {
+        return this.#running;
+    }
+    add(name, handler) {
+        let set = this.#handlers.get(name);
+        if (!set) {
+            set = new Set();
+            this.#handlers.set(name, set);
+        }
+        set.add(handler);
+        if (!LIFECYCLE.has(name) && !this.#running)
+            this.#start();
+    }
+    remove(name, handler) {
+        const set = this.#handlers.get(name);
+        if (!set)
+            return;
+        set.delete(handler);
+        if (set.size === 0)
+            this.#handlers.delete(name);
+        // The last event handler gone: nothing would read the stream, so it closes.
+        if (this.#running && !this.#hasEventHandlers()) {
+            const closeHandlers = [...(this.#handlers.get('close') ?? [])];
+            this.#stop();
+            for (const closeHandler of closeHandlers)
+                this.#callQuietly(closeHandler, { reconnect: false });
+        }
+    }
+    /** Ends the stream and its reconnects, and forgets every handler; a later `on()` starts again from the cursor. */
+    close() {
+        const wasRunning = this.#running;
+        this.#stop();
+        const closeHandlers = [...(this.#handlers.get('close') ?? [])];
+        this.#handlers.clear();
+        if (wasRunning)
+            for (const handler of closeHandlers)
+                this.#callQuietly(handler, { reconnect: false });
+    }
+    #hasEventHandlers() {
+        for (const name of this.#handlers.keys())
+            if (!LIFECYCLE.has(name))
+                return true;
+        return false;
+    }
+    #start() {
+        this.#running = true;
+        this.#attempt = 0;
+        const generation = ++this.#generation;
+        void this.#loop(generation).catch(error => this.#config.report(asError(error)));
+    }
+    #stop() {
+        this.#running = false;
+        this.#generation++;
+        this.#cancel?.();
+        this.#cancel = null;
+        this.#wait?.abort();
+        this.#wait = null;
+    }
+    #live(generation) {
+        return this.#running && this.#generation === generation;
+    }
+    async #loop(generation) {
+        while (this.#live(generation)) {
+            const outcome = await this.#connect(generation);
+            if (!this.#live(generation) || outcome.kind === 'closed')
+                return;
+            if (outcome.kind === 'stop') {
+                this.#stop();
+                await this.#emit('error', outcome.error);
+                for (const handler of [...(this.#handlers.get('close') ?? [])]) {
+                    this.#callQuietly(handler, { reconnect: false, error: outcome.error });
+                }
+                return;
+            }
+            if (outcome.reached)
+                this.#attempt = 0;
+            const delay = outcome.delayMs ?? RECONNECT_DELAYS_MS[Math.min(this.#attempt, RECONNECT_DELAYS_MS.length - 1)];
+            this.#attempt += 1;
+            for (const handler of [...(this.#handlers.get('close') ?? [])]) {
+                this.#callQuietly(handler, outcome.error ? { reconnect: true, error: outcome.error } : { reconnect: true });
+            }
+            const wait = new AbortController();
+            this.#wait = wait;
+            await sleep(this.#config.timers, delay, wait.signal);
+            if (this.#wait === wait)
+                this.#wait = null;
+        }
+    }
+    async #connect(generation) {
+        let target;
+        try {
+            target = this.#config.resolve();
+        }
+        catch (error) {
+            return { kind: 'stop', error: error instanceof WhispError ? error : localError('OPTIONS_INVALID', String(error)) };
+        }
+        const { timers } = this.#config;
+        const controller = new AbortController();
+        let reader = null;
+        // Aborting the fetch ends its body in every runtime's fetch; cancelling the reader too covers a custom
+        // fetch that doesn't tie the body to the signal, so a stop or the watchdog never leaves a read hanging.
+        const cancel = () => {
+            controller.abort();
+            void reader?.cancel().catch(() => { });
+        };
+        this.#cancel = cancel;
+        let abortedBy = null;
+        let timer = timers.setTimeout(() => {
+            abortedBy = 'connect';
+            cancel();
+        }, this.#config.connectTimeoutMs);
+        const sentCursor = this.#cursor;
+        const headers = {
+            authorization: `Bearer ${target.token}`,
+            accept: 'text/event-stream',
+            'cache-control': 'no-store',
+            'user-agent': target.userAgent,
+        };
+        if (sentCursor !== null)
+            headers['last-event-id'] = sentCursor;
+        let url = `${target.baseUrl.replace(/\/+$/, '')}/events/stream`;
+        if (this.#config.numbers && this.#config.numbers.length > 0) {
+            url += `?${new URLSearchParams({ numbers: this.#config.numbers.join(',') }).toString()}`;
+        }
+        let reached = false;
+        try {
+            let response;
+            try {
+                response = await target.fetch(url, { method: 'GET', headers, redirect: 'manual', signal: controller.signal });
+            }
+            catch (cause) {
+                if (!this.#live(generation))
+                    return { kind: 'closed' };
+                const error = abortedBy === 'connect'
+                    ? new WhispConnectionError('TIMEOUT', 'The event stream did not answer in time', cause)
+                    : new WhispConnectionError('NETWORK_ERROR', 'The event stream could not connect', cause);
+                return { kind: 'retry', error, reached };
+            }
+            timers.clearTimeout(timer);
+            timer = undefined;
+            if (response.status < 200 || response.status >= 300) {
+                const text = await response.text().catch(() => '');
+                const error = errorFromResponse(response, text, timers.now());
+                if (response.status === 429) {
+                    const asked = error.retryAfter !== null ? error.retryAfter * 1_000 : 0;
+                    return {
+                        kind: 'retry',
+                        error,
+                        reached,
+                        delayMs: Math.min(RATE_LIMITED_MAX_WAIT_MS, Math.max(RATE_LIMITED_WAIT_MS, asked)),
+                    };
+                }
+                // 401, 403, 404 and every other answer a retry can't change end the listener.
+                if (!isRetryableStatus(response.status))
+                    return { kind: 'stop', error };
+                return { kind: 'retry', error, reached };
+            }
+            const contentType = response.headers.get('content-type') ?? '';
+            if (!contentType.toLowerCase().startsWith('text/event-stream') || !response.body) {
+                await response.body?.cancel().catch(() => { });
+                return {
+                    kind: 'retry',
+                    reached,
+                    error: new WhispError({
+                        code: 'INVALID_RESPONSE',
+                        status: response.status,
+                        message: `The event stream answered ${response.status} with ${contentType || 'no content type'}, not an event stream`,
+                        requestId: response.headers.get('x-request-id'),
+                    }),
+                };
+            }
+            reader = response.body.getReader();
+            const parser = createSseParser();
+            const armWatchdog = () => {
+                timers.clearTimeout(timer);
+                timer = timers.setTimeout(() => {
+                    abortedBy = 'watchdog';
+                    cancel();
+                }, WATCHDOG_MS);
+            };
+            const silent = (cause) => new WhispConnectionError('TIMEOUT', `The event stream sent nothing for ${WATCHDOG_MS / 1_000} s`, cause);
+            for (;;) {
+                armWatchdog();
+                let chunk;
+                try {
+                    chunk = await reader.read();
+                }
+                catch (cause) {
+                    if (!this.#live(generation))
+                        return { kind: 'closed' };
+                    const error = abortedBy === 'watchdog'
+                        ? silent(cause)
+                        : new WhispConnectionError('NETWORK_ERROR', 'The event stream was cut', cause);
+                    return { kind: 'retry', error, reached };
+                }
+                // A cancelled reader ends with `done`, not an error.
+                if (!this.#live(generation))
+                    return { kind: 'closed' };
+                if (abortedBy === 'watchdog')
+                    return { kind: 'retry', error: silent(), reached };
+                // Handlers may take their time: the watchdog only watches the wait for bytes.
+                timers.clearTimeout(timer);
+                timer = undefined;
+                const events = chunk.done ? parser.end() : parser.push(chunk.value);
+                for (const event of events) {
+                    if (!this.#live(generation))
+                        return { kind: 'closed' };
+                    const step = await this.#handle(event, sentCursor);
+                    if (step === 'ready')
+                        reached = true;
+                    else if (step !== 'next')
+                        return step;
+                }
+                if (chunk.done)
+                    return { kind: 'retry', reached };
+            }
+        }
+        catch (cause) {
+            if (!this.#live(generation))
+                return { kind: 'closed' };
+            return { kind: 'retry', reached, error: asError(cause) };
+        }
+        finally {
+            timers.clearTimeout(timer);
+            if (this.#cancel === cancel)
+                this.#cancel = null;
+            // Whatever ended this connection, its socket is freed.
+            cancel();
+        }
+    }
+    /** One parsed SSE event. `'next'` goes on reading; anything else ends this connection. */
+    async #handle(event, sentCursor) {
+        switch (event.event) {
+            case 'ready': {
+                let ready = { resumed: false };
+                try {
+                    const parsed = JSON.parse(event.data);
+                    if (isRecord(parsed) && typeof parsed.resumed === 'boolean') {
+                        ready =
+                            parsed.reason === 'cursor_unknown' || parsed.reason === 'cursor_expired'
+                                ? { resumed: parsed.resumed, reason: parsed.reason }
+                                : { resumed: parsed.resumed };
+                    }
+                }
+                catch {
+                    // A ready we can't read still opens the stream.
+                }
+                // sdk-reconnect-without-cursor-loses-events: ready's `id` is where this stream starts. With no
+                // cursor yet, or a cursor the server refused, that is the resume point from now on: a reconnect
+                // before the first event resumes there instead of at the new live end, `cursor` can be saved at
+                // once, and a refused cursor is one 'gap' rather than one per reconnect. The gap below still
+                // names the cursor that was sent.
+                const start = event.id;
+                if (start !== undefined && start !== '' && (sentCursor === null || !ready.resumed))
+                    this.#cursor = start;
+                await this.#emit('open', ready);
+                if (sentCursor !== null && !ready.resumed) {
+                    await this.#emit('gap', { reason: ready.reason ?? 'cursor_unknown', cursor: sentCursor });
+                }
+                return 'ready';
+            }
+            case 'ping':
+                // feed-cursor-quiet-project: a ping's `id` is how far the stream has covered. Handlers run one at a
+                // time and nothing is read meanwhile, so every event before it has settled: the cursor follows, and
+                // a listener whose numbers stay quiet for days still resumes inside retention. Without one (an older
+                // server), nothing moves.
+                if (event.id !== undefined && event.id !== '')
+                    this.#cursor = event.id;
+                return 'next';
+            case 'error': {
+                let api = readApiError(null);
+                try {
+                    api = readApiError(JSON.parse(event.data));
+                }
+                catch {
+                    // Not JSON: reported with a generic code below.
+                }
+                const error = new WhispError({
+                    code: api?.code ?? 'STREAM_ERROR',
+                    message: api?.message ?? 'The event stream sent an error',
+                    params: api?.params ?? null,
+                });
+                // A revoked token won't work again: stop. SHUTDOWN (a redeploy) and the rest: reconnect.
+                if (error.code === 'TOKEN_REVOKED' || error.code === 'TOKEN_INVALID')
+                    return { kind: 'stop', error };
+                if (error.code !== 'SHUTDOWN')
+                    await this.#emit('error', error);
+                return { kind: 'retry', error, reached: true };
+            }
+            default:
+                return this.#deliver(event);
+        }
+    }
+    async #deliver(event) {
+        const cursor = event.id;
+        // Only events with an id are public events; anything else is not ours to hand out.
+        if (cursor === undefined || cursor === '')
+            return 'next';
+        if (!KNOWN_TYPES.has(event.event)) {
+            // A type this version doesn't know (the vocabulary only grows, 4.1): nobody can listen, so move on.
+            this.#cursor = cursor;
+            return 'next';
+        }
+        const handlers = [
+            ...(this.#handlers.get(event.event) ?? []),
+            ...(event.event === 'message.received' ? (this.#handlers.get('message') ?? []) : []),
+            ...(this.#handlers.get('*') ?? []),
+        ];
+        if (handlers.length > 0) {
+            let parsed;
+            try {
+                parsed = JSON.parse(event.data);
+            }
+            catch {
+                parsed = undefined;
+            }
+            if (!isEnvelope(parsed) || parsed.type !== event.event) {
+                await this.#emit('error', new WhispError({
+                    code: 'INVALID_RESPONSE',
+                    message: `The event stream sent a ${event.event} event that is not in the documented shape`,
+                    params: { cursor },
+                }));
+            }
+            else {
+                const payload = toListenerEvent(parsed, cursor);
+                for (const handler of handlers) {
+                    try {
+                        await handler(payload);
+                    }
+                    catch (error) {
+                        await this.#emit('error', asError(error), payload);
+                    }
+                }
+            }
+        }
+        this.#cursor = cursor;
+        return 'next';
+    }
+    /** Runs a lifecycle event's handlers in order; a throwing `open` or `gap` handler is reported as `'error'`. */
+    async #emit(name, arg, event) {
+        const handlers = [...(this.#handlers.get(name) ?? [])];
+        if (name === 'error') {
+            if (handlers.length === 0)
+                return this.#config.report(arg);
+            for (const handler of handlers) {
+                try {
+                    await handler(arg, event);
+                }
+                catch (error) {
+                    this.#config.report(asError(error));
+                }
+            }
+            return;
+        }
+        for (const handler of handlers) {
+            try {
+                await handler(arg);
+            }
+            catch (error) {
+                await this.#emit('error', asError(error));
+            }
+        }
+    }
+    #callQuietly(handler, arg) {
+        try {
+            const result = handler(arg);
+            if (result instanceof Promise)
+                result.catch(error => this.#config.report(asError(error)));
+        }
+        catch (error) {
+            this.#config.report(asError(error));
+        }
+    }
+}

package/dist/esm/media.d.ts

@@ -0,0 +1,40 @@
+import { type Timers } from './runtime.js';
+import { type FetchLike } from './transport.js';
+import type { UploadKind } from './types.js';
+/** What a file send takes: a public https URL the server downloads, or bytes the SDK uploads first. */
+export type MediaSource = MediaUrl | MediaFile;
+export interface MediaUrl {
+    /** https only; the server fetches it (private addresses and redirects are refused). */
+    url: string;
+    fileName?: string;
+    mime?: string;
+}
+export interface MediaFile {
+    file: Blob | Uint8Array | ArrayBuffer | ReadableStream<Uint8Array>;
+    /** Shown to the recipient for documents. Defaults to the File's name, else the kind. */
+    fileName?: string;
+    /** Defaults to the Blob's type, else a guess from fileName's extension. */
+    mime?: string;
+    /** A stream's length in bytes, checked against what it yields. Optional: the stream is read first anyway. */
+    size?: number;
+}
+/** A file ready to upload: its bytes in a form fetch sends with a Content-Length. */
+export interface PreparedFile {
+    body: Blob | Uint8Array;
+    size: number;
+    mime: string;
+    name: string;
+}
+/** The type a file name's extension suggests, or undefined. A voice note's `.webm` is audio, not video. */
+export declare const mimeFromName: (name: string | undefined, kind: UploadKind) => string | undefined;
+/** The bytes, size, type and name of a file to upload; throws MEDIA_INVALID when one can't be known. */
+export declare const prepareFile: (kind: UploadKind, source: MediaFile) => Promise<PreparedFile>;
+export interface PutConfig {
+    fetch: FetchLike;
+    timers: Timers;
+    timeoutMs: number;
+    maxRetries: number;
+    retrySignal?: AbortSignal;
+}
+/** The presigned PUT, retried like an API call (network errors, timeouts, 408, 429, 5xx). */
+export declare const putUpload: (config: PutConfig, url: string, headers: Record<string, string>, file: PreparedFile) => Promise<void>;

package/dist/esm/media.js

@@ -0,0 +1,175 @@
+/**
+ * Files for sends and downloads (phase2-design 5.8, 12.3).
+ *
+ * Sending a file you hold: `POST /uploads` (kind, type, size, name), then a
+ * PUT of the bytes to the presigned URL with exactly the headers it came
+ * with, then the send with `{ uploadId }`. The presigned PUT signs the
+ * length, and fetch sends a stream body chunked (no length), so a
+ * `ReadableStream` is read into memory first, never past its kind's cap; a
+ * `Blob` (`Bun.file()`, Node's `fs.openAsBlob()`) is sent as is. The PUT goes
+ * to storage, never to the API, so it carries no token.
+ *
+ * Downloading: `GET /messages/:id/media?redirect=0` with the token, then the
+ * returned link in a new request with no `Authorization` and
+ * `redirect: 'error'`. The SDK never follows the API's 302 with the token
+ * attached (12.3).
+ */
+import { UPLOAD_MAX_BYTES } from './constants.js';
+import { localError, WhispConnectionError, WhispError } from './errors.js';
+import { sleep } from './runtime.js';
+import { backoffDelay, isRetryableStatus } from './transport.js';
+const EXTENSION_MIME = {
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    png: 'image/png',
+    webp: 'image/webp',
+    gif: 'image/gif',
+    mp4: 'video/mp4',
+    ogg: 'audio/ogg',
+    oga: 'audio/ogg',
+    opus: 'audio/ogg',
+    mp3: 'audio/mpeg',
+    m4a: 'audio/mp4',
+    aac: 'audio/aac',
+    wav: 'audio/wav',
+    weba: 'audio/webm',
+    pdf: 'application/pdf',
+    txt: 'text/plain',
+    csv: 'text/csv',
+    json: 'application/json',
+    zip: 'application/zip',
+    doc: 'application/msword',
+    docx: 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    xls: 'application/vnd.ms-excel',
+    xlsx: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    ppt: 'application/vnd.ms-powerpoint',
+    pptx: 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+};
+/** The type a file name's extension suggests, or undefined. A voice note's `.webm` is audio, not video. */
+export const mimeFromName = (name, kind) => {
+    const extension = name?.split('.').pop()?.toLowerCase();
+    if (!extension || extension === name?.toLowerCase())
+        return undefined;
+    if (extension === 'webm')
+        return kind === 'voice' ? 'audio/webm' : 'video/webm';
+    return EXTENSION_MIME[extension];
+};
+const megabytes = (bytes) => `${Math.round(bytes / (1024 * 1024))} MB`;
+const readStream = async (stream, max, kind) => {
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > max) {
+                await reader.cancel().catch(() => { });
+                throw localError('MEDIA_INVALID', `The ${kind} is over its ${megabytes(max)} limit`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+};
+/** The bytes, size, type and name of a file to upload; throws MEDIA_INVALID when one can't be known. */
+export const prepareFile = async (kind, source) => {
+    const { file } = source;
+    const max = UPLOAD_MAX_BYTES[kind];
+    let body;
+    let blobType;
+    let blobName;
+    if (typeof Blob !== 'undefined' && file instanceof Blob) {
+        body = file;
+        blobType = file.type || undefined;
+        const named = file.name;
+        blobName = typeof named === 'string' && named !== '' ? named.split(/[\\/]/).pop() : undefined;
+    }
+    else if (file instanceof Uint8Array) {
+        body = file;
+    }
+    else if (file instanceof ArrayBuffer) {
+        body = new Uint8Array(file);
+    }
+    else if (typeof ReadableStream !== 'undefined' && file instanceof ReadableStream) {
+        body = await readStream(file, max, kind);
+        if (source.size !== undefined && source.size !== body.byteLength) {
+            throw localError('MEDIA_INVALID', `The stream gave ${body.byteLength} bytes, not the ${source.size} its size said`);
+        }
+    }
+    else {
+        throw localError('MEDIA_INVALID', '`file` must be a Blob, a Uint8Array, an ArrayBuffer or a ReadableStream');
+    }
+    const size = body instanceof Uint8Array ? body.byteLength : body.size;
+    if (size === 0)
+        throw localError('MEDIA_INVALID', `The ${kind} is empty`);
+    if (size > max)
+        throw localError('MEDIA_INVALID', `The ${kind} is over its ${megabytes(max)} limit`);
+    const name = (source.fileName?.trim() || blobName || kind).slice(0, 255);
+    const mime = source.mime?.trim() ||
+        blobType ||
+        mimeFromName(source.fileName ?? blobName, kind) ||
+        (kind === 'document' ? 'application/octet-stream' : undefined);
+    if (!mime) {
+        throw localError('MEDIA_INVALID', `Pass the ${kind}'s mime type (for example ${kind === 'image' ? 'image/jpeg' : kind === 'video' ? 'video/mp4' : 'audio/ogg'}), or a fileName with its extension`);
+    }
+    return { body, size, mime, name };
+};
+/** The presigned PUT, retried like an API call (network errors, timeouts, 408, 429, 5xx). */
+export const putUpload = async (config, url, headers, file) => {
+    // A slow link gets time for the bytes: at least 100 KB/s, never under the request timeout.
+    const timeoutMs = Math.max(config.timeoutMs, Math.ceil(file.size / 100));
+    let last = null;
+    for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
+        if (attempt > 0) {
+            await sleep(config.timers, backoffDelay(attempt - 1, () => config.timers.random()), config.retrySignal);
+            if (config.retrySignal?.aborted)
+                break;
+        }
+        const controller = new AbortController();
+        let timedOut = false;
+        const timer = config.timers.setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeoutMs);
+        try {
+            const response = await config.fetch(url, {
+                method: 'PUT',
+                headers,
+                body: file.body,
+                redirect: 'error',
+                signal: controller.signal,
+            });
+            await response.arrayBuffer().catch(() => undefined);
+            if (response.ok)
+                return;
+            last = new WhispError({
+                code: 'UPLOAD_FAILED',
+                status: response.status,
+                message: `The upload to storage answered ${response.status}`,
+            });
+            if (!isRetryableStatus(response.status))
+                break;
+        }
+        catch (cause) {
+            last = timedOut
+                ? new WhispConnectionError('TIMEOUT', `The upload did not finish within ${timeoutMs} ms`, cause)
+                : new WhispConnectionError('NETWORK_ERROR', 'The upload to storage failed', cause);
+        }
+        finally {
+            config.timers.clearTimeout(timer);
+        }
+    }
+    throw last ?? new WhispError({ code: 'UPLOAD_FAILED', message: 'The upload to storage was stopped' });
+};

package/dist/esm/refs.d.ts

@@ -0,0 +1,4 @@
+/** The canonical reference (`972501234567` or `num_7Hq2kD3x`), or null for anything else. */
+export declare const normalizeNumberRef: (ref: unknown) => string | null;
+/** Like normalizeNumberRef, but throws PHONE_INVALID naming the value. */
+export declare const requireNumberRef: (ref: unknown, where: string) => string;