@openvtc/trust-tasks 0.28.10 → 0.28.12

package/src/vtc/notifications/relay/0.1/payload.ts

@@ -0,0 +1,382 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/vtc/notifications/relay/0.1/payload.schema.json
+ */
+
+import type { Ext, GroupId, Recipients, RecipientScope, RecordId_VtcNotificationsV0_1 as RecordId } from "../../../../_shared/components.js";
+
+
+/**
+ * An administrator with `vtc.notifications.relay` decides that the community relays one notification it holds to some of its members — all of them, the members of one group, or the holders of one community role — having been shown what the relay discloses about the community (VTI-NTF-046, VTI-NTF-071 – VTI-NTF-073). The community relays the document it received exactly as received, one notifications/relay/0.1 per member, never to itself, the originator or any earlier relayer, and relays every later revision to the same members without a further decision (VTI-NTF-044). The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface VTCNotificationsRelayPayload {
+  recordId: RecordId;
+  recipients: Recipients;
+  /**
+   * The administrator's statement that they were shown the notification's `relayDisclosure` and decide the relay knowing it (VTI-NTF-046). REQUIRED to be true for a notification whose kind's definition says a relay discloses something; ignored for one whose definition says nothing is disclosed.
+   */
+  disclosureAcknowledged?: boolean;
+  ext?: Ext;
+}
+export interface VTCNotificationsRelayResponsePayload {
+  recordId: RecordId;
+  /**
+   * The revision of the notification the decision relays.
+   */
+  revision: number;
+  /**
+   * How many parties this decision added to those the notification is relayed to, each of which the community has queued one relay for. Zero when the selection reaches no member an earlier decision had not.
+   */
+  recipientCount: number;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { Ext, GroupId, Recipients, RecipientScope, RecordId };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/vtc/notifications/relay/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 = VTCNotificationsRelayPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/vtc/notifications/relay/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = VTCNotificationsRelayResponsePayload;
+
+/**
+ * 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/notifications/relay/0.1",
+  "title": "VTC Notifications — Relay — payload",
+  "description": "An administrator with `vtc.notifications.relay` decides that the community relays one notification it holds to some of its members — all of them, the members of one group, or the holders of one community role — having been shown what the relay discloses about the community (VTI-NTF-046, VTI-NTF-071 – VTI-NTF-073). The community relays the document it received exactly as received, one notifications/relay/0.1 per member, never to itself, the originator or any earlier relayer, and relays every later revision to the same members without a further decision (VTI-NTF-044). The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "recordId",
+    "recipients"
+  ],
+  "properties": {
+    "recordId": {
+      "$ref": "#/$defs/RecordId"
+    },
+    "recipients": {
+      "$ref": "#/$defs/Recipients"
+    },
+    "disclosureAcknowledged": {
+      "type": "boolean",
+      "description": "The administrator's statement that they were shown the notification's `relayDisclosure` and decide the relay knowing it (VTI-NTF-046). REQUIRED to be true for a notification whose kind's definition says a relay discloses something; ignored for one whose definition says nothing is disclosed."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext"
+    }
+  },
+  "$defs": {
+    "Response": {
+      "$anchor": "response",
+      "title": "VTC Notifications — Relay — response payload",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "recordId",
+        "revision",
+        "recipientCount"
+      ],
+      "properties": {
+        "recordId": {
+          "$ref": "#/$defs/RecordId"
+        },
+        "revision": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000000,
+          "description": "The revision of the notification the decision relays."
+        },
+        "recipientCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many parties this decision added to those the notification is relayed to, each of which the community has queued one relay for. Zero when the selection reaches no member an earlier decision had not."
+        }
+      }
+    },
+    "RecordId": {
+      "title": "RecordId",
+      "description": "The community's own identifier for one received notification, stable across the revisions that replace it. Opaque and compared for equality only; unguessable, because a read by a caller without the capability is refused and an enumerable identifier would turn the refusal into an oracle.",
+      "type": "string",
+      "minLength": 16,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9._~:-]+$"
+    },
+    "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-]+)+$"
+      }
+    },
+    "Recipients": {
+      "title": "Recipients",
+      "description": "The members a relay decision reaches, resolved by the community from its own records when the decision is made (VTI-NTF-072). `groupId` is present exactly when `scope` is `group`, and `role` exactly when `scope` is `role`. Whatever the scope, the community never relays to itself, to the notification's originator, or to any relayer the received chain names (VTI-NTF-047), and relays to each party at most once per revision.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "scope"
+      ],
+      "properties": {
+        "scope": {
+          "$ref": "#/$defs/RecipientScope"
+        },
+        "groupId": {
+          "$ref": "#/$defs/GroupId",
+          "description": "The community group whose active members the relay reaches."
+        },
+        "role": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "The community role whose active holders the relay reaches, in the wire form the community's member records use — for example `moderator`, or `custom:editor`."
+        }
+      },
+      "dependentSchemas": {
+        "scope": {
+          "anyOf": [
+            {
+              "required": [
+                "groupId"
+              ]
+            },
+            {
+              "required": [
+                "role"
+              ]
+            },
+            {
+              "properties": {
+                "scope": {
+                  "const": "allMembers"
+                }
+              }
+            }
+          ]
+        },
+        "groupId": {
+          "properties": {
+            "scope": {
+              "const": "group"
+            }
+          }
+        },
+        "role": {
+          "properties": {
+            "scope": {
+              "const": "role"
+            }
+          }
+        }
+      }
+    },
+    "RecipientScope": {
+      "title": "RecipientScope",
+      "description": "Which of the community's members a relay decision reaches: `allMembers` — every active member; `group` — the active members of one community group; `role` — the active members holding one community role.",
+      "type": "string",
+      "enum": [
+        "allMembers",
+        "group",
+        "role"
+      ]
+    },
+    "GroupId": {
+      "title": "GroupId",
+      "description": "Opaque identifier of a community group: `grp_` followed by 16 to 64 base64url characters. Random and community-scoped; not the group's DID.",
+      "type": "string",
+      "pattern": "^grp_[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 Notifications — Relay — response payload",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "recordId",
+        "revision",
+        "recipientCount"
+      ],
+      "properties": {
+        "recordId": {
+          "$ref": "#/$defs/RecordId"
+        },
+        "revision": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 1000000,
+          "description": "The revision of the notification the decision relays."
+        },
+        "recipientCount": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "How many parties this decision added to those the notification is relayed to, each of which the community has queued one relay for. Zero when the selection reaches no member an earlier decision had not."
+        }
+      }
+    },
+    "RecordId": {
+      "title": "RecordId",
+      "description": "The community's own identifier for one received notification, stable across the revisions that replace it. Opaque and compared for equality only; unguessable, because a read by a caller without the capability is refused and an enumerable identifier would turn the refusal into an oracle.",
+      "type": "string",
+      "minLength": 16,
+      "maxLength": 128,
+      "pattern": "^[A-Za-z0-9._~:-]+$"
+    },
+    "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-]+)+$"
+      }
+    },
+    "Recipients": {
+      "title": "Recipients",
+      "description": "The members a relay decision reaches, resolved by the community from its own records when the decision is made (VTI-NTF-072). `groupId` is present exactly when `scope` is `group`, and `role` exactly when `scope` is `role`. Whatever the scope, the community never relays to itself, to the notification's originator, or to any relayer the received chain names (VTI-NTF-047), and relays to each party at most once per revision.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "scope"
+      ],
+      "properties": {
+        "scope": {
+          "$ref": "#/$defs/RecipientScope"
+        },
+        "groupId": {
+          "$ref": "#/$defs/GroupId",
+          "description": "The community group whose active members the relay reaches."
+        },
+        "role": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "The community role whose active holders the relay reaches, in the wire form the community's member records use — for example `moderator`, or `custom:editor`."
+        }
+      },
+      "dependentSchemas": {
+        "scope": {
+          "anyOf": [
+            {
+              "required": [
+                "groupId"
+              ]
+            },
+            {
+              "required": [
+                "role"
+              ]
+            },
+            {
+              "properties": {
+                "scope": {
+                  "const": "allMembers"
+                }
+              }
+            }
+          ]
+        },
+        "groupId": {
+          "properties": {
+            "scope": {
+              "const": "group"
+            }
+          }
+        },
+        "role": {
+          "properties": {
+            "scope": {
+              "const": "role"
+            }
+          }
+        }
+      }
+    },
+    "RecipientScope": {
+      "title": "RecipientScope",
+      "description": "Which of the community's members a relay decision reaches: `allMembers` — every active member; `group` — the active members of one community group; `role` — the active members holding one community role.",
+      "type": "string",
+      "enum": [
+        "allMembers",
+        "group",
+        "role"
+      ]
+    },
+    "GroupId": {
+      "title": "GroupId",
+      "description": "Opaque identifier of a community group: `grp_` followed by 16 to 64 base64url characters. Random and community-scoped; not the group's DID.",
+      "type": "string",
+      "pattern": "^grp_[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: 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;