@push.rocks/smartjmap 1.0.0

package/.smartconfig.json

@@ -0,0 +1,56 @@
+{
+  "@git.zone/cli": {
+    "projectType": "npm",
+    "module": {
+      "githost": "code.foss.global",
+      "gitscope": "push.rocks",
+      "gitrepo": "smartjmap",
+      "shortDescription": "JMAP client for mail (RFC 8620/8621)",
+      "description": "A TypeScript JMAP client for reading, sending, and watching mail via the JSON Meta Application Protocol (RFC 8620/8621), with a bundled test server for offline testing.",
+      "npmPackagename": "@push.rocks/smartjmap",
+      "license": "MIT",
+      "projectDomain": "push.rocks",
+      "keywords": [
+        "jmap",
+        "email",
+        "mail",
+        "rfc8620",
+        "rfc8621",
+        "fastmail",
+        "stalwart",
+        "json",
+        "http",
+        "client",
+        "typescript",
+        "event-driven",
+        "push",
+        "eventsource",
+        "message processing"
+      ]
+    },
+    "release": {
+      "targets": {
+        "git": {
+          "enabled": true,
+          "remote": "origin"
+        },
+        "npm": {
+          "enabled": true,
+          "registries": [
+            "https://verdaccio.lossless.digital",
+            "https://registry.npmjs.org"
+          ],
+          "accessLevel": "public"
+        },
+        "docker": {
+          "enabled": false,
+          "engine": "tsdocker"
+        }
+      }
+    }
+  },
+  "@ship.zone/szci": {
+    "npmGlobalTools": [],
+    "npmRegistryUrl": "registry.npmjs.org"
+  }
+}

package/dist_ts/00_commitinfo_data.d.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export declare const commitinfo: {
+    name: string;
+    version: string;
+    description: string;
+};

package/dist_ts/00_commitinfo_data.js

@@ -0,0 +1,9 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+    name: '@push.rocks/smartjmap',
+    version: '1.0.0',
+    description: 'A TypeScript JMAP client for reading, sending, and watching mail via the JSON Meta Application Protocol (RFC 8620/8621), with a bundled test server for offline testing.'
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx1QkFBdUI7SUFDN0IsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLDBLQUEwSztDQUN4TCxDQUFBIn0=

package/dist_ts/classes.jmapclient.d.ts

@@ -0,0 +1,236 @@
+import * as plugins from './smartjmap.plugins.js';
+export declare const JMAP_CORE_CAPABILITY = "urn:ietf:params:jmap:core";
+export declare const JMAP_MAIL_CAPABILITY = "urn:ietf:params:jmap:mail";
+export declare const JMAP_SUBMISSION_CAPABILITY = "urn:ietf:params:jmap:submission";
+export interface IJmapClientAuthBearer {
+    /** OAuth2 / API access token sent as `Authorization: Bearer <token>`. */
+    accessToken: string;
+}
+export interface IJmapClientAuthBasic {
+    user: string;
+    pass: string;
+}
+export type TJmapClientAuth = IJmapClientAuthBearer | IJmapClientAuthBasic;
+export interface IJmapClientConfig {
+    /**
+     * URL of the JMAP session resource.
+     * Callers can pass the autodiscovery endpoint, e.g. `https://host/.well-known/jmap`;
+     * relative URLs inside the session object are resolved against this URL.
+     */
+    sessionUrl: string;
+    /** Either `{ accessToken }` (Bearer) or `{ user, pass }` (Basic) — exactly one shape. */
+    auth: TJmapClientAuth;
+    /**
+     * Mailbox to watch for new messages. Defaults to 'INBOX' semantics:
+     * resolved via the Mailbox with role 'inbox', falling back to a
+     * case-insensitive name match.
+     */
+    mailbox?: string;
+    /** Fallback polling cadence in ms, used when the event stream is unavailable. Default 30000. */
+    pollIntervalMs?: number;
+}
+/** A single JMAP method call: [methodName, arguments, methodCallId] (RFC 8620 §3.2). */
+export type TJmapMethodCall = [string, Record<string, any>, string];
+/** A single JMAP method response: [methodName, arguments, methodCallId] (RFC 8620 §3.4). */
+export type TJmapMethodResponse = [string, Record<string, any>, string];
+export interface IJmapSession {
+    capabilities: Record<string, any>;
+    accounts: Record<string, any>;
+    primaryAccounts: Record<string, string>;
+    username?: string;
+    apiUrl: string;
+    downloadUrl: string;
+    uploadUrl?: string;
+    eventSourceUrl?: string;
+    state?: string;
+}
+export interface IJmapMailbox {
+    id: string;
+    name: string;
+    role?: string | null;
+    parentId?: string | null;
+    sortOrder?: number;
+    totalEmails?: number;
+    unreadEmails?: number;
+    totalThreads?: number;
+    unreadThreads?: number;
+}
+export interface IJmapEmailAddress {
+    name?: string | null;
+    email: string;
+}
+export interface IJmapEmailBodyPart {
+    partId?: string | null;
+    blobId?: string;
+    size?: number;
+    name?: string | null;
+    type?: string;
+    charset?: string | null;
+    disposition?: string | null;
+    cid?: string | null;
+}
+export interface IJmapEmailBodyValue {
+    value: string;
+    isTruncated?: boolean;
+    isEncodingProblem?: boolean;
+}
+/** The raw JMAP Email object (RFC 8621 §4) — the subset of properties this client requests. */
+export interface IJmapEmail {
+    id: string;
+    blobId: string;
+    threadId: string;
+    mailboxIds: Record<string, boolean>;
+    keywords: Record<string, boolean>;
+    size?: number;
+    receivedAt?: string;
+    sentAt?: string | 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[];
+}
+export interface IJmapAttachment {
+    blobId: string;
+    name?: string;
+    type?: string;
+    size?: number;
+}
+/** The message shape emitted on 'message' events and returned by the query/get helpers. */
+export interface ISmartJmapMessage {
+    id: string;
+    blobId: string;
+    threadId: string;
+    mailboxIds: Record<string, boolean>;
+    keywords: Record<string, boolean>;
+    from: IJmapEmailAddress[];
+    to: IJmapEmailAddress[];
+    cc: IJmapEmailAddress[];
+    bcc: IJmapEmailAddress[];
+    replyTo: IJmapEmailAddress[];
+    subject?: string;
+    receivedAt?: string;
+    /** Plain-text body, resolved from the JMAP bodyValues. */
+    textBody: string;
+    /** HTML body, resolved from the JMAP bodyValues; undefined when the email has no text/html part. */
+    htmlBody?: string;
+    attachments: IJmapAttachment[];
+    /** The full raw JMAP Email object as returned by Email/get. */
+    raw: IJmapEmail;
+}
+export interface IJmapOutgoingEmail {
+    /** Sender; defaults to the address of the account's first JMAP Identity. */
+    from?: IJmapEmailAddress;
+    to: IJmapEmailAddress[];
+    cc?: IJmapEmailAddress[];
+    bcc?: IJmapEmailAddress[];
+    subject?: string;
+    textBody?: string;
+    htmlBody?: string;
+}
+export interface IJmapSendResult {
+    emailId: string;
+    submissionId: string;
+}
+/** Error thrown for HTTP-level (RFC 7807 problem details) and JMAP method-level errors. */
+export declare class JmapError extends Error {
+    httpStatus?: number;
+    problemType?: string;
+    problemDetail?: string;
+    jmapErrorType?: string;
+    jmapErrorDescription?: string;
+    jmapCallId?: string;
+    constructor(message: string, fields?: Partial<JmapError>);
+}
+export declare class JmapClient extends plugins.events.EventEmitter {
+    private config;
+    private session;
+    private accountId;
+    private apiUrl;
+    private mailbox;
+    private connected;
+    private stopped;
+    private lastEmailState;
+    private seenEmailIds;
+    private pollTimer;
+    private sseAbortController;
+    private fetchingDeltas;
+    private deltaQueued;
+    constructor(config: IJmapClientConfig);
+    /**
+     * Fetches and validates the JMAP session, resolves the target mailbox,
+     * emits 'connected', emits 'message' for every email currently in the
+     * mailbox, then watches for new mail via the JMAP event source (SSE),
+     * falling back to polling when the event stream is unavailable.
+     * Failures are emitted as 'error' events; connect() does not throw.
+     */
+    connect(): Promise<void>;
+    /**
+     * Stops watching (event stream and/or polling timer) and emits
+     * 'disconnected' when the client was connected. Leaves no open handles.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Core JMAP method-call helper (RFC 8620 §3.2): POSTs { using, methodCalls }
+     * to the session's apiUrl and returns the methodResponses. HTTP problem
+     * details (RFC 7807) and JMAP `error` method responses are thrown as
+     * JmapError with `httpStatus`/`problemType`/`jmapErrorType` fields.
+     */
+    request(methodCalls: TJmapMethodCall[]): Promise<TJmapMethodResponse[]>;
+    /** Returns all mailboxes of the account (Mailbox/get with ids: null). */
+    getMailboxes(): Promise<IJmapMailbox[]>;
+    /**
+     * Runs Email/query (default filter: the watched mailbox) followed by a full
+     * Email/get and returns resolved messages, newest first.
+     */
+    queryEmails(filter?: Record<string, any>, limit?: number): Promise<ISmartJmapMessage[]>;
+    /** Fetches a single email with all body values resolved (RFC 8621 §4.2, fetchAllBodyValues). */
+    getEmail(id: string): Promise<ISmartJmapMessage>;
+    /** Replaces the full keywords object of an email via Email/set. */
+    setKeywords(emailId: string, keywords: Record<string, boolean>): Promise<void>;
+    /** Convenience: sets the $seen keyword via an Email/set keywords patch. */
+    markSeen(emailId: string): Promise<void>;
+    /**
+     * Sends an email: Identity/get lookup, Email/set create (into the mailbox
+     * with role 'sent', falling back to 'drafts', then the watched mailbox) and
+     * EmailSubmission/set referencing the created email.
+     */
+    sendEmail(outgoing: IJmapOutgoingEmail): Promise<IJmapSendResult>;
+    /**
+     * Downloads a blob's raw bytes using the session downloadUrl template
+     * (RFC 8620 §6.2: {accountId}, {blobId}, {type}, {name}).
+     */
+    downloadBlob(blobId: string, type?: string, name?: string): Promise<Uint8Array>;
+    private getAuthHeader;
+    private createHttpError;
+    private resolveMailbox;
+    private fetchEmailState;
+    private getEmailObjects;
+    private updateEmail;
+    private toMessage;
+    private emitMessage;
+    private emitInitialEmails;
+    private startWatching;
+    /**
+     * Watches the JMAP event source (RFC 8620 §7.3) by parsing SSE frames from
+     * a fetch body stream. A hand-rolled parser is used instead of the global
+     * EventSource because JMAP requires an Authorization header, which the
+     * WHATWG EventSource API cannot send.
+     */
+    private startEventStream;
+    private runEventStream;
+    private handleEventStreamEvent;
+    private startPolling;
+    private fetchDeltas;
+    private fetchDeltasOnce;
+    /** Full resync fallback when the server cannot calculate changes. */
+    private resyncViaQuery;
+    private teardownWatchers;
+}