@adukilabs/sdk 0.0.0-stage → 0.1.1

package/dist/jmap.js

@@ -0,0 +1,180 @@
+// JMAP (RFC 8620) over the authenticated fetch, shared by the services that
+// speak it (mail, contacts; `sdk/jmap`): the session resource, batched
+// method calls with back-references, and blob upload and download
+// (aduki-kt net/http/jmap.kt). JMAP ids are the REST hexes: an `Email` id is
+// a message hex, a `Mailbox` id a mailbox hex.
+import { rejection } from './envelope.js';
+import { AdukiError, ProtocolError } from './errors.js';
+import { url } from './http.js';
+export const CORE = 'urn:ietf:params:jmap:core';
+export const MAIL = 'urn:ietf:params:jmap:mail';
+export const SUBMISSION = 'urn:ietf:params:jmap:submission';
+/** Aduki body reading: `Email/get` takes `aduki:bodyMode` (ADK-MAIL-001 section 1.4, v47). */
+export const READING = 'urn:aduki:params:jmap:reading';
+/** Core and mail: enough for `Mailbox`, `Email` and `Thread`. */
+export const USING = Object.freeze([CORE, MAIL]);
+/**
+ * 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 class JmapError extends AdukiError {
+    constructor(method, error, id = '') {
+        const type = String(error?.type ?? 'serverFail');
+        const description = String(error?.description ?? '');
+        super(`${method} refused${id ? ` ${id}` : ''}: ${type}${description ? ` (${description})` : ''}`);
+        this.type = type;
+        this.description = description;
+        this.properties = Array.isArray(error?.properties) ? error.properties.map(String) : [];
+        this.method = method;
+        this.id = id;
+    }
+}
+export const ROOT = 'https://mail.aduki.pro';
+export class Jmap {
+    #session;
+    #root;
+    #audience;
+    #cached = null;
+    constructor(options) {
+        this.#session = options.session;
+        this.#root = (options.root ?? ROOT).replace(/\/+$/, '');
+        this.#audience = options.audience ?? 'mail';
+    }
+    /** Sends an authenticated request to the mail host (a path or an absolute URL). */
+    fetch(input, init) {
+        const target = /^https?:\/\//.test(input) ? input : url(this.#root, input.replace(/^\/+/, ''));
+        return this.#session.fetch(this.#audience, target, init);
+    }
+    /** The session (`GET /jmap/session`), fetched once; `refresh` fetches it again. */
+    session(refresh = false) {
+        if (!this.#cached || refresh) {
+            const pending = this.#load();
+            this.#cached = pending;
+            pending.catch(() => {
+                if (this.#cached === pending)
+                    this.#cached = null;
+            });
+        }
+        return this.#cached;
+    }
+    async #load() {
+        const data = await object(await this.fetch('jmap/session'), 'JMAP session');
+        const primary = data.primaryAccounts ?? {};
+        const account = String(primary[MAIL] ?? primary[CORE] ?? '');
+        if (!account)
+            throw new ProtocolError('JMAP session has no mail account');
+        const capabilities = data.capabilities && typeof data.capabilities === 'object' ? data.capabilities : {};
+        const field = (name) => {
+            const value = data[name];
+            if (typeof value !== 'string' || !value)
+                throw new ProtocolError(`JMAP session has no ${name}`);
+            return new URL(value, `${this.#root}/`).href.replace(/%7B/g, '{').replace(/%7D/g, '}');
+        };
+        return {
+            account,
+            api: field('apiUrl'),
+            upload: field('uploadUrl'),
+            download: field('downloadUrl'),
+            eventSource: typeof data.eventSourceUrl === 'string' ? field('eventSourceUrl') : '',
+            capabilities: Object.keys(capabilities),
+            limits: capabilities[CORE] && typeof capabilities[CORE] === 'object' ? { ...capabilities[CORE] } : {},
+            reading: READING in capabilities,
+        };
+    }
+    /** The primary mail account id. */
+    async account() {
+        return (await this.session()).account;
+    }
+    /**
+     * 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.
+     */
+    async call(calls, using = USING) {
+        const session = await this.session();
+        const body = JSON.stringify({ using: [...using], methodCalls: calls });
+        const response = await this.fetch(session.api, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body });
+        const data = await object(response, 'JMAP request');
+        if (!Array.isArray(data.methodResponses))
+            throw new ProtocolError('JMAP reply has no methodResponses');
+        return data.methodResponses.map((item, i) => {
+            if (!Array.isArray(item) || typeof item[0] !== 'string' || !item[1] || typeof item[1] !== 'object') {
+                throw new ProtocolError(`JMAP method response ${i} is malformed`);
+            }
+            const [name, args, id] = item;
+            if (name === 'error') {
+                const call = calls.find((c) => c[2] === id);
+                throw new JmapError(call?.[0] ?? 'JMAP', args);
+            }
+            return [name, args, String(id ?? '')];
+        });
+    }
+    /**
+     * Runs one method with `accountId` set and returns its arguments (the
+     * first response with the call id; implicit responses are dropped).
+     */
+    async method(name, args = {}, using = USING) {
+        const accountId = await this.account();
+        const replies = await this.call([[name, { accountId, ...args }, '0']], using);
+        const reply = replies.find((r) => r[2] === '0');
+        if (!reply)
+            throw new ProtocolError(`JMAP reply has no response to ${name}`);
+        return reply[1];
+    }
+    /** Uploads `data` as a blob of `type` (RFC 8620 section 6.1). */
+    async upload(data, type = 'application/octet-stream') {
+        const session = await this.session();
+        const target = session.upload.replace('{accountId}', encodeURIComponent(session.account));
+        const body = data instanceof Uint8Array ? new Uint8Array(data) : data;
+        const response = await this.fetch(target, { method: 'POST', headers: { 'Content-Type': type || 'application/octet-stream' }, body });
+        const out = await object(response, 'JMAP upload');
+        if (typeof out.blobId !== 'string' || !out.blobId)
+            throw new ProtocolError('JMAP upload answer has no blobId');
+        return { blob: out.blobId, type: String(out.type ?? type), size: Number(out.size) || 0 };
+    }
+    /**
+     * 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`).
+     */
+    async download(blob, options = {}) {
+        const session = await this.session();
+        const target = session.download
+            .replace('{accountId}', encodeURIComponent(session.account))
+            .replace('{blobId}', encodeURIComponent(blob))
+            .replace('{name}', encodeURIComponent(options.name || 'blob'))
+            .replace('{type}', encodeURIComponent(options.type || 'application/octet-stream'));
+        const response = await this.fetch(target);
+        if (!response.ok)
+            await refuse(response, 'JMAP download');
+        return response;
+    }
+}
+/** The JSON object of a 2xx answer; a failure throws (see refuse). */
+async function object(response, what) {
+    if (!response.ok)
+        await refuse(response, what);
+    const text = await response.text();
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new ProtocolError(`${what} answer is not JSON`);
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new ProtocolError(`${what} answer is not a JSON object`);
+    return value;
+}
+/**
+ * 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 async function refuse(response, what) {
+    const text = await response.text().catch(() => '');
+    throw rejection(response, text, what, { problem: true });
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@adukilabs/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Aduki API client for programs that use API keys (Authorization: Key): Aduki Mail, Contacts and Calendar over REST and JMAP. TypeScript, web platform APIs only, no dependencies; Node 20+, Deno, Bun, workers.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "main": "./dist/api/index.js",
+  "types": "./dist/api/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/api/index.d.ts",
+      "default": "./dist/api/index.js"
+    },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "default": "./dist/api/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adukilabs/ts.git"
+  },
+  "keywords": [
+    "aduki",
+    "api",
+    "mail",
+    "jmap",
+    "calendar",
+    "contacts"
+  ]
+}