@openvtc/trust-tasks 0.27.3 → 0.27.4

package/src/persona/contact/lists/put/1.1/payload.ts

@@ -0,0 +1,429 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/persona/contact/lists/put/1.1/payload.schema.json
+ */
+
+import type { ContactList, Ext, ListColour, ListId, ListName, ListOrder } from "../../../../../_shared/components.js";
+
+
+/**
+ * Create one of the holder's contact lists, or rename, recolour or reorder an existing one. Without `listId`: create, and `name` is required. With `listId`: update; each detail given replaces the stored one, `removeColour` removes the colour, and each detail absent is unchanged. Membership is not changed here — a contact's lists are set with persona/contact/put 1.1. The outer document members are owned by the framework — SPEC §6.3.
+ */
+export type PersonaContactListsPutPayload = {
+  contextId: string;
+  /**
+   * The list to update. Absent: create a new list, whose identifier the agent assigns and returns.
+   */
+  listId?: ListId;
+  /**
+   * The list's name. Required to create; on an update, replaces the name. Unique within the context.
+   */
+  name?: ListName;
+  /**
+   * The list's colour, replacing any it had. Absent: unchanged (none, on a create).
+   */
+  colour?: ListColour;
+  /**
+   * Remove the list's colour. Update only. Only `true` is accepted.
+   */
+  removeColour?: true;
+  /**
+   * Where the list sorts among the holder's lists. Absent on a create: after every existing list.
+   */
+  order?: ListOrder;
+  ext?: Ext;
+} & {
+  [k: string]: unknown | undefined;
+};
+
+/**
+ * Success response to persona/contact/lists/put. Type https://trusttasks.org/spec/persona/contact/lists/put/1.1#response. The list as it now stands.
+ */
+export interface PersonaContactListsPutResponsePayload {
+  list: ContactList;
+  /**
+   * True when this request created the list.
+   */
+  wasCreated: boolean;
+  /**
+   * True when this request created the list or changed any detail of it. False when every detail given already matched.
+   */
+  changed: boolean;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { ContactList, Ext, ListColour, ListId, ListName, ListOrder };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/persona/contact/lists/put/1.1" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = PersonaContactListsPutPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/persona/contact/lists/put/1.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = PersonaContactListsPutResponsePayload;
+
+/**
+ * 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/persona/contact/lists/put/1.1",
+  "title": "Persona Contact Lists Put — payload",
+  "description": "Create one of the holder's contact lists, or rename, recolour or reorder an existing one. Without `listId`: create, and `name` is required. With `listId`: update; each detail given replaces the stored one, `removeColour` removes the colour, and each detail absent is unchanged. Membership is not changed here — a contact's lists are set with persona/contact/put 1.1. The outer document members are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contextId"
+  ],
+  "oneOf": [
+    {
+      "required": [
+        "name"
+      ],
+      "not": {
+        "anyOf": [
+          {
+            "required": [
+              "listId"
+            ]
+          },
+          {
+            "required": [
+              "removeColour"
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "required": [
+        "listId"
+      ],
+      "anyOf": [
+        {
+          "required": [
+            "name"
+          ]
+        },
+        {
+          "required": [
+            "colour"
+          ]
+        },
+        {
+          "required": [
+            "removeColour"
+          ]
+        },
+        {
+          "required": [
+            "order"
+          ]
+        }
+      ]
+    }
+  ],
+  "dependentSchemas": {
+    "removeColour": {
+      "not": {
+        "required": [
+          "colour"
+        ]
+      }
+    }
+  },
+  "properties": {
+    "contextId": {
+      "type": "string",
+      "minLength": 1
+    },
+    "listId": {
+      "$ref": "#/$defs/ListId",
+      "description": "The list to update. Absent: create a new list, whose identifier the agent assigns and returns."
+    },
+    "name": {
+      "$ref": "#/$defs/ListName",
+      "description": "The list's name. Required to create; on an update, replaces the name. Unique within the context."
+    },
+    "colour": {
+      "$ref": "#/$defs/ListColour",
+      "description": "The list's colour, replacing any it had. Absent: unchanged (none, on a create)."
+    },
+    "removeColour": {
+      "type": "boolean",
+      "const": true,
+      "description": "Remove the list's colour. Update only. Only `true` is accepted."
+    },
+    "order": {
+      "$ref": "#/$defs/ListOrder",
+      "description": "Where the list sorts among the holder's lists. Absent on a create: after every existing list."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "Persona Contact Lists Put — response payload",
+      "description": "Success response to persona/contact/lists/put. Type https://trusttasks.org/spec/persona/contact/lists/put/1.1#response. The list as it now stands.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "list",
+        "wasCreated",
+        "changed"
+      ],
+      "properties": {
+        "list": {
+          "$ref": "#/$defs/ContactList"
+        },
+        "wasCreated": {
+          "type": "boolean",
+          "description": "True when this request created the list."
+        },
+        "changed": {
+          "type": "boolean",
+          "description": "True when this request created the list or changed any detail of it. False when every detail given already matched."
+        },
+        "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-]+)+$"
+      }
+    },
+    "ContactList": {
+      "title": "ContactList",
+      "description": "One of the holder's lists, as their agent keeps it. A list is context-scoped, like the contacts it holds: it may hold contacts known by any persona in its context, and contacts from any number of communities, but never a contact of another context.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "listId",
+        "name",
+        "order",
+        "contactCount",
+        "createdAt",
+        "updatedAt"
+      ],
+      "properties": {
+        "listId": {
+          "$ref": "#/$defs/ListId"
+        },
+        "name": {
+          "$ref": "#/$defs/ListName"
+        },
+        "colour": {
+          "$ref": "#/$defs/ListColour"
+        },
+        "order": {
+          "$ref": "#/$defs/ListOrder"
+        },
+        "contactCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many of the context's contacts are on the list now."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the list's name, colour or order last changed. Adding a contact to the list or removing one does not move it."
+        }
+      }
+    },
+    "ListOrder": {
+      "title": "ListOrder",
+      "description": "Where the holder wants a list among their lists: ascending, ties broken by `name`. A sort key, not a position, so moving one list does not renumber the others; gaps are expected.",
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 1000000
+    },
+    "ListColour": {
+      "title": "ListColour",
+      "description": "A colour the holder picked for a list, as a six-digit lowercase sRGB hex value (`#1f8a70`). A rendering hint: a consumer MAY map it to the nearest colour of its own palette that keeps contrast in light and dark themes, and MUST NOT rely on colour alone to tell lists apart.",
+      "type": "string",
+      "pattern": "^#[0-9a-f]{6}$"
+    },
+    "ListName": {
+      "title": "ListName",
+      "description": "The holder's name for one of their lists (\"Mentors\", \"Met at the spring meetup\"), on one line: no control characters. Unique within a context, compared exactly.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+    },
+    "ListId": {
+      "title": "ListId",
+      "description": "Identifier of one of the holder's contact lists: a ULID in Crockford base32, uppercase, assigned by the agent when the list is created. Meaningful only inside the context that holds the list; it is never sent to anyone but the holder's own clients.",
+      "type": "string",
+      "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
+    }
+  }
+} 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": "Persona Contact Lists Put — response payload",
+      "description": "Success response to persona/contact/lists/put. Type https://trusttasks.org/spec/persona/contact/lists/put/1.1#response. The list as it now stands.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "list",
+        "wasCreated",
+        "changed"
+      ],
+      "properties": {
+        "list": {
+          "$ref": "#/$defs/ContactList"
+        },
+        "wasCreated": {
+          "type": "boolean",
+          "description": "True when this request created the list."
+        },
+        "changed": {
+          "type": "boolean",
+          "description": "True when this request created the list or changed any detail of it. False when every detail given already matched."
+        },
+        "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-]+)+$"
+      }
+    },
+    "ContactList": {
+      "title": "ContactList",
+      "description": "One of the holder's lists, as their agent keeps it. A list is context-scoped, like the contacts it holds: it may hold contacts known by any persona in its context, and contacts from any number of communities, but never a contact of another context.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "listId",
+        "name",
+        "order",
+        "contactCount",
+        "createdAt",
+        "updatedAt"
+      ],
+      "properties": {
+        "listId": {
+          "$ref": "#/$defs/ListId"
+        },
+        "name": {
+          "$ref": "#/$defs/ListName"
+        },
+        "colour": {
+          "$ref": "#/$defs/ListColour"
+        },
+        "order": {
+          "$ref": "#/$defs/ListOrder"
+        },
+        "contactCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many of the context's contacts are on the list now."
+        },
+        "createdAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "updatedAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "When the list's name, colour or order last changed. Adding a contact to the list or removing one does not move it."
+        }
+      }
+    },
+    "ListOrder": {
+      "title": "ListOrder",
+      "description": "Where the holder wants a list among their lists: ascending, ties broken by `name`. A sort key, not a position, so moving one list does not renumber the others; gaps are expected.",
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 1000000
+    },
+    "ListColour": {
+      "title": "ListColour",
+      "description": "A colour the holder picked for a list, as a six-digit lowercase sRGB hex value (`#1f8a70`). A rendering hint: a consumer MAY map it to the nearest colour of its own palette that keeps contrast in light and dark themes, and MUST NOT rely on colour alone to tell lists apart.",
+      "type": "string",
+      "pattern": "^#[0-9a-f]{6}$"
+    },
+    "ListName": {
+      "title": "ListName",
+      "description": "The holder's name for one of their lists (\"Mentors\", \"Met at the spring meetup\"), on one line: no control characters. Unique within a context, compared exactly.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "pattern": "^[^\\u0000-\\u001F\\u007F]+$"
+    },
+    "ListId": {
+      "title": "ListId",
+      "description": "Identifier of one of the holder's contact lists: a ULID in Crockford base32, uppercase, assigned by the agent when the list is created. Meaningful only inside the context that holds the list; it is never sent to anyone but the holder's own clients.",
+      "type": "string",
+      "pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
+    }
+  }
+} 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;