n8n-nodes-lenz 0.6.0 → 0.8.0

package/README.md

@@ -36,8 +36,8 @@ Operations are grouped under a **Resource** picker. (Nodes added before v0.1.10
 
 | Operation | What it does |
 |---|---|
-| **Verify (Deep)** *(default)* | Full multi-model pipeline (research → debate → adjudication), ~90 seconds. Returns a verdict, confidence, `lenz_score` (1-10), `key_finding`, sourced citations, and an executive summary. Reserve for high-stakes claims that need a thorough, cited answer. **Depth** trades work for price: *Low* searches fewer sources, skips the recovery fetch tiers and stops the debate after the opening arguments, for **5 credits instead of 10**. |
-| **Assess (Fast)** | A quick 3-model panel verdict, ~10 seconds, one entry per claim identified in the input text. Good default for lower-stakes checks. Each entry carries a `verification_url`, **which is usually empty, and that is expected**: it is set only when the claim was already deep-checked with **Verify (Deep)** and that result is one you can read. A fresh panel verdict creates no stored verification, so there is no page to link to. If you need a link and sources for a claim, run Verify (Deep) on it. |
+| **Verify (Deep)** *(default)* | Full multi-model pipeline (research → debate → adjudication), ~90 seconds. Returns a verdict, confidence, `lenz_score` (1-10), `key_finding`, sourced citations, an executive summary, and a `suggested_rewrite` when the claim needs correcting. Reserve for high-stakes claims that need a thorough, cited answer. **Depth** trades work for price: *Low* searches fewer sources, skips the recovery fetch tiers and stops the debate after the opening arguments, for **5 credits instead of 10**. |
+| **Assess (Fast)** | A quick 3-model panel verdict, ~15 seconds, one entry per claim identified in the input text. Good default for lower-stakes checks. Each entry carries a `verification_url`, **which is usually empty, and that is expected**: it is set only when the claim was already deep-checked with **Verify (Deep)** and that result is one you can read. A fresh panel verdict creates no stored verification, so there is no page to link to. If you need a link and sources for a claim, run Verify (Deep) on it. |
 | **Extract Claims** | Free — pulls the verifiable factual claims out of a block of text without checking them. Useful as a first step before running Assess or Verify on each claim individually. **Focus** narrows the result to the claims you describe (300 characters, no extra cost); when none of them match, `status` comes back as `no_match` with an empty list rather than the unfocused claims. **Text** can also be a single public web page URL: Lenz reads the page, or a YouTube video's transcript, and extracts the claims from its first 50,000 characters. Pages behind a login (Facebook, Instagram, Threads, LinkedIn) can't be read, and a URL call typically takes 5-40 seconds. |
 
 ### Verification — manage submitted and stored work
@@ -48,10 +48,25 @@ Operations are grouped under a **Resource** picker. (Nodes added before v0.1.10
 | **Select Claims** | Resolves a paused verification (see [Multi-claim input](#multi-claim-input)). |
 | **Submit Batch** | Submits up to 20 claims at once without waiting. Returns one item per spawned task. Each claim can override the batch **Depth**, so one batch can mix 5- and 10-credit checks. |
 | **Get** | Retrieves a stored verification report by `verification_id`. |
-| **Get Many** | Lists the verifications stored against this API key, with **Return All** / **Limit**. |
+| **Get Many** | Lists the verifications stored in your Lenz account, with **Return All** / **Limit**. |
 | **List Related** | Public verifications semantically related to a given one — useful for "see also" surfaces. |
 | **Delete** | Permanently deletes one of your stored verifications. |
 
+### Review — check a whole draft, or its citations
+
+| Operation | What it does |
+|---|---|
+| **Review Draft** | Checks a whole draft (up to 50,000 characters, or one public web page by URL) in one call: finds its claims, quick-checks them (1 credit each, up to **Max Quick Checks**, default 20), deep-checks the doubtful ones (10 credits each, 5 at Low **Depth**, up to **Max Deep Checks**, default 5) and, with **Max Citations** above 0, checks whether each cited source says what the draft attributes to it (1 credit per citation). **Suggest Edits** adds the smallest edits that make the draft say what each correction says, at no extra cost. A review usually takes two to four minutes. |
+| **Get Review** | Fetches a review by `review_id`, for one that outlasted the wait. **Issues Only** leaves out the full claim and citation lists. |
+| **Check Citations** | Checks only the citations: either a **Text** with its links, DOIs or `[n]` markers and a reference list (**Max Citations**, default 20), or up to 20 **Statement-Source Pairs** you list, each with a URL or a DOI. 1 credit per citation checked; a source that could not be read is refunded. |
+| **Get Citation Check** | Fetches a citation check by `citecheck_id`. |
+
+Both hand on Lenz's result as it comes, plus `passed`: `true` only when `outcome` is `clean`, `false` for `issues_found`, `incomplete` or `unchecked`, and `null` until there is an outcome. **Branch on `outcome`** for anything finer: `issues[]` (claims Lenz found wrong, each with `verdict`, `key_finding` and `suggested_rewrite`) and `citation_issues[]` (citations whose source does not say what the text says, worst first) are the arrays to loop over, and `credits.charged` is what it cost.
+
+**Waiting.** With **Wait for Completion** on, the node polls until the job finishes, for up to **Options → Max Wait (Seconds)**, default **600**. If that runs out you get `status: "timeout"` with the `review_id` or `citecheck_id`; nothing is cancelled or lost, so fetch it later with **Get Review** / **Get Citation Check**. For long drafts, turn Wait for Completion off and use a **Webhook URL** (also under Options) or fetch it later.
+
+**Three at a time.** Lenz runs at most **3 reviews, and separately 3 citation checks, at once per account**. A fourth waits: the node holds it for up to five minutes until a slot opens, then submits it. Nothing is charged for the wait. If one item in a run fails for good, the error names the jobs earlier items already started, so a paid review is never lost with the run.
+
 ### Ask — follow-up questions
 
 | Operation | What it does |
@@ -65,6 +80,7 @@ Operations are grouped under a **Resource** picker. (Nodes added before v0.1.10
 | Operation | What it does |
 |---|---|
 | **Get Usage** | Returns your credit balance and the per-endpoint price list (`costs`), plus the same balance projected into each capability (`assess` / `verify` / `ask`), the `extract` daily cap, your current plan, and when credits reset. Prices that depend on a request parameter are under `cost_options` instead, nested capability → parameter → value — today `cost_options.verify.depth.low` is 5 against a default of 10. That is the only place it appears: it is a price rather than a capability, so it has no balance block of its own, and `costs` carries just the four capability keys (`verify`, `assess`, `ask`, `extract`). To size how many low-depth checks you can afford, divide `credits.remaining` by `cost_options.verify.depth.low`. If that block is missing, `costs.verify` is a safe fallback but it is the *standard* price, so it understates the answer by half. |
+| **Get Webhook Secret** | OAuth connections only. Returns `webhook_secret`, the secret Lenz signs this connection's webhook deliveries with — verify each delivery's signature with it. Lenz creates it on this first call and refuses a **Webhook URL** until it exists; a reconnected connection starts with no secret until you run this again. An API key's secret is set and shown on [lenz.io/api-credentials](https://lenz.io/api-credentials) instead. |
 
 The per-capability blocks (`verify` / `ask` / `assess`) and each block's `credits` alias are **deprecated, and the API removes them on 2026-11-29**. They are projections of the one balance, not separate allowances, so derive them instead and branch on the balance itself: `Math.floor(credits.remaining / costs[capability])`. Note the single slash — in an n8n expression `//` starts a comment, so the older form silently returned the raw balance. Only divide for a capability that costs credits: `costs.extract` is `0`. An **IF** node reading `{{ $json.verify.remaining }}` today will stop resolving on that date.
 
@@ -72,6 +88,8 @@ Every claim-checking operation returns a branch-ready `passed` boolean (derived
 
 Verify and Get also expose an **Include Audit Trail** toggle, which adds the adjudication reasoning, debate transcript, per-panelist assessments, and panel agreement under `audit`. It's off by default because it's a lot of data per item. At Low depth the debate transcript carries no rebuttals, because that round does not run.
 
+A completed verification — from **Verify (Deep)**, **Get Verify Status** or **Get** — also carries `suggested_rewrite`: a rewrite of the claim that the verification's findings support, for a person to review before using it. **It has not been verified itself**, so do not paste it over the original sentence without reading it. It is an empty string for a true claim, when no correction is established, and on verifications made before the field existed, so an **IF** node checking `{{ $json.suggested_rewrite }}` **is not empty** finds the claims that have one.
+
 ### Retry safety
 
 Billable calls (Verify, Assess, Extract, Submit Batch, Select Claims, Ask Follow-Up) send an `Idempotency-Key` derived from the execution ID, a hash of the node's identity, the item index, and a fingerprint of the request — its path as well as its body. If n8n retries the node — via **Retry On Fail**, or after a dropped response — the input is identical, so Lenz replays the original response instead of charging you a second time. A fresh run of the workflow is a new execution, so it bills normally.
@@ -84,14 +102,25 @@ Note that **Assess bills per claim found in the text**, not per request: a parag
 
 ## Credentials
 
-You'll need a free Lenz API key:
+Connect with your Lenz account (**OAuth**, the default on a new node) or with an API key. When you create a credential from a Lenz node, the credential window lets you pick either one.
+
+**OAuth (Lenz OAuth2 API)** — nothing to copy or paste:
 
-1. Sign up at [lenz.io/api-credentials](https://lenz.io/api-credentials) to get a key (starts with `lenz_`).
-2. In n8n, add new credentials of type **Lenz API**, paste the key, and click **Test** to confirm it's valid.
+1. On a Lenz node, open **Credential to connect with → Create new credential** and keep **OAuth** selected.
+2. Click **Connect my account**, sign in to Lenz and click **Allow**.
+
+n8n registers itself with Lenz the first time you connect, so there is no client ID, secret or redirect URL to set up, and any number of n8n instances and credentials can connect to the same Lenz account. It needs n8n 2.12.0 or later (see [Compatibility](#compatibility)). The OAuth Redirect URL n8n shows must be a public `https://` address, or `http://localhost` for an n8n on your own computer; if it shows an internal address, set `WEBHOOK_URL` to your instance's real address and restart n8n. Disconnect it any time under **Connected apps** in your Lenz account. To use a **Webhook URL** over OAuth, run **Account → Get Webhook Secret** once first: Lenz signs that connection's deliveries with it, and refuses a webhook URL until it has been fetched. A reconnected connection starts with no secret, so run **Get Webhook Secret** again before using a Webhook URL.
+
+**API key (Lenz API):**
+
+1. Get a free key at [lenz.io/api-credentials](https://lenz.io/api-credentials) (it starts with `lenz_`).
+2. Create a credential, pick **API Key**, paste the key and click **Save**; n8n tests it straight away.
+
+Nodes you added before OAuth existed keep using their API key: nothing changes for them unless you switch.
 
 ## Compatibility
 
-Built against `n8n-workflow` (n8n API version 1) and tested against n8n v2.30.4. No known version incompatibilities.
+Built against `n8n-workflow` (n8n API version 1) and tested against n8n v2.30.4; the OAuth credential against v2.41.6. **OAuth needs n8n 2.12.0 or later**, the first release that finds Lenz's OAuth metadata. On an older n8n, use an API key: a new Lenz node starts on OAuth, so pick **API Key** in the credential window.
 
 ## Usage
 
@@ -124,7 +153,7 @@ A simple "fact-check gate" pattern — verify an LLM's output before acting on i
 
 > **Check `status` before `passed`.** `passed` only means something once a verdict exists. A timeout, a `failed` pipeline or a `needs_input` interrupt has no verdict, and `passed` is `null` or absent — which an IF reads as false. Branching straight on `passed` therefore reports "this claim did not pass" for a claim nobody ever checked, and a provider outage becomes a debunking.
 
-For a lighter check on lower-stakes content, swap the Lenz operation to **Assess (Fast)** instead — same wiring, ~10s instead of ~90s.
+For a lighter check on lower-stakes content, swap the Lenz operation to **Assess (Fast)** instead — same wiring, ~15s instead of ~90s.
 
 ### Follow-up questions on a completed verification
 
@@ -189,7 +218,7 @@ So the Wait node has a number to read, the error output carries the refusal as f
 | `status_code` | The HTTP status, e.g. `429`, `503` |
 | `cost` | Credits the refused call needed, present only on an out-of-credits refusal |
 | `credits_remaining` | Credits the account holds — `0` is a real value and is reported, not dropped |
-| `error_message` / `error_description` | The same wording the node would have thrown, present only for a recognised billing, capacity or rate-limit refusal |
+| `error_message` / `error_description` | The same wording the node would have thrown, present only for a recognised billing, capacity, rate-limit or idempotency-conflict refusal (`code: "idempotency_conflict"`: an earlier attempt of the same request is still holding it, for up to 15 minutes, and nothing new was charged; Review Draft and Check Citations retry it for ~30 seconds first) |
 | `resets_in_seconds` | Seconds until a rate limit clears, when that is too long to sit in a Wait node — see [Rate limits](#rate-limits-http-429) |
 | `limit` | The limit the API stated, on a Lenz rate-limit refusal |
 | `upgrade_url` | Where that limit or plan is raised — on a Lenz rate-limit refusal, and on an out-of-credits refusal |
@@ -257,6 +286,17 @@ Note that the wait is read from the response body, not from the `Retry-After` he
 
 * **0.6.0** — **Three changes reach a workflow you already have, as soon as you update.** First, **Max Wait (Seconds) defaults to 300, up from 120.** A real verification finished in Lenz with a verdict and the credits were taken while the node had already given up at 120 seconds and returned `timeout`; Lenz measures a standard-depth run at about 90 seconds median with the tail past 120, so this was not rare. Because n8n does not save a parameter left at its default, every Verify node that never set Max Wait picks up the new value. It is a ceiling, not a delay — a fast verification returns exactly as before — but it is per item, so a ten-item run can now block for up to fifty minutes instead of twenty; set Max Wait explicitly if a workflow runs under a short execution timeout. Second, `progress` loses `content` and `step_stats` (below). Third, the `clarification_required` and `duplicate_found` pauses are gone, since the API no longer returns them: `multi_claim` is the one `needs_input` reason left, `candidates` and `similar_claims` stay on the output but are always empty until their removal on 2026-11-29, and Assess reports an empty result as `no_claim` rather than `ambiguous`. No parameter was renamed or removed. **Rate limits (HTTP 429) now have proper handling.** They arrived as n8n's stock "Request failed with status code 429"; the message now names the limit, when it clears and that nothing was charged. The documented Wait-node recovery was being fed `undefined`, because the error output read a key a 429 does not carry — a short reset now arrives as `retry_after`, and one too long to sit in a workflow, like the `/extract` daily cap that clears at midnight UTC, arrives as `resets_in_seconds` so that a workflow already wired to the Wait loop fails fast instead of parking for most of a day. The advice also names the Wait unit, because n8n's Wait node defaults to Hours and a bare `{{ $json.retry_after }}` turned a 45-second limit into a 45-hour wait. A 429 from a proxy or CDN in front of Lenz is no longer reported as your plan being too small. And a rate-limited status poll no longer abandons a verification you have paid for: a daily-cap 429 on the first poll used to sleep the whole of Max Wait in one go and then report `timeout` for a verification that had finished minutes in. The README gains an **Updating** section and explains why `verification_url` on Assess is usually empty. The rest of this entry covers the `progress` change and the other poll-loop fixes. **What a mid-run poll hands your workflow is now a fixed list.** While a Verify (Deep) runs, **Get Verify Status** returns a `progress` object, and the node used to pass whatever the API put in it straight onto the item. That endpoint was inherited from the consumer progress page and nothing shaped it, so what came through included `content` — the accumulated evidence pool, with full untruncated source quotes and every panelist's reasoning — and `step_stats`, Lenz's own per-step cost in EUR. Neither was ever part of the contract. `progress` now carries `step`, `index`, `total`, `elapsed_seconds` and `poll_after_seconds`, and nothing else; anything the API adds in future stays out until it is added deliberately. **If you mapped `progress.content` or `progress.step_stats`, those fields are gone** — that is the change, not a side effect of it. A `processing` response that states `poll_after_seconds` is now honoured instead of the node's own 2/4/8s cadence, since the server knows which stage it is in and how long that stage runs; a value outside the sane range is ignored rather than clamped. Reviewing that change turned up a fault in the poll loop that predated it: the deadline was enforced by the loop condition, so a wait clamped to the deadline was followed by the loop ending rather than by one more read — a verification that finished during that last wait was reported as a timeout, sending you to fetch a verdict that had already arrived. The loop now always ends on a read. Separately, a correction that was costing money: a paused task stays open for **24 hours from submission**, not the 10 minutes the Selected Claims field and this README both claimed. Anyone who believed that resubmitted, and paid a second time, for a **Select Claims** that would still have worked.
 
+* **0.7.0** — **Connect with your Lenz account instead of an API key.** A new **Lenz OAuth2 API** credential signs in with Lenz: **Connect my account**, sign in, **Allow**, and nothing to copy or paste. n8n registers itself with Lenz on that first connection, so there is no client ID, secret or redirect URL to set up, and any number of n8n instances and credentials can connect to the same Lenz account side by side — each its own connection, disconnected separately under **Connected apps**. It needs **n8n 2.12.0 or later**, and n8n's OAuth Redirect URL must be a public `https://` address or `http://localhost` — a self-hosted n8n behind an internal address sets `WEBHOOK_URL` to its real address first (see [Credentials](#credentials)); on an older n8n, use an API key. **Nothing changes for a workflow you already have.** The node gains version 1.2, and only a Lenz node added from now on starts on OAuth; a node already in a workflow keeps its API key, because n8n does not save a parameter left at its default and changing the default in place would have switched every existing node off its key. The choice between OAuth and API Key is in the credential window when you create a credential from a Lenz node; that is also how an existing node moves to OAuth. **Account → Get Webhook Secret** is new and is for OAuth connections: Lenz signs that connection's webhook deliveries with the secret it returns, creates it on that first call, and refuses a **Webhook URL** on an OAuth connection until then; a reconnected connection starts with no secret, so run **Get Webhook Secret** again before using a Webhook URL and check signatures with the secret it returns. Completed verifications now carry **`suggested_rewrite`**, a rewrite of the claim that the verification's findings support — not verified itself, so read it before using it — and an empty string when there is none. No parameter or output field was renamed or removed.
+
+* **0.8.0** — **Review a whole draft, or just its citations.** A new **Review** resource:
+  * **Review Draft** finds a draft's claims, quick-checks them, deep-checks the doubtful ones, optionally checks its citations (in a pasted text; a draft given as a URL checks none) and suggests edits. That is one call instead of an Extract → Assess → Verify chain.
+  * **Check Citations** checks whether each cited source says what the text says it does, from a text with its links, DOIs or `[n]` markers, or from statement-source pairs.
+  * **Get Review** and **Get Citation Check** fetch either by ID.
+
+  A review takes two to four minutes, so **Max Wait** for both sits under **Options** and defaults to **600 seconds**. When it runs out the node returns the ID, and nothing is cancelled. Lenz runs at most three reviews, and three citation checks, at once per account. A fourth waits up to five minutes for a slot instead of failing at once; if none opens, that item fails with a message saying so, and nothing is charged for the wait. If an item fails for good, the error lists the jobs that earlier Verify (Deep), Review Draft and Check Citations items already started, so their IDs are not lost with the run.
+
+  **A workflow you already have keeps working.** No parameter or output field was renamed or removed. Verify behaves exactly as before, now polling through the same loop as the new operations. A version 1.1 or 1.2 node simply gains the Review resource. An OAuth2 credential that was never connected now says to click **Connect my account** instead of showing n8n's signing error; with Continue On Fail, its error output carries `code: "oauth_not_connected"` and the new text.
+
 ## Maintainer
 
 [@David19782](https://github.com/David19782)

package/dist/credentials/LenzOAuth2Api.credentials.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LenzOAuth2Api = void 0;
+class LenzOAuth2Api {
+    constructor() {
+        this.name = 'lenzOAuth2Api';
+        this.extends = ['oAuth2Api'];
+        this.displayName = 'Lenz OAuth2 API';
+        this.icon = { light: 'file:../nodes/Lenz/lenz.svg', dark: 'file:../nodes/Lenz/lenz.dark.svg' };
+        this.documentationUrl = 'https://lenz.io/api-credentials';
+        this.properties = [
+            {
+                displayName: 'Click <b>Connect my account</b> and sign in to Lenz — nothing to fill in. Lenz needs the redirect URL above to be a public <code>https://</code> address or <code>http://localhost</code>; it needs n8n 2.12 or later; otherwise use an API key.',
+                name: 'connectNotice',
+                type: 'notice',
+                default: '',
+            },
+            {
+                displayName: 'Server URL',
+                name: 'serverUrl',
+                type: 'hidden',
+                default: 'https://lenz.io/api/v1',
+            },
+            {
+                displayName: 'Use Dynamic Client Registration',
+                name: 'useDynamicClientRegistration',
+                type: 'hidden',
+                default: true,
+            },
+        ];
+    }
+}
+exports.LenzOAuth2Api = LenzOAuth2Api;
+//# sourceMappingURL=LenzOAuth2Api.credentials.js.map

package/dist/credentials/LenzOAuth2Api.credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LenzOAuth2Api.credentials.js","sourceRoot":"","sources":["../../credentials/LenzOAuth2Api.credentials.ts"],"names":[],"mappings":";;;AAYA,MAAa,aAAa;IAA1B;QACC,SAAI,GAAG,eAAe,CAAC;QACvB,YAAO,GAAG,CAAC,WAAW,CAAC,CAAC;QACxB,gBAAW,GAAG,iBAAiB,CAAC;QAChC,SAAI,GAAG,EAAE,KAAK,EAAE,6BAA6B,EAAE,IAAI,EAAE,kCAAkC,EAAW,CAAC;QACnG,qBAAgB,GAAG,iCAAiC,CAAC;QAErD,eAAU,GAAsB;YAC/B;gBACC,WAAW,EACV,kPAAkP;gBACnP,IAAI,EAAE,eAAe;gBACrB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,EAAE;aACX;YACD;gBACC,WAAW,EAAE,YAAY;gBACzB,IAAI,EAAE,WAAW;gBACjB,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,wBAAwB;aACjC;YACD;gBACC,WAAW,EAAE,iCAAiC;gBAC9C,IAAI,EAAE,8BAA8B;gBACpC,IAAI,EAAE,QAAQ;gBACd,OAAO,EAAE,IAAI;aACb;SACD,CAAC;IACH,CAAC;CAAA;AA5BD,sCA4BC"}