@upvoiced/sdk 0.1.0 → 1.32.1

package/README.md

@@ -132,3 +132,29 @@ package version follows UpVoiced releases; each release is regenerated from that
 `src/generated/schema.ts` is generated, never edited: after changing API routes run
 `pnpm --filter @upvoiced/sdk generate` (needs a built `@upvoiced/api`). The SDK's tests fail
 while the committed file differs from the API. See ADR-0067.
+
+### Authenticated export files
+
+When export detail returns `download.method = "authenticated"`, use
+`downloadExport` with the detail's original size and expected format. It performs
+one scoped request and returns an ArrayBuffer without text decoding or automatic
+GET retries. The ordinary JSON methods refuse this binary route.
+
+```ts
+const detail = await upvoiced.get('/v1/exports/{id}', { path: { id: exportId } });
+if (detail.download?.method === 'authenticated' && detail.bytes) {
+  const mime =
+    detail.format === 'json'
+      ? 'application/json'
+      : detail.include.length > 1
+        ? 'application/zip'
+        : 'text/csv';
+  const bytes = await upvoiced.downloadExport({ id: detail.id, bytes: detail.bytes, mime });
+  // Store or consume the original bytes with detail.filename.
+}
+```
+
+The client binds the content path to its configured API origin and current workspace.
+A failed or interrupted request is surfaced to the caller; an explicit later user
+action may request a new current-domain read. Legacy signed-link metadata remains
+compatible while protected storage is disabled.

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import { type DownloadedImage, type DownloadedSocialImage } from './image-download.js';
 import type { ApiResponse, HttpMethod, Operation, PageItem, PaginatedPath, PathsWith, RequestArgs, ResponseData } from './types.js';
 /** Production API origin (ADR-0015). Staging: https://api-staging.upvoiced.com */
 export declare const defaultBaseUrl = "https://api.upvoiced.com";
@@ -37,6 +38,34 @@ export interface ClientOptions {
 export declare class UpVoiced {
     #private;
     constructor(options?: ClientOptions);
+    /** PRF-004 one explicit approved-quote attachment, never a JSON GET retry. */
+    downloadTestimonialImage(input: {
+        readonly id: string;
+        readonly size?: '1200x630' | '1080x1080' | '1080x1350';
+        readonly format?: 'png' | 'svg';
+        readonly scheme?: 'workspace' | 'light' | 'dark';
+        readonly signal?: AbortSignal;
+    }): Promise<DownloadedSocialImage>;
+    /** Binary content uses exactly one authenticated request; JSON GET retry policy never applies. */
+    downloadExport(input: {
+        readonly id: string;
+        readonly bytes: number;
+        readonly mime: 'text/csv' | 'application/json' | 'application/zip';
+        readonly signal?: AbortSignal;
+    }): Promise<ArrayBuffer>;
+    /** One authenticated read of the current operator's own stored pre-attachment logo. */
+    downloadBrandingPreview(input: {
+        readonly id: string;
+        readonly bytes: number;
+        readonly mime: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/svg+xml';
+        readonly signal?: AbortSignal;
+    }): Promise<ArrayBuffer>;
+    /** Current-member attached changelog image; one bounded request and no JSON retry. */
+    downloadChangelogImage(input: {
+        readonly entryId: string;
+        readonly assetId: string;
+        readonly signal?: AbortSignal;
+    }): Promise<DownloadedImage>;
     /** A client with the same settings acting on another workspace (operator-wide keys). */
     withWorkspace(workspace: string): UpVoiced;
     get<P extends PathsWith<'get'>>(path: P, ...args: RequestArgs<Operation<P, 'get'>>): Promise<ResponseData<Operation<P, "get">>>;

package/dist/client.js

@@ -1,3 +1,5 @@
+import { downloadImageBytes, downloadSocialImageBytes, } from './image-download.js';
+import { downloadExportBytes } from './export-download.js';
 import { UpVoicedError, errorShape, parseRetryAfter } from './errors.js';
 /** Production API origin (ADR-0015). Staging: https://api-staging.upvoiced.com */
 export const defaultBaseUrl = 'https://api.upvoiced.com';
@@ -96,6 +98,93 @@ export class UpVoiced {
         this.#maxRetries = maxRetries;
         this.#maxRetryDelayMs = maxRetryDelayMs;
     }
+    /** PRF-004 one explicit approved-quote attachment, never a JSON GET retry. */
+    async downloadTestimonialImage(input) {
+        const size = input.size ?? '1200x630', format = input.format ?? 'png', scheme = input.scheme ?? 'workspace';
+        if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(input.id) ||
+            !['1200x630', '1080x1080', '1080x1350'].includes(size) ||
+            !['png', 'svg'].includes(format) ||
+            !['workspace', 'light', 'dark'].includes(scheme) ||
+            !this.#options.apiKey ||
+            !this.#options.workspace)
+            throw new TypeError('A valid testimonial, image size/format, API key and workspace are required.');
+        const headers = new Headers(this.#options.headers);
+        headers.set('authorization', 'Bearer ' + this.#options.apiKey);
+        headers.set('x-workspace', this.#options.workspace);
+        const image = await downloadSocialImageBytes({
+            url: this.#baseUrl +
+                '/v1/testimonials/' +
+                input.id +
+                '/image?' +
+                new URLSearchParams({ size, format, scheme }).toString(),
+            headers,
+            ...(this.#options.fetch ? { fetch: this.#options.fetch } : {}),
+            ...(input.signal ? { signal: input.signal } : {}),
+        });
+        if (image.mime !== (format === 'png' ? 'image/png' : 'image/svg+xml')) {
+            new Uint8Array(image.buffer).fill(0);
+            throw new Error('The image format was unexpected.');
+        }
+        return image;
+    }
+    /** Binary content uses exactly one authenticated request; JSON GET retry policy never applies. */
+    async downloadExport(input) {
+        if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(input.id) ||
+            !this.#options.apiKey ||
+            !this.#options.workspace)
+            throw new TypeError('An export ID, API key and workspace are required.');
+        const headers = new Headers(this.#options.headers);
+        headers.set('authorization', 'Bearer ' + this.#options.apiKey);
+        headers.set('x-workspace', this.#options.workspace);
+        return downloadExportBytes({
+            url: this.#baseUrl + '/v1/exports/' + input.id + '/content',
+            headers,
+            bytes: input.bytes,
+            mime: input.mime,
+            ...(this.#options.fetch ? { fetch: this.#options.fetch } : {}),
+            ...(input.signal ? { signal: input.signal } : {}),
+        });
+    }
+    /** One authenticated read of the current operator's own stored pre-attachment logo. */
+    async downloadBrandingPreview(input) {
+        const { id, bytes, mime, signal } = input;
+        if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(id) ||
+            !this.#options.apiKey ||
+            !this.#options.workspace ||
+            !Number.isSafeInteger(bytes) ||
+            bytes < 1 ||
+            bytes > 2097152 ||
+            !['image/png', 'image/jpeg', 'image/webp', 'image/svg+xml'].includes(mime))
+            throw new TypeError('A logo ID, bounded image metadata, API key and workspace are required.');
+        const headers = new Headers(this.#options.headers);
+        headers.set('authorization', 'Bearer ' + this.#options.apiKey);
+        headers.set('x-workspace', this.#options.workspace);
+        return downloadExportBytes({
+            url: this.#baseUrl + '/v1/branding/previews/' + id,
+            headers,
+            bytes,
+            mime,
+            ...(this.#options.fetch ? { fetch: this.#options.fetch } : {}),
+            ...(signal ? { signal } : {}),
+        });
+    }
+    /** Current-member attached changelog image; one bounded request and no JSON retry. */
+    async downloadChangelogImage(input) {
+        const { entryId, assetId, signal } = input;
+        if (![entryId, assetId].every((id) => /^[a-f0-9]{8}-[a-f0-9]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(id)) ||
+            !this.#options.apiKey ||
+            !this.#options.workspace)
+            throw new TypeError('An entry ID, image ID, API key and workspace are required.');
+        const headers = new Headers(this.#options.headers);
+        headers.set('authorization', 'Bearer ' + this.#options.apiKey);
+        headers.set('x-workspace', this.#options.workspace);
+        return downloadImageBytes({
+            url: this.#baseUrl + '/v1/changelog/' + entryId + '/media/' + assetId,
+            headers,
+            ...(this.#options.fetch ? { fetch: this.#options.fetch } : {}),
+            ...(signal ? { signal } : {}),
+        });
+    }
     /** A client with the same settings acting on another workspace (operator-wide keys). */
     withWorkspace(workspace) {
         return new UpVoiced({ ...this.#options, workspace });
@@ -144,6 +233,17 @@ export class UpVoiced {
     async #send(method, template, raw) {
         if (!methods.includes(method))
             throw new TypeError(`Unsupported method ${method}.`);
+        if (/^\/v1\/changelog\/[^/]+\/media\/[^/]+(?:$|[/?#])/.test(template) ||
+            /^\/v1\/unlisted\/changelog\/preview\/[^/]+\/media\/[^/]+(?:$|[/?#])/.test(template))
+            throw new TypeError('Changelog images require a binary transport, never JSON retries.');
+        if (/^\/v1\/testimonials\/[^/]+\/image(?:$|[/?#])/.test(template))
+            throw new TypeError('Use downloadTestimonialImage for binary social images.');
+        if (/^\/v1\/branding\/previews\/[^/]+(?:$|[/?#])/.test(template))
+            throw new TypeError('Use downloadBrandingPreview for private logo bytes.');
+        if (/^\/v1\/exports\/[^/]+\/content(?:$|[/?#])/.test(template))
+            throw new TypeError('Use downloadExport for binary export content.');
+        if (/^\/v1\/public\/(?:branding|changelog)\/media\/[^/]+(?:$|[/?#])/.test(template))
+            throw new TypeError('Public media URLs are binary image resources, not JSON SDK operations.');
         const options = (raw ?? {});
         const path = expandPath(template, options.path);
         const url = `${this.#baseUrl}${path}${searchOf(options.query)}`;

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);
+    }
+}