@filefreak.io/sdk 0.0.0-stage → 0.2.0

package/dist/links.js

@@ -0,0 +1,355 @@
+// Saving what a share link or a public page holds, with no key: one file, or
+// a folder and everything in it (docs/reference/shard-links.md). For a
+// program that has been handed a link, as a person is, and has no account of
+// its own to use.
+//
+// It reads the link as the link's own page does, through the website's public
+// answers under /api/public at the link's own origin, which only ever grow
+// (api/src/routes/public.ts). It never sends a key, a token or a cookie: a
+// link can name any site, and that site is told nothing about whoever follows
+// it. For the same reason every answer is checked for the fields this reads
+// before anything is done with it. A plain file is fetched from its address in
+// ranges (ranges.ts), and a protected one is put back together from its map,
+// each part checked as it arrives (reader.ts).
+//
+// Each file saved counts as the link's page counts it: one of the link's
+// downloads, when it has a limit, and its size toward its owner's month. No
+// API call is counted, since no key is used.
+import { fetchRanges } from "./ranges.js";
+import { asItIsKept, readProtected } from "./reader.js";
+import { backoff, FileFreakError, sleep } from "./transport.js";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** As the API's route takes a token (api/src/routes/public.ts). */
+const TOKEN = /^[A-Za-z0-9_-]{20,80}$/;
+/** As the API's usernameSchema allows one, in either case: the website reads them without case. */
+const USERNAME = /^[A-Za-z0-9_]{3,30}$/;
+/** The local stack's two names, the only ones reached without https. */
+const LOCAL = new Set(["localhost", "127.0.0.1"]);
+/** Items asked for at once from a folder's listing: the most the API gives. */
+const PAGE = 200;
+/** How deep FileFreak lets folders go (api/src/services/removal.ts, MAX_DEPTH). A listing deeper than this is not FileFreak's. */
+const MAX_DEPTH = 32;
+const RETRIES = 4;
+/** The longest wait between tries, whatever Retry-After says. */
+const MOST_WAIT_MS = 60_000;
+/** A sleeping database takes about a minute to start. Five minutes of asking is plenty. */
+const WAKING_TRIES = 60;
+export const NOT_A_LINK = "That is not a FileFreak share link or public file address.";
+/**
+ * The link a web address is: `/share/<token>`, `/public/<username>/<id>`,
+ * or a public file's direct address, `/api/public/files/<id>/raw`. On https,
+ * or on http for the local stack only.
+ */
+export function linkOf(url) {
+    const notALink = (message = NOT_A_LINK) => new FileFreakError(0, "not_a_link", message);
+    let u;
+    try {
+        u = new URL(String(url));
+    }
+    catch {
+        throw notALink();
+    }
+    const secure = u.protocol === "https:" || (u.protocol === "http:" && LOCAL.has(u.hostname));
+    if (!secure || u.username || u.password)
+        throw notALink();
+    const [first, second, third, fourth, fifth, ...more] = u.pathname.split("/").filter((p) => p !== "");
+    if (more.length > 0)
+        throw notALink();
+    if (first === "share" && second && TOKEN.test(second) && third === undefined)
+        return { origin: u.origin, kind: "share", token: second };
+    if (first === "public" && second && USERNAME.test(second) && third && UUID.test(third) && fourth === undefined) {
+        return { origin: u.origin, kind: "public", id: third.toLowerCase(), username: second };
+    }
+    if (first === "public" && second && third === undefined)
+        throw notALink("That is somebody's public profile. Give the address of one of its files or folders.");
+    if (first === "api" && second === "public" && third === "files" && fourth && UUID.test(fourth) && fifth === "raw") {
+        return { origin: u.origin, kind: "public", id: fourth.toLowerCase(), username: null };
+    }
+    throw notALink();
+}
+function unreadable(origin) {
+    return new FileFreakError(0, "unreadable", `${origin} answered with something FileFreak would not: it may not be FileFreak, or not a version this SDK knows.`);
+}
+const isObject = (v) => typeof v === "object" && v !== null && !Array.isArray(v);
+const isCount = (v) => typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+/** Storage's addresses are https, or http on the local stack. Anything else a site sends, data: or file: among them, is not fetched. */
+const isWebAddress = (v) => typeof v === "string" && /^https?:\/\//i.test(v);
+/** The answers come from whatever site the link names, so each is checked before it is used. */
+class Reader {
+    origin;
+    constructor(origin) {
+        this.origin = origin;
+    }
+    fail() {
+        throw unreadable(this.origin);
+    }
+    item(v) {
+        if (!isObject(v) || typeof v.id !== "string" || !UUID.test(v.id) || (v.kind !== "file" && v.kind !== "folder") || typeof v.name !== "string")
+            this.fail();
+        if (v.kind === "file" && !isCount(v.sizeBytes))
+            this.fail();
+        const contentType = typeof v.contentType === "string" ? v.contentType : null;
+        return { id: v.id, kind: v.kind, name: v.name, sizeBytes: v.kind === "file" ? v.sizeBytes : 0, contentType, protected: v.protected === true };
+    }
+    listing(v) {
+        if (!isObject(v) || !Array.isArray(v.items) || !(v.nextOffset === null || isCount(v.nextOffset)))
+            this.fail();
+        return { items: v.items.map((i) => this.item(i)), nextOffset: v.nextOffset };
+    }
+    address(v) {
+        if (!isObject(v) || !isWebAddress(v.url))
+            this.fail();
+        return v.url;
+    }
+    map(v) {
+        if (!isObject(v) || typeof v.contentId !== "string" || typeof v.key !== "string" || typeof v.expiresAt !== "string" || typeof v.grant !== "string")
+            this.fail();
+        if (!isCount(v.sizeBytes) || !isCount(v.fragmentBytes) || !isCount(v.count) || !Array.isArray(v.fragments))
+            this.fail();
+        const fragments = v.fragments.map((f) => (isObject(f) && isCount(f.place) && isWebAddress(f.url) ? { place: f.place, url: f.url } : this.fail()));
+        return { contentId: v.contentId, sizeBytes: v.sizeBytes, fragmentBytes: v.fragmentBytes, count: v.count, key: v.key, fragments, expiresAt: v.expiresAt, grant: v.grant };
+    }
+}
+/** The link's own site, asked with nothing that says who is asking. */
+class Site {
+    origin;
+    fetcher;
+    signal;
+    read;
+    constructor(origin, fetcher, signal) {
+        this.origin = origin;
+        this.fetcher = fetcher;
+        this.signal = signal;
+        this.read = new Reader(origin);
+    }
+    /**
+     * One of the public answers. As the client's transport asks (transport.ts),
+     * but a request is sent again only when it is a read: a password sent twice
+     * is two tries against the link.
+     */
+    async ask(path, grants = {}, body, signal = this.signal) {
+        const method = body === undefined ? "GET" : "POST";
+        const headers = { Accept: "application/json" };
+        if (grants.share)
+            headers["X-Share-Grant"] = grants.share;
+        if (grants.read)
+            headers["X-Read-Grant"] = grants.read;
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        let waking = 0;
+        for (let attempt = 0;; attempt++) {
+            let res;
+            try {
+                res = await this.fetcher(`${this.origin}${path}`, {
+                    method,
+                    headers,
+                    body: body === undefined ? undefined : JSON.stringify(body),
+                    credentials: "omit",
+                    signal,
+                });
+            }
+            catch (e) {
+                if (signal?.aborted)
+                    throw signal.reason;
+                if (method !== "GET" || attempt >= RETRIES)
+                    throw new FileFreakError(0, "network_error", `${this.origin} could not be reached: ${e instanceof Error ? e.message : String(e)}`);
+                await sleep(backoff(attempt), signal);
+                continue;
+            }
+            const text = await res.text();
+            let parsed = null;
+            try {
+                parsed = text ? JSON.parse(text) : null;
+            }
+            catch {
+                parsed = null;
+            }
+            if (res.ok) {
+                if (!isObject(parsed))
+                    throw unreadable(this.origin);
+                return parsed;
+            }
+            const error = isObject(parsed) ? parsed : null;
+            const code = typeof error?.error === "string" ? error.error : `http_${res.status}`;
+            const message = typeof error?.message === "string" ? error.message : `${this.origin} answered ${res.status}.`;
+            // Not Number(header) alone: a missing header is null, and Number(null) is 0.
+            const header = res.headers.get("retry-after");
+            const after = header === null ? NaN : Number(header);
+            const retryAfter = Number.isFinite(after) && after >= 0 ? after : null;
+            const refusal = new FileFreakError(res.status, code, message, error, retryAfter);
+            if (res.status === 503 && code === "waking_up" && waking < WAKING_TRIES) {
+                waking++;
+                attempt--;
+                await sleep(Math.min(MOST_WAIT_MS, (retryAfter ?? 5) * 1000), signal);
+                continue;
+            }
+            const passing = method === "GET" && (res.status === 429 || res.status === 502 || res.status === 503 || res.status === 504);
+            if (!passing || attempt >= RETRIES)
+                throw refusal;
+            await sleep(retryAfter !== null ? Math.min(MOST_WAIT_MS, retryAfter * 1000) : backoff(attempt), signal);
+        }
+    }
+}
+async function openShare(site, token, password) {
+    const base = `/api/public/shares/${token}`;
+    const describe = async (share) => {
+        const v = await site.ask(base, { share });
+        if (!isObject(v) || typeof v.locked !== "boolean" || !(v.downloadsLeft === null || isCount(v.downloadsLeft)))
+            throw unreadable(site.origin);
+        return { locked: v.locked, downloadsLeft: v.downloadsLeft, item: v.locked ? null : site.read.item(v.item) };
+    };
+    let share = null;
+    let view = await describe(null);
+    if (view.locked) {
+        if (!password)
+            throw new FileFreakError(401, "password_required", "This link needs a password. Give it as the password option.");
+        const unlocked = await site.ask(`${base}/unlock`, {}, { password });
+        if (!isObject(unlocked) || typeof unlocked.grant !== "string")
+            throw unreadable(site.origin);
+        share = unlocked.grant;
+        view = await describe(share);
+        if (view.locked)
+            throw unreadable(site.origin);
+    }
+    return {
+        root: view.item,
+        downloadsLeft: view.downloadsLeft,
+        list: async (folder, offset) => site.read.listing(await site.ask(`${base}/items?parent=${folder}&offset=${offset}&limit=${PAGE}`, { share })),
+        address: async (id) => site.read.address(await site.ask(`${base}/files/${id}/url`, { share })),
+        page: async (id, from, read, signal) => site.read.map(await site.ask(`${base}/files/${id}/shards?from=${from}`, { share, read }, undefined, signal)),
+    };
+}
+async function openPublic(site, id, username) {
+    const v = await site.ask(`/api/public/files/${id}`);
+    if (!isObject(v) || !isObject(v.owner) || typeof v.owner.username !== "string")
+        throw unreadable(site.origin);
+    // As the website's page: under another person's name, it is not there.
+    if (username !== null && v.owner.username.toLowerCase() !== username.toLowerCase()) {
+        throw new FileFreakError(404, "not_found", "That file is not public, or does not exist.");
+    }
+    return {
+        root: site.read.item(v.item),
+        downloadsLeft: null,
+        list: async (folder, offset) => site.read.listing(await site.ask(`/api/public/files/${folder}/items?offset=${offset}&limit=${PAGE}`)),
+        address: async (file) => site.read.address(await site.ask(`/api/public/files/${file}/url`)),
+        page: async (file, from, read, signal) => site.read.map(await site.ask(`/api/public/files/${file}/shards?from=${from}`, { read }, undefined, signal)),
+    };
+}
+/** Every file in a shared folder, with the folders it is in, read folder by folder. */
+async function walk(opened) {
+    const found = [];
+    const seen = new Set([opened.root.id]);
+    const visit = async (folder, folders, depth) => {
+        if (depth > MAX_DEPTH) {
+            throw new FileFreakError(0, "too_deep", `This folder has folders more than ${MAX_DEPTH} deep, which FileFreak's never do. Nothing was saved.`);
+        }
+        for (let offset = 0; offset !== null;) {
+            const page = await opened.list(folder.id, offset);
+            for (const item of page.items) {
+                // Listed twice, as when something was added between two pages: saved once.
+                if (seen.has(item.id))
+                    continue;
+                seen.add(item.id);
+                if (item.kind === "folder")
+                    await visit(item, [...folders, item.name], depth + 1);
+                else
+                    found.push({ item, folders });
+            }
+            // A next page that does not move on would be asked for for ever.
+            offset = page.nextOffset !== null && page.nextOffset > offset ? page.nextOffset : null;
+        }
+    };
+    await visit(opened.root, [opened.root.name], 0);
+    return found;
+}
+function plural(n, one, many) {
+    return `${n} ${n === 1 ? one : many}`;
+}
+/**
+ * Save what a share link or a public page holds, with no key: one file into
+ * `into`, a Sink, or a folder and everything in it, each file into the Sink
+ * that `into`, a function, makes for it. Resolves once every file has been
+ * saved and its sink closed.
+ *
+ * Takes `https://<host>/share/<token>`, `https://<host>/public/<username>/<id>`
+ * and a public file's direct address. A protected file is put back together
+ * from its map and checked as it arrives. A failure is a FileFreakError, with
+ * the site's code and sentence or one of get's own: not_a_link, not_a_file
+ * (a folder's link given one Sink), password_required, not_enough_downloads,
+ * too_deep, fragment_damaged or fragment_unavailable. The file being saved
+ * when it stops has its sink aborted; files saved before it stay saved.
+ */
+export async function get(url, into, options = {}) {
+    const make = typeof into === "function" ? into : null;
+    const given = typeof into === "function" ? null : into;
+    const signal = options.signal;
+    try {
+        const link = linkOf(url);
+        const fetcher = options.fetch ?? fetch.bind(globalThis);
+        const site = new Site(link.origin, fetcher, signal);
+        const opened = link.kind === "share" ? await openShare(site, link.token, options.password) : await openPublic(site, link.id, link.username);
+        const { root } = opened;
+        if (root.kind === "folder" && given) {
+            throw new FileFreakError(400, "not_a_file", 'That link is to a folder. Give get() a function that makes a sink for each file, as toFolder in "@filefreak.io/sdk/node" does.');
+        }
+        const found = root.kind === "file" ? [{ item: root, folders: [] }] : await walk(opened);
+        // Each file saved is one of the link's downloads, as on its page. Saving
+        // part of a folder and using the link up doing it helps nobody.
+        const counted = found.filter((f) => f.item.sizeBytes > 0).length;
+        const left = opened.downloadsLeft;
+        if (left !== null && counted > left) {
+            if (left === 0)
+                throw new FileFreakError(410, "link_used_up", "This link has been used as many times as it allows.");
+            throw new FileFreakError(410, "not_enough_downloads", `This link allows ${plural(left, "more download", "more downloads")}, and saving everything in it takes ${counted}: each file is one. Nothing was saved.`);
+        }
+        const total = found.reduce((n, f) => n + f.item.sizeBytes, 0);
+        const saved = [];
+        let before = 0;
+        for (const { item, folders } of found) {
+            const file = { id: item.id, name: item.name, folders, sizeBytes: item.sizeBytes, contentType: item.contentType, protected: item.protected };
+            const sink = given ?? (await make(file));
+            try {
+                await saveOne(opened, item, sink, fetcher, signal, (written) => options.onProgress?.(before + written, total));
+                await sink.close?.();
+            }
+            catch (e) {
+                if (!given)
+                    await sink.abort?.(e).catch(() => undefined);
+                throw e;
+            }
+            before += item.sizeBytes;
+            saved.push(file);
+        }
+        return { kind: root.kind, name: root.name, files: saved, sizeBytes: total };
+    }
+    catch (e) {
+        await given?.abort?.(e).catch(() => undefined);
+        throw e;
+    }
+}
+/** One file of a link into its sink: from its address, or through its map. */
+async function saveOne(opened, item, sink, fetcher, signal, progress) {
+    // Nothing to fetch, and asking would count a download of nothing.
+    if (item.sizeBytes === 0)
+        return;
+    await asItIsKept(item.protected, async () => {
+        const url = await opened.address(item.id);
+        await fetchRanges({ url, sizeBytes: item.sizeBytes, sink, signal, progress, fetch: fetcher, sleep: (ms) => sleep(ms, signal) });
+    }, async () => {
+        // One reading: the first page counts it, and each page after carries
+        // the newest read grant on, held here in memory and nowhere else.
+        let read = null;
+        await readProtected({
+            pages: async (from, pageSignal) => {
+                const page = await opened.page(item.id, from, read, pageSignal);
+                read = page.grant;
+                return page;
+            },
+            sink,
+            signal,
+            progress,
+            fetch: fetcher,
+            sizeBytes: item.sizeBytes,
+        });
+    });
+}

package/dist/md5.d.ts

@@ -0,0 +1,18 @@
+export declare class Md5 {
+    private a;
+    private b;
+    private c;
+    private d;
+    /** Bytes waiting for a whole 64-byte block. */
+    private readonly tail;
+    private tailLength;
+    private total;
+    private readonly words;
+    private done;
+    update(data: Uint8Array): this;
+    /** The 16-byte digest. The hash cannot be fed after this. */
+    digest(): Uint8Array;
+    private block;
+}
+/** Bytes as base64, which is how Content-MD5 carries a digest. */
+export declare function base64(bytes: Uint8Array): string;

package/dist/md5.js

@@ -0,0 +1,130 @@
+// MD5, for the Content-MD5 header on each part of an upload.
+//
+// Storage checks a part against the Content-MD5 it was sent with and refuses
+// it if they differ, so a part damaged on the way, or a file that changed
+// while it was being sent, is never stored as it arrived. WebCrypto offers no
+// MD5, and this package runs in browsers as well as in Node, so it carries
+// its own: the one the website's uploads use (web/lib/md5.ts), checked
+// against the same examples.
+//
+// RFC 1321. Fed in pieces, so a part never has to be held whole to be hashed.
+/** The sine table, written out rather than computed: Math.sin is not required to give the same last bit everywhere. */
+const K = new Int32Array([
+    0xd76aa478, 0xe8c7b756, 0x242070db, 0xc1bdceee, 0xf57c0faf, 0x4787c62a, 0xa8304613, 0xfd469501, 0x698098d8, 0x8b44f7af, 0xffff5bb1, 0x895cd7be,
+    0x6b901122, 0xfd987193, 0xa679438e, 0x49b40821, 0xf61e2562, 0xc040b340, 0x265e5a51, 0xe9b6c7aa, 0xd62f105d, 0x02441453, 0xd8a1e681, 0xe7d3fbc8,
+    0x21e1cde6, 0xc33707d6, 0xf4d50d87, 0x455a14ed, 0xa9e3e905, 0xfcefa3f8, 0x676f02d9, 0x8d2a4c8a, 0xfffa3942, 0x8771f681, 0x6d9d6122, 0xfde5380c,
+    0xa4beea44, 0x4bdecfa9, 0xf6bb4b60, 0xbebfbc70, 0x289b7ec6, 0xeaa127fa, 0xd4ef3085, 0x04881d05, 0xd9d4d039, 0xe6db99e5, 0x1fa27cf8, 0xc4ac5665,
+    0xf4292244, 0x432aff97, 0xab9423a7, 0xfc93a039, 0x655b59c3, 0x8f0ccc92, 0xffeff47d, 0x85845dd1, 0x6fa87e4f, 0xfe2ce6e0, 0xa3014314, 0x4e0811a1,
+    0xf7537e82, 0xbd3af235, 0x2ad7d2bb, 0xeb86d391,
+]);
+/** How far each step rotates, four to a round. */
+const S = [7, 12, 17, 22, 5, 9, 14, 20, 4, 11, 16, 23, 6, 10, 15, 21];
+export class Md5 {
+    a = 0x67452301;
+    b = 0xefcdab89 | 0;
+    c = 0x98badcfe | 0;
+    d = 0x10325476;
+    /** Bytes waiting for a whole 64-byte block. */
+    tail = new Uint8Array(64);
+    tailLength = 0;
+    total = 0;
+    words = new Int32Array(16);
+    done = false;
+    update(data) {
+        if (this.done)
+            throw new Error("This MD5 has already been finished.");
+        this.total += data.length;
+        let i = 0;
+        if (this.tailLength > 0) {
+            const take = Math.min(64 - this.tailLength, data.length);
+            this.tail.set(data.subarray(0, take), this.tailLength);
+            this.tailLength += take;
+            i = take;
+            if (this.tailLength < 64)
+                return this;
+            this.block(this.tail, 0);
+            this.tailLength = 0;
+        }
+        for (; i + 64 <= data.length; i += 64)
+            this.block(data, i);
+        if (i < data.length) {
+            this.tail.set(data.subarray(i));
+            this.tailLength = data.length - i;
+        }
+        return this;
+    }
+    /** The 16-byte digest. The hash cannot be fed after this. */
+    digest() {
+        if (this.done)
+            throw new Error("This MD5 has already been finished.");
+        const bits = this.total * 8;
+        const pad = new Uint8Array(this.tailLength < 56 ? 64 - this.tailLength : 128 - this.tailLength);
+        pad[0] = 0x80;
+        // The length in bits, little-endian, in the last eight bytes. A file over
+        // 2^32 bits (512 MiB) needs the high word as well.
+        const end = pad.length - 8;
+        const low = bits >>> 0;
+        const high = Math.floor(bits / 0x100000000) >>> 0;
+        for (let k = 0; k < 4; k++) {
+            pad[end + k] = (low >>> (8 * k)) & 0xff;
+            pad[end + 4 + k] = (high >>> (8 * k)) & 0xff;
+        }
+        this.total -= pad.length;
+        this.update(pad);
+        this.done = true;
+        const out = new Uint8Array(16);
+        for (const [n, word] of [this.a, this.b, this.c, this.d].entries()) {
+            for (let k = 0; k < 4; k++)
+                out[n * 4 + k] = (word >>> (8 * k)) & 0xff;
+        }
+        return out;
+    }
+    block(bytes, at) {
+        const w = this.words;
+        for (let j = 0; j < 16; j++) {
+            const o = at + j * 4;
+            w[j] = bytes[o] | (bytes[o + 1] << 8) | (bytes[o + 2] << 16) | (bytes[o + 3] << 24);
+        }
+        let a = this.a;
+        let b = this.b;
+        let c = this.c;
+        let d = this.d;
+        for (let j = 0; j < 64; j++) {
+            let f;
+            let g;
+            if (j < 16) {
+                f = (b & c) | (~b & d);
+                g = j;
+            }
+            else if (j < 32) {
+                f = (d & b) | (~d & c);
+                g = (5 * j + 1) & 15;
+            }
+            else if (j < 48) {
+                f = b ^ c ^ d;
+                g = (3 * j + 5) & 15;
+            }
+            else {
+                f = c ^ (b | ~d);
+                g = (7 * j) & 15;
+            }
+            const s = S[(j >> 4) * 4 + (j & 3)];
+            const sum = (a + f + K[j] + w[g]) | 0;
+            a = d;
+            d = c;
+            c = b;
+            b = (b + ((sum << s) | (sum >>> (32 - s)))) | 0;
+        }
+        this.a = (this.a + a) | 0;
+        this.b = (this.b + b) | 0;
+        this.c = (this.c + c) | 0;
+        this.d = (this.d + d) | 0;
+    }
+}
+/** Bytes as base64, which is how Content-MD5 carries a digest. */
+export function base64(bytes) {
+    let text = "";
+    for (const byte of bytes)
+        text += String.fromCharCode(byte);
+    return btoa(text);
+}

package/dist/node.d.ts

@@ -0,0 +1,36 @@
+import type { LinkedFile } from "./links.js";
+import type { Sink } from "./ranges.js";
+/**
+ * A file on disk, to upload: read a part at a time as it is sent, never held
+ * whole. Node refuses to read it if it changes on disk in the meantime, so a
+ * file is never sent half old and half new.
+ */
+export declare function fromPath(path: string, options?: {
+    type?: string;
+}): Promise<File>;
+/**
+ * A file on disk to download into. The bytes are written beside it, under
+ * the same name and ".part", and it takes the name only once every byte is
+ * there: a download that fails leaves nothing, and never a file with holes
+ * where it was meant to be.
+ */
+export declare function toPath(path: string): Promise<Sink>;
+/**
+ * A name from a link, as a name this computer can hold that cannot step out
+ * of the folder it is written in: the part after its last slash or
+ * backslash, with what cannot be in a name written as "_". An empty name,
+ * "." or ".." is `fallback`. The CLI's filefreak get keeps names by the same
+ * rule.
+ */
+export declare function safeName(name: string, fallback: string, windows?: boolean): string;
+/**
+ * Where get() saves a link's files: each in `dir`, in the folders the link
+ * has it in, made as they are needed. Every name is the sharer's, so each is
+ * made safe first (safeName), and names FileFreak keeps apart can then come
+ * out as one ("a\u0001" and "a\u0002" are both "a_"). Compared without
+ * case, since many disks do, folders that come out as one name are one
+ * folder, and a file that comes out as the name of another file or a folder
+ * is told apart as "name (2).ext", as filefreak get does. A file's ".part"
+ * is its place too while it is written. Nothing is written outside `dir`.
+ */
+export declare function toFolder(dir: string): (file: LinkedFile) => Promise<Sink>;

package/dist/node.js

@@ -0,0 +1,124 @@
+// Files on disk, for a program in Node: one to upload, one to download into,
+// and a folder to save a link's files in. Apart from the main entry, which
+// runs in browsers too.
+//
+//   import { fromPath, toFolder, toPath } from "@filefreak.io/sdk/node";
+//   const item = await ff.upload(await fromPath("film.mp4"));
+//   await ff.download(item.id, await toPath("copy.mp4"));
+//   await get("https://filefreak.link/share/...", toFolder("downloads"));
+import { openAsBlob } from "node:fs";
+import { mkdir, open, rename, rm } from "node:fs/promises";
+import { basename, extname, join, resolve, sep } from "node:path";
+/**
+ * A file on disk, to upload: read a part at a time as it is sent, never held
+ * whole. Node refuses to read it if it changes on disk in the meantime, so a
+ * file is never sent half old and half new.
+ */
+export async function fromPath(path, options = {}) {
+    const blob = await openAsBlob(path, options.type ? { type: options.type } : {});
+    return new File([blob], basename(path), { type: blob.type });
+}
+/**
+ * A file on disk to download into. The bytes are written beside it, under
+ * the same name and ".part", and it takes the name only once every byte is
+ * there: a download that fails leaves nothing, and never a file with holes
+ * where it was meant to be.
+ */
+export async function toPath(path) {
+    const partial = partialOf(path);
+    const handle = await open(partial, "w");
+    let shut = false;
+    const close = async () => {
+        if (shut)
+            return;
+        shut = true;
+        await handle.close();
+    };
+    return {
+        async write(position, data) {
+            for (let at = 0; at < data.byteLength;) {
+                const { bytesWritten } = await handle.write(data, at, data.byteLength - at, position + at);
+                at += bytesWritten;
+            }
+        },
+        async close() {
+            await close();
+            await rename(partial, path);
+        },
+        async abort() {
+            await close();
+            await rm(partial, { force: true });
+        },
+    };
+}
+/** Where toPath writes a file until every byte is there. */
+const partialOf = (path) => `${path}.part`;
+/** Characters that are never kept in a name from a link: controls, and the ones that turn text around so ".exe" can read as ".pdf". */
+const UNSEEN = /[\u0000-\u001f\u007f-\u009f\u200e\u200f\u202a-\u202e\u2066-\u2069]/g;
+/** What Windows cannot hold in a name. */
+const NOT_ON_WINDOWS = /[<>:"|?*]/g;
+/** Names Windows keeps for devices, with or without an extension. */
+const DEVICE = /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\.|$)/i;
+/**
+ * A name from a link, as a name this computer can hold that cannot step out
+ * of the folder it is written in: the part after its last slash or
+ * backslash, with what cannot be in a name written as "_". An empty name,
+ * "." or ".." is `fallback`. The CLI's filefreak get keeps names by the same
+ * rule.
+ */
+export function safeName(name, fallback, windows = process.platform === "win32") {
+    let out = (name.split(/[/\\]/).pop() ?? "").replace(UNSEEN, "_");
+    if (windows) {
+        out = out.replace(NOT_ON_WINDOWS, "_").replace(/[ .]+$/, "");
+        if (DEVICE.test(out))
+            out = `_${out}`;
+    }
+    return out === "" || out === "." || out === ".." ? fallback : out;
+}
+/**
+ * Where get() saves a link's files: each in `dir`, in the folders the link
+ * has it in, made as they are needed. Every name is the sharer's, so each is
+ * made safe first (safeName), and names FileFreak keeps apart can then come
+ * out as one ("a\u0001" and "a\u0002" are both "a_"). Compared without
+ * case, since many disks do, folders that come out as one name are one
+ * folder, and a file that comes out as the name of another file or a folder
+ * is told apart as "name (2).ext", as filefreak get does. A file's ".part"
+ * is its place too while it is written. Nothing is written outside `dir`.
+ */
+export function toFolder(dir) {
+    const root = resolve(dir);
+    // Each place given, in lower case, as a file's or a folder's.
+    const taken = new Map();
+    // Each of the link's folders, by its names from the top, and where it is here.
+    const made = new Map();
+    const given = (path, kind) => kind === "folder" ? taken.get(path.toLowerCase()) === "file" : taken.has(path.toLowerCase()) || taken.has(partialOf(path).toLowerCase());
+    const place = (under, name, kind) => {
+        const ext = kind === "file" ? extname(name) : "";
+        const stem = name.slice(0, name.length - ext.length);
+        let path = join(under, name);
+        for (let n = 2; given(path, kind); n++)
+            path = join(under, `${stem} (${n})${ext}`);
+        taken.set(path.toLowerCase(), kind);
+        if (kind === "file")
+            taken.set(partialOf(path).toLowerCase(), "file");
+        return path;
+    };
+    return async (file) => {
+        let folder = root;
+        for (let i = 0; i < file.folders.length; i++) {
+            const key = JSON.stringify(file.folders.slice(0, i + 1));
+            let here = made.get(key);
+            if (here === undefined) {
+                here = place(folder, safeName(file.folders[i], "folder"), "folder");
+                made.set(key, here);
+            }
+            folder = here;
+        }
+        const path = place(folder, safeName(file.name, "download"), "file");
+        // safeName already keeps every part inside; this is the rule said once more where it matters.
+        if (!path.startsWith(root + sep))
+            throw new Error(`${JSON.stringify(file.name)} would be saved outside ${root}.`);
+        await mkdir(folder, { recursive: true });
+        return await toPath(path);
+    };
+}