@crossworks/client-types 0.232.338 → 0.232.343

package/package.json

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

package/src/dto/client.ts

@@ -5,7 +5,9 @@
  * client level only (the brain enforces it with row security). Client DTOs
  * never carry a staff name or an author: clients see the brand name.
  */
-import type { MemberItemKind } from '../member-kinds';
+import type { ClientItemKind, MemberItemKind } from '../member-kinds';
+import type { MemberItemPill, MemberSpaceItemRow } from './member';
+import type { NodeComment } from './rows';
 
 /** GET /api/client/shell: who is signed in and the brain's brand. */
 export type ClientShell = {
@@ -265,3 +267,182 @@ export type ClientChatUsage = {
   limits: { dailyTurns: number; dailyTokens: number };
   rows: { loginId: string; turnsToday: number; tokensToday: number }[];
 };
+
+// ── The client's own items, My requests (client logins C5) ─────────────────
+
+/**
+ * Where a row of My requests comes from: `own` an item in the client's own
+ * space (GET /api/client/space/:id; a draft, submitted, returned, or with a
+ * reviewer who took it over), `accepted` the version the client wrote and an
+ * admin accepted (GET /api/client/accepted/:id).
+ */
+export type ClientItemSource = 'own' | 'accepted';
+
+/** One row of GET /api/client/items. No level, no staff name. */
+export type ClientItemRow = {
+  id: string;
+  type: ClientItemKind;
+  title: string;
+  icon: string | null;
+  updatedAt: string;
+  source: ClientItemSource;
+  /** `private` a draft, `submitted`, `returned`, `with-admin`; null on an
+   *  accepted row. Never `draft` (a client never shares with the team). */
+  pill: MemberItemPill | null;
+  /** The space row of an own item (review state, the returned note). */
+  space: MemberSpaceItemRow | null;
+  acceptedAt: string | null;
+};
+
+/** GET /api/client/items?kind=&q=&state=&page=: the client's own items and
+ *  their accepted items in ONE list, newest first. `state` is a
+ *  ClientItemFilter (default `all`). */
+export type ClientItemsPage = {
+  items: ClientItemRow[];
+  total: number;
+  page: number;
+  pageSize: number;
+};
+
+/**
+ * The client's own space (/api/client/space*, /api/client/space-files): the
+ * member space routes' shapes (MemberSpaceItem, MemberSpaceItemRow,
+ * MemberSpaceList) for kinds page, note and file only. No share route: a
+ * client's item is private until submitted, and a submitted item goes to the
+ * reviewers (and members read it as a client request). Refusals (the 409
+ * `reason`): the member ones, plus `quota` for the client caps: 20 MB a file,
+ * 200 MB a client, 50 MB uploaded a day, 500 items, 10 submissions a day, 50
+ * waiting for review, and one total for all client spaces of the brain. The
+ * 200 MB and the total count page and note text too (C5 audit). A page
+ * document over 500 KB serialized (draft or Save version), or a note over
+ * 50,000 characters, is a 400 `too-large`. The comment caps:
+ * ClientCommentRefusedReason. Any JSON body over the route's ceiling (8 MB)
+ * is a 413 `body-too-large`.
+ */
+export type ClientSpaceRefusedReason =
+  | 'not-found'
+  | 'frozen'
+  | 'not-draft'
+  | 'not-submitted'
+  | 'unsaved-draft'
+  | 'quota'
+  | 'embed'
+  | 'not-shared'
+  | 'too-large'
+  | 'invalid'
+  | 'with-admin';
+
+/** GET /api/client/accepted/:id -> { item }: the version the client wrote
+ *  and an admin accepted (the snapshot taken at Accept, never the brain's
+ *  current version). A file's bytes: /api/client/files/:id while the brain
+ *  file still holds the bytes accepted (`changedByAdmin` otherwise). */
+export type ClientAcceptedItem =
+  | (ClientAcceptedBase & { type: 'page'; doc: unknown })
+  | (ClientAcceptedBase & { type: 'note'; content: string })
+  | (ClientAcceptedBase & {
+      type: 'file';
+      filename: string;
+      mimeType: string | null;
+      sizeBytes: number | null;
+      changedByAdmin?: boolean;
+    });
+
+export type ClientAcceptedBase = {
+  id: string;
+  title: string;
+  icon: string | null;
+  acceptedAt: string | null;
+  updatedAt: string;
+};
+
+// ── Comments (client logins C5, decision 8) ─────────────────────────────────
+
+/**
+ * GET /api/client/shared/:id/comments (POST { body } -> 201 { comment },
+ * DELETE /comments/:commentId for the client's own): the thread on an item
+ * shared with clients. The team, admins and every client login read and
+ * write it; each comment shows its author's display name (clients are
+ * approved users). Only on an item at client level: any other id is a 404.
+ *
+ * GET /api/client/space/:id/comments (POST, DELETE own) on the client's own
+ * item: the review talk with the reviewers, open while it is submitted. A
+ * reviewer's comment shows the brand name, never a staff name.
+ */
+export type ClientCommentThread = {
+  comments: NodeComment[];
+  /**
+   * Older comments exist (client logins C5 audit): a thread answers its
+   * NEWEST 100 comments, oldest first; `?before=<createdAt of the oldest
+   * shown>` answers the 100 before them. The same paging and `hasMore` on
+   * GET /api/member/library/:id/comments, /api/member/space/:id/comments,
+   * /api/team-admin/submissions/:id/comments and /api/nodes/:id/comments.
+   * Absent on an older brain (the whole thread).
+   */
+  hasMore?: boolean;
+};
+
+/**
+ * Why a comment was refused (the 4xx `reason`, client logins C5 audit): 429
+ * `comment-cap` (a client login writes at most 100 comments a day across
+ * every thread, the review talk and client threads; deleting one does not
+ * give it back), 409 `thread-full` (one thread holds at most 1000
+ * comments).
+ */
+export type ClientCommentRefusedReason = 'comment-cap' | 'thread-full';
+
+// ── Team admin > Clients: storage and client threads (C5 audit) ────────────
+
+/**
+ * GET /api/team-admin/clients/storage (admin only): what the client spaces
+ * hold against the client limits. A client space counts files, page
+ * documents (saved, draft and plain text) and note text, as stored.
+ * `limits.totalBytes` is the brain-wide total for ALL client spaces (5 GB
+ * unless the box sets MANTLE_CLIENT_SPACES_TOTAL_BYTES). A `former` row is a
+ * deleted client's space: it still counts until its 30-day purge, and its
+ * `loginId` is the space's id (the login row is gone).
+ */
+export type ClientStorageUsage = {
+  limits: {
+    fileMaxBytes: number;
+    perClientBytes: number;
+    dailyUploadBytes: number;
+    itemLimit: number;
+    totalBytes: number;
+    submitsPerDay: number;
+    openSubmissions: number;
+  };
+  totalUsedBytes: number;
+  rows: {
+    loginId: string;
+    name: string;
+    usedBytes: number;
+    uploadedTodayBytes: number;
+    items: number;
+    openSubmissions: number;
+    former: boolean;
+  }[];
+  /** Quota refusals in the last 7 days, newest first, at most 50. */
+  refusals: { at: string; loginId: string | null; reason: string }[];
+};
+
+/**
+ * GET /api/team-admin/clients/comments?days=7 (admin only, 1 to 90 days):
+ * the client-level items whose client thread had a comment by a CLIENT in
+ * the window, newest first, at most 100. `clientComments` counts the
+ * clients' comments in the window; `lastClientName` is the newest one's
+ * author. Open the thread on /api/nodes/:id/comments.
+ */
+export type ClientThreadActivity = {
+  rows: {
+    nodeId: string;
+    title: string;
+    type: string;
+    lastCommentAt: string;
+    clientComments: number;
+    lastClientName: string;
+  }[];
+};
+
+/** DELETE /api/team-admin/clients/:id/comments (admin only): every comment
+ *  that client login wrote (client threads and review talk) is removed. */
+export type ClientCommentsDeleted = { deleted: number };

package/src/dto/member.ts

@@ -256,8 +256,11 @@ export type MemberAcceptedItem =
 /** Where a row of the one list comes from; it picks the item view that
  *  opens it: `own` the member's editor, `team` a teammate's saved draft,
  *  `library` the brain item, `accepted` the version this member wrote and an
- *  admin accepted at a level above the Library's (admin or public). */
-export type MemberItemSource = 'own' | 'team' | 'library' | 'accepted';
+ *  admin accepted at a level above the Library's (admin or public),
+ *  `client-request` a client's SUBMITTED item (client logins C5, decision
+ *  5 B), read only from /api/member/client-requests/:id; its `space` row
+ *  carries the review state, its `author` the client (role `client`). */
+export type MemberItemSource = 'own' | 'team' | 'library' | 'accepted' | 'client-request';
 
 /** The small state pill a row wears beside its actions. Brain items (the
  *  Library and accepted rows) wear none. */
@@ -284,6 +287,14 @@ export type MemberItemRow = {
   space: MemberSpaceItemRow | null;
 };
 
+/** GET /api/member/client-requests/:id (client logins C5, decision 5 B): a
+ *  client's SUBMITTED item, read only, with its author (the client). File
+ *  bytes: /api/member/client-requests/:id/bytes. */
+export type MemberClientRequestItem<TDoc = unknown, TTable = unknown> = MemberSpaceItem<
+  TDoc,
+  TTable
+> & { author: MemberItemAuthor };
+
 /**
  * GET /api/member/items?kind=&q=&state=&page= (brains from the item-list
  * alignment release): the member's own items, teammates' shared drafts, the

package/src/dto/rows.ts

@@ -50,7 +50,7 @@ export type TaskTodo = {
 };
 
 /** Mirrors @mantle/db `NodeCommentAuthorKind`. */
-export type NodeCommentAuthorKind = 'owner' | 'member' | 'agent';
+export type NodeCommentAuthorKind = 'owner' | 'member' | 'agent' | 'client';
 
 /**
  * A comment on a node (tasks first; the table is node-generic). `authorName`

package/src/index.ts

@@ -86,6 +86,7 @@ export type {
   MemberSpaceItem,
   MemberSpaceItemBody,
   MemberSpaceItemRow,
+  MemberClientRequestItem,
   MemberSpaceItemState,
   MemberSpaceList,
   MemberSpaceSharing,
@@ -109,7 +110,7 @@ export type {
   MemberInviteRow,
   MemberInviteState,
 } from './dto/member-invites';
-export type { MemberItemKind } from './member-kinds';
+export type { MemberItemKind, ClientItemKind, ClientItemFilter } from './member-kinds';
 export type {
   LoginKind,
   LoginRefused,
@@ -143,6 +144,17 @@ export type {
   ClientShell,
   ClientSigninLinkCreated,
   ClientSigninLinkRow,
+  ClientItemSource,
+  ClientItemRow,
+  ClientItemsPage,
+  ClientSpaceRefusedReason,
+  ClientAcceptedItem,
+  ClientAcceptedBase,
+  ClientCommentThread,
+  ClientCommentRefusedReason,
+  ClientStorageUsage,
+  ClientThreadActivity,
+  ClientCommentsDeleted,
 } from './dto/client';
 
 // Types only at the root; the runtime constants (APP_TINTS, limits) are the

package/src/member-kinds.ts

@@ -25,6 +25,8 @@ export const MEMBER_ITEM_FILTERS = [
   'with-admin',
   'brain',
   'by-me',
+  // A client's submitted items (client logins C5, decision 5 B): read only.
+  'client-requests',
 ] as const;
 export type MemberItemFilter = (typeof MEMBER_ITEM_FILTERS)[number];
 
@@ -44,3 +46,30 @@ export function adminListStateOf(v: unknown): AdminListState {
     ? (v as AdminListState)
     : 'brain';
 }
+
+/** The kinds a CLIENT works with in their own space (client logins C5, plan
+ *  section 6): pages and notes they write, files they upload. */
+export const CLIENT_ITEM_KINDS = ['page', 'note', 'file'] as const;
+export type ClientItemKind = (typeof CLIENT_ITEM_KINDS)[number];
+
+export function isClientItemKind(v: unknown): v is ClientItemKind {
+  return typeof v === 'string' && (CLIENT_ITEM_KINDS as readonly string[]).includes(v);
+}
+
+/** The State filter of a client's one list, My requests (GET
+ *  /api/client/items?state=): `all`, one row pill (`private` a draft,
+ *  `submitted`, `returned`, `with-admin` an item a reviewer took over to
+ *  work on), or `accepted`. */
+export const CLIENT_ITEM_FILTERS = [
+  'all',
+  'private',
+  'submitted',
+  'returned',
+  'with-admin',
+  'accepted',
+] as const;
+export type ClientItemFilter = (typeof CLIENT_ITEM_FILTERS)[number];
+
+export function isClientItemFilter(v: unknown): v is ClientItemFilter {
+  return typeof v === 'string' && (CLIENT_ITEM_FILTERS as readonly string[]).includes(v);
+}