@adukilabs/sdk 0.0.0-stage → 0.1.1

package/dist/envelope.d.ts

@@ -0,0 +1,59 @@
+import type { AdukiError } from './errors.js';
+/** Stable error kinds clients switch on (ADK-NET-001 section 4). */
+export declare const kinds: Readonly<{
+    missing: "auth.missing";
+    invalid: "auth.invalid";
+    stale: "auth.stale";
+    stepup: "auth.stepup";
+    denied: "access.denied";
+    input: "input.invalid";
+    absent: "entity.missing";
+    conflict: "entity.conflict";
+    limited: "rate.limited";
+    reset: "sync.reset";
+    quota: "quota.exceeded";
+    plan: "plan.limit";
+    unavailable: "auth.unavailable";
+    server: "server.error";
+}>;
+/** A parsed envelope: an object with a `success` field (the rest is the server's). */
+export type Envelope = Record<string, any>;
+/** `{status, kind, message, details}` of a failure envelope. */
+export interface Failure {
+    status: number;
+    kind: string;
+    message: string;
+    details: unknown;
+}
+/** The parsed envelope, or null when the body is not one. */
+export declare function parse(body: string): Envelope | null;
+/**
+ * The `data` of a success envelope, or the parsed body itself when it is not an
+ * envelope (servers from before it pass through unchanged).
+ */
+export declare function data(body: string): any;
+/** `{status, kind, message, details}` from a failure envelope, or null. */
+export declare function failure(body: string): Failure | null;
+/**
+ * The typed error of a failed answer whose body was `body` (see
+ * `errors.refusal`): the envelope's kind, message and details, the
+ * `Retry-After` header, and with `problem` the `type` and `detail` of an
+ * RFC 7807 problem document (JMAP request-level errors) when the body is no
+ * envelope. A body that is neither (the gateway's plain 429 or 503) leaves
+ * the status alone to speak.
+ * @param what names the call in error messages
+ */
+export declare function rejection(response: Response, body: string, what: string, options?: {
+    problem?: boolean;
+}): AdukiError;
+/**
+ * Reads a fetch Response as an envelope. A 2xx answer returns its `data`.
+ * A failure throws the typed error of `rejection`: UnauthorizedError for a
+ * 401 (`kind: message`), otherwise a NetworkError (or one of its subclasses:
+ * RateLimitedError, StepUpError, LimitError, SyncResetError, ServerError)
+ * with the HTTP status, the kind, the details and `retryAfter`.
+ * @param what names the call in error messages
+ */
+export declare function read(response: Response, what: string): Promise<any>;
+/** True for the `auth.stale` kind (rights changed, renew the token). */
+export declare function isStale(error: unknown): boolean;

package/dist/envelope.js

@@ -0,0 +1,114 @@
+// The Aduki REST envelope (ADK-NET-001 section 3):
+// {success: true, data} or {success: false, error: {status, kind, message, details}}.
+import { NetworkError, UnauthorizedError, refusal } from './errors.js';
+/** Stable error kinds clients switch on (ADK-NET-001 section 4). */
+export const kinds = Object.freeze({
+    missing: 'auth.missing',
+    invalid: 'auth.invalid',
+    stale: 'auth.stale',
+    stepup: 'auth.stepup',
+    denied: 'access.denied',
+    input: 'input.invalid',
+    absent: 'entity.missing',
+    conflict: 'entity.conflict',
+    limited: 'rate.limited',
+    reset: 'sync.reset',
+    quota: 'quota.exceeded',
+    plan: 'plan.limit',
+    unavailable: 'auth.unavailable',
+    server: 'server.error',
+});
+/** The parsed envelope, or null when the body is not one. */
+export function parse(body) {
+    const text = String(body ?? '').trimStart();
+    if (!text.startsWith('{'))
+        return null;
+    try {
+        const value = JSON.parse(text);
+        return value && typeof value === 'object' && 'success' in value ? value : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The `data` of a success envelope, or the parsed body itself when it is not an
+ * envelope (servers from before it pass through unchanged).
+ */
+export function data(body) {
+    const envelope = parse(body);
+    if (!envelope || envelope.success !== true) {
+        try {
+            return JSON.parse(body);
+        }
+        catch {
+            return body;
+        }
+    }
+    return envelope.data ?? null;
+}
+/** `{status, kind, message, details}` from a failure envelope, or null. */
+export function failure(body) {
+    const error = parse(body)?.error;
+    if (!error || typeof error !== 'object')
+        return null;
+    return {
+        status: Number(error.status) || 0,
+        kind: String(error.kind ?? ''),
+        message: String(error.message ?? ''),
+        details: error.details,
+    };
+}
+/**
+ * The typed error of a failed answer whose body was `body` (see
+ * `errors.refusal`): the envelope's kind, message and details, the
+ * `Retry-After` header, and with `problem` the `type` and `detail` of an
+ * RFC 7807 problem document (JMAP request-level errors) when the body is no
+ * envelope. A body that is neither (the gateway's plain 429 or 503) leaves
+ * the status alone to speak.
+ * @param what names the call in error messages
+ */
+export function rejection(response, body, what, options = {}) {
+    const error = failure(body);
+    let kind = error?.kind ?? '';
+    let message = error?.message ?? '';
+    let details = error?.details;
+    if (!error && options.problem) {
+        try {
+            const problem = JSON.parse(body);
+            if (problem && typeof problem === 'object') {
+                kind = String(problem.type ?? '');
+                message = String(problem.detail ?? problem.title ?? '');
+                details = problem;
+            }
+        }
+        catch {
+            // not JSON: the status says it
+        }
+    }
+    return refusal({ status: response.status, kind, message, details, retry: response.headers.get('Retry-After'), what });
+}
+/**
+ * Reads a fetch Response as an envelope. A 2xx answer returns its `data`.
+ * A failure throws the typed error of `rejection`: UnauthorizedError for a
+ * 401 (`kind: message`), otherwise a NetworkError (or one of its subclasses:
+ * RateLimitedError, StepUpError, LimitError, SyncResetError, ServerError)
+ * with the HTTP status, the kind, the details and `retryAfter`.
+ * @param what names the call in error messages
+ */
+export async function read(response, what) {
+    const body = await response.text();
+    if (!response.ok)
+        throw rejection(response, body, what);
+    const envelope = parse(body);
+    if (!envelope)
+        throw new NetworkError(`Empty response from ${what}`, { status: response.status });
+    if (envelope.data === undefined || envelope.data === null) {
+        throw new NetworkError(`Empty response from ${what}`, { status: response.status });
+    }
+    return envelope.data;
+}
+/** True for the `auth.stale` kind (rights changed, renew the token). */
+export function isStale(error) {
+    return error instanceof UnauthorizedError && error.kind === kinds.stale;
+}

package/dist/errors.d.ts

@@ -0,0 +1,153 @@
+/** Base class of every error the SDK throws. */
+export declare class AdukiError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The options of NetworkError and its subclasses. */
+export interface NetworkErrorOptions {
+    status?: number | undefined;
+    kind?: string | undefined;
+    details?: unknown;
+    /** seconds to wait before trying again (`Retry-After`, or the envelope's `details`) */
+    retryAfter?: number | undefined;
+    cause?: unknown;
+}
+/**
+ * Transport failure or a non-2xx answer that is not a 401. `status` is the
+ * HTTP status when there was one (undefined: the server was not reached).
+ * `retryAfter` holds the seconds the server asked to wait, when it said.
+ * The subclasses below name the answers a client acts on; see `refusal`.
+ */
+export declare class NetworkError extends AdukiError {
+    status: number | undefined;
+    kind: string;
+    details: unknown;
+    retryAfter: number | undefined;
+    constructor(message: string, options?: NetworkErrorOptions);
+}
+/** `429`: too many requests (`rate.limited`, `mail.queue_busy`, or the gateway's plain 429). Wait `retryAfter` seconds when given. */
+export declare class RateLimitedError extends NetworkError {
+}
+/** `403 auth.stepup`: the action needs a fresh second factor; the session stays valid. */
+export declare class StepUpError extends NetworkError {
+}
+/**
+ * A package limit or quota was reached: `403 plan.limit` or `507 quota.exceeded`.
+ * `key`, `limit` and `used` come from the details when the server sent them.
+ */
+export declare class LimitError extends NetworkError {
+    key: string;
+    limit: number | undefined;
+    used: number | undefined;
+    constructor(message: string, options?: NetworkErrorOptions);
+}
+/** `410 sync.reset`: the sync token is no longer known; sync again without one. */
+export declare class SyncResetError extends NetworkError {
+}
+/** A `5xx` answer (`server.error`, `auth.unavailable`, a gateway 502, 503 or 504); `retryAfter` when the server said. */
+export declare class ServerError extends NetworkError {
+}
+/** The kinds after which the session is over and its tokens are useless (aduki-kt `Unauthorized.ENDED`). */
+export declare const ENDED: readonly string[];
+/** The server refused the credentials (401): wrong password, spent refresh token, stale token. */
+export declare class UnauthorizedError extends AdukiError {
+    status: number;
+    kind: string;
+    details: unknown;
+    constructor(message: string, options?: {
+        kind?: string;
+        details?: unknown;
+        cause?: unknown;
+    });
+    /**
+     * True when the kind says the session is over (`auth.invalid`,
+     * `auth.reused`, `auth.revoked`, `auth.expired`); false for other kinds
+     * (`auth.factor`, `auth.stale`, `auth.dpop`) and for a 401 without one.
+     */
+    get ended(): boolean;
+}
+/**
+ * `401 auth.dpop` or `401 auth.nonce`: the DPoP proof was refused (a key or
+ * clock problem), not the credentials (aduki-kt `AdukiException.Proof`). A
+ * subclass of UnauthorizedError, so existing `instanceof` checks still match.
+ */
+export declare class ProofError extends UnauthorizedError {
+}
+/**
+ * `401` with `details.reason = "token.required"`: the server needs the Aduki
+ * ID token and its proof with the request (the Chats handshake on an Aduki
+ * deployment). A client that cannot send them is too old: tell the user to
+ * update instead of retrying.
+ */
+export declare class TokenRequiredError extends UnauthorizedError {
+}
+/**
+ * `401` with `details.reason = "session.expired"` or `"session.ended"`: the
+ * Chats session is over (its time ran out, or Aduki ID ended the sign-in
+ * session that authorized it). Repeat the handshake; after `session.ended`
+ * that needs a current token (the person may have to sign in again).
+ */
+export declare class SessionEndedError extends UnauthorizedError {
+    /** `session.expired` or `session.ended` */
+    get reason(): string;
+}
+/**
+ * `403` with `details.reason = "subject"` (the token is for another account
+ * than the device's) or `"jkt.mismatch"` (the device is bound to another
+ * Aduki ID key than the token's). Retrying with the same key does not help.
+ */
+export declare class IdentityMismatchError extends NetworkError {
+    /** `subject` or `jkt.mismatch` */
+    get reason(): string;
+}
+/**
+ * A 2xx authentication answer that could not be used. `refresh` carries a
+ * rotated refresh token the answer did include, so callers never lose a token
+ * the server already swapped in.
+ */
+export declare class AuthError extends AdukiError {
+    refresh: string;
+    constructor(message: string, options?: {
+        refresh?: string;
+        cause?: unknown;
+    });
+}
+/** A protocol violation: bad state, issuer mismatch, bad id token, missing field. */
+export declare class ProtocolError extends AdukiError {
+}
+/** A storage backend failed. */
+export declare class StorageError extends AdukiError {
+}
+/** What `refusal` needs to know of a failed answer. */
+export interface Refused {
+    /** the HTTP status */
+    status: number;
+    /** the envelope's kind, or the problem document's type ('' when none) */
+    kind?: string | undefined;
+    /** the server's message ('' or absent: `HTTP <status>`) */
+    message?: string | undefined;
+    details?: unknown;
+    /** the `Retry-After` header, as sent */
+    retry?: string | null | undefined;
+    /** names the call in the message (`<what> failed: ...`) */
+    what?: string | undefined;
+}
+/**
+ * The one mapping from a refused answer to a typed error, used by every
+ * service module. A 401 is UnauthorizedError (`auth.dpop`, `auth.nonce`:
+ * ProofError; `details.reason` `token.required`: TokenRequiredError;
+ * `session.expired`, `session.ended`: SessionEndedError); a 429
+ * RateLimitedError; a 403 with `details.reason` `subject` or `jkt.mismatch`
+ * IdentityMismatchError; `403 auth.stepup` StepUpError;
+ * `plan.limit` and `quota.exceeded` LimitError; `sync.reset` SyncResetError;
+ * a 5xx ServerError; anything else NetworkError. Every one but the 401s is a
+ * NetworkError with `status`, `kind`, `details` and `retryAfter` (from the
+ * `Retry-After` header, else `details.retry_after` or `details.retry`).
+ */
+export declare function refusal({ status, kind, message, details, retry, what }: Refused): AdukiError;
+/**
+ * The seconds of a `Retry-After` value (delta seconds or an HTTP date), or
+ * undefined when absent or unreadable. Never negative.
+ */
+export declare function retryAfter(value: string | null | undefined, now?: number): number | undefined;

package/dist/errors.js

@@ -0,0 +1,190 @@
+// Errors mirror the Kotlin SDK's AdukiException hierarchy (aduki-kt core/errors).
+/** Base class of every error the SDK throws. */
+export class AdukiError extends Error {
+    constructor(message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = new.target.name;
+    }
+}
+/**
+ * Transport failure or a non-2xx answer that is not a 401. `status` is the
+ * HTTP status when there was one (undefined: the server was not reached).
+ * `retryAfter` holds the seconds the server asked to wait, when it said.
+ * The subclasses below name the answers a client acts on; see `refusal`.
+ */
+export class NetworkError extends AdukiError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.status = options.status;
+        this.kind = options.kind ?? '';
+        this.details = options.details;
+        this.retryAfter = options.retryAfter;
+    }
+}
+/** `429`: too many requests (`rate.limited`, `mail.queue_busy`, or the gateway's plain 429). Wait `retryAfter` seconds when given. */
+export class RateLimitedError extends NetworkError {
+}
+/** `403 auth.stepup`: the action needs a fresh second factor; the session stays valid. */
+export class StepUpError extends NetworkError {
+}
+/**
+ * A package limit or quota was reached: `403 plan.limit` or `507 quota.exceeded`.
+ * `key`, `limit` and `used` come from the details when the server sent them.
+ */
+export class LimitError extends NetworkError {
+    constructor(message, options = {}) {
+        super(message, options);
+        const details = options.details && typeof options.details === 'object' ? options.details : {};
+        this.key = typeof details.key === 'string' ? details.key : '';
+        this.limit = typeof details.limit === 'number' ? details.limit : undefined;
+        this.used = typeof details.used === 'number' ? details.used : undefined;
+    }
+}
+/** `410 sync.reset`: the sync token is no longer known; sync again without one. */
+export class SyncResetError extends NetworkError {
+}
+/** A `5xx` answer (`server.error`, `auth.unavailable`, a gateway 502, 503 or 504); `retryAfter` when the server said. */
+export class ServerError extends NetworkError {
+}
+/** The kinds after which the session is over and its tokens are useless (aduki-kt `Unauthorized.ENDED`). */
+export const ENDED = Object.freeze(['auth.invalid', 'auth.reused', 'auth.revoked', 'auth.expired']);
+/** The server refused the credentials (401): wrong password, spent refresh token, stale token. */
+export class UnauthorizedError extends AdukiError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.status = 401;
+        this.kind = options.kind ?? '';
+        this.details = options.details;
+    }
+    /**
+     * True when the kind says the session is over (`auth.invalid`,
+     * `auth.reused`, `auth.revoked`, `auth.expired`); false for other kinds
+     * (`auth.factor`, `auth.stale`, `auth.dpop`) and for a 401 without one.
+     */
+    get ended() {
+        return ENDED.includes(this.kind);
+    }
+}
+/**
+ * `401 auth.dpop` or `401 auth.nonce`: the DPoP proof was refused (a key or
+ * clock problem), not the credentials (aduki-kt `AdukiException.Proof`). A
+ * subclass of UnauthorizedError, so existing `instanceof` checks still match.
+ */
+export class ProofError extends UnauthorizedError {
+}
+/** `details.reason` of a refusal, or ''. */
+function reasonOf(details) {
+    const value = details && typeof details === 'object' ? details.reason : undefined;
+    return typeof value === 'string' ? value : '';
+}
+/**
+ * `401` with `details.reason = "token.required"`: the server needs the Aduki
+ * ID token and its proof with the request (the Chats handshake on an Aduki
+ * deployment). A client that cannot send them is too old: tell the user to
+ * update instead of retrying.
+ */
+export class TokenRequiredError extends UnauthorizedError {
+}
+/**
+ * `401` with `details.reason = "session.expired"` or `"session.ended"`: the
+ * Chats session is over (its time ran out, or Aduki ID ended the sign-in
+ * session that authorized it). Repeat the handshake; after `session.ended`
+ * that needs a current token (the person may have to sign in again).
+ */
+export class SessionEndedError extends UnauthorizedError {
+    /** `session.expired` or `session.ended` */
+    get reason() {
+        return reasonOf(this.details);
+    }
+}
+/**
+ * `403` with `details.reason = "subject"` (the token is for another account
+ * than the device's) or `"jkt.mismatch"` (the device is bound to another
+ * Aduki ID key than the token's). Retrying with the same key does not help.
+ */
+export class IdentityMismatchError extends NetworkError {
+    /** `subject` or `jkt.mismatch` */
+    get reason() {
+        return reasonOf(this.details);
+    }
+}
+/**
+ * A 2xx authentication answer that could not be used. `refresh` carries a
+ * rotated refresh token the answer did include, so callers never lose a token
+ * the server already swapped in.
+ */
+export class AuthError extends AdukiError {
+    constructor(message, options = {}) {
+        super(message, options);
+        this.refresh = options.refresh ?? '';
+    }
+}
+/** A protocol violation: bad state, issuer mismatch, bad id token, missing field. */
+export class ProtocolError extends AdukiError {
+}
+/** A storage backend failed. */
+export class StorageError extends AdukiError {
+}
+/**
+ * The one mapping from a refused answer to a typed error, used by every
+ * service module. A 401 is UnauthorizedError (`auth.dpop`, `auth.nonce`:
+ * ProofError; `details.reason` `token.required`: TokenRequiredError;
+ * `session.expired`, `session.ended`: SessionEndedError); a 429
+ * RateLimitedError; a 403 with `details.reason` `subject` or `jkt.mismatch`
+ * IdentityMismatchError; `403 auth.stepup` StepUpError;
+ * `plan.limit` and `quota.exceeded` LimitError; `sync.reset` SyncResetError;
+ * a 5xx ServerError; anything else NetworkError. Every one but the 401s is a
+ * NetworkError with `status`, `kind`, `details` and `retryAfter` (from the
+ * `Retry-After` header, else `details.retry_after` or `details.retry`).
+ */
+export function refusal({ status, kind = '', message, details, retry, what }) {
+    const text = message || `HTTP ${status}`;
+    const reason = reasonOf(details);
+    if (status === 401) {
+        const Type = reason === 'token.required' ? TokenRequiredError
+            : reason === 'session.expired' || reason === 'session.ended' ? SessionEndedError
+                : kind === 'auth.dpop' || kind === 'auth.nonce' ? ProofError : UnauthorizedError;
+        return new Type(kind ? `${kind}: ${text}` : text, { kind, details });
+    }
+    const options = { status, kind, details };
+    const wait = retryAfter(retry) ?? waited(details);
+    if (wait !== undefined)
+        options.retryAfter = wait;
+    const full = `${what ?? 'Request'} failed: ${text}`;
+    if (status === 429)
+        return new RateLimitedError(full, options);
+    if (status === 403 && (reason === 'subject' || reason === 'jkt.mismatch'))
+        return new IdentityMismatchError(full, options);
+    if (kind === 'auth.stepup')
+        return new StepUpError(full, options);
+    if (kind === 'plan.limit' || kind === 'quota.exceeded')
+        return new LimitError(full, options);
+    if (kind === 'sync.reset')
+        return new SyncResetError(full, options);
+    if (status >= 500 && status <= 599)
+        return new ServerError(full, options);
+    return new NetworkError(full, options);
+}
+/**
+ * The seconds of a `Retry-After` value (delta seconds or an HTTP date), or
+ * undefined when absent or unreadable. Never negative.
+ */
+export function retryAfter(value, now = Date.now()) {
+    const text = value?.trim();
+    if (!text)
+        return undefined;
+    if (/^\d+$/.test(text))
+        return Number(text);
+    const at = Date.parse(text);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, Math.ceil((at - now) / 1000));
+}
+/** `details.retry_after` (Aduki Mail) or `details.retry` (Aduki ID) in seconds. */
+function waited(details) {
+    if (!details || typeof details !== 'object')
+        return undefined;
+    const o = details;
+    const value = o.retry_after ?? o.retry;
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? Math.ceil(value) : undefined;
+}

package/dist/http.d.ts

@@ -0,0 +1,11 @@
+/** `base` and `path` joined with exactly one slash. */
+export declare const url: (base: string, path: string) => string;
+/** Runs fetch and turns a transport failure into NetworkError (an abort is passed through). */
+export declare function send(fetcher: typeof fetch, input: Request | string | URL, init?: RequestInit): Promise<Response>;
+/** The headers and body of a JSON request. */
+export declare const json: (body: unknown) => {
+    headers: {
+        'Content-Type': string;
+    };
+    body: string;
+};

package/dist/http.js

@@ -0,0 +1,22 @@
+// Small HTTP helpers shared by every service module (Aduki ID today; mail and
+// the other APIs next): joining a base and a path, a JSON request body, and a
+// fetch that reports a transport failure as NetworkError.
+import { NetworkError } from './errors.js';
+/** `base` and `path` joined with exactly one slash. */
+export const url = (base, path) => `${base.replace(/\/+$/, '')}/${path}`;
+/** Runs fetch and turns a transport failure into NetworkError (an abort is passed through). */
+export async function send(fetcher, input, init) {
+    try {
+        return await fetcher(input, init);
+    }
+    catch (cause) {
+        if (cause instanceof Error && cause.name === 'AbortError')
+            throw cause;
+        throw new NetworkError(`Request failed: ${cause instanceof Error ? cause.message : cause}`, { cause });
+    }
+}
+/** The headers and body of a JSON request. */
+export const json = (body) => ({
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+});

package/dist/jmap.d.ts

@@ -0,0 +1,100 @@
+import { AdukiError } from './errors.js';
+export declare const CORE = "urn:ietf:params:jmap:core";
+export declare const MAIL = "urn:ietf:params:jmap:mail";
+export declare const SUBMISSION = "urn:ietf:params:jmap:submission";
+/** Aduki body reading: `Email/get` takes `aduki:bodyMode` (ADK-MAIL-001 section 1.4, v47). */
+export declare const READING = "urn:aduki:params:jmap:reading";
+/** Core and mail: enough for `Mailbox`, `Email` and `Thread`. */
+export declare const USING: readonly string[];
+/** An authenticated fetch for one audience: `Session` and `Client` both have it. */
+export interface AudienceFetch {
+    fetch(audience: string, input: Request | string | URL, init?: RequestInit): Promise<Response>;
+}
+/** The part of the JMAP session resource the SDK uses. */
+export interface JmapSession {
+    /** the primary mail account id */
+    account: string;
+    api: string;
+    /** URL template with `{accountId}` */
+    upload: string;
+    /** URL template with `{accountId}`, `{blobId}`, `{name}`, `{type}` */
+    download: string;
+    /** URL template with `{types}`, `{closeafter}`, `{ping}` */
+    eventSource: string;
+    /** every session capability advertised */
+    capabilities: string[];
+    /** `urn:ietf:params:jmap:core` limits (`maxSizeUpload`, `maxCallsInRequest`, ...) */
+    limits: Record<string, unknown>;
+    /** the server reads bodies (`aduki:bodyMode`), see READING */
+    reading: boolean;
+}
+/** One method call: `[name, arguments, call id]`. */
+export type Invocation = [name: string, args: Record<string, unknown>, id: string];
+/** An uploaded blob. */
+export interface Uploaded {
+    blob: string;
+    type: string;
+    size: number;
+}
+/**
+ * A JMAP method error (`["error", {type, description}, id]`) or a per-object
+ * refusal of a `/set` call (`notCreated`, `notUpdated`, `notDestroyed`).
+ * `type` is the JMAP error type (`invalidArguments`, `forbiddenFrom`,
+ * `notFound`, ...); `id` names the object for a per-object refusal.
+ */
+export declare class JmapError extends AdukiError {
+    type: string;
+    description: string;
+    properties: string[];
+    method: string;
+    id: string;
+    constructor(method: string, error: Record<string, any>, id?: string);
+}
+export interface JmapOptions {
+    /** where the token comes from: a `Session` or a `Client` from `createClient` */
+    session: AudienceFetch;
+    /** the mail host root without `/v1` (default `https://mail.aduki.pro`) */
+    root?: string | undefined;
+    /** the token audience (default `mail`) */
+    audience?: string | undefined;
+}
+export declare const ROOT = "https://mail.aduki.pro";
+export declare class Jmap {
+    #private;
+    constructor(options: JmapOptions);
+    /** Sends an authenticated request to the mail host (a path or an absolute URL). */
+    fetch(input: string, init?: RequestInit): Promise<Response>;
+    /** The session (`GET /jmap/session`), fetched once; `refresh` fetches it again. */
+    session(refresh?: boolean): Promise<JmapSession>;
+    /** The primary mail account id. */
+    account(): Promise<string>;
+    /**
+     * Runs `calls` in one request and returns every response in order
+     * (`[name, args, id]`). A method `error` response throws JmapError;
+     * per-object refusals (`notCreated`, ...) are left to the caller.
+     */
+    call(calls: Invocation[], using?: readonly string[]): Promise<Invocation[]>;
+    /**
+     * Runs one method with `accountId` set and returns its arguments (the
+     * first response with the call id; implicit responses are dropped).
+     */
+    method(name: string, args?: Record<string, unknown>, using?: readonly string[]): Promise<Record<string, any>>;
+    /** Uploads `data` as a blob of `type` (RFC 8620 section 6.1). */
+    upload(data: Blob | ArrayBuffer | Uint8Array, type?: string): Promise<Uploaded>;
+    /**
+     * Downloads blob `blob` (RFC 8620 section 6.2). Returns the open response
+     * (read it with `blob()`, `arrayBuffer()` or `body`); a failure throws.
+     * `name` and `type` label the download (`Content-Disposition`, `Content-Type`).
+     */
+    download(blob: string, options?: {
+        name?: string;
+        type?: string;
+    }): Promise<Response>;
+}
+/**
+ * Throws for a non-2xx answer (`envelope.rejection`): 401 is
+ * UnauthorizedError, anything else a NetworkError (or a subclass) with the
+ * status and the kind of the envelope or the type of the RFC 7807 problem
+ * document JMAP uses for request-level errors.
+ */
+export declare function refuse(response: Response, what: string): Promise<never>;