@push.rocks/smartjmap 1.0.0 → 2.1.0

package/dist_ts/classes.jmapserver.d.ts

@@ -1,110 +1,180 @@
-import type { IJmapEmailAddress } from './classes.jmapclient.js';
-export interface IJmapServerMailbox {
-    id: string;
-    name: string;
-    role: string | null;
-    parentId: string | null;
-    sortOrder: number;
-}
-export interface IJmapServerBlob {
-    data: Buffer;
-    type: string;
-    name?: string;
-}
-export interface IJmapServerChangeEntry {
-    state: number;
-    created: string[];
-    updated: string[];
-    destroyed: string[];
-}
-export interface IJmapServerIdentity {
-    id: string;
-    name: string;
-    email: string;
-    mayDelete: boolean;
-}
-export interface IJmapServerSubmission {
-    id: string;
-    emailId: string;
-    identityId: string;
-    undoStatus: string;
-    sendAt: string;
+import { type IJmapMailBackend, type TJmapPrincipal } from "./interfaces.backend.js";
+/**
+ * Semantic capability marker for the bounded streaming-upload server surface.
+ * Consumers must check this exact value before relying on streaming backend
+ * uploads, upload concurrency limits, Bearer-only challenges, or error mapping.
+ */
+export declare const JMAP_SERVER_STREAMING_API_VERSION: 1;
+/** Options for constructing a JmapServer. */
+export interface IJmapServerOptions {
+    /** The storage backend; defaults to a fresh in-memory `MemoryMailBackend`. */
+    backend?: IJmapMailBackend;
+    /**
+     * Resolves an incoming Request to an authenticated principal (return null
+     * to reject with 401). Defaults to a static Basic/Bearer registry fed via
+     * `addUser`/`addBearerToken`.
+     */
+    authenticate?: (request: Request) => Promise<TJmapPrincipal | null>;
+    /**
+     * WWW-Authenticate challenges advertised on a 401 response. Defaults to
+     * Bearer and Basic for the built-in registry. Custom authenticators should
+     * list only the schemes they actually accept.
+     */
+    authenticationChallenges?: string[];
+    /**
+     * Absolute base URL (e.g. `https://mail.example.com`) prefixed to the URLs
+     * advertised in the session object. Defaults to relative URLs, which JMAP
+     * clients resolve against the session resource URL.
+     */
+    baseUrl?: string;
+    /** Overrides for the limits advertised in the JMAP session and enforced by this server. */
+    limits?: Partial<IJmapServerLimits>;
+    /**
+     * Process-wide upload ceiling across authenticated principals. Must be at
+     * least the advertised per-principal maxConcurrentUpload value.
+     */
+    maxConcurrentUploadServer?: number;
+    /** Maps backend upload failures to an RFC 7807 response instead of a generic 500. */
+    mapUploadError?: (error: unknown) => IJmapUploadProblem | null | undefined;
 }
-export interface IJmapServerUser {
-    username: string;
-    password: string;
-    bearerTokens: Set<string>;
-    accountId: string;
-    mailboxes: Map<string, IJmapServerMailbox>;
-    emails: Map<string, Record<string, any>>;
-    blobs: Map<string, IJmapServerBlob>;
-    submissions: Map<string, IJmapServerSubmission>;
-    identities: IJmapServerIdentity[];
-    state: number;
-    changes: IJmapServerChangeEntry[];
-    idCounter: number;
+export interface IJmapServerLimits {
+    maxSizeUpload: number;
+    maxConcurrentUpload: number;
+    maxSizeRequest: number;
+    maxConcurrentRequests: number;
+    maxCallsInRequest: number;
+    maxObjectsInGet: number;
+    maxObjectsInSet: number;
 }
-export interface IJmapServerEmailInput {
-    from: IJmapEmailAddress | IJmapEmailAddress[];
-    to: IJmapEmailAddress | IJmapEmailAddress[];
-    cc?: IJmapEmailAddress[];
-    bcc?: IJmapEmailAddress[];
-    subject?: string;
-    textBody?: string;
-    htmlBody?: string;
-    keywords?: Record<string, boolean>;
-    receivedAt?: string;
-    attachments?: Array<{
-        name: string;
-        type: string;
-        content: string | Uint8Array;
-    }>;
+export interface IJmapUploadProblem {
+    status: number;
+    type?: string;
+    detail: string;
+    limit?: string;
+    retryAfterSeconds?: number;
 }
+/** The advertised — and enforced — RFC 8620 core limits. */
+export declare const JMAP_SERVER_LIMITS: IJmapServerLimits;
 /**
- * A minimal in-memory JMAP server (RFC 8620 core + RFC 8621 mail subset)
- * for offline testing. Serves the session resource at /.well-known/jmap and
- * /jmap/session, the API at /jmap/api, blob downloads at /jmap/download/...,
- * and StateChange pushes via SSE at /jmap/eventsource.
+ * A JMAP server core (RFC 8620) with the RFC 8621 mail method surface,
+ * dispatching all storage into a pluggable `IJmapMailBackend`.
+ *
+ * The primary API is the web-standard `fetchHandler(request)` — mount it in
+ * any Request/Response runtime (Deno, Bun, service workers, Node ≥18). The
+ * `start(port)`/`stop()` pair wraps it in a node:http server for convenience.
+ *
+ * Endpoints: session (`/.well-known/jmap`, `/jmap/session`), API
+ * (`/jmap/api`), upload (`/jmap/upload/{accountId}`), download
+ * (`/jmap/download/{accountId}/{blobId}/{name}?type=`), and event source
+ * (`/jmap/eventsource` — SSE StateChange pushes per RFC 8620 §7.3).
+ *
+ * With no options this behaves as the offline test helper: an in-memory
+ * backend plus a static credential registry (`addUser`/`addBearerToken`).
  */
 export declare class JmapServer {
-    users: Map<string, IJmapServerUser>;
-    private server;
+    readonly backend: IJmapMailBackend;
+    private options;
+    private readonly limits;
+    private readonly maxConcurrentUploadServer;
+    private registry;
+    private httpServer;
     private sockets;
     private eventStreams;
-    constructor();
+    private changeFeedUnsubscribe;
+    private cleanupErrors;
+    private activeApiRequests;
+    private activeUploadRequests;
+    private activeUploadsByPrincipal;
+    private activeNodeRequests;
+    private nodeRequestControllers;
+    private stopping;
+    private authenticationChallenges;
+    constructor(options?: IJmapServerOptions);
+    /**
+     * Registers Basic credentials in the default authenticator's registry.
+     * Only consulted when no custom `authenticate` option is set. Account data
+     * itself lives in the backend (the memory backend auto-creates accounts).
+     */
     addUser(username: string, password: string): void;
-    /** Registers a valid Bearer token for a user. */
+    /** Registers a valid Bearer token for a user in the default authenticator. */
     addBearerToken(username: string, token: string): void;
-    createMailbox(username: string, name: string, role?: string): string;
-    /** Seeds an email into a user's mailbox; bumps state and pushes a StateChange. Returns the email id. */
-    addEmail(username: string, mailboxName: string, input: IJmapServerEmailInput): string;
-    /** Starts the server. Resolves with the bound port (pass 0 for an ephemeral port). */
+    /** Starts a node:http server around fetchHandler. Resolves with the bound port (pass 0 for ephemeral). */
     start(port: number): Promise<number>;
-    /** Stops the server, ending open event streams and destroying open connections. */
+    /**
+     * Stops the server: closes all event streams (clearing their ping timers
+     * and the backend change-feed subscription), destroys open connections,
+     * and closes the node listener when one was started.
+     */
     stop(): Promise<void>;
-    private handleRequest;
-    private authenticate;
+    /**
+     * Handles a JMAP request end to end and returns the Response. This is the
+     * runtime-agnostic core — mount it directly as a Deno/Bun fetch handler.
+     */
+    fetchHandler(request: Request): Promise<Response>;
+    private authenticatePrincipal;
     private handleSession;
+    private buildUrl;
     private handleApi;
-    private handleEventSource;
-    private handleDownload;
+    /**
+     * Resolves `#argument` ResultReference objects (RFC 8620 §3.7) against the
+     * responses of earlier method calls in the same request.
+     */
+    private resolveBackReferences;
     private dispatchMethod;
+    private requireAccountId;
     private methodMailboxGet;
     private methodMailboxQuery;
+    private methodMailboxChanges;
+    private methodThreadGet;
     private methodEmailGet;
+    /** Applies the Email/get body-value fetch flags and maxBodyValueBytes truncation. */
+    private buildBodyValues;
     private methodEmailQuery;
     private methodEmailChanges;
     private methodEmailSet;
+    /**
+     * Normalizes an Email/set update patch (RFC 8620 §5.3): full `keywords`/
+     * `mailboxIds` replacements and single-key JSON-pointer patches
+     * (`keywords/$seen`, `mailboxIds/<id>`). Email properties other than these
+     * two are immutable (RFC 8621 §4.6).
+     */
+    private parseEmailUpdatePatch;
     private methodIdentityGet;
     private methodEmailSubmissionSet;
-    private requireUser;
-    private createEmailFromSpec;
+    /** Uses the client-provided envelope or derives it from the email's addresses. */
+    private resolveEnvelope;
+    private cancelRequestBody;
+    private readRequestBodyBounded;
+    private createExactUploadBody;
+    private mappedUploadErrorResponse;
+    private requestBodyErrorResponse;
+    private handleStreamingUpload;
+    private handleUpload;
+    private handleDownload;
+    private handleEventSource;
+    private registerStream;
+    private unregisterStream;
+    private closeStream;
+    private writeToStream;
+    /**
+     * Pushes a StateChange to matching event streams. Per-type states are
+     * deduplicated per stream, so a mutation notified both by the backend
+     * change feed and by the post-request push is delivered once.
+     */
+    private pushStateChange;
     /**
-     * Applies an Email/set update patch: either whole properties (e.g. keywords)
-     * or JSON-pointer style paths like "keywords/$seen" (RFC 8620 §5.3).
+     * Emits a StateChange after a mutating JMAP request, covering backends
+     * whose change feed only reports out-of-band mutations. Deduplicated
+     * against feed-driven pushes via the per-stream state tracking.
      */
-    private applyPatch;
-    /** Increments the account state, records the change, and pushes a StateChange to open event streams. */
-    private bumpState;
-    private notifyStateChange;
+    private pushAfterMutation;
+    private nodeRequestBody;
+    private handleNodeRequest;
+    private validateProperties;
+    private projectObject;
+    private validatePosition;
+    private validateChangesArgs;
+    private jsonResponse;
+    private problemResponse;
+    private limitResponse;
 }