wicked-crew-api-types 0.175.0 → 0.178.0

package/index.d.ts

@@ -13157,6 +13157,8 @@ export interface SourceCatalogRelation {
   foreignKeys: Array<{ name: string; columns: string[]; references: { schema: string | null; table: string; columns: string[] } }>;
   /** Postgres: row security enabled or forced. */
   rowSecurity?: boolean;
+  /** (api-types 0.176.0) Postgres: row security FORCED (it applies to the table's owner too). */
+  rowSecurityForced?: boolean;
 }
 
 /** A `sql` source's catalog: structure only. */
@@ -15076,6 +15078,38 @@ export interface AppLockAction {
   contractHash: string;
 }
 
+/**
+ * (api-types 0.176.0, DES-APPS-001 K2b) One argument of a `.json` query text: a declared parameter of the
+ * query, or a literal fixed by the app (a string of at most 1,000 characters). Viewer values are declared on
+ * the query's parameters (`from`), never here.
+ */
+export type AppQueryArg = { kind: 'param'; name: string } | { kind: 'literal'; value: string | number | boolean | null };
+
+/**
+ * (api-types 0.176.0) `queries/<id>.json` of a `rest` or `mcp` query: one registry tool the person accepted
+ * as a read on the source sheet, and its arguments (at most 50, each one of the tool's input properties).
+ */
+export interface AppToolQueryText {
+  tool: string;
+  args: Record<string, AppQueryArg>;
+}
+
+/**
+ * (api-types 0.176.0) `queries/<id>.json` of a `crew` query: one route the built-in crew source reads
+ * (`SourceCatalogResponse` of `crew` lists them, e.g. `/runs/:id`), every `:param` of it in `params`, and
+ * query-string values in `query`.
+ */
+export interface AppCrewQueryText {
+  route: string;
+  params: Record<string, AppQueryArg>;
+  query: Record<string, AppQueryArg>;
+}
+
+// How a query's text binds its parameters (api-types 0.176.0): SQL `$n` (Postgres) and the n-th `?` (MySQL,
+// SQLite) bind the n-th parameter in the order `params.properties` declares them, and every declared
+// parameter is used; GraphQL variables are the parameters by name; `.json` texts name them in `AppQueryArg`s.
+// The order is part of the query's contract, so reordering the parameters is checked again.
+
 // ── Apps: the store and its routes (DES §6.4, §7.6, §9.1) ────────────────────────────────────────
 
 /**
@@ -15283,7 +15317,13 @@ export interface AppQueryBody {
 /** One cell: values are rendered as text by the runtime. */
 export type AppCell = string | number | boolean | null;
 
-/** `POST /apps/:app/query` 200 (DES §7.2). `rows` are aligned with `columns`. */
+/**
+ * `POST /apps/:app/query` 200 (DES §7.2). `rows` are aligned with `columns`, which are exactly the query's
+ * declared output (api-types 0.177.0: values coerced to their declared types; `integer` and `number` cells
+ * are JS numbers within ±2^53; `date` is `YYYY-MM-DD`, `datetime` ISO 8601). `truncated`: a cap cut the
+ * answer (5,000 rows, 10 MB, a cell past 64 KB cut). `hasMore`: the more path says another page exists.
+ * `ms`: this request's time. Identical reads within the query's cache life share one answer.
+ */
 export interface AppQueryResponse {
   columns: AppOutputColumn[];
   rows: AppCell[][];
@@ -15294,6 +15334,151 @@ export interface AppQueryResponse {
   cachedAt: number | null;
 }
 
+// ── Apps: the write path (api-types 0.178.0, DES-APPS-001 §7.3, §7.4, §9.4, slice K2b) ─────────────────
+
+/** Where a value on an action card comes from (DES §7.3: "your sign-in", "fixed by the app", "filled by studio: now"). */
+export type AppActionValueSource = 'param' | 'app' | 'viewer' | 'crew';
+
+/** One value on a card: the column or argument, the value as it will be sent, and where it comes from. */
+export interface AppActionCardValue {
+  name: string;
+  /** A list argument shows its items (an array parameter, the viewer's groups). */
+  value: string | number | boolean | null | Array<string | number | boolean>;
+  from: AppActionValueSource;
+  /** The words for `from`: "you entered it", "fixed by the app", "your sign-in", "filled by studio: now". */
+  label: string;
+}
+
+/**
+ * The card crew generates from the RESOLVED operation (DES §7.3) and the host draws outside the app's
+ * frame: the only per-run consent. Every value is on it, literals included.
+ */
+export type AppActionCard =
+  | {
+      kind: 'api';
+      app: string;
+      action: string;
+      source: string;
+      /** The source's kind: `rest`, `mcp-http`, `mcp-stdio` or `graphql`. */
+      sourceKind: string;
+      /** `POST /v1/tickets/4821/assign`, `mutation assign`, or `tool assign_ticket`. */
+      operation: string;
+      args: AppActionCardValue[];
+      /** The request as it will be sent (method and URL and body, the GraphQL document and variables, or the tool call). */
+      request: string;
+      /** The action's description, labelled "The app says" by the host. */
+      appSays?: string;
+    }
+  | {
+      kind: 'row-write';
+      app: string;
+      action: string;
+      source: string;
+      /** The login the write runs as. */
+      login: string;
+      verb: 'INSERT' | 'UPDATE' | 'DELETE';
+      /** Schema-qualified: `support.tickets`. */
+      table: string;
+      /** Every column it sets (an insert: every column of the table), with its value. */
+      columns: AppActionCardValue[];
+      /** The key (`id = 4821`). */
+      key: AppActionCardValue[];
+      /** "exactly 1 row, verified". */
+      rows: string;
+      /** "plain table: no triggers, rules, inheritance or row security; checked just now". */
+      checks: string;
+      /** The statement as it will run (values are its `$n` parameters, listed above). */
+      statement: string;
+      appSays?: string;
+    };
+
+/** `POST /apps/:app/actions/:id/prepare` (HUMAN operator). `params` are the action's declared, non-viewer parameters. */
+export interface AppActionPrepareBody {
+  version: number | string;
+  params?: Record<string, unknown>;
+}
+
+/** `POST /apps/:app/actions/:id/prepare` 200: the record to run within 2 minutes, and its card. */
+export interface AppActionPrepareResponse {
+  record: string;
+  card: AppActionCard;
+  /** Unix millis. */
+  expiresAt: number;
+}
+
+/** `POST /apps/:app/actions/:id/run` (HUMAN operator, the person who prepared it). */
+export interface AppActionRunBody {
+  record: string;
+}
+
+/**
+ * An action record's states (DES §7.3): `prepared → running → succeeded | failed | unknown`. `running` is the
+ * linearization point (persisted before the upstream call); `unknown` = the outcome could not be known (the
+ * daemon restarted during the call, or the call was sent and no answer came). Nothing is ever re-run.
+ */
+export type AppActionState = 'prepared' | 'running' | 'succeeded' | 'failed' | 'unknown';
+
+/** `POST /apps/:app/actions/:id/run` 200: how it ended. */
+export interface AppActionRunResponse {
+  record: string;
+  state: 'succeeded' | 'failed' | 'unknown';
+  /** Why it failed or is unknown, in crew's words. */
+  reason?: string;
+  /** A row write: `{ table, op, key }`; an API action: the answer, scrubbed and cut at 64 KB. */
+  result?: unknown;
+}
+
+/** `GET /apps/:app/actions/records/:id` 200 (the person who prepared it): answers a lost response. */
+export interface AppActionRecordView {
+  id: string;
+  app: string;
+  action: string;
+  version: number | null;
+  tree: string;
+  state: AppActionState;
+  reason?: string;
+  result?: unknown;
+  card: AppActionCard;
+  createdAt: number;
+  expiresAt: number;
+  endedAt?: number;
+}
+
+/** `POST /apps/:app/actions/:id/grant` (HUMAN operator): grant the action as it is in this version. */
+export interface AppActionGrantBody {
+  version: number | string;
+}
+
+/**
+ * A grant (DES §9.4): keyed by app and action, bound to the action hash, the contract hash (a row write's
+ * holds the table's safety fingerprint) and the source descriptor; any change withdraws it. Turning a
+ * source's Allow writes off withdraws its row-write grants.
+ */
+export interface AppActionGrant {
+  app: string;
+  action: string;
+  kind: 'api' | 'row-write';
+  source: string;
+  actionHash: string;
+  contractHash: string;
+  descriptorHash: string;
+  /** A row write: the table safety check's fingerprint at grant. */
+  fingerprint?: string;
+  grantedBy: Actor;
+  /** Unix millis. */
+  grantedAt: number;
+}
+
+/** `POST …/grant` 200 and `GET …/grant` 200 (observer). */
+export interface AppActionGrantResponse {
+  grant: AppActionGrant;
+}
+
+/** `DELETE …/grant` 200: whether a grant was there. */
+export interface AppActionRevokeResponse {
+  revoked: boolean;
+}
+
 /** One reason a check refused a tree. `path` is a JSON path into `apps.json`, or a repo path. */
 export interface AppCheckFinding {
   stage: 'spec' | 'files' | 'policy' | 'source';
@@ -15317,6 +15502,26 @@ export interface AppCheckFinding {
  *  - 429 `rate_limited` (with `retryAfterMs`: a query queue or a per-viewer rate is full, DES §7.5);
  *  - 501 `not_implemented` (a route a later slice serves; nothing happened);
  *  - 503 `apps_unavailable`.
+ *
+ * (api-types 0.178.0, K2b) The action routes also answer: 409 `read_only` (`APPS_READ_ONLY` is set: no
+ * write at all), `not_granted` (no grant for the action as it is now; a stale grant is withdrawn and says
+ * so), `writes_off` (the source's Allow writes switch is off), `table_changed` (the row write's table no
+ * longer passes the safety check, or its fingerprint differs from the grant's: the grant is withdrawn),
+ * `value_does_not_fit` (a value its column would change, P28), `record_used` (the record already ran or is
+ * running: nothing is re-run), `record_expired`, `missing_grants` (granting a row write whose login lacks a
+ * privilege the write needs: the message lists the exact `GRANT` statements); 404 `unknown_action`,
+ * `unknown_record`.
+ *
+ * (api-types 0.177.0, K2b) `POST /apps/:app/query` also answers: 400 `bad_params` (a parameter that is not
+ * declared, does not satisfy its schema, is required and missing, or is viewer-bound and was sent); 403
+ * `human_only` for an agent or plugin actor (an app's rows reach a person, never a model); 409
+ * `viewer_unavailable` (a viewer-bound value crew does not know, e.g. no git `user.email` locally, or groups
+ * in local preview), `contract_changed` (the source's connection, or what the query reads there, changed
+ * since this version was checked: check it again), `query_refused` (the read policy or the source's live
+ * relation checks refuse it now); 422 `result_invalid` (a value does not fit its declared column: the
+ * message names the column and row, never the value); 502 `source_failed` / `source_unavailable` (the
+ * source answered an error or could not be reached: a class and a SQLSTATE, never the source's words); 504
+ * `source_timeout` (stopped at the 10 s deadline, at the source).
  */
 export interface AppErrorBody {
   code:
@@ -15342,7 +15547,25 @@ export interface AppErrorBody {
     | 'not_this_turn'
     | 'not_checked'
     | 'reviewer_not_distinct'
-    | 'apps_unavailable';
+    | 'apps_unavailable'
+    | 'bad_params'
+    | 'viewer_unavailable'
+    | 'contract_changed'
+    | 'query_refused'
+    | 'result_invalid'
+    | 'source_failed'
+    | 'source_unavailable'
+    | 'source_timeout'
+    | 'read_only'
+    | 'not_granted'
+    | 'writes_off'
+    | 'table_changed'
+    | 'value_does_not_fit'
+    | 'record_used'
+    | 'record_expired'
+    | 'unknown_action'
+    | 'unknown_record'
+    | 'missing_grants';
   error: string;
   /** `rate_limited`: when to try again (also sent as `Retry-After`). */
   retryAfterMs?: number;
@@ -15380,9 +15603,15 @@ export type AppsCheckResponse =
  * serves that route for real rather than answering `501`.
  */
 export interface AppsCapabilities {
-  /** `POST /apps/:app/query` runs queries (until then it checks the receipt, then answers `501`). */
+  /**
+   * `POST /apps/:app/query` runs queries (until then it checks the receipt, then answers `501`). True since
+   * api-types 0.177.0 (K2b, the executor).
+   */
   query: boolean;
-  /** `POST /apps/:app/actions/:id/prepare|run|grant`, `GET …/actions/records/:id`. */
+  /**
+   * `POST /apps/:app/actions/:id/prepare|run|grant`, `GET|DELETE …/grant`, `GET …/actions/records/:id`. True
+   * since api-types 0.178.0 (K2b, the write path: API actions and Postgres row writes).
+   */
   actions: boolean;
   /** `POST /apps/:app/turns` launches `apps-turn` runs. */
   turns: boolean;
@@ -15390,7 +15619,10 @@ export interface AppsCapabilities {
   publish: boolean;
   /** `POST /apps/uploads`. */
   uploads: boolean;
-  /** The read policy and the per-kind source check run, so a change to queries or actions can land. */
+  /**
+   * The read policy and the per-kind source check run, so a change to queries or actions can land (true since
+   * api-types 0.176.0 on a daemon with a connector registry: crew's source stage, DES §9.2 step 3).
+   */
   sourceCheck: boolean;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.175.0",
+  "version": "0.178.0",
   "description": "The wire contract of the wicked-crew daemon's /api/v1 REST surface and /ws CoreEvent frames \u2014 types only, zero runtime",
   "type": "module",
   "types": "./index.d.ts",