@remit/api-openapi-spec 0.0.30 → 0.0.31

package/openapi.json

@@ -4784,7 +4784,8 @@
       "RemitImap.FolderAppointment": {
         "type": "object",
         "required": [
-          "role"
+          "role",
+          "source"
         ],
         "properties": {
           "role": {
@@ -4795,17 +4796,53 @@
             ],
             "description": "Which canonical role this entry fills."
           },
+          "source": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RemitImap.FolderAppointmentSource"
+              }
+            ],
+            "description": "Where `mailboxId` came from. Read this rather than inferring provenance from the shape of the entry: only `Appointed` means a person decided, and only `Appointed` and `Flagged` are evidence strong enough to destroy mail with."
+          },
           "mailboxId": {
             "allOf": [
               {
                 "$ref": "#/components/schemas/UUID"
               }
             ],
-            "description": "The mailbox appointed to the role. Absent when the role is unfilled — either nothing was detected yet, or the account genuinely has no such folder. When absent on a GET, this is a server-proposed best guess (SPECIAL-USE flag, then the reserved INBOX name, then a weak name hint) rather than a user's persisted choice; it becomes persisted only once the user calls appointFolderRole."
+            "description": "The mailbox this role resolves to. Absent when resolution names none — `source: None`, or a `Stale` appointment with nothing to fall back to."
+          },
+          "staleAppointmentMailboxId": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UUID"
+              }
+            ],
+            "description": "The mailbox the user appointed, when the account no longer holds it. Present exactly when `source` is `Stale`; the appointment is kept rather than collected, so the user can repair it instead of silently losing the choice."
+          },
+          "staleAppointmentPath": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/String512"
+              }
+            ],
+            "description": "The path that stale mailbox last had, recorded beside the appointment when it was made. Display only — resolution never reads it — and present only alongside `staleAppointmentMailboxId`, and only for an appointment made after the path was first recorded."
           }
         },
         "description": "Per-account appointment of a canonical role to at most one mailbox (RFC 032 exclusive-folder-appointment, issue #976). A role with no `mailboxId` is unfilled — either genuinely unappointed, or the account has no matching folder yet. Persisted as per-(account, role) AccountSetting rows (RFC 032 settings tiers), surfaced on AccountResponse.folderAppointments — never on the Mailbox entity, so two folders can never both claim the same role."
       },
+      "RemitImap.FolderAppointmentSource": {
+        "type": "string",
+        "enum": [
+          "Appointed",
+          "Flagged",
+          "Reserved",
+          "Proposed",
+          "Stale",
+          "None"
+        ],
+        "description": "Where a resolved FolderAppointment came from. Total and required: every role carries one, so a surface can tell a folder somebody chose from a folder reader guessed without inferring it from which fields happen to be present."
+      },
       "RemitImap.JunkOnlyFlag": {
         "type": "object",
         "required": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/api-openapi-spec",
-  "version": "0.0.30",
+  "version": "0.0.31",
   "description": "Remit API OpenAPI 3 document, generated from TypeSpec.",
   "exports": {
     ".": "./openapi.json",