@adukilabs/sdk 0.1.1 → 0.1.2

package/dist/api/model.d.ts

@@ -224,3 +224,253 @@ export interface Profile {
     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>;
+}

package/dist/api/space.js

@@ -0,0 +1,218 @@
+// Aduki Space for a program of the workspace (machine access), with the
+// DPoP-bound service-client token of `IdClient` (audience `space`). The same
+// transport rules as the web Space module: the envelope, keyset lists with an
+// opaque cursor, `Idempotency-Key` on creation, `ETag` / `If-Match` on edits.
+//
+// What Space gives a service client (its docs, "Programs of the workspace"):
+// every route that is neither strict nor money, within the bits its grant
+// gives (`space.use` and the route's bit, for example `tasks.write`,
+// `tickets.write`), seeing the rows a person with those bits and no team
+// would see. Refused with `403 access.denied`, reason `client`
+// (`ClientRefusedError`): refunds, charges, payouts, rails and gateways,
+// staff management and payroll, node management, settings changes, hooks,
+// endpoints and exports. The activity feed marks what a program did with
+// `kind: "client"`.
+import { parse, rejection } from '../envelope.js';
+import { ProtocolError } from '../errors.js';
+import { url } from '../http.js';
+/** The Space REST root. */
+export const SPACE = 'https://space.aduki.pro/v1';
+const HEX = /^[0-9a-f]{16}$/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Aduki Space for a program (see the module notes for what it may not do). */
+export class SpaceApi {
+    root;
+    #fetch;
+    constructor(session, options = {}) {
+        this.#fetch = (input, init) => session.fetch('space', input, init);
+        this.root = (options.root ?? SPACE).replace(/\/+$/, '');
+    }
+    // ---- transport -------------------------------------------------------
+    /**
+     * 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`.
+     */
+    async call(method, path, options = {}) {
+        const params = new URLSearchParams();
+        for (const [k, v] of Object.entries(options.query ?? {}))
+            if (v !== undefined && v !== null && v !== false)
+                params.set(k, String(v));
+        const q = params.toString();
+        const clean = path.replace(/^\/+/, '');
+        const headers = { Accept: 'application/json' };
+        const init = { method, headers };
+        if (options.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            init.body = JSON.stringify(options.body);
+        }
+        if (options.key !== undefined) {
+            if (!UUID.test(options.key))
+                throw new TypeError('An Idempotency-Key is a UUID');
+            headers['Idempotency-Key'] = options.key;
+        }
+        if (options.version !== undefined)
+            headers['If-Match'] = options.version === '*' || options.version.startsWith('"') ? options.version : `"${options.version}"`;
+        if (options.signal)
+            init.signal = options.signal;
+        const response = await this.#fetch(`${url(this.root, clean)}${q ? `?${q}` : ''}`, init);
+        const text = await response.text();
+        const what = `${method} /v1/${clean.split('?')[0]}`;
+        if (!response.ok)
+            throw rejection(response, text, what);
+        const envelope = parse(text);
+        if (!envelope || envelope.success !== true)
+            throw new ProtocolError(`${what}: the answer is not a success envelope`);
+        const tag = response.headers.get('ETag');
+        return { data: (envelope.data ?? null), status: response.status, etag: tag ? tag.replace(/^W\//, '').replace(/^"|"$/g, '') : null };
+    }
+    /** One page of a list route (`items`, `next`). */
+    async list(path, query = {}, page = {}) {
+        if (page.limit !== undefined && !(Number.isInteger(page.limit) && page.limit >= 1 && page.limit <= 100))
+            throw new TypeError('limit is 1 to 100');
+        const { data } = await this.call('GET', path, { query: { ...query, limit: page.limit, after: page.after } });
+        if (!data || !Array.isArray(data.items))
+            throw new ProtocolError(`${path}: a list without items`);
+        return { items: data.items, next: typeof data.next === 'string' && data.next ? data.next : null };
+    }
+    /** Every item of a list route, page by page (`size` per page). */
+    async *all(path, query = {}, size = 100) {
+        let after;
+        const seen = new Set();
+        for (;;) {
+            const page = await this.list(path, query, after ? { limit: size, after } : { limit: size });
+            yield* page.items;
+            if (!page.next)
+                return;
+            if (seen.has(page.next))
+                throw new ProtocolError(`${path}: cursor repeated`);
+            seen.add(page.next);
+            after = page.next;
+        }
+    }
+    // ---- workspace -------------------------------------------------------
+    /** The workspace settings, read only (`GET /v1/settings`); changing them is strict and refused to programs. */
+    settings() {
+        return this.call('GET', 'settings');
+    }
+    /** The workspace's teams (`GET /v1/teams`). */
+    teams(page = {}) {
+        return this.list('teams', {}, page);
+    }
+    /** The members of the workspace: name, handle and teams (`GET /v1/staff/directory`). */
+    directory(page = {}) {
+        return this.list('staff/directory', {}, page);
+    }
+    /** The activity feed (`GET /v1/activity`); entries a program made carry `kind: "client"`. */
+    activity(filters = {}) {
+        const { limit, after, ...query } = filters;
+        if (query.task)
+            hex(query.task, 'task');
+        return this.list('activity', query, paging(limit, after));
+    }
+    // ---- tasks and check-ins -----------------------------------------
+    /** Tasks the client may see (`GET /v1/tasks`), filtered. */
+    tasks(filters = {}) {
+        const { limit, after, ...query } = filters;
+        if (query.client)
+            hex(query.client, 'client');
+        if (query.team)
+            hex(query.team, 'team');
+        if (query.q === '')
+            delete query.q;
+        return this.list('tasks', query, paging(limit, after));
+    }
+    /** A task and its version (`GET /v1/tasks/{id}`). */
+    task(task) {
+        return this.call('GET', `tasks/${hex(task, 'task')}`);
+    }
+    /** Creates a task (`POST /v1/tasks`, `tasks.write`); a new Idempotency-Key unless `key` is given. */
+    createTask(input, options = {}) {
+        return this.call('POST', 'tasks', { body: input, key: options.key ?? crypto.randomUUID() });
+    }
+    /** Changes a task (`PATCH /v1/tasks/{id}`); `version` guards against a lost update. */
+    updateTask(task, changes, options = {}) {
+        return this.call('PATCH', `tasks/${hex(task, 'task')}`, versioned({ body: changes }, options.version));
+    }
+    /** The check-ins of a task (`GET /v1/tasks/{id}/checkins`). */
+    checkins(task, page = {}) {
+        return this.list(`tasks/${hex(task, 'task')}/checkins`, {}, page);
+    }
+    /** Reports work on a task (`POST /v1/tasks/{id}/checkins`, `tasks.work`): `minutes` and an optional `proof` link. */
+    checkin(task, input, options = {}) {
+        const minutes = input.minutes ?? 0;
+        if (!Number.isInteger(minutes) || minutes < 0)
+            throw new TypeError('minutes is a whole number, not negative');
+        const body = { body: input.body, minutes };
+        if (input.proof !== undefined)
+            body.proof = input.proof;
+        return this.call('POST', `tasks/${hex(task, 'task')}/checkins`, { body, key: options.key ?? crypto.randomUUID() });
+    }
+    // ---- tickets -------------------------------------------------------
+    /** Tickets the client may see (`GET /v1/tickets`, `tickets.read`), filtered. */
+    tickets(filters = {}) {
+        const { limit, after, ...query } = filters;
+        if (query.client)
+            hex(query.client, 'client');
+        if (query.assignee)
+            hex(query.assignee, 'assignee');
+        if (query.q === '')
+            delete query.q;
+        return this.list('tickets', query, paging(limit, after));
+    }
+    /** A ticket and its version (`GET /v1/tickets/{id}`). */
+    ticket(ticket) {
+        return this.call('GET', `tickets/${hex(ticket, 'ticket')}`);
+    }
+    /** Opens a ticket (`POST /v1/tickets`, `tickets.write`). */
+    createTicket(input, options = {}) {
+        return this.call('POST', 'tickets', { body: input, key: options.key ?? crypto.randomUUID() });
+    }
+    /** Changes a ticket (`PATCH /v1/tickets/{id}`): title, priority, status, assignee, service, node. */
+    updateTicket(ticket, changes, options = {}) {
+        return this.call('PATCH', `tickets/${hex(ticket, 'ticket')}`, versioned({ body: changes }, options.version));
+    }
+    /** The thread of a ticket, oldest first (`GET /v1/tickets/{id}/messages`). */
+    messages(ticket, page = {}) {
+        return this.list(`tickets/${hex(ticket, 'ticket')}/messages`, {}, page);
+    }
+    /** Replies on a ticket (`POST /v1/tickets/{id}/messages`); `internal` makes it a staff note the client never sees. */
+    reply(ticket, body, options = {}) {
+        return this.call('POST', `tickets/${hex(ticket, 'ticket')}/messages`, {
+            body: { body, internal: options.internal ?? false },
+            key: options.key ?? crypto.randomUUID(),
+        });
+    }
+    // ---- search ----------------------------------------------------------
+    /** Ids by query (`GET /v1/search`): `q` 1 to 200 characters, `entity` one collection, `limit` 1 to 50. */
+    async search(q, options = {}) {
+        const text = q.trim();
+        if (text.length < 1 || text.length > 200)
+            throw new TypeError('q is 1 to 200 characters');
+        if (options.limit !== undefined && !(Number.isInteger(options.limit) && options.limit >= 1 && options.limit <= 50))
+            throw new TypeError('limit is 1 to 50');
+        const { data } = await this.call('GET', 'search', { query: { q: text, entity: options.entity, limit: options.limit } });
+        return { items: data?.items ?? [], source: String(data?.source ?? ''), stale: Boolean(data?.stale) };
+    }
+}
+function hex(value, what) {
+    if (!HEX.test(value))
+        throw new TypeError(`${what} is not an id (16 lowercase hex digits)`);
+    return value;
+}
+function paging(limit, after) {
+    const out = {};
+    if (limit !== undefined)
+        out.limit = limit;
+    if (after !== undefined)
+        out.after = after;
+    return out;
+}
+function versioned(options, version) {
+    if (version !== undefined)
+        options.version = version;
+    return options;
+}