@remit/api-openapi-types 0.0.7 → 0.0.9

package/package.json

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

package/types.d.ts

@@ -13,6 +13,46 @@ declare namespace Components {
      * Lifecycle state of an account export request
      */
     export type AccountExportState = "Pending" | "Processing" | "Ready" | "Failed";
+    /**
+     * The fixed anchor set of canonical mailbox roles a user appoints to a folder (RFC 032 exclusive-folder-appointment, issue #976). Mirrors the IMAP SPECIAL-USE roles (RFC 6154). Each role resolves to at most one mailbox per account — see FolderAppointment.
+     */
+    export type CanonicalMailboxRole = "Inbox" | "Drafts" | "Sent" | "Archive" | "Junk" | "Trash" | "All" | "Flagged";
+    /**
+     * The pipeline step that refused a quarantined message.
+
+One member, and it is behind a real narrowing rather than a promise of one:
+the body parse has its own try block around the parse call and nothing else,
+so an error out of it can only be the message. S3, queue and database
+failures propagate and never become a record here — quarantining one would
+set a message aside for an outage, tell the user it was unreadable, and
+invite a public GitHub issue about it.
+
+A message that arrives with no ENVELOPE is deliberately NOT a member. Nothing
+can tell that apart from the FETCH row glitching (#408), and the IMAP client
+is far more often the cause than the message; the sync path holds its cursor
+and retries instead, so a transient glitch heals and a persistent one trips
+the stalled-cursor alert.
+     */
+    export type QuarantineFailureStage = "BodyParse";
+    /**
+     * The specific defect within a stage.
+
+Closed rather than free text: this is the one diagnostic that is interpolated
+into the title of an issue filed under the user's own GitHub account, so its
+publishability has to be a property of the type instead of a claim about the
+writer.
+
+The vocabulary is total — every quarantine write picks a member, and a defect
+the writer cannot name is `UnreadableBody` rather than an invented code. It
+is deliberately small: the body parser reports its refusals as free text with
+no stable type or code, so a member exists only where the writer can identify
+the defect without reading parser prose. `UnterminatedMultipartBoundary` and
+`TruncatedBody` were provisional members carried by Phase 2 and are gone —
+nothing on the narrowed sync path could produce either, and a member no
+writer can reach is a vocabulary that lies about what the field means.
+`MissingEnvelope` is absent for the same reason: see QuarantineFailureStage.
+     */
+    export type QuarantineFailureCode = "UnknownCharset" | "UnreadableBody";
     /**
      * Lifecycle state of an account configuration
      */
@@ -29,10 +69,6 @@ declare namespace Components {
      * Phase of the initial account sync lifecycle
      */
     export type SyncPhase = "idle" | "discovering_mailboxes" | "syncing_inbox" | "syncing_others" | "complete" | "error";
-    /**
-     * The fixed anchor set of canonical mailbox roles a user appoints to a folder (RFC 032 exclusive-folder-appointment, issue #976). Mirrors the IMAP SPECIAL-USE roles (RFC 6154). Each role resolves to at most one mailbox per account — see FolderAppointment.
-     */
-    export type CanonicalMailboxRole = "Inbox" | "Drafts" | "Sent" | "Archive" | "Junk" | "Trash" | "All" | "Flagged";
     /**
      * IMAP namespace types per RFC 9051 Section 6.3.10
      */
@@ -182,8 +218,10 @@ current enum emitter anyway, so the wire contract uses the bare form.
      */
     export type MessageFlagPushState = "pending" | "queued" | "processing" | "processed";
     export type UUID = string;
-    export type String800 = string;
     export type String512 = string;
+    export type String140 = string;
+    export type String64 = string;
+    export type String800 = string;
     export type String32 = string;
     export type String256 = string;
     /**
@@ -201,8 +239,6 @@ a compile-time error rather than a value that silently sorts incorrectly.
     export type SemanticVersion = string;
     export type String2048 = string;
     export type String200 = string;
-    export type String140 = string;
-    export type String64 = string;
     export interface CognitoAuthorizer {
       /**
        * API key authentication
@@ -452,6 +488,238 @@ a compile-time error rather than a value that silently sorts incorrectly.
        */
       errorMessage?: string;
     }
+    /**
+     * Everything quarantined for the current user, newest first. The list is small by design — a mailbox with a growing quarantine list is a bug being reported, not a page to paginate.
+     */
+    export interface QuarantineListResponse {
+      /**
+       * Quarantined messages, newest first.
+       */
+      entries: QuarantineResponse[];
+    }
+    /**
+     * A message the sync path could not apply, set aside so the mailbox cursor can
+advance past it (issue #72).
+
+Quarantine is a record, not a flag: the failing message was never written, so
+there is no row to mark. The record carries what was quarantined, why, and
+the diagnostics a bug report needs — it is the artifact, not a side effect of
+one.
+
+Two stored fields are shown on screen and never travel in a report:
+`mailboxPath` (folder names are the user's own words) and `failureMessage`
+(parser errors quote the input that broke them, and redacting arbitrary
+parser output is not solvable). Nothing else here is message content —
+no body, subject, addresses, attachment names, or Message-ID in the clear.
+
+The boundary this entity must not cross: a malformed message is
+quarantinable, an S3, queue or database failure is not. Writing an
+infrastructure failure here would advance the cursor past mail that is fine
+and tell the user it was unreadable.
+     */
+    export interface Quarantine {
+      /**
+       * Deterministic v5 identity derived from accountId, mailboxId, uidValidity and uid. Idempotent by construction: the same failing message keys the same row on every retry, so nothing has to check for an existing entry before writing one.
+       */
+      quarantineId: UUID;
+      /**
+       * Owning account configuration — the user. Scopes the settings list and the read endpoint.
+       */
+      accountConfigId: UUID;
+      /**
+       * Mail account the message arrived on. Part of the quarantineId derivation.
+       */
+      accountId: UUID;
+      /**
+       * Mailbox the message arrived in. Part of the quarantineId derivation.
+       */
+      mailboxId: UUID;
+      /**
+       * UIDVALIDITY of the mailbox when the message was set aside. A uid means nothing without it — only uidValidity + uid names a message forever (RFC 9051 2.3.1.1), and a mailbox keeps its mailboxId across a bump, so leaving this out would let a stale entry claim the identity of a later, unrelated message and suppress it from a sync round.
+       */
+      uidValidity: number;
+      /**
+       * The IMAP uid that was never written. Part of the quarantineId derivation.
+       */
+      uid: number;
+      /**
+       * Canonical role of the folder the message arrived in — travels in the report. Absent when the user has appointed no role to that folder, which is the normal state for a plain folder. A sentinel would mean a new member on the shared canonical-role enum, which FolderAppointment would then have to mean something by.
+       */
+      mailboxRole?: CanonicalMailboxRole;
+      /**
+       * The user's own folder name. Shown on screen, withheld from the report.
+       */
+      mailboxPath: String512;
+      /**
+       * Epoch millis the message was set aside.
+       */
+      quarantinedAt: number;
+      /**
+       * Rounds tried before the message was set aside.
+       */
+      attempts: number;
+      /**
+       * Pipeline step that refused the message.
+       */
+      failureStage: QuarantineFailureStage;
+      /**
+       * The specific defect. Closed vocabulary, because this is what a filed issue quotes.
+       */
+      failureCode: QuarantineFailureCode;
+      /**
+       * Parser error text. Shown on screen, never in the report.
+       */
+      failureMessage: String512;
+      /**
+       * Dot-numbered part path the failure is attributable to, off ROOT_PART_PATH. Absent when the failure belongs to no single node — every whole-body parse failure today.
+       */
+      failurePartPath?: String140;
+      /**
+       * Build of the imap-worker that failed to read the message. Named for the worker, not the app: the record is written by the sync worker, and stamping the client build on a backend parse failure points a maintainer at the wrong commit.
+       */
+      workerVersion: String64;
+      /**
+       * Top-level Content-Type, `type/subtype` only. Sender-controlled text — escape it wherever it is rendered. Absent together with the other BODYSTRUCTURE-derived fields when the message failed before its structure was read.
+       */
+      contentType?: String140;
+      /**
+       * Content-Transfer-Encoding as declared. Sender-controlled text. Absent when there was no BODYSTRUCTURE to read it from.
+       */
+      transferEncoding?: String64;
+      /**
+       * Declared charset. Sender-controlled text. Absent is meaningful: an undeclared charset is a cause in its own right, distinct from a charset nobody recognises.
+       */
+      charset?: String64;
+      /**
+       * RFC822.SIZE. Separates "too large" from "malformed". Absent when the FETCH that failed carried no size.
+       */
+      sizeBytes?: number;
+      /**
+       * The MIME tree, structure only, as a pre-order walk. The one field here that cannot be a column, because it is a tree; every other message-shape field is flat and stays typed. Empty when the message failed before its BODYSTRUCTURE was read.
+       */
+      structure: QuarantineMimeNode[];
+      /**
+       * SHA-256 of the Message-ID, `sha256:` prefixed. Pinned to one algorithm: correlating two reports of the same message is the whole point of the field, and two builds hashing differently make it useless. Absent when the message declared no Message-ID — a hash of the empty string would make every such message correlate with every other, which is worse than no value at all.
+       */
+      messageIdHash?: String140;
+      createdAt: number;
+      updatedAt: number;
+    }
+    /**
+     * One node of a quarantined message's MIME tree, in a pre-order walk.
+
+The tree is carried flat with an explicit `depth` rather than as nested
+children: a self-referential model is not expressible here (the entity
+emitter recurses forever on one), and the tree is only ever rendered as an
+indented list, which a pre-order walk reproduces exactly. Nothing caps the
+walk — it is as long as the message has parts.
+
+`contentType` is `type/subtype` only. BODYSTRUCTURE hands the type and its
+parameters over separately, so a node is built from `type`/`subtype` and
+never from a raw content-type line — parameters carry `name=` and
+`filename=`, which name the user's attachments.
+     */
+    export interface QuarantineMimeNode {
+      /**
+       * Nesting level, 0 for the root part.
+       */
+      depth: number;
+      /**
+       * Media type of this node, `type/subtype`, parameters stripped.
+       */
+      contentType: String140;
+    }
+    /**
+     * One quarantined message as the settings surface sees it.
+     */
+    export interface QuarantineResponse {
+      /**
+       * Deterministic v5 identity derived from accountId, mailboxId, uidValidity and uid. Idempotent by construction: the same failing message keys the same row on every retry, so nothing has to check for an existing entry before writing one.
+       */
+      quarantineId: UUID;
+      /**
+       * Owning account configuration — the user. Scopes the settings list and the read endpoint.
+       */
+      accountConfigId: UUID;
+      /**
+       * Mail account the message arrived on. Part of the quarantineId derivation.
+       */
+      accountId: UUID;
+      /**
+       * Mailbox the message arrived in. Part of the quarantineId derivation.
+       */
+      mailboxId: UUID;
+      /**
+       * UIDVALIDITY of the mailbox when the message was set aside. A uid means nothing without it — only uidValidity + uid names a message forever (RFC 9051 2.3.1.1), and a mailbox keeps its mailboxId across a bump, so leaving this out would let a stale entry claim the identity of a later, unrelated message and suppress it from a sync round.
+       */
+      uidValidity: number;
+      /**
+       * The IMAP uid that was never written. Part of the quarantineId derivation.
+       */
+      uid: number;
+      /**
+       * Canonical role of the folder the message arrived in — travels in the report. Absent when the user has appointed no role to that folder, which is the normal state for a plain folder. A sentinel would mean a new member on the shared canonical-role enum, which FolderAppointment would then have to mean something by.
+       */
+      mailboxRole?: CanonicalMailboxRole;
+      /**
+       * The user's own folder name. Shown on screen, withheld from the report.
+       */
+      mailboxPath: String512;
+      /**
+       * Epoch millis the message was set aside.
+       */
+      quarantinedAt: number;
+      /**
+       * Rounds tried before the message was set aside.
+       */
+      attempts: number;
+      /**
+       * Pipeline step that refused the message.
+       */
+      failureStage: QuarantineFailureStage;
+      /**
+       * The specific defect. Closed vocabulary, because this is what a filed issue quotes.
+       */
+      failureCode: QuarantineFailureCode;
+      /**
+       * Parser error text. Shown on screen, never in the report.
+       */
+      failureMessage: String512;
+      /**
+       * Dot-numbered part path the failure is attributable to, off ROOT_PART_PATH. Absent when the failure belongs to no single node — every whole-body parse failure today.
+       */
+      failurePartPath?: String140;
+      /**
+       * Build of the imap-worker that failed to read the message. Named for the worker, not the app: the record is written by the sync worker, and stamping the client build on a backend parse failure points a maintainer at the wrong commit.
+       */
+      workerVersion: String64;
+      /**
+       * Top-level Content-Type, `type/subtype` only. Sender-controlled text — escape it wherever it is rendered. Absent together with the other BODYSTRUCTURE-derived fields when the message failed before its structure was read.
+       */
+      contentType?: String140;
+      /**
+       * Content-Transfer-Encoding as declared. Sender-controlled text. Absent when there was no BODYSTRUCTURE to read it from.
+       */
+      transferEncoding?: String64;
+      /**
+       * Declared charset. Sender-controlled text. Absent is meaningful: an undeclared charset is a cause in its own right, distinct from a charset nobody recognises.
+       */
+      charset?: String64;
+      /**
+       * RFC822.SIZE. Separates "too large" from "malformed". Absent when the FETCH that failed carried no size.
+       */
+      sizeBytes?: number;
+      /**
+       * The MIME tree, structure only, as a pre-order walk. The one field here that cannot be a column, because it is a tree; every other message-shape field is flat and stays typed. Empty when the message failed before its BODYSTRUCTURE was read.
+       */
+      structure: QuarantineMimeNode[];
+      /**
+       * SHA-256 of the Message-ID, `sha256:` prefixed. Pinned to one algorithm: correlating two reports of the same message is the whole point of the field, and two builds hashing differently make it useless. Absent when the message declared no Message-ID — a hash of the empty string would make every such message correlate with every other, which is worse than no value at all.
+       */
+      messageIdHash?: String140;
+      createdAt: number;
+      updatedAt: number;
+    }
     /**
      * Full configuration description including accounts
      */
@@ -3772,6 +4040,11 @@ declare namespace Paths {
       export type $200 = void;
     }
   }
+  namespace ListQuarantine {
+    namespace Responses {
+      export type $200 = void;
+    }
+  }
   namespace GetConfig {
     namespace Responses {
       export type $200 = void;
@@ -4200,6 +4473,14 @@ export interface OperationMethods {
     data?: any,
     config?: AxiosRequestConfig
   ): OperationResponse<Paths.GetExport.Responses.$200>;
+  /**
+   * listQuarantine - List every message the sync path could not read, for the current user across all of their mail accounts (issue #72). Backs the quarantine section in settings. Unpaginated: the list is small by design, and an entry is a defect waiting to be reported rather than a page of mail.
+   */
+  'listQuarantine'(
+    parameters?: Parameters<UnknownParamsObject> | null,
+    data?: any,
+    config?: AxiosRequestConfig
+  ): OperationResponse<Paths.ListQuarantine.Responses.$200>;
   /**
    * getConfig - Get the current user's configuration including accounts and addresses
    */
@@ -4619,6 +4900,16 @@ export interface PathsDictionary {
       config?: AxiosRequestConfig
     ): OperationResponse<Paths.GetExport.Responses.$200>;
   };
+  ['/me/quarantine']: {
+    /**
+     * listQuarantine - List every message the sync path could not read, for the current user across all of their mail accounts (issue #72). Backs the quarantine section in settings. Unpaginated: the list is small by design, and an entry is a defect waiting to be reported rather than a page of mail.
+     */
+    'get'(
+      parameters?: Parameters<UnknownParamsObject> | null,
+      data?: any,
+      config?: AxiosRequestConfig
+    ): OperationResponse<Paths.ListQuarantine.Responses.$200>;
+  };
   ['/config']: {
     /**
      * getConfig - Get the current user's configuration including accounts and addresses
@@ -5084,6 +5375,10 @@ export type VipSuggestionEntry = Components.Schemas.VipSuggestionEntry;
 export type CreateExportResponse = Components.Schemas.CreateExportResponse;
 export type AccountExportRequest = Components.Schemas.AccountExportRequest;
 export type AccountExportRequestResponse = Components.Schemas.AccountExportRequestResponse;
+export type QuarantineListResponse = Components.Schemas.QuarantineListResponse;
+export type Quarantine = Components.Schemas.Quarantine;
+export type QuarantineMimeNode = Components.Schemas.QuarantineMimeNode;
+export type QuarantineResponse = Components.Schemas.QuarantineResponse;
 export type ConfigDescriptionResponse = Components.Schemas.ConfigDescriptionResponse;
 export type AccountConfig = Components.Schemas.AccountConfig;
 export type AccountConfigResponse = Components.Schemas.AccountConfigResponse;
@@ -5186,11 +5481,13 @@ export type MicrosoftOAuthStartRequest = Components.Schemas.MicrosoftOAuthStartR
 export type MicrosoftOAuthStartResponse = Components.Schemas.MicrosoftOAuthStartResponse;
 export type IndexType = Components.Schemas.IndexType;
 export type AccountExportState = Components.Schemas.AccountExportState;
+export type CanonicalMailboxRole = Components.Schemas.CanonicalMailboxRole;
+export type QuarantineFailureStage = Components.Schemas.QuarantineFailureStage;
+export type QuarantineFailureCode = Components.Schemas.QuarantineFailureCode;
 export type AccountConfigState = Components.Schemas.AccountConfigState;
 export type AccountAuthType = Components.Schemas.AccountAuthType;
 export type ConnectionState = Components.Schemas.ConnectionState;
 export type SyncPhase = Components.Schemas.SyncPhase;
-export type CanonicalMailboxRole = Components.Schemas.CanonicalMailboxRole;
 export type NamespaceType = Components.Schemas.NamespaceType;
 export type MailboxSyncStatus = Components.Schemas.MailboxSyncStatus;
 export type MailboxCursorState = Components.Schemas.MailboxCursorState;
@@ -5228,12 +5525,12 @@ export type MessagePlacementMoveState = Components.Schemas.MessagePlacementMoveS
 export type FlagPushOperation = Components.Schemas.FlagPushOperation;
 export type MessageFlagPushState = Components.Schemas.MessageFlagPushState;
 export type UUID = Components.Schemas.UUID;
-export type String800 = Components.Schemas.String800;
 export type String512 = Components.Schemas.String512;
+export type String140 = Components.Schemas.String140;
+export type String64 = Components.Schemas.String64;
+export type String800 = Components.Schemas.String800;
 export type String32 = Components.Schemas.String32;
 export type String256 = Components.Schemas.String256;
 export type SemanticVersion = Components.Schemas.SemanticVersion;
 export type String2048 = Components.Schemas.String2048;
 export type String200 = Components.Schemas.String200;
-export type String140 = Components.Schemas.String140;
-export type String64 = Components.Schemas.String64;