@remit/api-openapi-spec 0.0.5 → 0.0.7

package/openapi.json

@@ -1476,6 +1476,33 @@
         }
       }
     },
+    "/me/quarantine": {
+      "get": {
+        "operationId": "MeOperations_listQuarantine",
+        "description": "List every message the sync path could not read, for the current user across all of their mail accounts (issue #72). Backs the quarantine section in settings. Unpaginated: the list is small by design, and an entry is a defect waiting to be reported rather than a page of mail.",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RemitImap.QuarantineListResponse"
+                }
+              }
+            }
+          }
+        },
+        "x-amazon-apigateway-integration": {
+          "type": "aws_proxy",
+          "httpMethod": "POST",
+          "passthroughBehavior": "when_no_match",
+          "uri": {
+            "Fn::Sub": "arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/arn:aws:lambda:${AWS::Region}:${AWS::AccountId}:function:{{HandlerFunctionName}}/invocations"
+          }
+        }
+      }
+    },
     "/me/vip-suggestions": {
       "get": {
         "operationId": "MeOperations_listVipSuggestions",
@@ -4891,6 +4918,268 @@
         ],
         "description": "Actionable placement verdict — the direction Remit decided to move a message. `leave` is not represented: a left-in-place verdict means the placement sub-model is absent."
       },
+      "RemitImap.QuarantineFailureCode": {
+        "type": "string",
+        "enum": [
+          "UnknownCharset",
+          "UnreadableBody"
+        ],
+        "description": "The specific defect within a stage.\n\nClosed rather than free text: this is the one diagnostic that is interpolated\ninto the title of an issue filed under the user's own GitHub account, so its\npublishability has to be a property of the type instead of a claim about the\nwriter.\n\nThe vocabulary is total — every quarantine write picks a member, and a defect\nthe writer cannot name is `UnreadableBody` rather than an invented code. It\nis deliberately small: the body parser reports its refusals as free text with\nno stable type or code, so a member exists only where the writer can identify\nthe defect without reading parser prose. `UnterminatedMultipartBoundary` and\n`TruncatedBody` were provisional members carried by Phase 2 and are gone —\nnothing on the narrowed sync path could produce either, and a member no\nwriter can reach is a vocabulary that lies about what the field means.\n`MissingEnvelope` is absent for the same reason: see QuarantineFailureStage."
+      },
+      "RemitImap.QuarantineFailureStage": {
+        "type": "string",
+        "enum": [
+          "BodyParse"
+        ],
+        "description": "The pipeline step that refused a quarantined message.\n\nOne member, and it is behind a real narrowing rather than a promise of one:\nthe body parse has its own try block around the parse call and nothing else,\nso an error out of it can only be the message. S3, queue and database\nfailures propagate and never become a record here — quarantining one would\nset a message aside for an outage, tell the user it was unreadable, and\ninvite a public GitHub issue about it.\n\nA message that arrives with no ENVELOPE is deliberately NOT a member. Nothing\ncan tell that apart from the FETCH row glitching (#408), and the IMAP client\nis far more often the cause than the message; the sync path holds its cursor\nand retries instead, so a transient glitch heals and a persistent one trips\nthe stalled-cursor alert."
+      },
+      "RemitImap.QuarantineListResponse": {
+        "type": "object",
+        "required": [
+          "entries"
+        ],
+        "properties": {
+          "entries": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RemitImap.QuarantineResponse"
+            },
+            "description": "Quarantined messages, newest first."
+          }
+        },
+        "description": "Everything quarantined for the current user, newest first. The list is small by design — a mailbox with a growing quarantine list is a bug being reported, not a page to paginate."
+      },
+      "RemitImap.QuarantineMimeNode": {
+        "type": "object",
+        "required": [
+          "depth",
+          "contentType"
+        ],
+        "properties": {
+          "depth": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Nesting level, 0 for the root part."
+          },
+          "contentType": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/String140"
+              }
+            ],
+            "description": "Media type of this node, `type/subtype`, parameters stripped."
+          }
+        },
+        "description": "One node of a quarantined message's MIME tree, in a pre-order walk.\n\nThe tree is carried flat with an explicit `depth` rather than as nested\nchildren: a self-referential model is not expressible here (the entity\nemitter recurses forever on one), and the tree is only ever rendered as an\nindented list, which a pre-order walk reproduces exactly. Nothing caps the\nwalk — it is as long as the message has parts.\n\n`contentType` is `type/subtype` only. BODYSTRUCTURE hands the type and its\nparameters over separately, so a node is built from `type`/`subtype` and\nnever from a raw content-type line — parameters carry `name=` and\n`filename=`, which name the user's attachments."
+      },
+      "RemitImap.QuarantineResponse": {
+        "type": "object",
+        "required": [
+          "quarantineId",
+          "accountConfigId",
+          "accountId",
+          "mailboxId",
+          "uidValidity",
+          "uid",
+          "mailboxPath",
+          "quarantinedAt",
+          "attempts",
+          "failureStage",
+          "failureCode",
+          "failureMessage",
+          "workerVersion",
+          "structure",
+          "createdAt",
+          "updatedAt"
+        ],
+        "properties": {
+          "quarantineId": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UUID"
+              }
+            ],
+            "description": "Deterministic v5 identity derived from accountId, mailboxId, uidValidity and uid. Idempotent by construction: the same failing message keys the same row on every retry, so nothing has to check for an existing entry before writing one.",
+            "readOnly": true
+          },
+          "accountConfigId": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UUID"
+              }
+            ],
+            "description": "Owning account configuration — the user. Scopes the settings list and the read endpoint.",
+            "readOnly": true
+          },
+          "accountId": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UUID"
+              }
+            ],
+            "description": "Mail account the message arrived on. Part of the quarantineId derivation.",
+            "readOnly": true
+          },
+          "mailboxId": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UUID"
+              }
+            ],
+            "description": "Mailbox the message arrived in. Part of the quarantineId derivation.",
+            "readOnly": true
+          },
+          "uidValidity": {
+            "type": "integer",
+            "format": "int64",
+            "description": "UIDVALIDITY of the mailbox when the message was set aside. A uid means nothing without it — only uidValidity + uid names a message forever (RFC 9051 2.3.1.1), and a mailbox keeps its mailboxId across a bump, so leaving this out would let a stale entry claim the identity of a later, unrelated message and suppress it from a sync round.",
+            "readOnly": true
+          },
+          "uid": {
+            "type": "integer",
+            "format": "int64",
+            "description": "The IMAP uid that was never written. Part of the quarantineId derivation.",
+            "readOnly": true
+          },
+          "mailboxRole": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RemitImap.CanonicalMailboxRole"
+              }
+            ],
+            "description": "Canonical role of the folder the message arrived in — travels in the report. Absent when the user has appointed no role to that folder, which is the normal state for a plain folder. A sentinel would mean a new member on the shared canonical-role enum, which FolderAppointment would then have to mean something by.",
+            "readOnly": true
+          },
+          "mailboxPath": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/String512"
+              }
+            ],
+            "description": "The user's own folder name. Shown on screen, withheld from the report.",
+            "readOnly": true
+          },
+          "quarantinedAt": {
+            "type": "integer",
+            "format": "int64",
+            "description": "Epoch millis the message was set aside.",
+            "readOnly": true
+          },
+          "attempts": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Rounds tried before the message was set aside.",
+            "readOnly": true
+          },
+          "failureStage": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RemitImap.QuarantineFailureStage"
+              }
+            ],
+            "description": "Pipeline step that refused the message.",
+            "readOnly": true
+          },
+          "failureCode": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RemitImap.QuarantineFailureCode"
+              }
+            ],
+            "description": "The specific defect. Closed vocabulary, because this is what a filed issue quotes.",
+            "readOnly": true
+          },
+          "failureMessage": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/String512"
+              }
+            ],
+            "description": "Parser error text. Shown on screen, never in the report.",
+            "readOnly": true
+          },
+          "failurePartPath": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/String140"
+              }
+            ],
+            "description": "Dot-numbered part path the failure is attributable to, off ROOT_PART_PATH. Absent when the failure belongs to no single node — every whole-body parse failure today.",
+            "readOnly": true
+          },
+          "workerVersion": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/String64"
+              }
+            ],
+            "description": "Build of the imap-worker that failed to read the message. Named for the worker, not the app: the record is written by the sync worker, and stamping the client build on a backend parse failure points a maintainer at the wrong commit.",
+            "readOnly": true
+          },
+          "contentType": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/String140"
+              }
+            ],
+            "description": "Top-level Content-Type, `type/subtype` only. Sender-controlled text — escape it wherever it is rendered. Absent together with the other BODYSTRUCTURE-derived fields when the message failed before its structure was read.",
+            "readOnly": true
+          },
+          "transferEncoding": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/String64"
+              }
+            ],
+            "description": "Content-Transfer-Encoding as declared. Sender-controlled text. Absent when there was no BODYSTRUCTURE to read it from.",
+            "readOnly": true
+          },
+          "charset": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/String64"
+              }
+            ],
+            "description": "Declared charset. Sender-controlled text. Absent is meaningful: an undeclared charset is a cause in its own right, distinct from a charset nobody recognises.",
+            "readOnly": true
+          },
+          "sizeBytes": {
+            "type": "integer",
+            "format": "int64",
+            "description": "RFC822.SIZE. Separates \"too large\" from \"malformed\". Absent when the FETCH that failed carried no size.",
+            "readOnly": true
+          },
+          "structure": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RemitImap.QuarantineMimeNode"
+            },
+            "description": "The MIME tree, structure only, as a pre-order walk. The one field here that cannot be a column, because it is a tree; every other message-shape field is flat and stays typed. Empty when the message failed before its BODYSTRUCTURE was read.",
+            "default": [],
+            "readOnly": true
+          },
+          "messageIdHash": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/String140"
+              }
+            ],
+            "description": "SHA-256 of the Message-ID, `sha256:` prefixed. Pinned to one algorithm: correlating two reports of the same message is the whole point of the field, and two builds hashing differently make it useless. Absent when the message declared no Message-ID — a hash of the empty string would make every such message correlate with every other, which is worse than no value at all.",
+            "readOnly": true
+          },
+          "createdAt": {
+            "type": "integer",
+            "format": "int64",
+            "readOnly": true
+          },
+          "updatedAt": {
+            "type": "integer",
+            "format": "int64",
+            "readOnly": true
+          }
+        },
+        "description": "One quarantined message as the settings surface sees it."
+      },
       "RemitImap.RawMessageResponse": {
         "type": "object",
         "required": [
@@ -5887,6 +6176,10 @@
         ],
         "description": "Sender is wellknown: engagement counters crossed the promotion threshold"
       },
+      "String140": {
+        "type": "string",
+        "maxLength": 140
+      },
       "String256": {
         "type": "string",
         "maxLength": 256
@@ -5895,6 +6188,10 @@
         "type": "string",
         "maxLength": 512
       },
+      "String64": {
+        "type": "string",
+        "maxLength": 64
+      },
       "String800": {
         "type": "string",
         "maxLength": 800

package/package.json

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