@remit/api-openapi-spec 0.0.4 → 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",
@@ -2136,7 +2163,7 @@
     "/threads": {
       "get": {
         "operationId": "UnifiedThreadOperations_listAllThreads",
-        "description": "List threads across all non-muted accounts of the caller, ordered by sentDate desc. Each row carries an attached `accountId` (derived from a mailboxId→accountId map at read time) plus the usual `senderTrust`/`category` enrichment. Served by the `byDate` LSI1 (pk = the caller's account config), so the caller can never see another account config's threads.\n\nINBOX scope: results are filtered to each account's top-level INBOX, matched by exact path `fullPath === \"INBOX\"` (RFC 6154 defines no Inbox special-use). By design this excludes namespaced sub-paths like `INBOX/Receipts` and non-English server primaries — the unified inbox is each account's primary INBOX, not its sub-folders. Soft-deleted rows are also excluded.\n\nMute exclusion: muted accounts and muted mailboxes are excluded. The inbox/mute filter set is rebuilt per page from live state, so muting/unmuting a mailbox mid-pagination takes effect on the next page (never retroactively).\n\nPagination: pass the returned `continuationToken` to fetch the next page; keep paging until it is absent. In the default (INBOX) mode the INBOX/deleted filter is applied after the index read with a bounded read window per request, so a page may return FEWER than `limit` rows while still carrying a `continuationToken` — treat the presence of the token (not a full page) as the \"more results\" signal. No rows are skipped or duplicated across pages.\n\nStarred mode (`starred=true`): served by the `byStarred` LSI4 instead. A star is a marker on the mail rather than on its placement, so the INBOX scope does not apply and a starred thread in Archive is still returned. Excluded are muted and soft-deleted rows as usual, plus the folders a star never surfaces from: Junk, Trash, and Gmail's All Mail (a second copy of everything, whose rows would otherwise double every starred message). All filtering happens in the query, so a page is short only when the results are exhausted. Rows are per mailbox: the same mail filed in two folders is two rows sharing a `threadId`, and a client rendering one row per conversation collapses by `threadId` across the pages it has accumulated.",
+        "description": "List threads across all non-muted accounts of the caller, ordered by sentDate desc. Each row carries an attached `accountId` (derived from a mailboxId→accountId map at read time) plus the usual `senderTrust`/`category` enrichment. Served by the `byDate` LSI1 (pk = the caller's account config), so the caller can never see another account config's threads.\n\nINBOX scope: results are filtered to each account's top-level INBOX, matched by exact path `fullPath === \"INBOX\"` (RFC 6154 defines no Inbox special-use). By design this excludes namespaced sub-paths like `INBOX/Receipts` and non-English server primaries — the unified inbox is each account's primary INBOX, not its sub-folders. Soft-deleted rows are also excluded.\n\nMute exclusion: muted accounts and muted mailboxes are excluded. The inbox/mute filter set is rebuilt per page from live state, so muting/unmuting a mailbox mid-pagination takes effect on the next page (never retroactively).\n\nPagination: pass the returned `continuationToken` to fetch the next page; keep paging until it is absent. In the default (INBOX) mode the INBOX/deleted filter is applied after the index read with a bounded read window per request, so a page may return FEWER than `limit` rows while still carrying a `continuationToken` — treat the presence of the token (not a full page) as the \"more results\" signal. No rows are skipped or duplicated across pages.\n\nStarred mode (`starred=true`): served by the `byStarred` LSI4 instead. A star is a marker on the mail rather than on its placement, so the INBOX scope does not apply and a starred thread in Archive is still returned. Excluded are muted and soft-deleted rows as usual, plus the folders a star never surfaces from: Junk, Trash, and Gmail's All Mail (a second copy of everything, whose rows would otherwise double every starred message). All filtering happens in the query, so a page is short only when the results are exhausted. Rows are per mailbox: the same mail filed in two folders is two rows sharing a `threadId`, and a client rendering one row per conversation collapses by `threadId` across the pages it has accumulated.\n\nSearch mode (`query=<text>`): the listing widens past the INBOX scope to every non-muted mailbox of every non-muted account, and returns only rows whose subject or From address matches the text. This is the unscoped search of the daily brief: one query reaching every folder of every account. Whitespace splits the text into terms and every term must match (AND), each against subject OR From. Matching is case-insensitive substring, not tokenized full-text, so it neither stems nor ranks.\n\nSearch scope: every non-muted mailbox EXCEPT Trash. The scope is defined by what it excludes, so anything a server offers that is not on that list is searched — Spam, Drafts and Gmail's virtual folders (All Mail, Starred, Important) included. Spam is deliberately in scope: the point of an unscoped search is that it reaches the folders the user did not think to look in. Combining `query` with `starred=true` searches the starred scope instead.\n\nDuplicates: a virtual folder holds a second copy of mail that also lives in a real folder, so a backend keying a row by its mailbox returns the same message several times — a starred, Important Gmail inbox message four times. The extras are dropped from the response by message identity, keeping the copy in a real folder, so one message is one row. This is done after the read rather than by barring those folders from the scope, because a message whose only stored row sits in one of them would otherwise become unfindable. De-duplication is per page: a duplicate split across a page boundary survives, the same caveat that applies to collapsing by `threadId`. A page may therefore return fewer rows than `limit` while still carrying a `continuationToken`.\n\nSearch mode and pagination: `limit` is a page size over MATCHES, capped server-side at 500. A page may be shorter than `limit` for two reasons — the matches ran out, or duplicates were dropped from it — so treat the presence of a `continuationToken` as the \"more results\" signal rather than a full page. There is no total match count; page until the token is absent.\n\nWhat a row is in search mode: one per message, not one per mailbox. This differs from the starred mode above, where the same mail filed in two folders is two rows sharing a `threadId`. Collapsing by `threadId` is still a client's job if it renders one row per CONVERSATION, since distinct messages in one thread remain distinct rows here.\n\nCallers that omit `query` are unaffected: the INBOX (and starred) listings behave exactly as before.",
         "parameters": [
           {
             "name": "continuationToken",
@@ -2171,6 +2198,15 @@
             "schema": {
               "type": "boolean"
             }
+          },
+          {
+            "name": "query",
+            "in": "query",
+            "required": false,
+            "description": "Free text to match against subject and From address. Supplying it switches the listing into search mode, which widens the scope past INBOX to every non-muted mailbox — see the operation description. Omitting it leaves the listing unchanged.",
+            "schema": {
+              "type": "string"
+            }
           }
         ],
         "responses": {
@@ -4882,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": [
@@ -5878,6 +6177,10 @@
         ],
         "description": "Sender is wellknown: engagement counters crossed the promotion threshold"
       },
+      "String140": {
+        "type": "string",
+        "maxLength": 140
+      },
       "String256": {
         "type": "string",
         "maxLength": 256
@@ -5886,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.4",
+  "version": "0.0.6",
   "description": "Remit API OpenAPI 3 document, generated from TypeSpec.",
   "exports": {
     ".": "./openapi.json",