@frontera-sdk/blueprint 1.50.84 → 1.51.1

package/package.json

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

package/src/action-client.ts

@@ -1,4 +1,5 @@
 import type { FronteraClient } from '@frontera-sdk/core/client'
+import { FronteraError } from '@frontera-sdk/core/errors'
 import type {
   ActionDescriptor,
   ActionRequest,
@@ -8,6 +9,9 @@ import type {
 
 const BASE = '/v1/blueprint/governed-actions'
 
+/** The token of a person signed in to an externally hosted App. */
+const APP_USER_TOKEN_PREFIX = 'sk-au-'
+
 /**
  * The governed write plane.
  *
@@ -20,10 +24,36 @@ const BASE = '/v1/blueprint/governed-actions'
  * 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`.
+ *
+ * A person signed in to an EXTERNALLY HOSTED App is checked against the App's
+ * roles instead: `discover` lists the Actions their roles hold, and `request`
+ * 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.
  */
 export class ActionClient {
   constructor(private readonly client: FronteraClient) {}
 
+  /**
+   * The refusal for a call only a Frontera member can make, when the session
+   * belongs to a person signed in to an externally hosted App.
+   *
+   * The service answers such a call as if no credential had been sent. Left to
+   * that, the App would see "Authentication required" and the session would
+   * sign the person in again over a call that can never succeed. Said here
+   * instead, by name.
+   */
+  private membersOnly(what: string, instead: string): FronteraError | null {
+    const credential = this.client.config.credential
+    if (credential.kind !== 'token' || !credential.token.startsWith(APP_USER_TOKEN_PREFIX)) return null
+    return new FronteraError(
+      `${what} is not available to people signed in to an externally hosted App. ${instead}`,
+      { code: 'FORBIDDEN', status: 403 },
+    )
+  }
+
   /**
    * Actions this user may invoke, here, now.
    *
@@ -67,6 +97,11 @@ 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`.',
+    )
+    if (refused) return Promise.reject(refused)
     return this.client.request<ActionRequest[]>(`${BASE}/requests`, {
       query: lifecycle?.length ? { lifecycle: lifecycle.join(',') } : undefined,
     })
@@ -82,6 +117,11 @@ export class ActionClient {
    * from whoever submitted it.
    */
   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>(
       `${BASE}/requests/${encodeURIComponent(requestId)}/approvals`,
       { method: 'POST', body: { decision, reason } },
@@ -94,6 +134,11 @@ export class ActionClient {
    * rather than ignored, because the route accepts an exact key set.
    */
   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' },

package/src/action-types.ts

@@ -150,12 +150,26 @@ export interface ActionDescriptor {
  * "raised by the Collections Agent, under Alia's authority" are different
  * things to approve, and flattening them into one line hides the one an
  * approver most needs to see.
+ *
+ * `applicationId` names the App a request was raised through: by the person
+ * directly, or by a Function they started from that App. It does not change
+ * `kind`. Absent from a platform that predates the field.
+ *
+ * `appUserId` and `appUserName` are set when the person is an App user: someone
+ * signed in to an externally hosted App, who is not a workspace member. `kind`
+ * is then `person`, `userId` is `null`, and `applicationId` is their App. Show
+ * `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.
  */
 export interface ActionRequestRequester {
   kind: 'agent' | 'person' | 'automation'
   agentId: string | null
   agentName: string | null
   userId: string | null
+  applicationId?: string | null
+  appUserId?: string | null
+  appUserName?: string | null
 }
 
 /** How to read one submitted parameter value: its label, declared kind and whether it is withheld. */