@push.rocks/smartjmap 1.0.0 → 2.1.0

package/ts/index.ts

@@ -1,2 +1,4 @@
 export * from './classes.jmapclient.js';
+export * from './interfaces.backend.js';
+export * from './classes.memorymailbackend.js';
 export * from './classes.jmapserver.js';

package/ts/interfaces.backend.ts

@@ -0,0 +1,413 @@
+import type {
+  IJmapEmailAddress,
+  IJmapEmailBodyPart,
+  IJmapEmailBodyValue,
+} from './classes.jmapclient.js';
+
+/**
+ * The authenticated principal a JmapServer `authenticate` hook resolves from an
+ * incoming Request. The backend maps a principal to a JMAP account via
+ * `resolveAccount`.
+ */
+export type TJmapPrincipal = {
+  /** Stable identifier of the authenticated user, e.g. a username or token subject. */
+  username: string;
+};
+
+/** Account metadata returned by `IJmapMailBackend.resolveAccount`. */
+export interface IJmapAccountInfo {
+  /** The JMAP accountId used in method calls and URL templates. */
+  accountId: string;
+  /** Display name of the account, shown in the session object. */
+  name: string;
+  /** Defaults to true when omitted. */
+  isPersonal?: boolean;
+  /** Defaults to false when omitted. */
+  isReadOnly?: boolean;
+}
+
+/** A Mailbox record (RFC 8621 §2) as stored/served by a backend. */
+export interface IJmapMailboxRecord {
+  id: string;
+  name: string;
+  role: string | null;
+  parentId: string | null;
+  sortOrder: number;
+  totalEmails: number;
+  unreadEmails: number;
+  totalThreads: number;
+  unreadThreads: number;
+  /** Defaults to true when omitted. */
+  isSubscribed?: boolean;
+  /** Defaults to an all-permissive rights object when omitted. */
+  myRights?: Record<string, boolean>;
+}
+
+/**
+ * An Email record (RFC 8621 §4) as stored/served by a backend — the full
+ * superset of properties the server can project from. `bodyValues` must hold
+ * the complete body values; the server applies the Email/get fetch flags and
+ * `maxBodyValueBytes` truncation on top.
+ */
+export interface IJmapEmailRecord {
+  id: string;
+  blobId: string;
+  threadId: string;
+  mailboxIds: Record<string, boolean>;
+  keywords: Record<string, boolean>;
+  size: number;
+  receivedAt: string;
+  sentAt: string | null;
+  messageId?: string[] | null;
+  inReplyTo?: string[] | null;
+  references?: string[] | null;
+  sender?: IJmapEmailAddress[] | null;
+  subject: string | null;
+  from: IJmapEmailAddress[] | null;
+  to: IJmapEmailAddress[] | null;
+  cc: IJmapEmailAddress[] | null;
+  bcc: IJmapEmailAddress[] | null;
+  replyTo: IJmapEmailAddress[] | null;
+  hasAttachment: boolean;
+  preview: string;
+  bodyValues: Record<string, IJmapEmailBodyValue>;
+  textBody: IJmapEmailBodyPart[];
+  htmlBody: IJmapEmailBodyPart[];
+  attachments: IJmapEmailBodyPart[];
+}
+
+/** A Thread record (RFC 8621 §3): emailIds sorted oldest first. */
+export interface IJmapThreadRecord {
+  id: string;
+  emailIds: string[];
+}
+
+/** A stored blob: raw bytes plus the content type given at upload/creation. */
+export interface IJmapBlobRecord {
+  data: Uint8Array;
+  type: string;
+  name?: string;
+}
+
+/** An Identity record (RFC 8621 §6). */
+export interface IJmapIdentityRecord {
+  id: string;
+  name: string;
+  email: string;
+  mayDelete: boolean;
+}
+
+/** An EmailSubmission record (RFC 8621 §7) as returned by `submitEmail`. */
+export interface IJmapSubmissionRecord {
+  id: string;
+  emailId: string;
+  identityId: string;
+  undoStatus: string;
+  sendAt: string;
+}
+
+/** SMTP-style envelope handed to the backend on submission (RFC 8621 §7). */
+export interface IJmapEnvelope {
+  mailFrom: { email: string };
+  rcptTo: Array<{ email: string }>;
+}
+
+/** Everything the backend needs to actually send a message. */
+export interface IJmapSubmissionInput {
+  emailId: string;
+  identityId: string;
+  /** Envelope from the client, or derived by the server from the email's addresses. */
+  envelope: IJmapEnvelope;
+  /** The raw RFC 5322 payload (the email's blob) — the backend performs the actual sending. */
+  message: Uint8Array;
+}
+
+/**
+ * Authenticated, admitted upload handed to a streaming backend. The backend
+ * must reserve quota before reading `stream`, consume it through EOF, and
+ * abort its storage operation when `signal` fires.
+ */
+export interface IJmapBlobUploadStream {
+  stream: ReadableStream<Uint8Array>;
+  size: number;
+  type: string;
+  signal: AbortSignal;
+}
+
+/** Standard result shape for the /get-style backend reads. */
+export interface IJmapGetResult<T> {
+  /** Backend-owned opaque state string for the collection at read time. */
+  state: string;
+  list: T[];
+  notFound: string[];
+}
+
+/** Result shape for the /changes-style backend reads (RFC 8620 §5.2). */
+export interface IJmapChanges {
+  oldState: string;
+  newState: string;
+  hasMoreChanges: boolean;
+  created: string[];
+  updated: string[];
+  destroyed: string[];
+}
+
+/** The Email/query filter subset a backend must support (RFC 8621 §4.4.1). */
+export interface IJmapEmailFilter {
+  inMailbox?: string;
+  /** Case-insensitive match in subject, body text, or any address field. */
+  text?: string;
+  subject?: string;
+  from?: string;
+  to?: string;
+  /** receivedAt strictly before this UTC date. */
+  before?: string;
+  /** receivedAt at or after this UTC date. */
+  after?: string;
+  hasKeyword?: string;
+  notKeyword?: string;
+}
+
+/** A query sort comparator; the server only forwards supported properties. */
+export interface IJmapComparator {
+  property: string;
+  isAscending?: boolean;
+}
+
+/** Options passed to `queryEmails`; the server has already validated them. */
+export interface IJmapEmailQueryOptions {
+  filter?: IJmapEmailFilter | null;
+  /** Only `receivedAt` comparators are forwarded by the server. */
+  sort?: IJmapComparator[];
+  /** Zero-based offset into the full result list. */
+  position?: number;
+  limit?: number | null;
+  /** When true the result must include `total`. */
+  calculateTotal?: boolean;
+}
+
+export interface IJmapEmailQueryResult {
+  queryState: string;
+  ids: string[];
+  position: number;
+  /** Present when `calculateTotal` was requested. */
+  total?: number;
+}
+
+/** An Email creation spec (server-validated Email/set create arguments). */
+export interface IJmapEmailCreate {
+  mailboxIds: Record<string, boolean>;
+  keywords?: Record<string, boolean>;
+  from?: IJmapEmailAddress[] | null;
+  to?: IJmapEmailAddress[] | null;
+  cc?: IJmapEmailAddress[] | null;
+  bcc?: IJmapEmailAddress[] | null;
+  replyTo?: IJmapEmailAddress[] | null;
+  sender?: IJmapEmailAddress[] | null;
+  messageId?: string[] | null;
+  inReplyTo?: string[] | null;
+  references?: string[] | null;
+  subject?: string | null;
+  sentAt?: string | null;
+  receivedAt?: string;
+  bodyValues?: Record<string, { value: string }>;
+  textBody?: IJmapEmailBodyPart[];
+  htmlBody?: IJmapEmailBodyPart[];
+  /** Attachment body parts referencing previously uploaded blobs via `blobId`. */
+  attachments?: IJmapEmailBodyPart[];
+}
+
+/**
+ * An Email update, normalized by the server from RFC 8620 §5.3 patches:
+ * full replacements and per-key patches never overlap for the same property
+ * (the server rejects such patches before calling the backend).
+ */
+export interface IJmapEmailUpdate {
+  /** Full replacement of the keywords object. */
+  keywords?: Record<string, boolean>;
+  /** Full replacement of the mailboxIds object. */
+  mailboxIds?: Record<string, boolean>;
+  /** Per-keyword patch: true adds, null removes. */
+  keywordsPatch?: Record<string, true | null>;
+  /** Per-mailbox patch: true adds, null removes. */
+  mailboxIdsPatch?: Record<string, true | null>;
+}
+
+/** A JMAP SetError (RFC 8620 §5.3). */
+export interface IJmapSetError {
+  type: string;
+  description?: string;
+  properties?: string[];
+}
+
+/** The batch handed to `setEmails`; entries are already server-validated. */
+export interface IJmapEmailSetRequest {
+  /** Keyed by client creation id. */
+  create?: Record<string, IJmapEmailCreate>;
+  /** Keyed by email id. */
+  update?: Record<string, IJmapEmailUpdate>;
+  destroy?: string[];
+}
+
+/** The outcome of a `setEmails` batch; `created` carries the full new records. */
+export interface IJmapEmailSetResult {
+  oldState: string;
+  newState: string;
+  created: Record<string, IJmapEmailRecord>;
+  notCreated: Record<string, IJmapSetError>;
+  updated: string[];
+  notUpdated: Record<string, IJmapSetError>;
+  destroyed: string[];
+  notDestroyed: Record<string, IJmapSetError>;
+}
+
+/**
+ * A change notification the backend emits when data mutates — both for
+ * mutations performed through the JMAP server and for out-of-band mutations
+ * (e.g. new mail arriving via an IMAP bridge). `changed` maps JMAP type names
+ * ('Email', 'Mailbox', 'Thread', ...) to the new opaque state string.
+ */
+export interface IJmapStateChange {
+  accountId: string;
+  changed: Record<string, string>;
+}
+
+export type TJmapChangeListener = (change: IJmapStateChange) => void;
+
+/**
+ * Error a backend may throw from set-style operations to control the JMAP
+ * SetError `type` the server reports (e.g. 'notFound', 'invalidProperties').
+ * Any other thrown error is mapped to a generic SetError.
+ */
+export class JmapBackendError extends Error {
+  constructor(public type: string, description?: string) {
+    super(description ?? type);
+    this.name = 'JmapBackendError';
+  }
+}
+
+/**
+ * The storage contract `JmapServer` dispatches into. Implement this against a
+ * real store (SQL, MongoDB, ...) to expose it as a JMAP server; the bundled
+ * `MemoryMailBackend` is the in-memory reference implementation.
+ *
+ * All state strings are backend-owned opaque strings: the server never
+ * interprets them beyond equality comparison and echoing them to clients.
+ */
+export interface IJmapMailBackend {
+  /**
+   * Maps an authenticated principal to its JMAP account, or null when the
+   * principal has no account (the server then responds 403).
+   */
+  resolveAccount(principal: TJmapPrincipal): Promise<IJmapAccountInfo | null>;
+
+  /**
+   * Returns mailboxes by id (`ids: null` returns all mailboxes of the
+   * account) together with the current Mailbox collection state. Counter
+   * fields (totalEmails, unreadEmails, ...) must be accurate at read time.
+   */
+  getMailboxes(
+    accountId: string,
+    ids: string[] | null
+  ): Promise<IJmapGetResult<IJmapMailboxRecord>>;
+
+  /**
+   * Returns mailbox changes since the given state, or null when the state is
+   * unknown/too old (the server then answers `cannotCalculateChanges`).
+   * When `maxChanges` is given, the result may be partial with
+   * `hasMoreChanges: true` and an intermediate `newState` to resume from.
+   */
+  getMailboxChanges(
+    accountId: string,
+    sinceState: string,
+    maxChanges?: number
+  ): Promise<IJmapChanges | null>;
+
+  /**
+   * Returns emails by id together with the current Email collection state.
+   * `properties` is a projection hint (null/undefined = all): backends may
+   * use it to avoid loading bodies, but returning full records is always
+   * correct — the server applies the final projection itself.
+   */
+  getEmails(
+    accountId: string,
+    ids: string[],
+    properties?: string[] | null
+  ): Promise<IJmapGetResult<IJmapEmailRecord>>;
+
+  /**
+   * Runs an Email query: apply the filter, sort, then slice by
+   * position/limit. `total` must be included when `calculateTotal` is set.
+   */
+  queryEmails(
+    accountId: string,
+    options: IJmapEmailQueryOptions
+  ): Promise<IJmapEmailQueryResult>;
+
+  /**
+   * Returns email changes since the given state, or null when the state is
+   * unknown/too old (the server then answers `cannotCalculateChanges`).
+   */
+  getEmailChanges(
+    accountId: string,
+    sinceState: string,
+    maxChanges?: number
+  ): Promise<IJmapChanges | null>;
+
+  /**
+   * Applies an Email/set batch: creates (assigning ids, blobIds, and thread
+   * ids), updates (keyword/mailbox replacements and patches), and destroys.
+   * Per-item failures go into the not* maps; the whole batch must never
+   * throw for item-level problems. Must bump the Email state exactly when
+   * something changed and report old/new state.
+   */
+  setEmails(
+    accountId: string,
+    request: IJmapEmailSetRequest
+  ): Promise<IJmapEmailSetResult>;
+
+  /**
+   * Returns threads by id (each thread lists its emailIds oldest first)
+   * together with the current Thread collection state.
+   */
+  getThreads(accountId: string, ids: string[]): Promise<IJmapGetResult<IJmapThreadRecord>>;
+
+  /** Stores an uploaded blob and returns its id and byte size (RFC 8620 §6.1). */
+  uploadBlob(
+    accountId: string,
+    data: Uint8Array,
+    type: string
+  ): Promise<{ blobId: string; size: number }>;
+
+  /**
+   * Optional streaming upload path. When present, JmapServer requires a valid
+   * Content-Length and never buffers the request before invoking this method.
+   */
+  uploadBlobStream?(
+    accountId: string,
+    upload: IJmapBlobUploadStream
+  ): Promise<{ blobId: string; size: number }>;
+
+  /** Returns a blob's bytes and metadata, or null when unknown. */
+  getBlob(accountId: string, blobId: string): Promise<IJmapBlobRecord | null>;
+
+  /** Returns the sending identities of the account with their collection state. */
+  getIdentities(accountId: string): Promise<IJmapGetResult<IJmapIdentityRecord>>;
+
+  /**
+   * Accepts an email for sending: the server has already resolved the
+   * envelope and fetched the raw RFC 5322 payload — the backend performs (or
+   * queues) the actual delivery and returns the submission record.
+   */
+  submitEmail(
+    accountId: string,
+    submission: IJmapSubmissionInput
+  ): Promise<IJmapSubmissionRecord>;
+
+  /**
+   * Subscribes to change notifications so the server can emit StateChange
+   * pushes — including for mutations that happen outside a JMAP request.
+   * Returns an unsubscribe function; the server always calls it on teardown.
+   */
+  subscribeToChanges(listener: TJmapChangeListener): () => void;
+}