@adukilabs/sdk 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# @adukilabs/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Aduki API client for programs that use an API key: servers, scripts, scheduled jobs and workers. It calls Aduki Mail's REST API and JMAP with `Authorization: Key <key>`. There is no sign-in, no browser storage and no DPoP. It is written in TypeScript and ships as ES2022 modules with declarations. It uses web platform APIs only (`fetch`, WebCrypto) and has no dependencies. It runs on Node 20+, Deno, Bun and in workers. Apache 2.0.
+
+```sh
+npm install @adukilabs/sdk
+```
+
+## API keys
+
+A workspace owner makes an API key for the workspace and chooses its scopes. Each scope is written `user.<name>` (for example `user.mail:read`) or `tenant.<name>` (for example `tenant.keys:read`). A bare `mail:read` counts in both domains.
+
+What a key may do:
+- It holds only its scopes, and only while the owner who made it can still do the same.
+- A key with no scopes can do nothing.
+- A key never reaches the platform routes.
+- It acts as its owner's mail account.
+
+Keep the key secret: in an environment variable or a secret store, never in a web page.
+
+## Quick start
+
+```js
+import { Api } from '@adukilabs/sdk';
+
+const api = new Api({ key: process.env.ADUKI_API_KEY });
+
+const me = await api.user.profile();                       // users:read
+const inbox = await api.mail.list('inbox', { limit: 20 }); // mail:read
+for (const m of inbox.items) console.log(m.internaldate, m.subject);
+
+const hex = await api.mail.send({                          // mail:send
+  to: ['ada@example.com'],
+  subject: 'Report',
+  text: 'Done.',
+});
+```
+
+## What it covers
+
+Every call is on `https://mail.aduki.pro` (option `root` changes it). The scope a call needs is in brackets.
+
+| | Calls |
+|---|---|
+| `api.user` | `get` (`GET /v1/user`), `profile`, `keys` (the keys this account made), `aliases` [`users:read`, `aliases:read`] |
+| `api.mail` | `send` (plain text, with an `Idempotency-Key`) [`mail:send`]; `list(folder)` for `inbox`, `sent`, `draft`, `trash`, `starred`, `spam`; `get(hex)`, `unread`, `folder(name)`, `search`, `threads`, `thread`, `changes` [`mail:read`]; `flags`, `move`, `delete` [`mail:write`] |
+| `api.mailboxes` | `list`, `unread`, `search` [`mailbox:read`] |
+| `api.contacts` | `get(hex)`, `list`, `search`, `groups`, `group`, `sync` [`contacts:read`]; `delete` [`contacts:write`] |
+| `api.calendar` | `calendar(hex)`, `event(hex)`, `calendars`, `events`, `range`, `upcoming`, `search` [`calendars:read`]; `deleteEvent` [`calendars:write`] |
+| `api.keys` | the workspace's keys: `list` (all, `active`, `expired`), `get` [`tenant.keys:read`]; `rename`, `rotate` (a new secret, returned once), `delete` [`tenant.keys:write`] |
+| `api.jmap` | JMAP (RFC 8620, 8621) on the same key: `session`, `call`, `method`, `upload`, `download`. Signing in needs `mail:read`; `EmailSubmission/set` needs `mail:send` |
+| `api.call` | any other `user` or `tenant` route under `/v1`: `api.call('GET', 'tenant/domains')` |
+
+Lists take `{ page, limit }` (pages from 1) or `{ after, limit }` (a cursor), with a `limit` of 1 to 200 (default 50). They answer `{ items, total }` plus `page` and `pages`, or `next` when more items follow. `api.all(path)` goes through every page.
+
+Making a key and changing a key's scopes are only for a signed-in owner; a key gets `403` for both. `createKey()` makes a random key with its SHA-256 hash and prefix, as the server stores them.
+
+## Errors
+
+A refused call throws a typed error:
+
+| Answer | Error | What it means |
+|---|---|---|
+| `401` | `UnauthorizedError` | the key is unknown, expired or deleted |
+| `403 access.denied` | `NetworkError` | the key lacks the scope |
+| `429` | `RateLimitedError` | too many calls: 600 a minute per account, shared by its keys and sign-ins. `retryAfter` holds the seconds to wait |
+| `5xx` | `ServerError` | the server failed |
+
+The other failures are a `NetworkError` with `status`, `kind`, `message` and `details`. JMAP method errors are `JmapError`.
+
+## Not in this package
+
+The Aduki apps' own SDK (sign-in, sessions, the other services) is not published.

package/dist/api/api.d.ts

@@ -0,0 +1,223 @@
+import { Jmap } from '../jmap.js';
+import type * as model from './model.js';
+import type { Page, PageQuery } from './model.js';
+/** The mail host (REST under `/v1`, JMAP at the root). */
+export declare const ROOT = "https://mail.aduki.pro";
+export interface ApiOptions {
+    /** the API key, sent as `Authorization: Key <key>` */
+    key: string;
+    /** the mail host without `/v1` (default `https://mail.aduki.pro`) */
+    root?: string | undefined;
+    /** the transport (default global fetch) */
+    fetch?: typeof fetch | undefined;
+    /** a random id for Idempotency-Keys (default `crypto.randomUUID`) */
+    random?: (() => string) | undefined;
+}
+/** A query string: `undefined` values are left out. */
+export type Query = Record<string, string | number | boolean | undefined>;
+export interface CallOptions {
+    /** the query string */
+    query?: Query | undefined;
+    /** a JSON body */
+    body?: unknown;
+    /**
+     * The `Idempotency-Key` of a POST, PUT or PATCH: the server replays the
+     * first 2xx (or 422) answer to a retry with the same key for 24 hours.
+     */
+    idempotency?: string | undefined;
+    signal?: AbortSignal | undefined;
+}
+/** The mail folders with their own list route. */
+export type Folder = 'inbox' | 'sent' | 'draft' | 'trash' | 'starred' | 'spam';
+export declare class Api {
+    #private;
+    /** the JMAP client on the same key (mail: `u.mail:read`, sending: `u.mail:send`) */
+    readonly jmap: Jmap;
+    readonly user: User;
+    readonly mail: MailApi;
+    readonly mailboxes: Mailboxes;
+    readonly contacts: ContactsApi;
+    readonly calendar: CalendarApi;
+    readonly keys: Keys;
+    readonly random: () => string;
+    constructor(options: ApiOptions);
+    /**
+     * 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: string, init?: RequestInit): Promise<Response>;
+    /**
+     * 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`, ...).
+     */
+    call<T = any>(method: string, path: string, options?: CallOptions): Promise<T>;
+    /** `GET` of a list route with paging (see PageQuery). */
+    page<T>(path: string, query?: PageQuery | Query): Promise<Page<T>>;
+    /** Every item of a list route, following the cursor (`after`) page by page. */
+    all<T>(path: string, query?: Query & {
+        limit?: number;
+    }): AsyncGenerator<T>;
+}
+/** The account the key acts as. Scope `users:read`. */
+export declare class User {
+    #private;
+    constructor(api: Api);
+    /** `GET /v1/user`: the account. */
+    get(): Promise<model.Account>;
+    /** `GET /v1/user/profile`: name, address, workspace, role, plan, storage. */
+    profile(): Promise<model.Profile>;
+    /** `GET /v1/user/keys`: the API keys made by this account (never the keys themselves). */
+    keys(query?: PageQuery): Promise<Page<model.KeyRow>>;
+    /** `GET /v1/user/aliases` (scope `aliases:read`). */
+    aliases(): Promise<unknown>;
+}
+/** Mail over REST. Reading needs `mail:read`, changes `mail:write`, sending `mail:send`. */
+export declare class MailApi {
+    #private;
+    constructor(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`).
+     */
+    send(input: {
+        to: string | string[];
+        cc?: string[];
+        subject: string;
+        text: string;
+        from?: string;
+    }, options?: {
+        idempotency?: string;
+    }): Promise<string>;
+    /** `GET /v1/user/mail/<folder>`: the messages of a folder, newest first. */
+    list(folder: Folder, query?: PageQuery): Promise<Page<model.MessageRow>>;
+    /** `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: string): Promise<model.MessageRow>;
+    unread(query?: PageQuery): Promise<Page<model.MessageRow>>;
+    /** `GET /v1/user/mail/folder/{name}`: a mailbox by name. */
+    folder(name: string, query?: PageQuery): Promise<Page<model.MessageRow>>;
+    /** `GET /v1/user/mail/search/{text}`. */
+    search(text: string, query?: PageQuery): Promise<Page<model.MessageRow>>;
+    /** `GET /v1/user/mail/threads`. */
+    threads(query?: PageQuery): Promise<Page<model.ThreadRow>>;
+    /** `GET /v1/user/mail/thread/{thread}`: the messages of a thread. */
+    thread(thread: string, query?: PageQuery): Promise<Page<model.MessageRow>>;
+    /**
+     * `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: {
+        mailbox: string;
+        since?: number;
+        uidvalidity?: number;
+        limit?: number;
+    }): Promise<model.MailChanges>;
+    /** `PATCH /v1/user/mail/{hex}/flags`: adds and removes flags (`\\Seen`, `\\Flagged`, ...). */
+    flags(hex: string, change: {
+        add?: string[];
+        remove?: string[];
+    }): Promise<void>;
+    /** `PATCH /v1/user/mail/{hex}/mailbox`: moves a message to another mailbox (hex). */
+    move(hex: string, mailbox: string): Promise<{
+        hex: string;
+        mailbox: string;
+        uid: number;
+        modseq: number;
+    }>;
+    /** `DELETE /v1/user/mail/{hex}`. */
+    delete(hex: string): Promise<void>;
+}
+/** Mailboxes over REST: `mailbox:read`. */
+export declare class Mailboxes {
+    #private;
+    constructor(api: Api);
+    /** `GET /v1/user/mailbox`. */
+    list(query?: PageQuery): Promise<Page<model.MailboxRow>>;
+    /** `GET /v1/user/mailbox/unread`: the mailboxes with unread mail. */
+    unread(query?: PageQuery): Promise<Page<model.MailboxRow>>;
+    /** `GET /v1/user/mailbox/search/{text}`. */
+    search(text: string, query?: PageQuery): Promise<Page<model.MailboxRow>>;
+}
+/** The address book over REST: `contacts:read`, `contacts:write` to delete. */
+export declare class ContactsApi {
+    #private;
+    constructor(api: Api);
+    /** `GET /v1/user/contacts`. */
+    list(query?: PageQuery): Promise<Page<model.Card>>;
+    /** `GET /v1/user/contacts/{hex}`: one contact (scope `contacts:read`). */
+    get(hex: string): Promise<model.Card>;
+    /** `GET /v1/user/contacts/search/{text}`. */
+    search(text: string, query?: PageQuery): Promise<Page<model.Card>>;
+    /** `GET /v1/user/contacts/groups`. */
+    groups(query?: PageQuery): Promise<Page<unknown>>;
+    /** `GET /v1/user/contacts/group/{group}`: the cards of a group. */
+    group(group: string, query?: PageQuery): Promise<Page<model.Card>>;
+    /**
+     * `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?: {
+        since?: string;
+        limit?: number;
+    }): Promise<model.ContactChanges>;
+    /** `DELETE /v1/user/contacts/{hex}`. */
+    delete(hex: string): Promise<void>;
+}
+/** Calendars and events over REST: `calendars:read`, `calendars:write` to delete. */
+export declare class CalendarApi {
+    #private;
+    constructor(api: Api);
+    /** `GET /v1/user/calendars`. */
+    /** `GET /v1/user/calendars/{hex}`: one calendar (scope `calendars:read`). */
+    calendar(hex: string): Promise<model.CalendarRow>;
+    /** `GET /v1/user/events/{hex}`: one event with its `calendar` hex (scope `calendars:read`). */
+    event(hex: string): Promise<model.EventRow>;
+    calendars(query?: PageQuery): Promise<Page<model.CalendarRow>>;
+    /** `GET /v1/user/events`. */
+    events(query?: PageQuery): Promise<Page<model.EventRow>>;
+    /** `GET /v1/user/events/range/{from}/{to}`: occurrences between two instants (RFC 3339, or Dates). */
+    range(from: string | Date, to: string | Date, query?: PageQuery): Promise<Page<model.EventRow>>;
+    /** `GET /v1/user/events/upcoming`. */
+    upcoming(query?: PageQuery): Promise<Page<model.EventRow>>;
+    /** `GET /v1/user/events/search/{text}`. */
+    search(text: string, query?: PageQuery): Promise<Page<model.EventRow>>;
+    /** `DELETE /v1/user/events/{hex}`. */
+    deleteEvent(hex: string): Promise<void>;
+}
+/**
+ * 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 declare class Keys {
+    #private;
+    constructor(api: Api);
+    /** `GET /v1/tenant/keys`, `.../active` or `.../expired`. */
+    list(query?: PageQuery & {
+        state?: 'active' | 'expired';
+    }): Promise<Page<model.KeyRow>>;
+    /** `GET /v1/tenant/keys/{hex}`: name, prefix, scopes, dates (never the hash). */
+    get(hex: string): Promise<model.KeyDetail>;
+    /** `PATCH /v1/tenant/keys/{hex}/name`. */
+    rename(hex: string, name: string): Promise<void>;
+    /**
+     * 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).
+     */
+    rotate(hex: string): Promise<string>;
+    /** `DELETE /v1/tenant/keys/{hex}`: deletes the key; it stops working at once. */
+    delete(hex: string): Promise<void>;
+}