@adukilabs/sdk 0.1.1 → 0.1.2

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

package/dist/api/store.js

@@ -0,0 +1,352 @@
+// The workspace drive on Aduki Store for a program (machine access): the
+// metadata API on `store.aduki.pro/v1` and the content API on
+// `files.aduki.pro/v1`, with the DPoP-bound service-client token of
+// `IdClient` (audience `store`).
+//
+// What Store gives a service client (its docs, "Programs of a workspace"):
+// the workspace drive only, outside the Space folder, at the level of the
+// client's bits: `store.read` reads, `store.write` also creates, renames,
+// moves, trashes, restores and uploads. Never a drive of its own, never a
+// member's or a personal drive (their ids answer `404`). Shares, public
+// links, devices, reports, search, tickets and the change feed are for people:
+// `403 access.denied` with reason `client` (`ClientRefusedError`), so this
+// class has no calls for them.
+//
+// Uploads use the same chunking and hashing as the web Store module
+// (FastCDC 2020 cut points, BLAKE3 chunk and manifest hashes): begin a version
+// with the manifest, PUT the chunks the server lacks, commit; the same `key`
+// resumes an interrupted upload.
+import { failure, parse, rejection } from '../envelope.js';
+import { NetworkError, ProtocolError } from '../errors.js';
+import { url } from '../http.js';
+import { blob, manifest } from '../store/chunks.js';
+import * as model from '../store/model.js';
+/** Store's metadata API. */
+export const STORE = 'https://store.aduki.pro/v1';
+/** Store's content API (chunks, downloads). */
+export const FILES = 'https://files.aduki.pro/v1';
+const HEX = /^[0-9a-f]{16}$/;
+/** The workspace drive (see the module notes for what a program may not do). */
+export class StoreApi {
+    root;
+    files;
+    #fetch;
+    #sleep;
+    constructor(session, options = {}) {
+        this.#fetch = (input, init) => session.fetch('store', input, init);
+        this.root = (options.root ?? STORE).replace(/\/+$/, '');
+        this.files = (options.files ?? FILES).replace(/\/+$/, '');
+        this.#sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    }
+    /** The workspace drive's numbers: `owner` (the workspace), `cap`, `per`, `used` (`GET /v1/quota`). */
+    async quota() {
+        return (await this.call('GET', 'quota'));
+    }
+    /** The live children of folder `parent`, or of the drive root; with `trashed`, the trash (`GET /v1/folders`). */
+    async list(options = {}) {
+        const query = { parent: options.parent && id(options.parent, 'parent'), trashed: options.trashed ? true : undefined };
+        return model.listing(await this.call('GET', 'folders', { query }));
+    }
+    /** Folder `folder` (`GET /v1/folders/{id}`); one outside the workspace drive is `404`. */
+    async folder(folder) {
+        return model.folder(await this.call('GET', `folders/${id(folder, 'folder')}`));
+    }
+    /** File `file` (`GET /v1/files/{id}`). */
+    async file(file) {
+        return model.file(await this.call('GET', `files/${id(file, 'file')}`));
+    }
+    /** Creates a folder in `parent` (default the drive root) (`POST /v1/folders`, `store.write`); a name in use is 409. */
+    async createFolder(name, options = {}) {
+        const body = { name };
+        if (options.parent)
+            body.parent = id(options.parent, 'parent');
+        return model.folder(await this.call('POST', 'folders', { body }));
+    }
+    /** Creates an empty file to upload a version into (`POST /v1/files`). `upload` does this for you. */
+    async createFile(name, options = {}) {
+        const body = { name };
+        if (options.folder)
+            body.folder = id(options.folder, 'folder');
+        if (options.mime)
+            body.mime = options.mime;
+        return model.file(await this.call('POST', 'files', { body }));
+    }
+    /** Renames, moves (`parent: null` is the drive root), trashes or restores a folder (`PATCH /v1/folders/{id}`). */
+    async updateFolder(folder, change) {
+        const body = {};
+        if (change.name !== undefined)
+            body.name = change.name;
+        if (change.parent !== undefined)
+            body.parent = change.parent === null ? null : id(change.parent, 'parent');
+        if (change.trashed !== undefined)
+            body.trashed = change.trashed;
+        return model.folder(await this.call('PATCH', `folders/${id(folder, 'folder')}`, { body }));
+    }
+    /** Renames, moves (`folder: null` is the drive root), trashes or restores a file (`PATCH /v1/files/{id}`). */
+    async updateFile(file, change) {
+        const body = {};
+        if (change.name !== undefined)
+            body.name = change.name;
+        if (change.folder !== undefined)
+            body.folder = change.folder === null ? null : id(change.folder, 'folder');
+        if (change.trashed !== undefined)
+            body.trashed = change.trashed;
+        return model.file(await this.call('PATCH', `files/${id(file, 'file')}`, { body }));
+    }
+    /** Moves a folder and everything in it to the trash (`DELETE /v1/folders/{id}`). */
+    async trashFolder(folder) {
+        return model.folder(await this.call('DELETE', `folders/${id(folder, 'folder')}`));
+    }
+    /** Moves a file to the trash (`DELETE /v1/files/{id}`). */
+    async trashFile(file) {
+        return model.file(await this.call('DELETE', `files/${id(file, 'file')}`));
+    }
+    /** Takes a folder out of the trash. */
+    restoreFolder(folder) {
+        return this.updateFolder(folder, { trashed: false });
+    }
+    /** Takes a file out of the trash. */
+    restoreFile(file) {
+        return this.updateFile(file, { trashed: false });
+    }
+    // ---- versions and uploads ------------------------------------------
+    /** The versions of a file, newest first (`GET /v1/files/{id}/versions`). */
+    async versions(file) {
+        const list = await this.call('GET', `files/${id(file, 'file')}/versions`);
+        return (Array.isArray(list) ? list : []).map(model.version);
+    }
+    /** A version and the chunk positions still missing (`GET /v1/versions/{id}`). */
+    async version(version) {
+        return model.status(await this.call('GET', `versions/${id(version, 'version')}`));
+    }
+    /** Begins a version of `file` with its manifest (`POST /v1/files/{id}/versions`); `key` (a UUID) makes it idempotent. */
+    async begin(file, plan, options = {}) {
+        const fields = {
+            size: plan.size,
+            hash: plan.hash,
+            chunks: plan.chunks.map((c) => ({ hash: c.hash, size: c.size })),
+        };
+        if (options.base)
+            fields.base = id(options.base, 'base');
+        if (options.key)
+            fields.idempotency = options.key;
+        let body = JSON.stringify(fields);
+        if (options.attrs) {
+            // mtime_ns passes 2^53: written as an exact integer, not through a double
+            const ms = options.attrs.mtime instanceof Date ? options.attrs.mtime.getTime() : options.attrs.mtime;
+            if (!Number.isFinite(ms))
+                throw new TypeError('attrs.mtime is not a time');
+            const ns = (BigInt(Math.round(ms)) * 1000000n).toString();
+            body = `${body.slice(0, -1)},"attrs":{"mtime_ns":${ns},"exec":${options.attrs.exec ? 'true' : 'false'}}}`;
+        }
+        const headers = { 'Content-Type': 'application/json', Accept: 'application/json' };
+        if (options.key)
+            headers['Idempotency-Key'] = options.key;
+        const data = await this.#raw(url(this.root, `files/${id(file, 'file')}/versions`), { method: 'POST', headers, body }, 'Begin');
+        return { version: data.version, state: data.state, missing: data.missing ?? [], expires: data.expires ?? null, reserved: data.reserved ?? 0 };
+    }
+    /**
+     * 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.
+     */
+    async putChunk(owner, version, hash, bytes, signal) {
+        const target = url(this.files, `chunks/${id(owner, 'owner')}/${digest(hash)}`);
+        for (let attempt = 0;; attempt++) {
+            const init = {
+                method: 'PUT',
+                headers: { 'X-Version': id(version, 'version'), 'Content-Type': 'application/octet-stream' },
+                body: bytes instanceof Uint8Array ? new Uint8Array(bytes) : bytes,
+            };
+            if (signal)
+                init.signal = signal;
+            const response = await this.#fetch(target, init);
+            if (response.status === 201 || response.status === 204) {
+                await response.arrayBuffer().catch(() => { });
+                return response.status === 201;
+            }
+            const text = await response.text();
+            const error = failure(text);
+            if (response.status === 409 && error?.kind === 'chunk.busy' && attempt < 3) {
+                const wait = Number(error.details?.retry) || 5;
+                await this.#sleep(wait * 1000);
+                continue;
+            }
+            throw rejection(response, text, 'Chunk');
+        }
+    }
+    /** Commits a version (`POST /v1/files/{id}/commits`); chunks still missing are `409` with `details.missing`. */
+    async commit(file, version) {
+        return (await this.call('POST', `files/${id(file, 'file')}/commits`, { body: { version: id(version, 'version') } }));
+    }
+    /** Aborts an uncommitted version and frees its reservation (`DELETE /v1/files/{id}/versions/{version}`). */
+    async abort(file, version) {
+        return (await this.call('DELETE', `files/${id(file, 'file')}/versions/${id(version, 'version')}`));
+    }
+    /**
+     * 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.
+     */
+    async upload(content, options = {}) {
+        const source = blob(content);
+        let file;
+        let base = options.base;
+        if (options.file) {
+            file = await this.file(options.file);
+            base ??= file.version ?? undefined;
+        }
+        else {
+            const named = source.name;
+            const name = options.name ?? (typeof named === 'string' ? named : '');
+            if (!name)
+                throw new TypeError('upload needs a name or a file');
+            const place = { folder: options.folder ?? null };
+            const mime = options.mime ?? source.type;
+            if (mime)
+                place.mime = mime;
+            file = await this.createFile(name, place);
+        }
+        const owner = file.owner;
+        if (!owner)
+            throw new ProtocolError('The file has no owner');
+        const plan = options.manifest ?? (await manifest(source, (done) => options.progress?.({ phase: 'hash', done, total: source.size })));
+        const begin = { key: options.key ?? crypto.randomUUID() };
+        if (base)
+            begin.base = base;
+        if (options.attrs)
+            begin.attrs = options.attrs;
+        const begun = await this.begin(file.id, plan, begin);
+        if (begun.state === 'fast')
+            return { file, version: begun.version, state: 'ready', sent: 0 };
+        let sent = 0;
+        const total = begun.missing.reduce((n, i) => n + (plan.chunks[i]?.size ?? 0), 0);
+        const push = async (missing) => {
+            for (const index of missing) {
+                const chunk = plan.chunks[index];
+                if (!chunk)
+                    throw new ProtocolError(`The server asked for chunk ${index}, which the manifest does not have`);
+                options.signal?.throwIfAborted();
+                await this.putChunk(owner, begun.version, chunk.hash, source.slice(chunk.offset, chunk.offset + chunk.size), options.signal);
+                sent += chunk.size;
+                options.progress?.({ phase: 'send', done: sent, total: Math.max(total, sent) });
+            }
+        };
+        await push(begun.missing);
+        for (let round = 0;; round++) {
+            try {
+                const done = await this.commit(file.id, begun.version);
+                return { file, version: done.version, state: done.state, sent };
+            }
+            catch (error) {
+                const missing = error?.details;
+                if (round < 2 && error instanceof NetworkError && error.status === 409 && Array.isArray(missing?.missing)) {
+                    await push(missing.missing);
+                    continue;
+                }
+                throw error;
+            }
+        }
+    }
+    // ---- downloads and renditions -------------------------------------
+    /**
+     * 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).
+     */
+    async content(file, options = {}) {
+        const version = options.version ? `?version=${id(options.version, 'version')}` : '';
+        const headers = {};
+        if (options.range)
+            headers.Range = range(options.range);
+        if (options.etag)
+            headers['If-None-Match'] = options.etag.startsWith('"') ? options.etag : `"${options.etag}"`;
+        const init = { headers };
+        if (options.signal)
+            init.signal = options.signal;
+        const response = await this.#fetch(`${url(this.files, `files/${id(file, 'file')}/content`)}${version}`, init);
+        if (response.ok || response.status === 304)
+            return response;
+        throw rejection(response, await response.text(), 'Download');
+    }
+    /** The content of a file as a Blob (the whole file, or `range`). */
+    async download(file, options = {}) {
+        const response = await this.content(file, options);
+        if (response.status === 304)
+            throw new ProtocolError('Download answered 304: pass no etag to download');
+        return response.blob();
+    }
+    /** The renditions (thumbnails, posters, previews) of a version (`GET /v1/versions/{id}/media`). */
+    async media(version) {
+        const list = await this.call('GET', `versions/${id(version, 'version')}/media`);
+        return Array.isArray(list) ? list : [];
+    }
+    /** The bytes of a ready rendition (`GET /v1/derivatives/{id}/content` on the content host), or a `range` of them. */
+    async derivative(derivative, options = {}) {
+        const headers = {};
+        if (options.range)
+            headers.Range = range(options.range);
+        const init = { headers };
+        if (options.signal)
+            init.signal = options.signal;
+        const response = await this.#fetch(url(this.files, `derivatives/${id(derivative, 'derivative')}/content`), init);
+        if (response.ok)
+            return response;
+        throw rejection(response, await response.text(), 'Derivative');
+    }
+    // ---- any other route ----------------------------------------------
+    /**
+     * 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).
+     */
+    async call(method, path, options = {}) {
+        const params = new URLSearchParams();
+        for (const [k, v] of Object.entries(options.query ?? {}))
+            if (v !== undefined && v !== '')
+                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.signal)
+            init.signal = options.signal;
+        return this.#raw(`${url(this.root, clean)}${q ? `?${q}` : ''}`, init, `${method} /v1/${clean.split('?')[0]}`);
+    }
+    async #raw(target, init, what) {
+        const response = await this.#fetch(target, init);
+        const text = await response.text();
+        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`);
+        if (envelope.data === undefined)
+            throw new NetworkError(`Empty response from ${what}`, { status: response.status });
+        return envelope.data;
+    }
+}
+/** A public id (16 lowercase hex digits), or TypeError. */
+function id(value, what) {
+    if (!HEX.test(value))
+        throw new TypeError(`${what} is not an id (16 lowercase hex digits)`);
+    return value;
+}
+function digest(value) {
+    if (!/^[0-9a-f]{64}$/.test(value))
+        throw new TypeError('A chunk hash is 64 lowercase hex digits');
+    return value;
+}
+function range(r) {
+    if (!(Number.isInteger(r.start) && r.start >= 0) || (r.end !== undefined && !(Number.isInteger(r.end) && r.end >= r.start))) {
+        throw new TypeError('A range is whole byte offsets, start <= end');
+    }
+    return `bytes=${r.start}-${r.end ?? ''}`;
+}