jmap-kit 0.0.0 → 1.0.2

package/dist/src/jmap-client/utils/filter-session-capabilities.js

@@ -0,0 +1,40 @@
+import { deepFreeze } from "./deep-freeze.js";
+/**
+ * Construct a new session object with invalid capabilities filtered out, then deep-freeze it.
+ *
+ * - Server-level failures cause the capability to be removed from `capabilities`,
+ *   all `account.accountCapabilities`, and `primaryAccounts`.
+ * - Account-level failures cause the capability to be removed from that specific
+ *   account's `accountCapabilities` and, if the account was the primary for that
+ *   capability, from `primaryAccounts`.
+ *
+ * @param session The parsed (mutable) session from structural validation
+ * @param serverFailures Server capabilities that failed schema validation
+ * @param accountFailures Account capabilities that failed schema validation
+ * @returns A deeply frozen JMAPSession with invalid capabilities removed
+ */
+export function filterSessionCapabilities(session, serverFailures, accountFailures) {
+    const invalidServerUris = new Set(serverFailures.map((f) => f.uri));
+    // Build lookup: accountId → Set<uri> for account-level failures
+    const accountFailuresByAccount = Map.groupBy(accountFailures, (f) => f.accountId);
+    const isInvalidAccountUri = (accountId, uri) => accountFailuresByAccount.get(accountId)?.some((f) => f.uri === uri) ?? false;
+    // Filter server capabilities
+    const capabilities = Object.fromEntries(Object.entries(session.capabilities).filter(([uri]) => !invalidServerUris.has(uri)));
+    // Filter account capabilities
+    const accounts = Object.fromEntries(Object.entries(session.accounts).map(([accountId, account]) => [
+        accountId,
+        {
+            ...account,
+            accountCapabilities: Object.fromEntries(Object.entries(account.accountCapabilities).filter(([uri]) => !invalidServerUris.has(uri) && !isInvalidAccountUri(accountId, uri))),
+        },
+    ]));
+    // Filter primaryAccounts
+    const primaryAccounts = Object.fromEntries(Object.entries(session.primaryAccounts).filter(([uri, accountId]) => !invalidServerUris.has(uri) && !isInvalidAccountUri(accountId, uri)));
+    return deepFreeze({
+        ...session,
+        capabilities,
+        accounts,
+        primaryAccounts,
+    });
+}
+//# sourceMappingURL=filter-session-capabilities.js.map

package/dist/src/jmap-client/utils/filter-session-capabilities.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filter-session-capabilities.js","sourceRoot":"","sources":["../../../../src/jmap-client/utils/filter-session-capabilities.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,yBAAyB,CACrC,OAA8B,EAC9B,cAAyC,EACzC,eAA6D;IAE7D,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAEpE,gEAAgE;IAChE,MAAM,wBAAwB,GAAG,GAAG,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAClF,MAAM,mBAAmB,GAAG,CAAC,SAAiB,EAAE,GAAW,EAAW,EAAE,CACpE,wBAAwB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,IAAI,KAAK,CAAC;IAEjF,6BAA6B;IAC7B,MAAM,YAAY,GAAG,MAAM,CAAC,WAAW,CACnC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CACtF,CAAC;IAEF,8BAA8B;IAC9B,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAC/B,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC;QAC3D,SAAS;QACT;YACI,GAAG,OAAO;YACV,mBAAmB,EAAE,MAAM,CAAC,WAAW,CACnC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC,MAAM,CAC9C,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,SAAS,EAAE,GAAG,CAAC,CACjF,CACJ;SACJ;KACJ,CAAC,CACL,CAAC;IAEF,yBAAyB;IACzB,MAAM,eAAe,GAAG,MAAM,CAAC,WAAW,CACtC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,MAAM,CAC1C,CAAC,CAAC,GAAG,EAAE,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,mBAAmB,CAAC,SAAS,EAAE,GAAG,CAAC,CAC5F,CACJ,CAAC;IAEF,OAAO,UAAU,CAAC;QACd,GAAG,OAAO;QACV,YAAY;QACZ,QAAQ;QACR,eAAe;KAClB,CAAgB,CAAC;AACtB,CAAC"}

package/dist/src/jmap-client/utils/jmap-request-error.d.ts

@@ -0,0 +1,28 @@
+import type { JMAPRequestErrorTypes, ProblemDetails } from "../../common/types.js";
+/**
+ * Represents a JMAP request-level error.
+ *
+ * JMAP request-level errors are returned as top-level error objects in the HTTP response,
+ * not as part of the methodResponses array. They typically indicate issues with the entire
+ * request, such as authentication failures, quota limits, invalid JSON, etc.
+ */
+export declare class JMAPRequestError extends Error {
+    /**
+     * The type URI of the error.
+     */
+    readonly type: string;
+    /**
+     * The HTTP status code, if available.
+     */
+    readonly status?: number;
+    /**
+     * The raw error response object.
+     */
+    readonly problemDetails: ProblemDetails<JMAPRequestErrorTypes>;
+    /**
+     * Creates a new JMAP request error.
+     *
+     * @param error The error response from the JMAP server.
+     */
+    constructor(error: ProblemDetails<JMAPRequestErrorTypes>);
+}

package/dist/src/jmap-client/utils/jmap-request-error.js

@@ -0,0 +1,48 @@
+import { LIMIT, NOT_JSON, NOT_REQUEST, UNKNOWN_CAPABILITY } from "../../common/registry.js";
+/**
+ * Default error messages for common JMAP request-level error types.
+ * These are used as fallbacks when no detail or title is provided.
+ */
+const DEFAULT_ERROR_MESSAGES = {
+    [UNKNOWN_CAPABILITY]: "The request included a capability that the server does not support",
+    [NOT_JSON]: "The request was not valid JSON or had an incorrect Content-Type",
+    [NOT_REQUEST]: "The request did not match the required JMAP request format",
+    [LIMIT]: "The request exceeded a server-defined limit",
+};
+/**
+ * Represents a JMAP request-level error.
+ *
+ * JMAP request-level errors are returned as top-level error objects in the HTTP response,
+ * not as part of the methodResponses array. They typically indicate issues with the entire
+ * request, such as authentication failures, quota limits, invalid JSON, etc.
+ */
+export class JMAPRequestError extends Error {
+    /**
+     * The type URI of the error.
+     */
+    type;
+    /**
+     * The HTTP status code, if available.
+     */
+    status;
+    /**
+     * The raw error response object.
+     */
+    problemDetails;
+    /**
+     * Creates a new JMAP request error.
+     *
+     * @param error The error response from the JMAP server.
+     */
+    constructor(error) {
+        // Use detail, title, default message for the error type, or finally the type URI itself
+        // in order of preference
+        const message = error.detail ?? error.title ?? DEFAULT_ERROR_MESSAGES[error.type] ?? error.type;
+        super(message);
+        this.type = error.type;
+        this.status = error.status;
+        this.problemDetails = error;
+        this.name = "JMAPRequestError";
+    }
+}
+//# sourceMappingURL=jmap-request-error.js.map

package/dist/src/jmap-client/utils/jmap-request-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jmap-request-error.js","sourceRoot":"","sources":["../../../../src/jmap-client/utils/jmap-request-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAG5F;;;GAGG;AACH,MAAM,sBAAsB,GAAwD;IAChF,CAAC,kBAAkB,CAAC,EAAE,oEAAoE;IAC1F,CAAC,QAAQ,CAAC,EAAE,iEAAiE;IAC7E,CAAC,WAAW,CAAC,EAAE,4DAA4D;IAC3E,CAAC,KAAK,CAAC,EAAE,6CAA6C;CACzD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACvC;;OAEG;IACM,IAAI,CAAS;IAEtB;;OAEG;IACM,MAAM,CAAU;IAEzB;;OAEG;IACM,cAAc,CAAwC;IAE/D;;;;OAIG;IACH,YAAY,KAA4C;QACpD,wFAAwF;QACxF,yBAAyB;QACzB,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,KAAK,IAAI,sBAAsB,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC;QAEhG,KAAK,CAAC,OAAO,CAAC,CAAC;QAEf,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QACvB,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;QAC3B,IAAI,CAAC,cAAc,GAAG,KAAK,CAAC;QAC5B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACnC,CAAC;CACJ"}

package/dist/src/jmap-client/utils/logger.d.ts

@@ -0,0 +1,6 @@
+import type { Logger } from "../types.js";
+/**
+ * Create a safe logger that wraps an external logger implementation.
+ * All logger methods are wrapped in try/catch to prevent errors in the logger from affecting the application.
+ */
+export declare function createLogger(getCurrentLogger: () => Logger | undefined): Logger;

package/dist/src/jmap-client/utils/logger.js

@@ -0,0 +1,22 @@
+/**
+ * Create a safe logger that wraps an external logger implementation.
+ * All logger methods are wrapped in try/catch to prevent errors in the logger from affecting the application.
+ */
+export function createLogger(getCurrentLogger) {
+    const log = (method) => (message, ...optionalParameters) => {
+        try {
+            getCurrentLogger()?.[method](message, ...optionalParameters);
+        }
+        catch {
+            // Ignore any errors from the external logger
+        }
+    };
+    return {
+        log: log("log"),
+        info: log("info"),
+        warn: log("warn"),
+        error: log("error"),
+        debug: log("debug"),
+    };
+}
+//# sourceMappingURL=logger.js.map

package/dist/src/jmap-client/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../../../src/jmap-client/utils/logger.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,gBAA0C;IACnE,MAAM,GAAG,GACL,CAAC,MAAoB,EAAgB,EAAE,CACvC,CAAC,OAAO,EAAE,GAAG,kBAAkB,EAAE,EAAE;QAC/B,IAAI,CAAC;YACD,gBAAgB,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,GAAI,kBAAgC,CAAC,CAAC;QAChF,CAAC;QAAC,MAAM,CAAC;YACL,6CAA6C;QACjD,CAAC;IACL,CAAC,CAAC;IACN,OAAO;QACH,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC;QACf,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC;QACjB,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC;QACjB,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC;QACnB,KAAK,EAAE,GAAG,CAAC,OAAO,CAAC;KACtB,CAAC;AACN,CAAC"}

package/dist/src/jmap-client/utils/merge-headers.d.ts

@@ -0,0 +1,11 @@
+import type { HeadersInit } from "../types.js";
+/**
+ * Merges two Headers objects, respecting known single-value and multi-value headers.
+ * If a single-value header appears in both, the value from the second Headers object will override the first.
+ * Multi-value headers will combine values from both Headers objects, ensuring no duplicates.
+ *
+ * @param h1 The first set of headers.
+ * @param h2 The second set of headers.
+ * @returns A new Headers object containing the merged headers.
+ */
+export declare function mergeHeaders(h1: HeadersInit, h2: HeadersInit): Headers;

package/dist/src/jmap-client/utils/merge-headers.js

@@ -0,0 +1,40 @@
+/**
+ * Merges two Headers objects, respecting known single-value and multi-value headers.
+ * If a single-value header appears in both, the value from the second Headers object will override the first.
+ * Multi-value headers will combine values from both Headers objects, ensuring no duplicates.
+ *
+ * @param h1 The first set of headers.
+ * @param h2 The second set of headers.
+ * @returns A new Headers object containing the merged headers.
+ */
+export function mergeHeaders(h1, h2) {
+    const result = new Headers(h1);
+    const newHeaders = new Headers(h2);
+    // Known single-value headers (case-insensitive)
+    const singleValueRequestHeaders = new Set([
+        "authorization",
+        "content-disposition",
+        "content-encoding",
+        "content-language",
+        "content-location",
+        "content-type",
+        "if-match",
+        "if-modified-since",
+        "if-none-match",
+        "if-unmodified-since",
+    ]);
+    for (const [key, value] of newHeaders) {
+        const lowerKey = key.toLowerCase();
+        if (singleValueRequestHeaders.has(lowerKey)) {
+            result.set(key, value); // override
+        }
+        else {
+            const existing = new Set(result.get(key)?.split(/\s*,\s*/) ?? []);
+            const values = new Set(value.split(/\s*,\s*/));
+            const combined = existing.union(values);
+            result.set(key, Array.from(combined).join(", "));
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=merge-headers.js.map

package/dist/src/jmap-client/utils/merge-headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-headers.js","sourceRoot":"","sources":["../../../../src/jmap-client/utils/merge-headers.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,EAAe,EAAE,EAAe;IACzD,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC,EAAE,CAAC,CAAC;IAC/B,MAAM,UAAU,GAAG,IAAI,OAAO,CAAC,EAAE,CAAC,CAAC;IAEnC,gDAAgD;IAChD,MAAM,yBAAyB,GAAG,IAAI,GAAG,CAAC;QACtC,eAAe;QACf,qBAAqB;QACrB,kBAAkB;QAClB,kBAAkB;QAClB,kBAAkB;QAClB,cAAc;QACd,UAAU;QACV,mBAAmB;QACnB,eAAe;QACf,qBAAqB;KACxB,CAAC,CAAC;IAEH,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,UAAU,EAAE,CAAC;QACpC,MAAM,QAAQ,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;QAEnC,IAAI,yBAAyB,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1C,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,WAAW;QACvC,CAAC;aAAM,CAAC;YACJ,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;YAClE,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC;YAC/C,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YACxC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACrD,CAAC;IACL,CAAC;IAED,OAAO,MAAM,CAAC;AAClB,CAAC"}

package/dist/src/jmap-client/utils/template-utils.d.ts

@@ -0,0 +1,27 @@
+import type { PrimitiveValue } from "url-template";
+/**
+ * Extracts variable names from a URI template string.
+ *
+ * This extraction function is limited in its ability to handle malformed template strings,
+ * and it differs from how `url-template` handles such cases. However, JMAP defines that all
+ * URI Templates MUST be level 1 compliant, so this function should work correctly in all
+ * anticipated cases. It will, however, extract parameters from any valid template string
+ * from levels 1 to 4.
+ *
+ * @param template The URI template string from which to extract variables
+ * @returns A Set of variable names extracted from the template
+ */
+export declare function extractTemplateVariables(template: string): Set<string>;
+/**
+ * Expands a URI template with parameters, and ensures that any parameters not used in the template
+ * are appended as query parameters to the resulting URL.
+ *
+ * This behaviour is not technically part of the JMAP specification, but it has been observed that
+ * some JMAP servers (such as Fastmail) provide non-compliant templates that do not use all parameters,
+ * and are assumed to be expected as query string parameters.
+ *
+ * @param templateString The URI template string
+ * @param params An object containing parameter values to expand in the template
+ * @returns A URL object with the expanded template and any unused parameters as query params
+ */
+export declare function expandUrlWithParams(templateString: string, params: Record<string, PrimitiveValue>): URL;

package/dist/src/jmap-client/utils/template-utils.js

@@ -0,0 +1,61 @@
+import { parseTemplate } from "url-template";
+/**
+ * Extracts variable names from a URI template string.
+ *
+ * This extraction function is limited in its ability to handle malformed template strings,
+ * and it differs from how `url-template` handles such cases. However, JMAP defines that all
+ * URI Templates MUST be level 1 compliant, so this function should work correctly in all
+ * anticipated cases. It will, however, extract parameters from any valid template string
+ * from levels 1 to 4.
+ *
+ * @param template The URI template string from which to extract variables
+ * @returns A Set of variable names extracted from the template
+ */
+export function extractTemplateVariables(template) {
+    const regex = /\{([^}]+)\}/g;
+    const operatorChars = new Set(["+", "#", ".", "/", ";", "?", "&", "=", ",", "!", "@", "|"]);
+    const variables = new Set();
+    let match;
+    while ((match = regex.exec(template)) !== null) {
+        const expression = match[1];
+        /* v8 ignore else -- @preserve */
+        if (expression && expression.length > 0) {
+            /* istanbul ignore next */
+            const [opChar = ""] = expression;
+            const varList = operatorChars.has(opChar) ? expression.slice(1) : expression;
+            varList.split(",").forEach((v) => {
+                // Remove explode modifier (*) and prefix modifier (:number)
+                const name = v.replace(/\*$|:\d+$/, "");
+                variables.add(name);
+            });
+        }
+    }
+    return variables;
+}
+/**
+ * Expands a URI template with parameters, and ensures that any parameters not used in the template
+ * are appended as query parameters to the resulting URL.
+ *
+ * This behaviour is not technically part of the JMAP specification, but it has been observed that
+ * some JMAP servers (such as Fastmail) provide non-compliant templates that do not use all parameters,
+ * and are assumed to be expected as query string parameters.
+ *
+ * @param templateString The URI template string
+ * @param params An object containing parameter values to expand in the template
+ * @returns A URL object with the expanded template and any unused parameters as query params
+ */
+export function expandUrlWithParams(templateString, params) {
+    const template = parseTemplate(templateString);
+    const expandedUrl = template.expand(params);
+    const url = new URL(expandedUrl);
+    // Get the set of parameters that are in the template
+    const templateVars = extractTemplateVariables(templateString);
+    // For each parameter that's not in the template, add it as a query parameter
+    for (const [key, value] of Object.entries(params)) {
+        if (value !== null && !templateVars.has(key)) {
+            url.searchParams.set(key, `${value}`);
+        }
+    }
+    return url;
+}
+//# sourceMappingURL=template-utils.js.map

package/dist/src/jmap-client/utils/template-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template-utils.js","sourceRoot":"","sources":["../../../../src/jmap-client/utils/template-utils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,wBAAwB,CAAC,QAAgB;IACrD,MAAM,KAAK,GAAG,cAAc,CAAC;IAC7B,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC5F,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,IAAI,KAA6B,CAAC;IAElC,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC7C,MAAM,UAAU,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAC5B,iCAAiC;QACjC,IAAI,UAAU,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACtC,0BAA0B;YAC1B,MAAM,CAAC,MAAM,GAAG,EAAE,CAAC,GAAG,UAAU,CAAC;YACjC,MAAM,OAAO,GAAG,aAAa,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC;YAE7E,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE;gBAC7B,4DAA4D;gBAC5D,MAAM,IAAI,GAAG,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;gBACxC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YACxB,CAAC,CAAC,CAAC;QACP,CAAC;IACL,CAAC;IAED,OAAO,SAAS,CAAC;AACrB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,cAAsB,EAAE,MAAsC;IAC9F,MAAM,QAAQ,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;IAC/C,MAAM,WAAW,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC;IAEjC,qDAAqD;IACrD,MAAM,YAAY,GAAG,wBAAwB,CAAC,cAAc,CAAC,CAAC;IAE9D,6EAA6E;IAC7E,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAChD,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC;YAC3C,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;QAC1C,CAAC;IACL,CAAC;IAED,OAAO,GAAG,CAAC;AACf,CAAC"}

package/dist/src/jmap-client/utils/track-utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Adds a promise to the given Set while it is pending, and automatically removes it once the promise settles (resolves or rejects).
+ * Returns a promise that resolves or rejects with the same value as the input promise.
+ *
+ * @template T The resolved value type of the promise.
+ * @param set Set to track the pending promise.
+ * @param promise The promise to track.
+ * @returns A promise that resolves or rejects with the same value as the input promise.
+ */
+export declare function trackPromise<T>(set: Set<Promise<unknown>>, promise: Promise<T>): Promise<T>;
+/**
+ * Adds an AbortController to the given Set and automatically removes it when it is aborted.
+ * Returns the same AbortController instance for chaining or further use.
+ *
+ * @param set Set to track the AbortController.
+ * @param controller The AbortController to track.
+ * @returns The same AbortController instance.
+ */
+export declare function trackAbortController(set: Set<AbortController>, controller: AbortController): AbortController;

package/dist/src/jmap-client/utils/track-utils.js

@@ -0,0 +1,35 @@
+/**
+ * Adds a promise to the given Set while it is pending, and automatically removes it once the promise settles (resolves or rejects).
+ * Returns a promise that resolves or rejects with the same value as the input promise.
+ *
+ * @template T The resolved value type of the promise.
+ * @param set Set to track the pending promise.
+ * @param promise The promise to track.
+ * @returns A promise that resolves or rejects with the same value as the input promise.
+ */
+export async function trackPromise(set, promise) {
+    set.add(promise);
+    try {
+        return await promise;
+    }
+    finally {
+        set.delete(promise);
+    }
+}
+/**
+ * Adds an AbortController to the given Set and automatically removes it when it is aborted.
+ * Returns the same AbortController instance for chaining or further use.
+ *
+ * @param set Set to track the AbortController.
+ * @param controller The AbortController to track.
+ * @returns The same AbortController instance.
+ */
+export function trackAbortController(set, controller) {
+    set.add(controller);
+    const cleanup = () => {
+        set.delete(controller);
+    };
+    controller.signal.addEventListener("abort", cleanup, { once: true });
+    return controller;
+}
+//# sourceMappingURL=track-utils.js.map

package/dist/src/jmap-client/utils/track-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"track-utils.js","sourceRoot":"","sources":["../../../../src/jmap-client/utils/track-utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAI,GAA0B,EAAE,OAAmB;IACjF,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;IACjB,IAAI,CAAC;QACD,OAAO,MAAM,OAAO,CAAC;IACzB,CAAC;YAAS,CAAC;QACP,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxB,CAAC;AACL,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAyB,EAAE,UAA2B;IACvF,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IACpB,MAAM,OAAO,GAAG,GAAG,EAAE;QACjB,GAAG,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC3B,CAAC,CAAC;IACF,UAAU,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IACrE,OAAO,UAAU,CAAC;AACtB,CAAC"}

package/dist/src/jmap-client/utils/transport.d.ts

@@ -0,0 +1,12 @@
+import type { Transport } from "../types.js";
+/**
+ * Wrap a Transport implementation so that all requests and abort controllers are tracked in the provided Sets.
+ * Each request promise is added to the set and removed when settled.
+ * Each AbortController is tracked and removed when aborted.
+ *
+ * @param transport The original Transport implementation.
+ * @param activeRequests The Set to track all active (not yet settled) request promises.
+ * @param activeAbortControllers The Set to track all active (not yet aborted) AbortControllers.
+ * @returns A new Transport that tracks all requests and abort controllers.
+ */
+export declare function createTransport(transport: Transport, activeRequests: Set<Promise<unknown>>, activeAbortControllers: Set<AbortController>): Transport;

package/dist/src/jmap-client/utils/transport.js

@@ -0,0 +1,38 @@
+import { createAbortController } from "./abort-controller.js";
+import { trackAbortController, trackPromise } from "./track-utils.js";
+/**
+ * Wrap a Transport implementation so that all requests and abort controllers are tracked in the provided Sets.
+ * Each request promise is added to the set and removed when settled.
+ * Each AbortController is tracked and removed when aborted.
+ *
+ * @param transport The original Transport implementation.
+ * @param activeRequests The Set to track all active (not yet settled) request promises.
+ * @param activeAbortControllers The Set to track all active (not yet aborted) AbortControllers.
+ * @returns A new Transport that tracks all requests and abort controllers.
+ */
+export function createTransport(transport, activeRequests, activeAbortControllers) {
+    function createChainedAbortController(externalSignal) {
+        const controller = createAbortController(externalSignal);
+        return trackAbortController(activeAbortControllers, controller);
+    }
+    function wrapMethod(method) {
+        return (url, options = {}) => {
+            const controller = createChainedAbortController(options.signal);
+            const promise = (async () => {
+                try {
+                    return await transport[method](url, { ...options, signal: controller.signal });
+                }
+                finally {
+                    activeAbortControllers.delete(controller);
+                }
+            })();
+            return trackPromise(activeRequests, promise);
+        };
+    }
+    const wrapped = {
+        get: wrapMethod("get"),
+        post: wrapMethod("post"),
+    };
+    return wrapped;
+}
+//# sourceMappingURL=transport.js.map

package/dist/src/jmap-client/utils/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../../../src/jmap-client/utils/transport.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEtE;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAC3B,SAAoB,EACpB,cAAqC,EACrC,sBAA4C;IAE5C,SAAS,4BAA4B,CAAC,cAA4B;QAC9D,MAAM,UAAU,GAAG,qBAAqB,CAAC,cAAc,CAAC,CAAC;QACzD,OAAO,oBAAoB,CAAC,sBAAsB,EAAE,UAAU,CAAC,CAAC;IACpE,CAAC;IAOD,SAAS,UAAU,CAAI,MAAsB;QACzC,OAAO,CACH,GAAiB,EACjB,UAA2E,EAAE,EACnE,EAAE;YACZ,MAAM,UAAU,GAAG,4BAA4B,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAChE,MAAM,OAAO,GAAG,CAAC,KAAK,IAAI,EAAE;gBACxB,IAAI,CAAC;oBACD,OAAO,MAAM,SAAS,CAAC,MAAM,CAAC,CAAI,GAAG,EAAE,EAAE,GAAG,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,CAAC,CAAC;gBACtF,CAAC;wBAAS,CAAC;oBACP,sBAAsB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;gBAC9C,CAAC;YACL,CAAC,CAAC,EAAE,CAAC;YACL,OAAO,YAAY,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;QACjD,CAAC,CAAC;IACN,CAAC;IAED,MAAM,OAAO,GAAc;QACvB,GAAG,EAAE,UAAU,CAAC,KAAK,CAAC;QACtB,IAAI,EAAE,UAAU,CAAC,MAAM,CAAC;KAC3B,CAAC;IAEF,OAAO,OAAO,CAAC;AACnB,CAAC"}

package/dist/src/jmap-client/utils/validate-session.d.ts

@@ -0,0 +1,19 @@
+import type { JMAPSessionFromSchema, Logger } from "../types.js";
+/**
+ * Parse and validate a JMAP session response using the JMAPSessionSchema.
+ *
+ * Performs structural validation only (required top-level fields, account shape,
+ * presence of the Core server capability key). Capability-specific content
+ * validation is performed separately via the capability registry's
+ * `validateServerCapabilities()` and `validateAccountCapabilities()` methods.
+ *
+ * The returned session object is **not** frozen — callers should apply
+ * `deepFreeze()` after capability validation has had a chance to strip
+ * invalid capabilities from the session.
+ *
+ * @param jsonResponse The raw JSON response from the server to be validated.
+ * @param logger Logger instance used to log validation errors.
+ * @returns The parsed and structurally validated session object (mutable).
+ * @throws Error if the response does not conform to the JMAPSessionSchema.
+ */
+export declare function parseAndValidateJMAPSession(jsonResponse: unknown, logger: Logger): JMAPSessionFromSchema;

package/dist/src/jmap-client/utils/validate-session.js

@@ -0,0 +1,29 @@
+import { JMAPSessionSchema } from "../types.js";
+/**
+ * Parse and validate a JMAP session response using the JMAPSessionSchema.
+ *
+ * Performs structural validation only (required top-level fields, account shape,
+ * presence of the Core server capability key). Capability-specific content
+ * validation is performed separately via the capability registry's
+ * `validateServerCapabilities()` and `validateAccountCapabilities()` methods.
+ *
+ * The returned session object is **not** frozen — callers should apply
+ * `deepFreeze()` after capability validation has had a chance to strip
+ * invalid capabilities from the session.
+ *
+ * @param jsonResponse The raw JSON response from the server to be validated.
+ * @param logger Logger instance used to log validation errors.
+ * @returns The parsed and structurally validated session object (mutable).
+ * @throws Error if the response does not conform to the JMAPSessionSchema.
+ */
+export function parseAndValidateJMAPSession(jsonResponse, logger) {
+    const parseResult = JMAPSessionSchema.safeParse(jsonResponse);
+    if (!parseResult.success) {
+        logger.error("Invalid JMAP session response", { error: parseResult.error });
+        throw new Error("Invalid JMAP session response", {
+            cause: parseResult.error,
+        });
+    }
+    return parseResult.data;
+}
+//# sourceMappingURL=validate-session.js.map

package/dist/src/jmap-client/utils/validate-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-session.js","sourceRoot":"","sources":["../../../../src/jmap-client/utils/validate-session.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,2BAA2B,CAAC,YAAqB,EAAE,MAAc;IAC7E,MAAM,WAAW,GAAG,iBAAiB,CAAC,SAAS,CAAC,YAAY,CAAC,CAAC;IAC9D,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;QACvB,MAAM,CAAC,KAAK,CAAC,+BAA+B,EAAE,EAAE,KAAK,EAAE,WAAW,CAAC,KAAK,EAAE,CAAC,CAAC;QAC5E,MAAM,IAAI,KAAK,CAAC,+BAA+B,EAAE;YAC7C,KAAK,EAAE,WAAW,CAAC,KAAK;SAC3B,CAAC,CAAC;IACP,CAAC;IACD,OAAO,WAAW,CAAC,IAAI,CAAC;AAC5B,CAAC"}

package/dist/src/request-builder/request-builder.d.ts

@@ -0,0 +1,95 @@
+import type { Id, IdMap, JMAPCapability, JMAPRequest } from "../common/types.js";
+import type { Invocation } from "../invocation/invocation.js";
+import type { BaseInvocationArgs } from "../invocation/types.js";
+import type { ClientContext, JMAPClientInterface } from "../jmap-client/types.js";
+export declare class RequestBuilder {
+    #private;
+    constructor(client: JMAPClientInterface<RequestBuilder>, { logger }: ClientContext);
+    /** Get the set of unique URIs that will be included in the `using` parameter of the JMAP request */
+    get using(): Set<JMAPCapability>;
+    /** Get the collection of method calls that are included in this request */
+    get methodCalls(): readonly Invocation<BaseInvocationArgs>[];
+    /** Get the map of created IDs that are included in this request */
+    get createdIds(): Readonly<Record<string, string>> | null;
+    /** Get the map of client-specified creation IDs to server-assigned IDs */
+    get idMap(): Map<symbol, Id>;
+    /** Get the reverse map of server-assigned IDs to client-specified creation IDs */
+    get reverseIdMap(): Map<Id, symbol>;
+    /**
+     * Add a method call to the request. All methods must be unique. If the method
+     * already exists in the request, it will not be added again.
+     *
+     * @param method The method call to add to the request
+     * @returns The invocation builder instance to allow for method chaining
+     * @throws Error if the method's capability is not registered with the client
+     * @throws Error if adding this method would exceed the server's maxCallsInRequest limit
+     * @throws AggregateError if the invocation validation fails
+     */
+    add(method: Invocation<BaseInvocationArgs>): this;
+    /**
+     * Remove a method call from the request. If the method does not exist in the
+     * request, this method will do nothing.
+     *
+     * @param method The method call to remove from the request
+     * @returns The invocation builder instance to allow for method chaining
+     */
+    remove(method: Invocation<BaseInvocationArgs>): this;
+    /**
+     * Add the map of client specified creation IDs to server assigned IDs, to be included in the request.
+     *
+     * This may be invoked with an empty object to initialise the createdIds for the first request,
+     * or with a map of client-specified creation IDs to the server-assigned IDs that were obtained from a
+     * previous response.
+     *
+     * @param createdIds The map of client-specified creation IDs to the server assigned IDs
+     * @returns The invocation builder instance to allow for method chaining
+     */
+    addCreatedIds(createdIds: IdMap): this;
+    /**
+     * Reset the map of creation ids to remove any that had been previously added.
+     * After invoking this, the createdIds property will will be omitted from the request.
+     */
+    clearCreatedIds(): this;
+    /**
+     * Build the JMAP request object from the current state of the builder.
+     *
+     * This will generate unique IDs for each method call, and resolve any
+     * client-specified creation IDs to server-assigned IDs if they were provided.
+     *
+     * @param idPrefix The prefix to use for generated IDs (default is "id_")
+     * @returns The constructed JMAP request object
+     * @throws AggregateError if the pre-build validation fails
+     */
+    build(idPrefix?: string): JMAPRequest;
+    /**
+     * Serialise the request for sending as a request body.
+     * By default, returns a JSON string, but can be extended to support other formats.
+     *
+     * @returns The serialised request (string, Blob, ArrayBuffer, etc.)
+     * @throws AggregateError if the pre-serialization validation fails
+     * @throws AggregateError if the post-serialization validation fails
+     */
+    serialize(): Promise<{
+        body: string | Blob | ArrayBuffer | File;
+        headers: Headers;
+    }>;
+    /**
+     * Send this request to the JMAP server using the associated client.
+     *
+     * @param signal Optional AbortSignal to cancel the request.
+     * @returns The parsed response from the server.
+     */
+    send(signal?: AbortSignal): Promise<{
+        methodResponses: import("../invocation-factory/invocation-list.js").InvocationList<BaseInvocationArgs>;
+        sessionState: string;
+        createdIds: IdMap;
+    }>;
+    toJSON(): JMAPRequest;
+    /**
+     * Validate all invocations currently in the request.
+     *
+     * @returns A Promise resolving to the invocation builder instance
+     * @throws AggregateError if any invocation validation fails
+     */
+    validateInvocations(): Promise<this>;
+}