@formatjet/sdk 0.0.0-stage → 0.1.1

package/dist/client.js

@@ -0,0 +1,406 @@
+import createClient, {} from 'openapi-fetch';
+import { errorFromResponse, FormatJetError, retryAfterSeconds } from './errors.js';
+import { parseWebhook, verifyWebhook } from './webhooks.js';
+export const DEFAULT_BASE_URL = 'https://api.formatjet.com';
+const TERMINAL = new Set(['completed', 'failed', 'canceled']);
+const RETRY_STATUSES = new Set([429, 500, 502, 503, 504]);
+/** A longer `Retry-After` is answered as an error rather than slept through. */
+const MAX_RETRY_AFTER_SECONDS = 60;
+const DEFAULT_WAIT_MS = 15 * 60_000;
+const DOWNLOADS_AT_ONCE = 4;
+function environment(name) {
+    const runtime = globalThis;
+    return runtime.process?.env?.[name];
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(signal.reason);
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/** A signal that aborts after `ms` or with `signal`; `clear()` stops the timer. */
+function deadline(ms, signal) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new DOMException('The request timed out.', 'TimeoutError')), ms);
+    if (signal?.aborted)
+        controller.abort(signal.reason);
+    else
+        signal?.addEventListener('abort', () => controller.abort(signal.reason), { once: true });
+    return { signal: controller.signal, clear: () => clearTimeout(timer) };
+}
+/** Half a second, doubling, with up to a quarter of a second's jitter. */
+function backoff(attempt) {
+    return 500 * 2 ** attempt + Math.random() * 250;
+}
+function isFileData(value) {
+    return value instanceof Blob || value instanceof ArrayBuffer || ArrayBuffer.isView(value);
+}
+function prepare(input) {
+    const data = isFileData(input) ? input : input.data;
+    const named = !isFileData(input) ? input.filename : undefined;
+    const file = typeof File !== 'undefined' && data instanceof File ? data : undefined;
+    const blob = data instanceof Blob ? data : new Blob([data]);
+    return { blob, filename: named ?? file?.name ?? undefined };
+}
+function stepOf(options) {
+    if (!options.conversion && !options.to) {
+        throw new TypeError('Name the conversion, or the format to make (`to`).');
+    }
+    return {
+        op: 'convert',
+        ...(options.conversion && { conversion: options.conversion }),
+        ...(options.from && { from: options.from }),
+        ...(options.to && { to: options.to }),
+        ...(options.options && { options: options.options }),
+    };
+}
+/** The name in a `Content-Disposition` header (`filename*` first, as RFC 6266 says). */
+export function filenameFrom(header) {
+    if (!header)
+        return null;
+    const extended = /filename\*\s*=\s*UTF-8''([^;]+)/i.exec(header);
+    if (extended) {
+        try {
+            return decodeURIComponent(extended[1].trim());
+        }
+        catch {
+            // Fall through to the plain name.
+        }
+    }
+    const plain = /filename\s*=\s*"((?:[^"\\]|\\.)*)"|filename\s*=\s*([^;]+)/i.exec(header);
+    const name = plain?.[1]?.replace(/\\(.)/g, '$1') ?? plain?.[2]?.trim();
+    return name || null;
+}
+/** Runs `work` on each item with at most `limit` at once, keeping the order. */
+async function inOrder(items, limit, work) {
+    const results = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length) {
+            const i = next++;
+            results[i] = await work(items[i]);
+        }
+    });
+    await Promise.all(workers);
+    return results;
+}
+/** Throws the API's error when an openapi-fetch call didn't succeed. */
+async function unwrap(result) {
+    if (result.response.ok)
+        return result.data;
+    throw await errorFromResponse(result.response, result.error ?? undefined);
+}
+/** Jobs: make, read, list, wait for, cancel and delete them. */
+export class Jobs {
+    #api;
+    constructor(api) {
+        this.#api = api;
+    }
+    /** Makes a job (`POST /v1/jobs`). It starts at once; wait for it with `wait()`. */
+    async create(request, options = {}) {
+        return unwrap(await this.#api.POST('/v1/jobs', {
+            body: request,
+            signal: options.signal,
+            ...(options.idempotencyKey && { headers: { 'Idempotency-Key': options.idempotencyKey } }),
+        }));
+    }
+    async get(id, options = {}) {
+        return unwrap(await this.#api.GET('/v1/jobs/{id}', { params: { path: { id } }, signal: options.signal }));
+    }
+    /** One page of jobs, newest first: pass `next_cursor` back as `cursor` for the next. */
+    async list(params = {}, options = {}) {
+        return unwrap(await this.#api.GET('/v1/jobs', { params: { query: params }, signal: options.signal }));
+    }
+    /** Every job of the last 30 days, newest first, a page at a time. */
+    async *iterate(params = {}, options = {}) {
+        let cursor;
+        do {
+            const page = await this.list({ ...params, ...(cursor && { cursor }) }, options);
+            yield* page.data;
+            cursor = page.next_cursor ?? undefined;
+        } while (cursor);
+    }
+    /** Cancels a job that hasn't finished (`POST /v1/jobs/{id}/cancel`). */
+    async cancel(id, options = {}) {
+        return unwrap(await this.#api.POST('/v1/jobs/{id}/cancel', {
+            params: { path: { id } },
+            signal: options.signal,
+            ...(options.idempotencyKey && { headers: { 'Idempotency-Key': options.idempotencyKey } }),
+        }));
+    }
+    /** Deletes a job's files now and returns the signed deletion receipt. */
+    async delete(id, options = {}) {
+        const answer = await unwrap(await this.#api.DELETE('/v1/jobs/{id}', { params: { path: { id } }, signal: options.signal }));
+        return answer.receipt;
+    }
+    /**
+     * Reads the job until it has ended (completed, failed or canceled) and returns it, whatever
+     * the outcome. Throws a `FormatJetError` with code `timeout` if it runs past `timeoutMs`.
+     */
+    async wait(id, options = {}) {
+        const until = Date.now() + (options.timeoutMs ?? DEFAULT_WAIT_MS);
+        let pause = 500;
+        for (;;) {
+            const job = await this.get(id, { signal: options.signal });
+            if (TERMINAL.has(job.status))
+                return job;
+            options.onProgress?.(job);
+            if (Date.now() + pause > until) {
+                throw new FormatJetError({
+                    code: 'timeout',
+                    detail: `Job ${id} was still ${job.status} when the wait ran out; it carries on.`,
+                    jobId: id,
+                });
+            }
+            await sleep(pause, options.signal);
+            pause = Math.min(pause * 1.5, 5_000);
+        }
+    }
+}
+/** The webhook signature helpers. */
+export const webhooks = { verify: verifyWebhook, parse: parseWebhook };
+/**
+ * The FormatJet API. `convert()` sends a file and gets the result in one request (up to
+ * 25 MB); `uploadAndConvert()` uploads it first, for files up to the plan's limit. `jobs`
+ * manages jobs, `webhooks` checks deliveries and `api` calls any endpoint, typed.
+ */
+export class FormatJet {
+    baseUrl;
+    /** The typed client for every endpoint (openapi-fetch). */
+    api;
+    jobs;
+    webhooks = webhooks;
+    #apiKey;
+    #fetch;
+    #maxRetries;
+    #timeoutMs;
+    constructor(options = {}) {
+        const apiKey = options.apiKey ?? environment('FORMATJET_API_KEY');
+        if (!apiKey)
+            throw new TypeError('No API key: pass `apiKey` or set FORMATJET_API_KEY.');
+        this.#apiKey = apiKey;
+        this.baseUrl = (options.baseUrl ??
+            environment('FORMATJET_BASE_URL') ??
+            DEFAULT_BASE_URL).replace(/\/+$/, '');
+        this.#fetch = options.fetch ?? ((request) => fetch(request));
+        this.#maxRetries = options.maxRetries ?? 2;
+        this.#timeoutMs = options.timeoutMs ?? 5 * 60_000;
+        this.api = createClient({
+            baseUrl: this.baseUrl,
+            fetch: (request) => this.#call(request),
+        });
+        this.jobs = new Jobs(this.api);
+    }
+    /**
+     * Converts one file (or the files a joining conversion takes) in one request, up to 25 MB in
+     * all, and returns the converted files. A job that runs past 30 seconds is waited for.
+     */
+    async convert(input, options) {
+        const files = (Array.isArray(input) ? input : [input]).map(prepare);
+        const step = stepOf(options);
+        const query = new URLSearchParams();
+        if (step.conversion)
+            query.set('conversion', step.conversion);
+        if (step.from)
+            query.set('from', step.from);
+        if (step.to)
+            query.set('to', step.to);
+        if (step.options)
+            query.set('options', JSON.stringify(step.options));
+        if (options.outputFilename)
+            query.set('output_filename', options.outputFilename);
+        if (options.ttl !== undefined)
+            query.set('ttl', String(options.ttl));
+        const headers = {
+            Authorization: `Bearer ${this.#apiKey}`,
+            'Idempotency-Key': options.idempotencyKey ?? crypto.randomUUID(),
+        };
+        const response = await this.#retrying((signal) => {
+            const form = new FormData();
+            for (const file of files)
+                form.append('file', file.blob, file.filename ?? 'file');
+            return new Request(`${this.baseUrl}/v1/convert?${query}`, {
+                method: 'POST',
+                headers,
+                body: form,
+                signal,
+            });
+        }, options.signal);
+        if (!response.ok)
+            throw await errorFromResponse(response);
+        const type = response.headers.get('Content-Type') ?? '';
+        if (type.includes('application/json')) {
+            // Several files, or still converting after 30 s: the job, which lists them or carries on.
+            let job = (await response.json());
+            if (!TERMINAL.has(job.status)) {
+                job = await this.jobs.wait(job.id, {
+                    signal: options.signal,
+                    timeoutMs: options.timeoutMs,
+                });
+            }
+            return this.#result(job, options.signal);
+        }
+        const file = {
+            filename: filenameFrom(response.headers.get('Content-Disposition')),
+            mime: type || 'application/octet-stream',
+            data: new Uint8Array(await response.arrayBuffer()),
+        };
+        return {
+            jobId: response.headers.get('FormatJet-Job-Id') ?? '',
+            file,
+            files: [file],
+            credits: Number(response.headers.get('FormatJet-Credits') ?? 0),
+            engine: response.headers.get('FormatJet-Engine'),
+            job: null,
+        };
+    }
+    /**
+     * Uploads the file (or files, for a conversion that joins them), makes a job, waits for it
+     * and downloads what it made. For files larger than `convert()` takes.
+     */
+    async uploadAndConvert(input, options) {
+        const files = (Array.isArray(input) ? input : [input]).map(prepare);
+        const step = stepOf(options);
+        const uploads = await Promise.all(files.map((file) => this.#upload(file, options.signal)));
+        const refs = uploads.map((upload) => ({ upload_id: upload.id }));
+        const output = {
+            ...(options.ttl !== undefined && { ttl: options.ttl }),
+            ...(options.outputFilename && { filename: options.outputFilename }),
+        };
+        const created = await this.jobs.create({
+            ...(refs.length === 1 ? { input: refs[0] } : { inputs: refs }),
+            steps: [step],
+            ...(Object.keys(output).length > 0 && { output }),
+            ...(options.metadata && { metadata: options.metadata }),
+            ...(options.webhook && { webhook: options.webhook }),
+        }, { signal: options.signal, idempotencyKey: options.idempotencyKey });
+        const job = await this.jobs.wait(created.id, {
+            signal: options.signal,
+            timeoutMs: options.timeoutMs,
+            onProgress: options.onProgress,
+        });
+        return this.#result(job, options.signal);
+    }
+    /**
+     * Makes an upload and PUTs the file to it. Name the upload in a job's `input`
+     * (`{ upload_id: upload.id }`) within the hour.
+     */
+    async upload(input, options = {}) {
+        return this.#upload(prepare(input), options.signal);
+    }
+    /** Downloads one of a job's outputs. Its URL needs no key and works until `expires_at`. */
+    async download(output, options = {}) {
+        if (!output.url) {
+            throw new FormatJetError({
+                code: 'not_found',
+                detail: `Output ${output.id} has been deleted.`,
+            });
+        }
+        const url = output.url;
+        // Never send the key: the URL is signed, and may be our storage's rather than the API's.
+        const response = await this.#retrying((signal) => new Request(url, { signal }), options.signal);
+        if (!response.ok)
+            throw await errorFromResponse(response);
+        return {
+            filename: output.filename,
+            mime: output.mime,
+            data: new Uint8Array(await response.arrayBuffer()),
+        };
+    }
+    async #upload(file, signal) {
+        const upload = await unwrap(await this.api.POST('/v1/uploads', {
+            body: { size: file.blob.size, ...(file.filename && { filename: file.filename }) },
+            signal,
+        }));
+        const response = await this.#retrying((attempt) => new Request(upload.url, {
+            method: upload.method,
+            headers: upload.headers,
+            body: file.blob,
+            signal: attempt,
+        }), signal);
+        if (!response.ok)
+            throw await errorFromResponse(response);
+        await response.body?.cancel().catch(() => undefined);
+        return upload;
+    }
+    /** The finished job's files, or its failure as an error. */
+    async #result(job, signal) {
+        if (job.status === 'failed') {
+            throw new FormatJetError({
+                code: (job.error?.code ?? 'engine_failed'),
+                detail: job.error?.detail ?? 'The conversion failed.',
+                jobId: job.id,
+            });
+        }
+        if (job.status === 'canceled') {
+            throw new FormatJetError({
+                code: 'canceled',
+                detail: `Job ${job.id} was canceled.`,
+                jobId: job.id,
+            });
+        }
+        const files = await inOrder(job.outputs, DOWNLOADS_AT_ONCE, (output) => this.download(output, { signal }));
+        if (files.length === 0) {
+            throw new FormatJetError({
+                code: 'not_found',
+                detail: `Job ${job.id} has no outputs.`,
+                jobId: job.id,
+            });
+        }
+        return {
+            jobId: job.id,
+            file: files[0],
+            files,
+            credits: job.credits,
+            engine: job.engine ? `${job.engine} ${job.engine_version ?? ''}`.trim() : null,
+            job,
+        };
+    }
+    /** openapi-fetch's requests: the key, an Idempotency-Key on POSTs, and retries. */
+    async #call(request) {
+        const headers = new Headers(request.headers);
+        headers.set('Authorization', `Bearer ${this.#apiKey}`);
+        if (request.method === 'POST' && !headers.has('Idempotency-Key')) {
+            headers.set('Idempotency-Key', crypto.randomUUID());
+        }
+        // JSON bodies are small: read once, sent again as they are on a retry.
+        const body = request.body ? await request.arrayBuffer() : null;
+        const { url, method } = request;
+        return this.#retrying((signal) => new Request(url, { method, headers, body, signal }), request.signal);
+    }
+    /** Sends a request made fresh for each attempt, retrying 429s, 5xx answers and network errors. */
+    async #retrying(make, signal) {
+        for (let attempt = 0;; attempt++) {
+            const timer = deadline(this.#timeoutMs, signal);
+            let response;
+            try {
+                response = await this.#fetch(make(timer.signal));
+            }
+            catch (error) {
+                if (signal?.aborted || attempt >= this.#maxRetries)
+                    throw error;
+                await sleep(backoff(attempt), signal);
+                continue;
+            }
+            finally {
+                timer.clear();
+            }
+            if (!RETRY_STATUSES.has(response.status) || attempt >= this.#maxRetries)
+                return response;
+            const wait = retryAfterSeconds(response);
+            if (wait !== undefined && wait > MAX_RETRY_AFTER_SECONDS)
+                return response;
+            await response.body?.cancel().catch(() => undefined);
+            await sleep(wait !== undefined ? wait * 1000 : backoff(attempt), signal);
+        }
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,47 @@
+import type { components } from './generated/openapi.js';
+/** An RFC 9457 problem document, as the API answers every error. */
+export type Problem = components['schemas']['Problem'];
+/** The API's error codes, stable across versions: https://formatjet.com/docs/errors */
+export type ErrorCode = Problem['code'];
+/**
+ * The codes a `FormatJetError` carries: the API's, `timeout` when the SDK stopped waiting for a
+ * job (the job carries on) and `canceled` for a job canceled while the SDK waited for it.
+ */
+export type FormatJetErrorCode = ErrorCode | 'timeout' | 'canceled';
+export interface FormatJetErrorInit {
+    code: FormatJetErrorCode;
+    detail: string;
+    status?: number;
+    requestId?: string;
+    jobId?: string;
+    retryAfter?: number;
+    problem?: Problem;
+}
+/**
+ * An error from the API (its problem document), a job that failed, or a wait that ran out.
+ * Branch on `code`: it's stable, while `message` is written for people.
+ */
+export declare class FormatJetError extends Error {
+    readonly name = "FormatJetError";
+    /** The problem document's `code`, or the failed job's `error.code`. */
+    readonly code: FormatJetErrorCode;
+    readonly detail: string;
+    /** The HTTP status, when the API answered with an error. */
+    readonly status: number | undefined;
+    /** `FormatJet-Request-Id`: quote it when you contact us. */
+    readonly requestId: string | undefined;
+    /** The job the error belongs to, when there is one. */
+    readonly jobId: string | undefined;
+    /** Seconds to wait before trying again (`Retry-After`), on 429 and some 503 answers. */
+    readonly retryAfter: number | undefined;
+    /** The whole problem document, with `errors` for each field that failed validation. */
+    readonly problem: Problem | undefined;
+    constructor(init: FormatJetErrorInit);
+}
+/** Seconds from a `Retry-After` header, when it holds a number of them. */
+export declare function retryAfterSeconds(response: Response): number | undefined;
+/**
+ * The error for an answer that wasn't a success. `body` is the answer's body when it has
+ * already been read (openapi-fetch reads it); otherwise it's read here.
+ */
+export declare function errorFromResponse(response: Response, body?: unknown): Promise<FormatJetError>;

package/dist/errors.js

@@ -0,0 +1,87 @@
+/**
+ * An error from the API (its problem document), a job that failed, or a wait that ran out.
+ * Branch on `code`: it's stable, while `message` is written for people.
+ */
+export class FormatJetError extends Error {
+    name = 'FormatJetError';
+    /** The problem document's `code`, or the failed job's `error.code`. */
+    code;
+    detail;
+    /** The HTTP status, when the API answered with an error. */
+    status;
+    /** `FormatJet-Request-Id`: quote it when you contact us. */
+    requestId;
+    /** The job the error belongs to, when there is one. */
+    jobId;
+    /** Seconds to wait before trying again (`Retry-After`), on 429 and some 503 answers. */
+    retryAfter;
+    /** The whole problem document, with `errors` for each field that failed validation. */
+    problem;
+    constructor(init) {
+        super(`${init.code}: ${init.detail}`);
+        this.code = init.code;
+        this.detail = init.detail;
+        this.status = init.status;
+        this.requestId = init.requestId;
+        this.jobId = init.jobId;
+        this.retryAfter = init.retryAfter;
+        this.problem = init.problem;
+    }
+}
+/** Seconds from a `Retry-After` header, when it holds a number of them. */
+export function retryAfterSeconds(response) {
+    const value = response.headers.get('Retry-After');
+    if (!value || !/^\d+$/.test(value.trim()))
+        return undefined;
+    return Number(value.trim());
+}
+function isProblem(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.code === 'string' &&
+        typeof value.status === 'number');
+}
+/**
+ * The error for an answer that wasn't a success. `body` is the answer's body when it has
+ * already been read (openapi-fetch reads it); otherwise it's read here.
+ */
+export async function errorFromResponse(response, body) {
+    let parsed = body;
+    if (parsed === undefined) {
+        const text = await response.text().catch(() => '');
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            parsed = text;
+        }
+    }
+    const requestId = response.headers.get('FormatJet-Request-Id') ?? undefined;
+    const retryAfter = retryAfterSeconds(response);
+    if (isProblem(parsed)) {
+        return new FormatJetError({
+            code: parsed.code,
+            detail: parsed.detail ?? parsed.title,
+            status: response.status,
+            requestId: parsed.request_id ?? requestId,
+            jobId: parsed.job_id,
+            retryAfter,
+            problem: parsed,
+        });
+    }
+    // Not one of ours: a proxy's page, or an answer cut short.
+    const code = response.status === 401
+        ? 'unauthorized'
+        : response.status === 404
+            ? 'not_found'
+            : response.status === 429
+                ? 'rate_limited'
+                : 'internal_error';
+    return new FormatJetError({
+        code,
+        detail: `The API answered ${response.status} ${response.statusText}`.trim(),
+        status: response.status,
+        requestId,
+        retryAfter,
+    });
+}