@remit/api-openapi-spec 0.0.88 → 0.0.90

package/openapi.json

@@ -4365,7 +4365,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 enriching the rows this page read, not by a predicate over the mailbox, so `count` comes back absent whenever it is supplied.",
+            "description": "Filter to messages whose From address has one of these trust levels. Applied as a SQL predicate over the whole mailbox, so a page comes back full of matches.",
             "schema": {
               "type": "array",
               "items": {
@@ -4389,7 +4389,7 @@
             "name": "dkimMismatch",
             "in": "query",
             "required": false,
-            "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.",
+            "description": "Filter on the DKIM-alignment signal (true = DKIM mismatch). Applied as a SQL predicate over the whole mailbox; rows without an authenticity signal never match.",
             "schema": {
               "type": "boolean"
             }
@@ -4398,7 +4398,7 @@
             "name": "count",
             "in": "query",
             "required": false,
-            "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.",
+            "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.",
             "schema": {
               "type": "boolean"
             }
@@ -9461,7 +9461,7 @@
           "apiKeySaved",
           "enabled",
           "dailyLimit",
-          "savedAt",
+          "sources",
           "usage"
         ],
         "properties": {
@@ -9482,7 +9482,7 @@
           },
           "apiKeySaved": {
             "type": "boolean",
-            "description": "Whether an API key is stored for this provider."
+            "description": "Deprecated: read `sources.apiKey` instead. Whether an API key is saved or inherited from the deployment. Removed once reader-ui reads `sources`."
           },
           "enabled": {
             "type": "boolean",
@@ -9493,10 +9493,13 @@
             "format": "int32",
             "description": "The most classification calls per mail account per UTC day."
           },
-          "savedAt": {
-            "type": "integer",
-            "format": "int64",
-            "description": "When the provider, model, base URL or key was last saved, in epoch milliseconds (UTC)."
+          "sources": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RemitImap.ClassificationSources"
+              }
+            ],
+            "description": "Where each value comes from. A reader overrides one field by saving it, and inherits it again by saving it empty."
           },
           "usage": {
             "type": "array",
@@ -9506,7 +9509,7 @@
             "description": "Today's provider calls, one row per mail account of the account config."
           }
         },
-        "description": "The saved classification provider. The API key itself is never returned."
+        "description": "The classification provider in effect, saved or inherited from the deployment. No API key is ever returned."
       },
       "RemitImap.ClassificationCost": {
         "anyOf": [
@@ -9723,9 +9726,49 @@
           },
           {
             "$ref": "#/components/schemas/RemitImap.ClassificationConfigured"
+          },
+          {
+            "$ref": "#/components/schemas/RemitImap.ClassificationUnrunnable"
           }
         ]
       },
+      "RemitImap.ClassificationSources": {
+        "type": "object",
+        "required": [
+          "presetId",
+          "model",
+          "baseUrl",
+          "apiKey",
+          "enabled",
+          "dailyLimit"
+        ],
+        "properties": {
+          "presetId": {
+            "$ref": "#/components/schemas/RemitImap.ClassificationValueSource"
+          },
+          "model": {
+            "$ref": "#/components/schemas/RemitImap.ClassificationValueSource"
+          },
+          "baseUrl": {
+            "$ref": "#/components/schemas/RemitImap.ClassificationValueSource"
+          },
+          "apiKey": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RemitImap.ClassificationValueSource"
+              }
+            ],
+            "description": "`Saved` for a key the reader saved, `Deployment` for the deployment's key, `Default` for no key."
+          },
+          "enabled": {
+            "$ref": "#/components/schemas/RemitImap.ClassificationValueSource"
+          },
+          "dailyLimit": {
+            "$ref": "#/components/schemas/RemitImap.ClassificationValueSource"
+          }
+        },
+        "description": "Where each classification setting's value comes from."
+      },
       "RemitImap.ClassificationTestFailed": {
         "type": "object",
         "required": [
@@ -9783,15 +9826,15 @@
           },
           "model": {
             "type": "string",
-            "description": "The model to ask for. Empty means the preset's default model."
+            "description": "The model to ask for. Empty means the inherited model."
           },
           "baseUrl": {
             "type": "string",
-            "description": "The http or https base URL to call. Empty means the preset's default base URL."
+            "description": "The http or https base URL to call. Empty means the inherited base URL."
           },
           "apiKey": {
             "type": "string",
-            "description": "The provider's API key. Empty means the key saved for this preset."
+            "description": "The provider's API key. Empty means the key saved for this preset, or the deployment's key when the preset and base URL match the deployment's."
           }
         },
         "description": "The classification provider form as it stands, saved or not."
@@ -9842,6 +9885,37 @@
           }
         ]
       },
+      "RemitImap.ClassificationUnrunnable": {
+        "type": "object",
+        "required": [
+          "state",
+          "presetId",
+          "reason"
+        ],
+        "properties": {
+          "state": {
+            "type": "string",
+            "enum": [
+              "Unrunnable"
+            ]
+          },
+          "presetId": {
+            "$ref": "#/components/schemas/RemitImap.ClassificationPresetId"
+          },
+          "reason": {
+            "$ref": "#/components/schemas/RemitImap.ClassificationUnrunnableReason"
+          }
+        },
+        "description": "A classification provider is chosen but cannot run, so classification is off."
+      },
+      "RemitImap.ClassificationUnrunnableReason": {
+        "type": "string",
+        "enum": [
+          "NoBaseUrl",
+          "NoApiKey"
+        ],
+        "description": "Why a classification provider cannot run."
+      },
       "RemitImap.ClassificationUsage": {
         "type": "object",
         "required": [
@@ -9876,6 +9950,15 @@
         },
         "description": "One mail account's classification calls today."
       },
+      "RemitImap.ClassificationValueSource": {
+        "type": "string",
+        "enum": [
+          "Saved",
+          "Deployment",
+          "Default"
+        ],
+        "description": "Where a classification setting's value comes from."
+      },
       "RemitImap.ConfigDescriptionResponse": {
         "type": "object",
         "required": [
@@ -14184,7 +14267,7 @@
           "count": {
             "type": "integer",
             "format": "int32",
-            "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": "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."
           }
         },
         "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."
@@ -14831,29 +14914,29 @@
                 "$ref": "#/components/schemas/RemitImap.ClassificationPresetId"
               }
             ],
-            "description": "Save a classification provider. Saving another preset deletes the stored key. Without it, the classification fields below apply to the saved provider."
+            "description": "Save a classification provider. Saving another preset deletes the stored key, model and base URL. Without it, the classification fields below apply to the provider in effect, saved or inherited from the deployment."
           },
           "classificationModel": {
             "type": "string",
-            "description": "The model to ask for. Empty means the preset's default model."
+            "description": "The model to ask for. Empty deletes the saved model, so it is inherited again."
           },
           "classificationBaseUrl": {
             "type": "string",
-            "description": "The http or https base URL to call. Empty means the preset's default base URL. Refused with 400 `invalid_classification_base_url` when it is not a URL, or when the preset has no default base URL and none is given."
+            "description": "The http or https base URL to call. Empty deletes the saved base URL, so it is inherited again. Refused with 400 `invalid_classification_base_url` when it is not a URL, or when no base URL is saved, inherited or given by the preset."
           },
           "classificationApiKey": {
             "type": "string",
-            "description": "The provider's API key. Write-only: stored encrypted and never returned. Refused with 400 `classification_api_key_required` when the preset needs a key and none is stored for it."
+            "description": "The provider's API key. Write-only: stored encrypted and never returned. Refused with 400 `classification_api_key_required` when the preset needs a key and none is saved, or inherited from the deployment for the same preset and base URL."
           },
           "classificationEnabled": {
             "type": "boolean",
-            "description": "Switch classification on or off. Switching on with no saved provider is refused with 400 `classification_not_configured`; switching off keeps the provider and key."
+            "description": "Switch classification on or off. Switching on with no provider in effect is refused with 400 `classification_not_configured`; switching off keeps the provider and key."
           },
           "classificationDailyLimit": {
             "type": "integer",
             "format": "int32",
             "minimum": 1,
-            "description": "The most classification calls per mail account per UTC day. Needs a saved provider."
+            "description": "The most classification calls per mail account per UTC day. Needs a provider in effect, saved or inherited."
           }
         },
         "description": "A change to the caller's settings. Every field is optional and absence means untouched."
@@ -14891,7 +14974,7 @@
                 "$ref": "#/components/schemas/RemitImap.ClassificationSettings"
               }
             ],
-            "description": "The saved classification provider, or `NotConfigured`."
+            "description": "The classification provider in effect, `Unrunnable` when one is chosen but cannot run, or `NotConfigured`."
           }
         },
         "description": "The caller's own settings: choices that belong to the person rather than to\none mail account. Each field is stored as an `AccountSetting` row of the\naccount config and read back here, so a setting added later is one more\nfield on this resource rather than one more operation."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/api-openapi-spec",
-  "version": "0.0.88",
+  "version": "0.0.90",
   "description": "Remit API OpenAPI 3 document, generated from TypeSpec, and its precompiled request validators.",
   "exports": {
     ".": "./openapi.json",