@adukilabs/sdk 0.0.0-stage → 0.1.2

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,476 @@
+/** 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;
+}
+/** The workspace's profile (`GET /v1/tenant`). */
+export interface TenantProfile {
+    hex: string;
+    name?: string;
+    slug?: string;
+    [field: string]: unknown;
+}
+/** A member row (`GET /v1/tenant/members`). */
+export interface MemberRow {
+    hex: string;
+    email: string;
+    name: string;
+    avatar?: string | null;
+    owner: boolean;
+    state: string;
+    last?: string | null;
+    created: string;
+    tenant: unknown;
+    role: unknown;
+    [field: string]: unknown;
+}
+/** An audit row. */
+export interface AuditRow {
+    hex: string;
+    action: string;
+    success: boolean;
+    reason?: string | null;
+    ip?: string | null;
+    agent?: string | null;
+    device?: unknown;
+    created: string;
+    actor?: unknown;
+    [field: string]: unknown;
+}
+/** An audit record with its `meta` (`GET /v1/tenant/view/audit/{hex}`). */
+export interface AuditDetail extends AuditRow {
+    meta?: unknown;
+}
+/** A usage row: `value` of `metric` in the billing `window`. */
+export interface UsageRow {
+    tenant: string;
+    metric: string;
+    window: string;
+    value: number;
+    ceiling: number;
+    [field: string]: unknown;
+}
+/** A quota in full. */
+export interface Quota {
+    tenant: string;
+    metric: string;
+    ceiling: number;
+    reason?: string | null;
+    granted?: string | null;
+    expires?: string | null;
+    created: string;
+    updated: string;
+    [field: string]: unknown;
+}
+/** A quota as listed. */
+export interface QuotaRow {
+    tenant: string;
+    metric: string;
+    ceiling: number;
+    expires?: string | null;
+    created: string;
+    [field: string]: unknown;
+}
+/** A domain to register. */
+export interface DomainCreate {
+    name: string;
+    /** `primary`, `sending`, `receiving` or `alias` */
+    kind?: string;
+    /** the DKIM selector */
+    selector?: string;
+    meta?: Record<string, unknown>;
+}
+/** A DNS record of a DKIM key: publish `value` as TXT at `name`. */
+export interface DkimRecord {
+    selector?: string;
+    name: string;
+    value: string;
+    [field: string]: unknown;
+}
+/** A domain in full: its status and the DNS records and snapshots. */
+export interface Domain {
+    hex: string;
+    tenant: string;
+    name: string;
+    kind: string;
+    /** `pending`, `verified`, `active`, `suspended` or `failed` */
+    status: string;
+    selector: string;
+    /** the active key's record (never the private key) */
+    dkim?: DkimRecord | null;
+    dkim_twin?: DkimRecord | null;
+    dkim_rotation?: {
+        pending?: DkimRecord | null;
+        retired?: unknown;
+    } | null;
+    spf: unknown;
+    dmarc: unknown;
+    mta_sts: unknown;
+    bimi: unknown;
+    meta: unknown;
+    verified?: string | null;
+    created: string;
+    updated: string;
+    [field: string]: unknown;
+}
+/** A domain as listed. */
+export interface DomainRow {
+    hex: string;
+    name: string;
+    kind: string;
+    status: string;
+    verified?: string | null;
+    created: string;
+    tenant: unknown;
+    [field: string]: unknown;
+}
+/** The state of a DKIM rotation. */
+export interface DkimRotation {
+    active?: DkimRecord | null;
+    /** the staged key: publish it, then confirm */
+    pending?: DkimRecord | null;
+    /** the previous record, safe to remove after `remove_after` */
+    retired?: {
+        selector: string;
+        name: string;
+        remove_after: string;
+    } | null;
+    [field: string]: unknown;
+}
+/** An alias of a member's mailbox. */
+export interface Alias {
+    address: string;
+    user: string;
+    created?: string;
+    [field: string]: unknown;
+}
+/** A spam rule to create. */
+export interface RuleCreate {
+    name: string;
+    /** `header.from`, `header.to`, `header.subject`, `header.received`, `envelope.from`, `envelope.to`, `body.text`, `body.html`, `body.url`, `attachment.name`, `attachment.mime` */
+    target: string;
+    pattern: string;
+    regex?: boolean;
+    /** -100 to 100: positive towards spam, negative towards ham */
+    score: number;
+    active?: boolean;
+    meta?: Record<string, unknown>;
+}
+/** A spam rule. */
+export interface Rule {
+    hex: string;
+    tenant?: unknown;
+    name: string;
+    target: string;
+    pattern: string;
+    regex: boolean;
+    score: number;
+    active: boolean;
+    meta?: unknown;
+    created: string;
+    updated?: string;
+    [field: string]: unknown;
+}
+/** A spam rule as listed. */
+export type RuleRow = Omit<Rule, 'meta' | 'updated'>;
+/** A webhook to create. */
+export interface WebhookCreate {
+    /** `https`, a public host, at most 500 characters */
+    url: string;
+    /** 16 to 128 characters; omitted, the server makes one */
+    secret?: string;
+    /** `mail.delivered`, `mail.bounced`, `mail.deferred`, `mail.complained` */
+    events?: string[];
+    domains?: string[];
+    active?: boolean;
+    meta?: Record<string, unknown>;
+}
+/** A webhook as listed. */
+export interface WebhookRow {
+    hex: string;
+    url: string;
+    active: boolean;
+    created: string;
+    tenant: unknown;
+    [field: string]: unknown;
+}
+/** A webhook (never its secret). */
+export interface Webhook extends WebhookRow {
+    events: unknown;
+    domains?: unknown;
+    meta?: unknown;
+    updated?: string;
+}
+/** `GET /v1/tenant/security`. */
+export interface SecurityStatus {
+    mtasts: unknown[];
+    tlsa: unknown[];
+    bimi: unknown[];
+    reports: unknown[];
+    [field: string]: unknown;
+}
+/** A mail service and whether this workspace may use it. */
+export interface MailService {
+    id: string;
+    name: string;
+    status: string;
+    description: string;
+    requirements: string[];
+    limits: string;
+    entitled: boolean;
+    reason?: string | null;
+    [field: string]: unknown;
+}
+/** An effective holiday of the workspace. */
+export interface Holiday {
+    date: string;
+    name: string;
+    kind: string;
+    source: string;
+    region?: string | null;
+    hex?: string;
+    verified?: string | null;
+    [field: string]: unknown;
+}
+/** A schedule template. */
+export interface ScheduleTemplate {
+    hex: string;
+    name: string;
+    zone: string;
+    rules: unknown[];
+    followers: number;
+    [field: string]: unknown;
+}
+/** A room or piece of equipment. */
+export interface ScheduleResource {
+    hex: string;
+    name: string;
+    kind: string;
+    capacity?: number | null;
+    schedule?: string | null;
+    retired: boolean | string | null;
+    created: string;
+    updated: string;
+    [field: string]: unknown;
+}

package/dist/api/space.d.ts

@@ -0,0 +1,147 @@
+import type { Activity, Checkin, Found, Member, Message, Page, Reply, Settings, SupportTicket, Task, Team } from '../space/model.js';
+import type { AudienceFetch } from './store.js';
+/** The Space REST root. */
+export declare const SPACE = "https://space.aduki.pro/v1";
+export interface SpaceApiOptions {
+    /** the REST root with `/v1` (default `https://space.aduki.pro/v1`) */
+    root?: string | undefined;
+}
+/** A query: undefined, null and false values are left out. */
+export type SpaceQuery = Record<string, string | number | boolean | null | undefined>;
+/** One page: `limit` 1 to 100, `after` the `next` of the previous page. */
+export interface SpacePage {
+    limit?: number;
+    after?: string;
+}
+/** A request of `call`. */
+export interface SpaceCall {
+    query?: SpaceQuery;
+    body?: unknown;
+    /** `Idempotency-Key` (a UUID) */
+    key?: string;
+    /** `If-Match`: the `etag` of the read the change is based on (stale: 409 `entity.conflict`) */
+    version?: string;
+    signal?: AbortSignal;
+}
+/** The filters of `tasks`. */
+export interface SpaceTaskFilters extends SpacePage {
+    status?: string;
+    client?: string;
+    team?: string;
+    orphaned?: boolean;
+    unbilled?: boolean;
+    q?: string;
+    archived?: boolean;
+}
+/** The fields of a new task (`title` required). */
+export interface SpaceTaskInput {
+    title: string;
+    description?: string;
+    priority?: string;
+    status?: string;
+    due?: string;
+    client?: string;
+    service?: string;
+    team?: string;
+    [field: string]: unknown;
+}
+/** The filters of `tickets`. */
+export interface SpaceTicketFilters extends SpacePage {
+    status?: string;
+    client?: string;
+    assignee?: string;
+    unassigned?: boolean;
+    breached?: boolean;
+    q?: string;
+}
+/** The fields of a new ticket (`client` and `title` required). */
+export interface SpaceTicketInput {
+    client: string;
+    title: string;
+    contact?: string;
+    body?: string;
+    priority?: string;
+    assignee?: string;
+    service?: string;
+    node?: string;
+    [field: string]: unknown;
+}
+/** The filters of `activity`. */
+export interface SpaceActivityFilters extends SpacePage {
+    entity?: string;
+    action?: string;
+    task?: string;
+}
+/** Aduki Space for a program (see the module notes for what it may not do). */
+export declare class SpaceApi {
+    #private;
+    readonly root: string;
+    constructor(session: AudienceFetch, options?: SpaceApiOptions);
+    /**
+     * One request to `path` (under `/v1`, segments already encoded): the
+     * envelope's `data`, the status and the `ETag`. A refusal throws the typed
+     * error of `errors.refusal`: `ClientRefusedError` on a strict or money
+     * route, `NetworkError 403 access.denied` for a bit the client lacks,
+     * `403 app.disabled` for a read-only workspace, `404` for a row it may not
+     * see, `RateLimitedError` with `retryAfter`.
+     */
+    call<T = any>(method: string, path: string, options?: SpaceCall): Promise<Reply<T>>;
+    /** One page of a list route (`items`, `next`). */
+    list<T = Record<string, unknown>>(path: string, query?: SpaceQuery, page?: SpacePage): Promise<Page<T>>;
+    /** Every item of a list route, page by page (`size` per page). */
+    all<T = Record<string, unknown>>(path: string, query?: SpaceQuery, size?: number): AsyncGenerator<T>;
+    /** The workspace settings, read only (`GET /v1/settings`); changing them is strict and refused to programs. */
+    settings(): Promise<Reply<Settings>>;
+    /** The workspace's teams (`GET /v1/teams`). */
+    teams(page?: SpacePage): Promise<Page<Team>>;
+    /** The members of the workspace: name, handle and teams (`GET /v1/staff/directory`). */
+    directory(page?: SpacePage): Promise<Page<Member>>;
+    /** The activity feed (`GET /v1/activity`); entries a program made carry `kind: "client"`. */
+    activity(filters?: SpaceActivityFilters): Promise<Page<Activity>>;
+    /** Tasks the client may see (`GET /v1/tasks`), filtered. */
+    tasks(filters?: SpaceTaskFilters): Promise<Page<Task>>;
+    /** A task and its version (`GET /v1/tasks/{id}`). */
+    task(task: string): Promise<Reply<Task>>;
+    /** Creates a task (`POST /v1/tasks`, `tasks.write`); a new Idempotency-Key unless `key` is given. */
+    createTask(input: SpaceTaskInput, options?: {
+        key?: string;
+    }): Promise<Reply<Task>>;
+    /** Changes a task (`PATCH /v1/tasks/{id}`); `version` guards against a lost update. */
+    updateTask(task: string, changes: Record<string, unknown>, options?: {
+        version?: string;
+    }): Promise<Reply<Task>>;
+    /** The check-ins of a task (`GET /v1/tasks/{id}/checkins`). */
+    checkins(task: string, page?: SpacePage): Promise<Page<Checkin>>;
+    /** Reports work on a task (`POST /v1/tasks/{id}/checkins`, `tasks.work`): `minutes` and an optional `proof` link. */
+    checkin(task: string, input: {
+        body: string;
+        minutes?: number;
+        proof?: string;
+    }, options?: {
+        key?: string;
+    }): Promise<Reply<Checkin>>;
+    /** Tickets the client may see (`GET /v1/tickets`, `tickets.read`), filtered. */
+    tickets(filters?: SpaceTicketFilters): Promise<Page<SupportTicket>>;
+    /** A ticket and its version (`GET /v1/tickets/{id}`). */
+    ticket(ticket: string): Promise<Reply<SupportTicket>>;
+    /** Opens a ticket (`POST /v1/tickets`, `tickets.write`). */
+    createTicket(input: SpaceTicketInput, options?: {
+        key?: string;
+    }): Promise<Reply<SupportTicket>>;
+    /** Changes a ticket (`PATCH /v1/tickets/{id}`): title, priority, status, assignee, service, node. */
+    updateTicket(ticket: string, changes: Record<string, unknown>, options?: {
+        version?: string;
+    }): Promise<Reply<SupportTicket>>;
+    /** The thread of a ticket, oldest first (`GET /v1/tickets/{id}/messages`). */
+    messages(ticket: string, page?: SpacePage): Promise<Page<Message>>;
+    /** Replies on a ticket (`POST /v1/tickets/{id}/messages`); `internal` makes it a staff note the client never sees. */
+    reply(ticket: string, body: string, options?: {
+        internal?: boolean;
+        key?: string;
+    }): Promise<Reply<Message>>;
+    /** Ids by query (`GET /v1/search`): `q` 1 to 200 characters, `entity` one collection, `limit` 1 to 50. */
+    search(q: string, options?: {
+        entity?: string;
+        limit?: number;
+    }): Promise<Found>;
+}