@remit/api-openapi-spec 0.0.35 → 0.0.37

package/openapi.json

@@ -1467,6 +1467,63 @@
         }
       }
     },
+    "/config/import": {
+      "post": {
+        "operationId": "ConfigOperations_importConfig",
+        "description": "Validate, or validate and apply, a config document. `mode: validate` (the default) writes nothing and returns the same report an apply would. `onExisting: abort` (the default) refuses with 409 when this configuration already holds accounts, labels, filters or address flags. Nothing is written until the whole document has validated; a write failure after that aborts the remainder and the report names exactly what landed. Imported accounts arrive inactive with `connectionState: credentials_missing` (or `reauth_required` for OAuth) - the credentials the file deliberately omits are re-entered per account afterwards.",
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "The request has succeeded.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/RemitImap.ConfigImportReport"
+                }
+              }
+            }
+          },
+          "400": {
+            "description": "Validation error response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          },
+          "409": {
+            "description": "The import was refused because this configuration is not empty. The body is\nflat: `code`, `message` and `details` sit at the top level.\n\n`code: \"config_not_empty\"` — the configuration already holds an account, a\nlabel, a filter or an address flag. `details` names how many of each. Re-send\nwith `onExisting: merge` to upsert instead.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
+          }
+        },
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/RemitImap.ImportConfigInput"
+              }
+            }
+          }
+        },
+        "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"
+          }
+        }
+      }
+    },
     "/mailboxes/{mailboxId}/threads": {
       "get": {
         "operationId": "ThreadOperations_listThreads",
@@ -1876,6 +1933,16 @@
                 }
               }
             }
+          },
+          "409": {
+            "description": "The same flat 409 body, for a message whose folder and uid do not name the same message.\n\n`code: \"message_placement_unsettled\"` — the message is mid-move, so its row names the destination folder while its uid still belongs to the source; acting on that pair would hit whatever the destination holds at that uid. `details` carries `accountId`, `messageId` and `reason`, one of: `in_flight` (the move is still running, and the same request succeeds once it confirms) or `unverified` (the move gave up without confirming, so where the message sits is unknown until the folder is resynced).",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/ApiError"
+                }
+              }
+            }
           }
         },
         "requestBody": {
@@ -1915,7 +1982,7 @@
             }
           },
           "409": {
-            "description": "An action was refused because the folder role it needs is not settled. The body is flat: `code`, `message` and `details` sit at the top level, which is what the API emits. Clients branch on `code` and word their prompt from `details`, never from `message`.\n\n`code: \"folder_role_unresolved\"` — no folder holds the role this action needs. `details` carries `role`, `accountId`, and `reason`, one of: `none` (the account has no candidate folder), `stale` (the folder the user appointed is gone from the mail server), `unconfirmed` (a folder matches by name, but neither the user nor the server's own flag ever said it holds the role).",
+            "description": "The same flat 409 body, with the two codes this endpoint can answer with.\n\n`code: \"folder_role_unresolved\"` — as everywhere else, with `details` carrying `role`, `accountId` and `reason`.\n\n`code: \"message_placement_unsettled\"` — as `MessagePlacementConflict`, with `details` carrying `accountId`, `messageId` and `reason`.",
             "content": {
               "application/json": {
                 "schema": {
@@ -4011,6 +4078,14 @@
               "$ref": "#/components/schemas/RemitImap.AccountResponse"
             },
             "description": "Associated email accounts"
+          },
+          "pendingImport": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RemitImap.PendingConfigImport"
+              }
+            ],
+            "description": "Absent unless a configuration import is still waiting on folders IMAP has not produced yet (#1021). Nothing polls a separate route for it."
           }
         },
         "description": "Full configuration description including accounts"
@@ -4035,6 +4110,113 @@
         },
         "description": "A configuration export: one versioned document carrying every user decision this instance holds, and no credential."
       },
+      "RemitImap.ConfigImportItemReport": {
+        "type": "object",
+        "required": [
+          "section",
+          "key",
+          "verdict"
+        ],
+        "properties": {
+          "section": {
+            "type": "string",
+            "description": "Which section: accounts | labels | filters | addressFlags | settings"
+          },
+          "key": {
+            "type": "string",
+            "description": "Human key of the item - an email, a label name, a filter name"
+          },
+          "verdict": {
+            "type": "string",
+            "description": "created | updated | unchanged | skipped | rejected"
+          },
+          "reason": {
+            "type": "string",
+            "description": "Why, when the verdict is skipped or rejected"
+          }
+        },
+        "description": "What became of one item in the submitted document"
+      },
+      "RemitImap.ConfigImportMode": {
+        "type": "string",
+        "enum": [
+          "validate",
+          "apply"
+        ],
+        "description": "Whether an import writes. The default is the dry run, so the wizard can show what a file would do before anything lands."
+      },
+      "RemitImap.ConfigImportOnExisting": {
+        "type": "string",
+        "enum": [
+          "abort",
+          "merge"
+        ],
+        "description": "What an import does when the configuration it is importing into is not empty."
+      },
+      "RemitImap.ConfigImportReport": {
+        "type": "object",
+        "required": [
+          "valid",
+          "schemaVersion",
+          "applied",
+          "items",
+          "errors",
+          "warnings",
+          "accountsNeedingCredentials"
+        ],
+        "properties": {
+          "importId": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UUID"
+              }
+            ],
+            "description": "Import identity; present on apply, so the folder bindings this import is still waiting on can be named later"
+          },
+          "valid": {
+            "type": "boolean",
+            "description": "Whether the document is importable at all"
+          },
+          "schemaVersion": {
+            "type": "integer",
+            "format": "int32",
+            "description": "Schema version of the submitted document"
+          },
+          "applied": {
+            "type": "boolean",
+            "description": "Whether anything was written"
+          },
+          "items": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/RemitImap.ConfigImportItemReport"
+            },
+            "description": "Per-item verdicts"
+          },
+          "errors": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ApiError"
+            },
+            "description": "Blocking problems; non-empty means nothing was written"
+          },
+          "warnings": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/ApiError"
+            },
+            "description": "Non-blocking notes - e.g. a folder path this account does not hold yet"
+          },
+          "accountsNeedingCredentials": {
+            "type": "array",
+            "items": {
+              "$ref": "#/components/schemas/UUID"
+            },
+            "description": "Accounts that landed needing a credential before they can sync"
+          }
+        },
+        "description": "The outcome of a validate or an apply. A rejected document is an answer, not a failure: `valid` is false and `errors` says why."
+      },
       "RemitImap.ConnectionState": {
         "type": "string",
         "enum": [
@@ -4042,7 +4224,8 @@
           "authenticated",
           "selected",
           "logout",
-          "reauth_required"
+          "reauth_required",
+          "credentials_missing"
         ],
         "description": "IMAP connection states per RFC 9051 Section 3"
       },
@@ -4935,6 +5118,38 @@
         ],
         "description": "Where a resolved FolderAppointment came from. Total and required: every role carries one, so a surface can tell a folder somebody chose from a folder reader guessed without inferring it from which fields happen to be present."
       },
+      "RemitImap.ImportConfigInput": {
+        "type": "object",
+        "required": [
+          "document"
+        ],
+        "properties": {
+          "mode": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RemitImap.ConfigImportMode"
+              }
+            ],
+            "description": "`validate` writes nothing; `apply` writes.",
+            "default": "validate"
+          },
+          "onExisting": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/RemitImap.ConfigImportOnExisting"
+              }
+            ],
+            "description": "What to do when this configuration is not empty.",
+            "default": "abort"
+          },
+          "document": {
+            "type": "object",
+            "additionalProperties": {},
+            "description": "The config document, as exported."
+          }
+        },
+        "description": "Request body for POST /config/import"
+      },
       "RemitImap.JunkOnlyFlag": {
         "type": "object",
         "required": [
@@ -6203,6 +6418,31 @@
         ],
         "description": "Status of an outbox message in the send queue"
       },
+      "RemitImap.PendingConfigImport": {
+        "type": "object",
+        "required": [
+          "importId",
+          "folderPaths"
+        ],
+        "properties": {
+          "importId": {
+            "allOf": [
+              {
+                "$ref": "#/components/schemas/UUID"
+              }
+            ],
+            "description": "The import still waiting"
+          },
+          "folderPaths": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            },
+            "description": "The IMAP paths no mailbox answers to yet, deduplicated"
+          }
+        },
+        "description": "An import that is still waiting for IMAP discovery to produce the folders its\nfile named. The folder appointed to a role, a folder's own display name or\nmute, and a filter's move destination are all bound by path; a path this\naccount does not hold yet is kept, not guessed, and bound the moment discovery\nfinds it."
+      },
       "RemitImap.PlacementAction": {
         "type": "string",
         "enum": [

package/package.json

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