@upvoiced/sdk 0.0.0-stage → 1.32.1

package/dist/errors.js

@@ -0,0 +1,64 @@
+/**
+ * P2-015 (ADR-0067): every non-2xx answer becomes an UpVoicedError carrying the API's error
+ * shape `{ error: { code, message, details? } }` (spec 05). Bodies that are not that shape
+ * (a proxy's HTML 502) get `code: "http_<status>"`.
+ */
+export class UpVoicedError extends Error {
+    name = 'UpVoicedError';
+    /** HTTP status. */
+    status;
+    /** Stable machine-readable code (`insufficient_scope`, `not_found`, `rate_limited`, …). */
+    code;
+    details;
+    method;
+    /** Request path without the query string. */
+    path;
+    /** Seconds from `Retry-After` (429/503), else null. */
+    retryAfter;
+    /** The Idempotency-Key the request carried; reuse it to retry the same POST safely. */
+    idempotencyKey;
+    /** The parsed (or raw text) response body. */
+    body;
+    constructor(init) {
+        super(init.message);
+        this.status = init.status;
+        this.code = init.code;
+        this.details = init.details;
+        this.method = init.method;
+        this.path = init.path;
+        this.retryAfter = init.retryAfter;
+        this.idempotencyKey = init.idempotencyKey;
+        this.body = init.body;
+    }
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const detailsOf = (value) => Array.isArray(value)
+    ? value.flatMap((item) => isRecord(item) && typeof item['path'] === 'string' && typeof item['code'] === 'string'
+        ? [{ path: item['path'], code: item['code'] }]
+        : [])
+    : [];
+/** Reads `{ error: { code, message, details? } }`, tolerating anything else. */
+export function errorShape(status, statusText, body) {
+    const error = isRecord(body) ? body['error'] : undefined;
+    if (isRecord(error) && typeof error['code'] === 'string')
+        return {
+            code: error['code'],
+            message: typeof error['message'] === 'string' ? error['message'] : error['code'],
+            details: detailsOf(error['details']),
+        };
+    return {
+        code: `http_${String(status)}`,
+        message: statusText || `HTTP ${String(status)}`,
+        details: [],
+    };
+}
+/** `Retry-After` as seconds: delta-seconds or an HTTP date; null when absent or invalid. */
+export function parseRetryAfter(value, now = Date.now()) {
+    if (value === null || value.trim() === '')
+        return null;
+    const trimmed = value.trim();
+    if (/^\d+$/.test(trimmed))
+        return Number(trimmed);
+    const at = Date.parse(trimmed);
+    return Number.isNaN(at) ? null : Math.max(0, Math.ceil((at - now) / 1000));
+}

package/dist/export-download.d.ts

@@ -0,0 +1,11 @@
+/** Binary consumer only. Callers bind URL to their configured API and exact resource ID;
+ * this utility never derives authority from a response URL or retries a request. */
+export declare function downloadExportBytes(options: {
+    readonly url: string;
+    readonly headers: HeadersInit;
+    readonly bytes: number;
+    readonly mime: 'text/csv' | 'application/json' | 'application/zip' | 'image/png' | 'image/jpeg' | 'image/webp' | 'image/svg+xml';
+    readonly fetch?: (url: string, init: RequestInit) => Promise<Response>;
+    readonly assertCurrent?: () => void;
+    readonly signal?: AbortSignal;
+}): Promise<ArrayBuffer>;

package/dist/export-download.js

@@ -0,0 +1,106 @@
+/** Binary consumer only. Callers bind URL to their configured API and exact resource ID;
+ * this utility never derives authority from a response URL or retries a request. */
+export async function downloadExportBytes(options) {
+    const refused = () => new Error('Binary download is unavailable.');
+    const bytes = options.bytes, mime = options.mime, url = options.url, headers = new Headers(options.headers), fetcher = options.fetch ?? fetch, assertCurrent = options.assertCurrent, callerSignal = options.signal;
+    if (!Number.isSafeInteger(bytes) ||
+        bytes < 1 ||
+        bytes > 209715200 ||
+        ![
+            'text/csv',
+            'application/json',
+            'application/zip',
+            'image/png',
+            'image/jpeg',
+            'image/webp',
+            'image/svg+xml',
+        ].includes(mime))
+        throw refused();
+    const controller = new AbortController(), signal = callerSignal ? AbortSignal.any([controller.signal, callerSignal]) : controller.signal;
+    const deadline = performance.now() + 120000;
+    let reader, output;
+    const timer = setTimeout(() => {
+        controller.abort();
+        void reader?.cancel().catch(() => { });
+    }, 120000);
+    const check = () => {
+        if (signal.aborted || performance.now() >= deadline)
+            throw refused();
+        assertCurrent?.();
+    };
+    const bounded = (promise) => new Promise((resolve, reject) => {
+        const abort = () => {
+            reject(refused());
+        };
+        if (signal.aborted) {
+            void promise.catch(() => { });
+            reject(refused());
+            return;
+        }
+        signal.addEventListener('abort', abort, { once: true });
+        void promise.then((value) => {
+            signal.removeEventListener('abort', abort);
+            resolve(value);
+        }, () => {
+            signal.removeEventListener('abort', abort);
+            reject(refused());
+        });
+    });
+    try {
+        check();
+        const pending = fetcher(url, {
+            method: 'GET',
+            headers,
+            credentials: 'omit',
+            cache: 'no-store',
+            redirect: 'error',
+            signal,
+        });
+        void pending.then((response) => {
+            if (signal.aborted)
+                void response.body?.cancel().catch(() => { });
+        }, () => { });
+        const response = await bounded(pending);
+        reader = response.body?.getReader();
+        check();
+        if (response.status !== 200 ||
+            response.headers.get('content-type') !== mime ||
+            response.headers.get('content-length') !== String(bytes) ||
+            !reader)
+            throw refused();
+        output = new Uint8Array(bytes);
+        let count = 0;
+        for (;;) {
+            check();
+            const next = await bounded(reader.read());
+            check();
+            if (next.done)
+                break;
+            const raw = next.value;
+            // Native byte streams can cross a browser/Worker realm. Require a real typed
+            // byte view rather than relying on this realm's constructor identity.
+            if (!ArrayBuffer.isView(raw) ||
+                Object.prototype.toString.call(raw) !== '[object Uint8Array]' ||
+                count + raw.byteLength > bytes)
+                throw refused();
+            const chunk = new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength);
+            output.set(chunk, count);
+            count += chunk.byteLength;
+        }
+        if (count !== bytes)
+            throw refused();
+        check();
+        const result = output.buffer;
+        output = undefined;
+        return result;
+    }
+    catch {
+        throw refused();
+    }
+    finally {
+        clearTimeout(timer);
+        controller.abort();
+        void reader?.cancel().catch(() => { });
+        output?.fill(0);
+    }
+}