@remit/api-openapi-spec 0.0.49 → 0.0.51

package/openapi.json

@@ -1367,7 +1367,7 @@
     "/addresses/{addressId}": {
       "patch": {
         "operationId": "AddressDetailOperations_updateAddress",
-        "description": "Update an address (currently: per-sender flags). Pass `flags: { <name>: null }` to remove a flag. Other flags are untouched.",
+        "description": "Update an address (currently: per-sender flags). Pass `flags` to set flags and `clearFlags: [\"<name>\"]` to remove them. Other flags are untouched.",
         "parameters": [
           {
             "name": "addressId",
@@ -2764,6 +2764,7 @@
             "name": "query",
             "in": "query",
             "required": false,
+            "description": "Free text to match against subject, From address and body text. Whitespace splits it into terms and every term must match, each against any one of the three. Body text is the stored preview the row carries — the first prose of the message with quoted replies removed — so a term further into a long message is not reached; a term the reader can see on the row is. Matching is accent- and case-insensitive substring, not tokenized full-text, so it neither stems nor ranks.",
             "schema": {
               "type": "string"
             }
@@ -2772,6 +2773,7 @@
             "name": "subject",
             "in": "query",
             "required": false,
+            "description": "Match the subject alone, where `query` matches all three fields at once.",
             "schema": {
               "type": "string"
             }
@@ -2780,6 +2782,7 @@
             "name": "from",
             "in": "query",
             "required": false,
+            "description": "Match the From address or display name alone, where `query` matches all three fields at once.",
             "schema": {
               "type": "string"
             }
@@ -4101,7 +4104,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.\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.",
+        "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, From address or body text 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 OR body. Matching is case-insensitive substring, not tokenized full-text, so it neither stems nor ranks.\n\nBody text is the stored preview the row carries — the first prose of the message with quoted replies removed, which is the same text the row renders under its subject. A term further into a long message is not reached; a term the reader can see on the row is.\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\nField filters: `from` and `subject` each match one field, which the single `query` cannot express — it matches both at once. They compose with `query` and with each other as further AND terms.\n\nAccount scope: `accountId` narrows every mode to the mailboxes of one account. The scope is built from the account's own mailboxes, so the listing, the count and the search all answer over the same set. Without it the listing is the cross-account aggregate.\n\nMuted senders: `muted=false` excludes rows whose From address is muted, `muted=true` returns only those, and omitting it filters nothing. Muting is a property of the address rather than a column on the row, so this is the one predicate that reaches outside the ThreadMessage table; it applies to the listing and the `count` alike, which is what lets a caller that hides muted mail state a number that is the size of what it renders.\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",
@@ -4141,11 +4144,47 @@
             "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.",
+            "description": "Free text to match against subject, From address and body text. 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"
             }
           },
+          {
+            "name": "from",
+            "in": "query",
+            "required": false,
+            "description": "Match the From address or display name against this text. One field, where `query` matches subject and From at once, so `from:` can be asked for on its own. Applied as a SQL predicate over the whole scope; it does not widen the scope the way `query` does.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "subject",
+            "in": "query",
+            "required": false,
+            "description": "Match the subject against this text. One field, where `query` matches subject and From at once, so `subject:` can be asked for on its own. Applied as a SQL predicate over the whole scope; it does not widen the scope the way `query` does.",
+            "schema": {
+              "type": "string"
+            }
+          },
+          {
+            "name": "accountId",
+            "in": "query",
+            "required": false,
+            "description": "Narrow every mode to one account's mailboxes. The listing, the search and the `count` all read the same narrowed scope, so a count is the size of what the caller renders rather than of the cross-account aggregate. An account the caller does not own, or one that is muted, holds no mailboxes here and matches nothing.",
+            "schema": {
+              "$ref": "#/components/schemas/UUID"
+            }
+          },
+          {
+            "name": "muted",
+            "in": "query",
+            "required": false,
+            "description": "Filter by whether the From address is muted. `false` excludes muted senders, `true` returns only them, and omitting it filters nothing. Muting lives on the Address rather than on the row, so this is evaluated against the sender's flags; it narrows the `count` exactly as it narrows the listing.",
+            "schema": {
+              "type": "boolean"
+            }
+          },
           {
             "name": "category",
             "in": "query",
@@ -4852,6 +4891,20 @@
         },
         "description": "Common metadata for sender-level flags"
       },
+      "RemitImap.AddressFlagKey": {
+        "type": "string",
+        "enum": [
+          "trusted",
+          "blocked",
+          "muted",
+          "vip",
+          "junkOnly",
+          "category",
+          "autoArchive",
+          "unsubscribed"
+        ],
+        "description": "Names a key of `AddressFlags` that a client may address in `PATCH /addresses/{addressId}`. `wellknown` is deliberately absent: it is server-owned, derived from engagement counters, and is never written or removed by a client."
+      },
       "RemitImap.AddressFlags": {
         "type": "object",
         "properties": {
@@ -7390,7 +7443,7 @@
             "$ref": "#/components/schemas/RemitImap.AddressFlagBase"
           }
         ],
-        "description": "Address was only ever seen on mail in a Junk folder: withheld from autocomplete suggestions until the account corresponds with it, flags it, or meets it on live mail. Written by sync and by the boot-time repair; clear it by patching this key to null."
+        "description": "Address was only ever seen on mail in a Junk folder: withheld from autocomplete suggestions until the account corresponds with it, flags it, or meets it on live mail. Written by sync and by the boot-time repair; clear it by naming this key in `UpdateAddressInput.clearFlags`."
       },
       "RemitImap.JunkOnlyFlagUpdate": {
         "type": "object",
@@ -7404,7 +7457,7 @@
             "$ref": "#/components/schemas/RemitImap.AddressFlagBaseUpdate"
           }
         ],
-        "description": "Address was only ever seen on mail in a Junk folder: withheld from autocomplete suggestions until the account corresponds with it, flags it, or meets it on live mail. Written by sync and by the boot-time repair; clear it by patching this key to null."
+        "description": "Address was only ever seen on mail in a Junk folder: withheld from autocomplete suggestions until the account corresponds with it, flags it, or meets it on live mail. Written by sync and by the boot-time repair; clear it by naming this key in `UpdateAddressInput.clearFlags`."
       },
       "RemitImap.LabelAction": {
         "type": "string",
@@ -10019,7 +10072,7 @@
               }
             ],
             "nullable": true,
-            "description": "Set to `null` to offer this address in autocomplete again"
+            "description": "Name this key in `clearFlags` to offer the address in autocomplete again"
           },
           "category": {
             "type": "object",
@@ -10049,7 +10102,7 @@
             "nullable": true
           }
         },
-        "description": "Patch payload for a single AddressFlags entry. Pass `null` for a flag key to remove that flag while leaving the others untouched."
+        "description": "Patch payload for AddressFlags entries. Sets the flags named here and leaves the others untouched. Removal travels in `UpdateAddressInput.clearFlags`, not here: the `null` alternative below is unreachable over OAS 3.0, where a nullable `$ref` emits as `allOf` and the request validator drops the `nullable` — and no `null` form exists at all for `category`, whose value is an enum with no false-equivalent member."
       },
       "RemitImap.UpdateAddressInput": {
         "type": "object",
@@ -10060,7 +10113,14 @@
                 "$ref": "#/components/schemas/RemitImap.UpdateAddressFlagsInput"
               }
             ],
-            "description": "Per-flag merge update; omitted flags are untouched, `null` removes the flag"
+            "description": "Per-flag merge update; omitted flags are untouched"
+          },
+          "clearFlags": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RemitImap.AddressFlagKey"
+            },
+            "description": "Flag keys to remove from the sparse map, leaving the rest untouched. This is the removal form for every flag, whatever its value type — clearing `category` reverts the sender to automatic classification. Applied after `flags`, so a key named in both ends up removed. Removing an absent flag succeeds and changes nothing."
           }
         },
         "description": "Input for updating an Address (currently flag updates only)"

package/package.json

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