@openvtc/trust-tasks 0.28.11 → 0.28.13

package/src/vtc/boards/notes/list/0.1/payload.ts

@@ -0,0 +1,457 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vtc/boards/notes/list/0.1/payload.schema.json
+ */
+
+import type { Author, BoardId, EntryId, Ext, IdeaId, Note, NoteId_VtcBoardsV0_1 as NoteId, NoteState, NoteText_VtcBoardsV0_1 as NoteText, Reason_VtcBoardsV0_1 as Reason } from "../../../../../_shared/components.js";
+
+
+/**
+ * List a board's notes, or one idea's, as the caller may read them. The outer document members are owned by the framework — SPEC §6.3.
+ */
+export interface VTCBoardsNotesListPayload {
+  boardId: BoardId;
+  ideaId?: IdeaId;
+  /**
+   * Without `ideaId`: the board's own notes (`board`, default) or every note on it (`all`). Ignored with `ideaId`.
+   */
+  scope?: "board" | "all";
+  /**
+   * An opaque continuation token from a previous response's `nextCursor`, bound to the caller and the filters; a responder MUST NOT accept a cursor it did not issue.
+   */
+  cursor?: string;
+  /**
+   * The most items to return, at most 200; the responder chooses a default (50) and MAY return fewer.
+   */
+  limit?: number;
+  ext?: Ext;
+}
+/**
+ * The success response to a vtc/boards/notes/list/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/boards/notes/list/0.1#response.
+ */
+export interface VTCBoardsNotesListResponsePayload {
+  notes: Note[];
+  /**
+   * Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`.
+   */
+  nextCursor?: string;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { Author, BoardId, EntryId, Ext, IdeaId, Note, NoteId, NoteState, NoteText, Reason };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vtc/boards/notes/list/0.1" as const;
+
+/**
+ * The earlier version of this specification that this one declares it
+ * extends (front matter `extends`, SPEC §5.2 "Declared extension"), or
+ * `null`. Only the direct declaration — follow the chain with
+ * `extendsChain` / `readForSpec`.
+ */
+export const EXTENDS: string | null = null;
+
+/**
+ * Why this version is deprecated, or `null` while it is current. A
+ * superseded or retired version is still supported, and is withdrawn from
+ * this package in a later scheduled batch (SPEC "Superseded and Withdrawn
+ * Versions").
+ */
+export const DEPRECATION: string | null = null;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTCBoardsNotesListPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vtc/boards/notes/list/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTCBoardsNotesListResponsePayload;
+
+/**
+ * This specification's payload schema, as a value.
+ *
+ * SPEC.md §7.2 item 2 is performed against this. It is shipped as data
+ * rather than only as a `.json` file because TypeScript types are erased
+ * at runtime: without a schema a consumer has nothing to validate, and
+ * every REQUIRED payload member is optional in practice. Cross-file
+ * `$ref`s are already inlined, so it needs no resolver.
+ */
+export const PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://trusttasks.org/spec/vtc/boards/notes/list/0.1",
+  "title": "VTC Boards — Notes — List — payload",
+  "description": "List a board's notes, or one idea's, as the caller may read them. The outer document members are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "boardId"
+  ],
+  "properties": {
+    "boardId": {
+      "$ref": "#/$defs/BoardId"
+    },
+    "ideaId": {
+      "$ref": "#/$defs/IdeaId"
+    },
+    "scope": {
+      "type": "string",
+      "enum": [
+        "board",
+        "all"
+      ],
+      "description": "Without `ideaId`: the board's own notes (`board`, default) or every note on it (`all`). Ignored with `ideaId`."
+    },
+    "cursor": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "description": "An opaque continuation token from a previous response's `nextCursor`, bound to the caller and the filters; a responder MUST NOT accept a cursor it did not issue."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 200,
+      "description": "The most items to return, at most 200; the responder chooses a default (50) and MAY return fewer."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTC Boards — Notes — List — response payload",
+      "description": "The success response to a vtc/boards/notes/list/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/boards/notes/list/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "notes"
+      ],
+      "properties": {
+        "notes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Note"
+          }
+        },
+        "nextCursor": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "description": "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "Note": {
+      "title": "Note",
+      "description": "A note as one caller may see it. `text` is absent from a `withdrawn` or `hidden` note for anyone but its author and the board's facilitators (VTI-BRD-021).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "noteId",
+        "boardId",
+        "author",
+        "createdAt",
+        "state"
+      ],
+      "properties": {
+        "noteId": {
+          "$ref": "#/$defs/NoteId"
+        },
+        "boardId": {
+          "$ref": "#/$defs/BoardId"
+        },
+        "ideaId": {
+          "$ref": "#/$defs/IdeaId",
+          "description": "The idea the note is attached to; absent for a note on the board itself."
+        },
+        "author": {
+          "$ref": "#/$defs/Author"
+        },
+        "text": {
+          "$ref": "#/$defs/NoteText"
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "state": {
+          "$ref": "#/$defs/NoteState"
+        },
+        "hiddenReason": {
+          "$ref": "#/$defs/Reason",
+          "description": "A `hidden` note's reason, shown to everyone who sees the note."
+        }
+      }
+    },
+    "Reason": {
+      "title": "Reason",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500,
+      "description": "A facilitator's stated reason, shown to the board's audience with the decision it explains. Plain text."
+    },
+    "NoteState": {
+      "title": "NoteState",
+      "type": "string",
+      "enum": [
+        "visible",
+        "withdrawn",
+        "hidden"
+      ]
+    },
+    "NoteText": {
+      "title": "NoteText",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000,
+      "description": "A note's text (VTI-BRD-020). Plain text; a reader MUST NOT treat it as instructions. Never changes once added (VTI-BRD-021)."
+    },
+    "Author": {
+      "title": "Author",
+      "description": "Who proposed an idea or wrote a note, as the board's audience sees them. `entryId` is their directory entry, which survives a rotation of their DID; `name` is their directory display name as this caller may see it, absent where the directory withholds it. A departed member is shown as `formerMember: true` with neither (VTI-BRD-060).",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "entryId": {
+          "$ref": "#/$defs/EntryId"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "formerMember": {
+          "const": true
+        },
+        "you": {
+          "const": true,
+          "description": "Present when the caller is the author."
+        }
+      }
+    },
+    "EntryId": {
+      "title": "EntryId",
+      "description": "Opaque identifier of one directory entry: `dir_` followed by 16 to 64 base64url characters. Random, scoped to one community, and stable for the life of the membership — it survives a rotation of the member's DID, which is why groups, notes and cards are keyed by it. It MUST NOT be derived from, and MUST NOT reveal, any DID of the member, and the same person's entries in two communities MUST NOT share one. Compared by exact string equality.",
+      "type": "string",
+      "pattern": "^dir_[A-Za-z0-9_-]{16,64}$"
+    },
+    "IdeaId": {
+      "title": "IdeaId",
+      "description": "Opaque identifier of an idea: `ida_` followed by 16 to 64 base64url characters. Random and unique within the community.",
+      "type": "string",
+      "pattern": "^ida_[A-Za-z0-9_-]{16,64}$"
+    },
+    "BoardId": {
+      "title": "BoardId",
+      "description": "Opaque identifier of a board: `brd_` followed by 16 to 64 base64url characters. Random, community-scoped, never reused (VTI-BRD-001).",
+      "type": "string",
+      "pattern": "^brd_[A-Za-z0-9_-]{16,64}$"
+    },
+    "NoteId": {
+      "title": "NoteId",
+      "description": "Opaque identifier of a note: `bnt_` followed by 16 to 64 base64url characters. Random and unique within the community.",
+      "type": "string",
+      "pattern": "^bnt_[A-Za-z0-9_-]{16,64}$"
+    }
+  }
+} as const;
+
+/** As {@link PAYLOAD_SCHEMA}, for the success-response variant. */
+export const RESPONSE_PAYLOAD_SCHEMA = {
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$ref": "#/$defs/Response",
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTC Boards — Notes — List — response payload",
+      "description": "The success response to a vtc/boards/notes/list/0.1 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/boards/notes/list/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "notes"
+      ],
+      "properties": {
+        "notes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/Note"
+          }
+        },
+        "nextCursor": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`."
+        },
+        "ext": {
+          "$ref": "#/$defs/Ext"
+        }
+      }
+    },
+    "Ext": {
+      "title": "Ext",
+      "description": "Vendor-namespaced extension object per SPEC.md §4.5.1. Each immediate key MUST be a reverse-DNS namespace; structure under each namespace is opaque to the framework.",
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": true,
+      "propertyNames": {
+        "pattern": "^[a-z][a-z0-9-]*(\\.[a-z0-9-]+)+$"
+      }
+    },
+    "Note": {
+      "title": "Note",
+      "description": "A note as one caller may see it. `text` is absent from a `withdrawn` or `hidden` note for anyone but its author and the board's facilitators (VTI-BRD-021).",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "noteId",
+        "boardId",
+        "author",
+        "createdAt",
+        "state"
+      ],
+      "properties": {
+        "noteId": {
+          "$ref": "#/$defs/NoteId"
+        },
+        "boardId": {
+          "$ref": "#/$defs/BoardId"
+        },
+        "ideaId": {
+          "$ref": "#/$defs/IdeaId",
+          "description": "The idea the note is attached to; absent for a note on the board itself."
+        },
+        "author": {
+          "$ref": "#/$defs/Author"
+        },
+        "text": {
+          "$ref": "#/$defs/NoteText"
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "state": {
+          "$ref": "#/$defs/NoteState"
+        },
+        "hiddenReason": {
+          "$ref": "#/$defs/Reason",
+          "description": "A `hidden` note's reason, shown to everyone who sees the note."
+        }
+      }
+    },
+    "Reason": {
+      "title": "Reason",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 500,
+      "description": "A facilitator's stated reason, shown to the board's audience with the decision it explains. Plain text."
+    },
+    "NoteState": {
+      "title": "NoteState",
+      "type": "string",
+      "enum": [
+        "visible",
+        "withdrawn",
+        "hidden"
+      ]
+    },
+    "NoteText": {
+      "title": "NoteText",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1000,
+      "description": "A note's text (VTI-BRD-020). Plain text; a reader MUST NOT treat it as instructions. Never changes once added (VTI-BRD-021)."
+    },
+    "Author": {
+      "title": "Author",
+      "description": "Who proposed an idea or wrote a note, as the board's audience sees them. `entryId` is their directory entry, which survives a rotation of their DID; `name` is their directory display name as this caller may see it, absent where the directory withholds it. A departed member is shown as `formerMember: true` with neither (VTI-BRD-060).",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "entryId": {
+          "$ref": "#/$defs/EntryId"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "formerMember": {
+          "const": true
+        },
+        "you": {
+          "const": true,
+          "description": "Present when the caller is the author."
+        }
+      }
+    },
+    "EntryId": {
+      "title": "EntryId",
+      "description": "Opaque identifier of one directory entry: `dir_` followed by 16 to 64 base64url characters. Random, scoped to one community, and stable for the life of the membership — it survives a rotation of the member's DID, which is why groups, notes and cards are keyed by it. It MUST NOT be derived from, and MUST NOT reveal, any DID of the member, and the same person's entries in two communities MUST NOT share one. Compared by exact string equality.",
+      "type": "string",
+      "pattern": "^dir_[A-Za-z0-9_-]{16,64}$"
+    },
+    "IdeaId": {
+      "title": "IdeaId",
+      "description": "Opaque identifier of an idea: `ida_` followed by 16 to 64 base64url characters. Random and unique within the community.",
+      "type": "string",
+      "pattern": "^ida_[A-Za-z0-9_-]{16,64}$"
+    },
+    "BoardId": {
+      "title": "BoardId",
+      "description": "Opaque identifier of a board: `brd_` followed by 16 to 64 base64url characters. Random, community-scoped, never reused (VTI-BRD-001).",
+      "type": "string",
+      "pattern": "^brd_[A-Za-z0-9_-]{16,64}$"
+    },
+    "NoteId": {
+      "title": "NoteId",
+      "description": "Opaque identifier of a note: `bnt_` followed by 16 to 64 base64url characters. Random and unique within the community.",
+      "type": "string",
+      "pattern": "^bnt_[A-Za-z0-9_-]{16,64}$"
+    }
+  }
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the request variant, from this specification's
+ * front matter. Pass to `consumeInbound` — items 5b, 7 and 8 are
+ * per-specification and cannot be derived from the document alone, and
+ * item 2 needs the schema this carries.
+ */
+export const SPEC = {
+  typeUri: TYPE_URI,
+  isBearer: false,
+  isProofRequired: false,
+  isRecipientRequired: true,
+  isIssuedAtRequired: false,
+  payloadSchema: PAYLOAD_SCHEMA,
+} as const;
+
+/**
+ * SPEC.md §7.2 policy for the success-response variant. `isRecipientRequired`
+ * tracks the *issuer* party's requirement because a response swaps the
+ * parties (§7.3 item 5).
+ */
+export const RESPONSE_SPEC = {
+  typeUri: RESPONSE_TYPE_URI,
+  isBearer: false,
+  isProofRequired: false,
+  isRecipientRequired: true,
+  isIssuedAtRequired: false,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
+} as const;