@bitavu/client 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bitavu
+
+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,96 @@
-# Temporary Holding Version
+# Bitavu for Node.js
 
-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.
+Generate PDF invoices, reports, and other documents from a saved [Bitavu](https://bitavu.com) template and JSON data. The client includes TypeScript declarations and runs on Node.js 22.13 or newer in the Node.js 22, 24, and 26 release lines. It has no runtime dependencies.
+
+```sh
+npm install @bitavu/client
+```
+
+## Render a PDF
+
+In [Bitavu Studio](https://studio.bitavu.com/), save a template revision. Use **Integrations → Prepare a template request** to get its ID, revision, and example JSON. Create an API key with **Generate PDFs** permission for that template.
+
+Load the key from your application's server environment. Keep it in an ignored local environment file during development and in your hosting provider's secret store in production.
+
+```ts
+import { randomUUID } from 'node:crypto';
+import { writeFile } from 'node:fs/promises';
+import { BitavuClient } from '@bitavu/client';
+
+const apiKey = process.env.BITAVU_API_KEY;
+if (!apiKey) throw new Error('Configure BITAVU_API_KEY.');
+
+const client = new BitavuClient({ apiKey });
+const operationId = randomUUID();
+
+const pdf = await client.renderPdf({
+  templateId: 'your-template-id',
+  revision: 1,
+  data: {
+    invoice: { number: 'INV-1001' },
+    items: [{ description: 'Design consultation', quantity: 1, unitPrice: 240 }],
+  },
+  idempotencyKey: operationId,
+});
+
+await writeFile('invoice.pdf', pdf.bytes);
+console.log('Rendered revision', pdf.revision);
+```
+
+Replace the template ID, revision, and data with the values for your template. The client preserves the property names in your JSON. It returns the PDF bytes as a `Uint8Array` and includes the resolved revision, page count, and request ID when the API supplies them.
+
+## Choose a revision
+
+Set `revision` to a number to render that saved revision. Set `revision: 'latest-published'` and pass `baseRevision` to follow the current publication while checking compatibility against a revision you tested. If you omit `baseRevision`, Bitavu compares the current publication against the first published revision.
+
+```ts
+const pdf = await client.renderPdf({
+  templateId,
+  revision: 'latest-published',
+  baseRevision: testedRevision,
+  data,
+  idempotencyKey: operationId,
+}, { signal });
+```
+
+If the published revision is incompatible, the API returns HTTP 409 with `JSON_COMPATIBILITY`. If there is no publication, it returns HTTP 404 with `NOT_PUBLISHED`. You can pass `mappingId` in either mode when you use a mapping saved in Studio.
+
+## Read templates and save examples
+
+| Method | Returns |
+| --- | --- |
+| `checkCredentials()` | Completes if the key is valid. |
+| `listTemplates()` | The accessible templates, including each folder path, latest saved revision, and Studio link. |
+| `getTemplateVersions(templateId, { page, pageSize, revision })` | A page of saved-version summaries with the latest revision and an optional selected revision. |
+| `getTemplate(templateId, revision)` | A saved revision's Studio link, data bindings, example JSON, and input review. |
+| `saveTemplateExample({ templateId, expectedRevision, exampleJson })` | The new saved revision and its updated input review. |
+
+Template reads require **Read templates**. Saving examples requires **Save template examples**. Use the latest saved revision as `expectedRevision`. On a conflict, fetch the latest revision and check its bindings before deciding whether to save again.
+
+Fixed response fields are typed. Template data can be your own TypeScript interface. When you call `getTemplate<YourData>(…)`, the type argument describes the JSON shape you expect. Validate the saved example in your app if its shape is uncertain.
+
+```ts
+interface InvoiceData {
+  invoice: { number: string };
+  items: { description: string; quantity: number; unitPrice: number }[];
+}
+
+const { exampleJson, inputReview, studioUrl } =
+  await client.getTemplate<InvoiceData>(templateId, testedRevision);
+```
+
+`inputReview.missing` lists bindings absent from the saved example. `inputReview.unused` lists paths the template does not use. Both `exampleJson` and `inputReview` are `null` if the revision has no saved example.
+
+## Errors and retries
+
+`BitavuApiError` contains the HTTP status, API code, request ID, and retry delay when available. `BitavuTransportError` identifies timeouts and network failures. Pass an `AbortSignal` to cancel a request.
+
+A request uses a deadline of two minutes by default. The caller controls retries. For the same render, reuse the operation ID with the same template, revision selection, and data. Respect `retryAfterMs` if returned. Use a new operation ID for a different render.
+
+## Node.js and Next.js guide
+
+Follow the [Bitavu Node.js and Next.js guide](https://bitavu.com/support/nodejs) to generate an invoice PDF with the Node.js client and return it as a download from a Next.js App Router Route Handler.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,17 @@
+import type { BitavuClientOptions, JsonObject, RenderedPdf, RenderPdfInput, RequestOptions, SaveTemplateExampleInput, TemplateCatalog, TemplateRevision, TemplateVersionOptions, TemplateVersionPage } from './types.js';
+export declare class BitavuClient {
+    #private;
+    constructor({ apiKey, apiOrigin, timeoutMs, fetch }: BitavuClientOptions);
+    /** Checks authentication without reading templates or using render credits. */
+    checkCredentials(options?: RequestOptions): Promise<void>;
+    /** Lists accessible templates and their latest saved revisions. */
+    listTemplates(options?: RequestOptions): Promise<TemplateCatalog>;
+    /** Returns metadata, bindings and the saved example for the selected revision. */
+    getTemplate<TExample extends object = JsonObject>(templateId: string, revision: number, options?: RequestOptions): Promise<TemplateRevision<TExample>>;
+    /** Returns a page of saved-version summaries, newest first. */
+    getTemplateVersions(templateId: string, { page, pageSize, revision, signal }?: TemplateVersionOptions): Promise<TemplateVersionPage>;
+    /** Saves example data as a new revision, using the latest saved revision as a precondition. */
+    saveTemplateExample<TExample extends object>(input: SaveTemplateExampleInput<TExample>, options?: RequestOptions): Promise<TemplateRevision<TExample>>;
+    /** Renders a PDF using an explicit revision or the latest compatible publication. */
+    renderPdf<TData extends object>(input: RenderPdfInput<TData>, options?: RequestOptions): Promise<RenderedPdf>;
+}

package/dist/client.js

@@ -0,0 +1,255 @@
+import { isCatalog, isRecord, isTemplateRevision, isVersionPage } from './contracts.js';
+import { BitavuApiError, BitavuTransportError } from './errors.js';
+const productionOrigin = 'https://api.bitavu.com';
+const stagingOrigin = 'https://api-staging.bitavu.com';
+const maxErrorBytes = 65_536;
+const pdfSignature = [0x25, 0x50, 0x44, 0x46, 0x2d]; // %PDF-
+export class BitavuClient {
+    #apiKey;
+    #apiOrigin;
+    #timeoutMs;
+    #fetch;
+    constructor({ apiKey, apiOrigin = productionOrigin, timeoutMs = 120_000, fetch = globalThis.fetch }) {
+        if (typeof apiKey !== 'string' || !/^[A-Za-z0-9_.~+/-]+=*(?![\s\S])/.test(apiKey)) {
+            throw new TypeError('Provide a valid Bitavu API key.');
+        }
+        if (apiOrigin !== productionOrigin && apiOrigin !== stagingOrigin) {
+            throw new TypeError('Use a supported Bitavu API origin.');
+        }
+        assertInteger(timeoutMs, 'timeoutMs', 2_147_483_647);
+        this.#apiKey = apiKey;
+        this.#apiOrigin = apiOrigin;
+        this.#timeoutMs = timeoutMs;
+        this.#fetch = fetch;
+    }
+    /** Checks authentication without reading templates or using render credits. */
+    async checkCredentials(options = {}) {
+        await this.#json('/v1/credentials/check', options, isAuthenticated);
+    }
+    /** Lists accessible templates and their latest saved revisions. */
+    listTemplates(options = {}) {
+        return this.#json('/v1/templates', options, isCatalog);
+    }
+    /** Returns metadata, bindings and the saved example for the selected revision. */
+    async getTemplate(templateId, revision, options = {}) {
+        assertInteger(revision, 'revision');
+        const result = await this.#json(templatePath(templateId) + '?revision=' + revision, options, isTemplateRevision);
+        return result;
+    }
+    /** Returns a page of saved-version summaries, newest first. */
+    async getTemplateVersions(templateId, { page = 1, pageSize = 10, revision, signal } = {}) {
+        assertInteger(page, 'page', 10_000);
+        assertInteger(pageSize, 'pageSize', 50);
+        const query = new URLSearchParams({ summary: 'true', page: String(page), pageSize: String(pageSize) });
+        if (revision !== undefined) {
+            assertInteger(revision, 'revision');
+            query.set('revision', String(revision));
+        }
+        return this.#json(templatePath(templateId) + '/versions?' + query, signal ? { signal } : {}, isVersionPage);
+    }
+    /** Saves example data as a new revision, using the latest saved revision as a precondition. */
+    async saveTemplateExample(input, options = {}) {
+        const path = templatePath(input.templateId) + '/example';
+        assertInteger(input.expectedRevision, 'expectedRevision', Number.MAX_SAFE_INTEGER - 1);
+        const exampleJson = serializeObject(input.exampleJson, 'exampleJson');
+        const result = await this.#json(path, options, isTemplateRevision, {
+            expectedRevision: input.expectedRevision,
+            exampleJson,
+        });
+        return result;
+    }
+    /** Renders a PDF using an explicit revision or the latest compatible publication. */
+    async renderPdf(input, options = {}) {
+        templatePath(input.templateId);
+        if (input.revision === 'latest-published') {
+            if (input.baseRevision !== undefined)
+                assertInteger(input.baseRevision, 'baseRevision');
+        }
+        else {
+            assertInteger(input.revision, 'revision');
+            if (input.baseRevision !== undefined) {
+                throw new TypeError('baseRevision is only valid with latest-published.');
+            }
+        }
+        if (typeof input.idempotencyKey !== 'string'
+            || !/^[A-Za-z0-9_-]{16,128}(?![\s\S])/.test(input.idempotencyKey)) {
+            throw new TypeError('Use 16 to 128 ASCII letters, digits, underscores or hyphens for idempotencyKey.');
+        }
+        if (input.mappingId !== undefined && (typeof input.mappingId !== 'string' || !input.mappingId.trim())) {
+            throw new TypeError('mappingId must be a non-empty string.');
+        }
+        const data = serializeObject(input.data, 'data');
+        return this.#request('/v1/render', options, 'application/pdf', async (response) => {
+            if (!hasMediaType(response, 'application/pdf'))
+                throw this.#unexpectedResponse(response);
+            const bytes = new Uint8Array(await response.arrayBuffer());
+            if (!pdfSignature.every((byte, index) => bytes[index] === byte)) {
+                throw this.#unexpectedResponse(response);
+            }
+            return {
+                bytes,
+                revision: positiveHeader(response, 'X-Bitavu-Revision'),
+                pageCount: positiveHeader(response, 'X-Bitavu-Pages'),
+                requestId: this.#requestId(response),
+            };
+        }, {
+            templateId: input.templateId,
+            revision: input.revision,
+            baseRevision: input.baseRevision,
+            mappingId: input.mappingId,
+            data,
+        }, input.idempotencyKey);
+    }
+    #json(path, options, isExpected, body) {
+        return this.#request(path, options, 'application/json', async (response) => {
+            if (!hasMediaType(response, 'application/json'))
+                throw this.#unexpectedResponse(response);
+            const text = await response.text();
+            let value;
+            try {
+                value = JSON.parse(text);
+            }
+            catch {
+                throw this.#unexpectedResponse(response);
+            }
+            if (!isExpected(value))
+                throw this.#unexpectedResponse(response);
+            return value;
+        }, body);
+    }
+    async #request(path, { signal }, accept, read, body, idempotencyKey) {
+        signal?.throwIfAborted();
+        const deadline = AbortSignal.timeout(this.#timeoutMs);
+        const headers = new Headers({ Accept: accept, Authorization: 'Bearer ' + this.#apiKey });
+        if (idempotencyKey !== undefined)
+            headers.set('Idempotency-Key', idempotencyKey);
+        const init = {
+            method: 'GET',
+            headers,
+            redirect: 'error',
+            cache: 'no-store',
+            signal: signal ? AbortSignal.any([signal, deadline]) : deadline,
+        };
+        if (body !== undefined) {
+            init.method = 'POST';
+            headers.set('Content-Type', 'application/json');
+            init.body = JSON.stringify(body);
+        }
+        let response;
+        try {
+            response = await this.#fetch(this.#apiOrigin + path, init);
+            if (!response.ok) {
+                const retryAfterMs = parseRetryAfter(response);
+                throw new BitavuApiError({
+                    status: response.status,
+                    code: await readErrorCode(response, this.#apiKey),
+                    requestId: this.#requestId(response),
+                    ...(retryAfterMs === undefined ? {} : { retryAfterMs }),
+                });
+            }
+            return await read(response);
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            if (deadline.aborted)
+                throw new BitavuTransportError('TIMEOUT');
+            if (error instanceof BitavuApiError)
+                throw error;
+            throw new BitavuTransportError('NETWORK_ERROR');
+        }
+        finally {
+            if (!response?.bodyUsed)
+                void response?.body?.cancel().catch(() => { });
+        }
+    }
+    #requestId(response) {
+        const value = response.headers.get('X-Bitavu-Request-Id');
+        return value && value !== this.#apiKey
+            && /^[\da-f]{8}(?:-[\da-f]{4}){3}-[\da-f]{12}$/i.test(value) ? value : null;
+    }
+    #unexpectedResponse(response) {
+        return new BitavuApiError({
+            status: response.status, code: null, requestId: this.#requestId(response), invalidResponse: true,
+        });
+    }
+}
+function templatePath(id) {
+    if (typeof id !== 'string' || !/^[A-Za-z0-9_-]{1,80}(?![\s\S])/.test(id)) {
+        throw new TypeError('Use 1 to 80 ASCII letters, digits, underscores or hyphens for templateId.');
+    }
+    return '/v1/templates/' + id;
+}
+function assertInteger(value, name, maximum = Number.MAX_SAFE_INTEGER) {
+    if (!Number.isSafeInteger(value) || value < 1 || value > maximum) {
+        throw new RangeError(name + ' must be an integer from 1 to ' + maximum + '.');
+    }
+}
+function serializeObject(value, name) {
+    let serialized;
+    if (isRecord(value)) {
+        try {
+            serialized = JSON.parse(JSON.stringify(value));
+        }
+        catch {
+            // Use a fixed message even when a user-defined serializer throws.
+        }
+    }
+    if (!isRecord(serialized))
+        throw new TypeError(name + ' must be serializable as a JSON object.');
+    return serialized;
+}
+function isAuthenticated(value) {
+    return isRecord(value) && value.authenticated === true;
+}
+function hasMediaType(response, expected) {
+    return response.headers.get('Content-Type')?.split(';', 1)[0]?.trim().toLowerCase() === expected;
+}
+function positiveHeader(response, name) {
+    const value = response.headers.get(name);
+    if (!value || !/^\d+$/.test(value))
+        return null;
+    const number = Number(value);
+    return Number.isSafeInteger(number) && number > 0 ? number : null;
+}
+function parseRetryAfter(response) {
+    const value = response.headers.get('Retry-After');
+    if (!value)
+        return undefined;
+    const ms = /^\d+$/.test(value) ? Number(value) * 1000 : Math.max(0, Date.parse(value) - Date.now());
+    return Number.isSafeInteger(ms) ? ms : undefined;
+}
+async function readErrorCode(response, apiKey) {
+    if (!hasMediaType(response, 'application/json') || !response.body)
+        return null;
+    const length = response.headers.get('Content-Length');
+    if (length && Number(length) > maxErrorBytes)
+        return null;
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let size = 0;
+    let text = '';
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            size += chunk.value.byteLength;
+            if (size > maxErrorBytes) {
+                void reader.cancel().catch(() => { });
+                return null;
+            }
+            text += decoder.decode(chunk.value, { stream: true });
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    try {
+        const value = JSON.parse(text + decoder.decode());
+        const code = isRecord(value) ? value.code : undefined;
+        return typeof code === 'string' && code !== apiKey && /^[A-Z][A-Z0-9_]{1,63}$/.test(code) ? code : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/contracts.d.ts

@@ -0,0 +1,5 @@
+import type { TemplateCatalog, TemplateRevision, TemplateVersionPage } from './types.js';
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function isCatalog(value: unknown): value is TemplateCatalog;
+export declare function isVersionPage(value: unknown): value is TemplateVersionPage;
+export declare function isTemplateRevision(value: unknown): value is TemplateRevision;

package/dist/contracts.js

@@ -0,0 +1,45 @@
+export function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isString(value) {
+    return typeof value === 'string';
+}
+function isList(value, check) {
+    return Array.isArray(value) && value.every(check);
+}
+function isInteger(value, minimum) {
+    return typeof value === 'number' && Number.isSafeInteger(value) && value >= minimum;
+}
+function isRevisionSummary(value) {
+    return isRecord(value)
+        && isString(value.id) && isString(value.name) && isString(value.studioUrl)
+        && isInteger(value.revision, 1)
+        && (value.createdAt === null || isInteger(value.createdAt, 0))
+        && (value.updatedAt === null || isInteger(value.updatedAt, 0));
+}
+export function isCatalog(value) {
+    return isRecord(value) && isList(value.templates, item => isRecord(item)
+        && isString(item.id) && isString(item.name) && isString(item.studioUrl)
+        && isList(item.path, isString) && isInteger(item.latestRevision, 1));
+}
+export function isVersionPage(value) {
+    return isRecord(value)
+        && isList(value.versions, version => isRevisionSummary(version)
+            && (version.title === null || isString(version.title)))
+        && isRevisionSummary(value.latest)
+        && (value.selected === null || isRevisionSummary(value.selected))
+        && isInteger(value.page, 1) && isInteger(value.pageSize, 1)
+        && isInteger(value.total, 0) && isInteger(value.pages, 0);
+}
+function isMissingInput(value) {
+    return isRecord(value) && isString(value.path) && typeof value.required === 'boolean';
+}
+export function isTemplateRevision(value) {
+    if (!isRevisionSummary(value))
+        return false;
+    const review = value.inputReview;
+    return isList(value.bindings, item => isMissingInput(item) && isString(item.type))
+        && (value.exampleJson === null || isRecord(value.exampleJson))
+        && (review === null || (isRecord(review)
+            && isList(review.missing, isMissingInput) && isList(review.unused, isString)));
+}

package/dist/errors.d.ts

@@ -0,0 +1,19 @@
+export declare class BitavuApiError extends Error {
+    readonly status: number;
+    readonly code: string | null;
+    readonly requestId: string | null;
+    readonly retryAfterMs: number | null;
+    /** @internal */
+    constructor(options: {
+        status: number;
+        code: string | null;
+        requestId: string | null;
+        retryAfterMs?: number;
+        invalidResponse?: boolean;
+    });
+}
+export declare class BitavuTransportError extends Error {
+    readonly code: 'TIMEOUT' | 'NETWORK_ERROR';
+    /** @internal */
+    constructor(code: 'TIMEOUT' | 'NETWORK_ERROR');
+}

package/dist/errors.js

@@ -0,0 +1,28 @@
+export class BitavuApiError extends Error {
+    status;
+    code;
+    requestId;
+    retryAfterMs;
+    /** @internal */
+    constructor(options) {
+        super(options.invalidResponse
+            ? 'Bitavu returned an unexpected response.'
+            : 'Bitavu API returned HTTP ' + options.status + '.');
+        this.name = 'BitavuApiError';
+        this.status = options.status;
+        this.code = options.code;
+        this.requestId = options.requestId;
+        this.retryAfterMs = options.retryAfterMs ?? null;
+    }
+}
+export class BitavuTransportError extends Error {
+    code;
+    /** @internal */
+    constructor(code) {
+        super(code === 'TIMEOUT'
+            ? 'The Bitavu request timed out.'
+            : 'The Bitavu request could not be completed.');
+        this.name = 'BitavuTransportError';
+        this.code = code;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { BitavuClient } from './client.js';
+export { BitavuApiError, BitavuTransportError } from './errors.js';
+export type * from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { BitavuClient } from './client.js';
+export { BitavuApiError, BitavuTransportError } from './errors.js';

package/dist/types.d.ts

@@ -0,0 +1,99 @@
+export type JsonValue = string | number | boolean | null | JsonObject | readonly JsonValue[];
+export interface JsonObject {
+    readonly [key: string]: JsonValue;
+}
+export interface BitavuClientOptions {
+    /** An API key loaded by your application from server-side configuration. */
+    apiKey: string;
+    /** Defaults to the public Bitavu API. Use a key for the selected environment. */
+    apiOrigin?: 'https://api.bitavu.com' | 'https://api-staging.bitavu.com';
+    /** Deadline for the HTTP request and response body, in milliseconds. Defaults to 120000. */
+    timeoutMs?: number;
+    /** Custom transport. This function receives the authenticated request. */
+    fetch?: typeof fetch;
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+}
+export interface TemplateListItem {
+    readonly id: string;
+    readonly name: string;
+    readonly path: readonly string[];
+    readonly latestRevision: number;
+    readonly studioUrl: string;
+}
+export interface TemplateCatalog {
+    readonly templates: readonly TemplateListItem[];
+}
+export interface TemplateRevisionSummary {
+    readonly id: string;
+    readonly name: string;
+    readonly revision: number;
+    /** Unix time in milliseconds. */
+    readonly createdAt: number | null;
+    /** Unix time in milliseconds. */
+    readonly updatedAt: number | null;
+    readonly studioUrl: string;
+}
+export interface TemplateVersion extends TemplateRevisionSummary {
+    readonly title: string | null;
+}
+export interface TemplateVersionPage {
+    readonly versions: readonly TemplateVersion[];
+    readonly latest: TemplateRevisionSummary;
+    readonly selected: TemplateRevisionSummary | null;
+    readonly page: number;
+    readonly pageSize: number;
+    readonly total: number;
+    readonly pages: number;
+}
+export interface TemplateVersionOptions extends RequestOptions {
+    page?: number;
+    pageSize?: number;
+    /** Ask the server to include the summary of this revision, even on another page. */
+    revision?: number;
+}
+export interface DataBinding {
+    readonly path: string;
+    readonly type: string;
+    readonly required: boolean;
+}
+export interface MissingInput {
+    readonly path: string;
+    readonly required: boolean;
+}
+export interface InputReview {
+    readonly missing: readonly MissingInput[];
+    readonly unused: readonly string[];
+}
+export interface TemplateRevision<TExample extends object = JsonObject> extends TemplateRevisionSummary {
+    readonly bindings: readonly DataBinding[];
+    /** The JSON shape is determined by the template. A supplied type is a caller assertion. */
+    readonly exampleJson: TExample | null;
+    readonly inputReview: InputReview | null;
+}
+export interface SaveTemplateExampleInput<TExample extends object = JsonObject> {
+    templateId: string;
+    expectedRevision: number;
+    exampleJson: TExample;
+}
+export type RenderSelection = {
+    revision: number;
+    baseRevision?: never;
+} | {
+    revision: 'latest-published';
+    baseRevision?: number;
+};
+export type RenderPdfInput<TData extends object = JsonObject> = RenderSelection & {
+    templateId: string;
+    data: TData;
+    /** Reuse this key only when retrying the same render with the same input. */
+    idempotencyKey: string;
+    mappingId?: string;
+};
+export interface RenderedPdf {
+    readonly bytes: Uint8Array<ArrayBuffer>;
+    readonly revision: number | null;
+    readonly pageCount: number | null;
+    readonly requestId: string | null;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,39 @@
 {
   "name": "@bitavu/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Generate PDFs from saved Bitavu visual templates and workflow data",
+  "license": "MIT",
+  "author": {"name":"bitavu.com","email":"integration+n8n@bitavu.com","url":"https://bitavu.com"},
+  "homepage": "https://bitavu.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bitavu/bitavu-node.git"
+  },
+  "keywords": ["bitavu", "pdf", "pdf-generation", "invoice", "templates", "typescript"],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "node": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "engines": {
+    "node": "^22.13.0 || ^24.0.0 || >=26.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "npm run build && node --test",
+    "prepack": "npm run build",
+    "check:package": "npm run build && node scripts/check-package.mjs"
+  },
+  "devDependencies": {
+    "typescript": "5.9.3",
+    "@types/node": "22.19.19"
+  }
+}