@remit/api-openapi-types 0.0.39 → 0.0.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/api-openapi-types",
-  "version": "0.0.39",
+  "version": "0.0.40",
   "type": "module",
   "main": "types.d.ts",
   "types": "types.d.ts",

package/types.d.ts

@@ -64,7 +64,7 @@ writer can reach is a vocabulary that lies about what the field means.
     /**
      * IMAP connection states per RFC 9051 Section 3
      */
-    export type ConnectionState = "not_authenticated" | "authenticated" | "selected" | "logout" | "reauth_required";
+    export type ConnectionState = "not_authenticated" | "authenticated" | "selected" | "logout" | "reauth_required" | "credentials_missing";
     /**
      * Phase of the initial account sync lifecycle
      */
@@ -73,6 +73,14 @@ writer can reach is a vocabulary that lies about what the field means.
      * 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.
      */
     export type FolderAppointmentSource = "Appointed" | "Flagged" | "Reserved" | "Proposed" | "Stale" | "None";
+    /**
+     * Whether an import writes. The default is the dry run, so the wizard can show what a file would do before anything lands.
+     */
+    export type ConfigImportMode = "validate" | "apply";
+    /**
+     * What an import does when the configuration it is importing into is not empty.
+     */
+    export type ConfigImportOnExisting = "abort" | "merge";
     /**
      * Outcome of the most recent manifest check. `ok` when a manifest was fetched and validated, `failed` when it could not be, `disabled` when no manifest URL is configured or no check has ever run (RFC 037 D8).
      */
@@ -249,6 +257,14 @@ distinguishable from a network failure without parsing prose.
      * Known user-setting keys. Each maps, in the registry, to a required value kind and a zod schema. New keys are added deliberately by extending this enum and the registry — never as an ad-hoc column.
      */
     export type AccountSettingName = "Theme" | "Density" | "DefaultComposerFormat" | "PinnedFolders" | "AccountSignaturePlainText" | "AccountSignatureHtml" | "AccountDisplayName" | "AccountMuted" | "AccountComposeLanguages" | "MailboxDisplayName" | "MailboxMuted" | "FolderRoleAppointment" | "FolderRoleAppointmentLabel" | "MailboxRole";
+    /**
+     * Lifecycle of one applied configuration import. An import is Complete the moment every folder reference in the file has been bound to a real mailbox; until then it is Pending, waiting on the IMAP discovery that will produce those mailboxes.
+     */
+    export type ConfigImportState = "Pending" | "Complete";
+    /**
+     * Which piece of configuration a still-unbound folder reference belongs to. A mailbox id is regenerated by every discovery, so an imported file names folders by IMAP path and the binder writes the row once a path resolves.
+     */
+    export type ConfigImportRefKind = "FolderRole" | "MailboxOverride" | "FilterAction";
     /**
      * Explicit state engine for a pending placement-move marker (issue #1271, epic #1281). Recovery keys off this field, not control-flow inference: a redelivered/retried call drives a marker forward from whichever state it is actually in, rather than re-deriving intent by comparing the message's current location.
      */
@@ -860,6 +876,10 @@ never from a raw content-type line — parameters carry `name=` and
        * Associated email accounts
        */
       accounts: AccountResponse[];
+      /**
+       * Absent unless a configuration import is still waiting on folders IMAP has not produced yet (#1021). Nothing polls a separate route for it.
+       */
+      pendingImport?: PendingConfigImport;
     }
     /**
      * Configuration container for user accounts. Groups multiple IMAP accounts under a single user.
@@ -1233,6 +1253,23 @@ never from a raw content-type line — parameters carry `name=` and
        */
       staleAppointmentPath?: String512;
     }
+    /**
+     * An import that is still waiting for IMAP discovery to produce the folders its
+file named. The folder appointed to a role, a folder's own display name or
+mute, and a filter's move destination are all bound by path; a path this
+account does not hold yet is kept, not guessed, and bound the moment discovery
+finds it.
+     */
+    export interface PendingConfigImport {
+      /**
+       * The import still waiting
+       */
+      importId: UUID;
+      /**
+       * The IMAP paths no mailbox answers to yet, deduplicated
+       */
+      folderPaths: string[];
+    }
     /**
      * A configuration export: one versioned document carrying every user decision this instance holds, and no credential.
      */
@@ -1246,6 +1283,104 @@ never from a raw content-type line — parameters carry `name=` and
        */
       document: Record;
     }
+    /**
+     * Request body for POST /config/import
+     */
+    export interface ImportConfigInput {
+      /**
+       * `validate` writes nothing; `apply` writes.
+       */
+      mode?: ConfigImportMode;
+      /**
+       * What to do when this configuration is not empty.
+       */
+      onExisting?: ConfigImportOnExisting;
+      /**
+       * The config document, as exported.
+       */
+      document: Record;
+    }
+    /**
+     * The outcome of a validate or an apply. A rejected document is an answer, not a failure: `valid` is false and `errors` says why.
+     */
+    export interface ConfigImportReport {
+      /**
+       * Import identity; present on apply, so the folder bindings this import is still waiting on can be named later
+       */
+      importId?: UUID;
+      /**
+       * Whether the document is importable at all
+       */
+      valid: boolean;
+      /**
+       * Schema version of the submitted document
+       */
+      schemaVersion: number;
+      /**
+       * Whether anything was written
+       */
+      applied: boolean;
+      /**
+       * Per-item verdicts
+       */
+      items: ConfigImportItemReport[];
+      /**
+       * Blocking problems; non-empty means nothing was written
+       */
+      errors: ApiError[];
+      /**
+       * Non-blocking notes - e.g. a folder path this account does not hold yet
+       */
+      warnings: ApiError[];
+      /**
+       * Accounts that landed needing a credential before they can sync
+       */
+      accountsNeedingCredentials: UUID[];
+    }
+    /**
+     * What became of one item in the submitted document
+     */
+    export interface ConfigImportItemReport {
+      /**
+       * Which section: accounts | labels | filters | addressFlags | settings
+       */
+      section: string;
+      /**
+       * Human key of the item - an email, a label name, a filter name
+       */
+      key: string;
+      /**
+       * created | updated | unchanged | skipped | rejected
+       */
+      verdict: string;
+      /**
+       * Why, when the verdict is skipped or rejected
+       */
+      reason?: string;
+    }
+    /**
+     * The import was refused because this configuration is not empty. The body is
+flat: `code`, `message` and `details` sit at the top level.
+
+`code: "config_not_empty"` — the configuration already holds an account, a
+label, a filter or an address flag. `details` names how many of each. Re-send
+with `onExisting: merge` to upsert instead.
+     */
+    export interface ConfigImportConflict {
+      statusCode: 409;
+      /**
+       * Error code
+       */
+      code: string;
+      /**
+       * Human-readable error message
+       */
+      message: string;
+      /**
+       * Additional error details
+       */
+      details?: Record;
+    }
     /**
      * The self-update resource: the running version, the outcome of the most recent manifest check, and the state of the current or last run. One read serves every interface state. The check block and the run block are independent by construction (RFC 037 D7).
      */
@@ -4208,6 +4343,78 @@ either way and cannot tell which it received.
       createdAt: number;
       updatedAt: number;
     }
+    /**
+     * A folder reference an import could not bind yet. Every folder in a
+configuration file is named by IMAP path, because mailbox ids are regenerated
+by each discovery, and a fresh database holds no mailboxes at all until IMAP
+has been read. The reference is recorded rather than dropped or guessed, and
+the binder writes the row it belongs to once the path resolves.
+     */
+    export interface ConfigImportUnresolvedRef {
+      /**
+       * Which piece of configuration this reference belongs to
+       */
+      kind: ConfigImportRefKind;
+      /**
+       * The account whose folders this path resolves against
+       */
+      accountId: UUID;
+      /**
+       * The IMAP path, as the exporting instance spelled it
+       */
+      folderPath: String512;
+      /**
+       * The role for a folder role, the folder path for a mailbox override, the filter id for a filter's move action
+       */
+      target: String256;
+    }
+    /**
+     * One applied configuration import (#1021). It exists because a file's folder
+references cannot bind at apply time: IMAP discovery produces the mailboxes,
+minutes to hours later, and the ids it assigns are new every run.
+
+The row keeps the document as applied — credential-stripped, like the file
+itself — so the binder can re-read the payload behind each reference instead
+of copying it, and so a person can see what was imported after the fact.
+     */
+    export interface ConfigImport {
+      /**
+       * Primary identifier
+       */
+      importId: UUID;
+      /**
+       * The configuration this file was imported into — the caller's own, never the one the file records as its provenance
+       */
+      accountConfigId: UUID;
+      /**
+       * Schema version of the document as applied, after migration
+       */
+      schemaVersion: number;
+      /**
+       * Whether every folder reference has been bound
+       */
+      state: ConfigImportState;
+      /**
+       * The document as applied. Carries no credential, for the same reason the file does not.
+       */
+      document: Record;
+      /**
+       * Folder references still waiting for a mailbox. Emptied by the binder as discovery resolves each path; an empty list is what makes the import Complete.
+       */
+      unresolvedRefs: ConfigImportUnresolvedRef[];
+      /**
+       * Epoch millis when the import was applied
+       */
+      createdAt: number;
+      /**
+       * Epoch millis when the last folder reference was bound; `0` while the import is still Pending
+       */
+      completedAt: number;
+      /**
+       * Epoch millis when the row was last written
+       */
+      updatedAt: number;
+    }
     /**
      * Typed value for a user setting. `kind` discriminates the concrete shape; a registry binds each setting name to the kind it requires.
      */
@@ -4849,6 +5056,14 @@ declare namespace Paths {
       export type $200 = void;
     }
   }
+  namespace ImportConfig {
+    export type RequestBody = Components.Schemas.ImportConfigInput;
+    namespace Responses {
+      export type $200 = void;
+      export type $400 = void;
+      export type $409 = void;
+    }
+  }
   namespace GetSystemUpdate {
     export interface QueryParameters {
       refresh?: boolean;
@@ -5402,6 +5617,14 @@ export interface OperationMethods {
     data?: any,
     config?: AxiosRequestConfig
   ): OperationResponse<Paths.ExportConfig.Responses.$200>;
+  /**
+   * importConfig - 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.
+   */
+  'importConfig'(
+    parameters?: Parameters<UnknownParamsObject> | null,
+    data?: Paths.ImportConfig.RequestBody,
+    config?: AxiosRequestConfig
+  ): OperationResponse<Paths.ImportConfig.Responses.$200>;
   /**
    * getSystemUpdate - Read the self-update resource: the running version, the outcome of the most recent manifest check, and the state of the current or last run. With `refresh=true`, records a check request on the control volume for the updater to pick up and answers with the stored state as it stands; the caller watches `check.lastCheckedAt` for the updater's answer. Owner-only, and absent (404) unless a manifest URL is configured (RFC 037 D7, D8).
    */
@@ -5939,6 +6162,16 @@ export interface PathsDictionary {
       config?: AxiosRequestConfig
     ): OperationResponse<Paths.ExportConfig.Responses.$200>;
   };
+  ['/config/import']: {
+    /**
+     * importConfig - 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.
+     */
+    'post'(
+      parameters?: Parameters<UnknownParamsObject> | null,
+      data?: Paths.ImportConfig.RequestBody,
+      config?: AxiosRequestConfig
+    ): OperationResponse<Paths.ImportConfig.Responses.$200>;
+  };
   ['/system/update']: {
     /**
      * getSystemUpdate - Read the self-update resource: the running version, the outcome of the most recent manifest check, and the state of the current or last run. With `refresh=true`, records a check request on the control volume for the updater to pick up and answers with the stored state as it stands; the caller watches `check.lastCheckedAt` for the updater's answer. Owner-only, and absent (404) unless a manifest URL is configured (RFC 037 D7, D8).
@@ -6522,7 +6755,12 @@ export type AccountResponse = Components.Schemas.AccountResponse;
 export type AddressFlagBase = Components.Schemas.AddressFlagBase;
 export type MutedFlag = Components.Schemas.MutedFlag;
 export type FolderAppointment = Components.Schemas.FolderAppointment;
+export type PendingConfigImport = Components.Schemas.PendingConfigImport;
 export type ConfigExportResponse = Components.Schemas.ConfigExportResponse;
+export type ImportConfigInput = Components.Schemas.ImportConfigInput;
+export type ConfigImportReport = Components.Schemas.ConfigImportReport;
+export type ConfigImportItemReport = Components.Schemas.ConfigImportItemReport;
+export type ConfigImportConflict = Components.Schemas.ConfigImportConflict;
 export type SystemUpdateResponse = Components.Schemas.SystemUpdateResponse;
 export type SystemUpdateCheck = Components.Schemas.SystemUpdateCheck;
 export type SystemUpdateRun = Components.Schemas.SystemUpdateRun;
@@ -6611,6 +6849,8 @@ export type UpdateMessageLabelsInput = Components.Schemas.UpdateMessageLabelsInp
 export type SpamReportBulkResult = Components.Schemas.SpamReportBulkResult;
 export type SpamReportFailure = Components.Schemas.SpamReportFailure;
 export type EnvelopeAddress = Components.Schemas.EnvelopeAddress;
+export type ConfigImportUnresolvedRef = Components.Schemas.ConfigImportUnresolvedRef;
+export type ConfigImport = Components.Schemas.ConfigImport;
 export type AccountSettingValue = Components.Schemas.AccountSettingValue;
 export type BooleanSetting = Components.Schemas.BooleanSetting;
 export type StringSetting = Components.Schemas.StringSetting;
@@ -6646,6 +6886,8 @@ export type AccountAuthType = Components.Schemas.AccountAuthType;
 export type ConnectionState = Components.Schemas.ConnectionState;
 export type SyncPhase = Components.Schemas.SyncPhase;
 export type FolderAppointmentSource = Components.Schemas.FolderAppointmentSource;
+export type ConfigImportMode = Components.Schemas.ConfigImportMode;
+export type ConfigImportOnExisting = Components.Schemas.ConfigImportOnExisting;
 export type SystemUpdateCheckStatus = Components.Schemas.SystemUpdateCheckStatus;
 export type SystemUpdatePhase = Components.Schemas.SystemUpdatePhase;
 export type SystemUpdateOutcome = Components.Schemas.SystemUpdateOutcome;
@@ -6687,6 +6929,8 @@ export type MailboxAttribute = Components.Schemas.MailboxAttribute;
 export type StorageType = Components.Schemas.StorageType;
 export type ContentEncoding = Components.Schemas.ContentEncoding;
 export type AccountSettingName = Components.Schemas.AccountSettingName;
+export type ConfigImportState = Components.Schemas.ConfigImportState;
+export type ConfigImportRefKind = Components.Schemas.ConfigImportRefKind;
 export type MessagePlacementMoveState = Components.Schemas.MessagePlacementMoveState;
 export type FlagPushOperation = Components.Schemas.FlagPushOperation;
 export type MessageFlagPushState = Components.Schemas.MessageFlagPushState;