Create a new JMAPClient instance.
The provided Transport is responsible for all HTTP request concerns, including authentication, network errors, and any custom headers or request logic required by the server. The client itself does not handle authentication or low-level HTTP details.
If the port is not specified, it defaults to 443.
The transport implementation for HTTP requests, including authentication.
JMAP client options including hostname, port, headers, logger, and emitter.
The accounts from the session object, or null if not connected.
The API URL from the session object, or an empty string if not connected.
Get the capability registry.
This provides read-only access to the registry of JMAP capabilities. To register new capabilities, use the registerCapability method.
The current connection status of the client.
The download URL template from the session object, or an empty string if not connected.
The event source URL template from the session object, or an empty string if not connected.
The primary accounts from the session object, or an empty object if not connected.
The server capabilities from the session object, or null if not connected.
The upload URL template from the session object, or an empty string if not connected.
The username from the session object, or an empty string if not connected.
Connect to the JMAP server and fetch the session object.
This method is idempotent: if called multiple times while a connection is already in progress, each call will return a new Promise that resolves or rejects with the same result as the in-progress connection. Only one connection attempt will be made at a time; concurrent calls will not trigger multiple connections.
Optionalsignal: AbortSignalCreate a new RequestBuilder instance linked to this client.
The builder will have access to the client's current capabilities and session state, allowing it to validate requests and enforce server limits.
A new RequestBuilder instance
Disconnect from the JMAP server and clear session state.
This method is asynchronous and will not set the status to 'disconnected' until all in-flight requests have settled (resolved or rejected) after being aborted. It is idempotent: if already disconnecting, it returns the same promise.
Download a file from the server.
The id of the account to which the record with the blobId belongs.
The blobId representing the data of the file to download.
The name for the file; the server MUST return this as the filename if it sets a Content-Disposition header.
The type for the server to set in the Content-Type header of the response; the blobId only represents the binary data and does not have a content-type innately associated with it.
Optionalsignal: AbortSignalOptional AbortSignal to cancel the request.
A promise that resolves to a Blob containing the data of the file.
Error if the client is not connected, downloadUrl is missing from session, accountId is not listed in the session's accounts.
JMAPRequestError for JMAP protocol errors (non-200 status codes with RFC 7807 Problem Details).
Get the parsed download URL for a file.
The id of the account to which the record with the blobId belongs.
The blobId representing the data of the file to download.
The name for the file; the server MUST return this as the filename if it sets a Content-Disposition header.
The type for the server to set in the Content-Type header of the response; the blobId only represents the binary data and does not have a content-type innately associated with it.
the download URL with variables expanded
Get the parsed event source URL.
Either an array of event types to listen for, or "*" to listen for all types.
Either "state" (end response after pushing a state event) or "no" (persist connection).
Positive integer value in seconds. If non-zero, the server will send a ping event after this time elapses since the previous event.
the event source URL with variables expanded
Get the parsed upload URL for a file.
The id of the account to upload the file to.
the upload URL with variables expanded
Determines if a given capability identified by its URN is supported by the server.
The URN of the JMAP capability being queried.
True if supported, false otherwise.
Register one or more capabilities with the client.
When called after the client is connected, each capability's schema is validated against the session data. Capabilities that fail validation are rejected and not registered. When called before connecting, capabilities are registered without validation.
If called while the client is in the process of connecting, registration waits for the connection to complete before validating. If the connection fails, capabilities are registered without validation (no session to validate against).
The capability definitions to register
A result object containing arrays of validation failures (empty arrays if all succeeded)
Send an API request to the JMAP server.
The request builder instance.
Optionalsignal: AbortSignalOptional AbortSignal to cancel the request.
The parsed response from the server.
JMAPRequestError for JMAP protocol errors (non-200 status codes with RFC 7807 Problem Details).
Upload a file to the server.
The id of the account to upload to.
The file data to upload. Can be a Blob, ArrayBuffer, or File.
Optionalsignal: AbortSignalOptional AbortSignal to cancel the request.
A promise that resolves to the upload response from the server.
Error if the client is not connected, uploadUrl is missing from session, or accountId is not listed in the session's accounts.
JMAPRequestError for JMAP protocol errors (non-200 status codes with RFC 7807 Problem Details).
Set a custom event emitter for the client.
The event emitter function to handle events.
This client instance (for chaining).
Set additional headers for requests.
Additional headers to merge.
This client instance (for chaining).
Set the hostname for the JMAP server. Only allowed while disconnected.
The hostname of the JMAP server
This client instance (for chaining).
Set a custom logger for the client.
The logger instance or function.
This client instance (for chaining).
Set the port for the JMAP server. Only allowed while disconnected.
Port number.
This client instance (for chaining).
JMAP Client for interacting with a JMAP server.
This class manages the connection lifecycle, session state, and provides methods for interacting with the JMAP API, including capability checks, file downloads, and invocation requests and responses.