@tai42/api-client 19.2.1 → 20.0.0

package/src/schemas/interactions.ts

@@ -91,14 +91,51 @@ export const formData = z.object({
 });
 export type FormData = z.infer<typeof formData>;
 
+/** The kind of an ordered display block a page may carry alongside its input fields. */
+export const displayBlockKind = z.enum(['heading', 'body', 'image']);
+export type DisplayBlockKind = z.infer<typeof displayBlockKind>;
+
+/**
+ * One ordered, display-only block on a form page (never an input): a `heading` or
+ * `body` text block, or an `image`. `text` carries a heading/body's words; `src`/`alt`
+ * carry an image's source and alt text. An optional `slot` names a data key whose value
+ * the block shows in place of static `text` — filled from `format_payload.data` at send
+ * and/or by a reaction's `display` update (so a computed total is a display slot, not a
+ * special case). Every text field is `.nullish()` (absent OR explicit `null` both parse
+ * to absent) so a block that omits a key — or sends an explicit `null` — is not a
+ * whole-page parse failure. Applied per block by the preview (safeParsed via its page),
+ * so a malformed block is a loud notice, never silent.
+ */
+export const displayBlock = z.object({
+  kind: displayBlockKind,
+  text: z.string().nullish(),
+  src: z.string().nullish(),
+  alt: z.string().nullish(),
+  slot: z.string().nullish(),
+});
+export type DisplayBlock = z.infer<typeof displayBlock>;
+
+/** A page's role: an ordinary `input` page (default) or a terminal `review` summary. */
+export const formPageKind = z.enum(['input', 'review']);
+export type FormPageKind = z.infer<typeof formPageKind>;
+
 /**
  * One page of a stepped `form`: a `title` and the ordered top-level property names it
  * groups. `format_payload.pages` is the ordered list of these; absent = one page. The
  * form preview safeParses the list, so a malformed page is a loud notice, never silent.
+ *
+ * `display` is the ordered list of display-only blocks the page shows alongside (or
+ * instead of, for a review page) its input fields; it defaults to empty, so a page that
+ * carries none renders exactly as before. `kind` marks a `review` page — a terminal
+ * summary step that shows the readback of entered values and the confirm/submit footer
+ * and carries no new input fields; it defaults to `input`. Both are additive: an older
+ * payload ({title, fields}) parses unchanged.
  */
 export const formPage = z.object({
   title: z.string(),
   fields: z.array(z.string()),
+  display: z.array(displayBlock).default([]),
+  kind: formPageKind.default('input'),
 });
 export type FormPage = z.infer<typeof formPage>;
 
@@ -106,6 +143,59 @@ export type FormPage = z.infer<typeof formPage>;
 export const formPages = z.array(formPage);
 export type FormPages = z.infer<typeof formPages>;
 
+/**
+ * When a `form` reacts while it is open (`format_payload.reactions`): the plain,
+ * renderer-readable description of WHEN the form calls its reaction handler. Absent ⇒ a
+ * static (non-reacting) form, exactly as before. `field_changed` names the fields whose
+ * change triggers a reaction; `page_advanced` names the pages (by title) whose advance
+ * triggers one; `submitted` is true when the submission is checked by a reaction before
+ * acceptance; `choices` names the fields whose CHOICE LISTS a reaction may replace while
+ * the form is open (for such a field the send-time option list is advisory — the consumer
+ * owns membership at the `submitted` event). Every member defaults to empty/false so a
+ * partial declaration parses; a malformed block is a loud notice via the preview.
+ */
+export const formReactions = z.object({
+  field_changed: z.array(z.string()).default([]),
+  page_advanced: z.array(z.string()).default([]),
+  submitted: z.boolean().default(false),
+  choices: z.array(z.string()).default([]),
+});
+export type FormReactions = z.infer<typeof formReactions>;
+
+/**
+ * The form update a reaction door returns (`POST /api/interactions/{id}/react`): the
+ * same kind of data a form is sent with, applied to the open form. `values` sets field
+ * values; `options` replaces the per-send choice list of option-bearing fields; `errors`
+ * shows per-field messages (keyed by field name); `display` fills display slots (keyed by
+ * slot name) — a computed total among them. Every member defaults to empty, so a reaction
+ * that touches only one of them returns only that one. The door response is safeParsed, so
+ * a malformed update surfaces loudly rather than applying a half-understood change.
+ */
+export const formUpdate = z.object({
+  values: z.record(z.string(), z.unknown()).default({}),
+  options: z.record(z.string(), z.array(formOption)).default({}),
+  errors: z.record(z.string(), z.string()).default({}),
+  display: z.record(z.string(), z.unknown()).default({}),
+});
+export type FormUpdate = z.infer<typeof formUpdate>;
+
+/**
+ * The event a reaction round-trip reports to the door: `kind` is which of the three
+ * declared events fired, `field` names the changed field for a `field_changed` event, and
+ * `page` names the advanced-from page (by title) for a `page_advanced` event. A
+ * `submitted` event carries neither. The body also carries the partial `values` filled so
+ * far (see {@link interactionsClient}'s `reactInteraction`).
+ */
+export const reactionEventKind = z.enum(['field_changed', 'page_advanced', 'submitted']);
+export type ReactionEventKind = z.infer<typeof reactionEventKind>;
+
+export const reactionEvent = z.object({
+  kind: reactionEventKind,
+  field: z.string().optional(),
+  page: z.string().optional(),
+});
+export type ReactionEvent = z.infer<typeof reactionEvent>;
+
 export const interaction = z.object({
   interaction_id: z.string(),
   group_id: z.string(),

package/src/schemas/members.ts

@@ -0,0 +1,121 @@
+/** Member, invite, directory and member-action schemas for the generic Members view. */
+import { z } from 'zod';
+
+import { jsonSchema } from './shared';
+
+/**
+ * Where a declared member action renders: a page-level button, a member-row menu
+ * item, or an invite-row menu item. A provider classifies each of its own actions
+ * into one of these three places; Studio only joins by `scope`, never reads the
+ * provider's meaning behind it.
+ */
+export const memberActionScope = z.enum(['page', 'member_row', 'invite_row']);
+export type MemberActionScope = z.infer<typeof memberActionScope>;
+
+/**
+ * One platform principal a member holds (`GET /api/auth/members` →
+ * `members[].principals[]`). `user_id` is the platform principal id; `disabled` is
+ * taken from that principal's own record (the store the principals listing reads),
+ * never from a provider.
+ */
+export const memberPrincipalState = z.object({
+  user_id: z.string(),
+  disabled: z.boolean(),
+});
+export type MemberPrincipalState = z.infer<typeof memberPrincipalState>;
+
+/**
+ * One person an accounts provider owns, as the directory door returns them
+ * (`GET /api/auth/members` → `members[]`). `id` is the provider's stable handle for
+ * the person (a list key, not shown). `email` is the sign-in identity; `role` names
+ * the platform role the person holds (the NAME only — the role definition is read
+ * from the role listing). `principals` carries each principal's platform-joined
+ * state; `disabled` is derived True only when EVERY principal is disabled, so a
+ * person with any enabled principal still reads active while the per-principal truth
+ * stays visible. `handle` routes an invoke back to the producing provider and pins
+ * this row; `action_keys` are the opaque catalog keys of the actions applicable to
+ * it — Studio joins and echoes both, never parses them. `created_at` is an ISO-8601
+ * instant.
+ */
+export const memberRow = z.object({
+  id: z.string(),
+  email: z.string(),
+  role: z.string(),
+  created_at: z.string(),
+  principals: z.array(memberPrincipalState),
+  disabled: z.boolean(),
+  handle: z.string(),
+  action_keys: z.array(z.string()),
+});
+export type MemberRow = z.infer<typeof memberRow>;
+
+/**
+ * One outstanding invitation an accounts provider holds, as the directory door
+ * returns them (`GET /api/auth/members` → `invites[]`). `id` is the provider's
+ * stable handle for the invited person; `email` is the invited address; `role` names
+ * the platform role they will hold (name only, as on {@link memberRow}). An
+ * invitation holds no principal, so it carries no principal state. `handle` and
+ * `action_keys` are the opaque routing tokens (see {@link memberRow}). `created_at`
+ * and `expires_at` are ISO-8601 instants.
+ */
+export const inviteRow = z.object({
+  id: z.string(),
+  email: z.string(),
+  role: z.string(),
+  created_at: z.string(),
+  expires_at: z.string(),
+  handle: z.string(),
+  action_keys: z.array(z.string()),
+});
+export type InviteRow = z.infer<typeof inviteRow>;
+
+/**
+ * The deployment-wide membership (`GET /api/auth/members`): every accounts
+ * provider's people and outstanding invitations, aggregated and platform-joined by
+ * the backend into one view so a generic Members screen renders without naming any
+ * provider.
+ */
+export const memberDirectory = z.object({
+  members: z.array(memberRow),
+  invites: z.array(inviteRow),
+});
+export type MemberDirectory = z.infer<typeof memberDirectory>;
+
+/**
+ * One declared member action, serialized for the catalog (`GET
+ * /api/auth/member-actions` → `actions[]`). `key` is the opaque catalog key a caller
+ * joins and echoes, never parses. `label` is the resolved wording. `scope` places
+ * the action; `destructive` asks for a confirm before invoking. `input_schema` and
+ * `result_schema` are the declared models' JSON Schema — a caller renders an input
+ * form and a read-only result view from them generically, with no provider field
+ * name known to Studio.
+ */
+export const memberActionDescriptor = z.object({
+  key: z.string(),
+  label: z.string(),
+  scope: memberActionScope,
+  destructive: z.boolean(),
+  input_schema: jsonSchema,
+  result_schema: jsonSchema,
+});
+export type MemberActionDescriptor = z.infer<typeof memberActionDescriptor>;
+
+/**
+ * Every declared member action across the registered accounts providers (`GET
+ * /api/auth/member-actions`). ADMIN-ONLY (`secret`) — a non-admin projection never
+ * reaches the route, exactly as the members listing.
+ */
+export const memberActionCatalog = z.object({
+  actions: z.array(memberActionDescriptor),
+});
+export type MemberActionCatalog = z.infer<typeof memberActionCatalog>;
+
+/**
+ * The invoke-door result (`POST /api/auth/member-actions/invoke`): the provider's
+ * result-model dump, carried opaquely. `result` is rendered through the action's
+ * `result_schema`; Studio reads no field of it by name.
+ */
+export const invokeMemberActionResult = z.object({
+  result: jsonSchema,
+});
+export type InvokeMemberActionResult = z.infer<typeof invokeMemberActionResult>;