@adukilabs/sdk 0.0.0-stage → 0.1.2

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;
+}

package/dist/api/store.d.ts

@@ -0,0 +1,181 @@
+import type { Content, Manifest } from '../store/chunks.js';
+import type { Begun, Derivative, FileEntry, Folder, Listing, Quota, Version, VersionStatus } from '../store/model.js';
+/** Store's metadata API. */
+export declare const STORE = "https://store.aduki.pro/v1";
+/** Store's content API (chunks, downloads). */
+export declare const FILES = "https://files.aduki.pro/v1";
+/** An authenticated fetch for one audience (`IdClient`). */
+export interface AudienceFetch {
+    fetch(audience: string, input: Request | string | URL, init?: RequestInit): Promise<Response>;
+}
+export interface StoreApiOptions {
+    /** the metadata root with `/v1` (default `https://store.aduki.pro/v1`) */
+    root?: string | undefined;
+    /** the content root with `/v1` (default `https://files.aduki.pro/v1`) */
+    files?: string | undefined;
+    /** waits `ms` milliseconds before retrying a busy chunk (default a timer; tests pass a fake) */
+    sleep?: ((ms: number) => Promise<void>) | undefined;
+}
+/** What `updateFolder` changes: `parent: null` moves to the drive root. */
+export interface FolderChange {
+    name?: string;
+    parent?: string | null;
+    trashed?: boolean;
+}
+/** What `updateFile` changes: `folder: null` moves to the drive root. */
+export interface FileChange {
+    name?: string;
+    folder?: string | null;
+    trashed?: boolean;
+}
+/** Client metadata of a version: modification time (a Date or milliseconds) and the executable bit. */
+export interface VersionAttrs {
+    mtime: Date | number;
+    exec: boolean;
+}
+/** Progress of an upload: hashing the content, then sending the missing chunks. */
+export interface UploadProgress {
+    phase: 'hash' | 'send';
+    done: number;
+    total: number;
+}
+export interface StoreUploadOptions {
+    /** an existing file to add a version to; without it a new file is created */
+    file?: string;
+    /** the new file's name (required without `file`; default the name of a `File`) */
+    name?: string;
+    /** the new file's folder (default the drive root) */
+    folder?: string | null;
+    /** the new file's type (default the Blob's type) */
+    mime?: string;
+    /** the version this edit started from (default the file's current version, when adding to `file`) */
+    base?: string;
+    /** a UUID: the same key (and content) resumes the same upload (default a new one) */
+    key?: string;
+    attrs?: VersionAttrs;
+    /** a manifest computed before (`manifest(content)`), to skip hashing again */
+    manifest?: Manifest;
+    progress?: (progress: UploadProgress) => void;
+    signal?: AbortSignal;
+}
+/** What an upload made: the file, the version and its state (`pending` while scanned, or `ready`). */
+export interface StoreUploaded {
+    file: FileEntry;
+    version: string;
+    state: string;
+    /** bytes sent (0 when the server already held every chunk) */
+    sent: number;
+}
+/** A download: the current version or `version`; `range` asks for bytes `start` to `end` (inclusive); `etag` for a `304`. */
+export interface StoreDownload {
+    version?: string;
+    range?: {
+        start: number;
+        end?: number;
+    };
+    etag?: string;
+    signal?: AbortSignal;
+}
+type Query = Record<string, string | number | boolean | undefined>;
+/** The workspace drive (see the module notes for what a program may not do). */
+export declare class StoreApi {
+    #private;
+    readonly root: string;
+    readonly files: string;
+    constructor(session: AudienceFetch, options?: StoreApiOptions);
+    /** The workspace drive's numbers: `owner` (the workspace), `cap`, `per`, `used` (`GET /v1/quota`). */
+    quota(): Promise<Quota>;
+    /** The live children of folder `parent`, or of the drive root; with `trashed`, the trash (`GET /v1/folders`). */
+    list(options?: {
+        parent?: string;
+        trashed?: boolean;
+    }): Promise<Listing>;
+    /** Folder `folder` (`GET /v1/folders/{id}`); one outside the workspace drive is `404`. */
+    folder(folder: string): Promise<Folder>;
+    /** File `file` (`GET /v1/files/{id}`). */
+    file(file: string): Promise<FileEntry>;
+    /** Creates a folder in `parent` (default the drive root) (`POST /v1/folders`, `store.write`); a name in use is 409. */
+    createFolder(name: string, options?: {
+        parent?: string | null;
+    }): Promise<Folder>;
+    /** Creates an empty file to upload a version into (`POST /v1/files`). `upload` does this for you. */
+    createFile(name: string, options?: {
+        folder?: string | null;
+        mime?: string;
+    }): Promise<FileEntry>;
+    /** Renames, moves (`parent: null` is the drive root), trashes or restores a folder (`PATCH /v1/folders/{id}`). */
+    updateFolder(folder: string, change: FolderChange): Promise<Folder>;
+    /** Renames, moves (`folder: null` is the drive root), trashes or restores a file (`PATCH /v1/files/{id}`). */
+    updateFile(file: string, change: FileChange): Promise<FileEntry>;
+    /** Moves a folder and everything in it to the trash (`DELETE /v1/folders/{id}`). */
+    trashFolder(folder: string): Promise<Folder>;
+    /** Moves a file to the trash (`DELETE /v1/files/{id}`). */
+    trashFile(file: string): Promise<FileEntry>;
+    /** Takes a folder out of the trash. */
+    restoreFolder(folder: string): Promise<Folder>;
+    /** Takes a file out of the trash. */
+    restoreFile(file: string): Promise<FileEntry>;
+    /** The versions of a file, newest first (`GET /v1/files/{id}/versions`). */
+    versions(file: string): Promise<Version[]>;
+    /** A version and the chunk positions still missing (`GET /v1/versions/{id}`). */
+    version(version: string): Promise<VersionStatus>;
+    /** Begins a version of `file` with its manifest (`POST /v1/files/{id}/versions`); `key` (a UUID) makes it idempotent. */
+    begin(file: string, plan: Manifest, options?: {
+        base?: string;
+        key?: string;
+        attrs?: VersionAttrs;
+    }): Promise<Begun>;
+    /**
+     * Sends one chunk of an open version (`PUT /v1/chunks/{owner}/{hash}` on
+     * the content host): true when stored, false when the drive already held
+     * it. A chunk being reclaimed (`409 chunk.busy`) is retried after the
+     * server's wait, up to three times.
+     */
+    putChunk(owner: string, version: string, hash: string, bytes: Uint8Array | Blob, signal?: AbortSignal): Promise<boolean>;
+    /** Commits a version (`POST /v1/files/{id}/commits`); chunks still missing are `409` with `details.missing`. */
+    commit(file: string, version: string): Promise<{
+        version: string;
+        state: string;
+    }>;
+    /** Aborts an uncommitted version and frees its reservation (`DELETE /v1/files/{id}/versions/{version}`). */
+    abort(file: string, version: string): Promise<{
+        released: number;
+    }>;
+    /**
+     * Uploads `content` as a new file (`name`, `folder`) or as a new version of
+     * `file`: hashes it, begins the version, sends the missing chunks and
+     * commits. Run again with the same `key` to resume: only the chunks the
+     * server still lacks are sent. The version is `pending` until scanned.
+     */
+    upload(content: Content, options?: StoreUploadOptions): Promise<StoreUploaded>;
+    /**
+     * The content of a file as a Response (`GET /v1/files/{id}/content` on the
+     * content host): `200`, `206` for a range, `304` for an unchanged `etag`;
+     * `ETag`, `Content-Type`, `Content-Range` headers. A failure throws (`416`
+     * for a range past the end).
+     */
+    content(file: string, options?: StoreDownload): Promise<Response>;
+    /** The content of a file as a Blob (the whole file, or `range`). */
+    download(file: string, options?: StoreDownload): Promise<Blob>;
+    /** The renditions (thumbnails, posters, previews) of a version (`GET /v1/versions/{id}/media`). */
+    media(version: string): Promise<Derivative[]>;
+    /** The bytes of a ready rendition (`GET /v1/derivatives/{id}/content` on the content host), or a `range` of them. */
+    derivative(derivative: string, options?: {
+        range?: {
+            start: number;
+            end?: number;
+        };
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    /**
+     * Any metadata route under `/v1` (`path` without it): returns the
+     * envelope's `data`; a refusal throws the typed error of `errors.refusal`
+     * (`ClientRefusedError` for a route that is not for programs).
+     */
+    call<T = any>(method: string, path: string, options?: {
+        query?: Query;
+        body?: unknown;
+        signal?: AbortSignal;
+    }): Promise<T>;
+}
+export {};