@bitavu/n8n-nodes-bitavu 0.1.2 → 0.1.4

package/README.md

@@ -1,25 +1,31 @@
 # @bitavu/n8n-nodes-bitavu
 
-Generate PDFs from [Bitavu](https://bitavu.com)'s visual templates and data in
-your n8n workflow. Design and test the layout in Studio, save a version, then
-use **Bitavu → Generate PDF**.
+Generate PDFs from [Bitavu](https://bitavu.com)'s visual templates and workflow
+data. Dedicated template nodes list templates, inspect saved versions, and save
+example JSON.
 
 The [HTTP Request guide](https://bitavu.com/support/n8n) remains available for
-n8n Cloud and self-hosted instances. n8n verification of this node is pending.
+n8n Cloud and self-hosted instances.
 
 ## Installation
 
 Self-hosted n8n owners can install `@bitavu/n8n-nodes-bitavu`
 through **Settings → Community nodes → Install**. Follow
 [n8n's installation instructions](https://docs.n8n.io/integrations/community-nodes/installation/).
-n8n Cloud requires a verified community node; this package is not yet verified.
+On n8n Cloud, install an n8n-verified version from the nodes panel.
 
 ## Credentials
 
-Create a **Bitavu API** credential and paste your API key. In Studio's
-**Integrations → API keys**, reuse a suitable active key or create one with
-**Generate PDFs** permission for the report. **Read templates** is not needed.
-Keep the secret in Credentials, never in exported workflow JSON.
+Create a **Bitavu API** credential and paste your API key. Give it access to
+the templates in the workflow and the permission for each operation.
+
+| Operation | Permission |
+| --- | --- |
+| Generate PDF | Generate PDFs |
+| List Templates, List Template Versions, Get Template Version | Read templates |
+| Save Template Example | Save template examples |
+
+Store the key in n8n Credentials.
 
 Credential testing sends an authenticated, read-only `GET /v1/credentials/check`
 request. It does not read reports, generate a PDF or consume render credits.
@@ -32,21 +38,56 @@ and remaining allowance are checked when rendering.
    content to fields, save a version and test it.
 2. Copy **templateId**, numeric **revision** and **data** from **Integrations →
    Prepare a template request → Use in your app**.
-3. Add **Bitavu → Generate PDF** and select your credential.
-4. Set **Template ID**, **Saved Version** and **Document Data**. Map the JSON
+3. Search for **Bitavu**, add **Generate PDF**, and select your credential.
+4. Set **Template**, **Version Selection**, and **Document Data**. Map the JSON
    object using an expression such as `{{ $json.data }}` or `{{ $json }}`.
 5. Execute. Each input item produces a PDF in the **pdf** binary field, ready
    for an email, file-storage or other node accepting binary data.
 
-The node calls `POST https://api.bitavu.com/v1/render`, handles Bearer
-authentication and binary PDF output, and keeps TLS verification enabled.
-It preserves input JSON, existing binary fields and item pairing, and adds
-`bitavu` metadata with the template, version, operation ID and filename.
+Use **Template → From List** to search the templates your key can read, sorted by folder and name. The key
+needs **Read templates** permission for the picker and **Generate PDFs** for the
+render. **By ID** accepts a template ID or an expression and works with a key
+that only has **Generate PDFs** permission.
+
+Choose **Pinned** and select the **Pinned Version** to keep using a tested layout.
+Use **From List** with **Read templates** permission to see saved versions from newest
+to oldest, with the current publication marked **Published**. Use **By Number** to
+enter the saved version directly. Template and version are node settings. The
+incoming data can contain just the document fields.
+Choose **Latest Published** to follow the current publication when its JSON
+contract is compatible. The version field becomes **Base Version**, and carries
+over the version you entered. Leave it empty to compare against the first
+published version. If compatibility fails, review the changes in Studio or pin
+the tested version. Set **Options → Mapping ID** to use a mapping saved in Studio.
+
+The node preserves input JSON, existing binary fields, and item pairing. The
+`bitavu` output includes the requested and rendered revisions, page count,
+request ID, operation ID, and output file information. The rendered revision
+comes from the API when available. A pinned render can fall back to its requested
+revision.
 
 Any saved Bitavu report works when the supplied data matches that version.
 `examples/bitavu-generate-pdf.json` uses fictional data with the starter invoice
 (`invoice`, saved version 1) and contains no credentials.
 
+## Work with templates
+
+Search for **Bitavu** in the nodes panel and add the action you need. Each node
+has its own settings and uses the same **Bitavu API** credential. Results are
+returned under `$json.bitavu`.
+
+| Operation | Result |
+| --- | --- |
+| List Templates | Accessible templates with folder paths, latest saved revisions, and Studio links |
+| List Template Versions | Saved versions with a `published` flag on each row, the current `publishedRevision`, the latest summary, and an optional selected summary |
+| Get Template Version | A saved version with its bindings, example JSON, and missing or unused input paths |
+| Save Template Example | A new saved version with the example JSON and updated input review |
+
+For **Save Template Example**, set **Expected Version** to the latest saved version you
+reviewed. Bitavu rejects the save if that version is no longer current. Read the
+latest version and check its bindings before retrying a conflict or uncertain
+save. Saving an example leaves the current publication in place.
+
 ## Options and retries
 
 - **File Name:** defaults to `<templateId>.pdf`.
@@ -60,15 +101,15 @@ new IDs and can consume new credits. For retries across executions, retain a
 unique ID upstream and map it to **Options → Operation ID**. Reusing an ID with
 different data returns a conflict; the node does not hide it by changing the ID.
 
-There are no internal automatic retries. Configure retries in n8n and respect
-`Retry-After` for rate limits. After an uncertain network result, retry with the
-same ID and input. Request timeout: 120 seconds.
+Configure retries in n8n. For an uncertain render result, retry with the same
+operation ID and input. API errors show the request ID and retry delay when
+available. Request timeout is 120 seconds.
 
 ## Errors and privacy
 
-Errors explain invalid keys, missing permissions, template/version/data
-mismatches, operation conflicts and allowance limits. Use n8n error workflows
-or **On Error** settings to handle failures.
+Errors explain invalid keys, missing permissions, compatibility checks,
+revision conflicts, and allowance limits. Use n8n error workflows or
+**On Error** settings to handle failures.
 
 The node does not log keys, document data or PDFs, read files or access
 environment variables. It calls only `api.bitavu.com` and follows no redirects.
@@ -83,9 +124,9 @@ uses `n8n-workflow` 2.46.5, matching the tested n8n 2.46.7 instance.
 
 ```sh
 npm ci --ignore-scripts
-npm test
 npm run lint
 npm run typecheck
+npm test
 npm run vetting:check
 npm run dev
 ```
@@ -100,10 +141,10 @@ execution/node/run/item idempotency together. PDF binary output remains a
 regular workflow result, with AI tool generation disabled. Credentials use
 n8n's standard declarative credential test.
 
-Run the Publish workflow manually on the tag for the package version. Supply
-the SHA-256 of the reviewed tarball. The workflow builds and audits the package,
-then publishes with npm provenance if the tarball matches. Configure npm trusted
-publishing for `bitavu/n8n-nodes-bitavu`, workflow `publish.yml`, environment `npm`.
+The publish workflow builds, tests and publishes `v*.*.*` tags with npm
+provenance. Configure npm trusted publishing for repository
+`bitavu/n8n-nodes-bitavu`, workflow `publish.yml`, environment `npm`.
+The workflow audits the packed files and publishes that exact tarball.
 
 ## License
 

package/dist/credentials/BitavuApi.credentials.js

@@ -23,7 +23,7 @@ class BitavuApi {
                 typeOptions: { password: true },
                 required: true,
                 default: '',
-                description: 'A Bitavu key with Generate PDFs permission for your saved report. Paste only the key, without Bearer.',
+                description: 'A Bitavu key with permission for the selected operation and access to its templates. Paste only the key, without Bearer.',
             },
             {
                 displayName: 'Allowed HTTP Request Domains',

package/dist/nodes/Bitavu/Bitavu.node.js

@@ -1,65 +1,53 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Bitavu = void 0;
-const node_crypto_1 = require("node:crypto");
-const n8n_workflow_1 = require("n8n-workflow");
-const endpoint = 'https://api.bitavu.com/v1/render';
-const messages = {
-    INVALID_API_KEY: 'Your API key is invalid, expired or revoked. Check your Bitavu credential.',
-    KEY_REPORT: 'This key cannot access the report. Grant it access in Bitavu Integrations.',
-    KEY_SCOPE: 'Enable Generate PDFs permission for this key in Bitavu Integrations.',
-    IDEMPOTENCY_CONFLICT: 'This operation ID was already used with different data. Use a new ID for a new document.',
-    API_VERSION_LIMIT: 'This report reached its rolling saved-version limit. Use a previously tested version or wait for the limit to reset.',
-};
+const BitavuAction_1 = require("./BitavuAction");
 class Bitavu {
     constructor() {
         this.description = {
-            displayName: 'Bitavu',
+            ...BitavuAction_1.bitavuNodeDefaults,
+            displayName: 'Generate PDF',
             name: 'bitavu',
             icon: { light: 'file:bitavu.svg', dark: 'file:bitavu.svg' },
-            group: ['transform'],
-            version: 1,
             usableAsTool: undefined,
-            subtitle: '={{$parameter["operation"] === "generate" ? "Generate PDF" : ""}}',
-            description: 'Generate PDFs from visual templates and JSON data',
-            defaults: { name: 'Bitavu' },
-            inputs: [n8n_workflow_1.NodeConnectionTypes.Main],
-            outputs: [n8n_workflow_1.NodeConnectionTypes.Main],
-            credentials: [{ name: 'bitavuApi', required: true }],
+            subtitle: '',
+            description: 'Generate a PDF from a saved Bitavu template and workflow data',
+            defaults: { name: 'Generate PDF' },
             properties: [
-                { displayName: 'Resource', name: 'resource', type: 'hidden', default: 'document' },
+                BitavuAction_1.templatePicker,
                 {
-                    displayName: 'Operation',
-                    name: 'operation',
+                    displayName: 'Version Selection',
+                    name: 'versionSelection',
                     type: 'options',
-                    noDataExpression: true,
                     options: [
                         {
-                            name: 'Generate PDF',
-                            value: 'generate',
-                            description: 'Fill a saved visual template with JSON data',
-                            action: 'Generate a PDF',
+                            name: 'Pinned',
+                            value: 'pinned',
+                            description: 'Render a specific saved version',
+                        },
+                        {
+                            name: 'Latest Published',
+                            value: 'latest-published',
+                            description: 'Render the current publication if its JSON contract is compatible',
                         },
                     ],
-                    default: 'generate',
+                    default: 'pinned',
                 },
                 {
-                    displayName: 'Template ID',
-                    name: 'templateId',
-                    type: 'string',
-                    required: true,
-                    default: '',
-                    placeholder: 'invoice',
-                    description: 'Copy templateId from your saved report in Bitavu Integrations → Use in your app',
+                    displayName: 'Pinned Version',
+                    name: 'revision',
+                    ...BitavuAction_1.versionPicker,
+                    displayOptions: { show: { versionSelection: ['pinned'] } },
+                    description: 'The saved version to render. Defaults to version 1.',
                 },
                 {
-                    displayName: 'Saved Version',
+                    displayName: 'Base Version',
                     name: 'revision',
-                    type: 'number',
-                    required: true,
-                    default: 1,
-                    typeOptions: { minValue: 1, numberPrecision: 0 },
-                    description: 'The numeric revision of the saved report. Keep the tested version pinned so layout changes do not change your automation.',
+                    ...BitavuAction_1.versionPicker,
+                    displayOptions: {
+                        show: { versionSelection: ['latest-published'] },
+                    },
+                    description: 'Optional tested version for the compatibility check. Leave empty to use the first published version.',
                 },
                 {
                     displayName: 'Document Data',
@@ -67,7 +55,7 @@ class Bitavu {
                     type: 'json',
                     required: true,
                     default: '={{ $json.data }}',
-                    description: 'The JSON object expected by your template. Map incoming fields or use an expression such as the entire incoming item.',
+                    description: 'The JSON object expected by your template or saved mapping. Use an expression to pass data from a previous step.',
                 },
                 {
                     displayName: 'Options',
@@ -76,6 +64,12 @@ class Bitavu {
                     placeholder: 'Add Option',
                     default: {},
                     options: [
+                        {
+                            displayName: 'Base Version',
+                            name: 'baseRevision',
+                            type: 'hidden',
+                            default: null,
+                        },
                         {
                             displayName: 'File Name',
                             name: 'fileName',
@@ -84,6 +78,13 @@ class Bitavu {
                             placeholder: 'invoice.pdf',
                             description: 'Name for the generated PDF. Defaults to the template ID followed by .pdf.',
                         },
+                        {
+                            displayName: 'Mapping ID',
+                            name: 'mappingId',
+                            type: 'string',
+                            default: '',
+                            description: 'The ID of a saved Bitavu mapping for your incoming JSON fields',
+                        },
                         {
                             displayName: 'Operation ID',
                             name: 'operationId',
@@ -102,130 +103,10 @@ class Bitavu {
                 },
             ],
         };
+        this.methods = { listSearch: BitavuAction_1.bitavuListSearch };
     }
     async execute() {
-        var _a, _b;
-        const items = this.getInputData();
-        const output = [];
-        for (let itemIndex = 0; itemIndex < items.length; itemIndex++) {
-            try {
-                const templateId = this.getNodeParameter('templateId', itemIndex).trim();
-                const revision = this.getNodeParameter('revision', itemIndex);
-                const options = this.getNodeParameter('options', itemIndex, {});
-                const raw = this.getNodeParameter('data', itemIndex);
-                let data;
-                try {
-                    data = typeof raw === 'string' ? JSON.parse(raw) : raw;
-                }
-                catch {
-                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'Document Data must be valid JSON.', {
-                        itemIndex,
-                    });
-                }
-                const invalid = (message) => {
-                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), message, { itemIndex });
-                };
-                if (!/^[a-zA-Z0-9_-]{1,80}$/.test(templateId))
-                    invalid('Enter a valid Template ID from Bitavu Integrations.');
-                if (!Number.isSafeInteger(revision) || revision < 1)
-                    invalid('Saved Version must be a positive integer.');
-                if (!data || typeof data !== 'object' || Array.isArray(data))
-                    invalid('Document Data must be a JSON object, rather than an array or a primitive value.');
-                const outputField = String(options.outputField || 'pdf');
-                if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(outputField) ||
-                    ['__proto__', 'constructor', 'prototype'].includes(outputField))
-                    invalid('Output Binary Field must be a simple field name, such as pdf.');
-                const fileName = String(options.fileName || `${templateId}.pdf`).trim();
-                if (!fileName ||
-                    /[/\\]/.test(fileName) ||
-                    [...fileName].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127) ||
-                    !fileName.toLowerCase().endsWith('.pdf'))
-                    invalid('File Name must end in .pdf and contain no path separators or control characters.');
-                const operationId = String(options.operationId ||
-                    `bitavu-${(0, node_crypto_1.createHash)('sha256')
-                        .update(JSON.stringify([
-                        this.getExecutionId(),
-                        this.getNode().id,
-                        this.evaluateExpression('{{ $runIndex }}', itemIndex),
-                        itemIndex,
-                    ]))
-                        .digest('hex')}`);
-                if (!/^[a-zA-Z0-9_-]{16,128}$/.test(operationId))
-                    invalid('Operation ID must contain 16–128 letters, digits, underscores or hyphens.');
-                let response;
-                try {
-                    response = await this.helpers.httpRequestWithAuthentication.call(this, 'bitavuApi', {
-                        method: 'POST',
-                        url: endpoint,
-                        headers: {
-                            'Idempotency-Key': operationId,
-                            Accept: 'application/pdf',
-                            'Content-Type': 'application/json',
-                        },
-                        body: JSON.stringify({ templateId, revision, data }),
-                        encoding: 'arraybuffer',
-                        returnFullResponse: true,
-                        ignoreHttpStatusErrors: true,
-                        disableFollowRedirect: true,
-                        timeout: 120000,
-                    });
-                }
-                catch {
-                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), 'Could not reach Bitavu. Check your credential and network connection. Retry with the same operation ID if the result is uncertain.', { itemIndex });
-                }
-                const body = Buffer.isBuffer(response.body)
-                    ? response.body
-                    : Buffer.from((_a = response.body) !== null && _a !== void 0 ? _a : '');
-                if (response.statusCode !== 200) {
-                    let details = {};
-                    try {
-                        details = JSON.parse(body.toString('utf8'));
-                    }
-                    catch {
-                    }
-                    const code = typeof details.code === 'string' && /^[A-Z0-9_]+$/.test(details.code)
-                        ? details.code
-                        : '';
-                    const message = messages[code] ||
-                        (response.statusCode === 401
-                            ? messages.INVALID_API_KEY
-                            : response.statusCode === 429
-                                ? 'Bitavu is limiting requests or your render allowance is exhausted. Check your subscription and respect Retry-After before retrying.'
-                                : response.statusCode === 403
-                                    ? 'The key or workspace does not permit this render. Check report access and your subscription.'
-                                    : [400, 404, 422].includes(response.statusCode)
-                                        ? 'Check the Template ID, saved version and document fields against your tested Bitavu request.'
-                                        : 'Bitavu could not generate the PDF. Retry later with the same operation ID.');
-                    throw new n8n_workflow_1.NodeApiError(this.getNode(), { message, code, statusCode: response.statusCode }, { message, httpCode: String(response.statusCode), itemIndex });
-                }
-                if (!String(response.headers['content-type'] || '').includes('application/pdf') ||
-                    !body.subarray(0, 5).equals(Buffer.from('%PDF-')))
-                    invalid('Bitavu returned an unexpected response instead of a PDF. Contact support with the execution reference.');
-                const binary = await this.helpers.prepareBinaryData(body, fileName, 'application/pdf');
-                output.push({
-                    json: {
-                        ...items[itemIndex].json,
-                        bitavu: { templateId, revision, operationId, fileName, outputField },
-                    },
-                    binary: { ...items[itemIndex].binary, [outputField]: binary },
-                    pairedItem: { item: itemIndex },
-                });
-            }
-            catch (error) {
-                if (!this.continueOnFail()) {
-                    if (error instanceof n8n_workflow_1.NodeApiError)
-                        throw new n8n_workflow_1.NodeApiError(this.getNode(), { message: error.message }, { message: error.message, httpCode: (_b = error.httpCode) !== null && _b !== void 0 ? _b : undefined, itemIndex });
-                    throw new n8n_workflow_1.NodeOperationError(this.getNode(), error instanceof n8n_workflow_1.NodeOperationError
-                        ? error.message
-                        : 'Bitavu PDF generation failed. Check the node configuration.', { itemIndex });
-                }
-                output.push({
-                    json: { error: error instanceof Error ? error.message : 'Bitavu PDF generation failed.' },
-                    pairedItem: { item: itemIndex },
-                });
-            }
-        }
-        return [output];
+        return await BitavuAction_1.executeBitavu.call(this, 'generate');
     }
 }
 exports.Bitavu = Bitavu;

package/dist/nodes/Bitavu/Bitavu.node.json

@@ -2,9 +2,12 @@
     "node": "@bitavu/n8n-nodes-bitavu.bitavu",
     "nodeVersion": "1.0",
     "codexVersion": "1.0",
+    "alias": ["Bitavu"],
     "categories": [
         "Productivity",
-        "Data & Storage"
+        "Utility",
+        "Finance & Accounting",
+        "Marketing & Content"
     ],
     "resources": {
         "primaryDocumentation": [