@adukilabs/sdk 0.1.1 → 0.1.2

package/dist/store/chunks.js

@@ -0,0 +1,63 @@
+// The manifest of a file as Store declares it (ADK-STORAGE-001 section 3.0,
+// the Store docs "Uploading"): the chunk list from the FastCDC cut points,
+// each chunk named by the BLAKE3 of its bytes, and the manifest hash, the
+// BLAKE3 over `chunk hash (32 bytes) || chunk size (u32 little endian)` in
+// order. Reads the content a window at a time, so a large Blob is never held
+// whole in memory.
+import { blake3, hex } from './blake3.js';
+import { MAX, cut } from './cdc.js';
+/** `content` as a Blob (bytes are copied once). */
+export function blob(content) {
+    if (content instanceof Blob)
+        return content;
+    return new Blob([content instanceof Uint8Array ? new Uint8Array(content) : content]);
+}
+const READ = 8 * 1024 * 1024;
+/** The manifest of `content`; `progress` is called with the bytes read so far. */
+export async function manifest(content, progress) {
+    const source = blob(content);
+    const total = source.size;
+    const chunks = [];
+    if (total === 0)
+        return { size: 0, hash: hex(blake3(new Uint8Array(0))), chunks };
+    if (total <= MAX) {
+        const bytes = new Uint8Array(await source.arrayBuffer());
+        chunks.push({ offset: 0, size: total, hash: hex(blake3(bytes)) });
+        progress?.(total);
+        return { size: total, hash: seal(chunks), chunks };
+    }
+    // A window of unread bytes; a cut needs MAX bytes ahead (or the end).
+    let buffer = new Uint8Array(0);
+    let start = 0; // file offset of buffer[0]
+    let loaded = 0; // file offset after the buffer
+    let pos = 0; // offset in buffer of the next chunk
+    while (start + pos < total) {
+        if (buffer.length - pos < MAX && loaded < total) {
+            const next = new Uint8Array(await source.slice(loaded, Math.min(total, loaded + READ)).arrayBuffer());
+            const merged = new Uint8Array(buffer.length - pos + next.length);
+            merged.set(buffer.subarray(pos), 0);
+            merged.set(next, buffer.length - pos);
+            start += pos;
+            pos = 0;
+            buffer = merged;
+            loaded += next.length;
+            continue;
+        }
+        const window = buffer.subarray(pos, Math.min(buffer.length, pos + MAX));
+        const length = cut(window);
+        chunks.push({ offset: start + pos, size: length, hash: hex(blake3(window.subarray(0, length))) });
+        pos += length;
+        progress?.(start + pos);
+    }
+    return { size: total, hash: seal(chunks), chunks };
+}
+/** The manifest hash of `chunks`. */
+export function seal(chunks) {
+    const bytes = new Uint8Array(chunks.length * 36);
+    chunks.forEach((c, i) => {
+        for (let j = 0; j < 32; j++)
+            bytes[i * 36 + j] = parseInt(c.hash.slice(j * 2, j * 2 + 2), 16);
+        new DataView(bytes.buffer).setUint32(i * 36 + 32, c.size, true);
+    });
+    return hex(blake3(bytes));
+}

package/dist/store/model.d.ts

@@ -0,0 +1,202 @@
+/** Client metadata of a version: modification time (milliseconds since the epoch) and the executable bit. */
+export interface Attrs {
+    mtime: number;
+    exec: boolean;
+}
+/** A folder. `parent` null: at the drive root; `trashed`: when it went to the trash. */
+export interface Folder {
+    id: string;
+    owner: string | null;
+    parent: string | null;
+    name: string;
+    created: string;
+    updated: string;
+    trashed: string | null;
+}
+/**
+ * A file. `version` is the current version and `size` its size; `state` is
+ * `pending` until the first version is ready. `attrs` only when the author
+ * of the current version sent them.
+ */
+export interface FileEntry {
+    id: string;
+    owner: string | null;
+    folder: string | null;
+    name: string;
+    mime: string;
+    size: number;
+    version: string | null;
+    state: string;
+    attrs?: Attrs;
+    created: string;
+    updated: string;
+    trashed: string | null;
+}
+/** The live (or, with `trashed`, the trashed) children of a folder or drive root. */
+export interface Listing {
+    folders: Folder[];
+    files: FileEntry[];
+}
+/**
+ * A version of a file: `open` (chunks being sent), `pending` (committed,
+ * being scanned), `ready`, `superseded` or `quarantined`. `hash` is the
+ * manifest hash, `author` an account uuid, `expires` set while uncommitted.
+ */
+export interface Version {
+    id: string;
+    file: string;
+    state: string;
+    size: number;
+    hash: string;
+    author: string;
+    created: string;
+    committed: string | null;
+    expires: string | null;
+    reserved: number;
+    attrs?: Attrs;
+}
+/** A version and the chunk positions the server still lacks (`GET /v1/versions/{id}`). */
+export interface VersionStatus extends Version {
+    missing: number[];
+}
+/** The answer to `Begin`: `new` (send `missing`, then commit) or `fast` (already ready, nothing to send). */
+export interface Begun {
+    version: string;
+    state: 'new' | 'fast';
+    missing: number[];
+    expires: string | null;
+    reserved: number;
+}
+/** A drive's numbers: `cap` null is no cap; `used` counts open reservations; `mail` and `chat` are pooled attachments. */
+export interface Quota {
+    owner: string;
+    cap: number | null;
+    per: number | null;
+    used: number;
+    mail: number;
+    chat: number;
+}
+/** The use of a public link. */
+export interface LinkUse {
+    password: boolean;
+    cdn: boolean;
+    downloads: number;
+    bytes: number;
+    last: string | null;
+}
+/**
+ * A share of a file or folder (`kind`) with an account, the tenant, a team
+ * or anyone holding a link (`who`). `token` (links only) is in the answer
+ * that creates the link and never again.
+ */
+export interface Share {
+    id: string;
+    target: string | null;
+    kind: string;
+    who: string;
+    grantee: string | null;
+    access: string;
+    expires: string | null;
+    created: string;
+    link?: LinkUse;
+    token?: string;
+}
+/** A share made with the caller and the item it reaches (one of `folder` and `file`). */
+export interface Received {
+    share: Share;
+    folder: Folder | null;
+    file: FileEntry | null;
+}
+/** A folder as a link visitor sees it. */
+export interface PublicFolder {
+    id: string;
+    name: string;
+}
+/** A file as a link visitor sees it. */
+export interface PublicFile {
+    id: string;
+    name: string;
+    mime: string;
+    size: number;
+    updated: string;
+}
+/** What a public link shows: a file, or a folder with one level of its subtree; `cdn.parts` when served from the CDN. */
+export interface LinkPage {
+    kind: string;
+    expires: string | null;
+    folder: PublicFolder | null;
+    folders: PublicFolder[];
+    file: PublicFile | null;
+    files: PublicFile[];
+    cdn: {
+        parts: {
+            url: string;
+            size: number;
+        }[];
+    } | null;
+}
+/** A read ticket: single use, five minutes (`expires` in Unix seconds). */
+export interface Ticket {
+    ticket: string;
+    expires: number;
+}
+/** A thumbnail, poster, remux or rendition of a version. */
+export interface Derivative {
+    id: string;
+    kind: string;
+    preset: string;
+    state: string;
+    reason: string | null;
+    mime: string | null;
+    size: number | null;
+    width: number | null;
+    height: number | null;
+    duration: number | null;
+    ready: string | null;
+}
+/** One entry of the change feed. */
+export interface Change {
+    id: number;
+    owner: string | null;
+    target: string | null;
+    kind: string | null;
+    op: string;
+    parent: string | null;
+    name: string | null;
+    version: string | null;
+    hash: string | null;
+    size: number | null;
+    attrs?: Attrs;
+    updated: string;
+}
+/** A page of the change feed: pass `cursor` back for the next one; `more` means ask again at once. */
+export interface ChangePage {
+    changes: Change[];
+    /** owner id to the last change id applied */
+    cursor: Record<string, number>;
+    /** the drives the caller sees: `own`, `tenant` or `shared` */
+    roots: {
+        owner: string;
+        kind: string;
+    }[];
+    /** owners in the cursor the caller can no longer see */
+    gone: string[];
+    more: boolean;
+}
+/** Search hits (ready, untrashed files the caller may read); `degraded` when the index answered partly. */
+export interface SearchResult {
+    hits: FileEntry[];
+    degraded: boolean;
+}
+type Raw = Record<string, any>;
+/** `{mtime_ns, exec}` as `{mtime, exec}` (milliseconds); undefined when absent. */
+export declare function attrs(raw: unknown): Attrs | undefined;
+export declare const folder: (raw: Raw) => Folder;
+export declare const file: (raw: Raw) => FileEntry;
+export declare const version: (raw: Raw) => Version;
+export declare const status: (raw: Raw) => VersionStatus;
+export declare const change: (raw: Raw) => Change;
+export declare function listing(raw: Raw): Listing;
+export declare function received(raw: Raw): Received;
+export declare function changes(raw: Raw): ChangePage;
+export {};

package/dist/store/model.js

@@ -0,0 +1,38 @@
+// The shapes Aduki Store answers with (the Store docs, "HTTP API: metadata",
+// checked against `crates/app/src/api/*.rs`), and the small mappers that read
+// them. Ids are 16-digit hex public ids; times are RFC 3339 strings.
+/** `{mtime_ns, exec}` as `{mtime, exec}` (milliseconds); undefined when absent. */
+export function attrs(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const r = raw;
+    return { mtime: Math.round(Number(r.mtime_ns) / 1e6), exec: Boolean(r.exec) };
+}
+function withAttrs(raw) {
+    const { attrs: a, ...rest } = raw;
+    const out = rest;
+    const mapped = attrs(a);
+    if (mapped)
+        out.attrs = mapped;
+    return out;
+}
+export const folder = (raw) => raw;
+export const file = (raw) => withAttrs(raw);
+export const version = (raw) => withAttrs(raw);
+export const status = (raw) => withAttrs({ ...raw, missing: raw.missing ?? [] });
+export const change = (raw) => withAttrs(raw);
+export function listing(raw) {
+    return { folders: (raw.folders ?? []).map(folder), files: (raw.files ?? []).map(file) };
+}
+export function received(raw) {
+    return { share: raw.share, folder: raw.folder ? folder(raw.folder) : null, file: raw.file ? file(raw.file) : null };
+}
+export function changes(raw) {
+    return {
+        changes: (raw.changes ?? []).map(change),
+        cursor: raw.cursor ?? {},
+        roots: raw.roots ?? [],
+        gone: raw.gone ?? [],
+        more: Boolean(raw.more),
+    };
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adukilabs/sdk",
-  "version": "0.1.1",
-  "description": "Aduki API client for programs that use API keys (Authorization: Key): Aduki Mail, Contacts and Calendar over REST and JMAP. TypeScript, web platform APIs only, no dependencies; Node 20+, Deno, Bun, workers.",
+  "version": "0.1.2",
+  "description": "Aduki API clients for programs: Aduki Mail, Contacts and Calendar with an API key (REST and JMAP), and the workspace drive of Aduki Store and Aduki Space with an Aduki ID service-client key (DPoP-bound tokens). TypeScript, web platform APIs only, no dependencies; Node 20+, Deno, Bun, workers.",
   "license": "Apache-2.0",
   "type": "module",
   "engines": {
@@ -39,6 +39,9 @@
     "mail",
     "jmap",
     "calendar",
-    "contacts"
+    "contacts",
+    "store",
+    "space",
+    "dpop"
   ]
 }