@ironfang/n8n-nodes-ironfang 0.4.3 → 0.5.0

package/README.md

@@ -6,7 +6,13 @@ Use Ironfang Render, Finance, Audit and Rig, and Ironfang's public developer
 tools, in n8n. The Ironfang action node has **162 operations**, grouped by
 product. Ironfang Trigger receives signed Audit, Finance and Render events.
 
-**Release: 0.4.3.** Credits, cache status and webhook signatures are read from the `X-Ironfang-*` and `Ironfang-*` headers; update before the API stops sending the launch-era ones. 0.4.2 moved the API to `api.ironfang.com` (credentials saved with the old `api.ironfang.uk` address keep working unchanged), and 0.4.1 made the package installable on n8n releases
+**Release: 0.5.0.** Ironfang billing moved from credits to metered usage, and
+the node follows: a render reports the billing meter and quantity it counted
+instead of credits, Render Usage returns the month per meter, and a billing
+refusal keeps its code, product, meter and renewal date. Workflows that read
+`_ironfang.creditsCharged` need changing; see
+[Permissions and usage](#permissions-and-usage). 0.4.3 reads cache status and
+webhook signatures from the `X-Ironfang-*` and `Ironfang-*` headers. 0.4.2 moved the API to `api.ironfang.com` (credentials saved with the old `api.ironfang.uk` address keep working unchanged), and 0.4.1 made the package installable on n8n releases
 before 2.33 that use PostgreSQL; see [Installation](#installation-and-credentials).
 It includes 0.4.0, in which the products are named Ironfang Render, Finance and Audit
 (formerly Renderwolf, Financewolf and Auditwolf), and the node follows: requests
@@ -137,13 +143,17 @@ also applies to these outputs.
 Keys created with the earlier `renderwolf:*`, `financewolf:*` and `auditwolf:*`
 scopes keep working: the platform treats them as the scopes above.
 
-Render includes **250 free credits each month**, with no card required.
-A screenshot or template image costs 1 credit, a PDF 2, and QR codes 0. Clip
-costs depend on duration and output size. Cache hits consume no credits.
-Free renders can carry an Ironfang Render badge; QR codes never carry one. This
-allowance belongs to Render; other products have their own usage policies.
-
-Public tools use no account credits and share a 60/minute/address limit. The
+Usage is billed to your organisation's Ironfang billing account, which every
+Ironfang product shares. There are no plans or credits: each kind of work counts
+against a meter with a monthly free allowance, and usage beyond it is billed
+monthly once paid usage is switched on in Billing in the
+[Ironfang portal](https://portal.ironfang.com). A Render screenshot, PDF or
+template image counts 1 on its own meter, clips and site previews count output
+seconds, and QR codes are counted but never charged. Cache hits count nothing.
+Render Usage returns the month for each meter; limits, payment and statements
+are managed in the portal.
+
+Public tools are not billed to an account and share a 60/minute/address limit. The
 public screenshot service also has a 20/hour/address limit and a shared daily
 ceiling. Shared n8n egress addresses share these limits. Use authenticated
 Render rendering for account-based automation.
@@ -202,8 +212,10 @@ fields. Version 1.1 uses numeric `bytes` and structured errors; version 1.2 adds
 paging to the Audit lists named above and is otherwise identical. Version 2,
 which new nodes use, behaves as 1.2 does. All expose exact
 `byteLength`, item links and `_ironfang` response metadata when available:
-request ID, HTTP status, cache status and charged credits. Continued errors
-include available problem codes and retry information. New file operations use
+request ID, HTTP status, cache status, and the billing `meter` and `quantity`
+the request counted (0 for a cache hit). Continued errors include available
+problem codes and retry information; a billing refusal also carries `product`,
+`meter` and `resetAt` (when the free allowance renews) when the API states them. New file operations use
 numeric sizes; the output binary field defaults to `data`.
 
 Requests have explicit timeouts: 30 seconds for JSON (100 for a Rig wait) and

package/dist/lib/renderwolf.js

@@ -80,7 +80,7 @@ exports.renderwolf = {
                     {
                         name: 'Usage',
                         value: 'usage',
-                        description: 'Current period usage against your plan cap',
+                        description: "This month's usage of each Render meter, from your billing account",
                         action: 'Get usage',
                     }, {
                         name: 'Video Clip',
@@ -167,7 +167,7 @@ exports.renderwolf = {
                         name: 'no_cache',
                         type: 'boolean',
                         default: false,
-                        description: 'Whether to force a live capture instead of reusing an identical recent render. Use when the page must be captured exactly as it is right now, such as evidence or change detection. Counts against your quota.',
+                        description: 'Whether to force a live capture instead of reusing an identical recent render. Use when the page must be captured exactly as it is right now, such as evidence or change detection. A fresh render is always counted.',
                     },
                     {
                         displayName: 'Quality',
@@ -204,7 +204,7 @@ exports.renderwolf = {
                         name: 'no_cache',
                         type: 'boolean',
                         default: false,
-                        description: 'Whether to force a live capture instead of reusing an identical recent render. Use when the page must be captured exactly as it is right now, such as evidence or change detection. Counts against your quota.',
+                        description: 'Whether to force a live capture instead of reusing an identical recent render. Use when the page must be captured exactly as it is right now, such as evidence or change detection. A fresh render is always counted.',
                     },
                     {
                         displayName: 'Print Background',
@@ -330,7 +330,7 @@ exports.renderwolf = {
                 type: 'options',
                 default: 'vertical',
                 displayOptions: { show: { operation: ['video'] } },
-                description: 'Credits scale with pixels and seconds, so the smaller sizes cost less per second',
+                description: 'Counted in output seconds: vertical and landscape as 1080p, square and 720p as HD',
                 options: [
                     { name: '720p 1280x720', value: '720p' },
                     { name: 'Landscape 1920x1080', value: 'landscape' },

package/dist/nodes/Ironfang/catalog.js

@@ -1338,7 +1338,7 @@ exports.operations = [
         "product": "auditwolf",
         "id": "getUsage",
         "name": "Usage",
-        "description": "Credits, quota position, projection and hosted evidence",
+        "description": "This month's metered use, capacity and hosted evidence",
         "method": "GET",
         "path": "/v1/usage",
         "scope": "audit:read",
@@ -2011,27 +2011,18 @@ exports.operations = [
         "product": "financewolf",
         "id": "getEinvoiceUsage",
         "name": "Usage",
-        "description": "Reconcile Ironfang Finance document usage",
+        "description": "Read Ironfang Finance usage for a month",
         "method": "GET",
         "path": "/v1/einvoices/usage",
         "scope": "finance:billing:manage",
         "query": [
             {
-                "name": "start",
-                "label": "Start",
+                "name": "period",
+                "label": "Period",
                 "type": "string",
-                "required": true,
-                "default": "",
-                "description": "RFC3339 inclusive start / exclusive end; at most 366 days.",
-                "enum": []
-            },
-            {
-                "name": "end",
-                "label": "End",
-                "type": "string",
-                "required": true,
+                "required": false,
                 "default": "",
-                "description": "RFC3339 inclusive start / exclusive end; at most 366 days.",
+                "description": "A past or current UTC calendar month as YYYY-MM; the current month when omitted.",
                 "enum": []
             }
         ],
@@ -3327,7 +3318,7 @@ exports.operations = [
         "product": "rig",
         "id": "getUsage",
         "name": "Usage",
-        "description": "Runs and events in a window",
+        "description": "Runs, events and metered interactions",
         "method": "GET",
         "path": "/v1/usage",
         "scope": "rig:read",

package/dist/nodes/Ironfang/credentialTest.js

@@ -25,11 +25,15 @@ async function credentialTest(credential) {
             });
             lastStatus = response.statusCode;
             const body = response.body;
-            const valid = product === 'renderwolf' ? typeof body?.limit === 'number' || body?.unmetered === true : Array.isArray(body?.[checks[product][1]]);
+            // Render usage is a report per billing meter, or {"unmetered": true}.
+            const valid = product === 'renderwolf' ? Array.isArray(body?.meters) || body?.unmetered === true : Array.isArray(body?.[checks[product][1]]);
             if (response.statusCode === 200 && valid)
                 return { status: 'OK', message: `Connected to Ironfang ${name}. Each operation requires its own scope.` };
-            if (response.statusCode === 403 && (body?.error?.code ?? body?.code) === 'insufficient_scope')
+            const code = body?.error?.code ?? body?.code;
+            if (response.statusCode === 403 && code === 'insufficient_scope')
                 return { status: 'OK', message: `API key authenticated by Ironfang ${name}. The test read is outside its scopes; choose only the scopes your workflow needs.` };
+            if (response.statusCode === 403 && code === 'account_not_linked')
+                return { status: 'Error', message: 'API key authenticated, but its account belongs to no Ironfang organisation, so its usage cannot be billed. Contact support.' };
             if (response.statusCode !== 401 && response.statusCode !== 404)
                 break;
         }

package/dist/nodes/Ironfang/transport.js

@@ -32,15 +32,20 @@ function identifier(context, value, itemIndex) {
     }
     return encodeURIComponent(id);
 }
+// A billable response names the billing meter it counted against and the
+// quantity it counted there: 1 for most renders, output seconds for video,
+// 0 for a cache hit or an unmetered key.
 function responseMetadata(headers, statusCode) {
     const result = { statusCode };
     if (headers['x-ironfang-request-id'])
         result.requestId = headers['x-ironfang-request-id'];
     if (headers['x-ironfang-cache'])
         result.cacheStatus = headers['x-ironfang-cache'];
-    const credits = headers['x-ironfang-credits'];
-    if (credits !== undefined && credits !== '' && Number.isFinite(Number(credits)))
-        result.creditsCharged = Number(credits);
+    if (headers['x-ironfang-meter'])
+        result.meter = headers['x-ironfang-meter'];
+    const quantity = headers['x-ironfang-quantity'];
+    if (quantity !== undefined && /^\d+$/.test(quantity))
+        result.quantity = Number(quantity);
     return result;
 }
 async function request(options, authenticated = true) {
@@ -100,6 +105,16 @@ function errorDetails(error, itemIndex) {
     const retry = headers['retry-after'];
     if (typeof retry === 'string' && /^\d+$/.test(retry))
         details.retryAfterSeconds = Number(retry);
+    // A billing refusal names the product and meter it refused and, for an
+    // exhausted free allowance, when the allowance renews. Render and Audit put
+    // them in the error object; Finance problems carry them in `billing`.
+    const billing = Object.keys(object(problem.billing)).length ? object(problem.billing) : problem;
+    if (typeof billing.product === 'string' && /^[a-z]{1,32}$/.test(billing.product))
+        details.product = billing.product;
+    if (typeof billing.meter === 'string' && /^[a-z0-9_.]{1,64}$/.test(billing.meter))
+        details.meter = billing.meter;
+    if (typeof billing.reset_at === 'string' && !Number.isNaN(Date.parse(billing.reset_at)))
+        details.resetAt = billing.reset_at;
     return details;
 }
 function apiError(context, error, itemIndex) {

package/docs/operations.md

@@ -1,6 +1,6 @@
 # Operation reference
 
-Generated from Ironfang main `de1547b`. Runtime endpoint selection is fixed by this catalogue.
+Generated from Ironfang main `8ec778a0`. Runtime endpoint selection is fixed by this catalogue.
 Complex request bodies use JSON so all supported schema fields remain available. Replace placeholders with your own values.
 
 ## audit / Archive Monitor
@@ -608,7 +608,7 @@ Full request contract: https://api.ironfang.com/audit/openapi.yaml
 
 `GET /audit/v1/usage`. Scope: `audit:read`.
 
-Credits, quota position, projection and hosted evidence
+This month's metered use, capacity and hosted evidence
 
 Full request contract: https://api.ironfang.com/audit/openapi.yaml
 
@@ -941,11 +941,11 @@ Full request contract: https://api.ironfang.com/finance/openapi.yaml
 
 `GET /finance/v1/einvoices/usage`. Scope: `finance:billing:manage`.
 
-Reconcile Ironfang Finance document usage
+Read Ironfang Finance usage for a month
 
 Full request contract: https://api.ironfang.com/finance/openapi.yaml
 
-Query fields: `start` (required), `end` (required).
+Query fields: `period`.
 
 ## finance / Validate E-Invoice
 
@@ -1636,7 +1636,7 @@ Full request contract: https://api.ironfang.com/rig/openapi.yaml
 
 `GET /rig/v1/usage`. Scope: `rig:read`.
 
-Runs and events in a window
+Runs, events and metered interactions
 
 Full request contract: https://api.ironfang.com/rig/openapi.yaml
 

package/docs/validation.md

@@ -45,6 +45,15 @@ SQLite, which records nothing. `scripts/check-postgres-install.sh` now runs in
 CI before release. 224 tests and all three Docker checks passed locally on
 21 September.
 
+The 0.5.0 release follows Ironfang main `8ec778a0` (29 September 2026), where
+Render bills by meter rather than credits. `_ironfang` reports `meter` and
+`quantity` from the `X-Ironfang-Meter` and `X-Ironfang-Quantity` headers,
+billing refusals carry the product, meter and allowance renewal alongside the
+code, and the credential test accepts the per-meter usage report. These were
+checked against the API source and the unit tests, not against a live paid
+render. `npm run check` (229 tests), all three Docker checks and `npm audit`
+(zero reported vulnerabilities) passed locally on 29 September.
+
 ## Automated coverage
 
 - 0.4.0 adds cases for routing saved `/renderwolf` and origin bases to the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ironfang/n8n-nodes-ironfang",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "n8n nodes for Ironfang: Render, Finance, Audit, Rig, public tools and signed events",
   "keywords": [
     "n8n-community-node-package",