From 35d0ff2ee908f7a59df88608a11c2e21e6d031b4 Mon Sep 17 00:00:00 2001 From: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com> Date: Fri, 17 Jul 2026 20:01:33 +0800 Subject: [PATCH] docs(approvals): drop duplicated role warning, generalize approver literal (#3113 lint fix) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `lint.yml` has been red on main since #3113: the reserved-word ratchet (ADR-0090 D3) caught content/docs/automation/approvals.mdx growing 5 → 9 occurrences of "role". Every open PR inherits the failure. The four new occurrences are NOT a fifth legitimate boundary needing a baseline bump — three of them are a near-verbatim duplicate of the callout 80 lines earlier, and the fourth is an over-narrow API description: - The lifecycle Steps repeated the "type: 'role' is not a position" warning that "3. The approval node" already carries (and carries better — it names the `approval-role-not-membership-tier` lint rule). Kept the fact the lifecycle section actually needs (an unresolved approver list parks the run forever) and cross-referenced the authoritative warning instead. - `approverId` was documented as accepting `role:`. The runtime falls back to a generic `` `${a.type}:${a.value}` `` literal for EVERY approver type (approval-service.ts expandApprovers), and the REST layer only splits on commas — it never validates the prefix. `:` is the accurate contract; `role:` described one arbitrary instance of it. Net: same information, one authoritative home, no accuracy lost, and the baseline stays at 5 rather than freezing 4 avoidable occurrences. Deliberately NOT rewording the surviving 5: `role` there is the better-auth org-membership tier (`sys_member.role`), which is D3's single documented exception. It is live, not deprecated — spec `ApproverType` still enumerates 'role' alongside 'position' (approval.zod.ts, asserted in approval.test.ts) and `expandRoleUsers` resolves it against `sys_member.role`. Renaming a third-party identifier we do not own would make the docs wrong. Co-Authored-By: Claude Opus 4.8 --- content/docs/automation/approvals.mdx | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/content/docs/automation/approvals.mdx b/content/docs/automation/approvals.mdx index 592e26199c..8f6ec549e5 100644 --- a/content/docs/automation/approvals.mdx +++ b/content/docs/automation/approvals.mdx @@ -130,14 +130,11 @@ record is **locked** against edits while pending (`lockRecord`, default `true`), and the flow run parks until a decision arrives. Only `approvers` is required on the node; everything else has a default -(`behavior: 'first_response'`, `lockRecord: true`, `maxRevisions: 3`). - - -**`type: 'role'` is not a position.** In an approver entry, `role` means the -better-auth membership tier (`owner` / `admin` / `member`). Naming a business -role like `sales_manager` there matches nobody and the request silently has no -approvers — use `{ type: 'position', value: 'sales_manager' }`. - +(`behavior: 'first_response'`, `lockRecord: true`, `maxRevisions: 3`). An +approver entry that resolves to nobody is not an error: the request opens with +an empty `pending_approvers` and nothing can move it, so the run parks forever. +The approver-type trap that causes this is covered under +**3. The approval node** above. ### The approver finds it in their queue @@ -150,8 +147,10 @@ curl -b cookies.txt \ "https://your-app.example.com/api/v1/approvals/requests?status=pending&approverId=usr_123" ``` -`approverId` accepts a user id, an email, or `role:` — and takes several -values (comma-separated or repeated) to cover a person's identities in one call. +`approverId` accepts a user id, an email, or a `:` approver literal +(`position:finance_manager` — the form an entry falls back to when it resolves +to no users) — and takes several values (comma-separated or repeated) to cover +a person's identities in one call. Other filters: `status`, `object`, `recordId`, `submitterId`, `q`, `limit`, `offset`.