jmap-kit 0.0.0 → 1.0.2

package/dist/src/capabilities/email/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/capabilities/email/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/capabilities/email/types.ts"],"names":[],"mappings":""}

package/dist/src/capabilities/email-capability.d.ts

@@ -0,0 +1,266 @@
+import { z } from "zod/v4";
+import type { ValidationPlugin } from "../capability-registry/types.js";
+import { EMAIL_CAPABILITY_URI } from "../common/registry.js";
+import type { EmailImportRequestInvocationArgs, EmailQueryRequestInvocationArgs } from "./email/types.js";
+import type { MailboxSetRequestInvocationArgs } from "./mailbox/types.js";
+/**
+ * Validates that invocations using the Email capability have a valid accountId that supports the Email capability.
+ *
+ * This plugin performs three critical validation checks:
+ * 1. Verifies the invocation includes a valid `accountId` argument (non-empty string)
+ * 2. Confirms the account exists in the session's accounts collection
+ * 3. Ensures the account's `accountCapabilities` includes the Email capability URI
+ *
+ * This validation applies to all Email capability invocations (Mailbox, Email, Thread method calls)
+ * and implements the account capability checks described in RFC 8621 Section 1.2.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-1.2 | RFC 8621 Section 1.2: Addition to the Capabilities Object}
+
+ */
+export declare const emailAccountSupportPlugin: ValidationPlugin<"invocation">;
+/**
+ * Validates server-defined constraints for Mailbox/set operations.
+ *
+ * This plugin enforces account-specific mailbox creation limits defined in the Email capability:
+ *
+ * **Mailbox Name Length (RFC 8621 Section 2.2):**
+ * - Validates that mailbox names do not exceed `maxSizeMailboxName` octets (UTF-8 encoded)
+ * - The limit is server-defined and specified in the account's Email capability object
+ * - Prevents creation attempts that would be rejected by the server
+ *
+ * **Top-Level Mailbox Creation (RFC 8621 Section 2.2):**
+ * - Checks the `mayCreateTopLevelMailbox` server capability
+ * - Prevents attempts to create mailboxes with `parentId: null` when the server prohibits it
+ * - This restriction varies by server implementation and account type
+ *
+ * These validations catch client errors before sending requests to the server, providing
+ * immediate feedback and avoiding unnecessary network round-trips.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-2.2 | RFC 8621 Section 2.2: Mailboxes}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-1.2 | RFC 8621 Section 1.2: Addition to the Capabilities Object}
+
+ */
+export declare const mailboxSetValidationPlugin: ValidationPlugin<"invocation", MailboxSetRequestInvocationArgs>;
+/**
+ * Validates that Email/query sort properties are supported by the server.
+ *
+ * **Sort Property Validation (RFC 8621 Section 4.4):**
+ * - Checks that all sort properties specified in the `sort` argument are included in the
+ *   account's `emailQuerySortOptions` capability
+ * - The server defines which Email properties can be used for sorting in queries
+ * - Common sort options include `receivedAt`, `from`, `to`, `subject`, `size`, and `hasAttachment`
+ * - Server support varies based on implementation and indexing capabilities
+ *
+ * This validation prevents query errors by catching unsupported sort properties before
+ * sending the request. Without this check, the server would reject the query with an
+ * `unsupportedSort` error.
+ *
+ * **Example:**
+ * If a server only supports sorting by `receivedAt` and `size`, attempting to sort by
+ * `sentAt` would be caught and reported by this validator.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-4.4 | RFC 8621 Section 4.4: Email/query}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-1.3 | RFC 8621 Section 1.3: Addition to the Capabilities Object (emailQuerySortOptions)}
+ */
+export declare const emailQueryValidationPlugin: ValidationPlugin<"invocation", EmailQueryRequestInvocationArgs>;
+/**
+ * Prevents Email/import operations on read-only accounts.
+ *
+ * **Read-Only Account Protection (RFC 8620 Section 2, RFC 8621 Section 4.8):**
+ * - Validates that the target account's `isReadOnly` property is `false`
+ * - Read-only accounts cannot accept data modification operations
+ * - Email/import creates new Email objects, which requires write access
+ * - Attempting to import into a read-only account would fail with an `accountReadOnly` error
+ *
+ * This validator catches the error client-side before making a server request, providing
+ * immediate feedback when attempting invalid operations on read-only accounts.
+ *
+ * **Common read-only scenarios:**
+ * - Shared mailboxes with read-only permissions
+ * - Archive accounts
+ * - Accounts in maintenance mode
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-4.8 | RFC 8621 Section 4.8: Email/import}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-2 | RFC 8620 Section 2: The JMAP Session Resource}
+ */
+export declare const preventEmailImportOnReadOnlyAccountPlugin: ValidationPlugin<"invocation", EmailImportRequestInvocationArgs>;
+/**
+ * Defines the Email capability, including all its associated invocations
+ * (Mailbox, Thread, Email, SearchSnippet) and validation plugins.
+ */
+export declare const EmailCapability: {
+    uri: "urn:ietf:params:jmap:mail";
+    invocations: {
+        Mailbox: {
+            request: {
+                get: import("../index.js").InvocationFactory<import("./mailbox/types.js").MailboxGetRequestInvocationArgs, import("./mailbox/mailbox.js").MailboxInvocation<import("./mailbox/types.js").MailboxGetRequestInvocationArgs>>;
+                changes: import("../index.js").InvocationFactory<import("../index.js").BaseChangesRequestInvocationArgs, import("./mailbox/mailbox.js").MailboxInvocation<import("../index.js").BaseChangesRequestInvocationArgs>>;
+                query: import("../index.js").InvocationFactory<import("./mailbox/types.js").MailboxQueryRequestInvocationArgs, import("./mailbox/mailbox.js").MailboxInvocation<import("./mailbox/types.js").MailboxQueryRequestInvocationArgs>>;
+                queryChanges: import("../index.js").InvocationFactory<import("./mailbox/types.js").MailboxQueryChangesRequestInvocationArgs, import("./mailbox/mailbox.js").MailboxInvocation<import("./mailbox/types.js").MailboxQueryChangesRequestInvocationArgs>>;
+                set: import("../index.js").InvocationFactory<MailboxSetRequestInvocationArgs, import("./mailbox/mailbox.js").MailboxInvocation<MailboxSetRequestInvocationArgs>>;
+            };
+            response: {
+                get: import("../index.js").InvocationFactory<import("./mailbox/types.js").MailboxGetResponseInvocationArgs, import("./mailbox/mailbox.js").MailboxInvocation<import("./mailbox/types.js").MailboxGetResponseInvocationArgs>>;
+                changes: import("../index.js").InvocationFactory<import("./mailbox/types.js").MailboxChangesResponseInvocationArgs, import("./mailbox/mailbox.js").MailboxInvocation<import("./mailbox/types.js").MailboxChangesResponseInvocationArgs>>;
+                query: import("../index.js").InvocationFactory<import("../index.js").BaseQueryResponseInvocationArgs, import("./mailbox/mailbox.js").MailboxInvocation<import("../index.js").BaseQueryResponseInvocationArgs>>;
+                queryChanges: import("../index.js").InvocationFactory<import("../index.js").BaseQueryChangesResponseInvocationArgs, import("./mailbox/mailbox.js").MailboxInvocation<import("../index.js").BaseQueryChangesResponseInvocationArgs>>;
+                set: import("../index.js").InvocationFactory<import("./mailbox/types.js").MailboxSetResponseInvocationArgs, import("./mailbox/mailbox.js").MailboxInvocation<import("./mailbox/types.js").MailboxSetResponseInvocationArgs>>;
+            };
+        };
+        Thread: {
+            request: {
+                get: import("../index.js").InvocationFactory<import("./thread/types.js").ThreadGetRequestInvocationArgs, import("./thread/thread.js").ThreadInvocation<import("./thread/types.js").ThreadGetRequestInvocationArgs>>;
+                changes: import("../index.js").InvocationFactory<import("../index.js").BaseChangesRequestInvocationArgs, import("./thread/thread.js").ThreadInvocation<import("../index.js").BaseChangesRequestInvocationArgs>>;
+            };
+            response: {
+                get: import("../index.js").InvocationFactory<import("./thread/types.js").ThreadGetResponseInvocationArgs, import("./thread/thread.js").ThreadInvocation<import("./thread/types.js").ThreadGetResponseInvocationArgs>>;
+                changes: import("../index.js").InvocationFactory<import("../index.js").BaseChangesResponseInvocationArgs, import("./thread/thread.js").ThreadInvocation<import("../index.js").BaseChangesResponseInvocationArgs>>;
+            };
+        };
+        Email: {
+            request: {
+                get: import("../index.js").InvocationFactory<import("./email/types.js").EmailGetRequestInvocationArgs, import("./email/email.js").EmailInvocation<import("./email/types.js").EmailGetRequestInvocationArgs>>;
+                changes: import("../index.js").InvocationFactory<import("../index.js").BaseChangesRequestInvocationArgs, import("./email/email.js").EmailInvocation<import("../index.js").BaseChangesRequestInvocationArgs>>;
+                query: import("../index.js").InvocationFactory<EmailQueryRequestInvocationArgs, import("./email/email.js").EmailInvocation<EmailQueryRequestInvocationArgs>>;
+                queryChanges: import("../index.js").InvocationFactory<import("./email/types.js").EmailQueryChangesRequestInvocationArgs, import("./email/email.js").EmailInvocation<import("./email/types.js").EmailQueryChangesRequestInvocationArgs>>;
+                copy: import("../index.js").InvocationFactory<import("./email/types.js").EmailCopyRequestInvocationArgs, import("./email/email.js").EmailInvocation<import("./email/types.js").EmailCopyRequestInvocationArgs>>;
+                set: import("../index.js").InvocationFactory<import("./email/types.js").EmailSetRequestInvocationArgs, import("./email/email.js").EmailInvocation<import("./email/types.js").EmailSetRequestInvocationArgs>>;
+                import: import("../index.js").InvocationFactory<EmailImportRequestInvocationArgs, import("./email/email.js").EmailInvocation<EmailImportRequestInvocationArgs>>;
+                parse: import("../index.js").InvocationFactory<import("./email/types.js").EmailParseRequestInvocationArgs, import("./email/email.js").EmailInvocation<import("./email/types.js").EmailParseRequestInvocationArgs>>;
+            };
+            response: {
+                get: import("../index.js").InvocationFactory<import("./email/types.js").EmailGetResponseInvocationArgs, import("./email/email.js").EmailInvocation<import("./email/types.js").EmailGetResponseInvocationArgs>>;
+                changes: import("../index.js").InvocationFactory<import("../index.js").BaseChangesResponseInvocationArgs, import("./email/email.js").EmailInvocation<import("../index.js").BaseChangesResponseInvocationArgs>>;
+                query: import("../index.js").InvocationFactory<import("../index.js").BaseQueryResponseInvocationArgs, import("./email/email.js").EmailInvocation<import("../index.js").BaseQueryResponseInvocationArgs>>;
+                queryChanges: import("../index.js").InvocationFactory<import("../index.js").BaseQueryChangesResponseInvocationArgs, import("./email/email.js").EmailInvocation<import("../index.js").BaseQueryChangesResponseInvocationArgs>>;
+                copy: import("../index.js").InvocationFactory<import("./email/types.js").EmailCopyResponseInvocationArgs, import("./email/email.js").EmailInvocation<import("./email/types.js").EmailCopyResponseInvocationArgs>>;
+                set: import("../index.js").InvocationFactory<import("./email/types.js").EmailSetResponseInvocationArgs, import("./email/email.js").EmailInvocation<import("./email/types.js").EmailSetResponseInvocationArgs>>;
+                import: import("../index.js").InvocationFactory<import("./email/types.js").EmailImportResponseInvocationArgs, import("./email/email.js").EmailInvocation<import("./email/types.js").EmailImportResponseInvocationArgs>>;
+                parse: import("../index.js").InvocationFactory<import("./email/types.js").EmailParseResponseInvocationArgs, import("./email/email.js").EmailInvocation<import("./email/types.js").EmailParseResponseInvocationArgs>>;
+            };
+        };
+        SearchSnippet: {
+            request: {
+                get: import("../index.js").InvocationFactory<import("./searchsnippet/types.js").SearchSnippetGetRequestInvocationArgs, import("./searchsnippet/searchsnippet.js").SearchSnippetInvocation<import("./searchsnippet/types.js").SearchSnippetGetRequestInvocationArgs>>;
+            };
+            response: {
+                get: import("../index.js").InvocationFactory<import("./searchsnippet/types.js").SearchSnippetGetResponseInvocationArgs, import("./searchsnippet/searchsnippet.js").SearchSnippetInvocation<import("./searchsnippet/types.js").SearchSnippetGetResponseInvocationArgs>>;
+            };
+        };
+    };
+    validators: ({
+        name: string;
+        hook: "invocation";
+        trigger: {
+            capabilityUri?: import("../index.js").JMAPCapability;
+            dataType?: import("../index.js").JMAPDataType;
+            method?: import("../index.js").JMAPMethodName;
+        };
+        validate(this: void, context: import("../capability-registry/types.js").BasePluginContext & {
+            invocation: import("../index.js").Invocation<import("../index.js").BaseInvocationArgs>;
+        }): import("../index.js").MaybePromise<import("../capability-registry/types.js").ValidationResult>;
+    } | {
+        name: string;
+        hook: "invocation";
+        trigger: {
+            capabilityUri?: import("../index.js").JMAPCapability;
+            dataType?: import("../index.js").JMAPDataType;
+            method?: import("../index.js").JMAPMethodName;
+        };
+        validate(this: void, context: import("../capability-registry/types.js").BasePluginContext & {
+            invocation: import("../index.js").Invocation<MailboxSetRequestInvocationArgs>;
+        }): import("../index.js").MaybePromise<import("../capability-registry/types.js").ValidationResult>;
+    } | {
+        name: string;
+        hook: "invocation";
+        trigger: {
+            capabilityUri?: import("../index.js").JMAPCapability;
+            dataType?: import("../index.js").JMAPDataType;
+            method?: import("../index.js").JMAPMethodName;
+        };
+        validate(this: void, context: import("../capability-registry/types.js").BasePluginContext & {
+            invocation: import("../index.js").Invocation<EmailQueryRequestInvocationArgs>;
+        }): import("../index.js").MaybePromise<import("../capability-registry/types.js").ValidationResult>;
+    } | {
+        name: string;
+        hook: "invocation";
+        trigger: {
+            capabilityUri?: import("../index.js").JMAPCapability;
+            dataType?: import("../index.js").JMAPDataType;
+            method?: import("../index.js").JMAPMethodName;
+        };
+        validate(this: void, context: import("../capability-registry/types.js").BasePluginContext & {
+            invocation: import("../index.js").Invocation<EmailImportRequestInvocationArgs>;
+        }): import("../index.js").MaybePromise<import("../capability-registry/types.js").ValidationResult>;
+    })[];
+    schema: {
+        accountCapability: z.ZodObject<{
+            maxMailboxesPerEmail: z.ZodNullable<z.ZodNumber>;
+            maxMailboxDepth: z.ZodNullable<z.ZodNumber>;
+            maxSizeMailboxName: z.ZodNumber;
+            maxSizeAttachmentsPerEmail: z.ZodNumber;
+            emailQuerySortOptions: z.ZodArray<z.ZodString>;
+            mayCreateTopLevelMailbox: z.ZodBoolean;
+        }, z.core.$loose>;
+    };
+};
+declare module "../common/types.js" {
+    interface ServerCapabilityRegistry {
+        [EMAIL_CAPABILITY_URI]?: EmptyObject;
+    }
+    interface AccountCapabilityRegistry {
+        [EMAIL_CAPABILITY_URI]?: {
+            /**
+             * The maximum number of Mailboxes that can be can assigned to a single Email object.
+             * This MUST be an integer >= 1, or null for no limit (or rather, the limit is always
+             * the number of Mailboxes in the account).
+             */
+            maxMailboxesPerEmail: UnsignedInt | null;
+            /**
+             * The maximum depth of the Mailbox hierarchy (i.e., one more than the maximum number of
+             * ancestors a Mailbox may have), or null for no limit.
+             */
+            maxMailboxDepth: UnsignedInt | null;
+            /**
+             * The maximum length, in (UTF-8) octets, allowed for the name of a Mailbox.
+             * This MUST be at least 100, although it is recommended servers allow more.
+             */
+            maxSizeMailboxName: UnsignedInt;
+            /**
+             * The maximum total size of attachments, in octets, allowed for a single Email object.
+             * A server MAY still reject the import or creation of an Email with a lower attachment
+             * size total (for example, if the body includes several megabytes of text, causing the
+             * size of the encoded MIME structure to be over some server-defined limit).
+             *
+             * Note that this limit is for the sum of unencoded attachment sizes. Users are generally
+             * not knowledgeable about encoding overhead, etc., nor should they need to be, so
+             * marketing and help materials normally tell them the "max size attachments". This is the
+             * unencoded size they see on their hard drive, so this capability matches that and allows
+             * the client to consistently enforce what the user understands as the limit.
+             *
+             * The server may separately have a limit for the total size of the message [@!RFC5322],
+             * created by combining the attachments (often base64 encoded) with the message headers and
+             * bodies. For example, suppose the server advertises 50 MB:
+             *
+             *     maxSizeAttachmentsPerEmail: 50000000
+             *
+             * The enforced server limit may be for a message size of 70000000 octets. Even with base64
+             * encoding and a 2 MB HTML body, 50 MB attachments would fit under this limit.
+             */
+            maxSizeAttachmentsPerEmail: UnsignedInt;
+            /**
+             * A list of all the values the server supports for the "property" field of the Comparator
+             * object in an Email/query sort (see Section 4.4.2). This MAY include properties the client
+             * does not recognise (for example, custom properties specified in a vendor extension).
+             * Clients MUST ignore any unknown properties in the list.
+             */
+            emailQuerySortOptions: string[];
+            /**
+             * If true, the user may create a Mailbox in this account with a null parentId.
+             * (Permission for creating a child of an existing Mailbox is given by the myRights property
+             * on that Mailbox.)
+             */
+            mayCreateTopLevelMailbox: boolean;
+        };
+    }
+}

package/dist/src/capabilities/email-capability.js

@@ -0,0 +1,241 @@
+import { z } from "zod/v4";
+import { EMAIL_CAPABILITY_URI } from "../common/registry.js";
+import { Email } from "./email/email.js";
+import { Mailbox } from "./mailbox/mailbox.js";
+import { SearchSnippet } from "./searchsnippet/searchsnippet.js";
+import { Thread } from "./thread/thread.js";
+import { assertInvocation } from "./utils/assert-invocation.js";
+import { assertNonNullish } from "./utils/assert-non-nullish.js";
+import { createReadOnlyAccountValidator } from "./utils/create-readonly-account-validator.js";
+/**
+ * Validates that invocations using the Email capability have a valid accountId that supports the Email capability.
+ *
+ * This plugin performs three critical validation checks:
+ * 1. Verifies the invocation includes a valid `accountId` argument (non-empty string)
+ * 2. Confirms the account exists in the session's accounts collection
+ * 3. Ensures the account's `accountCapabilities` includes the Email capability URI
+ *
+ * This validation applies to all Email capability invocations (Mailbox, Email, Thread method calls)
+ * and implements the account capability checks described in RFC 8621 Section 1.2.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-1.2 | RFC 8621 Section 1.2: Addition to the Capabilities Object}
+
+ */
+export const emailAccountSupportPlugin = {
+    name: "email-account-support",
+    hook: "invocation",
+    trigger: {
+        capabilityUri: EMAIL_CAPABILITY_URI,
+    },
+    validate(context) {
+        const { invocation, accounts } = context;
+        const accountId = invocation.getArgument("accountId");
+        if (typeof accountId !== "string" || accountId === "") {
+            return {
+                valid: false,
+                errors: [new Error(`Invocation is missing a valid accountId argument.`)],
+            };
+        }
+        const account = accounts[accountId];
+        if (!account) {
+            return {
+                valid: false,
+                errors: [new Error(`Account "${accountId}" does not exist.`)],
+            };
+        }
+        if (!account.accountCapabilities[EMAIL_CAPABILITY_URI]) {
+            return {
+                valid: false,
+                errors: [new Error(`Account "${accountId}" does not support the Email capability.`)],
+            };
+        }
+        return { valid: true };
+    },
+};
+/**
+ * Validates server-defined constraints for Mailbox/set operations.
+ *
+ * This plugin enforces account-specific mailbox creation limits defined in the Email capability:
+ *
+ * **Mailbox Name Length (RFC 8621 Section 2.2):**
+ * - Validates that mailbox names do not exceed `maxSizeMailboxName` octets (UTF-8 encoded)
+ * - The limit is server-defined and specified in the account's Email capability object
+ * - Prevents creation attempts that would be rejected by the server
+ *
+ * **Top-Level Mailbox Creation (RFC 8621 Section 2.2):**
+ * - Checks the `mayCreateTopLevelMailbox` server capability
+ * - Prevents attempts to create mailboxes with `parentId: null` when the server prohibits it
+ * - This restriction varies by server implementation and account type
+ *
+ * These validations catch client errors before sending requests to the server, providing
+ * immediate feedback and avoiding unnecessary network round-trips.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-2.2 | RFC 8621 Section 2.2: Mailboxes}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-1.2 | RFC 8621 Section 1.2: Addition to the Capabilities Object}
+
+ */
+export const mailboxSetValidationPlugin = {
+    name: "mailbox-validation",
+    hook: "invocation",
+    trigger: {
+        capabilityUri: EMAIL_CAPABILITY_URI,
+        dataType: "Mailbox",
+        method: "set",
+    },
+    validate(context) {
+        const { invocation, accounts } = context;
+        assertInvocation(invocation, "Mailbox", "set");
+        const accountId = invocation.getArgument("accountId");
+        const account = accounts[accountId];
+        if (!account) {
+            return {
+                valid: false,
+                errors: [new Error(`Account "${accountId}" does not exist.`)],
+            };
+        }
+        const emailCapability = account.accountCapabilities[EMAIL_CAPABILITY_URI];
+        assertNonNullish(emailCapability, "Email capability");
+        const create = invocation.getArgument("create");
+        if (!create) {
+            return { valid: true };
+        }
+        const errors = [];
+        // Create a TextEncoder once for UTF-8 encoding
+        const encoder = new TextEncoder();
+        for (const [clientId, mailbox] of Object.entries(create)) {
+            // Validate mailbox name length (in UTF-8 octets)
+            const nameOctetLength = encoder.encode(mailbox.name).length;
+            if (nameOctetLength > emailCapability.maxSizeMailboxName) {
+                errors.push(new Error(`Mailbox name for ${clientId} exceeds maximum length of ${emailCapability.maxSizeMailboxName} octets (actual: ${nameOctetLength} octets)`));
+            }
+            // Validate top-level mailbox creation permission
+            if (mailbox.parentId === null && !emailCapability.mayCreateTopLevelMailbox) {
+                errors.push(new Error(`Account "${accountId}" does not allow creating top-level mailboxes`));
+            }
+        }
+        if (errors.length > 0) {
+            return {
+                valid: false,
+                errors,
+            };
+        }
+        return { valid: true };
+    },
+};
+/**
+ * Validates that Email/query sort properties are supported by the server.
+ *
+ * **Sort Property Validation (RFC 8621 Section 4.4):**
+ * - Checks that all sort properties specified in the `sort` argument are included in the
+ *   account's `emailQuerySortOptions` capability
+ * - The server defines which Email properties can be used for sorting in queries
+ * - Common sort options include `receivedAt`, `from`, `to`, `subject`, `size`, and `hasAttachment`
+ * - Server support varies based on implementation and indexing capabilities
+ *
+ * This validation prevents query errors by catching unsupported sort properties before
+ * sending the request. Without this check, the server would reject the query with an
+ * `unsupportedSort` error.
+ *
+ * **Example:**
+ * If a server only supports sorting by `receivedAt` and `size`, attempting to sort by
+ * `sentAt` would be caught and reported by this validator.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-4.4 | RFC 8621 Section 4.4: Email/query}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-1.3 | RFC 8621 Section 1.3: Addition to the Capabilities Object (emailQuerySortOptions)}
+ */
+export const emailQueryValidationPlugin = {
+    name: "email-validation",
+    hook: "invocation",
+    trigger: {
+        capabilityUri: EMAIL_CAPABILITY_URI,
+        dataType: "Email",
+        method: "query",
+    },
+    validate(context) {
+        const { invocation, accounts } = context;
+        assertInvocation(invocation, "Email", "query");
+        const accountId = invocation.getArgument("accountId");
+        const account = accounts[accountId];
+        if (!account) {
+            return {
+                valid: false,
+                errors: [new Error(`Account ${accountId} does not exist.`)],
+            };
+        }
+        const emailCapability = account.accountCapabilities[EMAIL_CAPABILITY_URI];
+        assertNonNullish(emailCapability, "Email capability");
+        const sort = invocation.getArgument("sort");
+        if (sort) {
+            const errors = [];
+            const { emailQuerySortOptions } = emailCapability;
+            for (const { property } of sort) {
+                if (!emailQuerySortOptions.includes(property)) {
+                    errors.push(new Error(`Unsupported sort property '${property}' for Account ${accountId}. Supported properties: ${emailQuerySortOptions.join(", ")}`));
+                }
+            }
+            if (errors.length > 0) {
+                return {
+                    valid: false,
+                    errors,
+                };
+            }
+        }
+        return { valid: true };
+    },
+};
+/**
+ * Prevents Email/import operations on read-only accounts.
+ *
+ * **Read-Only Account Protection (RFC 8620 Section 2, RFC 8621 Section 4.8):**
+ * - Validates that the target account's `isReadOnly` property is `false`
+ * - Read-only accounts cannot accept data modification operations
+ * - Email/import creates new Email objects, which requires write access
+ * - Attempting to import into a read-only account would fail with an `accountReadOnly` error
+ *
+ * This validator catches the error client-side before making a server request, providing
+ * immediate feedback when attempting invalid operations on read-only accounts.
+ *
+ * **Common read-only scenarios:**
+ * - Shared mailboxes with read-only permissions
+ * - Archive accounts
+ * - Accounts in maintenance mode
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-4.8 | RFC 8621 Section 4.8: Email/import}
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8620.html#section-2 | RFC 8620 Section 2: The JMAP Session Resource}
+ */
+export const preventEmailImportOnReadOnlyAccountPlugin = createReadOnlyAccountValidator({
+    name: "email-prevent-import-on-readonly-account",
+    trigger: {
+        dataType: "Email",
+        method: "import",
+    },
+});
+const emailAccountCapabilitySchema = z.looseObject({
+    maxMailboxesPerEmail: z.number().int().min(1).nullable(),
+    maxMailboxDepth: z.number().int().min(1).nullable(),
+    maxSizeMailboxName: z.number().int().min(100),
+    maxSizeAttachmentsPerEmail: z.number().int().min(0),
+    emailQuerySortOptions: z.array(z.string()),
+    mayCreateTopLevelMailbox: z.boolean(),
+});
+/**
+ * Defines the Email capability, including all its associated invocations
+ * (Mailbox, Thread, Email, SearchSnippet) and validation plugins.
+ */
+export const EmailCapability = {
+    uri: EMAIL_CAPABILITY_URI,
+    invocations: {
+        Mailbox,
+        Thread,
+        Email,
+        SearchSnippet,
+    },
+    validators: [
+        emailAccountSupportPlugin,
+        mailboxSetValidationPlugin,
+        emailQueryValidationPlugin,
+        preventEmailImportOnReadOnlyAccountPlugin,
+    ],
+    schema: { accountCapability: emailAccountCapabilitySchema },
+};
+//# sourceMappingURL=email-capability.js.map

package/dist/src/capabilities/email-capability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-capability.js","sourceRoot":"","sources":["../../../src/capabilities/email-capability.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAE3B,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAEzC,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AACjE,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAAE,8BAA8B,EAAE,MAAM,8CAA8C,CAAC;AAE9F;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAmC;IACrE,IAAI,EAAE,uBAAuB;IAC7B,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE;QACL,aAAa,EAAE,oBAAoB;KACtC;IACD,QAAQ,CAAC,OAAO;QACZ,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;QACzC,MAAM,SAAS,GAAG,UAAU,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;QACtD,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;YACpD,OAAO;gBACH,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,CAAC,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;aAC3E,CAAC;QACN,CAAC;QACD,MAAM,OAAO,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;QACpC,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO;gBACH,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,CAAC,IAAI,KAAK,CAAC,YAAY,SAAS,mBAAmB,CAAC,CAAC;aAChE,CAAC;QACN,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,mBAAmB,CAAC,oBAAoB,CAAC,EAAE,CAAC;YACrD,OAAO;gBACH,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,CAAC,IAAI,KAAK,CAAC,YAAY,SAAS,0CAA0C,CAAC,CAAC;aACvF,CAAC;QACN,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;CACJ,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAoE;IACvG,IAAI,EAAE,oBAAoB;IAC1B,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE;QACL,aAAa,EAAE,oBAAoB;QACnC,QAAQ,EAAE,SAAS;QACnB,MAAM,EAAE,KAAK;KAChB;IACD,QAAQ,CAAC,OAAO;QACZ,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;QAEzC,gBAAgB,CAAC,UAAU,EAAE,SAAS,EAAE,KAAK,CAAC,CAAC;QAE/C,MAAM,SAAS,GAAG,UAAU,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;QACtD,MAAM,OAAO,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;QAEpC,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO;gBACH,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,CAAC,IAAI,KAAK,CAAC,YAAY,SAAS,mBAAmB,CAAC,CAAC;aAChE,CAAC;QACN,CAAC;QAED,MAAM,eAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC,oBAAoB,CAAC,CAAC;QAE1E,gBAAgB,CAAC,eAAe,EAAE,kBAAkB,CAAC,CAAC;QAEtD,MAAM,MAAM,GAAG,UAAU,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;QAEhD,IAAI,CAAC,MAAM,EAAE,CAAC;YACV,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;QAC3B,CAAC;QAED,MAAM,MAAM,GAAY,EAAE,CAAC;QAE3B,+CAA+C;QAC/C,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;QAElC,KAAK,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YACvD,iDAAiD;YACjD,MAAM,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC;YAC5D,IAAI,eAAe,GAAG,eAAe,CAAC,kBAAkB,EAAE,CAAC;gBACvD,MAAM,CAAC,IAAI,CACP,IAAI,KAAK,CACL,oBAAoB,QAAQ,8BAA8B,eAAe,CAAC,kBAAkB,oBAAoB,eAAe,UAAU,CAC5I,CACJ,CAAC;YACN,CAAC;YAED,iDAAiD;YACjD,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,eAAe,CAAC,wBAAwB,EAAE,CAAC;gBACzE,MAAM,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,YAAY,SAAS,+CAA+C,CAAC,CAAC,CAAC;YACjG,CAAC;QACL,CAAC;QAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpB,OAAO;gBACH,KAAK,EAAE,KAAK;gBACZ,MAAM;aACT,CAAC;QACN,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;CACJ,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAoE;IACvG,IAAI,EAAE,kBAAkB;IACxB,IAAI,EAAE,YAAY;IAClB,OAAO,EAAE;QACL,aAAa,EAAE,oBAAoB;QACnC,QAAQ,EAAE,OAAO;QACjB,MAAM,EAAE,OAAO;KAClB;IACD,QAAQ,CAAC,OAAO;QACZ,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;QAEzC,gBAAgB,CAAC,UAAU,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QAE/C,MAAM,SAAS,GAAG,UAAU,CAAC,WAAW,CAAC,WAAW,CAAC,CAAC;QACtD,MAAM,OAAO,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;QACpC,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,OAAO;gBACH,KAAK,EAAE,KAAK;gBACZ,MAAM,EAAE,CAAC,IAAI,KAAK,CAAC,WAAW,SAAS,kBAAkB,CAAC,CAAC;aAC9D,CAAC;QACN,CAAC;QAED,MAAM,eAAe,GAAG,OAAO,CAAC,mBAAmB,CAAC,oBAAoB,CAAC,CAAC;QAC1E,gBAAgB,CAAC,eAAe,EAAE,kBAAkB,CAAC,CAAC;QAEtD,MAAM,IAAI,GAAG,UAAU,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAE5C,IAAI,IAAI,EAAE,CAAC;YACP,MAAM,MAAM,GAAY,EAAE,CAAC;YAC3B,MAAM,EAAE,qBAAqB,EAAE,GAAG,eAAe,CAAC;YAElD,KAAK,MAAM,EAAE,QAAQ,EAAE,IAAI,IAAI,EAAE,CAAC;gBAC9B,IAAI,CAAC,qBAAqB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;oBAC5C,MAAM,CAAC,IAAI,CACP,IAAI,KAAK,CACL,8BAA8B,QAAQ,iBAAiB,SAAS,2BAA2B,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAChI,CACJ,CAAC;gBACN,CAAC;YACL,CAAC;YAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACpB,OAAO;oBACH,KAAK,EAAE,KAAK;oBACZ,MAAM;iBACT,CAAC;YACN,CAAC;QACL,CAAC;QAED,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC3B,CAAC;CACJ,CAAC;AAEF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,MAAM,yCAAyC,GAGlD,8BAA8B,CAAmC;IACjE,IAAI,EAAE,0CAA0C;IAChD,OAAO,EAAE;QACL,QAAQ,EAAE,OAAO;QACjB,MAAM,EAAE,QAAQ;KACnB;CACJ,CAAC,CAAC;AAEH,MAAM,4BAA4B,GAAG,CAAC,CAAC,WAAW,CAAC;IAC/C,oBAAoB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACxD,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IACnD,kBAAkB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC;IAC7C,0BAA0B,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACnD,qBAAqB,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC1C,wBAAwB,EAAE,CAAC,CAAC,OAAO,EAAE;CACxC,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;IAC3B,GAAG,EAAE,oBAAoB;IACzB,WAAW,EAAE;QACT,OAAO;QACP,MAAM;QACN,KAAK;QACL,aAAa;KAChB;IACD,UAAU,EAAE;QACR,yBAAyB;QACzB,0BAA0B;QAC1B,0BAA0B;QAC1B,yCAAyC;KAC5C;IACD,MAAM,EAAE,EAAE,iBAAiB,EAAE,4BAA4B,EAAE;CAC/B,CAAC"}

package/dist/src/capabilities/emailsubmission/emailsubmission.d.ts

@@ -0,0 +1,95 @@
+import type { JMAPCapability, JMAPMethodName } from "../../common/types.js";
+import { Invocation } from "../../invocation/invocation.js";
+import type { InvocationArgs, InvocationFactory } from "../../invocation/types.js";
+import type { EmailSubmissionGetRequestInvocationArgs, EmailSubmissionGetResponseInvocationArgs, EmailSubmissionQueryChangesRequestInvocationArgs, EmailSubmissionQueryRequestInvocationArgs, EmailSubmissionRequestInvocationArgs, EmailSubmissionResponseInvocationArgs, EmailSubmissionSetRequestInvocationArgs, EmailSubmissionSetResponseInvocationArgs } from "./types.js";
+/**
+ * EmailSubmissionInvocation represents a JMAP EmailSubmission capability invocation.
+ *
+ * An EmailSubmission object represents the submission of an Email for delivery to one or more
+ * recipients. It supports standard JMAP methods for retrieving, querying, and modifying submissions.
+ *
+ * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-7 | RFC 8621 Section 7: Email Submission}
+ */
+export declare class EmailSubmissionInvocation<TArgs extends EmailSubmissionRequestInvocationArgs | EmailSubmissionResponseInvocationArgs> extends Invocation<TArgs> {
+    get uri(): JMAPCapability;
+    /**
+     * Constructs an EmailSubmissionInvocation
+     *
+     * @param method The name of the method being invoked (e.g., "get", "set", "query")
+     * @param args The arguments for the method invocation
+     * @param methodCallId An optional unique symbol to identify this method call for result referencing
+     */
+    constructor(method: JMAPMethodName, args: InvocationArgs<TArgs>, methodCallId?: symbol);
+    /**
+     * Create an invocation factory function
+     *
+     * @param method The name of the method to create
+     * @returns A new EmailSubmission invocation factory function for creating invocations of the specified type
+     */
+    static createInvocationFactory<TArgs extends EmailSubmissionRequestInvocationArgs | EmailSubmissionResponseInvocationArgs>(method: JMAPMethodName): InvocationFactory<TArgs, EmailSubmissionInvocation<TArgs>>;
+}
+export declare const EmailSubmission: {
+    request: {
+        /**
+         * Retrieves EmailSubmission objects by their IDs.
+         *
+         * @param args The invocation arguments for EmailSubmission/get
+         * @param methodCallId An optional unique symbol to identify this method call for result referencing
+         * @returns An EmailSubmissionInvocation representing the EmailSubmission/get request
+         *
+         * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-7.1 | RFC 8621 Section 7.1: EmailSubmission/get}
+         */
+        get: InvocationFactory<EmailSubmissionGetRequestInvocationArgs, EmailSubmissionInvocation<EmailSubmissionGetRequestInvocationArgs>>;
+        /**
+         * Returns changes to EmailSubmission objects since a given state.
+         *
+         * @param args The invocation arguments for EmailSubmission/changes
+         * @param methodCallId An optional unique symbol to identify this method call for result referencing
+         * @returns An EmailSubmissionInvocation representing the EmailSubmission/changes request
+         *
+         * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-7.2 | RFC 8621 Section 7.2: EmailSubmission/changes}
+         */
+        changes: InvocationFactory<import("../../invocation/types.js").BaseChangesRequestInvocationArgs, EmailSubmissionInvocation<import("../../invocation/types.js").BaseChangesRequestInvocationArgs>>;
+        /**
+         * Queries for EmailSubmission objects matching specified criteria.
+         *
+         * @param args The invocation arguments for EmailSubmission/query
+         * @param methodCallId An optional unique symbol to identify this method call for result referencing
+         * @returns An EmailSubmissionInvocation representing the EmailSubmission/query request
+         *
+         * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-7.3 | RFC 8621 Section 7.3: EmailSubmission/query}
+         */
+        query: InvocationFactory<EmailSubmissionQueryRequestInvocationArgs, EmailSubmissionInvocation<EmailSubmissionQueryRequestInvocationArgs>>;
+        /**
+         * Returns changes to a query result since a given state.
+         *
+         * @param args The invocation arguments for EmailSubmission/queryChanges
+         * @param methodCallId An optional unique symbol to identify this method call for result referencing
+         * @returns An EmailSubmissionInvocation representing the EmailSubmission/queryChanges request
+         *
+         * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-7.4 | RFC 8621 Section 7.4: EmailSubmission/queryChanges}
+         */
+        queryChanges: InvocationFactory<EmailSubmissionQueryChangesRequestInvocationArgs, EmailSubmissionInvocation<EmailSubmissionQueryChangesRequestInvocationArgs>>;
+        /**
+         * Creates, updates, or destroys EmailSubmission objects.
+         *
+         * An Email is sent by creating an EmailSubmission object. Additional `onSuccessUpdateEmail`
+         * and `onSuccessDestroyEmail` arguments allow updating or destroying the referenced Email
+         * upon successful submission.
+         *
+         * @param args The invocation arguments for EmailSubmission/set
+         * @param methodCallId An optional unique symbol to identify this method call for result referencing
+         * @returns An EmailSubmissionInvocation representing the EmailSubmission/set request
+         *
+         * @see {@link https://www.rfc-editor.org/rfc/rfc8621.html#section-7.5 | RFC 8621 Section 7.5: EmailSubmission/set}
+         */
+        set: InvocationFactory<EmailSubmissionSetRequestInvocationArgs, EmailSubmissionInvocation<EmailSubmissionSetRequestInvocationArgs>>;
+    };
+    response: {
+        get: InvocationFactory<EmailSubmissionGetResponseInvocationArgs, EmailSubmissionInvocation<EmailSubmissionGetResponseInvocationArgs>>;
+        changes: InvocationFactory<import("../../invocation/types.js").BaseChangesResponseInvocationArgs, EmailSubmissionInvocation<import("../../invocation/types.js").BaseChangesResponseInvocationArgs>>;
+        query: InvocationFactory<import("../../invocation/types.js").BaseQueryResponseInvocationArgs, EmailSubmissionInvocation<import("../../invocation/types.js").BaseQueryResponseInvocationArgs>>;
+        queryChanges: InvocationFactory<import("../../invocation/types.js").BaseQueryChangesResponseInvocationArgs, EmailSubmissionInvocation<import("../../invocation/types.js").BaseQueryChangesResponseInvocationArgs>>;
+        set: InvocationFactory<EmailSubmissionSetResponseInvocationArgs, EmailSubmissionInvocation<EmailSubmissionSetResponseInvocationArgs>>;
+    };
+};