@remit/api-openapi-spec 0.0.42 → 0.0.44

package/openapi.json

@@ -2812,7 +2812,7 @@
             "name": "senderTrust",
             "in": "query",
             "required": false,
-            "description": "Filter to messages whose From address has one of these trust levels. Off-row criterion, resolved by in-handler enrichment over the capped window.",
+            "description": "Filter to messages whose From address has one of these trust levels. Off-row criterion: resolved by enriching the rows this page read, not by a predicate over the mailbox, so `count` comes back absent whenever it is supplied.",
             "schema": {
               "type": "array",
               "items": {
@@ -2836,7 +2836,7 @@
             "name": "dkimMismatch",
             "in": "query",
             "required": false,
-            "description": "Filter on the DKIM-alignment signal (true = DKIM mismatch). Off-row criterion; rows without an authenticity signal never match.",
+            "description": "Filter on the DKIM-alignment signal (true = DKIM mismatch). Off-row criterion, like `senderTrust`: rows without an authenticity signal never match, and `count` comes back absent whenever it is supplied.",
             "schema": {
               "type": "boolean"
             }
@@ -2845,7 +2845,7 @@
             "name": "count",
             "in": "query",
             "required": false,
-            "description": "Include how many messages the query matches. Counted over the whole mailbox, independent of `limit`.",
+            "description": "Include how many messages the query matches, exactly, over the whole mailbox. Opt-in because it is a second read over the entire match set rather than a by-product of the page: ask for it on a deliberate act, never on a keystroke. Answered as absent — not as a page length — when the query carries `senderTrust` or `dkimMismatch`, which no predicate can count.",
             "schema": {
               "type": "boolean"
             }
@@ -2863,7 +2863,7 @@
             "name": "limit",
             "in": "query",
             "required": false,
-            "description": "Page size for the rows returned, capped server-side at 500. Bounds the read, not the `count`.",
+            "description": "Page size for the rows returned, capped server-side at 500. It bounds this page and nothing else: `count` is over the whole mailbox and does not move when this does.",
             "schema": {
               "type": "integer",
               "format": "int32"
@@ -4091,7 +4091,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` enrichment; `category` is served from the ThreadMessage row. 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.",
+        "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` enrichment; `category` is served from the ThreadMessage row. 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.\n\nRow filters: `category`, `unread` and `attachments` are columns on the ThreadMessage row, so each is a predicate inside the query rather than a pass over what a page returned. They compose with every mode above — INBOX, starred and search alike — and a page therefore comes back full of matches however rare the criterion is. This is what the cross-account collections need: filtering the pages a client happens to have loaded shows an empty list whenever the matching mail sits below the newest page (#308).\n\nCounting: `count=true` answers how many CONVERSATIONS match, over the whole scope and independent of `limit`. `results=false` omits the rows, which is how a header total is read without also paying for a page of mail. Conversations rather than rows because that is what this listing renders: a row is per mailbox, so the same mail filed in two folders is two rows sharing a `threadId`, and clients collapse by it. Counting rows would put a third number beside a list that shows a second one.",
         "parameters": [
           {
             "name": "continuationToken",
@@ -4135,6 +4135,54 @@
             "schema": {
               "type": "string"
             }
+          },
+          {
+            "name": "category",
+            "in": "query",
+            "required": false,
+            "description": "Filter to messages with one of these header-derived categories, as a union over the values given. Applied as a SQL predicate over the whole scope, so a page comes back full of matches however rare the category is. `uncategorized` is one of them — the pending state's name, never the absence of one.",
+            "schema": {
+              "type": "array",
+              "items": {
+                "$ref": "#/components/schemas/RemitImap.MessageCategory"
+              }
+            }
+          },
+          {
+            "name": "unread",
+            "in": "query",
+            "required": false,
+            "description": "When true, return only unread messages. A column on the row, so it narrows the query rather than the page.",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "attachments",
+            "in": "query",
+            "required": false,
+            "description": "When true, return only messages carrying an attachment. A column on the row, so it narrows the query rather than the page.",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "count",
+            "in": "query",
+            "required": false,
+            "description": "Include how many conversations the listing matches, exactly, over the whole scope. Opt-in because it is a second read over the entire match set rather than a by-product of the page: ask for it on a deliberate act, never on a keystroke.",
+            "schema": {
+              "type": "boolean"
+            }
+          },
+          {
+            "name": "results",
+            "in": "query",
+            "required": false,
+            "description": "Return matching rows. Default true; set false for a count-only response.",
+            "schema": {
+              "type": "boolean"
+            }
           }
         ],
         "responses": {
@@ -4143,26 +4191,7 @@
             "content": {
               "application/json": {
                 "schema": {
-                  "type": "object",
-                  "required": [
-                    "items"
-                  ],
-                  "properties": {
-                    "continuationToken": {
-                      "allOf": [
-                        {
-                          "$ref": "#/components/schemas/String800"
-                        }
-                      ],
-                      "description": "Opaque, server-minted cursor: absent means the first (or last) page, present means resume from here. Echo it back unchanged to fetch the next page. Every listing endpoint that accepts it rejects a token it cannot decode with 400 ValidationError rather than silently restarting from the first page (#136, #172)."
-                    },
-                    "items": {
-                      "type": "array",
-                      "items": {
-                        "$ref": "#/components/schemas/RemitImap.ThreadMessageResponse"
-                      }
-                    }
-                  }
+                  "$ref": "#/components/schemas/RemitImap.ThreadSearchResponse"
                 }
               }
             }
@@ -9666,10 +9695,10 @@
           "count": {
             "type": "integer",
             "format": "int32",
-            "description": "How many messages the query matches, over the whole mailbox and independent of `limit`. Present only when `count=true`. With `senderTrust` or `dkimMismatch` in the query the count is over the enriched window instead, since those are resolved off the row."
+            "description": "How much the query matches, over the whole scope. Exact: no page size bounds\nit, no cursor narrows it, so it is the same number on the first page and the\nlast. Present only when `count=true`.\n\nEach operation counts what it lists. `searchThreads` lists messages of one\nmailbox and counts messages. `listAllThreads` counts CONVERSATIONS across\nevery non-muted mailbox of every account — a thread holding two matching\nmessages counts once, and so does one message reachable through a real\nfolder and a virtual copy of it — because that is what the cross-account\nlisting renders after collapsing by `threadId`. A count that disagreed with\nthe rows beneath it would be a third number for the same set.\n\nAbsent when the query carries `senderTrust` or `dkimMismatch`, even with\n`count=true`. Those are resolved by enriching rows rather than by a\npredicate, so no exact count exists short of enriching the whole mailbox.\nAbsence says so; a page's post-filter length labelled `count` would be a\npage length presented as a total. A client with no number renders none."
           }
         },
-        "description": "Aggregate response for `searchThreads`. Carries the matching rows (`items`), a\npagination `continuationToken`, and an optional `count` of every message the\nquery matches. `items` is omitted when `results=false` (count-only); `count` is\npresent only when `count=true`. Thread-specific so the shared `ResultList<T>`\n(7 endpoints) stays untouched."
+        "description": "Aggregate response for the filterable thread listings — `searchThreads` and\n`listAllThreads`. Carries the matching rows (`items`), a pagination\n`continuationToken`, and an optional `count` of what the query matches.\n`items` is omitted when `results=false` (count-only); `count` is present only\nwhen `count=true`. Thread-specific so the shared `ResultList<T>` (7 endpoints)\nstays untouched.\n\n`listAllThreads` answers with this model rather than `ResultList<T>` for that\nsame reason: it needs the count field and the shared model cannot carry one.\nOne model over both operations rather than a second of the same shape, so a\nclient reading a filtered thread listing reads one response type whether the\nlisting is scoped to a mailbox or spans every account."
       },
       "RemitImap.TrustedFlag": {
         "type": "object",

package/package.json

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