@formatjet/sdk 0.0.0-stage → 0.1.0

package/dist/generated/openapi.js

@@ -0,0 +1,2 @@
+// Generated by openapi-typescript from apps/api/openapi.json (bun run sdk:generate). Don't edit by hand.
+export {};

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { DEFAULT_BASE_URL, filenameFrom, FormatJet, Jobs, webhooks, type ApiClient, type ConversionOptions, type ConvertOptions, type ConvertResult, type DeletionReceipt, type FileData, type FileInput, type FormatId, type FormatJetOptions, type Job, type JobOutput, type JobRequest, type JobStatus, type JobStep, type JobSummary, type OutputFile, type RequestOptions, type Upload, type UploadAndConvertOptions, type WaitOptions, } from './client.js';
+export { FormatJetError, type ErrorCode, type FormatJetErrorCode, type FormatJetErrorInit, type Problem, } from './errors.js';
+export type { components, operations, paths } from './generated/openapi.js';
+export { DEFAULT_TOLERANCE_SECONDS, parseWebhook, SIGNATURE_HEADER, verifyWebhook, WebhookSignatureError, type VerifyWebhookInput, type WebhookEvent, type WebhookEventType, type WebhookVerification, } from './webhooks.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { DEFAULT_BASE_URL, filenameFrom, FormatJet, Jobs, webhooks, } from './client.js';
+export { FormatJetError, } from './errors.js';
+export { DEFAULT_TOLERANCE_SECONDS, parseWebhook, SIGNATURE_HEADER, verifyWebhook, WebhookSignatureError, } from './webhooks.js';

package/dist/webhooks.d.ts

@@ -0,0 +1,55 @@
+import type { components } from './generated/openapi.js';
+/** The header each delivery carries: `t=<unix seconds>,v1=<hex HMAC-SHA256>[,v1=…]`. */
+export declare const SIGNATURE_HEADER = "FormatJet-Signature";
+/** Deliveries signed longer ago than this (5 minutes) are refused, so a copy can't be replayed. */
+export declare const DEFAULT_TOLERANCE_SECONDS = 300;
+export type WebhookEventType = 'job.completed' | 'job.failed' | 'job.canceled';
+/** The body of a delivery. */
+export interface WebhookEvent {
+    /** `evt_…`: the same on every retry of this event, so use it to skip repeats. */
+    id: string;
+    type: WebhookEventType;
+    created_at: string;
+    mode: 'live' | 'test';
+    data: {
+        job: components['schemas']['Job'];
+    };
+}
+export interface VerifyWebhookInput {
+    /** The raw request body exactly as it arrived: read it before parsing the JSON. */
+    body: string | Uint8Array | ArrayBuffer;
+    /** The `FormatJet-Signature` header. */
+    header: string | null | undefined;
+    /** The endpoint's secret (`whsec_…`). */
+    secret: string;
+    toleranceSeconds?: number;
+    /** Now, in milliseconds (tests). */
+    now?: number;
+}
+export type WebhookVerification = {
+    ok: true;
+    timestamp: number;
+} | {
+    ok: false;
+    reason: 'missing_header' | 'malformed_header' | 'timestamp_out_of_range' | 'no_match';
+};
+/** A delivery whose signature didn't check out. */
+export declare class WebhookSignatureError extends Error {
+    readonly reason: Exclude<WebhookVerification, {
+        ok: true;
+    }>['reason'];
+    readonly name = "WebhookSignatureError";
+    constructor(reason: Exclude<WebhookVerification, {
+        ok: true;
+    }>['reason']);
+}
+/**
+ * Checks a delivery's signature: any `v1` made with the secret is enough (a rotation sends
+ * two), and a timestamp more than `toleranceSeconds` from now is refused.
+ */
+export declare function verifyWebhook(input: VerifyWebhookInput): Promise<WebhookVerification>;
+/**
+ * Checks a delivery and returns its event, or throws `WebhookSignatureError`. Answer 2xx
+ * quickly once it's checked: a delivery that takes over 10 seconds is retried.
+ */
+export declare function parseWebhook(input: VerifyWebhookInput): Promise<WebhookEvent>;

package/dist/webhooks.js

@@ -0,0 +1,77 @@
+/** The header each delivery carries: `t=<unix seconds>,v1=<hex HMAC-SHA256>[,v1=…]`. */
+export const SIGNATURE_HEADER = 'FormatJet-Signature';
+/** Deliveries signed longer ago than this (5 minutes) are refused, so a copy can't be replayed. */
+export const DEFAULT_TOLERANCE_SECONDS = 300;
+/** A delivery whose signature didn't check out. */
+export class WebhookSignatureError extends Error {
+    reason;
+    name = 'WebhookSignatureError';
+    constructor(reason) {
+        super(`The webhook signature isn't valid: ${reason}`);
+        this.reason = reason;
+    }
+}
+const encoder = new TextEncoder();
+function bytesOf(body) {
+    if (typeof body === 'string')
+        return encoder.encode(body);
+    return body instanceof Uint8Array ? body : new Uint8Array(body);
+}
+async function hmacHex(secret, message) {
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    const signature = new Uint8Array(await crypto.subtle.sign('HMAC', key, message));
+    return Array.from(signature, (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+/** Compares two strings in time that depends only on their length. */
+function sameText(a, b) {
+    if (a.length !== b.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < a.length; i++)
+        diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    return diff === 0;
+}
+/**
+ * Checks a delivery's signature: any `v1` made with the secret is enough (a rotation sends
+ * two), and a timestamp more than `toleranceSeconds` from now is refused.
+ */
+export async function verifyWebhook(input) {
+    if (!input.header)
+        return { ok: false, reason: 'missing_header' };
+    let timestamp;
+    const signatures = [];
+    for (const part of input.header.split(',')) {
+        const [name, value] = part.trim().split('=', 2);
+        if (name === 't' && value && /^\d{1,12}$/.test(value))
+            timestamp = Number(value);
+        else if (name === 'v1' && value && /^[0-9a-f]{64}$/.test(value))
+            signatures.push(value);
+    }
+    if (timestamp === undefined || signatures.length === 0) {
+        return { ok: false, reason: 'malformed_header' };
+    }
+    const now = Math.floor((input.now ?? Date.now()) / 1000);
+    if (Math.abs(now - timestamp) > (input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS)) {
+        return { ok: false, reason: 'timestamp_out_of_range' };
+    }
+    const body = bytesOf(input.body);
+    const prefix = encoder.encode(`${timestamp}.`);
+    const message = new Uint8Array(prefix.length + body.length);
+    message.set(prefix);
+    message.set(body, prefix.length);
+    const expected = await hmacHex(input.secret, message);
+    return signatures.some((signature) => sameText(signature, expected))
+        ? { ok: true, timestamp }
+        : { ok: false, reason: 'no_match' };
+}
+/**
+ * Checks a delivery and returns its event, or throws `WebhookSignatureError`. Answer 2xx
+ * quickly once it's checked: a delivery that takes over 10 seconds is retried.
+ */
+export async function parseWebhook(input) {
+    const result = await verifyWebhook(input);
+    if (!result.ok)
+        throw new WebhookSignatureError(result.reason);
+    const text = typeof input.body === 'string' ? input.body : new TextDecoder().decode(bytesOf(input.body));
+    return JSON.parse(text);
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@formatjet/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Convert documents, images, data and PDFs with the FormatJet API, from TypeScript and JavaScript.",
+  "license": "MIT",
+  "author": "Taprobane Labs",
+  "homepage": "https://formatjet.com/docs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TaprobaneLabs/formatjet.git",
+    "directory": "packages/sdk-js"
+  },
+  "keywords": [
+    "formatjet",
+    "file conversion",
+    "pdf",
+    "docx",
+    "api"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run build",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "openapi-fetch": "0.17.0"
+  },
+  "devDependencies": {
+    "openapi-typescript": "7.13.0"
+  }
+}