@formfeed/sdk 0.2.0 → 0.3.0

package/types/lib/client.d.ts

@@ -6,7 +6,11 @@
  */
 export type Region = 'eu' | 'us';
 export type Engine = 'jinja2' | 'liquid' | 'handlebars';
-export type OutputFormat = 'pdf' | 'png' | 'jpg' | 'webp';
+/**
+ * PDF and image templates, HTML and URLs produce `pdf` or an image; a Word template produces `docx`
+ * or `pdf`, a PowerPoint template `pptx` or `pdf`.
+ */
+export type OutputFormat = 'pdf' | 'png' | 'jpg' | 'webp' | 'docx' | 'pptx';
 export type RenderStatus = 'queued' | 'rendering' | 'succeeded' | 'failed';
 export interface FormfeedOptions {
     apiKey: string;
@@ -26,6 +30,7 @@ export interface RenderRequest {
     url?: string;
     engine?: Engine;
     data?: Record<string, unknown>;
+    /** Left out, the template decides: PDF, or an image template's `settings.image.format`. */
     output?: OutputFormat;
     settings?: Record<string, unknown>;
     filename?: string;
@@ -39,11 +44,36 @@ export interface RenderRequest {
     meta?: Record<string, unknown>;
     region?: Region;
     dedupe?: boolean;
+    /**
+     * Decides a channel's canary split: renders with the same value (a customer or order id) land on the
+     * same version. Not the Idempotency-Key, which would replay the first response for every render.
+     */
+    canary_key?: string | null;
     /** PDF post-processing: merge, watermark, password, applied in that order (0.5 units each). */
     post?: PostProcessing | null;
     /** Check `data` against the template's stored schema first; a mismatch throws `data_validation_error`. */
     validate_data?: boolean;
 }
+/**
+ * Slug → data type of the workspace's templates. Empty here; the file `formfeed types` generates
+ * augments it (`declare module '@formfeed/sdk' { interface FormfeedTemplates { invoice: InvoiceData } }`),
+ * which makes `renders.create({ template: 'invoice', data })` check `data` at compile time.
+ */
+export interface FormfeedTemplates {
+}
+/** The data type of template `T`: generated for known slugs, a plain record otherwise. */
+export type TemplateData<T> = T extends keyof FormfeedTemplates ? FormfeedTemplates[T] : Record<string, unknown>;
+/**
+ * A render request whose `data` follows the template's generated type. A slug the generated file
+ * does not know, a template id or a string variable keeps the untyped `Record<string, unknown>`.
+ */
+export type TypedRenderRequest<T extends string = string> = Omit<RenderRequest, 'template' | 'data'> & {
+    template?: T;
+} & (T extends keyof FormfeedTemplates ? {
+    data: FormfeedTemplates[T];
+} : {
+    data?: Record<string, unknown>;
+});
 export type PdfPermission = 'print' | 'copy' | 'modify' | 'annotate';
 /** A text or an image watermark; pass one of `text` and `image`. */
 export interface WatermarkOptions {
@@ -105,10 +135,13 @@ export interface Render {
     units: number;
     region: string;
     environment: 'live' | 'test';
+    /** `channel`: the release channel the version came from; `canary` when the channel's canary share picked it. */
     template: {
         id: string;
         slug: string;
         version: number;
+        channel?: string | null;
+        canary?: boolean;
     } | null;
     engine_version: string | null;
     template_checksum: string | null;
@@ -124,9 +157,16 @@ export interface Render {
     created_at: string;
     completed_at: string | null;
 }
-export interface BatchRequest {
-    template?: string;
-    items: RenderRequest[];
+export interface BatchRequest<T extends string = string> {
+    /** Default template of the items; with a generated type for it, every item's `data` is checked. */
+    template?: T;
+    /** Default `canary_key` of the items; without one the whole batch lands on one version. */
+    canary_key?: string;
+    /** Default `output` of the items; an item's own wins, without either its template decides. */
+    output?: OutputFormat;
+    items: Array<Omit<RenderRequest, 'data'> & {
+        data?: TemplateData<T>;
+    }>;
     zip?: boolean;
     webhook_url?: string | null;
     webhook_secret?: string | null;
@@ -166,16 +206,97 @@ export interface FileUpload {
     /** Sent with the bytes; the API also goes by the extension when it is missing. */
     contentType?: string;
 }
+/** A Word, PowerPoint or other office file sent to the API: a template's file or a document to convert. */
+export interface OfficeFileUpload {
+    /** The bytes: a Blob or File, a Uint8Array (Node's Buffer is one) or an ArrayBuffer. */
+    data: Blob | Uint8Array | ArrayBuffer;
+    /** The file name, e.g. `offer.docx`; a File's own name when omitted. The API reads the type from the content. */
+    name?: string;
+}
+export interface ConvertOptions extends PdfOutputOptions {
+    /** Pages to convert, e.g. `1-3,5`; all when omitted. */
+    page_ranges?: string;
+    /** Landscape for spreadsheets and documents without their own page setup. */
+    landscape?: boolean;
+    /** Each spreadsheet sheet on one page. */
+    single_page_sheets?: boolean;
+}
 export interface FileListOptions {
     /** Only names starting with this, e.g. `brand/`. */
     prefix?: string;
     limit?: number;
     cursor?: string | null;
 }
+/**
+ * The organisation's brand kit (`GET /brand`): what templates see as `brand`, plus the page defaults
+ * new templates start from. Unset values are `null`; `colors` is always an object.
+ */
+export interface Brand {
+    version: number;
+    name: string | null;
+    /** Token → hex colour, e.g. `primary`; also `--brand-color-<token>` in the document. */
+    colors: Record<string, string>;
+    fonts: {
+        heading: string | null;
+        body: string | null;
+    };
+    font_size: string | null;
+    /** CDN URLs of the logos. */
+    logo: {
+        primary: string | null;
+        inverse: string | null;
+        mark: string | null;
+    };
+    legal_footer: string | null;
+    /** `{}` when unset. */
+    page_defaults: {
+        paper?: {
+            format?: string;
+            landscape?: boolean;
+        };
+        margin?: {
+            top?: string;
+            right?: string;
+            bottom?: string;
+            left?: string;
+        };
+    };
+    updated_at: string | null;
+}
+/** A shared partial of the organisation (`/partials`), included by name from templates of its engine. */
+export interface SharedPartial {
+    /** Lowercase letters, digits, `-` and `_`; the API stores a name in lowercase. */
+    name: string;
+    engine: Engine;
+    description: string | null;
+    version: number;
+    /** Only when read one by one (`partials.get`) and in the result of `partials.put`. */
+    source?: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface SharedPartialPut {
+    engine: Engine;
+    source: string;
+    description?: string | null;
+    /**
+     * The version the change is based on; the API answers 409 `conflict` when the partial has another,
+     * with the stored partial as `problem.current` (`null` when it was deleted).
+     */
+    base_version?: number;
+}
+export interface SharedPartialPutResult {
+    partial: SharedPartial;
+    /** `true` when the name did not exist before (201), `false` for an update (200). */
+    created: boolean;
+}
+export type WebhookEnvironment = 'live' | 'test';
 export interface WebhookEndpoint {
     id: string;
     url: string;
     events: string[];
+    /** Render environments whose events the endpoint receives; both by default. Quota events are sent regardless. */
+    environments?: WebhookEnvironment[];
     enabled: boolean;
     description: string | null;
     consecutive_failures: number;
@@ -184,7 +305,78 @@ export interface WebhookEndpoint {
     created_at: string;
     updated_at: string;
 }
-export type TemplateKind = 'pdf' | 'image';
+export interface WebhookEndpointCreate {
+    url: string;
+    events?: string[];
+    environments?: WebhookEnvironment[];
+    description?: string | null;
+}
+export interface WebhookEndpointUpdate {
+    url?: string;
+    events?: string[];
+    environments?: WebhookEnvironment[];
+    enabled?: boolean;
+    description?: string | null;
+}
+export interface ListenSessionOptions {
+    /** Event types the session receives; all by default. */
+    events?: string[];
+    /** Include live-environment events (needs `webhook:manage`); test events only by default. */
+    live?: boolean;
+}
+/**
+ * A listen session (`POST /webhooks/listen`): receives the workspace's events like an endpoint and relays
+ * them over `websocket_url`, which is valid for 60 seconds and needs no key. The SDK opens no socket.
+ */
+export interface ListenSession {
+    id: string;
+    /** Signs the session's deliveries. */
+    secret: string;
+    events: string[];
+    environments: WebhookEnvironment[];
+    expires_at: string;
+    websocket_url: string;
+}
+export interface WebhookResend {
+    delivery_id: string;
+    event_id: string;
+    event: string;
+    endpoint_id: string;
+}
+/**
+ * The stored request of a render (`GET /renders/{id}/input`). Template renders carry `template` and
+ * `data`, ad-hoc renders `html` or `url`. Passwords of `post` are never included.
+ */
+export interface RenderInput {
+    render_id: string;
+    template?: {
+        id: string;
+        slug: string;
+        version: number;
+        channel?: string | null;
+    };
+    html?: string;
+    engine?: Engine;
+    url?: string;
+    data?: Record<string, unknown>;
+    locale?: string | null;
+    output?: OutputFormat;
+    settings?: Record<string, unknown>;
+    filename?: string;
+    post?: Record<string, unknown>;
+    meta?: Record<string, unknown>;
+    environment: 'live' | 'test';
+    created_at: string;
+}
+/** `docx` and `pptx` templates are Word and PowerPoint files with tags in their text (Starter plan and above). */
+export type TemplateKind = 'pdf' | 'image' | 'docx' | 'pptx';
+export type OfficeTemplateKind = 'docx' | 'pptx';
+/** The file of a Word or PowerPoint template version; download it with `templates.versions.file`. */
+export interface TemplateFile {
+    sha256: string;
+    bytes: number;
+    format: OfficeTemplateKind;
+}
 export type VersionStatus = 'draft' | 'published' | 'archived';
 export interface Template {
     id: string;
@@ -243,6 +435,69 @@ export interface TemplateVersion extends Partial<TemplateFiles> {
     change_note: string | null;
     created_at: string;
     published_at: string | null;
+    /** Publishing only: how the data schema changed against the version callers used before. */
+    schema_check?: SchemaCheck;
+    /** Word and PowerPoint templates: the version's file; `null` for other kinds. */
+    source_file?: TemplateFile | null;
+}
+/** One difference between two data schemas, from the point of view of a caller sending data. */
+export interface SchemaChange {
+    /** Dotted field path (`customer.email`, `items[]`); empty for the data itself. */
+    path: string;
+    pointer: string;
+    kind: string;
+    breaking: boolean;
+    message: string;
+}
+/**
+ * The schema comparison publishing and channel moves run. `stored`: both versions store a schema and
+ * breaking changes are refused unless `allowBreaking` is set. `inferred`: compared from sample data,
+ * a warning only. `none`: nothing to compare.
+ */
+export interface SchemaCheck {
+    source: 'stored' | 'inferred' | 'none';
+    breaking: SchemaChange[];
+    safe: SchemaChange[];
+}
+/** A release channel of a template (`published` or a named one such as `staging`). */
+export interface Channel {
+    name: string;
+    version: number | null;
+    canary: {
+        version: number;
+        percent: number;
+    } | null;
+    /** The version before the last move; `rollback` returns to it. */
+    previous_version: number | null;
+    updated_at: string;
+    /** Renders of the last 24 hours through this channel, per version (list only). */
+    usage_24h?: Array<{
+        version: number;
+        renders: number;
+        failed: number;
+    }>;
+    /** Writes only. */
+    schema_check?: SchemaCheck;
+}
+export interface ChannelList {
+    data: Channel[];
+    /** The plan's allowance: named channels per template (`null` unlimited) and whether canaries are allowed. */
+    limits: {
+        channels: number | null;
+        canary: boolean;
+    };
+}
+export interface ChannelMove {
+    version: number;
+    /** A second version that receives `percent` (1 to 50) of the channel's renders; `null` clears it. */
+    canary?: {
+        version: number;
+        percent: number;
+    } | null;
+}
+export interface SchemaGuardOptions extends RequestOptions {
+    /** Go ahead although the data schema breaks callers of the current version. */
+    allowBreaking?: boolean;
 }
 export interface TemplateCreate extends TemplateFiles {
     name: string;
@@ -258,6 +513,32 @@ export interface TemplateVersionCreate extends TemplateFiles {
     /** Checksum of the version the draft was based on; the API answers 409 when the latest differs. */
     base_checksum?: string;
     publish?: boolean;
+    /** With `publish`: go ahead although the data schema breaks callers of the published version. */
+    allow_breaking?: boolean;
+}
+/** What a Word or PowerPoint template has besides its file: no markup, no partials. */
+type OfficeFields = Omit<TemplateFiles, 'html' | 'css' | 'head' | 'partials'>;
+/** A Word or PowerPoint template, created from its file (up to 20 MB). */
+export interface OfficeTemplateCreate extends OfficeFields {
+    name: string;
+    slug: string;
+    description?: string | null;
+    kind: OfficeTemplateKind;
+    engine: Engine;
+    tags?: string[];
+    publish?: boolean;
+    file: OfficeFileUpload;
+}
+/**
+ * A new version of a Word or PowerPoint template: with `file`, the new document; without, the
+ * latest version's file is kept and only data, schema or settings change.
+ */
+export interface OfficeVersionCreate extends OfficeFields {
+    file?: OfficeFileUpload;
+    change_note?: string;
+    base_checksum?: string;
+    publish?: boolean;
+    allow_breaking?: boolean;
 }
 export interface Usage {
     period: string;
@@ -328,7 +609,7 @@ export declare class Formfeed {
     constructor(options: FormfeedOptions);
     readonly renders: {
         /** Renders a template, HTML or URL. Sync by default; `mode: 'async'` returns a queued render. */
-        create: (request: RenderRequest, options?: RequestOptions) => Promise<Render>;
+        create: <T extends string = string>(request: TypedRenderRequest<T>, options?: RequestOptions) => Promise<Render>;
         get: (id: string, options?: RequestOptions) => Promise<Render>;
         /** Polls until the render succeeded or failed (async renders). */
         waitFor: (id: string, options?: WaitOptions) => Promise<Render>;
@@ -343,7 +624,12 @@ export declare class Formfeed {
         all: (query?: Omit<RenderListOptions, "cursor">, options?: RequestOptions) => Promise<Render[]>;
         /** Removes the stored files of a render before they expire. Needs the `file:delete` scope. */
         deleteOutputs: (id: string, options?: RequestOptions) => Promise<void>;
-        batch: (request: BatchRequest, options?: RequestOptions) => Promise<Job>;
+        /**
+         * The stored request of a render, to render it again. Needs `render:input`; throws
+         * `render_input_expired` (410) when the workspace keeps no requests or the period ended.
+         */
+        input: (id: string, options?: RequestOptions) => Promise<RenderInput>;
+        batch: <T extends string = string>(request: BatchRequest<T>, options?: RequestOptions) => Promise<Job>;
     };
     /**
      * PDF tools on the outputs of earlier renders (a `Render` or its id) and on PDFs of the file library
@@ -355,6 +641,15 @@ export declare class Formfeed {
         protect: (source: Render | string, protect: ProtectOptions, options?: RequestOptions) => Promise<Render>;
         watermark: (source: Render | string, watermark: WatermarkOptions & PdfOutputOptions, options?: RequestOptions) => Promise<Render>;
         info: (source: Render | string, options?: RequestOptions) => Promise<PdfInfo>;
+        /**
+         * Converts an office document to a PDF render (Starter plan and above): an uploaded file (Word,
+         * Excel, PowerPoint, OpenDocument, RTF or HTML, up to 20 MB, not kept), or the output of a Word or
+         * PowerPoint template render. Costs follow the PDF rule. A busy converter answers 503, which is
+         * retried like any other.
+         */
+        convert: (source: {
+            file: OfficeFileUpload;
+        } | Render | string, convert?: ConvertOptions, options?: RequestOptions) => Promise<Render>;
     };
     /**
      * The workspace file library (`/files`): images and PDFs a template references by name with
@@ -376,27 +671,49 @@ export declare class Formfeed {
         /** Removes the file and its bytes; templates that name it render a missing image afterwards. */
         delete: (file: LibraryFile | string, options?: RequestOptions) => Promise<void>;
     };
+    /** The organisation's brand kit, read-only through the API (it is edited in the app). Needs `template:read`. */
+    readonly brand: {
+        get: (options?: RequestOptions) => Promise<Brand>;
+    };
+    /**
+     * Shared partials of the organisation. Renders use the current source, so a change reaches every
+     * template that includes the partial without a new version. Needs `template:read` or `template:write`.
+     */
+    readonly partials: {
+        /** Every shared partial, without its source. */
+        list: (options?: RequestOptions) => Promise<SharedPartial[]>;
+        /** One partial with its source. */
+        get: (name: string, options?: RequestOptions) => Promise<SharedPartial>;
+        /** Creates or replaces a partial; pass `base_version` to fail with 409 when it changed since you read it. */
+        put: (name: string, input: SharedPartialPut, options?: RequestOptions) => Promise<SharedPartialPutResult>;
+        /** Removes a partial; templates that still include it fail to render afterwards. */
+        delete: (name: string, options?: RequestOptions) => Promise<void>;
+    };
     readonly jobs: {
         get: (id: string, options?: RequestOptions) => Promise<Job>;
         waitFor: (id: string, options?: WaitOptions) => Promise<Job>;
     };
     readonly webhooks: {
         list: (options?: RequestOptions) => Promise<WebhookEndpoint[]>;
-        create: (input: {
-            url: string;
-            events?: string[];
-            description?: string | null;
-        }, options?: RequestOptions) => Promise<WebhookEndpoint>;
-        update: (id: string, patch: {
-            url?: string;
-            events?: string[];
-            enabled?: boolean;
-            description?: string | null;
-        }, options?: RequestOptions) => Promise<WebhookEndpoint>;
+        create: (input: WebhookEndpointCreate, options?: RequestOptions) => Promise<WebhookEndpoint>;
+        update: (id: string, patch: WebhookEndpointUpdate, options?: RequestOptions) => Promise<WebhookEndpoint>;
         delete: (id: string, options?: RequestOptions) => Promise<void>;
         test: (id: string, options?: RequestOptions) => Promise<{
             queued: boolean;
         }>;
+        /**
+         * Sends a stored event (`evt_…`) again as a new delivery to a registered endpoint (`webhook:manage`)
+         * or a running listen session (`webhook:listen`).
+         */
+        resend: (eventId: string, endpointId: string, options?: RequestOptions) => Promise<WebhookResend>;
+        /**
+         * Listen sessions, what `formfeed listen` uses. Needs `webhook:listen`. Starting a session ends the
+         * previous one of the same key; the WebSocket itself is up to the caller.
+         */
+        listen: {
+            start: (input?: ListenSessionOptions, options?: RequestOptions) => Promise<ListenSession>;
+            end: (id: string, options?: RequestOptions) => Promise<void>;
+        };
     };
     readonly templates: {
         list: (query?: TemplateListOptions, options?: RequestOptions) => Promise<{
@@ -406,7 +723,8 @@ export declare class Formfeed {
         /** Every template of the workspace, following the cursor. */
         all: (query?: Omit<TemplateListOptions, "cursor">, options?: RequestOptions) => Promise<Template[]>;
         get: (idOrSlug: string, options?: RequestOptions) => Promise<Template>;
-        create: (input: TemplateCreate, options?: RequestOptions) => Promise<Template>;
+        /** A Word or PowerPoint template (`kind` `docx` or `pptx`) is created from its `file`, sent as multipart. */
+        create: (input: TemplateCreate | OfficeTemplateCreate, options?: RequestOptions) => Promise<Template>;
         update: (idOrSlug: string, patch: {
             name?: string;
             description?: string | null;
@@ -415,10 +733,34 @@ export declare class Formfeed {
         archive: (idOrSlug: string, options?: RequestOptions) => Promise<void>;
         versions: {
             list: (idOrSlug: string, options?: RequestOptions) => Promise<TemplateVersion[]>;
-            /** `which`: 'published', 'latest' or a version number. Carries the files. */
-            get: (idOrSlug: string, which?: "published" | "latest" | number, options?: RequestOptions) => Promise<TemplateVersion>;
-            create: (idOrSlug: string, input: TemplateVersionCreate, options?: RequestOptions) => Promise<TemplateVersion>;
-            publish: (idOrSlug: string, number: number, options?: RequestOptions) => Promise<TemplateVersion>;
+            /** `which`: 'published', 'latest', a version number or a channel name (its main version). Carries the files. */
+            get: (idOrSlug: string, which?: string | number, options?: RequestOptions) => Promise<TemplateVersion>;
+            /** For a Word or PowerPoint template, pass `file` to replace the document; without it the latest file is kept. */
+            create: (idOrSlug: string, input: TemplateVersionCreate | OfficeVersionCreate, options?: RequestOptions) => Promise<TemplateVersion>;
+            /** The Word or PowerPoint file of a version (`which` as for `get`); needs `template:read`. */
+            file: (idOrSlug: string, which?: string | number, options?: RequestOptions) => Promise<Uint8Array>;
+            /**
+             * Publishes a version. When both versions store a data schema and the new one breaks callers of the
+             * published one, the API refuses with `schema_breaking_change` unless `allowBreaking` is set.
+             */
+            publish: (idOrSlug: string, number: number, options?: SchemaGuardOptions) => Promise<TemplateVersion>;
+        };
+        /**
+         * Release channels (`published` and named ones such as `staging`): a render with `version: 'staging'`
+         * uses the version the channel points at. Moves reach renders within a minute.
+         */
+        channels: {
+            list: (idOrSlug: string, options?: RequestOptions) => Promise<ChannelList>;
+            /** Creates or moves a channel; on `published` this publishes. */
+            set: (idOrSlug: string, name: string, move: ChannelMove, options?: SchemaGuardOptions) => Promise<Channel>;
+            /** The canary becomes the main version. */
+            promote: (idOrSlug: string, name: string, options?: SchemaGuardOptions) => Promise<Channel>;
+            /** Back to the version before the last move. */
+            rollback: (idOrSlug: string, name: string, options?: SchemaGuardOptions) => Promise<Channel>;
+            /** Refused with `channel_in_use` while renders of the last hour used the channel, unless `force`. */
+            delete: (idOrSlug: string, name: string, options?: RequestOptions & {
+                force?: boolean;
+            }) => Promise<void>;
         };
         schema: (idOrSlug: string, options?: RequestOptions) => Promise<Record<string, unknown>>;
         /**
@@ -436,7 +778,22 @@ export declare class Formfeed {
         /** Units of the current period, or of `YYYY-MM`, with a daily series and a breakdown per template. */
         usage: (period?: string, options?: RequestOptions) => Promise<Usage>;
     };
+    /** Workspaces of the key's organisation. Needs `workspace:delete`, which no key has by default. */
+    readonly workspaces: {
+        /**
+         * Deletes a workspace: it leaves the app and the API at once, its keys are revoked and its content
+         * is removed after 30 days. The organisation's last workspace is refused with `last_workspace`.
+         */
+        delete: (id: string, options?: RequestOptions) => Promise<void>;
+    };
+    private channelAction;
     /** Raw request with auth, retries and problem mapping; use it for endpoints without a helper. */
     request<T>(method: string, path: string, body?: unknown, options?: RequestOptions): Promise<T>;
+    /**
+     * `request` with the HTTP status, for endpoints whose answer depends on it (201 created, 200 updated).
+     * `bytes` returns a successful body as bytes (file downloads); problems are JSON either way.
+     */
+    private send;
     private backoff;
 }
+export {};