Merge pull request #290 from plotday/today-note-todayitem-field

Add Note.todayItem for reading Today-item pin context

Author: KrisBraun

.changeset/note-today-item-reference.md

@@ -0,0 +1,8 @@
+---
+"@plotday/twister": minor
+---
+
+Added: `Note.todayItem` — when a message is sent while a Today item is
+pinned as context, the note carries `{ id }` pointing at that item. Twists
+can read `note.todayItem` in a note handler to know which Today item a
+message refers to. Read-only (not settable via `NewNote`).

twister/src/plot.today-item.test-d.ts

@@ -0,0 +1,11 @@
+import { describe, expectTypeOf, it } from "vitest";
+import type { Note, NewNote } from "./plot";
+
+describe("Note.todayItem", () => {
+  it("is a required { id } | null field on Note", () => {
+    expectTypeOf<Note["todayItem"]>().toEqualTypeOf<{ id: Note["id"] } | null>();
+  });
+  it("is NOT settable on NewNote", () => {
+    expectTypeOf<NewNote>().not.toHaveProperty("todayItem");
+  });
+});

twister/src/plot.ts

@@ -732,6 +732,15 @@ export type Note = ThreadCommon & {
   actions: Array<Action> | null;
   /** The note this is a reply to, or null if not a reply */
   reNote: { id: Uuid } | null;
+  /**
+   * The Today-item context this note was composed against, via the Today
+   * thread's pin affordance (pin an item to discuss it), or null. Mutually
+   * exclusive with `reNote` and a forward snapshot — a note is at most one
+   * of a reply, a forward, or a Today-item reference. Read-only from a
+   * twist's perspective: only the Plot app sets it, when the user pins a
+   * Today item and sends a message in the Today thread.
+   */
+  todayItem: { id: Uuid } | null;
   /**
    * Contacts who can see this note, or null if the note inherits thread visibility.
    * When set (even to []), the note is private to the listed contacts plus the creator.
@@ -795,7 +804,7 @@ export type Note = ThreadCommon & {
 export type NewNote = Partial<
   Omit<
     Note,
-    "author" | "thread" | "tags" | "reactions" | "mentions" | "accessContacts" | "recipients" | "id" | "key" | "reNote" | "tagActors"
+    "author" | "thread" | "tags" | "reactions" | "mentions" | "accessContacts" | "recipients" | "id" | "key" | "reNote" | "todayItem" | "tagActors"
   >
 > &
   ({ id: Uuid } | { key: string } | {}) & {