@formatjet/sdk 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taprobane Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,101 @@
-# Temporary Holding Version
+# FormatJet for TypeScript and JavaScript
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Convert documents, images, data and PDFs with the [FormatJet API](https://formatjet.com/docs): Word to PDF, PDF to Word, HEIC to JPG, Excel to CSV, Merge PDF and [the rest](https://formatjet.com/api).
+
+```sh
+npm install @formatjet/sdk
+```
+
+Node.js 20 or later, or Bun. ESM only.
+
+## Convert a file
+
+Make an API key in the [dashboard](https://formatjet.com/app/) and set `FORMATJET_API_KEY`. A test key (`fj_test_…`) converts for free with smaller limits.
+
+```ts
+import { readFile, writeFile } from 'node:fs/promises';
+import { FormatJet } from '@formatjet/sdk';
+
+const formatjet = new FormatJet(); // reads FORMATJET_API_KEY
+
+const result = await formatjet.convert(
+  { data: await readFile('report.docx'), filename: 'report.docx' },
+  { conversion: 'word-to-pdf' },
+);
+await writeFile(result.file.filename ?? 'report.pdf', result.file.data);
+```
+
+`convert()` sends the file in one request (up to 25 MB) and returns the converted files: `result.files` holds several for Split PDF, a PDF's pages as images or a workbook's sheets as CSV. Name the conversion by its slug (`GET /v1/operations` lists them), or say only the format to make: `{ to: 'pdf' }`. Options go in `options`, such as `{ conversion: 'pdf-to-jpg', options: { dpi: 300 } }`.
+
+Files come as a `Uint8Array` (Node's `Buffer` is one), an `ArrayBuffer`, a `Blob` or a `File`; pass `{ data, filename }` to name the output after the input.
+
+## Larger files
+
+`uploadAndConvert()` uploads the file straight to storage first, so it takes files up to your plan's limit, then makes a job, waits for it and downloads the result:
+
+```ts
+const result = await formatjet.uploadAndConvert(
+  { data: await readFile('scan.pdf'), filename: 'scan.pdf' },
+  { conversion: 'pdf-to-word', metadata: { order: '8812' }, onProgress: (job) => console.log(job.progress) },
+);
+```
+
+Files to join (Merge PDF, Image to PDF) go as a list, in order: `formatjet.convert([first, second], { conversion: 'merge-pdf' })`.
+
+## Jobs
+
+```ts
+const job = await formatjet.jobs.create({
+  input: { url: 'https://example.com/report.docx' },
+  steps: [{ op: 'convert', conversion: 'word-to-pdf' }],
+  webhook: 'https://example.com/hooks/formatjet',
+});
+const done = await formatjet.jobs.wait(job.id);
+const pdf = await formatjet.download(done.outputs[0]!);
+
+for await (const summary of formatjet.jobs.iterate()) console.log(summary.id, summary.status);
+await formatjet.jobs.delete(job.id); // files deleted now; returns the signed receipt
+```
+
+`jobs.get()`, `jobs.list()`, `jobs.cancel()` and `upload()` cover the rest, and `formatjet.api` calls any endpoint, typed from the OpenAPI document:
+
+```ts
+const { data } = await formatjet.api.GET('/v1/account');
+```
+
+## Errors and retries
+
+Failed calls and failed jobs throw `FormatJetError`. Branch on its `code` ([the list](https://formatjet.com/docs/errors)); `requestId` identifies the request if you contact us.
+
+```ts
+import { FormatJetError } from '@formatjet/sdk';
+
+try {
+  await formatjet.convert(file, { conversion: 'word-to-pdf' });
+} catch (error) {
+  if (error instanceof FormatJetError && error.code === 'insufficient_credits') {
+    // …
+  }
+}
+```
+
+The client retries 429s, 5xx answers and network errors twice, honouring `Retry-After`. Each POST carries an `Idempotency-Key`, the same on every retry, so a retry never makes a second job. Set `maxRetries` and `timeoutMs` in the constructor.
+
+## Webhooks
+
+Check each delivery's signature with the raw body, before parsing it:
+
+```ts
+const event = await formatjet.webhooks.parse({
+  body: await request.text(),
+  header: request.headers.get('FormatJet-Signature'),
+  secret: process.env.FORMATJET_WEBHOOK_SECRET!,
+});
+if (event.type === 'job.completed') console.log(event.data.job.outputs);
+```
+
+`parse()` throws `WebhookSignatureError` for a delivery that doesn't check out; `verify()` returns the reason instead.
+
+## Licence
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,175 @@
+import { type Client } from 'openapi-fetch';
+import type { components, paths } from './generated/openapi.js';
+import { parseWebhook, verifyWebhook } from './webhooks.js';
+type Schemas = components['schemas'];
+export type Job = Schemas['Job'];
+export type JobSummary = Schemas['JobSummary'];
+export type JobRequest = Schemas['JobRequest'];
+export type JobStep = JobRequest['steps'][number];
+export type JobStatus = Job['status'];
+export type JobOutput = Job['outputs'][number];
+export type Upload = Schemas['Upload'];
+export type DeletionReceipt = Schemas['DeletionReceiptResponse']['receipt'];
+/** A format's ID, such as `pdf` or `docx`. */
+export type FormatId = NonNullable<JobStep['to']>;
+/** The typed client for every endpoint, from the OpenAPI document. */
+export type ApiClient = Client<paths>;
+export declare const DEFAULT_BASE_URL = "https://api.formatjet.com";
+/** A file's bytes: a `Blob` or `File`, a `Uint8Array` (Node's `Buffer` is one) or an `ArrayBuffer`. */
+export type FileData = Blob | ArrayBuffer | ArrayBufferView;
+/** A file, with its name when it isn't a `File`: the output is named after it. */
+export type FileInput = FileData | {
+    data: FileData;
+    filename?: string;
+};
+export interface FormatJetOptions {
+    /** An API key from the dashboard. Defaults to the `FORMATJET_API_KEY` environment variable. */
+    apiKey?: string;
+    /** Defaults to https://api.formatjet.com. */
+    baseUrl?: string;
+    /** Retries after a 429, a 5xx answer or a network error (default 2). POSTs carry an Idempotency-Key, so a retry never runs a job twice. */
+    maxRetries?: number;
+    /** How long one request may take before it's retried, in milliseconds (default 5 minutes). */
+    timeoutMs?: number;
+    /** A `fetch` to use instead of the global one. */
+    fetch?: (request: Request) => Promise<Response>;
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+    /** Sent as `Idempotency-Key` (default: a new UUID for each call, kept across its retries). */
+    idempotencyKey?: string;
+}
+export interface ConversionOptions {
+    /** A conversion's slug from `GET /v1/operations`, such as `word-to-pdf`. */
+    conversion?: string;
+    /** The format to make, when `conversion` is left out. */
+    to?: FormatId;
+    /** What the file is; detected from its bytes when left out. */
+    from?: FormatId;
+    /** The conversion's options (`options_schema` in `GET /v1/operations`). */
+    options?: Record<string, unknown>;
+    /** The output's name (default: the input's name with the new extension). */
+    outputFilename?: string;
+    /** Seconds the output is kept after the job ends (default 86400). */
+    ttl?: number;
+}
+export interface WaitOptions {
+    signal?: AbortSignal;
+    /** How long to wait, in milliseconds (default 15 minutes). The job carries on after. */
+    timeoutMs?: number;
+    /** Called with the job each time it's read while it runs. */
+    onProgress?: (job: Job) => void;
+}
+export interface ConvertOptions extends ConversionOptions, RequestOptions {
+    /** How long to wait for a job that runs past the request's 30 seconds (default 15 minutes). */
+    timeoutMs?: number;
+}
+export interface UploadAndConvertOptions extends ConvertOptions {
+    /** Up to 20 string values, returned with the job and in its webhook events. */
+    metadata?: Record<string, string>;
+    /** A URL that gets this job's events, besides your webhook endpoints. */
+    webhook?: string;
+    onProgress?: (job: Job) => void;
+}
+export interface OutputFile {
+    /** The file's name, from the input's and the conversion's. */
+    filename: string | null;
+    mime: string;
+    data: Uint8Array;
+}
+export interface ConvertResult {
+    jobId: string;
+    /** The first (usually the only) converted file. */
+    file: OutputFile;
+    /** Every converted file in order: several for Split PDF, a PDF's pages as images and the like. */
+    files: OutputFile[];
+    /** Credits charged: none with a test key. */
+    credits: number;
+    /** The engine and its version, such as `office libreoffice-25.8+runner-7`. */
+    engine: string | null;
+    /** The job, when the API answered with it (several files, or a wait past 30 seconds). */
+    job: Job | null;
+}
+/** The name in a `Content-Disposition` header (`filename*` first, as RFC 6266 says). */
+export declare function filenameFrom(header: string | null): string | null;
+/** Jobs: make, read, list, wait for, cancel and delete them. */
+export declare class Jobs {
+    #private;
+    constructor(api: ApiClient);
+    /** Makes a job (`POST /v1/jobs`). It starts at once; wait for it with `wait()`. */
+    create(request: JobRequest, options?: RequestOptions): Promise<Job>;
+    get(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<Job>;
+    /** One page of jobs, newest first: pass `next_cursor` back as `cursor` for the next. */
+    list(params?: {
+        limit?: number;
+        cursor?: string;
+    }, options?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        data: JobSummary[];
+        next_cursor: string | null;
+    }>;
+    /** Every job of the last 30 days, newest first, a page at a time. */
+    iterate(params?: {
+        limit?: number;
+    }, options?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<JobSummary>;
+    /** Cancels a job that hasn't finished (`POST /v1/jobs/{id}/cancel`). */
+    cancel(id: string, options?: RequestOptions): Promise<Job>;
+    /** Deletes a job's files now and returns the signed deletion receipt. */
+    delete(id: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<DeletionReceipt>;
+    /**
+     * 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`.
+     */
+    wait(id: string, options?: WaitOptions): Promise<Job>;
+}
+/** The webhook signature helpers. */
+export declare const webhooks: {
+    readonly verify: typeof verifyWebhook;
+    readonly parse: typeof 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 declare class FormatJet {
+    #private;
+    readonly baseUrl: string;
+    /** The typed client for every endpoint (openapi-fetch). */
+    readonly api: ApiClient;
+    readonly jobs: Jobs;
+    readonly webhooks: {
+        readonly verify: typeof verifyWebhook;
+        readonly parse: typeof parseWebhook;
+    };
+    constructor(options?: FormatJetOptions);
+    /**
+     * 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.
+     */
+    convert(input: FileInput | FileInput[], options: ConvertOptions): Promise<ConvertResult>;
+    /**
+     * 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.
+     */
+    uploadAndConvert(input: FileInput | FileInput[], options: UploadAndConvertOptions): Promise<ConvertResult>;
+    /**
+     * Makes an upload and PUTs the file to it. Name the upload in a job's `input`
+     * (`{ upload_id: upload.id }`) within the hour.
+     */
+    upload(input: FileInput, options?: {
+        signal?: AbortSignal;
+    }): Promise<Upload>;
+    /** Downloads one of a job's outputs. Its URL needs no key and works until `expires_at`. */
+    download(output: JobOutput, options?: {
+        signal?: AbortSignal;
+    }): Promise<OutputFile>;
+}
+export {};