@adukilabs/sdk 0.0.0-stage → 0.1.2

package/dist/store/blake3.js

@@ -0,0 +1,130 @@
+// BLAKE3 (hash mode, 32-byte output) in plain TypeScript: Store names every
+// chunk and every manifest by its BLAKE3, and WebCrypto has no BLAKE3. A
+// straight port of the reference implementation (github.com/BLAKE3-team/BLAKE3,
+// reference_impl.rs); the Store golden corpus checks it end to end.
+const IV = Uint32Array.of(0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19);
+const PERMUTATION = [2, 6, 3, 10, 7, 0, 4, 13, 1, 11, 12, 5, 9, 14, 15, 8];
+const CHUNK_START = 1;
+const CHUNK_END = 2;
+const PARENT = 4;
+const ROOT = 8;
+const BLOCK = 64;
+const CHUNK = 1024;
+// One state and one message schedule reused by every compression (single-threaded).
+const state = new Uint32Array(16);
+const words = new Uint32Array(16);
+const scratch = new Uint32Array(16);
+function g(a, b, c, d, x, y) {
+    const s = state;
+    s[a] = (s[a] + s[b] + x) | 0;
+    let t = s[d] ^ s[a];
+    s[d] = (t >>> 16) | (t << 16);
+    s[c] = (s[c] + s[d]) | 0;
+    t = s[b] ^ s[c];
+    s[b] = (t >>> 12) | (t << 20);
+    s[a] = (s[a] + s[b] + y) | 0;
+    t = s[d] ^ s[a];
+    s[d] = (t >>> 8) | (t << 24);
+    s[c] = (s[c] + s[d]) | 0;
+    t = s[b] ^ s[c];
+    s[b] = (t >>> 7) | (t << 25);
+}
+/** Compresses `block` (16 words) into `cv` (8 words) in place; `out` gets the first 8 output words. */
+function compress(cv, block, counter, length, flags, out) {
+    state.set(cv.subarray(0, 8), 0);
+    state[8] = IV[0];
+    state[9] = IV[1];
+    state[10] = IV[2];
+    state[11] = IV[3];
+    state[12] = counter >>> 0;
+    state[13] = Math.floor(counter / 0x1_0000_0000) >>> 0;
+    state[14] = length;
+    state[15] = flags;
+    const m = words;
+    m.set(block);
+    for (let round = 0; round < 7; round++) {
+        g(0, 4, 8, 12, m[0], m[1]);
+        g(1, 5, 9, 13, m[2], m[3]);
+        g(2, 6, 10, 14, m[4], m[5]);
+        g(3, 7, 11, 15, m[6], m[7]);
+        g(0, 5, 10, 15, m[8], m[9]);
+        g(1, 6, 11, 12, m[10], m[11]);
+        g(2, 7, 8, 13, m[12], m[13]);
+        g(3, 4, 9, 14, m[14], m[15]);
+        if (round < 6) {
+            for (let i = 0; i < 16; i++)
+                scratch[i] = m[PERMUTATION[i]];
+            m.set(scratch);
+        }
+    }
+    for (let i = 0; i < 8; i++)
+        out[i] = state[i] ^ state[i + 8];
+}
+/** The 16 little-endian words of the 64-byte block of `data` at `offset` (zero padded). */
+function load(data, offset, length, into) {
+    if (length === BLOCK && (data.byteOffset + offset) % 4 === 0 && littleEndian) {
+        into.set(new Uint32Array(data.buffer, data.byteOffset + offset, 16));
+        return;
+    }
+    into.fill(0);
+    for (let i = 0; i < length; i++)
+        into[i >> 2] |= data[offset + i] << ((i & 3) * 8);
+}
+const littleEndian = new Uint8Array(Uint32Array.of(1).buffer)[0] === 1;
+/** The output of chunk `index` (`data[offset, offset + length)`, at most 1024 bytes). */
+function chunk(data, offset, length, index) {
+    const cv = IV.slice();
+    const block = new Uint32Array(16);
+    const blocks = Math.max(1, Math.ceil(length / BLOCK));
+    for (let b = 0; b < blocks - 1; b++) {
+        load(data, offset + b * BLOCK, BLOCK, block);
+        compress(cv, block, index, BLOCK, b === 0 ? CHUNK_START : 0, cv);
+    }
+    const last = length - (blocks - 1) * BLOCK;
+    load(data, offset + (blocks - 1) * BLOCK, last, block);
+    return { cv, block, counter: index, length: last, flags: (blocks === 1 ? CHUNK_START : 0) | CHUNK_END };
+}
+function chaining(output) {
+    const out = new Uint32Array(8);
+    compress(output.cv, output.block, output.counter, output.length, output.flags, out);
+    return out;
+}
+function parent(left, right) {
+    const block = new Uint32Array(16);
+    block.set(left, 0);
+    block.set(right, 8);
+    return { cv: IV.slice(), block, counter: 0, length: BLOCK, flags: PARENT };
+}
+/** The BLAKE3 hash (32 bytes) of `data`. */
+export function blake3(data) {
+    const chunks = Math.max(1, Math.ceil(data.length / CHUNK));
+    const stack = [];
+    for (let i = 0; i < chunks - 1; i++) {
+        let cv = chaining(chunk(data, i * CHUNK, CHUNK, i));
+        // Merge completed subtrees: one merge per trailing zero bit of the chunk count.
+        for (let total = i + 1; (total & 1) === 0; total >>= 1)
+            cv = chaining(parent(stack.pop(), cv));
+        stack.push(cv);
+    }
+    let output = chunk(data, (chunks - 1) * CHUNK, data.length - (chunks - 1) * CHUNK, chunks - 1);
+    while (stack.length > 0)
+        output = parent(stack.pop(), chaining(output));
+    const root = new Uint32Array(8);
+    compress(output.cv, output.block, 0, output.length, output.flags | ROOT, root);
+    const bytes = new Uint8Array(32);
+    for (let i = 0; i < 8; i++) {
+        const w = root[i];
+        bytes[i * 4] = w & 0xff;
+        bytes[i * 4 + 1] = (w >>> 8) & 0xff;
+        bytes[i * 4 + 2] = (w >>> 16) & 0xff;
+        bytes[i * 4 + 3] = (w >>> 24) & 0xff;
+    }
+    return bytes;
+}
+/** Lowercase hex of `bytes`. */
+export function hex(bytes) {
+    let out = '';
+    for (const b of bytes)
+        out += b.toString(16).padStart(2, '0');
+    return out;
+}

package/dist/store/cdc.d.ts

@@ -0,0 +1,12 @@
+/** Minimum chunk size of a multi-chunk file (256 KiB). */
+export declare const MIN: number;
+/** Average chunk size (1 MiB). */
+export declare const AVG: number;
+/** Maximum chunk size, and the largest file that stays one chunk (4 MiB). */
+export declare const MAX: number;
+/**
+ * The length of the first chunk of `source` (`cut_gear` of fastcdc v2020
+ * with the Store parameters): at most `MAX`, all of `source` when it is at
+ * most `MIN` long.
+ */
+export declare function cut(source: Uint8Array): number;

package/dist/store/cdc.js

@@ -0,0 +1,127 @@
+// FastCDC 2020 cut points as Store cuts them (the `chunk` crate of the Store
+// repository over `fastcdc` 5.0.0 `v2020`: normalisation level 1, no seed,
+// the default gear table): a file of at most 4 MiB is one chunk, a longer one
+// is cut with minimum 256 KiB, average 1 MiB and maximum 4 MiB. The same
+// cuts as the server's mean identical content deduplicates. The 64-bit gear
+// hash runs on two 32-bit halves.
+/** Minimum chunk size of a multi-chunk file (256 KiB). */
+export const MIN = 256 * 1024;
+/** Average chunk size (1 MiB). */
+export const AVG = 1024 * 1024;
+/** Maximum chunk size, and the largest file that stays one chunk (4 MiB). */
+export const MAX = 4 * 1024 * 1024;
+// fastcdc v2020 GEAR: 256 u64 values, 16 hex digits each.
+const TABLE = '3b5d3c7d207e37dc784d68ba91123086cd52880f882e7298eacf8e4e19fdcca7c31f385dfbd1632b1d5f27001e25abe683130bde3c9ad991c4b225676e9b7649' +
+    'aa329b29e08eb499b67fcbd21e577d580027baaada2acf6be3ef2d5ac73c22260890f24d6ed312b7a809e036851d7c7ef0a6fe5e0013d81b1d026304452cec14' +
+    '03864632648e248fcdaacf3dcd92b9b4f5e012e63c1878568862f9d3821c00b6a82f7338750f6f8a1e583dc6c1cb0b6f7a3145b69743a7f1abb20fee404807eb' +
+    'b14b3cfe07b83a5db9dc27898adb9a0f3703f5e91baa62becf0bb866815f7d983d9867c41ea9dcd31be1fa65442bf22c14300da4c55631d9e698e9cbc6545c99' +
+    '4763107ec64e92a5c65821fc65696a2476196c064822f0b7485be841f3525e01f652bc9c85974ff5cad8352face9e3e92a6ed1dceb35e98ec6f483badc11680f' +
+    '3cfd8c17e9cf12f189b83c5e2ea56471ae665cfd24e392a9ec33c4e504cb89153fb9b15fc9fe7451d7fd1fd1945f219531ade0853443efd8255efc9863e1e2d2' +
+    '10eab6008d5642cf46f04863257ac804a52dc42a789a27d3daaadf9ce77af5656b479cd53d87febb6309e2d3f93db72fc5738ffbaa1ff9d66bd57f3f25af7968' +
+    '67605486d90d0a4ae14d0b9663bfbdaeb7bbd8d816eb0414def8a4f16b35a116e7932d85aaaffed608161cbae90cfd48855507beb294f08b91234ea6ffd399b2' +
+    'ad70cf4b2435f302d289a97565bc2d278e558437ffca99de96d2704b7115c0400889bbcdfc660e415e0d4e67dc92128d72a9f8917063ed97438b69d409e016e3' +
+    'df4fed8a5d8a439700f41dcf41d403f74814eb038e52603f9dafbacc58e2d651fe2f458e4be170af4457ec414df6a94006e62f1451123314bd1014d173ba92cc' +
+    'def318e25ed577609fea0de9dfca8525459de1e76c20624baeec189617e2d666126a2c06ab5a83cbb1321532360f613265421503dbb401232d67c287ea089ab3' +
+    '6c93bff5a56bd6b64ffb2036cab6d98dce7b785b1be7ad4fedb42ef6189fd163dc905288703988f6365f9c1d2c691884c640583680d99bfe3cd4624c07593ec6' +
+    '7f1ea8d85d7c5805014842d480b571490b649bcb5a828688bcd5708ed79b18f0e987c862fbd2f2f0982731671f0cd82cbaf13e8b16d8c0638ea3109cbd951bba' +
+    'd141045bfb385cad2acbc1a0af1f7d30e6444d89df03bfdfa18cc771b8188ff99834429db01c39bb214add07fe086a1f8f07c19b1f6b3ff956a297b1bf4ffe55' +
+    '94d558e493c54fc740bfc24c764552cb931a706f8a8520cb32229d322935bd522560d0f5dc4fefaf9dbcc48355969bb60fd81c3985c0b56ae03817e1560f2bda' +
+    'c1bb4f81d892b2d5b0c4864f4e28d2d73ecc49f9d9d6c26351307e99b52ba65e8af2b688da84a752f5d72523b91b20b66d95ff1ff4634806562f21555458339a' +
+    'c0ce47f889336346487823e5089b40d8e4727c7ebc6d95925a8f7277e94970bafca2f406b1c8bb505b1f8a95f1791070d304af9fc90286055440ab7fc930e748' +
+    '312d25fbca2ab5a110f4a4b234a4d57590301d55047e74733b6372886c61591e293402b77c444e06451f34a4d3e97dd73158d814d81bc57b034942425b9bda69' +
+    'e2032ff9e532d9bb62ae066b8b2179e59545e10c2f8d71d87ff7483eb2d23fc000945fcebdc98d868764bbbe99b26ca21b1ec62284c0bfc358e0fcc4f0aa362b' +
+    '5f4abefa878d458dfd74ac2f9607c519a4e3fb37df8cbfa9bf697e43cac574e586f14a3f68f4cd5324a23d076f1ce522e725cd8048868cc8bf3c729eb2464362' +
+    'd8f6cd57b3cc1ed86329e5242554157762aa688ad5ae1ac00a242566269bf845168b1a4753aca74bf789afefff2e7e3c6c3362093b6fccdb4ce8f50bd28c09b2' +
+    '006a2db95ae8aa93975b0d623c3d1a8c18605d3935338c5b5bb6f6136cad3c710f53a20701f8d8a6ab8c5ad2e7e93c6740b5ac5127acaa298c7bf63c2075895f' +
+    '78bd9f7e014a805cb2c9e9f4f9c8c032efd6049827eb91f32be459f482c16fbdd92ce0c5745aaa8c0aaa8fb298d965b92b37f92c6c803b158c54a5e94e0f0e78' +
+    '95f9b6e90c0a3032e7939faa436c7874d16bfe8f6a8a40c944982b86263fd2fae285fb39f984e583779a8df72d7619d3f2d79a8de8d5dd1ed1037354d66684e2' +
+    '004c82a4e668a8e531d40a7668b044e6d70578538bd02c11db45431078c5f482977121bb7f6a51ad73d5ccbd34eff8dde437a07d356e17cd47b2782043c95627' +
+    '9fb251413e41d49accd70b60652513d31c95b31e8a1b49b2cae73dfd1bcb4c1b34d98331b1f5b70f784e39f22338d92f18613d4a064df420f1d8dae25f0bcebe' +
+    '33f77c15ae855efc3c88b3b912eb109c956a2ec96bafeea51aa005b5e0ad0e875500d70527c4bb8ee36c57196421cc4413c4d286cc36ee395654a23d818b2a81' +
+    '77b1dc13d161abdc734f44de5f8d5eb560717e174a6c89a2d47d9649266a211e5b13a4322bb69e90f7669609f8b5fc3c21e6ac55bedcdac99b56b62b61166dea' +
+    'f48f66b939797e9c35f332f9c0e6ae9acc733f6a9a878db03da161e41cc108c2b7d74ae535914d514d493b0b11d36469ce264d1dfba9741aa9d1f2dc7436dc06' +
+    '70738016604c2a27231d36e96e93f3d57666881197838d194a2a83090aaad40cf1e761591668b35d7363236497f730a7301080e37379dd4d502dea2971827042' +
+    'c2c5eb858f32625f786afb9edfafbdffdaee0d868490b2a4617366b3268609f6ae0e35a0fe46173ed1a07de93e824f11079b8b115ea4cca893a99274558faebb' +
+    'fb1e6e22e08a03b3ea635fdba3698dd0cf53659328503a5ccde3b31e6fd5d7808e3e4221d3614413ef14d0d86bf1a22ce1d830d3f16c5ddbaabd2b2a451504e1';
+const GEAR_HI = new Uint32Array(256);
+const GEAR_LO = new Uint32Array(256);
+const LS_HI = new Uint32Array(256);
+const LS_LO = new Uint32Array(256);
+for (let i = 0; i < 256; i++) {
+    const hi = parseInt(TABLE.slice(i * 16, i * 16 + 8), 16) >>> 0;
+    const lo = parseInt(TABLE.slice(i * 16 + 8, i * 16 + 16), 16) >>> 0;
+    GEAR_HI[i] = hi;
+    GEAR_LO[i] = lo;
+    // GEAR_LS is GEAR shifted left one bit (wrapping), as in the crate.
+    LS_HI[i] = ((hi << 1) | (lo >>> 31)) >>> 0;
+    LS_LO[i] = (lo << 1) >>> 0;
+}
+// The masks for an average of 1 MiB at level 1: MASKS[21] (strict) and
+// MASKS[19] (relaxed), and each shifted left one bit.
+const S_HI = 0x0000d917;
+const S_LO = 0x67537000;
+const L_HI = 0x0000d917;
+const L_LO = 0x07537000;
+const SLS_HI = ((S_HI << 1) | (S_LO >>> 31)) >>> 0;
+const SLS_LO = (S_LO << 1) >>> 0;
+const LLS_HI = ((L_HI << 1) | (L_LO >>> 31)) >>> 0;
+const LLS_LO = (L_LO << 1) >>> 0;
+/**
+ * The length of the first chunk of `source` (`cut_gear` of fastcdc v2020
+ * with the Store parameters): at most `MAX`, all of `source` when it is at
+ * most `MIN` long.
+ */
+export function cut(source) {
+    let remaining = source.length;
+    if (remaining <= MIN)
+        return remaining;
+    let center = AVG;
+    if (remaining > MAX)
+        remaining = MAX;
+    else if (remaining < center)
+        center = remaining;
+    const limit1 = center >>> 1;
+    const limit2 = remaining >>> 1;
+    let index = MIN >>> 1;
+    let hi = 0;
+    let lo = 0;
+    while (index < limit1) {
+        const a = index * 2;
+        // hash = (hash << 2) + GEAR_LS[src[a]]
+        let b = source[a];
+        hi = ((hi << 2) | (lo >>> 30)) >>> 0;
+        lo = (lo << 2) >>> 0;
+        let sum = lo + LS_LO[b];
+        lo = sum >>> 0;
+        hi = (hi + LS_HI[b] + (sum > 0xffffffff ? 1 : 0)) >>> 0;
+        if ((hi & SLS_HI) === 0 && (lo & SLS_LO) === 0)
+            return a;
+        // hash = hash + GEAR[src[a + 1]]
+        b = source[a + 1];
+        sum = lo + GEAR_LO[b];
+        lo = sum >>> 0;
+        hi = (hi + GEAR_HI[b] + (sum > 0xffffffff ? 1 : 0)) >>> 0;
+        if ((hi & S_HI) === 0 && (lo & S_LO) === 0)
+            return a + 1;
+        index++;
+    }
+    while (index < limit2) {
+        const a = index * 2;
+        let b = source[a];
+        hi = ((hi << 2) | (lo >>> 30)) >>> 0;
+        lo = (lo << 2) >>> 0;
+        let sum = lo + LS_LO[b];
+        lo = sum >>> 0;
+        hi = (hi + LS_HI[b] + (sum > 0xffffffff ? 1 : 0)) >>> 0;
+        if ((hi & LLS_HI) === 0 && (lo & LLS_LO) === 0)
+            return a;
+        b = source[a + 1];
+        sum = lo + GEAR_LO[b];
+        lo = sum >>> 0;
+        hi = (hi + GEAR_HI[b] + (sum > 0xffffffff ? 1 : 0)) >>> 0;
+        if ((hi & L_HI) === 0 && (lo & L_LO) === 0)
+            return a + 1;
+        index++;
+    }
+    return remaining;
+}

package/dist/store/chunks.d.ts

@@ -0,0 +1,23 @@
+/** One chunk of a manifest: where it is in the file, its size and its BLAKE3 (64 hex digits). */
+export interface Chunk {
+    offset: number;
+    size: number;
+    hash: string;
+}
+/** A file's chunk list, its size and its manifest hash. */
+export interface Manifest {
+    size: number;
+    hash: string;
+    chunks: Chunk[];
+}
+/** Content the SDK can upload: a Blob (a File too), an ArrayBuffer or bytes. */
+export type Content = Blob | ArrayBuffer | Uint8Array;
+/** `content` as a Blob (bytes are copied once). */
+export declare function blob(content: Content): Blob;
+/** The manifest of `content`; `progress` is called with the bytes read so far. */
+export declare function manifest(content: Content, progress?: (read: number) => void): Promise<Manifest>;
+/** The manifest hash of `chunks`. */
+export declare function seal(chunks: readonly {
+    hash: string;
+    size: number;
+}[]): string;

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,6 +1,47 @@
 {
   "name": "@adukilabs/sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "main": "./dist/api/index.js",
+  "types": "./dist/api/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/api/index.d.ts",
+      "default": "./dist/api/index.js"
+    },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "default": "./dist/api/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adukilabs/ts.git"
+  },
+  "keywords": [
+    "aduki",
+    "api",
+    "mail",
+    "jmap",
+    "calendar",
+    "contacts",
+    "store",
+    "space",
+    "dpop"
+  ]
+}