@remit/api-openapi-spec 0.0.29 → 0.0.31

package/openapi.json

@@ -521,6 +521,16 @@
                 }
               }
             }
+          },
+          "409": {
+            "description": "The same flat 409 body as `FolderRoleConflict`, with one code only this endpoint can answer with.\n\n`code: \"folder_role_unresolved\"` — as everywhere else, with `details` carrying `role`, `accountId` and `reason`.\n\n`code: \"mailbox_not_settled\"` — the mailbox being appointed is still being created or deleted on the mail server, so it cannot yet hold a role. `details` carries `mailboxId` and `syncStatus`. Clearing a role is never refused this way.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
           }
         },
         "requestBody": {
@@ -1241,6 +1251,16 @@
                 }
               }
             }
+          },
+          "409": {
+            "description": "An action was refused because the folder role it needs is not settled. The body is flat: `code`, `message` and `details` sit at the top level, which is what the API emits. Clients branch on `code` and word their prompt from `details`, never from `message`.\n\n`code: \"folder_role_unresolved\"` — no folder holds the role this action needs. `details` carries `role`, `accountId`, and `reason`, one of: `none` (the account has no candidate folder), `stale` (the folder the user appointed is gone from the mail server), `unconfirmed` (a folder matches by name, but neither the user nor the server's own flag ever said it holds the role).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
           }
         },
         "x-amazon-apigateway-integration": {
@@ -1836,6 +1856,16 @@
                 }
               }
             }
+          },
+          "409": {
+            "description": "An action was refused because the folder role it needs is not settled. The body is flat: `code`, `message` and `details` sit at the top level, which is what the API emits. Clients branch on `code` and word their prompt from `details`, never from `message`.\n\n`code: \"folder_role_unresolved\"` — no folder holds the role this action needs. `details` carries `role`, `accountId`, and `reason`, one of: `none` (the account has no candidate folder), `stale` (the folder the user appointed is gone from the mail server), `unconfirmed` (a folder matches by name, but neither the user nor the server's own flag ever said it holds the role).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
           }
         },
         "requestBody": {
@@ -4754,7 +4784,8 @@
       "RemitImap.FolderAppointment": {
         "type": "object",
         "required": [
-          "role"
+          "role",
+          "source"
         ],
         "properties": {
           "role": {
@@ -4765,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.29",
+  "version": "0.0.31",
   "description": "Remit API OpenAPI 3 document, generated from TypeSpec.",
   "exports": {
     ".": "./openapi.json",