@adukilabs/sdk 0.0.0-stage → 0.1.1

package/dist/api/api.js

@@ -0,0 +1,361 @@
+// The API-key client: programs (servers, scripts, workers) that call Aduki
+// Mail with a tenant API key, `Authorization: Key <key>`. No sign-in, no
+// browser storage, no DPoP: the key is the credential, its stored scopes
+// (narrowed to what the workspace owner who made it may do) are its rights.
+//
+// Aduki Mail (`mail.aduki.pro`) is the one service that accepts API keys:
+// its REST API under `/v1` (the `user` and `tenant` routes; never
+// `platform`) and its JMAP endpoints. Aduki ID, Store and Space take only
+// Aduki ID tokens.
+import { rejection } from '../envelope.js';
+import { ProtocolError } from '../errors.js';
+import { json, send, url } from '../http.js';
+import { Jmap } from '../jmap.js';
+import { createKey } from './key.js';
+/** The mail host (REST under `/v1`, JMAP at the root). */
+export const ROOT = 'https://mail.aduki.pro';
+export class Api {
+    /** the JMAP client on the same key (mail: `u.mail:read`, sending: `u.mail:send`) */
+    jmap;
+    user;
+    mail;
+    mailboxes;
+    contacts;
+    calendar;
+    keys;
+    #key;
+    #root;
+    #fetch;
+    random;
+    constructor(options) {
+        const key = options?.key?.trim();
+        if (!key)
+            throw new TypeError('Api needs a key');
+        if (/\s/.test(key))
+            throw new TypeError('An API key has no whitespace');
+        this.#key = key;
+        this.#root = (options.root ?? ROOT).replace(/\/+$/, '');
+        const transport = options.fetch ?? ((...args) => globalThis.fetch(...args));
+        this.#fetch = (input, init) => send(transport, input, init);
+        this.random = options.random ?? (() => crypto.randomUUID());
+        const keyed = { fetch: (_audience, input, init) => this.#send(input, init) };
+        this.jmap = new Jmap({ session: keyed, root: this.#root });
+        this.user = new User(this);
+        this.mail = new MailApi(this);
+        this.mailboxes = new Mailboxes(this);
+        this.contacts = new ContactsApi(this);
+        this.calendar = new CalendarApi(this);
+        this.keys = new Keys(this);
+    }
+    /** The request with the key added (an absolute URL, or a path on the mail host). */
+    #send(input, init) {
+        const target = typeof input === 'string' && !/^https?:\/\//.test(input) ? url(this.#root, input.replace(/^\/+/, '')) : input;
+        const request = new Request(target, init);
+        request.headers.set('Authorization', `Key ${this.#key}`);
+        return this.#fetch(request);
+    }
+    /**
+     * Sends a request to the mail host with the key (`path` relative to the
+     * host, as `v1/user`, or an absolute URL) and returns the raw response.
+     * A transport failure is a NetworkError; the answer is not checked.
+     */
+    fetch(path, init) {
+        return this.#send(path, init);
+    }
+    /**
+     * Any REST route under `/v1` (`path` without it, as `user/profile`):
+     * returns the envelope's `data` (null for `204`); a refusal throws the
+     * typed error of `errors.refusal` (UnauthorizedError for a bad key,
+     * NetworkError with `403 access.denied` for a scope the key lacks,
+     * RateLimitedError with `retryAfter`, ...).
+     */
+    async call(method, path, options = {}) {
+        let target = `v1/${path.replace(/^\/+/, '')}`;
+        const query = new URLSearchParams();
+        for (const [name, value] of Object.entries(options.query ?? {}))
+            if (value !== undefined)
+                query.set(name, String(value));
+        if ([...query].length)
+            target += `?${query}`;
+        const headers = { Accept: 'application/json' };
+        let body;
+        if (options.body !== undefined) {
+            const request = json(options.body);
+            Object.assign(headers, request.headers);
+            body = request.body;
+        }
+        if (options.idempotency)
+            headers['Idempotency-Key'] = options.idempotency;
+        const init = { method, headers };
+        if (body !== undefined)
+            init.body = body;
+        if (options.signal)
+            init.signal = options.signal;
+        const response = await this.#send(target, init);
+        const text = await response.text();
+        const what = `${method} /${target.split('?')[0]}`;
+        if (!response.ok)
+            throw rejection(response, text, what);
+        if (response.status === 204 || !text.trim())
+            return null;
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new ProtocolError(`${what} answer is not JSON`);
+        }
+        return (parsed && typeof parsed === 'object' && 'success' in parsed ? (parsed.data ?? null) : parsed);
+    }
+    /** `GET` of a list route with paging (see PageQuery). */
+    page(path, query = {}) {
+        return this.call('GET', path, { query: query });
+    }
+    /** Every item of a list route, following the cursor (`after`) page by page. */
+    async *all(path, query = {}) {
+        let after;
+        do {
+            const page = await this.page(path, { ...query, after });
+            yield* page.items ?? [];
+            after = page.next || undefined;
+        } while (after);
+    }
+}
+const seg = (value) => encodeURIComponent(value);
+/** The account the key acts as. Scope `users:read`. */
+export class User {
+    #api;
+    constructor(api) {
+        this.#api = api;
+    }
+    /** `GET /v1/user`: the account. */
+    get() {
+        return this.#api.call('GET', 'user');
+    }
+    /** `GET /v1/user/profile`: name, address, workspace, role, plan, storage. */
+    profile() {
+        return this.#api.call('GET', 'user/profile');
+    }
+    /** `GET /v1/user/keys`: the API keys made by this account (never the keys themselves). */
+    keys(query = {}) {
+        return this.#api.page('user/keys', query);
+    }
+    /** `GET /v1/user/aliases` (scope `aliases:read`). */
+    aliases() {
+        return this.#api.call('GET', 'user/aliases');
+    }
+}
+/** Mail over REST. Reading needs `mail:read`, changes `mail:write`, sending `mail:send`. */
+export class MailApi {
+    #api;
+    constructor(api) {
+        this.#api = api;
+    }
+    /**
+     * `POST /v1/user/mail/send`: a plain-text message, a copy filed in Sent;
+     * returns its hex. `from` defaults to the default identity (an address the
+     * account may not send as is `403`). Sent with an `Idempotency-Key`
+     * (`idempotency`, else a random one): a retry with the same key never
+     * sends twice. A full queue is `RateLimitedError` (`mail.queue_busy`).
+     */
+    async send(input, options = {}) {
+        const body = { to: input.to, subject: input.subject, text: input.text };
+        if (input.cc?.length)
+            body.cc = input.cc;
+        if (input.from)
+            body.from = input.from;
+        const data = await this.#api.call('POST', 'user/mail/send', { body, idempotency: options.idempotency ?? this.#api.random() });
+        if (typeof data?.hex !== 'string')
+            throw new ProtocolError('Send answer has no hex');
+        return data.hex;
+    }
+    /** `GET /v1/user/mail/<folder>`: the messages of a folder, newest first. */
+    list(folder, query = {}) {
+        return this.#api.page(`user/mail/${folder}`, query);
+    }
+    /** `GET /v1/user/mail/inbox/unread`. */
+    /** `GET /v1/user/mail/{hex}`: one message (scope `mail:read`); a deleted or unknown one is a 404. */
+    get(hex) {
+        return this.#api.call('GET', `user/mail/${seg(hex)}`);
+    }
+    unread(query = {}) {
+        return this.#api.page('user/mail/inbox/unread', query);
+    }
+    /** `GET /v1/user/mail/folder/{name}`: a mailbox by name. */
+    folder(name, query = {}) {
+        return this.#api.page(`user/mail/folder/${seg(name)}`, query);
+    }
+    /** `GET /v1/user/mail/search/{text}`. */
+    search(text, query = {}) {
+        return this.#api.page(`user/mail/search/${seg(text)}`, query);
+    }
+    /** `GET /v1/user/mail/threads`. */
+    threads(query = {}) {
+        return this.#api.page('user/mail/threads', query);
+    }
+    /** `GET /v1/user/mail/thread/{thread}`: the messages of a thread. */
+    thread(thread, query = {}) {
+        return this.#api.page(`user/mail/thread/${seg(thread)}`, query);
+    }
+    /**
+     * `GET /v1/user/mail/changes`: what changed in a mailbox since `since` (a
+     * modseq, 0 for everything). Pass the `uidvalidity` last seen: a stale one
+     * comes back with `reset`.
+     */
+    changes(input) {
+        return this.#api.call('GET', 'user/mail/changes', {
+            query: { mailbox: input.mailbox, since: input.since ?? 0, uidvalidity: input.uidvalidity, limit: input.limit },
+        });
+    }
+    /** `PATCH /v1/user/mail/{hex}/flags`: adds and removes flags (`\\Seen`, `\\Flagged`, ...). */
+    async flags(hex, change) {
+        await this.#api.call('PATCH', `user/mail/${seg(hex)}/flags`, { body: { add: change.add ?? [], remove: change.remove ?? [] } });
+    }
+    /** `PATCH /v1/user/mail/{hex}/mailbox`: moves a message to another mailbox (hex). */
+    move(hex, mailbox) {
+        return this.#api.call('PATCH', `user/mail/${seg(hex)}/mailbox`, { body: { mailbox } });
+    }
+    /** `DELETE /v1/user/mail/{hex}`. */
+    async delete(hex) {
+        await this.#api.call('DELETE', `user/mail/${seg(hex)}`);
+    }
+}
+/** Mailboxes over REST: `mailbox:read`. */
+export class Mailboxes {
+    #api;
+    constructor(api) {
+        this.#api = api;
+    }
+    /** `GET /v1/user/mailbox`. */
+    list(query = {}) {
+        return this.#api.page('user/mailbox', query);
+    }
+    /** `GET /v1/user/mailbox/unread`: the mailboxes with unread mail. */
+    unread(query = {}) {
+        return this.#api.page('user/mailbox/unread', query);
+    }
+    /** `GET /v1/user/mailbox/search/{text}`. */
+    search(text, query = {}) {
+        return this.#api.page(`user/mailbox/search/${seg(text)}`, query);
+    }
+}
+/** The address book over REST: `contacts:read`, `contacts:write` to delete. */
+export class ContactsApi {
+    #api;
+    constructor(api) {
+        this.#api = api;
+    }
+    /** `GET /v1/user/contacts`. */
+    list(query = {}) {
+        return this.#api.page('user/contacts', query);
+    }
+    /** `GET /v1/user/contacts/{hex}`: one contact (scope `contacts:read`). */
+    get(hex) {
+        return this.#api.call('GET', `user/contacts/${seg(hex)}`);
+    }
+    /** `GET /v1/user/contacts/search/{text}`. */
+    search(text, query = {}) {
+        return this.#api.page(`user/contacts/search/${seg(text)}`, query);
+    }
+    /** `GET /v1/user/contacts/groups`. */
+    groups(query = {}) {
+        return this.#api.page('user/contacts/groups', query);
+    }
+    /** `GET /v1/user/contacts/group/{group}`: the cards of a group. */
+    group(group, query = {}) {
+        return this.#api.page(`user/contacts/group/${seg(group)}`, query);
+    }
+    /**
+     * `GET /v1/user/contacts/sync`: one page of changes since `since` (the
+     * `token` of the last answer; none for the whole book). A token the server
+     * no longer knows throws SyncResetError: sync again without one.
+     */
+    sync(input = {}) {
+        return this.#api.call('GET', 'user/contacts/sync', { query: { since: input.since, limit: input.limit } });
+    }
+    /** `DELETE /v1/user/contacts/{hex}`. */
+    async delete(hex) {
+        await this.#api.call('DELETE', `user/contacts/${seg(hex)}`);
+    }
+}
+/** Calendars and events over REST: `calendars:read`, `calendars:write` to delete. */
+export class CalendarApi {
+    #api;
+    constructor(api) {
+        this.#api = api;
+    }
+    /** `GET /v1/user/calendars`. */
+    /** `GET /v1/user/calendars/{hex}`: one calendar (scope `calendars:read`). */
+    calendar(hex) {
+        return this.#api.call('GET', `user/calendars/${seg(hex)}`);
+    }
+    /** `GET /v1/user/events/{hex}`: one event with its `calendar` hex (scope `calendars:read`). */
+    event(hex) {
+        return this.#api.call('GET', `user/events/${seg(hex)}`);
+    }
+    calendars(query = {}) {
+        return this.#api.page('user/calendars', query);
+    }
+    /** `GET /v1/user/events`. */
+    events(query = {}) {
+        return this.#api.page('user/events', query);
+    }
+    /** `GET /v1/user/events/range/{from}/{to}`: occurrences between two instants (RFC 3339, or Dates). */
+    range(from, to, query = {}) {
+        const iso = (t) => (t instanceof Date ? t.toISOString() : t);
+        return this.#api.page(`user/events/range/${seg(iso(from))}/${seg(iso(to))}`, query);
+    }
+    /** `GET /v1/user/events/upcoming`. */
+    upcoming(query = {}) {
+        return this.#api.page('user/events/upcoming', query);
+    }
+    /** `GET /v1/user/events/search/{text}`. */
+    search(text, query = {}) {
+        return this.#api.page(`user/events/search/${seg(text)}`, query);
+    }
+    /** `DELETE /v1/user/events/{hex}`. */
+    async deleteEvent(hex) {
+        await this.#api.call('DELETE', `user/events/${seg(hex)}`);
+    }
+}
+/**
+ * The workspace's API keys: `tenant.keys:read`, `tenant.keys:write` to
+ * rename, rotate and revoke. Making a key or changing its scopes is for a
+ * workspace owner signed in (a key is never an owner: `403`).
+ */
+export class Keys {
+    #api;
+    constructor(api) {
+        this.#api = api;
+    }
+    /** `GET /v1/tenant/keys`, `.../active` or `.../expired`. */
+    list(query = {}) {
+        const { state, ...rest } = query;
+        return this.#api.page(state ? `tenant/keys/${state}` : 'tenant/keys', rest);
+    }
+    /** `GET /v1/tenant/keys/{hex}`: name, prefix, scopes, dates (never the hash). */
+    get(hex) {
+        return this.#api.call('GET', `tenant/keys/${seg(hex)}`);
+    }
+    /** `PATCH /v1/tenant/keys/{hex}/name`. */
+    async rename(hex, name) {
+        await this.#api.call('PATCH', `tenant/keys/${seg(hex)}/name`, { body: { name } });
+    }
+    /**
+     * A new secret for key `hex` (`PATCH /v1/tenant/keys/{hex}/hash`): makes a
+     * random key, stores its hash and returns it. The old secret stops working
+     * at once (also for this client, if it is the key in use: make a new Api
+     * with the returned key); the key keeps its hex, name and scopes, and its
+     * prefix becomes the new key's (servers before ADK-MAIL-001 v52 ignore
+     * `prefix` and keep the old one).
+     */
+    async rotate(hex) {
+        const made = await createKey();
+        await this.#api.call('PATCH', `tenant/keys/${seg(hex)}/hash`, { body: { hash: made.hash, prefix: made.prefix } });
+        return made.key;
+    }
+    /** `DELETE /v1/tenant/keys/{hex}`: deletes the key; it stops working at once. */
+    async delete(hex) {
+        await this.#api.call('DELETE', `tenant/keys/${seg(hex)}`);
+    }
+}

package/dist/api/index.d.ts

@@ -0,0 +1,10 @@
+export { Api, CalendarApi, ContactsApi, Keys, MailApi, Mailboxes, ROOT, User } from './api.js';
+export type { ApiOptions, CallOptions, Folder, Query } from './api.js';
+export { createKey, hashKey } from './key.js';
+export type { NewKey } from './key.js';
+export type * from './model.js';
+export { AdukiError, LimitError, NetworkError, ProtocolError, RateLimitedError, ServerError, StepUpError, SyncResetError, UnauthorizedError, refusal, retryAfter, } from '../errors.js';
+export type { NetworkErrorOptions, Refused } from '../errors.js';
+export { kinds } from '../envelope.js';
+export { CORE, Jmap, JmapError, MAIL, SUBMISSION, USING } from '../jmap.js';
+export type { Invocation, JmapSession, Uploaded } from '../jmap.js';

package/dist/api/index.js

@@ -0,0 +1,9 @@
+// sdk/api (published on npm as `@adukilabs/sdk`): the client for programs
+// that use an Aduki API key (`Authorization: Key <key>`) on Aduki Mail's
+// REST API and JMAP. Only the core it needs (errors, envelope, http, jmap)
+// comes with it: no sign-in, session, browser storage or DPoP.
+export { Api, CalendarApi, ContactsApi, Keys, MailApi, Mailboxes, ROOT, User } from './api.js';
+export { createKey, hashKey } from './key.js';
+export { AdukiError, LimitError, NetworkError, ProtocolError, RateLimitedError, ServerError, StepUpError, SyncResetError, UnauthorizedError, refusal, retryAfter, } from '../errors.js';
+export { kinds } from '../envelope.js';
+export { CORE, Jmap, JmapError, MAIL, SUBMISSION, USING } from '../jmap.js';

package/dist/api/key.d.ts

@@ -0,0 +1,16 @@
+/** A new key: the raw value to keep secret, and what the server stores. */
+export interface NewKey {
+    /** the raw key, sent as `Authorization: Key <key>`; shown once, never sent to the server when created */
+    key: string;
+    /** SHA-256 of the key as lowercase hex (what the server stores) */
+    hash: string;
+    /** the first 16 characters of the key (the server's lookup index, not a secret by itself) */
+    prefix: string;
+}
+/** SHA-256 of `key` (its UTF-8 bytes) as lowercase hex, as the server hashes it. */
+export declare function hashKey(key: string): Promise<string>;
+/**
+ * A fresh random key (`adk_` and 32 random bytes as hex) with its hash and
+ * prefix. `random` fills the bytes (default `crypto.getRandomValues`).
+ */
+export declare function createKey(random?: (bytes: Uint8Array<ArrayBuffer>) => Uint8Array): Promise<NewKey>;

package/dist/api/key.js

@@ -0,0 +1,16 @@
+// Making an API key on the client (Aduki Mail keeps only its SHA-256): the
+// raw key is random bytes, shown once; the server gets the hash and a short
+// prefix to find it by. Web platform APIs only (WebCrypto).
+const hex = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+/** SHA-256 of `key` (its UTF-8 bytes) as lowercase hex, as the server hashes it. */
+export async function hashKey(key) {
+    return hex(new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(key))));
+}
+/**
+ * A fresh random key (`adk_` and 32 random bytes as hex) with its hash and
+ * prefix. `random` fills the bytes (default `crypto.getRandomValues`).
+ */
+export async function createKey(random = (b) => crypto.getRandomValues(b)) {
+    const key = `adk_${hex(random(new Uint8Array(32)))}`;
+    return { key, hash: await hashKey(key), prefix: key.slice(0, 16) };
+}

package/dist/api/model.d.ts

@@ -0,0 +1,226 @@
+/** A list: page mode (`page`, `pages`) or cursor mode (`next`, when more follow). */
+export interface Page<T> {
+    items: T[];
+    total: number;
+    /** page mode: this page (from 1) */
+    page?: number;
+    /** page mode: the number of pages */
+    pages?: number;
+    /** cursor mode: pass as `after` for the next page; absent on the last one */
+    next?: string;
+}
+/**
+ * Which part of a list: `{page, limit}` (pages from 1) or `{after, limit}`
+ * (a cursor, the `next` of the page before). `limit` is 1 to 200 (default 50).
+ */
+export interface PageQuery {
+    page?: number;
+    after?: string;
+    limit?: number;
+}
+/** A message row of the mail lists. */
+export interface MessageRow {
+    hex: string;
+    uid: number;
+    subject?: string | null;
+    sender?: string | null;
+    size: number;
+    flags: (string | null)[];
+    thread?: string | null;
+    spam?: number | null;
+    internaldate: string;
+    preview?: string | null;
+    from?: unknown;
+    to: unknown;
+    cc: unknown;
+    bcc: unknown;
+    reply_to: unknown;
+    message_id?: string | null;
+    has_attachment: boolean;
+    mailbox: unknown;
+    [field: string]: unknown;
+}
+/** A thread row (`GET /v1/user/mail/threads`). */
+export interface ThreadRow {
+    thread: string;
+    subject?: string | null;
+    count: number;
+    unread: number;
+    latest: string;
+    mailbox: unknown;
+    [field: string]: unknown;
+}
+/** A mailbox row. */
+export interface MailboxRow {
+    hex: string;
+    name: string;
+    delimiter: string;
+    flags: unknown;
+    uidvalidity: number;
+    uidnext: number;
+    role?: string | null;
+    messages: number;
+    unread: number;
+    created: string;
+    [field: string]: unknown;
+}
+/** What changed in one mailbox since a modseq (`GET /v1/user/mail/changes`). */
+export interface MailChanges {
+    mailbox: string;
+    uidvalidity: number;
+    modseq: number;
+    /** the `uidvalidity` given is stale: sync the mailbox again from 0 */
+    reset: boolean;
+    /** more changes follow: ask again from `modseq` */
+    more: boolean;
+    created: MessageRow[];
+    updated: MessageRow[];
+    /** uids removed */
+    vanished: number[];
+    [field: string]: unknown;
+}
+/** A contact card. */
+export interface Card {
+    hex: string;
+    uid: string;
+    href: string;
+    etag: string;
+    /** the vCard text */
+    vcard: string;
+    name?: string | null;
+    emails: unknown[];
+    phones: unknown[];
+    groups: unknown[];
+    meta: unknown;
+    version: number;
+    size: number;
+    created: string;
+    updated: string;
+    photo: unknown;
+    [field: string]: unknown;
+}
+/** One page of the address book's change feed (`GET /v1/user/contacts/sync`). */
+export interface ContactChanges {
+    items: Card[];
+    /** hexes removed */
+    removed: unknown[];
+    /** pass as `since` next time */
+    token: string;
+    more: boolean;
+    /** the answer is the whole book, not changes */
+    full: boolean;
+    total?: number;
+    [field: string]: unknown;
+}
+/** A calendar. */
+export interface CalendarRow {
+    hex: string;
+    kind: string;
+    href: string;
+    name: string;
+    description?: string | null;
+    color?: string | null;
+    timezone: string;
+    components: string[];
+    transp: string;
+    created: string;
+    updated: string;
+    [field: string]: unknown;
+}
+/** An event (occurrences are expanded in a range). */
+export interface EventRow {
+    hex: string;
+    uid: string;
+    href: string;
+    etag: string;
+    /** the iCalendar object */
+    ical: string;
+    kind: string;
+    start?: string | null;
+    end?: string | null;
+    summary?: string | null;
+    description?: string | null;
+    location?: string | null;
+    attendees: unknown[];
+    organizer?: unknown;
+    status?: string | null;
+    sequence: number;
+    categories: string[];
+    rrule?: string | null;
+    recurring: boolean;
+    /** the calendar's hex */
+    calendar: string;
+    created: string;
+    updated: string;
+    [field: string]: unknown;
+}
+/** An API key as listed (never the key itself, nor its hash). */
+export interface KeyRow {
+    hex: string;
+    name: string;
+    prefix: string;
+    active: boolean;
+    expires?: string | null;
+    last?: string | null;
+    created: string;
+    tenant: unknown;
+    user?: unknown;
+    [field: string]: unknown;
+}
+/** An API key in full (`GET /v1/tenant/keys/{hex}`). */
+export interface KeyDetail {
+    hex: string;
+    name: string;
+    prefix: string;
+    scopes: (string | null)[] | null;
+    meta: unknown;
+    last?: string | null;
+    expires?: string | null;
+    revoked?: string | null;
+    created: string;
+    updated: string;
+    [field: string]: unknown;
+}
+/** The account a key acts as (`GET /v1/user`). */
+export interface Account {
+    hex: string;
+    email: string;
+    name: string;
+    tenant: unknown;
+    owner: boolean;
+    state: string;
+    timezone: string;
+    locale: string;
+    created: string;
+    [field: string]: unknown;
+}
+/** The account's profile (`GET /v1/user/profile`). */
+export interface Profile {
+    hex: string;
+    name: string;
+    email: string;
+    avatar?: {
+        hex: string;
+        updated: string;
+    } | null;
+    kind: string;
+    tenant?: {
+        hex: string;
+        name: string;
+        slug: string;
+    } | null;
+    role: {
+        label: string;
+        owner: boolean;
+    };
+    plan?: {
+        code: string;
+        state: string;
+    } | null;
+    storage: {
+        used: number;
+        limit?: number | null;
+    };
+    editable: boolean;
+    [field: string]: unknown;
+}