@frontera-sdk/blueprint 1.43.10 → 1.44.0

package/README.md

@@ -23,6 +23,32 @@ function App() {
 }
 ```
 
+## Generate workspace types
+
+Inside a Frontera App, run:
+
+```bash
+frontera blueprint generate-types
+```
+
+This writes `src/generated/frontera-blueprint.ts`, which augments the SDK from
+the active Blueprint slice granted to the authenticated workspace. When that
+file is part of the TypeScript project, object names and returned rows are
+inferred automatically; filter, projection, and ordering property names are
+checked as well.
+
+```tsx
+const shipments = useObjects('Shipment', {
+  where: { property: 'status', op: 'eq', value: 'delayed' },
+  select: ['shipmentId', 'status'],
+})
+```
+
+Commit the generated file. Run `frontera blueprint generate-types --check` in
+an authenticated CI freshness gate; do not generate during install or build.
+Apps without a generated registry retain the existing string-keyed behavior,
+and explicit calls such as `useObjects<MyRow>('Shipment')` remain supported.
+
 ## Filter on the server
 
 `where` compiles into the object set, so the server filters and pages.
@@ -31,6 +57,22 @@ total — a filter matching 8,961 records renders 5 of them under "Page 1 of 1".
 For the same reason a total is its own query (`useAggregate` with a count over
 the same object set), never `rows.length`.
 
+## Page with cursors
+
+The query API uses stable cursor pagination, not page numbers. Omit
+`pageToken` for the first request, then pass the response's `nextPageToken` to
+the next request:
+
+```tsx
+const rows = useObjects('Shipment', { pageSize: 25, pageToken })
+const next = rows.data?.nextPageToken
+```
+
+`nextPageToken` is present exactly when `hasMore`. Keep previously received
+tokens in UI state if the experience needs a Previous button. Changing a
+filter, projection, or ordering invalidates that history and must return to the
+first page.
+
 ## Entry points
 
 | Import | What it is |

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@frontera-sdk/blueprint",
-  "version": "1.43.10",
-  "description": "React hooks for reading Blueprint data from inside a Frontera app.",
+  "version": "1.44.0",
+  "description": "React hooks for reading Blueprint data and invoking governed Actions from inside a Frontera app.",
   "keywords": [
     "frontera",
     "blueprint",
@@ -33,6 +33,18 @@
       "types": "./src/hooks.ts",
       "import": "./src/hooks.ts"
     },
+    "./action-types": {
+      "types": "./src/action-types.ts",
+      "import": "./src/action-types.ts"
+    },
+    "./action-client": {
+      "types": "./src/action-client.ts",
+      "import": "./src/action-client.ts"
+    },
+    "./action-hooks": {
+      "types": "./src/action-hooks.ts",
+      "import": "./src/action-hooks.ts"
+    },
     "./provider": {
       "types": "./src/provider.tsx",
       "import": "./src/provider.tsx"
@@ -40,11 +52,11 @@
   },
   "scripts": {
     "test": "bun test",
-    "typecheck": "bunx tsc --noEmit",
+    "typecheck": "bunx tsc --noEmit && bunx tsc --noEmit -p type-tests/tsconfig.json && bunx tsc --noEmit -p type-tests/tsconfig.loose.json",
     "smoke": "bun run scripts/smoke.ts"
   },
   "dependencies": {
-    "@frontera-sdk/core": "1.43.6"
+    "@frontera-sdk/core": "1.43.10"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.90.21",

package/src/action-client.ts

@@ -0,0 +1,175 @@
+import type { FronteraClient } from '@frontera-sdk/core/client'
+import type {
+  ActionDescriptor,
+  ActionRequest,
+  ActionRequestLifecycle,
+  SubmitActionInput,
+} from './action-types'
+
+const BASE = '/v1/blueprint/governed-actions'
+
+/**
+ * The governed write plane.
+ *
+ * Authorized against the PERSON, never the app. A hosted app is handed a token
+ * carrying the signed-in user's id, and every call is checked against that
+ * user's organization role, their workspace membership, and the workspace's
+ * grant on the object type. So the same page can offer a button to one
+ * colleague and not another, and neither the app nor its author decides which.
+ *
+ * A workspace key cannot invoke at all — its principal belongs to no
+ * organization member — which is why a scaffolded dev host, holding one, will
+ * read fine and refuse every write. See `README` on `frontera app init`.
+ */
+export class ActionClient {
+  constructor(private readonly client: FronteraClient) {}
+
+  /**
+   * Actions this user may invoke, here, now.
+   *
+   * An empty list is ambiguous ON PURPOSE — unpublished, undeployed and
+   * unpermitted are indistinguishable to a caller, so a probe cannot map what
+   * exists. That is right for security and hostile to debugging, so treat an
+   * unexpected empty list as a question about the CALLER's permissions first.
+   */
+  discover(): Promise<ActionDescriptor[]> {
+    return this.client.request<ActionDescriptor[]>(`${BASE}/discovery`)
+  }
+
+  /**
+   * Submit one Action. Returns as soon as the Request is recorded — NOT when
+   * the effect has landed.
+   *
+   * The write is durable from this point: it survives a closed tab, a restarted
+   * server, and a worker that is not running yet. What it does not do is finish
+   * synchronously, so a UI that renders success here is lying. Poll the Request
+   * (`useActionRequest`) and show the lifecycle.
+   */
+  async submit(
+    action: ActionDescriptor,
+    input: SubmitActionInput,
+  ): Promise<ActionRequest> {
+    const idempotencyKey = input.idempotencyKey ?? mintIdempotencyKey()
+    return this.client.request<ActionRequest>(
+      `${BASE}/actions/${encodeURIComponent(action.apiName)}/requests`,
+      {
+        method: 'POST',
+        headers: { 'idempotency-key': idempotencyKey },
+        // Wrapped, and the wrapper is EXACT: the route accepts a body whose
+        // keys are precisely `['invocation']` and refuses anything else with
+        // "Governed Action HTTP command body is invalid." — a message that
+        // names the body rather than the field, so sending the envelope at the
+        // top level reads like a malformed invocation instead of a missing
+        // wrapper.
+        body: { invocation: buildInvocation(action, input) },
+      },
+    )
+  }
+
+  requests(lifecycle?: readonly ActionRequestLifecycle[]): Promise<ActionRequest[]> {
+    return this.client.request<ActionRequest[]>(`${BASE}/requests`, {
+      query: lifecycle?.length ? { lifecycle: lifecycle.join(',') } : undefined,
+    })
+  }
+
+  request(requestId: string): Promise<ActionRequest> {
+    return this.client.request<ActionRequest>(`${BASE}/requests/${encodeURIComponent(requestId)}`)
+  }
+
+  /**
+   * 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.
+   */
+  decide(requestId: string, decision: 'approve' | 'reject', reason: string): Promise<ActionRequest> {
+    return this.client.request<ActionRequest>(
+      `${BASE}/requests/${encodeURIComponent(requestId)}/approvals`,
+      { method: 'POST', body: { decision, reason } },
+    )
+  }
+
+  /**
+   * 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(requestId: string): Promise<ActionRequest> {
+    return this.client.request<ActionRequest>(
+      `${BASE}/requests/${encodeURIComponent(requestId)}/cancel`,
+      { method: 'POST' },
+    )
+  }
+}
+
+/**
+ * The wire envelope, assembled from the flat input a caller actually has.
+ *
+ * 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.
+ */
+export function buildInvocation(
+  action: ActionDescriptor,
+  input: SubmitActionInput,
+): Record<string, unknown> {
+  const invocation: Record<string, unknown> = { input: { ...input.input } }
+
+  if (action.subject.mode === 'existing') {
+    if (!input.objectId) {
+      throw new Error(
+        `"${action.apiName}" changes an existing ${action.subject.objectTypeId}, so it needs an objectId.`,
+      )
+    }
+    invocation.subjectRef = {
+      objectTypeId: action.subject.objectTypeId,
+      objectId: input.objectId,
+    }
+    if (input.expectedVersion !== undefined) {
+      // A STRING here, deliberately: the subject version is an opaque token,
+      // while the compare-and-set parameter below is the numeric record
+      // version. Same number, two types, two meanings.
+      invocation.expectedSubjectVersion = String(input.expectedVersion)
+    }
+  } else if (input.objectId) {
+    throw new Error(`"${action.apiName}" creates an object, so it takes no objectId.`)
+  }
+
+  // Fed to the Action's own compare-and-set parameter when it declares one,
+  // and only then — an Action without it would refuse the unknown key.
+  const casParameter = compareAndSetParameter(action)
+  if (casParameter && input.expectedVersion !== undefined) {
+    const parameters = invocation.input as Record<string, unknown>
+    if (!(casParameter in parameters)) parameters[casParameter] = Number(input.expectedVersion)
+  }
+
+  if (input.reason !== undefined) invocation.reason = input.reason
+  if (input.correlationId !== undefined) invocation.correlationId = input.correlationId
+  return invocation
+}
+
+/**
+ * The parameter carrying the record version, read off the published schema
+ * rather than assumed by name.
+ */
+function compareAndSetParameter(action: ActionDescriptor): string | null {
+  const input = (action.inputSchema as { properties?: Record<string, unknown> } | undefined)
+    ?.properties?.input as { properties?: Record<string, unknown> } | undefined
+  const properties = input?.properties
+  if (!properties) return null
+  return 'expectedVersion' in properties ? 'expectedVersion' : null
+}
+
+/**
+ * One key per user intent.
+ *
+ * The service dedupes by this: the same key with a different invocation is
+ * REFUSED, and the same key with the same invocation returns the original
+ * Request rather than acting twice. So it must be stable across retries of one
+ * intent and different between two intents — which is exactly the lifetime of
+ * a single `submit` call, not of a component or a session.
+ */
+function mintIdempotencyKey(): string {
+  const random = globalThis.crypto?.randomUUID?.()
+    ?? Math.random().toString(36).slice(2).padEnd(22, '0')
+  return `frontera-app-${random}`
+}

package/src/action-hooks.ts

@@ -0,0 +1,210 @@
+import { createContext, useContext, useEffect } from 'react'
+import {
+  useMutation,
+  useQuery,
+  useQueryClient,
+  type UseMutationResult,
+  type UseQueryOptions,
+  type UseQueryResult,
+} from '@tanstack/react-query'
+
+import type { ActionClient } from './action-client'
+import { blueprintKeys } from './hooks'
+import {
+  actionEffectOf,
+  isTerminalLifecycle,
+  type ActionDescriptor,
+  type ActionRequest,
+  type ActionRequestLifecycle,
+  type SubmitActionInput,
+} from './action-types'
+
+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,
+}
+
+export const FronteraActionContext = createContext<ActionClient | null>(null)
+
+export function useActionClient(): ActionClient {
+  const client = useContext(FronteraActionContext)
+  if (!client) {
+    throw new Error(
+      'No ActionClient in context. Wrap the tree in FronteraActionContext.Provider — createFronteraApp does this for you in a Frontera app.',
+    )
+  }
+  return client
+}
+
+type ReadOptions<TData> = Omit<UseQueryOptions<TData, Error>, 'queryKey' | 'queryFn'>
+
+/**
+ * Actions the signed-in user may invoke.
+ *
+ * Render buttons from THIS, never from a hard-coded list: the same page must
+ * offer different actions to different colleagues, and only the server knows
+ * which. A hard-coded button that 403s on click is a worse experience than one
+ * that was never drawn.
+ *
+ * An empty list during development is much more likely to be permissions than
+ * a bug in this hook — an Action is hidden unless it is published, deployed,
+ * AND its invoke capability is held by the caller's role.
+ */
+export function useActions(
+  options: ReadOptions<ActionDescriptor[]> = {},
+): UseQueryResult<ActionDescriptor[], Error> {
+  const client = useActionClient()
+  return useQuery({
+    queryKey: actionKeys.discovery(),
+    queryFn: () => client.discover(),
+    ...options,
+  })
+}
+
+/**
+ * One Action by name, or `null` when this user may not invoke it.
+ *
+ * `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.
+ */
+export function useAction(
+  apiName: string,
+  options: ReadOptions<ActionDescriptor[]> = {},
+): { action: ActionDescriptor | null; isLoading: boolean; error: Error | null } {
+  const { data, isLoading, error } = useActions(options)
+  return {
+    action: data?.find((entry) => entry.apiName === apiName) ?? null,
+    isLoading,
+    error: error ?? null,
+  }
+}
+
+/**
+ * Submit an Action.
+ *
+ * Resolves when the Request is RECORDED, not when the effect has landed —
+ * dispatch runs on a background worker. A button whose success toast fires here
+ * is claiming something it does not know, so pass the returned request id to
+ * `useActionRequest` and let the lifecycle drive what the user sees.
+ *
+ * The idempotency key is minted per `mutate` call, which is the correct
+ * lifetime: React Query retrying a failed network call reuses the same key and
+ * cannot double-apply, while a second click is a second intent and gets its
+ * own.
+ */
+export function useSubmitAction(
+  action: ActionDescriptor | null,
+): UseMutationResult<ActionRequest, Error, SubmitActionInput> {
+  const client = useActionClient()
+  const queryClient = useQueryClient()
+
+  return useMutation<ActionRequest, Error, SubmitActionInput>({
+    mutationFn: (input) => {
+      if (!action) {
+        return Promise.reject(new Error(
+          'This Action is not available to you. Render the control only when `useAction` returns one.',
+        ))
+      }
+      return client.submit(action, input)
+    },
+    onSuccess: (request) => {
+      queryClient.setQueryData(actionKeys.request(request.id), request)
+      void queryClient.invalidateQueries({ queryKey: actionKeys.requests() })
+    },
+  })
+}
+
+/**
+ * Follow one Request until it settles.
+ *
+ * Polls while the lifecycle is non-terminal and stops once it is, so a settled
+ * Request costs nothing to keep on screen. The interval is deliberately short:
+ * the gap between "submitted" and "applied" is the part users find alarming,
+ * and the cheapest fix is showing it moving.
+ */
+export function useActionRequest(
+  requestId: string | null | undefined,
+  options: ReadOptions<ActionRequest> & { pollMs?: number } = {},
+): UseQueryResult<ActionRequest, Error> {
+  const client = useActionClient()
+  const queryClient = useQueryClient()
+  const { pollMs = 1_500, ...queryOptions } = options
+
+  const result = useQuery({
+    queryKey: actionKeys.request(requestId ?? ''),
+    queryFn: () => client.request(requestId as string),
+    enabled: Boolean(requestId) && queryOptions.enabled !== false,
+    refetchInterval: (query) => {
+      const lifecycle = query.state.data?.lifecycle
+      if (!lifecycle) return pollMs
+      return isTerminalLifecycle(lifecycle) ? false : pollMs
+    },
+    ...queryOptions,
+  })
+
+  /**
+   * Refresh what the app is READING once the write has actually landed.
+   *
+   * Not on submit: at that point the Request is recorded and the object is
+   * unchanged, so refetching returns the old values and caches them as fresh —
+   * the table would settle on stale data and stay there.
+   *
+   * Keyed on the CERTAINTY rather than the lifecycle. `confirmed_applied` is
+   * the moment the write commits; `succeeded` comes later, after the platform
+   * has verified its own promise, and refreshing only then leaves the table
+   * showing yesterday's row for the whole verification pass. Nothing about the
+   * data changes in that gap.
+   *
+   * Deliberately not on a refusal: nothing changed, and a refetch there is a
+   * request per failure for no new information.
+   */
+  const landed = actionEffectOf(result.data) === 'applied'
+  useEffect(() => {
+    if (!landed) return
+    void queryClient.invalidateQueries({ queryKey: blueprintKeys.all })
+  }, [landed, queryClient])
+
+  return result
+}
+
+/** The queue: Requests in this workspace, optionally narrowed by lifecycle. */
+export function useActionRequests(
+  lifecycle?: readonly ActionRequestLifecycle[],
+  options: ReadOptions<ActionRequest[]> = {},
+): UseQueryResult<ActionRequest[], Error> {
+  const client = useActionClient()
+  return useQuery({
+    queryKey: actionKeys.requests(lifecycle),
+    queryFn: () => client.requests(lifecycle),
+    ...options,
+  })
+}
+
+/**
+ * Approve or reject a Request awaiting a decision.
+ *
+ * An Action with separation of duties refuses a decision from whoever
+ * 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.
+ */
+export function useDecideActionRequest(): UseMutationResult<
+  ActionRequest,
+  Error,
+  { requestId: string; decision: 'approve' | 'reject'; reason: 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() })
+    },
+  })
+}

package/src/action-types.ts

@@ -0,0 +1,181 @@
+/**
+ * Types for the governed write plane.
+ *
+ * Reads and writes are deliberately separate surfaces. A read is answered from
+ * a catalog snapshot; a write is a REQUEST against a durable ledger that may be
+ * approved by someone else, dispatched by a background worker minutes later,
+ * and reconciled after that. Modelling both as "call the server" would hide the
+ * 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'
+
+/**
+ * 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.
+ */
+export type ActionEffectCertainty =
+  | 'not_attempted'
+  | 'confirmed_applied'
+  | 'confirmed_not_applied'
+  | 'outcome_unknown'
+
+const TERMINAL: ReadonlySet<ActionRequestLifecycle> = new Set([
+  'succeeded', 'failed', 'cancelled', 'rejected',
+])
+
+export function isTerminalLifecycle(lifecycle: ActionRequestLifecycle): boolean {
+  return TERMINAL.has(lifecycle)
+}
+
+/**
+ * What to tell the person who pressed the button.
+ *
+ * Four answers, and they come from the CERTAINTY, not the lifecycle — which is
+ * the distinction every app gets wrong, because "succeeded" reads like the
+ * finish line and is not.
+ *
+ * A request reaches `confirmed_applied` the moment the write commits, and then
+ * spends a while in `finalizing` while the platform verifies its own promise:
+ * it re-reads the target, checks the properties the Action declared it would
+ * change, evaluates the postconditions. That verification NEVER undoes the
+ * write — its worst outcome is `awaiting_resolution`, which still carries
+ * `confirmed_applied` and means a human should look at why the proof was
+ * inconclusive. So waiting for `succeeded` before telling someone their ticket
+ * exists leaves them staring at a spinner over a ticket that already exists.
+ *
+ * `uncertain` is the one that must not be collapsed into either neighbour. It
+ * means a dispatch was attempted and the outcome could not be established —
+ * the connection died mid-commit, and the write may well have landed. Rendering
+ * it as failure invites a duplicate; rendering it as success invites a lie. Say
+ * it is being checked; the platform reconciles it against the target and the
+ * answer arrives on its own.
+ */
+export type ActionEffect = 'pending' | 'applied' | 'refused' | 'uncertain'
+
+export function actionEffectOf(
+  request: Pick<ActionRequest, 'lifecycle' | 'effectCertainty'> | null | undefined,
+): ActionEffect {
+  if (!request) return 'pending'
+  switch (request.effectCertainty) {
+    case 'confirmed_applied': return 'applied'
+    case 'confirmed_not_applied': return 'refused'
+    case 'outcome_unknown': return 'uncertain'
+    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'
+}
+
+/**
+ * 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.
+ *
+ * So a control that edits a row from a table fetches the instance first:
+ *
+ * ```tsx
+ * const instance = useObjectInstance('SupportTicket', selectedId)
+ * submit.mutate({ …, expectedVersion: recordVersionOf(instance.data) })
+ * ```
+ *
+ * Returns `undefined` for a type with no overlay, which is correct — there is
+ * no version to assert, and the write path does not expect one.
+ */
+export function recordVersionOf(instance: unknown): number | undefined {
+  if (!instance || typeof instance !== 'object') return undefined
+  const meta = (instance as { _meta?: unknown })._meta
+  if (!meta || typeof meta !== 'object') return undefined
+  const version = (meta as { recordVersion?: unknown }).recordVersion
+  return typeof version === 'number' ? version : undefined
+}
+
+export interface ActionApprovalPolicy {
+  mode: 'none' | 'required'
+  threshold?: number
+  separationOfDuties?: boolean
+}
+
+/**
+ * One Action this caller may invoke.
+ *
+ * Discovery returns ONLY what the caller is authorized for. An Action absent
+ * from this list may be unpublished, undeployed, or simply not permitted to
+ * this user — the three are indistinguishable here, by design.
+ */
+export interface ActionDescriptor {
+  actionDefinitionId: string
+  apiName: string
+  displayName: string
+  description: string
+  contractDigest: string
+  activeReleaseId: string
+  availability: string
+  subject: { objectTypeId: string; mode: 'existing' | 'create' }
+  approval: ActionApprovalPolicy
+  /** JSON Schema for the whole invocation envelope, not just the inputs. */
+  inputSchema: Record<string, unknown>
+}
+
+export interface ActionRequest {
+  id: string
+  actionDefinitionId: string
+  apiName?: string
+  lifecycle: ActionRequestLifecycle
+  effectCertainty?: ActionEffectCertainty
+  createdAt?: string
+  updatedAt?: string
+}
+
+/**
+ * What a caller supplies to invoke an Action.
+ *
+ * Deliberately flatter than the wire envelope. The service takes a subject
+ * reference, a separate string `expectedSubjectVersion`, an `input` map and a
+ * `reason`; and an Action with compare-and-set ALSO takes a numeric version as
+ * an ordinary input. Two version fields, one string and one number, meaning
+ * related but different things, is the kind of contract a hand-written caller
+ * 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'`. */
+  objectId?: string
+  /** Parameter values, keyed by the Action's parameter API names. */
+  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.
+   */
+  expectedVersion?: number | string
+  /** Required when the Action declares `reason: 'required'`. */
+  reason?: string
+  correlationId?: string
+  /**
+   * Reused across retries of the SAME intended effect. Omit and the hook mints
+   * one per user intent, which is almost always what you want: a retried
+   * network call must not become a second escalation.
+   */
+  idempotencyKey?: string
+}

package/src/blueprint-client.ts

@@ -3,6 +3,9 @@ import type {
   AggregateGroupBy,
   AggregateRequest,
   AggregateResponse,
+  BlueprintFilterableProperty,
+  BlueprintObjectName,
+  BlueprintRow,
   MetricQueryRequest,
   ObjectInstance,
   QueryRequest,
@@ -57,19 +60,62 @@ export class BlueprintClient {
     })
   }
 
-  instance<TProps = Record<string, unknown>>(
-    objectType: string,
+  instance<
+    TLegacy extends object = never,
+    const TObject extends BlueprintObjectName = BlueprintObjectName,
+  >(
+    objectType: TObject,
     pk: string,
-  ): Promise<ObjectInstance<TProps>> {
-    return this.client.request<ObjectInstance<TProps>>(
+  ): Promise<ObjectInstance<[TLegacy] extends [never] ? BlueprintRow<TObject> : TLegacy>> {
+    return this.client.request<ObjectInstance<[TLegacy] extends [never] ? BlueprintRow<TObject> : TLegacy>>(
       `/v1/blueprint/object-types/${encodeURIComponent(objectType)}/instances/${encodeURIComponent(pk)}`,
     )
   }
 
-  propertyValues(objectType: string, property: string): Promise<string[]> {
-    return this.client.request<string[]>(
-      `/v1/blueprint/object-types/${encodeURIComponent(objectType)}/properties/${encodeURIComponent(property)}/values`,
-    )
+  /**
+   * Distinct values for one property — the source for a filter's options.
+   *
+   * The service answers `{ kind: 'values', values, truncated }`, not a bare
+   * array. This returned the envelope while claiming `string[]`, so every
+   * caller that trusted the type got an object where it expected a list — and
+   * `.map` on it threw at runtime in code that type-checked.
+   *
+   * `truncated` is dropped here deliberately: it means the distinct set hit the
+   * service's cap, which a filter cannot act on beyond showing what it has.
+   * Use `propertyValuesWithTruncation` when it matters.
+   */
+  async propertyValues<const TObject extends BlueprintObjectName = BlueprintObjectName>(
+    objectType: TObject,
+    property: BlueprintFilterableProperty<TObject>,
+  ): Promise<string[]> {
+    return (await this.propertyValuesWithTruncation(objectType, property)).values
+  }
+
+  /**
+   * Narrowed against the committed contract, like `instance` above: a property
+   * the workspace does not expose for filtering has no distinct-value endpoint,
+   * and asking for one is a 400 that only shows up when a filter is opened.
+   * Before generation, `BlueprintFilterableProperty` is `string` and this is the
+   * loose signature it always was.
+   */
+  propertyValuesWithTruncation<const TObject extends BlueprintObjectName = BlueprintObjectName>(
+    objectType: TObject,
+    property: BlueprintFilterableProperty<TObject>,
+  ): Promise<{ values: string[]; truncated: boolean }> {
+    return this.client
+      .request<{ kind?: string; values?: string[]; truncated?: boolean }>(
+        `/v1/blueprint/object-types/${encodeURIComponent(objectType)}/properties/${encodeURIComponent(property)}/values`,
+      )
+      // `Array.isArray`, not a truthiness check: reading `.values` off an ARRAY
+      // returns `Array.prototype.values` — the iterator function — so a payload
+      // in the older bare-array shape would hand every caller a function where
+      // it expected a list, which is a worse failure than the one being fixed.
+      .then((payload) => ({
+        values: Array.isArray(payload?.values)
+          ? payload.values
+          : Array.isArray(payload) ? (payload as string[]) : [],
+        truncated: payload?.truncated === true,
+      }))
   }
 
   metricQuery(apiName: string, request: MetricQueryRequest = {}): Promise<AggregateResponse> {

package/src/hooks.ts

@@ -6,9 +6,15 @@ import { objectsOf } from './types'
 import type {
   AggregateRequest,
   AggregateResponse,
+  BlueprintFilterableProperty,
+  BlueprintObjectName,
+  BlueprintRow,
+  BlueprintSortableProperty,
+  MetricQueryRequest,
   ObjectInstance,
   QueryRequest,
   QueryResponse,
+  TypedWhereNode,
   WhereNode,
 } from './types'
 
@@ -26,6 +32,8 @@ export const blueprintKeys = {
     ['blueprint', 'aggregate', JSON.stringify(request)] as const,
   instance: (objectType: string, pk: string) =>
     ['blueprint', 'instance', objectType, pk] as const,
+  metric: (apiName: string, request: MetricQueryRequest) =>
+    ['blueprint', 'metric', apiName, JSON.stringify(request)] as const,
 }
 
 export const FronteraBlueprintContext = createContext<BlueprintClient | null>(null)
@@ -40,7 +48,7 @@ export function useBlueprintClient(): BlueprintClient {
   return client
 }
 
-type ReadOptions<TData> = Omit<UseQueryOptions<TData, Error>, 'queryKey' | 'queryFn'>
+type ReadOptions<TData> = Omit<UseQueryOptions<TData, Error>, 'queryKey' | 'queryFn' | 'select'>
 
 /** Run an arbitrary object-set query. */
 export function useObjectQuery<TRow = Record<string, unknown>>(
@@ -62,15 +70,69 @@ export function useObjectQuery<TRow = Record<string, unknown>>(
  * pages. Filtering the returned rows in the component instead is the classic
  * mistake: it narrows only the page you happened to fetch, so a facet showing
  * 8,961 matches renders 5 rows and claims "Page 1 of 1".
+ *
+ * Paging is a CURSOR, not a page number. Hold the token from the previous
+ * response and pass it back; `hasMore` is false and `nextPageToken` absent on
+ * the last page. There is no total and no page count — an unordered scan cannot
+ * produce one, which is exactly why offset paging was removed rather than left
+ * to mislead.
+ *
+ * ```tsx
+ * const [token, setToken] = useState<string | undefined>()
+ * const page = useObjects<Ticket>('SupportTicket', { pageSize: 25, pageToken: token })
+ * // next:     setToken(page.data?.nextPageToken)
+ * // restart:  setToken(undefined)
+ * ```
  */
-export function useObjects<TRow = Record<string, unknown>>(
-  objectType: string,
-  options: ReadOptions<QueryResponse<TRow>> &
-    Omit<QueryRequest, 'objectSet'> & { where?: WhereNode } = {},
-): UseQueryResult<QueryResponse<TRow>, Error> {
-  const { select, orderBy, page, pageSize, where, ...queryOptions } = options
-  return useObjectQuery<TRow>(
-    { objectSet: objectsOf(objectType, where), select, orderBy, page, pageSize },
+type EffectiveRow<TLegacy, TObject extends BlueprintObjectName> =
+  [TLegacy] extends [never] ? BlueprintRow<TObject> : TLegacy
+
+type EffectiveFilterable<TLegacy, TObject extends BlueprintObjectName> =
+  [TLegacy] extends [never]
+    ? BlueprintFilterableProperty<TObject>
+    : Extract<keyof TLegacy, string>
+
+type EffectiveSortable<TLegacy, TObject extends BlueprintObjectName> =
+  [TLegacy] extends [never]
+    ? BlueprintSortableProperty<TObject>
+    : Extract<keyof TLegacy, string>
+
+type SelectedRow<TRow, TSelect> =
+  undefined extends TSelect
+    ? TRow
+    : TSelect extends readonly (Extract<keyof TRow, string>)[]
+      ? Pick<TRow, TSelect[number]>
+      : TRow
+
+type ObjectsOptions<
+  TLegacy,
+  TObject extends BlueprintObjectName,
+  TSelect extends readonly Extract<keyof EffectiveRow<TLegacy, TObject>, string>[] | undefined,
+> = ReadOptions<QueryResponse<SelectedRow<EffectiveRow<TLegacy, TObject>, TSelect>>> &
+  Omit<QueryRequest, 'objectSet' | 'select' | 'orderBy'> & {
+    select?: TSelect
+    orderBy?: Array<{ property: EffectiveSortable<TLegacy, TObject>; dir: 'asc' | 'desc' }>
+    where?: TypedWhereNode<EffectiveRow<TLegacy, TObject>, EffectiveFilterable<TLegacy, TObject>>
+  }
+
+export function useObjects<
+  TLegacy extends object = never,
+  const TObject extends BlueprintObjectName = BlueprintObjectName,
+  const TSelect extends readonly Extract<keyof EffectiveRow<TLegacy, TObject>, string>[] | undefined =
+    readonly Extract<keyof EffectiveRow<TLegacy, TObject>, string>[] | undefined,
+>(
+  objectType: TObject,
+  options: ObjectsOptions<NoInfer<TLegacy>, TObject, TSelect> = {},
+): UseQueryResult<QueryResponse<SelectedRow<EffectiveRow<TLegacy, TObject>, TSelect>>, Error> {
+  const { select, orderBy, pageSize, pageToken, where, ...queryOptions } = options
+  return useObjectQuery<SelectedRow<EffectiveRow<TLegacy, TObject>, TSelect>>(
+    {
+      objectSet: objectsOf(objectType, where as WhereNode | undefined),
+      select: select ? [...select] : undefined,
+      orderBy,
+      pageSize,
+      pageToken,
+    },
     queryOptions,
   )
 }
@@ -87,16 +149,47 @@ export function useAggregate(
   })
 }
 
-export function useObjectInstance<TProps = Record<string, unknown>>(
-  objectType: string,
+export function useObjectInstance<
+  TLegacy extends object = never,
+  const TObject extends BlueprintObjectName = BlueprintObjectName,
+>(
+  objectType: TObject,
   pk: string | null | undefined,
-  options: ReadOptions<ObjectInstance<TProps>> = {},
-): UseQueryResult<ObjectInstance<TProps>, Error> {
+  options: ReadOptions<ObjectInstance<EffectiveRow<TLegacy, TObject>>> = {},
+): UseQueryResult<ObjectInstance<EffectiveRow<TLegacy, TObject>>, Error> {
   const client = useBlueprintClient()
   return useQuery({
     queryKey: blueprintKeys.instance(objectType, pk ?? ''),
-    queryFn: () => client.instance<TProps>(objectType, pk as string),
+    queryFn: () => client.instance<TLegacy, TObject>(objectType, pk as string),
     enabled: Boolean(pk) && options.enabled !== false,
     ...options,
   })
 }
+
+/**
+ * One metric the organization has already defined.
+ *
+ * A metric exists so every reader computes it the same way. Deriving the same
+ * figure from raw columns in a component is how two dashboards end up
+ * disagreeing about one number, and it is where the arithmetic bugs live — one
+ * app shipped a share ratio whose numerator omitted the filter its denominator
+ * applied, reading 551.7%, next to a defined metric that had been there all
+ * along.
+ *
+ * This hook existed only as `client.metricQuery` for a while, so apps that
+ * wanted a metric hand-rolled a hook around `useBlueprintClient` — the exact
+ * detour the guidance tells authors not to take. Reach for this instead;
+ * `useAggregate` is for figures nobody has defined yet.
+ */
+export function useMetric(
+  apiName: string,
+  request: MetricQueryRequest = {},
+  options: ReadOptions<AggregateResponse> = {},
+): UseQueryResult<AggregateResponse, Error> {
+  const client = useBlueprintClient()
+  return useQuery({
+    queryKey: blueprintKeys.metric(apiName, request),
+    queryFn: () => client.metricQuery(apiName, request),
+    ...options,
+  })
+}

package/src/provider.tsx

@@ -1,11 +1,13 @@
 import type { ReactNode } from 'react'
 import type { FronteraClient } from '@frontera-sdk/core/client'
 
+import { ActionClient } from './action-client'
+import { FronteraActionContext } from './action-hooks'
 import { BlueprintClient } from './blueprint-client'
 import { FronteraBlueprintContext } from './hooks'
 
 /**
- * Plug Blueprint reads into `createFronteraApp`.
+ * Plug Blueprint reads AND governed writes into `createFronteraApp`.
  *
  * The dependency runs one way — `@frontera-sdk/blueprint` knows about
  * `@frontera-sdk/core`, never the reverse — so the app entry point composes the
@@ -16,8 +18,15 @@ import { FronteraBlueprintContext } from './hooks'
  * createFronteraApp(<App />, { providers: [blueprintProvider] })
  * ```
  *
- * The client is rebuilt whenever the host rotates the credential, because the
- * `FronteraClient` it wraps is replaced rather than mutated.
+ * Both clients come from ONE provider deliberately. Splitting them would mean
+ * an app that reads compiles and an app that acts throws at runtime with
+ * "no ActionClient in context" — a failure no type checks and every author
+ * hits exactly once, on the line where they added their first button.
+ *
+ * Both are rebuilt whenever the host rotates the credential, because the
+ * `FronteraClient` they wrap is replaced rather than mutated. That matters more
+ * for writes than reads: a submit carrying a stale token is refused after the
+ * user has already confirmed the thing they wanted to happen.
  */
 export function blueprintProvider(
   value: { client: FronteraClient },
@@ -25,7 +34,9 @@ export function blueprintProvider(
 ): ReactNode {
   return (
     <FronteraBlueprintContext.Provider value={new BlueprintClient(value.client)}>
-      {children}
+      <FronteraActionContext.Provider value={new ActionClient(value.client)}>
+        {children}
+      </FronteraActionContext.Provider>
     </FronteraBlueprintContext.Provider>
   )
 }

package/src/types.ts

@@ -25,6 +25,75 @@ export type DatePreset =
   | 'TODAY' | 'YESTERDAY' | 'LAST_7_DAYS' | 'LAST_30_DAYS' | 'LAST_90_DAYS'
   | 'THIS_MONTH' | 'LAST_MONTH' | 'THIS_QUARTER' | 'THIS_YEAR'
 
+/**
+ * Workspace-specific object types are added here by the App-local generated
+ * file. An empty registry deliberately degrades to the existing string-keyed
+ * SDK so Apps do not need code generation to remain compatible.
+ */
+export interface BlueprintRegistry {}
+
+export interface BlueprintObjectSchema<
+  TRow,
+  TFilterable extends keyof TRow & string,
+  TSortable extends keyof TRow & string,
+> {
+  row: TRow
+  filterable: TFilterable
+  sortable: TSortable
+}
+
+type RegisteredObjectName = Extract<keyof BlueprintRegistry, string>
+
+export type BlueprintObjectName =
+  [RegisteredObjectName] extends [never] ? string : RegisteredObjectName
+
+export type BlueprintRow<TObject extends BlueprintObjectName> =
+  TObject extends keyof BlueprintRegistry
+    ? BlueprintRegistry[TObject] extends BlueprintObjectSchema<infer TRow, any, any>
+      ? TRow
+      : never
+    : Record<string, unknown>
+
+export type BlueprintFilterableProperty<TObject extends BlueprintObjectName> =
+  TObject extends keyof BlueprintRegistry
+    ? BlueprintRegistry[TObject] extends BlueprintObjectSchema<infer _TRow, infer TFilterable, infer _TSortable>
+      ? TFilterable
+      : never
+    : string
+
+export type BlueprintSortableProperty<TObject extends BlueprintObjectName> =
+  TObject extends keyof BlueprintRegistry
+    ? BlueprintRegistry[TObject] extends BlueprintObjectSchema<infer _TRow, infer _TFilterable, infer TSortable>
+      ? TSortable
+      : never
+    : string
+
+type PropertyValue<TRow, TProperty extends string> =
+  TProperty extends keyof TRow ? TRow[TProperty] : unknown
+
+export type TypedPropertyCondition<TRow, TProperty extends string> =
+  TProperty extends unknown
+    ? {
+        property: TProperty
+        op: ConditionOp
+        value?: PropertyValue<TRow, TProperty>
+        values?: Array<PropertyValue<TRow, TProperty>>
+        preset?: DatePreset
+        timezone?: string
+      }
+    : never
+
+export type TypedWhereNode<TRow, TProperty extends string> =
+  | TypedPropertyCondition<TRow, TProperty>
+  | { and: Array<TypedWhereNode<TRow, TProperty>> }
+  | { or: Array<TypedWhereNode<TRow, TProperty>> }
+  | { not: TypedWhereNode<TRow, TProperty> }
+
+export type BlueprintWhereNode<TObject extends BlueprintObjectName> = TypedWhereNode<
+  BlueprintRow<TObject>,
+  BlueprintFilterableProperty<TObject>
+>
+
 export interface PropertyCondition {
   property: string
   op: ConditionOp
@@ -59,8 +128,17 @@ export interface QueryRequest {
   objectSet: ObjectSetExpr
   select?: string[]
   orderBy?: OrderBy[]
-  page?: number
   pageSize?: number
+  /**
+   * Cursor for the next page — the previous response's `nextPageToken`.
+   *
+   * There is no `page`. Offset paging was removed because it has no defined
+   * meaning over an unordered scan, and the service now REFUSES a request
+   * carrying it (`INVALID_PAGE`) rather than quietly serving page 1 forever.
+   * This SDK declared `page` for a while after that, so every caller following
+   * the types sent a parameter guaranteed to fail.
+   */
+  pageToken?: string
 }
 
 /**
@@ -70,8 +148,21 @@ export interface QueryRequest {
  */
 export interface QueryResponse<TRow = Record<string, unknown>> {
   rows: TRow[]
-  properties: Array<{ apiName: string; displayName?: string; dataType?: string }>
-  totalCount?: number
+  properties: Array<{
+    apiName: string
+    displayName?: string
+    propertyType?: string
+    dataType?: string
+  }>
+  objectType: string
+  pageSize: number
+  /** Whether another page exists. `nextPageToken` is present exactly when this is true. */
+  hasMore: boolean
+  /**
+   * Pass back as `pageToken`. Its ABSENCE is how a scan learns it has finished
+   * — there is no total, so a caller that waits for one waits forever.
+   */
+  nextPageToken?: string
 }
 
 export const AGGREGATE_FUNCTIONS = [