@remit/api-openapi-spec 0.0.84 → 0.0.86

package/openapi.json

@@ -6522,6 +6522,100 @@
         }
       }
     },
+    "/settings/classification-provider": {
+      "delete": {
+        "operationId": "UserSettingsOperations_clearClassificationProvider",
+        "description": "Delete the saved classification provider, its key and every classification setting. Classification is then off. Answers with every setting as it now stands.",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RemitImap.UserSettingsResponse"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "The request carried no usable credential. `code` is `unauthorized`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        },
+        "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"
+          }
+        }
+      }
+    },
+    "/settings/classification-test": {
+      "post": {
+        "operationId": "UserSettingsOperations_testClassificationProvider",
+        "description": "Classify one built-in sample message with the form values, saved or not, and answer with the label or the failure. An empty key uses the saved key. Saved settings stay as they were, and the call counts toward no daily limit.",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RemitImap.ClassificationTestResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "The request was refused as malformed or contradictory. `code` is\n`invalid_request` where nothing more specific is known, and the refusal's own\ntoken where there is one.\n\nThe calendar surface answers with the reason it read the request by:\n`invalid_window`, `invalid_scope`, `invalid_url_segment`, `url_segment_taken`,\n`unknown_time_zone` and `default_calendar_undeletable` on the collection and\nthe query, and, for a VCALENDAR it could not accept,\n`malformed_icalendar`, `not_a_calendar`, `unsupported_component`, `no_event`,\n`no_master_event`, `multiple_master_events`, `missing_uid`, `mismatched_uid`,\n`missing_dt_start`, `backwards_end`, `invalid_date_time`,\n`invalid_recurrence_rule`, `missing_recurrence_id`, `not_recurring`,\n`unknown_occurrence` and `unmovable_recurrence_rule`. The outbox answers `mail_sync_off` to a\nsend from an account whose `syncedServices` leave out `Mail`, with the\naccount in `details.accountId`.\n\n`errors` is present only when the request failed schema validation before any\nhandler ran, and names every field that was refused.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ValidationError"
+                }
+              }
+            }
+          },
+          "401": {
+            "description": "The request carried no usable credential. `code` is `unauthorized`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RemitImap.ClassificationTestInput"
+              }
+            }
+          }
+        },
+        "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"
+          }
+        }
+      }
+    },
     "/settings/default-invitation-sender": {
       "delete": {
         "operationId": "UserSettingsOperations_clearDefaultInvitationSender",
@@ -9348,6 +9442,360 @@
         ],
         "description": "Category override for auto-classification"
       },
+      "RemitImap.ClassificationAdapterShape": {
+        "type": "string",
+        "enum": [
+          "DecisionApi",
+          "ChatJsonSchema",
+          "JinaClassify"
+        ],
+        "description": "The request shape a classification provider speaks. `DecisionApi` returns a calibrated probability per label; `ChatJsonSchema` is an OpenAI-compatible chat completion constrained to the label enum; `JinaClassify` is Jina's `/v1/classify`."
+      },
+      "RemitImap.ClassificationConfigured": {
+        "type": "object",
+        "required": [
+          "state",
+          "presetId",
+          "model",
+          "baseUrl",
+          "apiKeySaved",
+          "enabled",
+          "dailyLimit",
+          "savedAt"
+        ],
+        "properties": {
+          "state": {
+            "type": "string",
+            "enum": [
+              "Configured"
+            ]
+          },
+          "presetId": {
+            "$ref": "#/components/schemas/RemitImap.ClassificationPresetId"
+          },
+          "model": {
+            "type": "string"
+          },
+          "baseUrl": {
+            "type": "string"
+          },
+          "apiKeySaved": {
+            "type": "boolean",
+            "description": "Whether an API key is stored for this provider."
+          },
+          "enabled": {
+            "type": "boolean",
+            "description": "Whether classification runs."
+          },
+          "dailyLimit": {
+            "type": "integer",
+            "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)."
+          }
+        },
+        "description": "The saved classification provider. The API key itself is never returned."
+      },
+      "RemitImap.ClassificationFailureKind": {
+        "type": "string",
+        "enum": [
+          "Unauthorized",
+          "ModelNotFound",
+          "RateLimited",
+          "Rejected",
+          "ProviderError",
+          "Unreachable",
+          "TimedOut",
+          "Unparseable"
+        ],
+        "description": "Why a classification provider call gave no usable answer."
+      },
+      "RemitImap.ClassificationField": {
+        "type": "string",
+        "enum": [
+          "ApiKey",
+          "Model",
+          "BaseUrl"
+        ],
+        "description": "The classification provider form field a failure points at."
+      },
+      "RemitImap.ClassificationLabel": {
+        "type": "string",
+        "enum": [
+          "Spam",
+          "Phishing",
+          "Priority",
+          "Personal",
+          "Newsletter",
+          "Marketing",
+          "Automated",
+          "Transactional",
+          "Social"
+        ],
+        "description": "A label a classification provider picks for a message: the junk verdicts, priority, and the message categories."
+      },
+      "RemitImap.ClassificationNoPrice": {
+        "type": "object",
+        "required": [
+          "state"
+        ],
+        "properties": {
+          "state": {
+            "type": "string",
+            "enum": [
+              "NoPrice"
+            ]
+          }
+        },
+        "description": "A classification preset with no price to show: self-hosted, or a price the provider sets per model."
+      },
+      "RemitImap.ClassificationNotConfigured": {
+        "type": "object",
+        "required": [
+          "state"
+        ],
+        "properties": {
+          "state": {
+            "type": "string",
+            "enum": [
+              "NotConfigured"
+            ]
+          }
+        },
+        "description": "No classification provider is saved, so classification is off."
+      },
+      "RemitImap.ClassificationPreset": {
+        "type": "object",
+        "required": [
+          "presetId",
+          "label",
+          "group",
+          "adapterShape",
+          "defaultModel",
+          "needsKey",
+          "price"
+        ],
+        "properties": {
+          "presetId": {
+            "$ref": "#/components/schemas/RemitImap.ClassificationPresetId"
+          },
+          "label": {
+            "type": "string"
+          },
+          "group": {
+            "$ref": "#/components/schemas/RemitImap.ClassificationPresetGroup"
+          },
+          "adapterShape": {
+            "$ref": "#/components/schemas/RemitImap.ClassificationAdapterShape"
+          },
+          "defaultBaseUrl": {
+            "type": "string",
+            "description": "The base URL used when the reader leaves it empty. Absent when a save has to name one in `classificationBaseUrl`."
+          },
+          "defaultModel": {
+            "type": "string",
+            "description": "The model used when the reader leaves it empty."
+          },
+          "needsKey": {
+            "type": "boolean",
+            "description": "Whether a save needs `classificationApiKey`."
+          },
+          "price": {
+            "$ref": "#/components/schemas/RemitImap.ClassificationPrice"
+          }
+        },
+        "description": "A classification provider the reader can pick."
+      },
+      "RemitImap.ClassificationPresetGroup": {
+        "type": "string",
+        "enum": [
+          "Hosted",
+          "Custom",
+          "Local"
+        ],
+        "description": "How a settings screen groups the classification presets. `Hosted` is a named provider, `Custom` an endpoint the reader names, `Local` a model on the reader's own machine."
+      },
+      "RemitImap.ClassificationPresetId": {
+        "type": "string",
+        "enum": [
+          "Jev",
+          "Jina",
+          "Mistral",
+          "Gemini",
+          "OpenAiCompatible",
+          "Local"
+        ],
+        "description": "A classification provider preset: a known provider with its adapter shape, default base URL and default model."
+      },
+      "RemitImap.ClassificationPrice": {
+        "anyOf": [
+          {
+            "$ref": "#/components/schemas/RemitImap.ClassificationPriced"
+          },
+          {
+            "$ref": "#/components/schemas/RemitImap.ClassificationNoPrice"
+          }
+        ]
+      },
+      "RemitImap.ClassificationPriced": {
+        "type": "object",
+        "required": [
+          "state",
+          "currency",
+          "perMillionInputTokens"
+        ],
+        "properties": {
+          "state": {
+            "type": "string",
+            "enum": [
+              "Priced"
+            ]
+          },
+          "currency": {
+            "type": "string",
+            "enum": [
+              "USD"
+            ],
+            "description": "ISO 4217 currency of `perMillionInputTokens`."
+          },
+          "perMillionInputTokens": {
+            "type": "number",
+            "format": "double",
+            "description": "Price of one million input tokens. Output tokens are not charged."
+          }
+        },
+        "description": "A classification preset that has a known price per million input tokens."
+      },
+      "RemitImap.ClassificationSettings": {
+        "anyOf": [
+          {
+            "$ref": "#/components/schemas/RemitImap.ClassificationNotConfigured"
+          },
+          {
+            "$ref": "#/components/schemas/RemitImap.ClassificationConfigured"
+          }
+        ]
+      },
+      "RemitImap.ClassificationTestFailed": {
+        "type": "object",
+        "required": [
+          "state",
+          "latencyMs",
+          "kind",
+          "fix"
+        ],
+        "properties": {
+          "state": {
+            "type": "string",
+            "enum": [
+              "Failed"
+            ]
+          },
+          "latencyMs": {
+            "type": "integer",
+            "format": "int32",
+            "description": "How long the provider call took, in milliseconds."
+          },
+          "status": {
+            "type": "integer",
+            "format": "int32",
+            "description": "The HTTP status the provider answered with. Absent when no answer arrived."
+          },
+          "kind": {
+            "$ref": "#/components/schemas/RemitImap.ClassificationFailureKind"
+          },
+          "field": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RemitImap.ClassificationField"
+              }
+            ],
+            "description": "The form field to change. Absent when no field can fix it: a rate limit or a provider error."
+          },
+          "fix": {
+            "type": "string",
+            "description": "What to change so the next test passes."
+          }
+        },
+        "description": "The provider call gave no usable answer."
+      },
+      "RemitImap.ClassificationTestInput": {
+        "type": "object",
+        "required": [
+          "presetId",
+          "model",
+          "baseUrl",
+          "apiKey"
+        ],
+        "properties": {
+          "presetId": {
+            "$ref": "#/components/schemas/RemitImap.ClassificationPresetId"
+          },
+          "model": {
+            "type": "string",
+            "description": "The model to ask for. Empty means the preset's default model."
+          },
+          "baseUrl": {
+            "type": "string",
+            "description": "The http or https base URL to call. Empty means the preset's default base URL."
+          },
+          "apiKey": {
+            "type": "string",
+            "description": "The provider's API key. Empty means the key saved for this preset."
+          }
+        },
+        "description": "The classification provider form as it stands, saved or not."
+      },
+      "RemitImap.ClassificationTestPassed": {
+        "type": "object",
+        "required": [
+          "state",
+          "latencyMs",
+          "label",
+          "confidence"
+        ],
+        "properties": {
+          "state": {
+            "type": "string",
+            "enum": [
+              "Passed"
+            ]
+          },
+          "latencyMs": {
+            "type": "integer",
+            "format": "int32",
+            "description": "How long the provider call took, in milliseconds."
+          },
+          "label": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RemitImap.ClassificationLabel"
+              }
+            ],
+            "description": "The label the provider chose for the sample message."
+          },
+          "confidence": {
+            "type": "number",
+            "format": "double",
+            "description": "The provider's confidence in `label`, between 0 and 1."
+          }
+        },
+        "description": "The provider classified the sample message."
+      },
+      "RemitImap.ClassificationTestResponse": {
+        "anyOf": [
+          {
+            "$ref": "#/components/schemas/RemitImap.ClassificationTestPassed"
+          },
+          {
+            "$ref": "#/components/schemas/RemitImap.ClassificationTestFailed"
+          }
+        ]
+      },
       "RemitImap.ConfigDescriptionResponse": {
         "type": "object",
         "required": [
@@ -14296,6 +14744,36 @@
               }
             ],
             "description": "The account invitations go out from by default. Refused with 400 `unknown_sender` when it is not an account of the caller's account config that sends mail. Cleared with `clearDefaultInvitationSender`."
+          },
+          "classificationPresetId": {
+            "allOf": [
+              {
+                "$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."
+          },
+          "classificationModel": {
+            "type": "string",
+            "description": "The model to ask for. Empty means the preset's default model."
+          },
+          "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."
+          },
+          "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."
+          },
+          "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."
+          },
+          "classificationDailyLimit": {
+            "type": "integer",
+            "format": "int32",
+            "minimum": 1,
+            "description": "The most classification calls per mail account per UTC day. Needs a saved provider."
           }
         },
         "description": "A change to the caller's settings. Every field is optional and absence means untouched."
@@ -14303,7 +14781,9 @@
       "RemitImap.UserSettingsResponse": {
         "type": "object",
         "required": [
-          "defaultInvitationSenderChosen"
+          "defaultInvitationSenderChosen",
+          "classificationPresets",
+          "classification"
         ],
         "properties": {
           "defaultInvitationSenderAccountId": {
@@ -14317,6 +14797,21 @@
           "defaultInvitationSenderChosen": {
             "type": "boolean",
             "description": "Whether `defaultInvitationSenderAccountId` is the reader's own choice rather than the account an event is on."
+          },
+          "classificationPresets": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RemitImap.ClassificationPreset"
+            },
+            "description": "Every classification provider the reader can pick."
+          },
+          "classification": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RemitImap.ClassificationSettings"
+              }
+            ],
+            "description": "The saved classification provider, 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.84",
+  "version": "0.0.86",
   "description": "Remit API OpenAPI 3 document, generated from TypeSpec, and its precompiled request validators.",
   "exports": {
     ".": "./openapi.json",