@openvtc/trust-tasks 0.28.14 → 0.28.16

package/src/rooms/keys/watch/0.1/payload.ts

@@ -0,0 +1,452 @@
+/**
+ * Generated by scripts/build-ts-bindings.mjs — DO NOT EDIT BY HAND.
+ * Source: specs/rooms/keys/watch/0.1/payload.schema.json
+ */
+
+import type { Ext } from "../../../../_shared/components.js";
+
+
+/**
+ * A member's own client asks the member's key holder to arm, re-arm or cancel rooms/watch at one host for one or more rooms, as the member, with an address the key holder controls; the key holder passes each signal on to the client with rooms/keys/changed. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.
+ */
+export interface RoomsKeysWatchPayload {
+  /**
+   * The member to watch as: a DID the recipient holds keys for and the caller may act as. Always named — the recipient never picks a member for the caller. This task's subject.
+   */
+  member: string;
+  /**
+   * The host to arm the watches at, as a DID. Named by the caller for the reason it is on rooms/keys/browse: nothing maps a room to its host.
+   */
+  host: string;
+  /**
+   * The rooms to watch at this host, each at most once. Each is armed at the host with its own rooms/watch request, presentation and address; the host never sees them together.
+   *
+   * @minItems 1
+   * @maxItems 64
+   */
+  rooms: [RoomToWatch, ...RoomToWatch[]];
+  /**
+   * How long the caller asks each watch to last if it does not fire, in seconds, up to 30 days. Passed to the host as rooms/watch's leaseSeconds; the host and the recipient MAY grant less. Absent means the host's default. Ignored on a cancel.
+   */
+  leaseSeconds?: number;
+  /**
+   * End the watches on the named rooms. Only `true` is meaningful, so only `true` is accepted. A cancel of a watch the recipient does not hold succeeds with `armed: false`.
+   */
+  cancel?: true;
+  /**
+   * Ecosystem-defined extension members per SPEC.md §4.5.1.
+   */
+  ext?: Ext;
+}
+/**
+ * One room of the request, with the version the caller has read it to.
+ */
+export interface RoomToWatch {
+  /**
+   * The room.
+   */
+  roomId: string;
+  /**
+   * The highest version of the room the caller has read to, passed to the host as rooms/watch's sinceVersion: the host signals as soon as the room is above it, at once if it already is. Absent means the room's latest version when the host arms the watch. Ignored on a cancel.
+   */
+  sinceVersion?: number;
+}
+/**
+ * Success response to rooms/keys/watch: one outcome per room requested, in the order requested. Type https://trusttasks.org/spec/rooms/keys/watch/0.1#response.
+ */
+export interface RoomsKeysWatchResponsePayload {
+  /**
+   * The member, echoed.
+   */
+  member: string;
+  /**
+   * The host, echoed.
+   */
+  host: string;
+  /**
+   * @minItems 1
+   * @maxItems 64
+   */
+  watches: [OutcomeForOneRoom, ...OutcomeForOneRoom[]];
+  ext?: Ext;
+}
+/**
+ * What became of one room of the request.
+ */
+export interface OutcomeForOneRoom {
+  /**
+   * The room, echoed.
+   */
+  roomId: string;
+  /**
+   * `true`: the host holds the watch armed and the recipient will pass on its signal with rooms/keys/changed. `false`: the watch was cancelled, there was none to cancel, or it was refused (`refused` says why).
+   */
+  armed: boolean;
+  /**
+   * Present when `armed` is `true`: when the watch lapses if it has not fired — the expiresAt the host answered, or earlier where the recipient bounds it. The caller re-arms before then if it still wants a signal.
+   */
+  expiresAt?: string;
+  /**
+   * Present when this room's watch was not armed or cancelled because of a refusal. `notAMember`: the recipient holds no credential the room issued to `member`. `actionNotHeld`: the member's credentials do not confer `read`. `limitReached`: the recipient holds as many watches as it allows — the caller polls this room. `hostUnreachable`: the host could not be resolved, advertises no transport the recipient speaks, or did not answer — a retry may succeed. `hostRefused`: the host answered with a trust-task-error, whose code is in `hostCode`.
+   */
+  refused?: "notAMember" | "actionNotHeld" | "limitReached" | "hostUnreachable" | "hostRefused";
+  /**
+   * Present when `refused` is `hostRefused`: the code of the host's trust-task-error, unaltered — for instance `rooms/watch:limitReached` or the standard `permissionDenied`.
+   */
+  hostCode?: string;
+}
+
+/** Shared definitions this specification references, re-exported under the names it used to declare them with. */
+export type { Ext };
+
+/** Trust Task type URI. */
+export const TYPE_URI = "https://trusttasks.org/spec/rooms/keys/watch/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 = RoomsKeysWatchPayload;
+
+/** Trust Task response type URI (request type URI + "#response"). */
+export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/rooms/keys/watch/0.1#response" as const;
+
+/** Stable alias for this specification's success-response payload shape. */
+export type Response = RoomsKeysWatchResponsePayload;
+
+/**
+ * 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/rooms/keys/watch/0.1",
+  "title": "Rooms Keys — Watch — payload",
+  "description": "A member's own client asks the member's key holder to arm, re-arm or cancel rooms/watch at one host for one or more rooms, as the member, with an address the key holder controls; the key holder passes each signal on to the client with rooms/keys/changed. The outer document members (id, type, issuer, recipient, issuedAt, expiresAt, proof) are owned by the framework — SPEC §6.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "member",
+    "host",
+    "rooms"
+  ],
+  "properties": {
+    "member": {
+      "type": "string",
+      "pattern": "^did:",
+      "maxLength": 2048,
+      "description": "The member to watch as: a DID the recipient holds keys for and the caller may act as. Always named — the recipient never picks a member for the caller. This task's subject."
+    },
+    "host": {
+      "type": "string",
+      "pattern": "^did:",
+      "maxLength": 2048,
+      "description": "The host to arm the watches at, as a DID. Named by the caller for the reason it is on rooms/keys/browse: nothing maps a room to its host."
+    },
+    "rooms": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 64,
+      "description": "The rooms to watch at this host, each at most once. Each is armed at the host with its own rooms/watch request, presentation and address; the host never sees them together.",
+      "items": {
+        "$ref": "#/$defs/RoomWatchRequest"
+      }
+    },
+    "leaseSeconds": {
+      "type": "integer",
+      "minimum": 60,
+      "maximum": 2592000,
+      "description": "How long the caller asks each watch to last if it does not fire, in seconds, up to 30 days. Passed to the host as rooms/watch's leaseSeconds; the host and the recipient MAY grant less. Absent means the host's default. Ignored on a cancel."
+    },
+    "cancel": {
+      "type": "boolean",
+      "const": true,
+      "description": "End the watches on the named rooms. Only `true` is meaningful, so only `true` is accepted. A cancel of a watch the recipient does not hold succeeds with `armed: false`."
+    },
+    "ext": {
+      "$ref": "#/$defs/Ext",
+      "description": "Ecosystem-defined extension members per SPEC.md §4.5.1."
+    }
+  },
+  "$defs": {
+    "RoomWatchRequest": {
+      "title": "Room to watch",
+      "description": "One room of the request, with the version the caller has read it to.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "roomId"
+      ],
+      "properties": {
+        "roomId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048,
+          "description": "The room."
+        },
+        "sinceVersion": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The highest version of the room the caller has read to, passed to the host as rooms/watch's sinceVersion: the host signals as soon as the room is above it, at once if it already is. Absent means the room's latest version when the host arms the watch. Ignored on a cancel."
+        }
+      }
+    },
+    "RoomWatchOutcome": {
+      "title": "Outcome for one room",
+      "description": "What became of one room of the request.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "roomId",
+        "armed"
+      ],
+      "properties": {
+        "roomId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048,
+          "description": "The room, echoed."
+        },
+        "armed": {
+          "type": "boolean",
+          "description": "`true`: the host holds the watch armed and the recipient will pass on its signal with rooms/keys/changed. `false`: the watch was cancelled, there was none to cancel, or it was refused (`refused` says why)."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Present when `armed` is `true`: when the watch lapses if it has not fired — the expiresAt the host answered, or earlier where the recipient bounds it. The caller re-arms before then if it still wants a signal."
+        },
+        "refused": {
+          "type": "string",
+          "enum": [
+            "notAMember",
+            "actionNotHeld",
+            "limitReached",
+            "hostUnreachable",
+            "hostRefused"
+          ],
+          "description": "Present when this room's watch was not armed or cancelled because of a refusal. `notAMember`: the recipient holds no credential the room issued to `member`. `actionNotHeld`: the member's credentials do not confer `read`. `limitReached`: the recipient holds as many watches as it allows — the caller polls this room. `hostUnreachable`: the host could not be resolved, advertises no transport the recipient speaks, or did not answer — a retry may succeed. `hostRefused`: the host answered with a trust-task-error, whose code is in `hostCode`."
+        },
+        "hostCode": {
+          "type": "string",
+          "maxLength": 256,
+          "description": "Present when `refused` is `hostRefused`: the code of the host's trust-task-error, unaltered — for instance `rooms/watch:limitReached` or the standard `permissionDenied`."
+        }
+      }
+    },
+    "Response": {
+      "$anchor": "response",
+      "title": "Rooms Keys — Watch — response payload",
+      "description": "Success response to rooms/keys/watch: one outcome per room requested, in the order requested. Type https://trusttasks.org/spec/rooms/keys/watch/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "member",
+        "host",
+        "watches"
+      ],
+      "properties": {
+        "member": {
+          "type": "string",
+          "pattern": "^did:",
+          "maxLength": 2048,
+          "description": "The member, echoed."
+        },
+        "host": {
+          "type": "string",
+          "pattern": "^did:",
+          "maxLength": 2048,
+          "description": "The host, echoed."
+        },
+        "watches": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "$ref": "#/$defs/RoomWatchOutcome"
+          }
+        },
+        "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-]+)+$"
+      }
+    }
+  }
+} 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": {
+    "RoomWatchRequest": {
+      "title": "Room to watch",
+      "description": "One room of the request, with the version the caller has read it to.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "roomId"
+      ],
+      "properties": {
+        "roomId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048,
+          "description": "The room."
+        },
+        "sinceVersion": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The highest version of the room the caller has read to, passed to the host as rooms/watch's sinceVersion: the host signals as soon as the room is above it, at once if it already is. Absent means the room's latest version when the host arms the watch. Ignored on a cancel."
+        }
+      }
+    },
+    "RoomWatchOutcome": {
+      "title": "Outcome for one room",
+      "description": "What became of one room of the request.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "roomId",
+        "armed"
+      ],
+      "properties": {
+        "roomId": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 2048,
+          "description": "The room, echoed."
+        },
+        "armed": {
+          "type": "boolean",
+          "description": "`true`: the host holds the watch armed and the recipient will pass on its signal with rooms/keys/changed. `false`: the watch was cancelled, there was none to cancel, or it was refused (`refused` says why)."
+        },
+        "expiresAt": {
+          "type": "string",
+          "format": "date-time",
+          "description": "Present when `armed` is `true`: when the watch lapses if it has not fired — the expiresAt the host answered, or earlier where the recipient bounds it. The caller re-arms before then if it still wants a signal."
+        },
+        "refused": {
+          "type": "string",
+          "enum": [
+            "notAMember",
+            "actionNotHeld",
+            "limitReached",
+            "hostUnreachable",
+            "hostRefused"
+          ],
+          "description": "Present when this room's watch was not armed or cancelled because of a refusal. `notAMember`: the recipient holds no credential the room issued to `member`. `actionNotHeld`: the member's credentials do not confer `read`. `limitReached`: the recipient holds as many watches as it allows — the caller polls this room. `hostUnreachable`: the host could not be resolved, advertises no transport the recipient speaks, or did not answer — a retry may succeed. `hostRefused`: the host answered with a trust-task-error, whose code is in `hostCode`."
+        },
+        "hostCode": {
+          "type": "string",
+          "maxLength": 256,
+          "description": "Present when `refused` is `hostRefused`: the code of the host's trust-task-error, unaltered — for instance `rooms/watch:limitReached` or the standard `permissionDenied`."
+        }
+      }
+    },
+    "Response": {
+      "$anchor": "response",
+      "title": "Rooms Keys — Watch — response payload",
+      "description": "Success response to rooms/keys/watch: one outcome per room requested, in the order requested. Type https://trusttasks.org/spec/rooms/keys/watch/0.1#response.",
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "member",
+        "host",
+        "watches"
+      ],
+      "properties": {
+        "member": {
+          "type": "string",
+          "pattern": "^did:",
+          "maxLength": 2048,
+          "description": "The member, echoed."
+        },
+        "host": {
+          "type": "string",
+          "pattern": "^did:",
+          "maxLength": 2048,
+          "description": "The host, echoed."
+        },
+        "watches": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "$ref": "#/$defs/RoomWatchOutcome"
+          }
+        },
+        "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-]+)+$"
+      }
+    }
+  }
+} 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/rooms/records/get/0.1/payload.ts

@@ -6,7 +6,7 @@
 import type { AuthorityPresentation, DataCommitment, DigestMultibase, Ext, HeadVersion, RecordCount, RecordTrace, SealedRecord } from "../../../../_shared/components.js";
 
 
-/** @deprecated superseded by rooms/records/get/0.2 */
+/** @deprecated superseded by rooms/records/get/0.3 */
 export interface RoomsRecordsGetPayload {
   /**
    * The room's identifier.
@@ -28,7 +28,7 @@ export interface RoomsRecordsGetPayload {
 /**
  * Success response to rooms/records/get. Type https://trusttasks.org/spec/rooms/records/get/0.1#response.
  *
- * @deprecated superseded by rooms/records/get/0.2
+ * @deprecated superseded by rooms/records/get/0.3
  */
 export interface RoomsRecordsGetResponsePayload {
   key: string;
@@ -104,12 +104,12 @@ export const EXTENDS: string | null = null;
  * this package in a later scheduled batch (SPEC "Superseded and Withdrawn
  * Versions").
  */
-export const DEPRECATION: string | null = "superseded by rooms/records/get/0.2";
+export const DEPRECATION: string | null = "superseded by rooms/records/get/0.3";
 
 /**
  * Stable alias for this specification's request payload shape.
  *
- * @deprecated superseded by rooms/records/get/0.2
+ * @deprecated superseded by rooms/records/get/0.3
  */
 export type Payload = RoomsRecordsGetPayload;
 
@@ -119,7 +119,7 @@ export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/rooms/records/get/
 /**
  * Stable alias for this specification's success-response payload shape.
  *
- * @deprecated superseded by rooms/records/get/0.2
+ * @deprecated superseded by rooms/records/get/0.3
  */
 export type Response = RoomsRecordsGetResponsePayload;
 

package/src/rooms/records/get/0.2/payload.ts

@@ -6,6 +6,7 @@
 import type { AuthorityPresentation, BlobRef, DataCommitment, DigestMultibase, Ext, HeadVersion, RecordCount, RecordTrace, SealedRecord } from "../../../../_shared/components.js";
 
 
+/** @deprecated superseded by rooms/records/get/0.3 */
 export interface RoomsRecordsGetPayload {
   /**
    * The room's identifier.
@@ -26,6 +27,8 @@ export interface RoomsRecordsGetPayload {
 }
 /**
  * Success response to rooms/records/get. Type https://trusttasks.org/spec/rooms/records/get/0.2#response.
+ *
+ * @deprecated superseded by rooms/records/get/0.3
  */
 export interface RoomsRecordsGetResponsePayload {
   key: string;
@@ -108,15 +111,23 @@ export const EXTENDS: string | null = null;
  * this package in a later scheduled batch (SPEC "Superseded and Withdrawn
  * Versions").
  */
-export const DEPRECATION: string | null = null;
+export const DEPRECATION: string | null = "superseded by rooms/records/get/0.3";
 
-/** Stable alias for this specification's request payload shape. */
+/**
+ * Stable alias for this specification's request payload shape.
+ *
+ * @deprecated superseded by rooms/records/get/0.3
+ */
 export type Payload = RoomsRecordsGetPayload;
 
 /** Trust Task response type URI (request type URI + "#response"). */
 export const RESPONSE_TYPE_URI = "https://trusttasks.org/spec/rooms/records/get/0.2#response" as const;
 
-/** Stable alias for this specification's success-response payload shape. */
+/**
+ * Stable alias for this specification's success-response payload shape.
+ *
+ * @deprecated superseded by rooms/records/get/0.3
+ */
 export type Response = RoomsRecordsGetResponsePayload;
 
 /**