@remit/api-openapi-spec 0.0.5 → 0.0.6

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,269 @@
         ],
         "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": [
+          "UnterminatedMultipartBoundary",
+          "UnknownCharset",
+          "TruncatedBody"
+        ],
+        "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. Grows with the same narrowing that grows QuarantineFailureStage."
+      },
+      "RemitImap.QuarantineFailureStage": {
+        "type": "string",
+        "enum": [
+          "BodyParse"
+        ],
+        "description": "The pipeline step that refused a quarantined message.\n\nOne member. No catch site on the sync path can currently tell a parse failure\nfrom an infrastructure failure: the per-message frame in `body-sync.ts` wraps\nthe S3 body write, the parsed-body cache write, the body-part upserts, the\nplacement move and the label and counter writes alongside the `simpleParser`\ncall, and filters only connection drops out of it. A stage is added when a\ntry block is narrowed far enough to attribute it, never ahead of that — an\nenum member that reached stored rows cannot be walked back."
+      },
+      "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 +6177,10 @@
         ],
         "description": "Sender is wellknown: engagement counters crossed the promotion threshold"
       },
+      "String140": {
+        "type": "string",
+        "maxLength": 140
+      },
       "String256": {
         "type": "string",
         "maxLength": 256
@@ -5895,6 +6189,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.6",
   "description": "Remit API OpenAPI 3 document, generated from TypeSpec.",
   "exports": {
     ".": "./openapi.json",