@crossworks/client-types 0.232.354 → 0.232.362

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crossworks/client-types",
-  "version": "0.232.354",
+  "version": "0.232.362",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",

package/src/dto/access.ts

@@ -77,6 +77,30 @@ export type AccessNodeView = {
   /** The shared folder it takes its share from (folder sharing); null when
    *  none. Absent from brains before folder sharing. */
   sharedVia?: AccessSharedVia | null;
+  /** What it is read through by embeds (migration 0208); null when nothing
+   *  reaches it. Absent from brains before 0208. */
+  readThrough?: AccessReadThrough | null;
+};
+
+/** An item is read through the items that embed it (migration 0208): a
+ *  shared note makes its image readable wherever the image lives. The item
+ *  is read at least at `level`, whatever its own level says, so the control
+ *  offers nothing above it: take the embed out, or move the embedder out of
+ *  its shared folder, to hide it. */
+export type AccessReadThrough = {
+  level: 'team' | 'client';
+  /** The nearest items that embed it and carry a share, most open first
+   *  (at most five). */
+  via: Array<{
+    id: string;
+    title: string;
+    /** The node type ('note', 'page', 'draw', ...). */
+    type: string;
+    level: 'team' | 'client';
+    /** 'folder': shared by its own folder; 'embed': itself read through
+     *  another embed. */
+    through: 'folder' | 'embed';
+  }>;
 };
 
 /** The nearest shared folder holding an item (folder sharing, phase 4). The

package/src/dto/review.ts

@@ -5,7 +5,7 @@
  * the wire, so an older brain or an older client keeps working.
  */
 import type { AccessItemView, AccessLevel } from './access';
-import type { TreeCrumb, TreeKind } from '../tree';
+import type { TreeCrumb, TreeKind, TreeShareLevel, TreeVisibilityChange } from '../tree';
 
 /** Who wrote a reviewable item: a member or a client login. */
 export type ReviewAuthorRole = 'member' | 'client';
@@ -43,6 +43,10 @@ export type AcceptPlace = {
   /** The folder's crumbs, top-down, itself included. */
   crumbs: TreeCrumb[];
   creates: string[];
+  /** The share it is read at there through a shared folder (null: none):
+   *  the item is read at the more open of this and the chosen level. Absent
+   *  from brains before the Accept visibility check. */
+  share?: TreeShareLevel | null;
 };
 
 /** POST /api/team-admin/submissions/:id/accept and
@@ -61,6 +65,25 @@ export type AcceptRequest = {
    *  For a client's item at client or public every closure item that goes
    *  down must be here. */
   confirmedIds?: string[];
+  /** The admin saw the `visibility` refusal's list and accepts that those
+   *  items are read above the chosen level where they land. */
+  visibilityConfirmed?: boolean;
+};
+
+/** 409 from either Accept (brains with the Accept visibility check): the item, or something of its
+ *  bundle, lands in a shared folder and would be read above the chosen
+ *  level there. Nothing moved; repeat with `visibilityConfirmed: true`. */
+export type AcceptVisibilityRefusal = {
+  error: string;
+  reason: 'visibility';
+  /** The first changes (at most TREE_VISIBILITY_LIST_MAX): `from` the
+   *  chosen level, `to` the level it would be read at. */
+  changes: TreeVisibilityChange[];
+  total: number;
+  /** Brain items the bundle embeds that would be read through it at the
+   *  folder's share (migration 0208), `from` now, `to` then. Absent when
+   *  there are none, and from brains before it was listed. */
+  alsoEmbeds?: TreeVisibilityChange[];
 };
 
 /** 409 from either Accept: a client's item at client or public without the

package/src/dto/rows.ts

@@ -175,6 +175,13 @@ export type AppRow = {
   isHub: boolean;
   /** Access level (admin > team > client > public); the owner UI's badge. */
   audience: AccessLevel;
+  /** The share it inherits from a folder above it (team or client), or
+   *  null; it is read at the more open of this and `audience`. Optional:
+   *  absent from brains before the folder audit fixes. */
+  inherited?: 'team' | 'client' | null;
+  /** The share it is read at through something that embeds it (migration
+   *  0208), or null. Optional: absent from brains before it. */
+  embedded?: 'team' | 'client' | null;
   /** Informational (client logins C6): members and clients only read the
    *  app's data. Off, an app at team or client level is a shared workspace
    *  everyone who runs it writes. Set with PATCH /api/apps/:id

package/src/index.ts

@@ -41,6 +41,7 @@ export type {
   AccessNodeUpdate,
   AccessNodeView,
   AccessSharedVia,
+  AccessReadThrough,
   ClientOldLinkAbove,
   ClientReport,
   ClientReportAck,
@@ -56,6 +57,7 @@ export type {
   AcceptPlace,
   AcceptPreview,
   AcceptRequest,
+  AcceptVisibilityRefusal,
   ReviewAuthorRole,
   ReviewAuthorView,
 } from './dto/review';

package/src/tree.ts

@@ -28,7 +28,7 @@ export const TREE_KINDS = [
   'contacts',
   'secrets',
   // Recall v2's maps (its own content type, not pages). Appended last so no
-  // earlier kind's index moves. Not served until the Recall screen ships.
+  // earlier kind's index moves. Served since the Recall screen (R3).
   'recall',
 ] as const;
 export type TreeKind = (typeof TREE_KINDS)[number];
@@ -160,11 +160,14 @@ export const TREE_KIND_SPECS: Readonly<Record<TreeKind, TreeKindSpec>> = {
   },
   // The tree lists maps only; a map's cards are recall_nodes rows, never
   // nodes, so they never appear as items.
+  // Not shareable YET: team sharing is Recall R6, which adds the recall root
+  // to nodes_share_level_ck and the type to mantle_workspace_kind(). Until
+  // then the database refuses the share, so the tree must not offer it.
   recall: {
     kind: 'recall',
     root: 'recall',
     nodeType: 'recall',
-    shareable: true,
+    shareable: false,
     shareLevels: ['team'],
     sorts: ['name', 'updated'],
   },
@@ -222,12 +225,16 @@ export type TreeItem = {
   /** A short kind-specific token for the status slot: a file's extension, a
    *  secret's kind, an event's start. Null when the kind has none. */
   subtype: string | null;
-  /** Who can read it: its own level, or its folder's share when that is more
-   *  open. */
+  /** Who can read it: the most open of its own level, its folder's share and
+   *  the share of something that embeds it. */
   level: AccessLevel;
   /** The share it takes from the nearest shared folder holding it (what
    *  "Shared via" names); null = none. `level` already counts it. */
   inherited?: TreeShareLevel | null;
+  /** The share it is read at through something that embeds it (a shared
+   *  note's image), kept by the brain; absent = none. `level` already
+   *  counts it. */
+  embedded?: TreeShareLevel | null;
   state: TreeItemState | null;
   updatedAt: string;
   meta?: TreeItemMeta;
@@ -299,6 +306,10 @@ export type TreeVisibilityChange = {
   title: string;
   from: AccessLevel;
   to: AccessLevel;
+  /** The item's node type ('file', 'table', 'note', 'branch', ...), sent in
+   *  `alsoEmbeds`: an embed may open any workspace item, and a table
+   *  opening is more than an image. Absent elsewhere. */
+  type?: string;
 };
 export type TreeVisibilityRefusal = {
   error: 'visibility';
@@ -306,6 +317,18 @@ export type TreeVisibilityRefusal = {
   changes: TreeVisibilityChange[];
   /** How many items change in all. */
   total: number;
+  /** Items elsewhere that pages, drawings and notes in `changes` embed,
+   *  whose access changes with them: `to` more open when they become
+   *  readable through them, less open when an unshare or a move out takes
+   *  that away (nothing's own level changes; migration 0208). Absent when
+   *  there are none, and from brains before it was listed. */
+  alsoEmbeds?: TreeVisibilityChange[];
+  /** How many embedded items change in all (`alsoEmbeds` holds the first
+   *  TREE_VISIBILITY_LIST_MAX). A confirm's `seen` is `total` plus this. */
+  embedsTotal?: number;
+  /** @deprecated Never sent: an unreleased first form of `alsoEmbeds`, when
+   *  a share still lowered embeds for good. */
+  alsoLowered?: TreeVisibilityChange[];
 };
 export const TREE_VISIBILITY_LIST_MAX = 100;
 
@@ -321,7 +344,10 @@ export const TREE_VISIBILITY_LIST_MAX = 100;
 /** A folder as a client login's tree shows it. */
 export type ClientTreeFolder = Omit<TreeFolder, 'share' | 'inherited' | 'system' | 'own'>;
 /** An item as a client login's tree shows it. */
-export type ClientTreeItem = Omit<TreeItem, 'level' | 'inherited' | 'state' | 'source' | 'author'>;
+export type ClientTreeItem = Omit<
+  TreeItem,
+  'level' | 'inherited' | 'embedded' | 'state' | 'source' | 'author'
+>;
 
 export type ClientTreeFolderPage = Omit<TreeFolderPage, 'folder' | 'folders' | 'items'> & {
   folder: ClientTreeFolder | null;

package/src/types/recall.ts

@@ -112,9 +112,9 @@ export interface RecallNodeDTO {
   updatedAt: string;
 }
 
-/** One card with its body — `GET /api/recall/maps/:id/cards/:cardId`, what
- *  the editor opens. Separate from the list shape on purpose (see
- *  `bodyChars`). */
+/** One card with its body, `GET /api/recall/maps/:id/cards/:slug`: what
+ *  the editor opens. A slug the card had before an explicit slug change still
+ *  finds it. Separate from the list shape on purpose (see `bodyChars`). */
 export interface RecallCardDetailDTO extends RecallNodeDTO {
   /** The markdown the owner edits, at most RECALL_BODY_CHAR_BUDGET characters
    *  (`@mantle/content-core/recall-compile`). */
@@ -179,8 +179,10 @@ export interface RecallMapCreateResultDTO {
 /** The body of every refused Recall write. `error` is a sentence written to be
  *  shown as is: what failed and what to do. `code` is stable and absent only on
  *  a malformed request (a body that failed validation). A stale `version` is
- *  409 with code `version_stale`; any code ending `_not_found` is 404; every
- *  other refusal is 400. */
+ *  409 with code `version_stale`; `map_not_found`, `card_not_found` and
+ *  `revision_not_found` are 404; every other refusal is 400, including a bad
+ *  reference inside the body (`cross_map_not_found`, `folder_not_found`) and a
+ *  revision that has nothing to put back (`revision_not_restorable`). */
 export interface RecallWriteErrorDTO {
   error: string;
   code?: string;
@@ -199,28 +201,44 @@ export interface RecallMapPatchDTO {
   version: number;
 }
 
-/** `PUT /api/recall/maps/:id/cards/:cardId` — create or replace one card.
- *  `options` replaces the card's whole list, so read-modify-write it. */
+/** A card write. `POST /api/recall/maps/:id/cards` adds one;
+ *  `PUT /api/recall/maps/:id/cards/:slug` replaces an existing one (an unknown
+ *  slug is 404, not a create).
+ *
+ *  `title` and `bodyMd` always replace. `useWhen`, `options` and `prompt` are
+ *  STICKY on a replace: leave one out and the card keeps its value. So send
+ *  `prompt` only when the owner changed the Prompt switch: a save that sends
+ *  `prompt: false` for a card with a pending request drops the request. When
+ *  `options` is sent it replaces the card's whole list: read-modify-write it. */
 export interface RecallCardWriteDTO {
   title: string;
   /** Markdown, at most RECALL_BODY_CHAR_BUDGET characters. */
   bodyMd: string;
-  /** The matcher line. Required when `prompt` is true: a prompt without one
-   *  cannot be matched by meaning, which is the only thing prompts are for. */
+  /** The matcher line. Required when the card is or asks to be a prompt: a
+   *  prompt without one cannot be matched by meaning, which is the only thing
+   *  prompts are for. */
   useWhen?: string;
-  /** Ask for this card to be a prompt. From the OWNER this makes it one; from
-   *  an agent it only records the request (`promptPending`). */
+  /** From the OWNER: true makes the card a prompt (confirming any pending
+   *  request), false makes it knowledge (demoting a prompt, or dropping a
+   *  request). From an agent, true only records a request (`promptPending`). */
   prompt?: boolean;
   options?: RecallOptionDTO[];
-  /** Slug of the card to place this one after, for a new card. */
+  /** POST only: the slug of the card to place the new one after. A slug that
+   *  names no card is refused (`after_not_found`). */
   after?: string;
+  /** PUT only, owner only: an explicit slug change. The old slug keeps
+   *  resolving (recall_go, the card GET), and options in this map that led to
+   *  it follow the card. */
+  slug?: string;
   version: number;
 }
 
 /** One advisory warning from a native write. Never blocks: an orphan card is
  *  a normal intermediate state while a map is being built. No `severity`,
  *  because a native write has only one kind of issue it reports rather than
- *  refuses. Codes today: `orphan_card`, `entry_without_options`. */
+ *  refuses. Codes today: `orphan_card`, `entry_without_options`,
+ *  `cross_map_target_gone` (an option to a map no longer published, hidden
+ *  from agents), `prompt_kept` (an agent tried to demote a prompt). */
 export interface RecallWarningDTO {
   code: string;
   message: string;
@@ -242,7 +260,13 @@ export interface RecallWriteResultDTO {
 }
 
 /** One entry in a map's revision log (`GET /api/recall/maps/:id/revisions`),
- *  newest first. Restore one with `POST /api/recall/revisions/:id/restore`. */
+ *  newest first. Restore one with `POST /api/recall/revisions/:id/restore`,
+ *  which puts back what that write replaced: a card's content (and its slug,
+ *  if that write moved it); a deleted card under its old slug, at its old
+ *  place, with the options other cards had to it; the old order for a
+ *  reorder; the map fields that write changed. Undoing "card added" deletes
+ *  the card. "map created" cannot be restored (`revision_not_restorable`), nor
+ *  can a reorder logged before its old order was kept. */
 export interface RecallRevisionDTO {
   id: string;
   /** The card this touched; null for a map-level change. */
@@ -250,9 +274,12 @@ export interface RecallRevisionDTO {
   /** The card's slug at the time, for display when the card is gone. */
   cardSlug: string | null;
   actorKind: RecallActorKind;
-  /** The agent's slug or the admin's display name, when known. */
+  /** The agent's slug, 'mcp' for an external MCP client, or the admin's
+   *  display name, stored with the revision. Null on rows written before
+   *  brain v0.232.357. */
   actorName: string | null;
-  /** One line on what changed ("body edited", "card added", "published"). */
+  /** One line on what changed: "card added", "card edited", "card deleted",
+   *  "cards reordered", "prompt confirmed", "renamed, published", and so on. */
   summary: string;
   createdAt: string;
 }