@frontera-sdk/blueprint 1.52.5 → 1.52.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/blueprint",
-  "version": "1.52.5",
+  "version": "1.52.7",
   "description": "React hooks for reading Blueprint data and invoking governed Actions from inside a Frontera app.",
   "keywords": [
     "frontera",
@@ -56,7 +56,7 @@
     "smoke": "bun run scripts/smoke.ts"
   },
   "dependencies": {
-    "@frontera-sdk/core": "1.52.5"
+    "@frontera-sdk/core": "1.52.7"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.90.21",

package/src/action-client.ts

@@ -1,9 +1,13 @@
 import type { FronteraClient } from '@frontera-sdk/core/client'
 import { FronteraError } from '@frontera-sdk/core/errors'
 import type {
+  ActionApprovalDecision,
+  ActionDecisionResult,
   ActionDescriptor,
   ActionRequest,
   ActionRequestLifecycle,
+  ActionRequestListOptions,
+  ActionRequestPage,
   SubmitActionInput,
 } from './action-types'
 
@@ -30,8 +34,14 @@ const APP_USER_TOKEN_PREFIX = 'sk-au-'
  * reads a request they raised. `submit` is accepted only for records that a
  * role listing that Action lets the person read. A role that only reads never
  * widens what they can change. A referenced record need only be readable.
- * `requests`, `decide` and `cancel` are for Frontera members and are refused
- * here for such a person, before anything is sent.
+ *
+ * Such a person also decides the approval steps their App role is given:
+ * `awaitingMe` lists the requests waiting on one, `decide` approves or
+ * rejects one, and `request` reads it. Any other request answers as not
+ * found, whether or not it exists. `mine` lists the requests they raised, and
+ * `cancel` withdraws one of those while it waits. `requests`, every request
+ * in the workspace, is for Frontera members and is refused here for such a
+ * person, before anything is sent.
  */
 export class ActionClient {
   constructor(private readonly client: FronteraClient) {}
@@ -98,8 +108,8 @@ export class ActionClient {
 
   requests(lifecycle?: readonly ActionRequestLifecycle[]): Promise<ActionRequest[]> {
     const refused = this.membersOnly(
-      'Listing Action requests',
-      'Keep the id `submit` returns and read that request with `request(id)` or `useActionRequest`.',
+      'Listing every Action request in the workspace',
+      'Read the requests waiting for their decision with `awaitingMe()` or `useApprovalInbox`, and the requests they raised with `mine()` or `useMyActionRequests`.',
     )
     if (refused) return Promise.reject(refused)
     return this.client.request<ActionRequest[]>(`${BASE}/requests`, {
@@ -107,6 +117,62 @@ export class ActionClient {
     })
   }
 
+  /**
+   * The waiting requests this person could decide right now, newest first.
+   *
+   * For a Frontera member: requests waiting on a step workspace members
+   * decide, in a workspace where they may approve. For a person signed in to
+   * an externally hosted App: requests waiting on a step that names an App
+   * role they hold, for a record that role's data scope covers.
+   *
+   * Never one they raised, one they already decided a step of, or one past
+   * its deadline. A request leaves the list as soon as any of that changes, so
+   * a list read a moment ago can hold a request that `decide` now refuses.
+   * Nothing here says how many other requests are waiting for other people.
+   *
+   * A page looks at a bounded number of the most recent waiting requests.
+   * When it stopped there, the page says `truncated: true`: more may wait
+   * behind them.
+   */
+  awaitingMe(options: ActionRequestListOptions = {}): Promise<ActionRequestPage> {
+    return this.page({ awaiting: 'me', ...listQuery(options) })
+  }
+
+  /**
+   * The requests this person raised, newest first, in every state unless
+   * `lifecycle` narrows it. Each carries its approval steps, who decided them
+   * by name and, for a rejected request, the reason.
+   *
+   * For a person signed in to an externally hosted App: the requests they
+   * raised through this App.
+   */
+  mine(
+    options: ActionRequestListOptions & { lifecycle?: readonly ActionRequestLifecycle[] } = {},
+  ): Promise<ActionRequestPage> {
+    return this.page({
+      mine: 'true',
+      ...(options.lifecycle?.length ? { lifecycle: options.lifecycle.join(',') } : {}),
+      ...listQuery(options),
+    })
+  }
+
+  /** One page of a named list: the requests, and where the next page starts. */
+  private async page(query: Record<string, string>): Promise<ActionRequestPage> {
+    const envelope = await this.client.requestEnvelope<{
+      data?: ActionRequest[]
+      nextCursor?: string | null
+      truncated?: boolean
+    } | null>(
+      `${BASE}/requests`,
+      { query },
+    )
+    return {
+      requests: envelope?.data ?? [],
+      nextCursor: envelope?.nextCursor ?? null,
+      truncated: envelope?.truncated === true,
+    }
+  }
+
   request(requestId: string): Promise<ActionRequest> {
     return this.client.request<ActionRequest>(`${BASE}/requests/${encodeURIComponent(requestId)}`)
   }
@@ -115,30 +181,52 @@ export class ActionClient {
    * Approve or reject. Separate from `submit` because it is a different act by
    * a different person — an Action with separation of duties refuses a decision
    * from whoever submitted it.
+   *
+   * `stage` names the approval-chain step being decided, as `approval.currentStage`
+   * showed it to the person. It is required for a request approved in steps
+   * (one whose `approval` is not `null`): without it the decision is refused as
+   * invalid, with reason `ACTION_APPROVAL_STEP_REQUIRED`. If another step is
+   * waiting by the time the decision arrives, it is refused with reason
+   * `ACTION_APPROVAL_STEP_CHANGED` rather than recorded on that step. Leave it
+   * out only for a request that has no approval steps, where naming one is
+   * refused.
+   *
+   * A Frontera member decides the requests and steps that name workspace
+   * members. A person signed in to an externally hosted App decides a step
+   * that names an App role they hold, for a record that role's data scope
+   * covers. To that person every other request answers `ACTION_NOT_FOUND`,
+   * the same as a request that does not exist: show "nothing to decide here",
+   * not an error about permissions.
+   *
+   * Resolves to the request as the decision left it, with `request` (the same
+   * request) and `approvalDecision` (the decision recorded) beside it: see
+   * `ActionDecisionResult`.
    */
-  decide(requestId: string, decision: 'approve' | 'reject', reason: string): Promise<ActionRequest> {
-    const refused = this.membersOnly(
-      'Approving or rejecting an Action request',
-      'A Frontera member with approval permission decides it in Frontera.',
-    )
-    if (refused) return Promise.reject(refused)
-    return this.client.request<ActionRequest>(
+  async decide(
+    requestId: string,
+    decision: 'approve' | 'reject',
+    reason: string,
+    stage?: string,
+  ): Promise<ActionDecisionResult> {
+    const answer = await this.client.request<{ approval: ActionApprovalDecision; request: ActionRequest }>(
       `${BASE}/requests/${encodeURIComponent(requestId)}/approvals`,
-      { method: 'POST', body: { decision, reason } },
+      { method: 'POST', body: { decision, reason, ...(stage ? { stage } : {}) } },
     )
+    return { ...answer.request, request: answer.request, approvalDecision: answer.approval }
   }
 
   /**
-   * Cancel takes NO body. It reads the request and the caller from the URL and
-   * the credential; a `reason` sent here is refused as an invalid command body
-   * rather than ignored, because the route accepts an exact key set.
+   * Cancel sends no body. The platform reads the request from the URL and the
+   * caller from the credential, and ignores anything sent as a body: a
+   * `reason` sent here would be dropped, not recorded, so none is taken.
+   *
+   * A Frontera member with permission to cancel requests cancels a request
+   * that waits for approval, or is approved and has not started to run. A person signed in to an externally hosted App withdraws
+   * only a request they raised, and only while it waits for approval: any
+   * other request answers as not found, and one already approved answers
+   * `CONFLICT`.
    */
   cancel(requestId: string): Promise<ActionRequest> {
-    const refused = this.membersOnly(
-      'Cancelling an Action request',
-      'A Frontera member with permission to cancel requests can cancel it in Frontera.',
-    )
-    if (refused) return Promise.reject(refused)
     return this.client.request<ActionRequest>(
       `${BASE}/requests/${encodeURIComponent(requestId)}/cancel`,
       { method: 'POST' },
@@ -146,6 +234,15 @@ export class ActionClient {
   }
 }
 
+/** The query a list sends for its filter and position: only what was given. */
+function listQuery(options: ActionRequestListOptions): Record<string, string> {
+  return {
+    ...(options.actionDefinitionId ? { actionDefinitionId: options.actionDefinitionId } : {}),
+    ...(options.limit !== undefined ? { limit: String(options.limit) } : {}),
+    ...(options.cursor ? { cursor: options.cursor } : {}),
+  }
+}
+
 /**
  * The wire envelope, assembled from the flat input a caller actually has.
  *

package/src/action-hooks.ts

@@ -1,5 +1,6 @@
 import { createContext, useContext, useEffect } from 'react'
 import {
+  useInfiniteQuery,
   useMutation,
   useQuery,
   useQueryClient,
@@ -13,18 +14,47 @@ import { blueprintKeys } from './hooks'
 import {
   actionEffectOf,
   isTerminalLifecycle,
+  type ActionDecisionResult,
   type ActionDescriptor,
   type ActionRequest,
   type ActionRequestLifecycle,
+  type ActionRequestPage,
   type SubmitActionInput,
 } from './action-types'
 
+/** Which requests `useApprovalInbox` reads. */
+export interface ApprovalInboxFilter {
+  /** Only requests of this Action. */
+  actionDefinitionId?: string
+  /** Requests read per page: 1 to 200. Left out, 50. */
+  pageSize?: number
+}
+
+/** Which requests `useMyActionRequests` reads. */
+export interface MyActionRequestsFilter extends ApprovalInboxFilter {
+  /** Only requests in these states. Left out, every state. */
+  lifecycle?: readonly ActionRequestLifecycle[]
+}
+
 export const actionKeys = {
   all: ['blueprint', 'actions'] as const,
   discovery: () => ['blueprint', 'actions', 'discovery'] as const,
   requests: (lifecycle?: readonly ActionRequestLifecycle[]) =>
     ['blueprint', 'actions', 'requests', lifecycle?.join(',') ?? 'all'] as const,
   request: (requestId: string) => ['blueprint', 'actions', 'request', requestId] as const,
+  /** With no filter: the prefix every approval inbox is cached under. */
+  awaitingMe: (filter?: ApprovalInboxFilter) => (filter
+    ? ['blueprint', 'actions', 'awaiting-me', filter.actionDefinitionId ?? 'all', filter.pageSize ?? 'default'] as const
+    : ['blueprint', 'actions', 'awaiting-me'] as const),
+  /** With no filter: the prefix every list of one's own requests is cached under. */
+  mine: (filter?: MyActionRequestsFilter) => (filter
+    ? [
+        'blueprint', 'actions', 'mine',
+        filter.lifecycle?.join(',') ?? 'all',
+        filter.actionDefinitionId ?? 'all',
+        filter.pageSize ?? 'default',
+      ] as const
+    : ['blueprint', 'actions', 'mine'] as const),
 }
 
 export const FronteraActionContext = createContext<ActionClient | null>(null)
@@ -114,6 +144,8 @@ export function useSubmitAction(
     onSuccess: (request) => {
       queryClient.setQueryData(actionKeys.request(request.id), request)
       void queryClient.invalidateQueries({ queryKey: actionKeys.requests() })
+      // A request they raised: their own list has one more.
+      void queryClient.invalidateQueries({ queryKey: actionKeys.mine() })
     },
   })
 }
@@ -184,6 +216,164 @@ export function useActionRequests(
   })
 }
 
+/** One named list of requests, read page by page. */
+export interface ActionRequestList {
+  /** Every request read so far, newest first. */
+  requests: ActionRequest[]
+  /** True until the first page has arrived. */
+  isLoading: boolean
+  /** True while any page is being read, the first or a later one. */
+  isFetching: boolean
+  error: Error | null
+  /** Whether the platform has at least one more request past what was read. */
+  hasMore: boolean
+  /**
+   * The approval inbox only: a page stopped at the platform's limit before it
+   * had looked at every waiting request, so the list may be incomplete even
+   * when `hasMore` is false. Always false for `useMyActionRequests`.
+   */
+  truncated: boolean
+  /** Read the next page. Does nothing when there is none, or one is on its way. */
+  loadMore(): Promise<void>
+  /** Read the list again from the top. */
+  refetch(): Promise<void>
+}
+
+type ListReadOptions = {
+  /** Set false to read nothing until it is true. */
+  enabled?: boolean
+  /** Read the list again this often, in milliseconds. Left out, only on `refetch` and after a decision. */
+  refetchInterval?: number | false
+}
+
+/** A named list as React Query reads it: one page per cursor. */
+export interface ActionRequestListQuery {
+  queryKey: readonly unknown[]
+  queryFn(context: { pageParam: string | null }): Promise<ActionRequestPage>
+  initialPageParam: string | null
+  getNextPageParam(last: ActionRequestPage): string | null
+}
+
+/**
+ * The query behind `useApprovalInbox`: its cache key and how it reads a page.
+ * Exported for an App that prefetches or drives the cache itself.
+ */
+export function approvalInboxQuery(client: ActionClient, filter: ApprovalInboxFilter = {}): ActionRequestListQuery {
+  return {
+    queryKey: actionKeys.awaitingMe(filter),
+    queryFn: ({ pageParam }) => client.awaitingMe({
+      ...(filter.actionDefinitionId ? { actionDefinitionId: filter.actionDefinitionId } : {}),
+      ...(filter.pageSize ? { limit: filter.pageSize } : {}),
+      ...(pageParam ? { cursor: pageParam } : {}),
+    }),
+    initialPageParam: null,
+    getNextPageParam: (last) => last.nextCursor,
+  }
+}
+
+/** The query behind `useMyActionRequests`. */
+export function myActionRequestsQuery(client: ActionClient, filter: MyActionRequestsFilter = {}): ActionRequestListQuery {
+  return {
+    queryKey: actionKeys.mine(filter),
+    queryFn: ({ pageParam }) => client.mine({
+      ...(filter.lifecycle?.length ? { lifecycle: filter.lifecycle } : {}),
+      ...(filter.actionDefinitionId ? { actionDefinitionId: filter.actionDefinitionId } : {}),
+      ...(filter.pageSize ? { limit: filter.pageSize } : {}),
+      ...(pageParam ? { cursor: pageParam } : {}),
+    }),
+    initialPageParam: null,
+    getNextPageParam: (last) => last.nextCursor,
+  }
+}
+
+/**
+ * The pages read so far as one list. A request that moved between two reads
+ * can be on two pages; it is listed once, where it first appears.
+ */
+export function requestsOfPages(pages: readonly ActionRequestPage[] | undefined): ActionRequest[] {
+  const seen = new Set<string>()
+  const requests: ActionRequest[] = []
+  for (const page of pages ?? []) {
+    for (const request of page.requests) {
+      if (seen.has(request.id)) continue
+      seen.add(request.id)
+      requests.push(request)
+    }
+  }
+  return requests
+}
+
+/**
+ * Whether any page read so far stopped at the platform's limit: the list may
+ * then be incomplete, whatever its last page says about a next one.
+ */
+export function pagesTruncated(pages: readonly ActionRequestPage[] | undefined): boolean {
+  return (pages ?? []).some((page) => page.truncated)
+}
+
+function useRequestList(query: ActionRequestListQuery, options: ListReadOptions): ActionRequestList {
+  const result = useInfiniteQuery({
+    ...query,
+    ...(options.enabled === undefined ? {} : { enabled: options.enabled }),
+    ...(options.refetchInterval === undefined ? {} : { refetchInterval: options.refetchInterval }),
+  })
+  return {
+    requests: requestsOfPages(result.data?.pages),
+    isLoading: result.isLoading,
+    isFetching: result.isFetching,
+    error: result.error ?? null,
+    hasMore: result.hasNextPage,
+    truncated: pagesTruncated(result.data?.pages),
+    loadMore: async () => {
+      if (result.hasNextPage && !result.isFetchingNextPage) await result.fetchNextPage()
+    },
+    refetch: async () => {
+      await result.refetch()
+    },
+  }
+}
+
+/**
+ * What awaits this person's approval: the waiting requests they could decide
+ * right now, newest first.
+ *
+ * Works for a Frontera member and for a person signed in to an externally
+ * hosted App, each under their own rules (`ActionClient.awaitingMe`). Render
+ * the review screen from `requests`: each carries `intent` (what is asked,
+ * and by whom) and `approval` (the steps, and the one waiting). Decide with
+ * `useDecideActionRequest`, passing `approval.currentStage` as `stage`; the
+ * list is read again after every decision made through that hook.
+ *
+ * `truncated` is true when a page stopped at the platform's limit of waiting
+ * requests looked at: say that the list may be incomplete, and narrow it with
+ * `actionDefinitionId`.
+ *
+ * The list is a moment's answer. Someone else may decide a request, or the
+ * record may leave the person's data, between the read and the decision; the
+ * decision then answers as it would for a request that is not there. Call
+ * `refetch`, or set `refetchInterval`, to keep a screen left open current.
+ */
+export function useApprovalInbox(options: ApprovalInboxFilter & ListReadOptions = {}): ActionRequestList {
+  const client = useActionClient()
+  const { enabled, refetchInterval, ...filter } = options
+  return useRequestList(approvalInboxQuery(client, filter), { enabled, refetchInterval })
+}
+
+/**
+ * The requests this person raised, newest first: what became of each, the
+ * approval steps it passed, who decided them by name and, for a rejected
+ * request, the reason given.
+ *
+ * For a person signed in to an externally hosted App: the requests they
+ * raised through this App. Read again after `useSubmitAction`,
+ * `useDecideActionRequest` and `useCancelActionRequest` succeed.
+ */
+export function useMyActionRequests(options: MyActionRequestsFilter & ListReadOptions = {}): ActionRequestList {
+  const client = useActionClient()
+  const { enabled, refetchInterval, ...filter } = options
+  return useRequestList(myActionRequestsQuery(client, filter), { enabled, refetchInterval })
+}
+
 /**
  * Approve or reject a Request awaiting a decision.
  *
@@ -191,20 +381,65 @@ export function useActionRequests(
  * submitted it, so this will fail for the requester — correctly. Surface that
  * refusal rather than hiding the control: "someone else must approve this" is
  * the information the user needs.
+ *
+ * Works with the session of a person signed in to an externally hosted App,
+ * for a step their App role decides.
+ *
+ * For a request approved in steps, `stage` is required: pass
+ * `request.approval.currentStage` from the request the person is looking at,
+ * so a decision is never recorded on a step they did not read. The hook does
+ * not fill it in from its cache: the cache may have been read again since the
+ * screen was drawn, and only your component knows which step it showed. A
+ * decision without it is refused (`ACTION_APPROVAL_STEP_REQUIRED`). Leave it
+ * out for a request whose `approval` is `null`.
+ *
+ * Resolves to the request as the decision left it (`ActionDecisionResult`).
+ * The request, the approval inbox and the lists of requests are read again.
  */
 export function useDecideActionRequest(): UseMutationResult<
-  ActionRequest,
+  ActionDecisionResult,
   Error,
-  { requestId: string; decision: 'approve' | 'reject'; reason: string }
+  { requestId: string; decision: 'approve' | 'reject'; reason: string; stage?: string }
 > {
   const client = useActionClient()
   const queryClient = useQueryClient()
 
   return useMutation({
-    mutationFn: ({ requestId, decision, reason }) => client.decide(requestId, decision, reason),
-    onSuccess: (request) => {
-      queryClient.setQueryData(actionKeys.request(request.id), request)
-      void queryClient.invalidateQueries({ queryKey: actionKeys.requests() })
-    },
+    mutationFn: ({ requestId, decision, reason, stage }) => client.decide(requestId, decision, reason, stage),
+    onSuccess: (decided) => refreshAfterWrite(queryClient, decided.id),
+  })
+}
+
+/**
+ * Withdraw a Request that is still waiting.
+ *
+ * A person signed in to an externally hosted App withdraws only a request
+ * they raised, while it waits for approval. A Frontera member needs the
+ * permission to cancel requests. The request and the lists are read again.
+ */
+export function useCancelActionRequest(): UseMutationResult<ActionRequest, Error, string> {
+  const client = useActionClient()
+  const queryClient = useQueryClient()
+
+  return useMutation({
+    mutationFn: (requestId) => client.cancel(requestId),
+    onSuccess: (cancelled) => refreshAfterWrite(queryClient, cancelled.id),
   })
 }
+
+/**
+ * After a decision or a cancellation: read the request again rather than
+ * cache the reply, which carries no `intent` and no approval steps, and read
+ * every list it may have left or changed in.
+ */
+export function refreshAfterWrite(
+  queryClient: { invalidateQueries(filters: { queryKey: readonly unknown[] }): Promise<void> },
+  requestId: string,
+): void {
+  for (const queryKey of [
+    actionKeys.request(requestId),
+    actionKeys.requests(),
+    actionKeys.awaitingMe(),
+    actionKeys.mine(),
+  ]) void queryClient.invalidateQueries({ queryKey })
+}

package/src/action-types.ts

@@ -111,12 +111,49 @@ export function recordVersionOf(instance: unknown): number | undefined {
   return typeof version === 'number' ? version : undefined
 }
 
+/**
+ * What a submission of this Action waits for.
+ *
+ * Any mode but `'none'` means the request may wait for approval. Test
+ * `mode !== 'none'`, not `mode === 'required'`: a mode you did not test for
+ * would otherwise read as "no approval". Under `'chain'` the request passes
+ * its steps one after another, and a step whose condition does not hold for
+ * it is skipped; read the request's `approval` to see where it stands.
+ */
 export interface ActionApprovalPolicy {
-  mode: 'none' | 'required'
+  mode: 'none' | 'required' | 'conditional' | 'chain'
   threshold?: number
-  separationOfDuties?: boolean
+  separationOfDuties?: boolean | 'strict'
+  /** Under `'chain'`: how long a request may wait for its steps, in hours or days, such as `24h` or `3d`. */
+  expiresAfter?: string
+  /** Under `'chain'`: the steps, in order. Absent for every other mode. */
+  stages?: ActionApprovalChainStep[]
+}
+
+/**
+ * One step of an Action's approval chain, as discovery describes it.
+ *
+ * `conditional` says whether the step applies only to some requests. The
+ * condition itself is not told: read a request's `approval` to see which
+ * steps applied to it.
+ *
+ * A step whose `approver` is an App role is decided for requests raised
+ * through an App that has that role. When such a step is not `conditional`,
+ * every request for the Action must be raised through such an App: one raised
+ * with no App is refused when it is submitted.
+ */
+export interface ActionApprovalChainStep {
+  key: string
+  /** Workspace members who may approve Action Requests, or the people who hold the named App role. */
+  approver: 'members' | { role: string }
+  /** How many approvals the step needs. */
+  quorum: number
+  conditional: boolean
 }
 
+/** Who decides a step of a request's approval chain: workspace members who may approve, or the people who hold an App role. */
+export type ActionApproverRule = { members: true } | { role: string; scope: 'subject' }
+
 /**
  * One Action this caller may invoke.
  *
@@ -161,6 +198,11 @@ export interface ActionDescriptor {
  * `appUserName` when it is present; it can be `null` when the person's identity
  * provider sent no name. Both are `null` for every other request, and absent
  * from a platform that predates the fields.
+ *
+ * A reader who is signed in to an externally hosted App is given names and no
+ * identifier of anyone else: on a request someone else raised, `userId`,
+ * `agentId`, `appUserId` and `applicationId` are all `null`. On a request they
+ * raised themselves, `appUserId` and `applicationId` are their own.
  */
 export interface ActionRequestRequester {
   kind: 'agent' | 'person' | 'automation'
@@ -240,6 +282,117 @@ export interface ActionRequest {
    * Never fall back to a guess.
    */
   intent?: ActionRequestIntent | null
+  /**
+   * Where the request stands in its Action's approval chain. Present on reads
+   * of a request whose Action uses approval mode `chain`; `null` for every
+   * other request, and absent from a platform that predates the field.
+   */
+  approval?: ActionRequestApproval | null
+}
+
+/** One step of a request's approval chain. */
+export interface ActionRequestApprovalStep {
+  /** The step's key, as the Action's approval chain names it. */
+  key: string
+  /**
+   * `open` is the step waiting for decisions now; `pending` waits for the
+   * steps before it. `skipped` never applied to this request: its condition
+   * did not hold.
+   */
+  status: 'pending' | 'open' | 'approved' | 'skipped' | 'rejected'
+  /**
+   * Who decides the step: workspace members who may approve Action Requests,
+   * or the people who hold the named role in the App the request was raised
+   * through.
+   */
+  approverRule: ActionApproverRule
+  /** How many approvals the step needs. */
+  quorum: number
+  /**
+   * Who decided this step, in the order they decided, by display name.
+   * `name` is `null` for someone no longer a member of the organization, and
+   * for a person whose App sign-in carried no name.
+   */
+  decidedBy: Array<{ name: string | null }>
+  /** When the step was approved or rejected; `null` while it is not settled. */
+  decidedAt: string | null
+}
+
+/**
+ * A request's approval chain: every step, the one waiting now, and the
+ * rejection that closed the request, if one did.
+ */
+export interface ActionRequestApproval {
+  stages: ActionRequestApprovalStep[]
+  /** The key of the step waiting for decisions; `null` when none is. */
+  currentStage: string | null
+  /**
+   * The rejection that closed the request. `reason` is what the approver
+   * wrote; it is `null` when the stored reason could not be read.
+   */
+  rejection: { stage: string; reason: string | null; decidedBy: { name: string | null } } | null
+}
+
+/**
+ * One page of a request list. `nextCursor` is `null` on the last page;
+ * otherwise pass it back as `cursor` to read the next one.
+ *
+ * `truncated` is only ever true for `awaitingMe()`: the platform looks at a
+ * bounded number of the most recent waiting requests for one page, and it
+ * stopped there. Requests the person could decide may wait behind them, so a
+ * short or empty page with no `nextCursor` is not proof that nothing else
+ * waits. Tell the person the list may be incomplete, and narrow it with
+ * `actionDefinitionId`.
+ */
+export interface ActionRequestPage {
+  requests: ActionRequest[]
+  nextCursor: string | null
+  truncated: boolean
+}
+
+/** Which requests a list reads, and where in it. */
+export interface ActionRequestListOptions {
+  /** Only requests of this Action. */
+  actionDefinitionId?: string
+  /** Requests per page: 1 to 200. Left out, 50. */
+  limit?: number
+  /** `nextCursor` of the page before. */
+  cursor?: string
+}
+
+/** A decision as the platform recorded it. */
+export interface ActionApprovalDecision {
+  id: string
+  requestId: string
+  decision: 'approve' | 'reject'
+  /** The approval-chain step decided; `null` for an Action that does not use a chain. */
+  stage: string | null
+  decidedAt: string
+  expiresAt?: string
+  policyThreshold?: number
+  separationOfDuties?: boolean
+  humanApproverId?: string
+  humanApproverRole?: string
+}
+
+/**
+ * What `decide` resolves to: the request as the decision left it, with the
+ * two parts the platform answers a decision with.
+ *
+ * It IS the request (`id`, `lifecycle` and the rest read as they do on any
+ * `ActionRequest`), so code written against the earlier `ActionRequest`
+ * return type keeps compiling and now reads real values. `request` is that
+ * same request under the name the platform gives it, and `approvalDecision`
+ * is the decision just recorded. The platform calls that part `approval`; it
+ * has another name here because `approval` on a request already means where
+ * the request stands in its approval chain.
+ *
+ * Like every reply to a write, it carries no `intent` and no chain progress:
+ * read the request again for those.
+ */
+export interface ActionDecisionResult extends ActionRequest {
+  request: ActionRequest
+  approvalDecision: ActionApprovalDecision
 }
 
 /**