@upyo/jmap 0.4.0-dev.1

package/dist/index.d.cts

@@ -0,0 +1,286 @@
+import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
+
+//#region src/config.d.ts
+
+/**
+ * Configuration interface for JMAP transport connection settings.
+ * @since 0.4.0
+ */
+interface JmapConfig {
+  /**
+   * The JMAP session URL (e.g., `https://server/.well-known/jmap`).
+   * This is used for session discovery per RFC 8620 Section 2.
+   */
+  readonly sessionUrl: string;
+  /**
+   * Bearer token for authentication.
+   * Used in Authorization header as `Bearer {token}`.
+   * Either `bearerToken` or `basicAuth` must be provided.
+   */
+  readonly bearerToken?: string;
+  /**
+   * Basic authentication credentials.
+   * Used in Authorization header as `Basic {base64(username:password)}`.
+   * Either `bearerToken` or `basicAuth` must be provided.
+   * @since 0.4.0
+   */
+  readonly basicAuth?: {
+    readonly username: string;
+    readonly password: string;
+  };
+  /**
+   * The JMAP account ID to use.
+   * If not provided, will be auto-detected from the session response
+   * (first account with mail capability).
+   */
+  readonly accountId?: string;
+  /**
+   * The identity ID to use for email submission.
+   * If not provided, will be auto-resolved based on sender email address.
+   */
+  readonly identityId?: string;
+  /**
+   * HTTP request timeout in milliseconds.
+   * @default 30000
+   */
+  readonly timeout?: number;
+  /**
+   * Number of retry attempts for failed requests.
+   * @default 3
+   */
+  readonly retries?: number;
+  /**
+   * Custom HTTP headers to include with requests.
+   */
+  readonly headers?: Record<string, string>;
+  /**
+   * Session cache TTL in milliseconds.
+   * Sessions are refreshed when capabilities errors occur or after this duration.
+   * @default 300000 (5 minutes)
+   */
+  readonly sessionCacheTtl?: number;
+  /**
+   * Base URL to use for rewriting session URLs.
+   * Some JMAP servers return internal hostnames in session responses.
+   * When set, URLs from the session (apiUrl, uploadUrl, etc.) will be rewritten
+   * to use this base URL instead.
+   * Example: If the session returns `http://internal-host:8080/jmap/` and
+   * baseUrl is `http://localhost:8080`, URLs will be rewritten to use localhost.
+   * @since 0.4.0
+   */
+  readonly baseUrl?: string;
+}
+/**
+ * Resolved JMAP configuration with all fields populated.
+ * @since 0.4.0
+ */
+type ResolvedJmapConfig = {
+  readonly sessionUrl: string;
+  readonly bearerToken: string | null;
+  readonly basicAuth: {
+    readonly username: string;
+    readonly password: string;
+  } | null;
+  readonly accountId: string | null;
+  readonly identityId: string | null;
+  readonly timeout: number;
+  readonly retries: number;
+  readonly headers: Record<string, string>;
+  readonly sessionCacheTtl: number;
+  readonly baseUrl: string | null;
+};
+/**
+ * Creates a resolved JMAP configuration with default values applied.
+ * @param config The user-provided configuration.
+ * @returns The resolved configuration with all fields populated.
+ * @throws Error if neither bearerToken nor basicAuth is provided.
+ * @since 0.4.0
+ */
+declare function createJmapConfig(config: JmapConfig): ResolvedJmapConfig;
+//#endregion
+//#region src/jmap-transport.d.ts
+/**
+ * JMAP transport for sending emails via JMAP protocol (RFC 8620/8621).
+ * @since 0.4.0
+ */
+declare class JmapTransport implements Transport {
+  readonly config: ResolvedJmapConfig;
+  private readonly httpClient;
+  private cachedSession;
+  /**
+   * Creates a new JMAP transport instance.
+   * @param config The JMAP transport configuration.
+   * @since 0.4.0
+   */
+  constructor(config: JmapConfig);
+  /**
+   * Sends a single email message.
+   * @param message The message to send.
+   * @param options Optional transport options.
+   * @returns A receipt indicating success or failure.
+   * @since 0.4.0
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt>;
+  /**
+   * Sends multiple messages sequentially.
+   * @param messages The messages to send.
+   * @param options Optional transport options.
+   * @yields Receipts for each message.
+   * @since 0.4.0
+   */
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+  /**
+   * Gets or refreshes the JMAP session.
+   * @param signal Optional abort signal.
+   * @returns The JMAP session.
+   * @since 0.4.0
+   */
+  private getSession;
+  /**
+   * Rewrites session URLs to use the configured baseUrl.
+   * @param session The original session from the server.
+   * @returns A new session with rewritten URLs.
+   * @since 0.4.0
+   */
+  private rewriteSessionUrls;
+  /**
+   * Gets the drafts mailbox ID from the session.
+   * @param session The JMAP session.
+   * @param accountId The account ID.
+   * @param signal Optional abort signal.
+   * @returns The drafts mailbox ID.
+   * @since 0.4.0
+   */
+  private getDraftsMailboxId;
+  /**
+   * Gets the identity ID for the sender.
+   * @param session The JMAP session.
+   * @param accountId The account ID.
+   * @param senderEmail The sender's email address.
+   * @param signal Optional abort signal.
+   * @returns The identity ID.
+   * @since 0.4.0
+   */
+  private getIdentityId;
+  /**
+   * Uploads all attachments and returns a map of contentId to blobId.
+   * @param session The JMAP session.
+   * @param accountId The account ID.
+   * @param attachments Array of attachments to upload.
+   * @param signal Optional abort signal.
+   * @returns Map of contentId to blobId.
+   * @since 0.4.0
+   */
+  private uploadAttachments;
+  /**
+   * Parses the JMAP response to extract receipt information.
+   * @param response The JMAP response.
+   * @returns A receipt indicating success or failure.
+   * @since 0.4.0
+   */
+  private parseResponse;
+}
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error class for JMAP API errors.
+ * @since 0.4.0
+ */
+declare class JmapApiError extends Error {
+  readonly statusCode?: number;
+  readonly responseBody?: string;
+  readonly jmapErrorType?: string;
+  constructor(message: string, statusCode?: number, responseBody?: string, jmapErrorType?: string);
+}
+/**
+ * JMAP-specific error types from RFC 8620.
+ * @since 0.4.0
+ */
+declare const JMAP_ERROR_TYPES: {
+  readonly unknownCapability: "urn:ietf:params:jmap:error:unknownCapability";
+  readonly notJSON: "urn:ietf:params:jmap:error:notJSON";
+  readonly notRequest: "urn:ietf:params:jmap:error:notRequest";
+  readonly limit: "urn:ietf:params:jmap:error:limit";
+};
+/**
+ * Checks if the given error is a JMAP capability error.
+ * @param error The error to check.
+ * @returns `true` if the error is a JMAP capability error, `false` otherwise.
+ * @since 0.4.0
+ */
+declare function isCapabilityError(error: unknown): boolean;
+//#endregion
+//#region src/session.d.ts
+/**
+ * JMAP Session response structure (RFC 8620 Section 2).
+ * @since 0.4.0
+ */
+interface JmapSession {
+  readonly capabilities: Record<string, unknown>;
+  readonly accounts: Record<string, JmapAccount>;
+  readonly primaryAccounts: Record<string, string>;
+  readonly username: string;
+  readonly apiUrl: string;
+  readonly downloadUrl: string;
+  readonly uploadUrl: string;
+  readonly eventSourceUrl?: string;
+  readonly state: string;
+}
+/**
+ * JMAP Account structure from session response.
+ * @since 0.4.0
+ */
+interface JmapAccount {
+  readonly name: string;
+  readonly isPersonal: boolean;
+  readonly isReadOnly: boolean;
+  readonly accountCapabilities: Record<string, unknown>;
+}
+/**
+ * JMAP Identity object for sender authorization (RFC 8621 Section 6).
+ * @since 0.4.0
+ */
+interface JmapIdentity {
+  readonly id: string;
+  readonly name: string;
+  readonly email: string;
+  readonly replyTo?: readonly {
+    readonly email: string;
+    readonly name?: string;
+  }[];
+  readonly bcc?: readonly {
+    readonly email: string;
+    readonly name?: string;
+  }[];
+  readonly textSignature?: string;
+  readonly htmlSignature?: string;
+  readonly mayDelete: boolean;
+}
+/**
+ * Cached session data with metadata.
+ * @since 0.4.0
+ */
+//#endregion
+//#region src/blob-uploader.d.ts
+/**
+ * Response from a successful blob upload.
+ */
+interface BlobUploadResponse {
+  readonly accountId: string;
+  readonly blobId: string;
+  readonly type: string;
+  readonly size: number;
+}
+/**
+ * Upload a blob to the JMAP server.
+ *
+ * @param config - The resolved JMAP configuration
+ * @param uploadUrl - The upload URL template from the session (e.g., "https://server/upload/{accountId}")
+ * @param accountId - The account ID to upload to
+ * @param blob - The blob or file to upload
+ * @param signal - Optional abort signal
+ * @returns The upload response containing the blobId
+ */
+declare function uploadBlob(config: ResolvedJmapConfig, uploadUrl: string, accountId: string, blob: Blob | File, signal?: AbortSignal): Promise<BlobUploadResponse>;
+//#endregion
+export { BlobUploadResponse, JMAP_ERROR_TYPES, JmapAccount, JmapApiError, JmapConfig, JmapIdentity, JmapSession, JmapTransport, ResolvedJmapConfig, createJmapConfig, isCapabilityError, uploadBlob };

package/dist/index.d.ts

@@ -0,0 +1,286 @@
+import { Message, Receipt, Transport, TransportOptions } from "@upyo/core";
+
+//#region src/config.d.ts
+
+/**
+ * Configuration interface for JMAP transport connection settings.
+ * @since 0.4.0
+ */
+interface JmapConfig {
+  /**
+   * The JMAP session URL (e.g., `https://server/.well-known/jmap`).
+   * This is used for session discovery per RFC 8620 Section 2.
+   */
+  readonly sessionUrl: string;
+  /**
+   * Bearer token for authentication.
+   * Used in Authorization header as `Bearer {token}`.
+   * Either `bearerToken` or `basicAuth` must be provided.
+   */
+  readonly bearerToken?: string;
+  /**
+   * Basic authentication credentials.
+   * Used in Authorization header as `Basic {base64(username:password)}`.
+   * Either `bearerToken` or `basicAuth` must be provided.
+   * @since 0.4.0
+   */
+  readonly basicAuth?: {
+    readonly username: string;
+    readonly password: string;
+  };
+  /**
+   * The JMAP account ID to use.
+   * If not provided, will be auto-detected from the session response
+   * (first account with mail capability).
+   */
+  readonly accountId?: string;
+  /**
+   * The identity ID to use for email submission.
+   * If not provided, will be auto-resolved based on sender email address.
+   */
+  readonly identityId?: string;
+  /**
+   * HTTP request timeout in milliseconds.
+   * @default 30000
+   */
+  readonly timeout?: number;
+  /**
+   * Number of retry attempts for failed requests.
+   * @default 3
+   */
+  readonly retries?: number;
+  /**
+   * Custom HTTP headers to include with requests.
+   */
+  readonly headers?: Record<string, string>;
+  /**
+   * Session cache TTL in milliseconds.
+   * Sessions are refreshed when capabilities errors occur or after this duration.
+   * @default 300000 (5 minutes)
+   */
+  readonly sessionCacheTtl?: number;
+  /**
+   * Base URL to use for rewriting session URLs.
+   * Some JMAP servers return internal hostnames in session responses.
+   * When set, URLs from the session (apiUrl, uploadUrl, etc.) will be rewritten
+   * to use this base URL instead.
+   * Example: If the session returns `http://internal-host:8080/jmap/` and
+   * baseUrl is `http://localhost:8080`, URLs will be rewritten to use localhost.
+   * @since 0.4.0
+   */
+  readonly baseUrl?: string;
+}
+/**
+ * Resolved JMAP configuration with all fields populated.
+ * @since 0.4.0
+ */
+type ResolvedJmapConfig = {
+  readonly sessionUrl: string;
+  readonly bearerToken: string | null;
+  readonly basicAuth: {
+    readonly username: string;
+    readonly password: string;
+  } | null;
+  readonly accountId: string | null;
+  readonly identityId: string | null;
+  readonly timeout: number;
+  readonly retries: number;
+  readonly headers: Record<string, string>;
+  readonly sessionCacheTtl: number;
+  readonly baseUrl: string | null;
+};
+/**
+ * Creates a resolved JMAP configuration with default values applied.
+ * @param config The user-provided configuration.
+ * @returns The resolved configuration with all fields populated.
+ * @throws Error if neither bearerToken nor basicAuth is provided.
+ * @since 0.4.0
+ */
+declare function createJmapConfig(config: JmapConfig): ResolvedJmapConfig;
+//#endregion
+//#region src/jmap-transport.d.ts
+/**
+ * JMAP transport for sending emails via JMAP protocol (RFC 8620/8621).
+ * @since 0.4.0
+ */
+declare class JmapTransport implements Transport {
+  readonly config: ResolvedJmapConfig;
+  private readonly httpClient;
+  private cachedSession;
+  /**
+   * Creates a new JMAP transport instance.
+   * @param config The JMAP transport configuration.
+   * @since 0.4.0
+   */
+  constructor(config: JmapConfig);
+  /**
+   * Sends a single email message.
+   * @param message The message to send.
+   * @param options Optional transport options.
+   * @returns A receipt indicating success or failure.
+   * @since 0.4.0
+   */
+  send(message: Message, options?: TransportOptions): Promise<Receipt>;
+  /**
+   * Sends multiple messages sequentially.
+   * @param messages The messages to send.
+   * @param options Optional transport options.
+   * @yields Receipts for each message.
+   * @since 0.4.0
+   */
+  sendMany(messages: Iterable<Message> | AsyncIterable<Message>, options?: TransportOptions): AsyncIterable<Receipt>;
+  /**
+   * Gets or refreshes the JMAP session.
+   * @param signal Optional abort signal.
+   * @returns The JMAP session.
+   * @since 0.4.0
+   */
+  private getSession;
+  /**
+   * Rewrites session URLs to use the configured baseUrl.
+   * @param session The original session from the server.
+   * @returns A new session with rewritten URLs.
+   * @since 0.4.0
+   */
+  private rewriteSessionUrls;
+  /**
+   * Gets the drafts mailbox ID from the session.
+   * @param session The JMAP session.
+   * @param accountId The account ID.
+   * @param signal Optional abort signal.
+   * @returns The drafts mailbox ID.
+   * @since 0.4.0
+   */
+  private getDraftsMailboxId;
+  /**
+   * Gets the identity ID for the sender.
+   * @param session The JMAP session.
+   * @param accountId The account ID.
+   * @param senderEmail The sender's email address.
+   * @param signal Optional abort signal.
+   * @returns The identity ID.
+   * @since 0.4.0
+   */
+  private getIdentityId;
+  /**
+   * Uploads all attachments and returns a map of contentId to blobId.
+   * @param session The JMAP session.
+   * @param accountId The account ID.
+   * @param attachments Array of attachments to upload.
+   * @param signal Optional abort signal.
+   * @returns Map of contentId to blobId.
+   * @since 0.4.0
+   */
+  private uploadAttachments;
+  /**
+   * Parses the JMAP response to extract receipt information.
+   * @param response The JMAP response.
+   * @returns A receipt indicating success or failure.
+   * @since 0.4.0
+   */
+  private parseResponse;
+}
+//#endregion
+//#region src/errors.d.ts
+/**
+ * Error class for JMAP API errors.
+ * @since 0.4.0
+ */
+declare class JmapApiError extends Error {
+  readonly statusCode?: number;
+  readonly responseBody?: string;
+  readonly jmapErrorType?: string;
+  constructor(message: string, statusCode?: number, responseBody?: string, jmapErrorType?: string);
+}
+/**
+ * JMAP-specific error types from RFC 8620.
+ * @since 0.4.0
+ */
+declare const JMAP_ERROR_TYPES: {
+  readonly unknownCapability: "urn:ietf:params:jmap:error:unknownCapability";
+  readonly notJSON: "urn:ietf:params:jmap:error:notJSON";
+  readonly notRequest: "urn:ietf:params:jmap:error:notRequest";
+  readonly limit: "urn:ietf:params:jmap:error:limit";
+};
+/**
+ * Checks if the given error is a JMAP capability error.
+ * @param error The error to check.
+ * @returns `true` if the error is a JMAP capability error, `false` otherwise.
+ * @since 0.4.0
+ */
+declare function isCapabilityError(error: unknown): boolean;
+//#endregion
+//#region src/session.d.ts
+/**
+ * JMAP Session response structure (RFC 8620 Section 2).
+ * @since 0.4.0
+ */
+interface JmapSession {
+  readonly capabilities: Record<string, unknown>;
+  readonly accounts: Record<string, JmapAccount>;
+  readonly primaryAccounts: Record<string, string>;
+  readonly username: string;
+  readonly apiUrl: string;
+  readonly downloadUrl: string;
+  readonly uploadUrl: string;
+  readonly eventSourceUrl?: string;
+  readonly state: string;
+}
+/**
+ * JMAP Account structure from session response.
+ * @since 0.4.0
+ */
+interface JmapAccount {
+  readonly name: string;
+  readonly isPersonal: boolean;
+  readonly isReadOnly: boolean;
+  readonly accountCapabilities: Record<string, unknown>;
+}
+/**
+ * JMAP Identity object for sender authorization (RFC 8621 Section 6).
+ * @since 0.4.0
+ */
+interface JmapIdentity {
+  readonly id: string;
+  readonly name: string;
+  readonly email: string;
+  readonly replyTo?: readonly {
+    readonly email: string;
+    readonly name?: string;
+  }[];
+  readonly bcc?: readonly {
+    readonly email: string;
+    readonly name?: string;
+  }[];
+  readonly textSignature?: string;
+  readonly htmlSignature?: string;
+  readonly mayDelete: boolean;
+}
+/**
+ * Cached session data with metadata.
+ * @since 0.4.0
+ */
+//#endregion
+//#region src/blob-uploader.d.ts
+/**
+ * Response from a successful blob upload.
+ */
+interface BlobUploadResponse {
+  readonly accountId: string;
+  readonly blobId: string;
+  readonly type: string;
+  readonly size: number;
+}
+/**
+ * Upload a blob to the JMAP server.
+ *
+ * @param config - The resolved JMAP configuration
+ * @param uploadUrl - The upload URL template from the session (e.g., "https://server/upload/{accountId}")
+ * @param accountId - The account ID to upload to
+ * @param blob - The blob or file to upload
+ * @param signal - Optional abort signal
+ * @returns The upload response containing the blobId
+ */
+declare function uploadBlob(config: ResolvedJmapConfig, uploadUrl: string, accountId: string, blob: Blob | File, signal?: AbortSignal): Promise<BlobUploadResponse>;
+//#endregion
+export { BlobUploadResponse, JMAP_ERROR_TYPES, JmapAccount, JmapApiError, JmapConfig, JmapIdentity, JmapSession, JmapTransport, ResolvedJmapConfig, createJmapConfig, isCapabilityError, uploadBlob };