@upvoiced/sdk 0.1.0 → 1.32.3

package/dist/generated/schema.js

@@ -2,6 +2,6 @@
  * Generated from the UpVoiced API OpenAPI document (version 0.1.0)
  * by openapi-typescript. Do not edit by hand (P2-015, ADR-0067):
  * run `pnpm --filter @upvoiced/sdk generate` after changing routes.
- * Document sha256: b2e98a3bd5edbe654e2e232efd73a133e4323e3ebc5263b931d0d0b9dbe01144
+ * Document sha256: b1a1581db6735eb4d0165c44c07c0217d67ee532d17a69413123ddbc727cd973
  */
 export {};

package/dist/image-download.d.ts

@@ -0,0 +1,33 @@
+type ImageMime = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/svg+xml';
+export type DownloadedImage = {
+    readonly buffer: ArrayBuffer;
+    readonly mime: 'image/png' | 'image/jpeg' | 'image/webp';
+};
+export type DownloadedSocialImage = {
+    readonly buffer: ArrayBuffer;
+    readonly mime: 'image/png' | 'image/svg+xml';
+};
+/** Safe fixed messages only; never retain an error body, token-bearing URL or provider response. */
+export declare class SocialImageDownloadError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number);
+}
+type ImageDownloadOptions = Parameters<typeof readImage>[0];
+/** Existing changelog images keep their original raster-only5MiB contract. */
+export declare function downloadImageBytes(options: ImageDownloadOptions): Promise<DownloadedImage>;
+/** Social SVG comes only from the fixed authenticated endpoint, never a user SVG URL. */
+export declare function downloadSocialImageBytes(options: ImageDownloadOptions): Promise<DownloadedSocialImage>;
+/** One authenticated image GET. Size/type are read only from the fixed API response,
+ * bounded to the native5MiB image cap; never issue a metadata GET or a second body request. */
+declare function readImage<M extends ImageMime>(options: {
+    readonly url: string;
+    readonly headers: HeadersInit;
+    readonly fetch?: (url: string, init: RequestInit) => Promise<Response>;
+    readonly assertCurrent?: () => void;
+    readonly signal?: AbortSignal;
+}, allowed: readonly M[], maxBytes: number): Promise<{
+    readonly buffer: ArrayBuffer;
+    readonly mime: M;
+}>;
+export {};

package/dist/image-download.js

@@ -0,0 +1,132 @@
+import { downloadExportBytes } from './export-download.js';
+/** Safe fixed messages only; never retain an error body, token-bearing URL or provider response. */
+export class SocialImageDownloadError extends Error {
+    status;
+    code;
+    constructor(status) {
+        const failure = status === 422
+            ? [
+                'unsupported_image_text',
+                'Image export needs nonempty text in the bundled Latin-script font.',
+            ]
+            : status === 409
+                ? ['image_changed', 'The quote or workspace theme changed. Prepare the current version.']
+                : status === 404
+                    ? ['not_found', 'This testimonial is unavailable or is no longer approved.']
+                    : status === 429
+                        ? ['image_busy', 'Image export is busy. Try again shortly.']
+                        : status === 401
+                            ? ['unauthenticated', 'Sign in again to export this testimonial.']
+                            : status === 403
+                                ? ['forbidden', 'Your current workspace role cannot export this testimonial.']
+                                : ['image_unavailable', 'Image export is unavailable. Try again shortly.'];
+        super(failure[1]);
+        this.name = 'SocialImageDownloadError';
+        this.status = status;
+        this.code = failure[0] ?? 'image_unavailable';
+    }
+}
+/** Existing changelog images keep their original raster-only5MiB contract. */
+export function downloadImageBytes(options) {
+    return readImage(options, ['image/png', 'image/jpeg', 'image/webp'], 5242880);
+}
+/** Social SVG comes only from the fixed authenticated endpoint, never a user SVG URL. */
+export function downloadSocialImageBytes(options) {
+    return readImage(options, ['image/png', 'image/svg+xml'], 2097152);
+}
+/** One authenticated image GET. Size/type are read only from the fixed API response,
+ * bounded to the native5MiB image cap; never issue a metadata GET or a second body request. */
+async function readImage(options, allowed, maxBytes) {
+    const url = options.url, headers = new Headers(options.headers), send = options.fetch ?? fetch, assertCurrent = options.assertCurrent, callerSignal = options.signal;
+    const controller = new AbortController();
+    const signal = callerSignal
+        ? AbortSignal.any([controller.signal, callerSignal])
+        : controller.signal;
+    const deadline = performance.now() + 120000;
+    const refused = () => new Error('Image download is unavailable.');
+    let response, handed = false;
+    const held = new Set();
+    const retainsResponse = () => !handed;
+    const timer = setTimeout(() => {
+        controller.abort();
+        void response?.body?.cancel().catch(() => { });
+    }, 120000);
+    const current = () => {
+        if (signal.aborted || performance.now() >= deadline)
+            throw refused();
+        assertCurrent?.();
+    };
+    try {
+        current();
+        const pending = send(url, {
+            method: 'GET',
+            headers,
+            credentials: 'omit',
+            cache: 'no-store',
+            redirect: 'error',
+            signal,
+        });
+        void pending.then((value) => {
+            if (signal.aborted)
+                void value.body?.cancel().catch(() => { });
+        }, () => { });
+        response = await new Promise((resolve, reject) => {
+            const abort = () => {
+                reject(refused());
+            };
+            if (signal.aborted) {
+                void pending.catch(() => { });
+                reject(refused());
+                return;
+            }
+            signal.addEventListener('abort', abort, { once: true });
+            void pending.then((value) => {
+                signal.removeEventListener('abort', abort);
+                resolve(value);
+            }, () => {
+                signal.removeEventListener('abort', abort);
+                reject(refused());
+            });
+        });
+        current();
+        if (response.status !== 200 && allowed.includes('image/svg+xml'))
+            throw new SocialImageDownloadError(response.status);
+        const mime = response.headers.get('content-type'), length = response.headers.get('content-length');
+        if (response.status !== 200 ||
+            !length ||
+            !/^[1-9][0-9]{0,7}$/.test(length) ||
+            mime === null ||
+            !allowed.includes(mime))
+            throw refused();
+        const bytes = Number(length);
+        if (!Number.isSafeInteger(bytes) || bytes > maxBytes)
+            throw refused();
+        const accepted = response;
+        const buffer = await downloadExportBytes({
+            url,
+            headers,
+            bytes,
+            mime: mime,
+            signal,
+            assertCurrent: current,
+            fetch: () => {
+                if (handed)
+                    return Promise.reject(refused());
+                handed = true;
+                return Promise.resolve(accepted);
+            },
+        });
+        held.add(buffer);
+        current();
+        held.delete(buffer);
+        return { buffer, mime: mime };
+    }
+    finally {
+        for (const buffer of held)
+            new Uint8Array(buffer).fill(0);
+        clearTimeout(timer);
+        controller.abort();
+        if (retainsResponse())
+            void response?.body?.cancel().catch(() => { });
+    }
+}

package/dist/index.d.ts

@@ -8,3 +8,6 @@ export { UpVoicedError } from './errors.js';
 export type { ErrorDetail } from './errors.js';
 export type { ApiResponse, CommonRequestOptions, HttpMethod, Operation, PageItem, PaginatedPath, PathParams, PathsWith, QueryParams, RequestArgs, RequestBody, RequestOptions, ResponseData, } from './types.js';
 export type { components, operations, paths, webhooks } from './generated/schema.js';
+export { downloadExportBytes } from './export-download.js';
+export { downloadImageBytes, downloadSocialImageBytes, SocialImageDownloadError, } from './image-download.js';
+export type { DownloadedImage, DownloadedSocialImage } from './image-download.js';

package/dist/index.js

@@ -4,3 +4,5 @@
  */
 export { UpVoiced, defaultBaseUrl, defaultMaxRetries, defaultMaxRetryDelayMs } from './client.js';
 export { UpVoicedError } from './errors.js';
+export { downloadExportBytes } from './export-download.js';
+export { downloadImageBytes, downloadSocialImageBytes, SocialImageDownloadError, } from './image-download.js';

package/dist/types.d.ts

@@ -9,9 +9,9 @@ export type HttpMethod = 'get' | 'put' | 'post' | 'patch' | 'delete';
 export type ManagedHeader = 'authorization' | 'x-workspace' | 'idempotency-key';
 type Empty<T> = [T] extends [never] ? true : [T] extends [undefined] ? true : false;
 /** Paths that define `method`. */
-export type PathsWith<M extends HttpMethod> = {
+export type PathsWith<M extends HttpMethod> = Exclude<{
     [P in keyof paths]: Empty<paths[P][M]> extends true ? never : P;
-}[keyof paths];
+}[keyof paths], '/v1/changelog/{entryId}/media/{id}' | '/v1/unlisted/changelog/preview/{token}/media/{id}' | '/v1/branding/previews/{id}' | '/v1/exports/{id}/content' | '/v1/public/branding/media/{id}' | '/v1/public/changelog/media/{id}'>;
 export type Operation<P extends keyof paths, M extends HttpMethod> = Exclude<paths[P][M], undefined>;
 type ParametersOf<O> = O extends {
     parameters: infer X;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@upvoiced/sdk",
-  "version": "0.1.0",
+  "version": "1.32.3",
   "description": "Typed TypeScript client for the UpVoiced API, generated from its OpenAPI document.",
   "license": "MIT",
   "homepage": "https://docs.upvoiced.com",