@tai42/api-client 0.1.0 → 0.1.1

package/src/client.ts

@@ -82,6 +82,23 @@ export interface TopicVerifierBody {
   readonly config?: Record<string, unknown>;
 }
 
+/**
+ * Body for minting a trigger link (POST `/api/hooks/trigger-links`). `ttl_seconds`
+ * is REQUIRED and nullable — a positive int is a timed link, `null` is a permanent
+ * link (`0`/negative is a loud server 400); it is always sent EXPLICITLY (a dropped
+ * key 400s server-side). `name` is optional (the server generates one when omitted);
+ * `tool_kwargs` is the optional per-link params merged last into every fire.
+ */
+export interface TriggerLinkCreateBody {
+  readonly topic: string;
+  readonly name?: string;
+  readonly execution_key: string;
+  // The link is a token door; this is its only auth knob (token → token+api_key).
+  readonly require_api_key: boolean;
+  readonly ttl_seconds: number | null;
+  readonly tool_kwargs?: Record<string, unknown> | null;
+}
+
 /** Body for adding a URL to a scope (POST `/api/auth/scopes`). */
 export interface AddUrlToScopeBody {
   readonly scope_id: string;
@@ -89,6 +106,31 @@ export interface AddUrlToScopeBody {
   readonly pattern?: string;
 }
 
+/**
+ * Body for creating a role (POST `/api/auth/roles`). `base_tier` is the security
+ * tier the role inherits (`editor`/`viewer` — `admin` is reserved); its jq is
+ * resolved server-side, never authored here. `grants` is the editable per-tag
+ * access-level map (feature-group tag → `none`/`read`/`write`); it defaults to
+ * empty (every group `none`, fail-closed) when omitted.
+ */
+export interface RoleCreateBody {
+  readonly name: string;
+  readonly description?: string;
+  readonly base_tier: string;
+  readonly grants?: Record<string, s.GrantLevel>;
+}
+
+/**
+ * Body for editing a role (PUT `/api/auth/roles/{name}`). Both fields are
+ * omit-means-KEEP: an absent `grants` preserves the stored map (never a silent
+ * wipe), an absent `description` preserves the stored description. The base-tier jq
+ * is seed-fixed and not editable here.
+ */
+export interface RoleUpdateBody {
+  readonly grants?: Record<string, s.GrantLevel>;
+  readonly description?: string;
+}
+
 /**
  * Body for pinning a route public (POST `/api/auth/public-routes`). `pattern` is an
  * optional regex the AC verifier full-matches request paths against, mapping every
@@ -311,6 +353,13 @@ export function createApiClient(config: ApiConfig) {
   ) => apiRequest(config, path, schema, options);
 
   return {
+    // The configured API base — the exact `baseUrl` this client was constructed
+    // with (`''` for a same-origin deployment). Read-only: features that must
+    // compose an ABSOLUTE API URL (a QR-encoded public path the API origin must
+    // receive, not the SPA origin) read it instead of assuming same-origin. The
+    // transport itself still joins it per request; this only surfaces the value.
+    baseUrl: config.baseUrl ?? '',
+
     // -- tools ---------------------------------------------------------------
     listTools: (signal?: AbortSignal) => req('/api/tools', s.toolNames, { signal }),
     getToolSchema: (name: string, signal?: AbortSignal) =>
@@ -579,6 +628,32 @@ export function createApiClient(config: ApiConfig) {
         method: 'DELETE',
       }),
 
+    // -- hooks: trigger links -------------------------------------------------
+    // Mint a trigger link for a topic. `ttl_seconds` is sent EXPLICITLY
+    // (including `null` for a permanent link) — the server requires the key present
+    // and 400s a dropped one; `tool_kwargs` is omitted when undefined. The raw
+    // `token` rides the response ONCE (composed into the QR URL client-side).
+    createTriggerLink: (body: TriggerLinkCreateBody) =>
+      req('/api/hooks/trigger-links', s.triggerLinkCreated, {
+        method: 'POST',
+        body: {
+          topic: body.topic,
+          name: body.name,
+          execution_key: body.execution_key,
+          require_api_key: body.require_api_key,
+          ttl_seconds: body.ttl_seconds,
+          tool_kwargs: body.tool_kwargs,
+        },
+      }),
+    // Every live trigger-link record (hash prefix only — never a raw token).
+    listTriggerLinks: (signal?: AbortSignal) =>
+      req('/api/hooks/trigger-links', s.triggerLinkList, { signal }),
+    // Revoke a link by name (immediate + durable). 404 when the name is unknown.
+    deleteTriggerLink: (name: string) =>
+      req(`/api/hooks/trigger-links/${encodeSegment(name)}`, s.triggerLinkDeleted, {
+        method: 'DELETE',
+      }),
+
     // -- mcp config schema (manifest McpTab form) ----------------------------
     getMcpConfigSchema: (signal?: AbortSignal) =>
       req('/api/mcp-config/schema', s.jsonSchema, { signal }),
@@ -610,6 +685,35 @@ export function createApiClient(config: ApiConfig) {
     unpinPublicRoute: (url: string) =>
       req('/api/auth/public-routes', s.unpinPublicResult, { method: 'DELETE', body: { url } }),
 
+    // -- auth: roles (editable per-tag RBAC) ---------------------------------
+    // The seeded + operator-authored roles as full bodies (base-tier ceiling +
+    // editable per-tag grant map). ADMIN-ONLY — the route is `secret` (a listing
+    // exposes each role's raw base-tier jq); a non-admin projection never reaches it.
+    listRoles: (signal?: AbortSignal) => req('/api/auth/roles', s.roleList, { signal }),
+    // Create an operator-authored role. The server validates the grant map + base
+    // tier and 409s on a name collision; the reserved `admin` role cannot be created.
+    createRole: (body: RoleCreateBody) =>
+      req('/api/auth/roles', s.roleBody, { method: 'POST', body }),
+    // Edit a role's per-tag grant map + description (omit-means-keep). The reserved
+    // `admin` role and any `allow_all` role are block-downgrade guarded server-side.
+    updateRole: (name: string, body: RoleUpdateBody) =>
+      req(`/api/auth/roles/${encodeSegment(name)}`, s.roleBody, { method: 'PUT', body }),
+    // Delete a role. The reserved `admin` role is undeletable; a role still assigned
+    // to any principal is a loud 409.
+    deleteRole: (name: string) =>
+      req(`/api/auth/roles/${encodeSegment(name)}`, s.roleDeleted, { method: 'DELETE' }),
+    // A role's append-only version history + who/action/before→after audit trail.
+    // ADMIN-ONLY (`secret`).
+    listRoleVersions: (name: string, signal?: AbortSignal) =>
+      req(`/api/auth/roles/${encodeSegment(name)}/versions`, s.roleVersions, { signal }),
+    // Re-point a role's active version to a prior one (LIVE — holders follow on
+    // their next request); returns the re-pointed role body.
+    rollbackRole: (name: string, version: number) =>
+      req(`/api/auth/roles/${encodeSegment(name)}/rollback`, s.roleBody, {
+        method: 'POST',
+        body: { version },
+      }),
+
     // -- auth: api keys ------------------------------------------------------
     listTokensPayload: (signal?: AbortSignal) =>
       req('/api/auth/tokens-payload', s.tokensPayload, { signal }),
@@ -738,8 +842,8 @@ export function createApiClient(config: ApiConfig) {
       req(`/api/schedules/${encodeSegment(name)}`, s.jsonValue, { method: 'DELETE' }),
 
     // -- observability -------------------------------------------------------
-    // NB: named `getObservabilityMetrics` (not `getMetrics`) — `getMetrics`
-    // already serves the Prometheus `/metrics` text endpoint.
+    // The monitoring-backend dashboard rollups (`GET /api/observability/metrics`),
+    // a JSON aggregate distinct from any raw process-metrics text endpoint.
     getObservabilityMetrics: (params: MetricsQuery = {}, signal?: AbortSignal) =>
       req('/api/observability/metrics', s.dashboardMetrics, {
         query: { from: params.from, to: params.to, granularity: params.granularity },
@@ -801,9 +905,8 @@ export function createApiClient(config: ApiConfig) {
     getMarketplaceAdvisories: (signal?: AbortSignal) =>
       req('/api/marketplace/advisories', s.marketplaceAdvisories, { signal }),
 
-    // -- system (plain-text ops endpoints) -----------------------------------
+    // -- system (plain-text ops endpoint) ------------------------------------
     getHealth: (signal?: AbortSignal) => apiText(config, '/health', { signal }),
-    getMetrics: (signal?: AbortSignal) => apiText(config, '/metrics', { signal }),
 
     // The pluggable-kind status table (`GET /api/system/kinds`) — a JSON `{data}`
     // envelope, one row per kind with its active/default/off state.

package/src/http.ts

@@ -129,9 +129,8 @@ export async function apiRequest<S extends z.ZodTypeAny>(
 }
 
 /**
- * Fetch a plain-text endpoint (the skeleton's `/health` → `"OK"` and `/metrics`
- * → Prometheus text). No `{ data }` envelope, no zod — the body is returned
- * verbatim. Non-2xx still throws loudly.
+ * Fetch a plain-text endpoint (the skeleton's `/health` → `"OK"`). No `{ data }`
+ * envelope, no zod — the body is returned verbatim. Non-2xx still throws loudly.
  */
 export async function apiText(
   config: ApiConfig,

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * @tai42/api-client — the typed transport for the tai-skeleton HTTP API.
+ * @tai42/api-client — the typed transport for the tai42-skeleton HTTP API.
  *
  * One zod schema per consumed endpoint; every response is
  * validated and every failure throws. No caching of its own — server state
@@ -14,7 +14,10 @@ export type {
   ClaimLinkBody,
   ValidateConditionBody,
   TopicVerifierBody,
+  TriggerLinkCreateBody,
   AddUrlToScopeBody,
+  RoleCreateBody,
+  RoleUpdateBody,
   PinRoutePublicBody,
   CreatePresetBody,
   SavePresetVersionBody,
@@ -67,6 +70,13 @@ export type {
   ToolMediaResult,
   ToolTagEntry,
   AuthRoute,
+  RouteAction,
+  GrantLevel,
+  RoleGrants,
+  RoleBody,
+  RoleVersion,
+  RoleAuditEvent,
+  RoleVersions,
   PresetRecord,
   PresetDetail,
   PresetBody,
@@ -95,6 +105,8 @@ export type {
   Notification,
   Notifications,
   HookParams,
+  HookList,
+  TriggerAuth,
   SettingsSchema,
   TokensPayload,
   LoginFormField,
@@ -106,6 +118,10 @@ export type {
   PatternEntry,
   SubMcpEntry,
   ClaimLinkCreated,
+  TriggerLinkCreated,
+  TriggerLinkRecord,
+  TriggerLinkList,
+  TriggerLinkDeleted,
   LogoutResult,
   AuthCapabilities,
   BackupDocument,

package/src/schemas.ts

@@ -679,14 +679,26 @@ export const notifications = z.object({
 export type Notifications = z.infer<typeof notifications>;
 
 // -- hooks -------------------------------------------------------------------
-// Shapes match tai_contract.hooks.HookParams: a hook fires a `tool` on a `topic`,
+// Shapes match tai42_contract.hooks.HookParams: a hook fires a `tool` on a `topic`,
 // optionally gated by a `condition` and shaped by an `expr` (each either an inline
 // spec or a registered id, with its own kwargs).
 
+/** A fire door — who may trigger a path, not what the fire may do. A string enum. */
+export const triggerAuth = z.enum([
+  'public',
+  'verifier',
+  'token',
+  'token+api_key',
+  'out-of-service',
+]);
+export type TriggerAuth = z.infer<typeof triggerAuth>;
+
 export const hookParams = z.object({
   name: z.string(),
   topic: z.string(),
   tool: z.string(),
+  // The api-key `user_id` the fire runs AS.
+  execution_key: z.string().min(1),
   tool_kwargs: z.record(z.string(), z.unknown()).default({}),
   condition: z.string().nullable().default(null),
   condition_id: z.string().nullable().default(null),
@@ -711,7 +723,10 @@ export const hookList = z.object({
       z.object({ verifier: z.string(), config: z.record(z.string(), z.unknown()) }),
     )
     .default({}),
+  // Per-topic fire door (topic → door). Tolerant of an older response omitting it.
+  trigger_auth: z.record(z.string(), triggerAuth).default({}),
 });
+export type HookList = z.infer<typeof hookList>;
 
 export const hookRegistered = z.object({
   registered: z.boolean(),
@@ -734,6 +749,58 @@ export const topicVerifierSet = z.object({ topic: z.string(), verifier: z.string
 /** `DELETE /api/hooks/topics/{topic}/verifier` — the unbound topic. */
 export const topicVerifierRemoved = z.object({ removed: z.boolean(), topic: z.string() });
 
+// -- trigger links -----------------------------------------------------------
+// A trigger link is a minted, token-bearing PUBLIC URL (`GET|POST /trigger/{token}`)
+// that resolves to a hook TOPIC and fires it. Studio mints, lists, and revokes them
+// on the hooks page; the QR encodes the composed absolute URL.
+
+/**
+ * `POST /api/hooks/trigger-links` — a freshly minted trigger link. `trigger_path`
+ * is a relative path (`/trigger/<token>`, never an absolute URL — Studio composes
+ * the API origin); `token` is the raw token returned exactly ONCE, in this response
+ * (nothing else stores or lists it — a listed link's QR is unrecoverable by
+ * design). `expires_at` is an ISO-8601 instant, or `null` for a permanent link.
+ */
+export const triggerLinkCreated = z.object({
+  name: z.string(),
+  trigger_path: z.string(),
+  token: z.string(),
+  topic: z.string(),
+  expires_at: z.string().nullable(),
+});
+export type TriggerLinkCreated = z.infer<typeof triggerLinkCreated>;
+
+/**
+ * One listed trigger-link record (`GET /api/hooks/trigger-links` item). `tool_kwargs`
+ * is the per-link params merged last into every fire (`null` or `{}` = none);
+ * `created_by` is the ambient creator identity (`null` on an identity-less,
+ * gate-off deployment); `token_hash_prefix` is a short hash prefix for log
+ * correlation — never a raw token (none is stored).
+ */
+export const triggerLinkRecord = z.object({
+  name: z.string(),
+  topic: z.string(),
+  execution_key: z.string().min(1),
+  trigger_auth: triggerAuth,
+  tool_kwargs: z.record(z.string(), z.unknown()).nullable(),
+  created_by: z.string().nullable(),
+  created_at: z.string(),
+  expires_at: z.string().nullable(),
+  token_hash_prefix: z.string(),
+});
+export type TriggerLinkRecord = z.infer<typeof triggerLinkRecord>;
+
+/** `GET /api/hooks/trigger-links` — every live trigger-link record. */
+export const triggerLinkList = z.object({
+  items: z.array(triggerLinkRecord),
+  total: z.number(),
+});
+export type TriggerLinkList = z.infer<typeof triggerLinkList>;
+
+/** `DELETE /api/hooks/trigger-links/{name}` — the revoked link. */
+export const triggerLinkDeleted = z.object({ removed: z.boolean(), name: z.string() });
+export type TriggerLinkDeleted = z.infer<typeof triggerLinkDeleted>;
+
 // -- settings schema ---------------------------------------------------------
 // The settings form is auto-rendered from a declarative group/field description
 // the skeleton emits from its typed settings models.
@@ -771,20 +838,113 @@ export const addUrlToScopeResult = z.object({ scope_id: z.string(), url: z.strin
 export const removeUrlFromScopeResult = z.object({ url: z.string() });
 export const removeScopeResult = z.object({ scope_id: z.string(), deleted_keys: z.number() });
 
+/**
+ * A route's authorization ACTION class, joined onto the catalog from the route
+ * registry. `read`/`write` routes are GRANTABLE — a role's per-tag level opens
+ * them; `fenced`/`secret` routes are ADMIN-ONLY and never grantable (no per-tag
+ * level reaches them). `null` marks a path the registry carries no metadata for
+ * (an unregistered/ungated path — no feature tags, no action).
+ */
+export const routeAction = z.enum(['read', 'write', 'fenced', 'secret']);
+export type RouteAction = z.infer<typeof routeAction>;
+
 /**
  * One row of the route catalog (`GET /api/auth/routes`) — a plain HTTP route with
- * its current mapping. `mapped` is the scope id, the public marker, or `null` when
- * the path is unmapped (the mapper's "unassigned" bucket source). `methods` is the
- * route's method set with `HEAD` removed.
+ * its current mapping, JOINED with its route-registry metadata. `mapped` is the
+ * scope id, the public marker, or `null` when the path is unmapped (the mapper's
+ * "unassigned" bucket source). `methods` is the route's method set with `HEAD`
+ * removed. `tags` are the route's feature-group labels, `summary` its one-line
+ * description, and `action` its authorization class — the join fields the Roles
+ * grant editor reads to derive grantable feature groups and mark the admin-only
+ * (fenced/secret) routes it must never offer a grant for. An unregistered path
+ * carries `tags: []`, `summary: ''`, `action: null`.
  */
 export const authRoute = z.object({
   path: z.string(),
   methods: z.array(z.string()),
   mapped: z.string().nullable(),
+  tags: z.array(z.string()),
+  summary: z.string(),
+  action: routeAction.nullable(),
 });
 export type AuthRoute = z.infer<typeof authRoute>;
 export const authRoutes = z.array(authRoute);
 
+// -- auth: roles (editable per-tag RBAC) -------------------------------------
+
+/** A role's per-tag ACCESS LEVEL: `none` (no access), `read`, or `write`. */
+export const grantLevel = z.enum(['none', 'read', 'write']);
+export type GrantLevel = z.infer<typeof grantLevel>;
+
+/** A role's editable grant map: feature-group TAG name → the role's access level. */
+export const roleGrants = z.record(z.string(), grantLevel);
+export type RoleGrants = z.infer<typeof roleGrants>;
+
+/**
+ * A role body (`GET /api/auth/roles`, and the write routes' echo). Layer 1 is the
+ * read-only base-tier ceiling — the seeded jq `condition` plus `base_tier`
+ * (`editor`/`viewer`, or `null` for the reserved `allow_all` admin). Layer 2 is the
+ * editable per-tag `grants` map. `allow_all` (admin) carries an empty `grants` map
+ * and reaches everything, un-lockable. `condition`/`condition_id`/`condition_kwargs`
+ * are the base-tier jq — READ-ONLY here (no raw-jq authoring surface).
+ */
+export const roleBody = z.object({
+  name: z.string(),
+  description: z.string(),
+  scopes: z.array(z.string()),
+  condition: z.string().nullable(),
+  condition_id: z.string().nullable(),
+  condition_kwargs: jsonValue.nullable(),
+  base_tier: z.string().nullable(),
+  allow_all: z.boolean(),
+  grants: roleGrants,
+});
+export type RoleBody = z.infer<typeof roleBody>;
+export const roleList = z.array(roleBody);
+
+/** `DELETE /api/auth/roles/{name}` — the deleted role's name. */
+export const roleDeleted = z.object({ name: z.string(), deleted: z.boolean() });
+
+/**
+ * One immutable role-version row (`GET /api/auth/roles/{name}/versions` →
+ * `versions`). `body` is the role body at that version; `is_current` flags the
+ * active pointer. Mirrors the generic versioned-store row shape.
+ */
+export const roleVersion = z.object({
+  version: z.number(),
+  body: roleBody,
+  tags: z.array(z.string()),
+  created_at: z.string(),
+  is_current: z.boolean(),
+});
+export type RoleVersion = z.infer<typeof roleVersion>;
+
+/**
+ * One who/action/before→after audit row (`GET /api/auth/roles/{name}/versions` →
+ * `audit`). Its `body` carries the mutation kind, the actor, and the before/after
+ * role bodies (both `null` for a create's `before` / a delete's `after`).
+ */
+export const roleAuditEvent = z.object({
+  version: z.number(),
+  body: z.object({
+    action: z.string(),
+    actor: z.string().nullable(),
+    before: jsonValue.nullable(),
+    after: jsonValue.nullable(),
+  }),
+  tags: z.array(z.string()),
+  created_at: z.string(),
+  is_current: z.boolean(),
+});
+export type RoleAuditEvent = z.infer<typeof roleAuditEvent>;
+
+/** `GET /api/auth/roles/{name}/versions` — the append-only history + audit trail. */
+export const roleVersions = z.object({
+  versions: z.array(roleVersion),
+  audit: z.array(roleAuditEvent),
+});
+export type RoleVersions = z.infer<typeof roleVersions>;
+
 /** `GET /api/auth/public-routes` — the sorted urls pinned to the public marker. */
 export const publicRoutes = z.array(z.string());
 
@@ -793,9 +953,12 @@ export const pinPublicResult = z.object({ url: z.string() });
 /** `DELETE /api/auth/public-routes` — the unpinned url (404 when not pinned). */
 export const unpinPublicResult = z.object({ url: z.string() });
 
+/** The per-key payloads (`GET /api/auth/tokens-payload`). The stable per-mint
+ * `key_fingerprint` is nested under `policy_data`; the picker reads it there. */
 export const tokensPayload = z.array(
   z.object({
-    user_id: z.string(),
+    // The value an `execution_key` binding names.
+    user_id: z.string().min(1),
     description: z.string(),
     scopes: z.array(z.string()),
     policy_data: jsonValue,
@@ -806,8 +969,11 @@ export const tokensPayload = z.array(
 );
 export type TokensPayload = z.infer<typeof tokensPayload>;
 
-/** The raw `sk-…` key string, returned once at creation time and never again. */
-export const createdApiKey = z.string();
+/** Mint reply `{ api_key, key_fingerprint }` narrowed to the raw `sk-…` key,
+ *  returned once at creation and never again. */
+export const createdApiKey = z
+  .object({ api_key: z.string(), key_fingerprint: z.string() })
+  .transform((minted) => minted.api_key);
 export const editApiKeyResult = z.object({ user_id: z.string(), updated: z.boolean() });
 export const revokeApiKeyResult = z.object({ user_id: z.string(), revoked: z.boolean() });