jmap-kit 0.0.0 → 1.0.2

package/dist/src/common/types.js

@@ -0,0 +1,21 @@
+import { z } from "zod/v4";
+import { CORE_CAPABILITY_URI } from "./registry.js";
+/**
+ * Zod schema for JMAPServerCapabilities.
+ *
+ * Validates the structural requirement that the Core capability key is present.
+ * Content validation of individual capabilities is handled by each capability's
+ * own StandardSchema, validated via {@link CapabilityRegistryInterface.validateServerCapabilities}.
+ */
+export const JMAPServerCapabilitiesSchema = z.looseObject({
+    [CORE_CAPABILITY_URI]: z.looseObject({}),
+});
+/**
+ * Zod schema for JMAPAccountCapabilities.
+ *
+ * Validates the structural shape of account capabilities. Content validation of individual
+ * capabilities is handled by each capability's own StandardSchema, validated via
+ * {@link CapabilityRegistryInterface.validateAccountCapabilities}.
+ */
+export const JMAPAccountCapabilitiesSchema = z.looseObject({});
+//# sourceMappingURL=types.js.map

package/dist/src/common/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,QAAQ,CAAC;AAqD3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAwGpD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,WAAW,CAAC;IACtD,CAAC,mBAAmB,CAAC,EAAE,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC;CAC3C,CAAC,CAAC;AAiCH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC"}

package/dist/src/common/utils.d.ts

@@ -0,0 +1,20 @@
+import type { Id } from "./types.js";
+/**
+ * A generator function that produces unique IDs with an optional prefix. The IDs are generated as
+ * strings of incrementing BigInt values, starting from a specified initial value (default is 0).
+ * This is used for generating unique identifiers for method calls by the
+ * by the {@linkcode RequestBuilder}.
+ *
+ * @param prefix The prefix to prepend to each generated ID.
+ * @param start The initial value for the ID counter.
+ * @returns A generator that yields unique IDs as strings with the specified prefix.
+ *
+ * @example
+ * ```ts
+ * const gen = idGenerator("c");
+ * console.log(gen.next().value); // "c0"
+ * console.log(gen.next().value); // "c1"
+ * console.log(gen.next().value); // "c2"
+ * ```
+ */
+export declare function idGenerator(prefix?: string, start?: Parameters<typeof BigInt>[0]): Generator<Id, never, never>;

package/dist/src/common/utils.js

@@ -0,0 +1,26 @@
+/**
+ * A generator function that produces unique IDs with an optional prefix. The IDs are generated as
+ * strings of incrementing BigInt values, starting from a specified initial value (default is 0).
+ * This is used for generating unique identifiers for method calls by the
+ * by the {@linkcode RequestBuilder}.
+ *
+ * @param prefix The prefix to prepend to each generated ID.
+ * @param start The initial value for the ID counter.
+ * @returns A generator that yields unique IDs as strings with the specified prefix.
+ *
+ * @example
+ * ```ts
+ * const gen = idGenerator("c");
+ * console.log(gen.next().value); // "c0"
+ * console.log(gen.next().value); // "c1"
+ * console.log(gen.next().value); // "c2"
+ * ```
+ */
+export function* idGenerator(prefix = "", start = 0) {
+    let id = BigInt(start);
+    while (true) {
+        yield `${prefix}${id}`;
+        id = id + 1n;
+    }
+}
+//# sourceMappingURL=utils.js.map

package/dist/src/common/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../../src/common/utils.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,SAAS,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,EAAE,EAAE,QAAsC,CAAC;IAC7E,IAAI,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAEvB,OAAO,IAAI,EAAE,CAAC;QACV,MAAM,GAAG,MAAM,GAAG,EAAE,EAAE,CAAC;QACvB,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC;IACjB,CAAC;AACL,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,40 @@
+export { ErrorInvocation } from "./invocation/error-invocation.js";
+export { Invocation } from "./invocation/invocation.js";
+export { ResultReference } from "./invocation/result-reference.js";
+export { JMAPClient } from "./jmap-client/jmap-client.js";
+export { RequestBuilder } from "./request-builder/request-builder.js";
+export { isErrorInvocation, isResultReference } from "./invocation/utils.js";
+export { JMAPRequestError } from "./jmap-client/utils/jmap-request-error.js";
+export { BlobCapability } from "./capabilities/blob-capability.js";
+export { CoreCapability } from "./capabilities/core-capability.js";
+export { EmailCapability } from "./capabilities/email-capability.js";
+export { MaskedEmailCapability } from "./capabilities/maskedemail-capability.js";
+export { SubmissionCapability } from "./capabilities/submission-capability.js";
+export { VacationResponseCapability } from "./capabilities/vacationresponse-capability.js";
+export { Blob } from "./capabilities/blob/blob.js";
+export { Core } from "./capabilities/core/core.js";
+export { Email } from "./capabilities/email/email.js";
+export { EmailSubmission } from "./capabilities/emailsubmission/emailsubmission.js";
+export { Identity } from "./capabilities/identity/identity.js";
+export { Mailbox } from "./capabilities/mailbox/mailbox.js";
+export { MaskedEmail } from "./capabilities/maskedemail/maskedemail.js";
+export { SearchSnippet } from "./capabilities/searchsnippet/searchsnippet.js";
+export { Thread } from "./capabilities/thread/thread.js";
+export { VacationResponse } from "./capabilities/vacationresponse/vacationresponse.js";
+export * from "./common/registry.js";
+export type * from "./common/types.js";
+export type { CapabilityRegistrationResult, ClientContext, ConnectionStatus, EventEmitterFn, JMAPAccount, JMAPClientEventName, JMAPClientEvents, JMAPClientInterface, JMAPClientOptions, JMAPSession, JMAPUploadResponse, Logger, LoggerMethod, Transport, TransportRequestOptions, TransportResponseType, TypedEventEmitterFn, } from "./jmap-client/types.js";
+export type { AddedItem, BaseChangesRequestInvocationArgs, BaseChangesResponseInvocationArgs, BaseCopyRequestInvocationArgs, BaseCopyResponseInvocationArgs, BaseFilterCondition, BaseGetRequestInvocationArgs, BaseGetResponseInvocationArgs, BaseInvocationArgs, BaseObject, BaseQueryChangesRequestInvocationArgs, BaseQueryChangesResponseInvocationArgs, BaseQueryRequestInvocationArgs, BaseQueryResponseInvocationArgs, BaseSetRequestInvocationArgs, BaseSetResponseInvocationArgs, Comparator, FilterCondition, FilterOperator, GenericInvocationFactory, InvocationArgs, InvocationFactory, InvocationFactoryCollection, InvocationFactoryMethods, InvocationInterface, PatchObject, ResultReferenceInterface, SetError, SetErrorCategory, SetErrorType, } from "./invocation/types.js";
+export type { AccountCapabilityValidationResult, BasePluginContext, CapabilityDefinition, CapabilityRegistryInterface, InvocationFactoryMap, PluginContext, PluginData, PluginLifecycleHook, PluginTrigger, ServerCapabilityValidationResult, TransformationPlugin, TransformationPluginMap, TransformerExecutionContext, ValidationPlugin, ValidationPluginContext, ValidationPluginLifecycleHook, ValidationPluginMap, ValidationPluginTrigger, ValidationResult, ValidatorExecutionContext, } from "./capability-registry/types.js";
+export type { HandlerFn, InvocationHandlerMap } from "./invocation-factory/types.js";
+export type { CoreEchoRequestInvocationArgs, CoreEchoResponseInvocationArgs, CoreInvocationArgs, } from "./capabilities/core/types.js";
+export type { EmailAddress, EmailAddressGroup, EmailBodyPart, EmailBodyValue, EmailChangesRequestInvocationArgs, EmailChangesResponseInvocationArgs, EmailCopyRequestInvocationArgs, EmailCopyResponseInvocationArgs, EmailFilterCondition, EmailGetRequestInvocationArgs, EmailGetResponseInvocationArgs, EmailHeader, EmailImport, EmailImportRequestInvocationArgs, EmailImportResponseInvocationArgs, EmailObject, EmailObjectServerSet, EmailObjectSettable, EmailParseRequestInvocationArgs, EmailParseResponseInvocationArgs, EmailQueryChangesRequestInvocationArgs, EmailQueryChangesResponseInvocationArgs, EmailQueryRequestInvocationArgs, EmailQueryResponseInvocationArgs, EmailSetRequestInvocationArgs, EmailSetResponseInvocationArgs, JMAPKeywords, } from "./capabilities/email/types.js";
+export type { MailboxChangesRequestInvocationArgs, MailboxChangesResponseInvocationArgs, MailboxFilterCondition, MailboxGetRequestInvocationArgs, MailboxGetResponseInvocationArgs, MailboxObject, MailboxObjectServerSet, MailboxObjectSettable, MailboxQueryChangesRequestInvocationArgs, MailboxQueryChangesResponseInvocationArgs, MailboxQueryRequestInvocationArgs, MailboxQueryResponseInvocationArgs, MailboxRights, MailboxSetRequestInvocationArgs, MailboxSetResponseInvocationArgs, } from "./capabilities/mailbox/types.js";
+export type { ThreadChangesRequestInvocationArgs, ThreadChangesResponseInvocationArgs, ThreadGetRequestInvocationArgs, ThreadGetResponseInvocationArgs, ThreadObject, ThreadObjectServerSet, } from "./capabilities/thread/types.js";
+export type { IdentityChangesRequestInvocationArgs, IdentityChangesResponseInvocationArgs, IdentityGetRequestInvocationArgs, IdentityGetResponseInvocationArgs, IdentityObject, IdentityObjectServerSet, IdentityObjectSettable, IdentitySetRequestInvocationArgs, IdentitySetResponseInvocationArgs, } from "./capabilities/identity/types.js";
+export { HTTPDigestAlgorithmSchema as HTTPDigestAlgorithmValueSchema } from "./capabilities/blob/types.js";
+export type { BlobCopyRequestInvocationArgs, BlobCopyResponseInvocationArgs, BlobDataFormat, BlobGetRequestInvocationArgs, BlobGetResponseInvocationArgs, BlobInfo, BlobLookupRequestInvocationArgs, BlobLookupResponseInvocationArgs, BlobObject, BlobObjectData, BlobObjectDigest, BlobObjectSize, BlobUploadRequestInvocationArgs, BlobUploadResponseInvocationArgs, DataCreatedObject, DataSourceObject, HTTPDigestAlgorithm, UploadObject, } from "./capabilities/blob/types.js";
+export type { DeliveryStatus, EmailSubmissionAddress, EmailSubmissionChangesRequestInvocationArgs, EmailSubmissionChangesResponseInvocationArgs, EmailSubmissionEnvelope, EmailSubmissionFilterCondition, EmailSubmissionGetRequestInvocationArgs, EmailSubmissionGetResponseInvocationArgs, EmailSubmissionObject, EmailSubmissionObjectServerSet, EmailSubmissionObjectSettable, EmailSubmissionQueryChangesRequestInvocationArgs, EmailSubmissionQueryChangesResponseInvocationArgs, EmailSubmissionQueryRequestInvocationArgs, EmailSubmissionQueryResponseInvocationArgs, EmailSubmissionSetRequestInvocationArgs, EmailSubmissionSetResponseInvocationArgs, } from "./capabilities/emailsubmission/types.js";
+export type { VacationResponseGetRequestInvocationArgs, VacationResponseGetResponseInvocationArgs, VacationResponseObject, VacationResponseObjectServerSet, VacationResponseObjectSettable, VacationResponseSetRequestInvocationArgs, VacationResponseSetResponseInvocationArgs, } from "./capabilities/vacationresponse/types.js";
+export type { MaskedEmailGetRequestInvocationArgs, MaskedEmailGetResponseInvocationArgs, MaskedEmailObject, MaskedEmailObjectServerSet, MaskedEmailObjectSettable, MaskedEmailSetRequestInvocationArgs, MaskedEmailSetResponseInvocationArgs, MaskedEmailState, } from "./capabilities/maskedemail/types.js";
+export type { SearchSnippetGetRequestInvocationArgs, SearchSnippetGetResponseInvocationArgs, SearchSnippetObject, } from "./capabilities/searchsnippet/types.js";

package/dist/src/index.js

@@ -0,0 +1,33 @@
+// Classes
+export { ErrorInvocation } from "./invocation/error-invocation.js";
+export { Invocation } from "./invocation/invocation.js";
+export { ResultReference } from "./invocation/result-reference.js";
+export { JMAPClient } from "./jmap-client/jmap-client.js";
+export { RequestBuilder } from "./request-builder/request-builder.js";
+// Type guards
+export { isErrorInvocation, isResultReference } from "./invocation/utils.js";
+// Error handling
+export { JMAPRequestError } from "./jmap-client/utils/jmap-request-error.js";
+// Capability definitions
+export { BlobCapability } from "./capabilities/blob-capability.js";
+export { CoreCapability } from "./capabilities/core-capability.js";
+export { EmailCapability } from "./capabilities/email-capability.js";
+export { MaskedEmailCapability } from "./capabilities/maskedemail-capability.js";
+export { SubmissionCapability } from "./capabilities/submission-capability.js";
+export { VacationResponseCapability } from "./capabilities/vacationresponse-capability.js";
+// Invocation factories
+export { Blob } from "./capabilities/blob/blob.js";
+export { Core } from "./capabilities/core/core.js";
+export { Email } from "./capabilities/email/email.js";
+export { EmailSubmission } from "./capabilities/emailsubmission/emailsubmission.js";
+export { Identity } from "./capabilities/identity/identity.js";
+export { Mailbox } from "./capabilities/mailbox/mailbox.js";
+export { MaskedEmail } from "./capabilities/maskedemail/maskedemail.js";
+export { SearchSnippet } from "./capabilities/searchsnippet/searchsnippet.js";
+export { Thread } from "./capabilities/thread/thread.js";
+export { VacationResponse } from "./capabilities/vacationresponse/vacationresponse.js";
+// Common types and capability URI constants
+export * from "./common/registry.js";
+// Blob types
+export { HTTPDigestAlgorithmSchema as HTTPDigestAlgorithmValueSchema } from "./capabilities/blob/types.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,UAAU;AACV,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,sCAAsC,CAAC;AAEtE,cAAc;AACd,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAE7E,iBAAiB;AACjB,OAAO,EAAE,gBAAgB,EAAE,MAAM,2CAA2C,CAAC;AAE7E,yBAAyB;AACzB,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACrE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AAC/E,OAAO,EAAE,0BAA0B,EAAE,MAAM,+CAA+C,CAAC;AAE3F,uBAAuB;AACvB,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AACnD,OAAO,EAAE,IAAI,EAAE,MAAM,6BAA6B,CAAC;AACnD,OAAO,EAAE,KAAK,EAAE,MAAM,+BAA+B,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,mDAAmD,CAAC;AACpF,OAAO,EAAE,QAAQ,EAAE,MAAM,qCAAqC,CAAC;AAC/D,OAAO,EAAE,OAAO,EAAE,MAAM,mCAAmC,CAAC;AAC5D,OAAO,EAAE,WAAW,EAAE,MAAM,2CAA2C,CAAC;AACxE,OAAO,EAAE,aAAa,EAAE,MAAM,+CAA+C,CAAC;AAC9E,OAAO,EAAE,MAAM,EAAE,MAAM,iCAAiC,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qDAAqD,CAAC;AAEvF,4CAA4C;AAC5C,cAAc,sBAAsB,CAAC;AAqKrC,aAAa;AACb,OAAO,EAAE,yBAAyB,IAAI,8BAA8B,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/src/invocation/arguments-proxy.d.ts

@@ -0,0 +1,14 @@
+import type { Invocation } from "./invocation.js";
+import type { BaseInvocationArgs } from "./types.js";
+/**
+ * Creates a Proxy over an {@link Invocation} that behaves like a plain object.
+ *
+ * The returned Proxy supports property access, `in`, `Object.keys()`, spread,
+ * and `JSON.stringify()`. If the host implements `setArgument` and `deleteArgument`,
+ * property assignment and deletion delegate to those methods (preserving any
+ * validation they perform). Otherwise, those operations throw a TypeError.
+ *
+ * @param host The backing Invocation to proxy
+ * @returns A Proxy that presents the host's arguments as an object
+ */
+export declare function createArgumentsProxy<TArgs extends BaseInvocationArgs>(host: Invocation<TArgs>): TArgs;

package/dist/src/invocation/arguments-proxy.js

@@ -0,0 +1,37 @@
+/**
+ * Creates a Proxy over an {@link Invocation} that behaves like a plain object.
+ *
+ * The returned Proxy supports property access, `in`, `Object.keys()`, spread,
+ * and `JSON.stringify()`. If the host implements `setArgument` and `deleteArgument`,
+ * property assignment and deletion delegate to those methods (preserving any
+ * validation they perform). Otherwise, those operations throw a TypeError.
+ *
+ * @param host The backing Invocation to proxy
+ * @returns A Proxy that presents the host's arguments as an object
+ */
+export function createArgumentsProxy(host) {
+    return new Proxy(host, {
+        get: (target, prop) => target.getArgument(prop),
+        has: (target, prop) => target.hasArgument(prop),
+        ownKeys: (target) => target.argumentKeys(),
+        getOwnPropertyDescriptor: (target, prop) => {
+            if (target.hasArgument(prop)) {
+                return {
+                    configurable: true,
+                    enumerable: true,
+                    writable: typeof target.setArgument === "function",
+                    value: target.getArgument(prop),
+                };
+            }
+            return undefined;
+        },
+        set(target, prop, value) {
+            target.setArgument(prop, value);
+            return true;
+        },
+        deleteProperty(target, prop) {
+            return target.deleteArgument(prop);
+        },
+    });
+}
+//# sourceMappingURL=arguments-proxy.js.map

package/dist/src/invocation/arguments-proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arguments-proxy.js","sourceRoot":"","sources":["../../../src/invocation/arguments-proxy.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,MAAM,UAAU,oBAAoB,CAAmC,IAAuB;IAE1F,OAAO,IAAI,KAAK,CAAoB,IAAI,EAAE;QACtC,GAAG,EAAE,CAAC,MAAM,EAAE,IAAiB,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC;QAC5D,GAAG,EAAE,CAAC,MAAM,EAAE,IAAiB,EAAE,EAAE,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC;QAC5D,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,YAAY,EAAE;QAC1C,wBAAwB,EAAE,CAAC,MAAM,EAAE,IAAiB,EAAE,EAAE;YACpD,IAAI,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC;gBAC3B,OAAO;oBACH,YAAY,EAAE,IAAI;oBAClB,UAAU,EAAE,IAAI;oBAChB,QAAQ,EAAE,OAAO,MAAM,CAAC,WAAW,KAAK,UAAU;oBAClD,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC;iBAClC,CAAC;YACN,CAAC;YACD,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,GAAG,CAAC,MAAM,EAAE,IAAiB,EAAE,KAAsD;YACjF,MAAM,CAAC,WAAW,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;YAChC,OAAO,IAAI,CAAC;QAChB,CAAC;QACD,cAAc,CAAC,MAAM,EAAE,IAAiB;YACpC,OAAO,MAAM,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;QACvC,CAAC;KACJ,CAAqB,CAAC;AAC3B,CAAC"}

package/dist/src/invocation/error-invocation.d.ts

@@ -0,0 +1,27 @@
+import type { JMAPResponseInvocationErrorArgs, JSONValue } from "../common/types.js";
+/**
+ * Represents a JMAP method-level error invocation.
+ *
+ * This class encapsulates error responses from the JMAP server, providing a similar interface
+ * to Invocation, but with no dataType property. The error arguments are stored as a map and
+ * can be accessed via the `arguments` getter. The error type is available via the `type` getter.
+ */
+export declare class ErrorInvocation {
+    #private;
+    /**
+     * Construct a new ErrorInvocation.
+     * @param args The error arguments, including the required `type` property.
+     * @param methodCallId The unique symbol for this invocation (optional; a new symbol is generated if omitted).
+     */
+    constructor(args: JMAPResponseInvocationErrorArgs, methodCallId?: symbol);
+    /** The name of this invocation, always "error". */
+    get name(): "error";
+    /** The error arguments as a plain object. */
+    get arguments(): {
+        [k: string]: JSONValue;
+    };
+    /** The unique symbol identifier for this error invocation. */
+    get id(): symbol;
+    /** The error type string (e.g., "serverFail", "invalidArguments"). */
+    get type(): JMAPResponseInvocationErrorArgs["type"];
+}

package/dist/src/invocation/error-invocation.js

@@ -0,0 +1,39 @@
+/**
+ * Represents a JMAP method-level error invocation.
+ *
+ * This class encapsulates error responses from the JMAP server, providing a similar interface
+ * to Invocation, but with no dataType property. The error arguments are stored as a map and
+ * can be accessed via the `arguments` getter. The error type is available via the `type` getter.
+ */
+export class ErrorInvocation {
+    /** Map of error argument keys to their values. */
+    #arguments;
+    /** The unique symbol identifier for this error invocation. */
+    #id;
+    /**
+     * Construct a new ErrorInvocation.
+     * @param args The error arguments, including the required `type` property.
+     * @param methodCallId The unique symbol for this invocation (optional; a new symbol is generated if omitted).
+     */
+    constructor(args, methodCallId) {
+        this.#arguments = new Map(Object.entries(args));
+        this.#id = methodCallId ?? Symbol();
+    }
+    /** The name of this invocation, always "error". */
+    get name() {
+        return "error";
+    }
+    /** The error arguments as a plain object. */
+    get arguments() {
+        return Object.fromEntries(this.#arguments);
+    }
+    /** The unique symbol identifier for this error invocation. */
+    get id() {
+        return this.#id;
+    }
+    /** The error type string (e.g., "serverFail", "invalidArguments"). */
+    get type() {
+        return this.#arguments.get("type");
+    }
+}
+//# sourceMappingURL=error-invocation.js.map

package/dist/src/invocation/error-invocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-invocation.js","sourceRoot":"","sources":["../../../src/invocation/error-invocation.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,OAAO,eAAe;IACxB,kDAAkD;IACzC,UAAU,CAAiE;IACpF,8DAA8D;IACrD,GAAG,CAAS;IAErB;;;;OAIG;IACH,YAAY,IAAqC,EAAE,YAAqB;QACpE,IAAI,CAAC,UAAU,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAChD,IAAI,CAAC,GAAG,GAAG,YAAY,IAAI,MAAM,EAAE,CAAC;IACxC,CAAC;IACD,mDAAmD;IACnD,IAAI,IAAI;QACJ,OAAO,OAAgB,CAAC;IAC5B,CAAC;IAED,6CAA6C;IAC7C,IAAI,SAAS;QACT,OAAO,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAC/C,CAAC;IAED,8DAA8D;IAC9D,IAAI,EAAE;QACF,OAAO,IAAI,CAAC,GAAG,CAAC;IACpB,CAAC;IAED,sEAAsE;IACtE,IAAI,IAAI;QACJ,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAA4C,CAAC;IAClF,CAAC;CACJ"}

package/dist/src/invocation/invocation.d.ts

@@ -0,0 +1,111 @@
+import type { JMAPCapability, JMAPDataType, JMAPMethodName, JMAPRequestInvocation } from "../common/types.js";
+import { ResultReference } from "./result-reference.js";
+import type { BaseInvocationArgs, InvocationArgs, InvocationInterface, JMAPInvocationInternal } from "./types.js";
+/**
+ * Base class for invocations.
+ * @remarks
+ * This class is not meant to be constructed directly. Instead, use one of the capabilities subclasses,
+ * or extend it to build a new capability.
+ * @typeParam TArgs The type of the arguments for the invocation
+ */
+export declare abstract class Invocation<TArgs extends BaseInvocationArgs> implements InvocationInterface<TArgs> {
+    #private;
+    abstract readonly uri: JMAPCapability;
+    /**
+     * Constructs an Invocation
+     *
+     * @param dataType The data type of the invocation
+     * @param method The name of the method being invoked (e.g., "get", "set", "query")
+     * @param args object containing named arguments for that method or response
+     * @throws {InvalidResultReferenceError}
+     * @throws {UnexpectedResultReferenceError}
+     */
+    constructor(dataType: JMAPDataType, method: JMAPMethodName, args: InvocationArgs<TArgs>, methodCallId?: symbol);
+    /**
+     * Get the name of the method
+     *
+     * The name of the method in the format "{dataType}/{method}"
+     */
+    get name(): string;
+    /**
+     * Get the data type of the invocation
+     *
+     * The data type of the invocation is the name of the object that methods are associated with
+     * (e.g., "Email", "Mailbox", "Thread")
+     */
+    get dataType(): JMAPDataType;
+    /**
+     * Get the method name of the invocation
+     *
+     * The method name of the invocation is the name of the method being invoked (e.g., "get", "set", "query")
+     */
+    get method(): JMAPMethodName;
+    /**
+     * Get the internal identifier for the invocation
+     *
+     * The internal identifier is a unique symbol used to identify this invocation instance.
+     */
+    get id(): symbol;
+    /**
+     * Get the arguments for the invocation
+     *
+     * The arguments are the named parameters passed to the method being invoked.
+     */
+    get arguments(): TArgs;
+    /**
+     * Get the value of a named argument.
+     * @param name The name of the argument
+     * @returns The value or result reference for the named argument.
+     */
+    getArgument<K extends keyof TArgs & string>(name: K): TArgs[K];
+    /**
+     * Set the value of a named argument.
+     * @param name The name of the argument
+     * @param value The value or result reference for the named argument.
+     */
+    setArgument<K extends keyof TArgs & string>(name: K, value: InvocationArgs<TArgs>[K]): void;
+    /**
+     * Delete a named argument.
+     * @param name The name of the argument
+     * @returns Whether the argument was deleted
+     */
+    deleteArgument(name: keyof TArgs & string): boolean;
+    /**
+     * Check if a named argument exists.
+     * @param name The name of the argument
+     * @returns Whether the argument exists
+     */
+    hasArgument(name: keyof TArgs & string): boolean;
+    /**
+     * Get the keys of all arguments.
+     * @returns An array of argument names
+     */
+    argumentKeys(): (keyof TArgs & string)[];
+    /**
+     * Create a result reference for a named argument to use in another method.
+     * @param path The path to the result to reference
+     * @returns The result reference
+     */
+    createReference(path: string): ResultReference;
+    /**
+     * Resolve the invocation into a JMAP request invocation tuple.
+     *
+     * Converts internal {@link ResultReference} arguments into their wire format
+     * (`#property` keys with resolved `resultOf` ids) and produces the
+     * `[name, arguments, methodCallId]` tuple expected by the JMAP protocol.
+     *
+     * @param id The method call id to assign to this invocation in the request
+     * @param lookupId A function that resolves an invocation's internal symbol id
+     *        to the string method call id assigned in the request
+     * @returns The resolved JMAP request invocation tuple
+     * @throws If a result reference refers to an invocation whose id cannot be resolved
+     */
+    resolve(id: string, lookupId: (id: symbol) => string | undefined): JMAPRequestInvocation;
+    /**
+     * Convert the invocation to a serialisable representation.
+     * @returns A serialisable representation of the invocation
+     * @remarks It is expected that the caller will provide a resolver function to resolve the ID
+     *         and any result references referring to other invocations.
+     */
+    toJSON(): JMAPInvocationInternal;
+}

package/dist/src/invocation/invocation.js

@@ -0,0 +1,158 @@
+import { createArgumentsProxy } from "./arguments-proxy.js";
+import { ResultReference } from "./result-reference.js";
+import { isResultReference } from "./utils.js";
+/**
+ * Base class for invocations.
+ * @remarks
+ * This class is not meant to be constructed directly. Instead, use one of the capabilities subclasses,
+ * or extend it to build a new capability.
+ * @typeParam TArgs The type of the arguments for the invocation
+ */
+export class Invocation {
+    #dataType;
+    #method;
+    #arguments;
+    #id;
+    #argumentsProxy = null;
+    /**
+     * Constructs an Invocation
+     *
+     * @param dataType The data type of the invocation
+     * @param method The name of the method being invoked (e.g., "get", "set", "query")
+     * @param args object containing named arguments for that method or response
+     * @throws {InvalidResultReferenceError}
+     * @throws {UnexpectedResultReferenceError}
+     */
+    constructor(dataType, method, args, methodCallId) {
+        this.#dataType = dataType;
+        this.#method = method;
+        this.#arguments = new Map(Object.entries(args));
+        this.#id = methodCallId ?? Symbol();
+    }
+    /**
+     * Get the name of the method
+     *
+     * The name of the method in the format "{dataType}/{method}"
+     */
+    get name() {
+        return `${this.#dataType}/${this.#method}`;
+    }
+    /**
+     * Get the data type of the invocation
+     *
+     * The data type of the invocation is the name of the object that methods are associated with
+     * (e.g., "Email", "Mailbox", "Thread")
+     */
+    get dataType() {
+        return this.#dataType;
+    }
+    /**
+     * Get the method name of the invocation
+     *
+     * The method name of the invocation is the name of the method being invoked (e.g., "get", "set", "query")
+     */
+    get method() {
+        return this.#method;
+    }
+    /**
+     * Get the internal identifier for the invocation
+     *
+     * The internal identifier is a unique symbol used to identify this invocation instance.
+     */
+    get id() {
+        return this.#id;
+    }
+    /**
+     * Get the arguments for the invocation
+     *
+     * The arguments are the named parameters passed to the method being invoked.
+     */
+    get arguments() {
+        this.#argumentsProxy ??= createArgumentsProxy(this);
+        return this.#argumentsProxy;
+    }
+    /**
+     * Get the value of a named argument.
+     * @param name The name of the argument
+     * @returns The value or result reference for the named argument.
+     */
+    getArgument(name) {
+        return this.#arguments.get(name);
+    }
+    /**
+     * Set the value of a named argument.
+     * @param name The name of the argument
+     * @param value The value or result reference for the named argument.
+     */
+    setArgument(name, value) {
+        if (isResultReference(value) && value.id === this.#id) {
+            throw new Error(`Result reference must not reference the invocation itself`);
+        }
+        this.#arguments.set(name, value);
+    }
+    /**
+     * Delete a named argument.
+     * @param name The name of the argument
+     * @returns Whether the argument was deleted
+     */
+    deleteArgument(name) {
+        return this.#arguments.delete(name);
+    }
+    /**
+     * Check if a named argument exists.
+     * @param name The name of the argument
+     * @returns Whether the argument exists
+     */
+    hasArgument(name) {
+        return this.#arguments.has(name);
+    }
+    /**
+     * Get the keys of all arguments.
+     * @returns An array of argument names
+     */
+    argumentKeys() {
+        return [...this.#arguments.keys()];
+    }
+    /**
+     * Create a result reference for a named argument to use in another method.
+     * @param path The path to the result to reference
+     * @returns The result reference
+     */
+    createReference(path) {
+        return new ResultReference(this.#id, this.name, path);
+    }
+    /**
+     * Resolve the invocation into a JMAP request invocation tuple.
+     *
+     * Converts internal {@link ResultReference} arguments into their wire format
+     * (`#property` keys with resolved `resultOf` ids) and produces the
+     * `[name, arguments, methodCallId]` tuple expected by the JMAP protocol.
+     *
+     * @param id The method call id to assign to this invocation in the request
+     * @param lookupId A function that resolves an invocation's internal symbol id
+     *        to the string method call id assigned in the request
+     * @returns The resolved JMAP request invocation tuple
+     * @throws If a result reference refers to an invocation whose id cannot be resolved
+     */
+    resolve(id, lookupId) {
+        const entries = [...this.#arguments];
+        const args = Object.fromEntries(entries.map(([property, value]) => {
+            return value instanceof ResultReference ? [`#${property}`, value.resolve(lookupId)] : [property, value];
+        }));
+        return [this.name, args, id];
+    }
+    /**
+     * Convert the invocation to a serialisable representation.
+     * @returns A serialisable representation of the invocation
+     * @remarks It is expected that the caller will provide a resolver function to resolve the ID
+     *         and any result references referring to other invocations.
+     */
+    toJSON() {
+        return [
+            this.name,
+            Object.fromEntries(Array.from(this.#arguments.entries(), ([k, v]) => v instanceof ResultReference ? [`#${k}`, v] : [k, v])),
+            this.#id,
+        ];
+    }
+}
+//# sourceMappingURL=invocation.js.map

package/dist/src/invocation/invocation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invocation.js","sourceRoot":"","sources":["../../../src/invocation/invocation.ts"],"names":[],"mappings":"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"}