@frontera-sdk/blueprint 1.52.39 → 1.52.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/blueprint",
-  "version": "1.52.39",
+  "version": "1.52.40",
   "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.39"
+    "@frontera-sdk/core": "1.52.40"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.90.21",

package/src/action-client.ts

@@ -9,7 +9,9 @@ import type {
   ActionRequestListOptions,
   ActionRequestPage,
   SubmitActionInput,
+  UnavailableAction,
 } from './action-types'
+import { unavailableReasonOf } from './action-types'
 
 const BASE = '/v1/blueprint/governed-actions'
 
@@ -76,6 +78,26 @@ export class ActionClient {
     return this.client.request<ActionDescriptor[]>(`${BASE}/discovery`)
   }
 
+  /**
+   * Why discovery does not offer each Action it leaves out, or `null` when
+   * this caller may not be told: only someone who may read the organization's
+   * Actions (a member who builds, or the App's dev session on a local
+   * runtime) is. A person signed in to an externally hosted App is never
+   * asked for it; a 403 is the same `null`. Advisory: discovery and submit
+   * stay the decision.
+   */
+  async unavailable(): Promise<UnavailableAction[] | null> {
+    const credential = this.client.config.credential
+    if (credential.kind === 'token' && credential.token.startsWith(APP_USER_TOKEN_PREFIX)) return null
+    try {
+      const rows = await this.client.request<UnavailableAction[]>(`${BASE}/discovery/unavailable`)
+      return (Array.isArray(rows) ? rows : []).map((row) => ({ ...row, reason: unavailableReasonOf(row.reason) }))
+    } catch (err) {
+      if (err instanceof FronteraError && (err.status === 403 || err.status === 404)) return null
+      throw err
+    }
+  }
+
   /**
    * Submit one Action. Returns as soon as the Request is recorded — NOT when
    * the effect has landed.
@@ -246,6 +268,13 @@ function listQuery(options: ActionRequestListOptions): Record<string, string> {
 /**
  * The wire envelope, assembled from the flat input a caller actually has.
  *
+ * For an edit it carries the subject (`subjectRef`, `expectedSubjectVersion`)
+ * and, when the Action declares it, the numeric `expectedVersion` input. The
+ * Action's key input is not guessed here (the descriptor does not say which
+ * input it is): the platform fills it from `subjectRef.objectId` when `input`
+ * leaves it out, and refuses a key or version in `input` that disagrees with
+ * the subject.
+ *
  * Exported for the tests: this is the part with a trap in it, and the trap is
  * silent — a wrong shape comes back as "Action invocation is invalid" with no
  * field named.

package/src/action-hooks.ts

@@ -12,8 +12,12 @@ import {
 import type { ActionClient } from './action-client'
 import { blueprintKeys } from './hooks'
 import {
+  actionAvailabilityOf,
   actionEffectOf,
+  actionUnavailableText,
   isTerminalLifecycle,
+  type ActionUnavailableReason,
+  type UnavailableAction,
   type ActionDecisionResult,
   type ActionDescriptor,
   type ActionRequest,
@@ -39,6 +43,8 @@ export interface MyActionRequestsFilter extends ApprovalInboxFilter {
 export const actionKeys = {
   all: ['blueprint', 'actions'] as const,
   discovery: () => ['blueprint', 'actions', 'discovery'] as const,
+  /** Why discovery leaves Actions out, for a caller who may be told. */
+  unavailable: () => ['blueprint', 'actions', 'discovery', 'unavailable'] as const,
   requests: (lifecycle?: readonly ActionRequestLifecycle[]) =>
     ['blueprint', 'actions', 'requests', lifecycle?.join(',') ?? 'all'] as const,
   request: (requestId: string) => ['blueprint', 'actions', 'request', requestId] as const,
@@ -90,27 +96,84 @@ export function useActions(
   return useQuery({
     queryKey: actionKeys.discovery(),
     queryFn: () => client.discover(),
+    // Only what the caller can invoke: entries listed just to say why not are for `useAction`.
+    select: (entries) => entries.filter((entry) => actionAvailabilityOf(entry).available),
     ...options,
   })
 }
 
+/** What `useAction` answers: the Action when it can be invoked, else why not. */
+export interface UseActionResult {
+  /** The Action, or `null` when this caller cannot invoke it (or while discovery loads). */
+  action: ActionDescriptor | null
+  /** Whether it can be invoked. `false` while discovery loads too: check `isLoading`. */
+  available: boolean
+  /**
+   * Why not, once known: the platform's reason when this caller may be told,
+   * else `unknown`. `null` when available, or while discovery (or its
+   * explanation) loads.
+   */
+  reason: ActionUnavailableReason | null
+  /** A sentence for the person (a disabled control's tooltip or the line beside it): the platform's own when it sent one. `null` when available or still loading. */
+  reasonText: string | null
+  /** What would make it available, for the person building the App; only ever told to a caller who may read the organization's Actions. */
+  next: string | null
+  isLoading: boolean
+  error: Error | null
+}
+
 /**
- * One Action by name, or `null` when this user may not invoke it.
+ * One Action by name, or `null` when this user may not invoke it, with why.
  *
  * `null` rather than a thrown error, because "you may not do this" is an
  * ordinary state for a UI to be in — it renders nothing, or a disabled control
- * with an explanation — not an exception.
+ * with an explanation — not an exception. `reasonText` is that explanation: a
+ * control that stays visible says it (a tooltip, or a line beside it) rather
+ * than sitting disabled with no word of why.
+ *
+ * Only when discovery leaves the Action out does this ask the platform why
+ * (`discovery/unavailable`), and only a caller who may be told is answered: a
+ * person signed in to an externally hosted App gets the neutral `unknown`.
  */
 export function useAction(
   apiName: string,
   options: ReadOptions<ActionDescriptor[]> = {},
-): { action: ActionDescriptor | null; isLoading: boolean; error: Error | null } {
+): UseActionResult {
+  const client = useActionClient()
   const { data, isLoading, error } = useActions(options)
-  return {
-    action: data?.find((entry) => entry.apiName === apiName) ?? null,
-    isLoading,
-    error: error ?? null,
-  }
+  const missing = !!data && !data.some((entry) => entry.apiName === apiName)
+  const explained = useQuery({
+    queryKey: actionKeys.unavailable(),
+    queryFn: () => client.unavailable(),
+    enabled: missing,
+    // Advisory, and a refusal is an answer (null): never retried into a loop.
+    retry: false,
+    staleTime: 30_000,
+  })
+  const explanation = missing ? (explained.isPending ? undefined : (explained.data ?? null)) : null
+  return { ...actionLookup(data, apiName, explanation), isLoading, error: error ?? null }
+}
+
+/**
+ * One Action of a discovery answer, by name: it when it can be invoked, else
+ * why not. `explained` is the platform's explanation of what discovery left
+ * out: `undefined` while it loads, `null` when this caller may not be told.
+ */
+export function actionLookup(
+  entries: readonly ActionDescriptor[] | undefined,
+  apiName: string,
+  explained?: readonly UnavailableAction[] | null,
+): Pick<UseActionResult, 'action' | 'available' | 'reason' | 'reasonText' | 'next'> {
+  const none = { action: null, available: false, reason: null, reasonText: null, next: null }
+  if (!entries) return none
+  const entry = entries.find((candidate) => candidate.apiName === apiName)
+  const availability = actionAvailabilityOf(entry)
+  if (availability.available) return { action: entry!, available: true, reason: null, reasonText: null, next: null }
+  if (entry) return { action: null, available: false, reason: availability.reason, reasonText: actionUnavailableText(availability.reason), next: null }
+  if (explained === undefined) return none
+  const why = explained?.find((row) => row.apiName === apiName)
+  if (!why) return { action: null, available: false, reason: 'unknown', reasonText: actionUnavailableText('unknown'), next: null }
+  return { action: null, available: false, reason: why.reason, reasonText: why.message || actionUnavailableText(why.reason), next: why.next ?? null }
 }
 
 /**

package/src/action-types.ts

@@ -8,34 +8,76 @@
  * one fact a UI has to show: submitting is not the same as done.
  */
 
-/** Where a Request has got to. Only `succeeded` and the failures are terminal. */
-export type ActionRequestLifecycle =
-  | 'ready'
-  | 'awaiting_approval'
-  | 'dispatching'
-  | 'finalizing'
-  | 'succeeded'
-  | 'failed'
-  | 'cancelled'
-  | 'rejected'
-  | 'awaiting_resolution'
+/**
+ * Every state a Request can hold, in the platform's order.
+ *
+ * A copy of the platform's wire contract, not shared code: this package
+ * installs from public npm and cannot import the service. A test pins the two
+ * lists together, so a state added on one side fails the build on the other.
+ */
+export const ACTION_REQUEST_LIFECYCLES = [
+  'received',
+  'awaiting_approval',
+  'ready',
+  'executing',
+  'finalizing',
+  'succeeded',
+  'rejected',
+  'expired',
+  'cancelled',
+  'failed',
+  'outcome_unknown',
+  'awaiting_resolution',
+  'closed_unknown',
+] as const
+
+/**
+ * Where a Request has got to.
+ *
+ * - `received`: recorded, not yet checked against its approval policy.
+ * - `awaiting_approval`: waiting for someone to decide it.
+ * - `ready`: cleared to run; a worker picks it up.
+ * - `executing`: the write is being attempted now.
+ * - `finalizing`: the write committed; the platform is verifying it.
+ * - `succeeded`: applied and verified.
+ * - `rejected`, `expired`, `cancelled`: closed before anything was attempted.
+ * - `failed`: attempted, and the target refused it.
+ * - `outcome_unknown`: attempted, and whether it landed could not be
+ *   established yet; the platform reconciles it against the target.
+ * - `awaiting_resolution`: a person has to look at it, because verification or
+ *   reconciliation could not settle it.
+ * - `closed_unknown`: closed by a person without the outcome ever being
+ *   established. The write may have landed.
+ */
+export type ActionRequestLifecycle = typeof ACTION_REQUEST_LIFECYCLES[number]
+
+/** Every effect certainty a Request can carry, in the platform's order. Pinned to the platform's list by a test. */
+export const ACTION_EFFECT_CERTAINTIES = [
+  'not_attempted',
+  'in_flight',
+  'confirmed_not_applied',
+  'confirmed_applied',
+  'unknown',
+] as const
 
 /**
  * What is known about the effect on the target — NOT whether the request is
- * finished. `outcome_unknown` is the honest state after a dispatch whose
- * outcome could not be established, and a UI must not render it as failure:
- * the write may well have landed.
+ * finished. `in_flight` is a dispatch under way. `unknown` is the honest state
+ * after a dispatch whose outcome could not be established, and a UI must not
+ * render it as failure: the write may well have landed.
  */
-export type ActionEffectCertainty =
-  | 'not_attempted'
-  | 'confirmed_applied'
-  | 'confirmed_not_applied'
-  | 'outcome_unknown'
+export type ActionEffectCertainty = typeof ACTION_EFFECT_CERTAINTIES[number]
 
+/**
+ * The states a Request stops moving in by itself. `failed` and `closed_unknown`
+ * can still change if late evidence about the target arrives, but nothing is
+ * scheduled to move them, so polling stops there too.
+ */
 const TERMINAL: ReadonlySet<ActionRequestLifecycle> = new Set([
-  'succeeded', 'failed', 'cancelled', 'rejected',
+  'succeeded', 'rejected', 'expired', 'cancelled', 'failed', 'closed_unknown',
 ])
 
+/** Whether a Request has settled: nothing will move it on its own. */
 export function isTerminalLifecycle(lifecycle: ActionRequestLifecycle): boolean {
   return TERMINAL.has(lifecycle)
 }
@@ -71,27 +113,41 @@ export function actionEffectOf(
   if (!request) return 'pending'
   switch (request.effectCertainty) {
     case 'confirmed_applied': return 'applied'
-    case 'confirmed_not_applied': return 'refused'
-    case 'outcome_unknown': return 'uncertain'
+    case 'unknown': return 'uncertain'
+    // A refused attempt is final only once the Request has settled: `ready`
+    // with this certainty is a retry the platform has already queued.
+    case 'confirmed_not_applied':
+      if (!request.lifecycle || isTerminalLifecycle(request.lifecycle)) return 'refused'
+      return 'pending'
     default: break
   }
-  // No certainty reported. A terminal lifecycle still answers the question —
-  // a rejected or cancelled Request never reached the target at all — while
-  // anything else is genuinely still in flight.
-  return request.lifecycle && isTerminalLifecycle(request.lifecycle)
-    && request.lifecycle !== 'succeeded'
-    ? 'refused'
-    : 'pending'
+  // No certainty reported, or one that says nothing about the effect yet
+  // (`not_attempted`, `in_flight`). The lifecycle still answers when it has
+  // settled: a rejected, expired or cancelled Request never reached the
+  // target, and an unknown outcome stays unknown. Anything else is genuinely
+  // still in flight.
+  switch (request.lifecycle) {
+    case 'succeeded': return 'applied'
+    case 'outcome_unknown':
+    case 'closed_unknown': return 'uncertain'
+    case 'rejected':
+    case 'expired':
+    case 'cancelled':
+    case 'failed': return 'refused'
+    default: return 'pending'
+  }
 }
 
 /**
  * The record version to send with an edit, read off an object instance.
  *
- * The version arrives as `_meta.recordVersion`, and only from the INSTANCE
- * route — a list query's rows do not carry it, and only an editable type has
- * one at all. Reaching into `_meta` by hand is how a caller ends up sending
- * `undefined`, which does not fail: the compare-and-set is simply skipped, and
- * two people overwrite each other with no refusal and no evidence.
+ * The version arrives as `_meta.recordVersion`, and only an editable type has
+ * one at all. The instance route always sends it; a query's rows carry it only
+ * when the query asks (`recordVersions: true`, which Functions, workflows and
+ * the CLI ask for), and this SDK's queries do not ask. Reaching into `_meta`
+ * by hand is how a caller ends up sending `undefined`, and an edit of an
+ * existing record always compares versions: one sent without a version is
+ * refused, and nothing changes.
  *
  * So a control that edits a row from a table fetches the instance first:
  *
@@ -175,6 +231,99 @@ export interface ActionDescriptor {
   inputSchema: Record<string, unknown>
 }
 
+/**
+ * Why an Action is not offered to this caller, as the platform explains it
+ * (`discovery/unavailable`), in the order its gates refuse:
+ *
+ * - `not_deployed`: published, but no deployment runs it here (never
+ *   deployed, or switched off).
+ * - `no_workspace_grant`: this workspace holds no Blueprint grant on the
+ *   Action's object type.
+ * - `not_a_person`: the caller acts as a key, which belongs to no member.
+ * - `not_a_member`: the person is not a member of this workspace.
+ * - `business_user`: a Business user holds no governed authority here.
+ * - `role_cannot_submit`: the person's role may not submit Action requests.
+ * - `capability_not_granted`: the role does not hold the Action's invoke capability.
+ * - `agent_not_active`, `agent_no_grant`: for an Agent caller.
+ * - `agent_cannot_act`: the Agent may read the Action's object type, but its
+ *   grant there has no `act`, so it submits no Action on it.
+ * - `refused`: refused for a reason not listed.
+ * - `unknown`: the platform did not say (the caller may not ask, such as a
+ *   person signed in to an externally hosted App, or a platform that
+ *   predates the explanation).
+ */
+export type ActionUnavailableReason =
+  | 'not_deployed'
+  | 'no_workspace_grant'
+  | 'not_a_person'
+  | 'not_a_member'
+  | 'business_user'
+  | 'role_cannot_submit'
+  | 'capability_not_granted'
+  | 'agent_not_active'
+  | 'agent_no_grant'
+  | 'agent_cannot_act'
+  | 'refused'
+  | 'unknown'
+
+const REASONS: readonly ActionUnavailableReason[] = [
+  'not_deployed', 'no_workspace_grant', 'not_a_person', 'not_a_member', 'business_user',
+  'role_cannot_submit', 'capability_not_granted', 'agent_not_active', 'agent_no_grant', 'agent_cannot_act', 'refused', 'unknown',
+]
+
+/** A reason as the platform sent it: one of the known ones, else `unknown`. */
+export function unavailableReasonOf(value: unknown): ActionUnavailableReason {
+  return typeof value === 'string' && (REASONS as readonly string[]).includes(value) ? (value as ActionUnavailableReason) : 'unknown'
+}
+
+/**
+ * One Action discovery did not offer this caller, and why
+ * (`GET /v1/blueprint/governed-actions/discovery/unavailable`). Only a caller
+ * who may read the organization's Actions is told; the explanation is
+ * advisory, and discovery and submit stay the decision.
+ */
+export interface UnavailableAction {
+  apiName: string
+  displayName: string
+  reason: ActionUnavailableReason
+  /** One sentence for a person. */
+  message: string
+  /** What would make it available, when there is something to do. */
+  next: string | null
+  invokeCapability: string
+  /** The role the decision was made for, when the caller is a member. */
+  role?: string
+  /** For `not_deployed`: the deployment's state. */
+  deploymentStatus?: string
+  deploymentReason?: string
+}
+
+/** Whether a discovery entry can be invoked: discovery offers only what can, so anything but `available` (or no word) cannot. */
+export function actionAvailabilityOf(entry: Pick<ActionDescriptor, 'availability'> | null | undefined): { available: true; reason: null } | { available: false; reason: ActionUnavailableReason } {
+  if (!entry) return { available: false, reason: 'unknown' }
+  return entry.availability === undefined || entry.availability === 'available' ? { available: true, reason: null } : { available: false, reason: 'not_deployed' }
+}
+
+/**
+ * A sentence for a control that stays visible but cannot be used, when the
+ * platform sent none of its own: show it beside the disabled button, or as
+ * its tooltip. `unknown` stays neutral: it says nothing about why.
+ */
+export function actionUnavailableText(reason: ActionUnavailableReason): string {
+  switch (reason) {
+    case 'not_deployed':
+      return "This action isn't set up in this workspace yet."
+    case 'capability_not_granted':
+    case 'role_cannot_submit':
+    case 'business_user':
+      return "Your role can't do this. Ask your administrator for access."
+    case 'not_a_member':
+      return "You're not a member of this workspace."
+    default:
+      return "This action isn't available to you here."
+  }
+}
+
 /**
  * What raised a request, in the only terms a reader can act on.
  *
@@ -288,6 +437,31 @@ export interface ActionRequest {
    * other request, and absent from a platform that predates the field.
    */
   approval?: ActionRequestApproval | null
+  /**
+   * Every approval or rejection recorded on the request, oldest first. Empty
+   * when nobody has decided yet. Present on reads of a request (single and
+   * listed), whatever its approval mode; absent from a platform that predates
+   * the field.
+   */
+  approvalDecisions?: ActionRequestApprovalDecision[]
+}
+
+/**
+ * One decision recorded on a request: an approval or a rejection.
+ *
+ * `stage` is the approval-chain step it decided, or `null` when the Action
+ * approves in one step. `decidedBy.name` is `null` for someone no longer a
+ * member of the organization, and for a person whose App sign-in carried no
+ * name. `reason` is what the approver wrote; it is `null` when they wrote none
+ * or the stored reason could not be read.
+ */
+export interface ActionRequestApprovalDecision {
+  stage: string | null
+  decision: 'approve' | 'reject'
+  decidedBy: { name: string | null }
+  /** When the decision was recorded (ISO 8601). */
+  decidedAt: string
+  reason: string | null
 }
 
 /** One step of a request's approval chain. */
@@ -406,14 +580,31 @@ export interface ActionDecisionResult extends ActionRequest {
  * gets wrong once and then debugs for an hour. `submit` assembles it.
  */
 export interface SubmitActionInput {
-  /** Primary key of the object being changed. Omit only for `mode: 'create'`. */
+  /**
+   * Primary key of the object being changed, sent as the request's subject
+   * (`subjectRef.objectId`). Omit only for `mode: 'create'`.
+   *
+   * The platform fills the Action's input named like the object type's
+   * primary key (`id`, `ticketId`, …) from it when `input` leaves that out,
+   * so `input` need not repeat the key. If `input` does carry it, the two must
+   * be the same key: a request where they differ is refused, naming the input.
+   */
   objectId?: string
-  /** Parameter values, keyed by the Action's parameter API names. */
+  /**
+   * Parameter values, keyed by the Action's parameter API names. Leave out
+   * the key input and `expectedVersion`: they are filled from `objectId` and
+   * `expectedVersion` (see those).
+   */
   input: Record<string, unknown>
   /**
-   * The version the caller believes it read. Sent as the subject version AND,
-   * when the Action declares a compare-and-set parameter, as that parameter —
-   * so a stale write is refused rather than clobbering a concurrent one.
+   * The record version the change was decided on: `recordVersionOf` of the
+   * instance the person saw. Sent as the subject version
+   * (`expectedSubjectVersion`, as text) AND, when the Action declares an
+   * `expectedVersion` input, as that input (a number) — so a stale write is
+   * refused rather than clobbering a concurrent one. An edit sent without it
+   * is refused, never applied unchecked. When `input.expectedVersion` is given
+   * as well and differs, the platform refuses the request rather than
+   * picking one.
    */
   expectedVersion?: number | string
   /** Required when the Action declares `reason: 'required'`. */

package/src/types.ts

@@ -240,6 +240,11 @@ export interface QueryRequest {
  * this list matches `select`.
  */
 export interface QueryResponse<TRow = Record<string, unknown>> {
+  /**
+   * The records, as the platform sends them; the SDK changes no value. A
+   * timestamp property is ISO 8601 text in UTC (`'2026-10-17T09:17:00.000Z'`,
+   * which `new Date()` reads), a date property `'YYYY-MM-DD'`.
+   */
   rows: TRow[]
   properties: Array<{
     apiName: string