@anchrd/intel-contract 0.24.0 → 0.26.0

package/dist/contract/board.d.ts

@@ -107,3 +107,28 @@ export declare const BoardTaskUpdateInput: z.ZodObject<{
     idempotencyKey: z.ZodString;
 }, z.core.$strict>;
 export type BoardTaskUpdateInput = z.infer<typeof BoardTaskUpdateInput>;
+export declare const BoardAssignee: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    email: z.ZodEmail;
+    isMachine: z.ZodBoolean;
+}, z.core.$strict>;
+export type BoardAssignee = z.infer<typeof BoardAssignee>;
+export declare const BoardAssigneeSearchInput: z.ZodObject<{
+    boardId: z.ZodString;
+    query: z.ZodString;
+}, z.core.$strict>;
+export type BoardAssigneeSearchInput = z.infer<typeof BoardAssigneeSearchInput>;
+export declare const BoardAssigneeResolveInput: z.ZodObject<{
+    ids: z.ZodArray<z.ZodString>;
+}, z.core.$strict>;
+export type BoardAssigneeResolveInput = z.infer<typeof BoardAssigneeResolveInput>;
+export declare const BoardAssigneeList: z.ZodObject<{
+    items: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        email: z.ZodEmail;
+        isMachine: z.ZodBoolean;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type BoardAssigneeList = z.infer<typeof BoardAssigneeList>;

package/dist/contract/board.js

@@ -188,3 +188,39 @@ export const BoardTaskUpdateInput = z.strictObject({
         .describe("A node this card waits for. `null` clears the dependency."),
     idempotencyKey: IdempotencyKey,
 });
+// ── Who a card can be given to ────────────────────────────────────────────────────────────────
+// D70 (`~/Dev/anchrd/core/DECISIONS.md`): the people offered here are the ones who can actually open
+// THIS board, never everyone who holds an account. The narrower answer is the point, and it is what
+// makes the door safe to offer to anyone who can see the board.
+//
+// ⚠️ `email` travels because two colleagues share a first name more often than a picker can afford,
+// and a list of indistinguishable "Anton" rows is not a picker. It is no wider than what gate hands
+// any signed-in person at `POST /directory/search`; the narrowing this door adds is WHO appears,
+// not WHAT is said about them.
+//
+// `isMachine` travels for the same reason gate carries it: whoever picks an assignee wants to know
+// whether they are handing the card to a colleague or to an agent.
+export const BoardAssignee = z.strictObject({
+    id: IntelId,
+    name: z.string(),
+    email: z.email(),
+    isMachine: z.boolean(),
+});
+export const BoardAssigneeSearchInput = z.strictObject({
+    boardId: IntelId.describe("The board whose people to offer. Only those who can open this board appear, so the same query against two boards can give two different answers."),
+    query: z
+        .string()
+        .describe("What was typed. Under two characters the answer is empty rather than everybody: a single letter is a listing under a different name."),
+});
+// ⚠️ A DIFFERENT question from the one above, and deliberately not board-scoped. This one names
+// people who are ALREADY recorded on a card, so that a circle can carry initials instead of a raw
+// id (`#258`). Someone whose access was withdrawn, or whose account was switched off, still has to
+// be nameable: a card that reads as unassigned is a worse answer than the truth.
+export const BoardAssigneeResolveInput = z.strictObject({
+    ids: z
+        .array(IntelId)
+        .min(1)
+        .max(100)
+        .describe("The ids to name. Ids that cannot be named are absent from the answer rather than reported, and more than a hundred is refused rather than silently shortened."),
+});
+export const BoardAssigneeList = z.strictObject({ items: z.array(BoardAssignee) });

package/dist/contract/feed.d.ts

@@ -0,0 +1,70 @@
+import { z } from "zod";
+export declare const FeedAction: z.ZodEnum<{
+    "node.create": "node.create";
+    "node.save": "node.save";
+    "node.update": "node.update";
+    "node.append": "node.append";
+    "node.archive": "node.archive";
+    "node.share": "node.share";
+    "node.revoke": "node.revoke";
+}>;
+export type FeedAction = z.infer<typeof FeedAction>;
+export declare const FeedPathSegment: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+}, z.core.$strict>;
+export type FeedPathSegment = z.infer<typeof FeedPathSegment>;
+export declare const FeedEvent: z.ZodObject<{
+    id: z.ZodString;
+    actorId: z.ZodString;
+    action: z.ZodEnum<{
+        "node.create": "node.create";
+        "node.save": "node.save";
+        "node.update": "node.update";
+        "node.append": "node.append";
+        "node.archive": "node.archive";
+        "node.share": "node.share";
+        "node.revoke": "node.revoke";
+    }>;
+    nodeId: z.ZodString;
+    nodeTitle: z.ZodString;
+    path: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+    }, z.core.$strict>>;
+    metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    occurredAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type FeedEvent = z.infer<typeof FeedEvent>;
+export declare const FeedCursor: z.ZodString;
+export declare const FeedListRequest: z.ZodObject<{
+    actor: z.ZodOptional<z.ZodString>;
+    before: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strict>;
+export type FeedListRequest = z.infer<typeof FeedListRequest>;
+export declare const FeedListResponse: z.ZodObject<{
+    events: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        actorId: z.ZodString;
+        action: z.ZodEnum<{
+            "node.create": "node.create";
+            "node.save": "node.save";
+            "node.update": "node.update";
+            "node.append": "node.append";
+            "node.archive": "node.archive";
+            "node.share": "node.share";
+            "node.revoke": "node.revoke";
+        }>;
+        nodeId: z.ZodString;
+        nodeTitle: z.ZodString;
+        path: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            title: z.ZodString;
+        }, z.core.$strict>>;
+        metadata: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        occurredAt: z.ZodISODateTime;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+export type FeedListResponse = z.infer<typeof FeedListResponse>;

package/dist/contract/feed.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { IntelId, IsoDateTime } from "./contract.js";
+// What a person did, in the words a person would use. This is a POSITIVE LIST and not the set of
+// actions the journal carries (#740).
+//
+// ⚠️ Two omissions are the point of the list, not an oversight. `node.version` is written by the
+// same batch as `node.save`, so admitting both would show every edit twice — and because this feed
+// does not group anything yet, twice means two cards. `node.link` and `node.import` are machine
+// traces of a save rather than something anybody did.
+//
+// ⚠️ And it stays a positive list. "Everything except" would silently admit whatever the next
+// migration starts writing, on a surface whose whole job is to be readable.
+export const FeedAction = z.enum([
+    "node.create",
+    "node.save",
+    "node.update",
+    "node.append",
+    "node.archive",
+    "node.share",
+    "node.revoke",
+]);
+// One step on the way down to the node, from the root. It carries the id as well as the title
+// because the surface links each step, and two folders may share a name.
+export const FeedPathSegment = z.strictObject({
+    id: IntelId,
+    title: z.string().min(1),
+});
+// One card's worth of journal.
+//
+// ⚠️ `nodeTitle` and `path` are read from `nodes` at query time, so they are TODAY's title and
+// today's place — not the ones the node had when the event happened. That is the right answer for a
+// feed (the reader wants to find the thing now) and the wrong one for an audit trail, which is one
+// more reason these are two doors and not one.
+//
+// `metadata` is whatever the write site recorded, untyped on purpose: a schema per action would
+// have to be kept in step with eleven write sites and would go stale in silence. What the surface
+// needs from it today is `sequence` on a `node.save`, which is the version number behind the card's
+// button.
+export const FeedEvent = z.strictObject({
+    id: IntelId,
+    actorId: z.string().min(1),
+    action: FeedAction,
+    nodeId: IntelId,
+    nodeTitle: z.string().min(1),
+    path: z.array(FeedPathSegment),
+    metadata: z.record(z.string(), z.unknown()),
+    occurredAt: IsoDateTime,
+});
+// ⚠️ Opaque BY CONTRACT, like the audit cursor and for the same reason: it is a PAIR
+// (`occurredAt`, `id`), and a timestamp alone cannot separate two events written in the same
+// millisecond — the normal case inside one batch. A reader continuing on the timestamp alone skips
+// the second one with no error and no log.
+//
+// ⚠️ It is deliberately NOT interchangeable with an audit cursor, although both encode the same
+// pair. The two doors walk the journal in opposite directions, so handing one's position to the
+// other reads on from the wrong end — and would look like a feed that suddenly starts at the
+// beginning of time rather than like a mistake. The encoding therefore carries its own marker and
+// the other door's cursor is refused.
+export const FeedCursor = z.string().min(1).max(400);
+export const FeedListRequest = z.strictObject({
+    actor: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Show only what this person or agent did. Omit it for everybody whose work you may see anyway."),
+    before: FeedCursor.optional().describe("Where to continue: the `nextCursor` of a previous answer, passed back unchanged. Omit it to start at the most recent event. Do not build one — it is opaque on purpose, and a cursor from `audit_list` is refused rather than followed backwards."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .default(30)
+        .describe("How many events to return at most. The answer may be shorter."),
+});
+// `nextCursor` is present exactly when another page may exist, and it is the cursor of the LAST
+// returned row.
+//
+// ⚠️ Present does not promise the next page is non-empty: the rows a reader may see can shrink
+// between calls. Treating "cursor present" as "there is more" is fair; treating an empty answer as
+// "you have reached the beginning of the journal" is not.
+export const FeedListResponse = z.strictObject({
+    events: z.array(FeedEvent),
+    nextCursor: FeedCursor.nullable(),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anchrd/intel-contract",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "type": "module",
   "license": "UNLICENSED",
   "repository": {
@@ -28,6 +28,10 @@
       "types": "./dist/contract/bundle.d.ts",
       "default": "./dist/contract/bundle.js"
     },
+    "./feed": {
+      "types": "./dist/contract/feed.d.ts",
+      "default": "./dist/contract/feed.js"
+    },
     "./flow": {
       "types": "./dist/contract/flow.d.ts",
       "default": "./dist/contract/flow.js"