@openvtc/trust-tasks 0.27.2 → 0.27.4

package/src/vtc/members/list/0.2/payload.ts

@@ -0,0 +1,426 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vtc/members/list/0.2/payload.schema.json
+ */
+
+import type { Ext, MemberResponse } from "../../../../_shared/components.js";
+
+
+export interface VTCMembersListPayload {
+  /**
+   * Filter to members with this role (wire form, e.g. `admin`, `custom:editor`).
+   */
+  role?: string;
+  /**
+   * An opaque continuation token from a previous response's `nextCursor`; 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;
+}
+export interface VTCMembersListResponsePayload {
+  items: MemberResponse[];
+  /**
+   * Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`.
+   */
+  nextCursor?: string;
+  /**
+   * Approximate total matching members, when the maintainer can cheaply estimate it.
+   */
+  totalEstimate?: number | null;
+  ext?: Ext;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { Ext, MemberResponse };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vtc/members/list/0.2" as const;
+
+/** Stable alias for this specification's request payload shape. */
+export type Payload = VTCMembersListPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vtc/members/list/0.2#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTCMembersListResponsePayload;
+
+/**
+ * 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/members/list/0.2",
+  "title": "VTC Members List — payload",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "role": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Filter to members with this role (wire form, e.g. `admin`, `custom:editor`)."
+    },
+    "cursor": {
+      "type": "string",
+      "description": "An opaque continuation token from a previous response's `nextCursor`; 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 Members List — response payload",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "items"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/MemberResponse"
+          }
+        },
+        "nextCursor": {
+          "type": "string",
+          "description": "Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`."
+        },
+        "totalEstimate": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "description": "Approximate total matching members, when the maintainer can cheaply estimate it."
+        },
+        "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-]+)+$"
+      }
+    },
+    "MemberResponse": {
+      "$anchor": "memberResponse",
+      "title": "MemberResponse",
+      "description": "One community member as the maintainer sees it: the membership record joined with its ACL role.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "did",
+        "role",
+        "joinedAt",
+        "publishConsent",
+        "departurePreference",
+        "extensions"
+      ],
+      "properties": {
+        "did": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The member's DID."
+        },
+        "role": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The member's role in wire form (e.g. `admin`, `moderator`, `custom:editor`)."
+        },
+        "label": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "maxLength": 256,
+          "description": "Optional human-readable label."
+        },
+        "joinedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "publishConsent": {
+          "type": "boolean",
+          "description": "Whether the member consented to being published in the community directory."
+        },
+        "departurePreference": {
+          "type": "string",
+          "enum": [
+            "purge",
+            "tombstone",
+            "historical",
+            "policydefault"
+          ],
+          "description": "How the member's record is handled on departure."
+        },
+        "statusListIndex": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "description": "The member's slot on the community's membership status list, when allocated."
+        },
+        "currentVmcId": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Id of the member's current Verifiable Membership Credential, if issued."
+        },
+        "currentRoleVacId": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Id of the member's current role credential — a community-issued Verifiable Authority Credential conferring `role:<name>` — if issued. Formerly `currentRoleVecId`."
+        },
+        "personhood": {
+          "type": "boolean",
+          "description": "Whether the community has asserted that this member is a distinct real person. Read-only here: it is set and cleared by the personhood verbs, and cleared by a renewal-policy downgrade. Load-bearing rather than informational — a community that recognises members of another community may gate on it, so a consumer that cannot read it cannot make that decision."
+        },
+        "personhoodAssertedAt": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time",
+          "description": "When personhood was most recently asserted. Absent where it never has been. Operator-facing: it belongs on admin-gated reads, and a member's own view of themselves need carry only the flag."
+        },
+        "joinedViaInvitation": {
+          "type": "boolean",
+          "description": "Whether this member joined by presenting an invitation credential rather than by an admin's decision on an open request. The two routes to membership carry different evidence, and an operator reviewing a roster can otherwise not tell them apart."
+        },
+        "memberVmcId": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "`id` of the member-issued reciprocal membership credential — the member half of the pair — once the member has sent it. Absent until then, which is the useful signal: it distinguishes a membership the community has asserted from one the member has acknowledged. The credential body is not echoed here."
+        },
+        "memberVmcReceivedAt": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time",
+          "description": "When that reciprocal credential was received. Paired with `memberVmcId`."
+        },
+        "extensions": {
+          "type": "object",
+          "description": "Opaque community-defined extension bag. Keys are maintainer-defined; the maintainer caps its size (16 KiB in the reference implementation)."
+        }
+      }
+    }
+  }
+} 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 Members List — response payload",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "items"
+      ],
+      "properties": {
+        "items": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/MemberResponse"
+          }
+        },
+        "nextCursor": {
+          "type": "string",
+          "description": "Continuation token for the next page; pass it back as `cursor`. Absent on the last page — never `null`."
+        },
+        "totalEstimate": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "description": "Approximate total matching members, when the maintainer can cheaply estimate it."
+        },
+        "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-]+)+$"
+      }
+    },
+    "MemberResponse": {
+      "$anchor": "memberResponse",
+      "title": "MemberResponse",
+      "description": "One community member as the maintainer sees it: the membership record joined with its ACL role.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "did",
+        "role",
+        "joinedAt",
+        "publishConsent",
+        "departurePreference",
+        "extensions"
+      ],
+      "properties": {
+        "did": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The member's DID."
+        },
+        "role": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The member's role in wire form (e.g. `admin`, `moderator`, `custom:editor`)."
+        },
+        "label": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "maxLength": 256,
+          "description": "Optional human-readable label."
+        },
+        "joinedAt": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "publishConsent": {
+          "type": "boolean",
+          "description": "Whether the member consented to being published in the community directory."
+        },
+        "departurePreference": {
+          "type": "string",
+          "enum": [
+            "purge",
+            "tombstone",
+            "historical",
+            "policydefault"
+          ],
+          "description": "How the member's record is handled on departure."
+        },
+        "statusListIndex": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "description": "The member's slot on the community's membership status list, when allocated."
+        },
+        "currentVmcId": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Id of the member's current Verifiable Membership Credential, if issued."
+        },
+        "currentRoleVacId": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Id of the member's current role credential — a community-issued Verifiable Authority Credential conferring `role:<name>` — if issued. Formerly `currentRoleVecId`."
+        },
+        "personhood": {
+          "type": "boolean",
+          "description": "Whether the community has asserted that this member is a distinct real person. Read-only here: it is set and cleared by the personhood verbs, and cleared by a renewal-policy downgrade. Load-bearing rather than informational — a community that recognises members of another community may gate on it, so a consumer that cannot read it cannot make that decision."
+        },
+        "personhoodAssertedAt": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time",
+          "description": "When personhood was most recently asserted. Absent where it never has been. Operator-facing: it belongs on admin-gated reads, and a member's own view of themselves need carry only the flag."
+        },
+        "joinedViaInvitation": {
+          "type": "boolean",
+          "description": "Whether this member joined by presenting an invitation credential rather than by an admin's decision on an open request. The two routes to membership carry different evidence, and an operator reviewing a roster can otherwise not tell them apart."
+        },
+        "memberVmcId": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "`id` of the member-issued reciprocal membership credential — the member half of the pair — once the member has sent it. Absent until then, which is the useful signal: it distinguishes a membership the community has asserted from one the member has acknowledged. The credential body is not echoed here."
+        },
+        "memberVmcReceivedAt": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "format": "date-time",
+          "description": "When that reciprocal credential was received. Paired with `memberVmcId`."
+        },
+        "extensions": {
+          "type": "object",
+          "description": "Opaque community-defined extension bag. Keys are maintainer-defined; the maintainer caps its size (16 KiB in the reference implementation)."
+        }
+      }
+    }
+  }
+} 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;