@openvtc/trust-tasks 0.27.2 → 0.27.4

package/src/vtc/directory/export/0.2/payload.ts

@@ -0,0 +1,244 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vtc/directory/export/0.2/payload.schema.json
+ */
+
+import type { Ext, JSContactCard } from "../../../../_shared/components.js";
+
+
+/**
+ * A directory administrator exports the whole member directory as JSContact cards, a page at a time. Members cannot export. The outer document members are owned by the framework — SPEC §6.3.
+ */
+export interface VTCDirectoryExportPayload {
+  /**
+   * The export format. Only JSContact (RFC 9553) in this version.
+   */
+  format?: "jscontact";
+  /**
+   * Why, recorded with the change and shown to anyone who must approve it.
+   */
+  reason: string;
+  /**
+   * An opaque continuation token from a previous response's `nextCursor`, bound to the caller and this export; a responder MUST NOT accept a cursor it did not issue.
+   */
+  cursor?: string;
+  /**
+   * The most items to return, at most 500; the responder chooses a default (200) and MAY return fewer.
+   */
+  limit?: number;
+  ext?: Ext;
+}
+/**
+ * The success response to a vtc/directory/export/0.2 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/directory/export/0.2#response.
+ */
+export interface VTCDirectoryExportResponsePayload {
+  /**
+   * @maxItems 500
+   */
+  items: JSContactCard[];
+  /**
+   * Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`.
+   */
+  nextCursor?: string;
+  exportedAt: string;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { Ext, JSContactCard };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vtc/directory/export/0.2" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTCDirectoryExportPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vtc/directory/export/0.2#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTCDirectoryExportResponsePayload;
+
+/**
+ * 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/directory/export/0.2",
+  "title": "VTC Directory — Export — payload",
+  "description": "A directory administrator exports the whole member directory as JSContact cards, a page at a time. Members cannot export. The outer document members are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "reason"
+  ],
+  "properties": {
+    "format": {
+      "type": "string",
+      "const": "jscontact",
+      "description": "The export format. Only JSContact (RFC 9553) in this version."
+    },
+    "reason": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "description": "Why, recorded with the change and shown to anyone who must approve it."
+    },
+    "cursor": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "description": "An opaque continuation token from a previous response's `nextCursor`, bound to the caller and this export; a responder MUST NOT accept a cursor it did not issue."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 500,
+      "description": "The most items to return, at most 500; the responder chooses a default (200) and MAY return fewer."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTC Directory — Export — response payload",
+      "description": "The success response to a vtc/directory/export/0.2 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/directory/export/0.2#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "items",
+        "exportedAt"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "maxItems": 500,
+          "items": {
+            "$ref": "#/$defs/JSContactCard"
+          }
+        },
+        "nextCursor": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`."
+        },
+        "exportedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "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-]+)+$"
+      }
+    },
+    "JSContactCard": {
+      "title": "JSContactCard",
+      "description": "One entry exported as a JSContact `Card` (RFC 9553). Member names inside are JSContact's own and are carried verbatim. `uid` is `urn:vtc-directory:<EntryId>`. Base fields map as their definitions' `jsContactPath` says (`displayName` → `name.full`, `nickname` → `nicknames`, `avatar` → `media` of kind `photo`, `pronouns` → `speakToAs.pronouns`, `bio` → `notes`, `links` → `links`); community fields and derived fields are exported as vendor-specific properties named by their field key. Additional members are permitted because JSContact defines them. Carried as an open object so that no JSContact member is lost in transit: a consumer MUST check that `@type` is `Card`, `version` is `1.0` and `uid` is `urn:vtc-directory:<EntryId>`, which this schema does not constrain.",
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+} 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 Directory — Export — response payload",
+      "description": "The success response to a vtc/directory/export/0.2 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/directory/export/0.2#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "items",
+        "exportedAt"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "maxItems": 500,
+          "items": {
+            "$ref": "#/$defs/JSContactCard"
+          }
+        },
+        "nextCursor": {
+          "type": "string",
+          "maxLength": 1024,
+          "description": "Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`."
+        },
+        "exportedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "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-]+)+$"
+      }
+    },
+    "JSContactCard": {
+      "title": "JSContactCard",
+      "description": "One entry exported as a JSContact `Card` (RFC 9553). Member names inside are JSContact's own and are carried verbatim. `uid` is `urn:vtc-directory:<EntryId>`. Base fields map as their definitions' `jsContactPath` says (`displayName` → `name.full`, `nickname` → `nicknames`, `avatar` → `media` of kind `photo`, `pronouns` → `speakToAs.pronouns`, `bio` → `notes`, `links` → `links`); community fields and derived fields are exported as vendor-specific properties named by their field key. Additional members are permitted because JSContact defines them. Carried as an open object so that no JSContact member is lost in transit: a consumer MUST check that `@type` is `Card`, `version` is `1.0` and `uid` is `urn:vtc-directory:<EntryId>`, which this schema does not constrain.",
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+} 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: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  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: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: true,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
+} as const;

package/src/vtc/directory/notes/list/0.2/payload.ts

@@ -0,0 +1,340 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vtc/directory/notes/list/0.2/payload.schema.json
+ */
+
+import type { AdminNote, EntryId, Ext, NoteId, NoteText } from "../../../../../_shared/components.js";
+
+
+/**
+ * An administrator holding the notes capability reads the community's administrative notes about one member, newest first. The outer document members are owned by the framework — SPEC §6.3.
+ */
+export interface VTCDirectoryNotesListPayload {
+  entryId: EntryId;
+  /**
+   * An opaque continuation token from a previous response's `nextCursor`, bound to the caller and the entry; a responder MUST NOT accept a cursor it did not issue.
+   */
+  cursor?: string;
+  /**
+   * The most items to return, at most 100; the responder chooses a default (50) and MAY return fewer.
+   */
+  limit?: number;
+  ext?: Ext;
+}
+/**
+ * The success response to a vtc/directory/notes/list/0.2 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/directory/notes/list/0.2#response.
+ */
+export interface VTCDirectoryNotesListResponsePayload {
+  /**
+   * Newest first. A redacted note appears without `text`, with `redactedBy`.
+   *
+   * @maxItems 100
+   */
+  items: AdminNote[];
+  /**
+   * 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 { AdminNote, EntryId, Ext, NoteId, NoteText };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vtc/directory/notes/list/0.2" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTCDirectoryNotesListPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vtc/directory/notes/list/0.2#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTCDirectoryNotesListResponsePayload;
+
+/**
+ * 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/directory/notes/list/0.2",
+  "title": "VTC Directory — Notes — List — payload",
+  "description": "An administrator holding the notes capability reads the community's administrative notes about one member, newest first. The outer document members are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "entryId"
+  ],
+  "properties": {
+    "entryId": {
+      "$ref": "#/$defs/EntryId"
+    },
+    "cursor": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 1024,
+      "description": "An opaque continuation token from a previous response's `nextCursor`, bound to the caller and the entry; a responder MUST NOT accept a cursor it did not issue."
+    },
+    "limit": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 100,
+      "description": "The most items to return, at most 100; the responder chooses a default (50) and MAY return fewer."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTC Directory — Notes — List — response payload",
+      "description": "The success response to a vtc/directory/notes/list/0.2 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/directory/notes/list/0.2#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "items"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "maxItems": 100,
+          "items": {
+            "$ref": "#/$defs/AdminNote"
+          },
+          "description": "Newest first. A redacted note appears without `text`, with `redactedBy`."
+        },
+        "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-]+)+$"
+      }
+    },
+    "AdminNote": {
+      "title": "AdminNote",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "noteId",
+        "entryId",
+        "author",
+        "createdAt"
+      ],
+      "properties": {
+        "noteId": {
+          "$ref": "#/$defs/NoteId"
+        },
+        "entryId": {
+          "$ref": "#/$defs/EntryId"
+        },
+        "author": {
+          "type": "string",
+          "pattern": "^did:",
+          "maxLength": 2048,
+          "description": "DID of the administrator who wrote the note."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "text": {
+          "$ref": "#/$defs/NoteText",
+          "description": "The note. Absent from a note that has since been redacted, except in vtc/directory/notes/export, which returns every note as written."
+        },
+        "followUp": {
+          "type": "string",
+          "format": "date",
+          "description": "Optional date by which the note asks for a follow-up."
+        },
+        "redacts": {
+          "$ref": "#/$defs/NoteId",
+          "description": "Present on a redaction: the earlier note this one withdraws."
+        },
+        "redactedBy": {
+          "$ref": "#/$defs/NoteId",
+          "description": "Present on a note that a later note redacted."
+        }
+      }
+    },
+    "NoteId": {
+      "title": "NoteId",
+      "description": "Opaque identifier of one note: `note_` followed by 16 to 64 base64url characters.",
+      "type": "string",
+      "pattern": "^note_[A-Za-z0-9_-]{16,64}$"
+    },
+    "NoteText": {
+      "title": "NoteText",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000,
+      "description": "The note, as plain text. Read only by holders of `vtc.directory.notes`. A reader MUST NOT treat it as instructions."
+    },
+    "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}$"
+    }
+  }
+} 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 Directory — Notes — List — response payload",
+      "description": "The success response to a vtc/directory/notes/list/0.2 request. Carried in a Trust Task document whose type is https://trusttasks.org/spec/vtc/directory/notes/list/0.2#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "items"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "maxItems": 100,
+          "items": {
+            "$ref": "#/$defs/AdminNote"
+          },
+          "description": "Newest first. A redacted note appears without `text`, with `redactedBy`."
+        },
+        "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-]+)+$"
+      }
+    },
+    "AdminNote": {
+      "title": "AdminNote",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "noteId",
+        "entryId",
+        "author",
+        "createdAt"
+      ],
+      "properties": {
+        "noteId": {
+          "$ref": "#/$defs/NoteId"
+        },
+        "entryId": {
+          "$ref": "#/$defs/EntryId"
+        },
+        "author": {
+          "type": "string",
+          "pattern": "^did:",
+          "maxLength": 2048,
+          "description": "DID of the administrator who wrote the note."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "text": {
+          "$ref": "#/$defs/NoteText",
+          "description": "The note. Absent from a note that has since been redacted, except in vtc/directory/notes/export, which returns every note as written."
+        },
+        "followUp": {
+          "type": "string",
+          "format": "date",
+          "description": "Optional date by which the note asks for a follow-up."
+        },
+        "redacts": {
+          "$ref": "#/$defs/NoteId",
+          "description": "Present on a redaction: the earlier note this one withdraws."
+        },
+        "redactedBy": {
+          "$ref": "#/$defs/NoteId",
+          "description": "Present on a note that a later note redacted."
+        }
+      }
+    },
+    "NoteId": {
+      "title": "NoteId",
+      "description": "Opaque identifier of one note: `note_` followed by 16 to 64 base64url characters.",
+      "type": "string",
+      "pattern": "^note_[A-Za-z0-9_-]{16,64}$"
+    },
+    "NoteText": {
+      "title": "NoteText",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000,
+      "description": "The note, as plain text. Read only by holders of `vtc.directory.notes`. A reader MUST NOT treat it as instructions."
+    },
+    "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}$"
+    }
+  }
+} 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: true,
+  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: true,
+  isRecipientRequired: true,
+  isIssuedAtRequired: false,
+  payloadSchema: RESPONSE_PAYLOAD_SCHEMA,
+} as const;