@filefreak.io/sdk 0.3.2 → 0.5.0

package/README.md

@@ -33,7 +33,9 @@ const bytes = await ff.bytes(file.id); // for a file small enough to hold in mem
 than memory is fine. `toPath` writes beside the file and gives it its name
 only once every byte is there: a download that fails leaves nothing behind.
 A file under Shard Protection has no address, and `download` and `bytes`
-read it through its map instead, each fragment checked as it arrives.
+read it through its map instead, each fragment checked as it arrives. One
+written in version 2 of the shard format, in blocks cut by its content, is
+read the same way, its outline checked before any block is fetched.
 Into a folder under Shard Protection, `upload` seals each part with the
 file's own key before it is sent, so none of the file is ever plain in
 storage. The key is asked of the API for the upload and kept nowhere, and
@@ -74,6 +76,42 @@ folder asked for, for a minute to an hour. It is checked against its key on
 every request, so revoking the key stops its tokens at once. A token cannot
 make another.
 
+## Previews
+
+Once the service has made them, within a few minutes of an upload, a file
+has `thumbnailUrl`, a small WebP picture of an image, a photo from an
+iPhone, a PDF's first page, the cover in an audio file's tags or a frame of
+a video; or `previewTextUrl`, the first lines of a text or code file or a
+document, as text. Both are addresses on storage itself that need no key.
+Each is the same all day, so a browser keeps what it fetched, and fetching
+one counts as nothing. They are null until made, and for a file with none.
+
+```ts
+const { items } = await ff.files.list({ parent: folder.id });
+for (const item of items) {
+  if (item.thumbnailUrl) gallery.append(Object.assign(new Image(), { src: item.thumbnailUrl, alt: item.name }));
+}
+```
+
+The service never reads a video, so a video's picture is a frame of it that
+you send. In a web page, `upload` draws one about a second in from the file
+the page has, and sends it once the file is stored, without the upload
+waiting for it; `frame: false` sends none. On a server, make a JPEG of a
+frame with anything that can, and send that:
+
+```ts
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { promisify } from "node:util";
+
+// The frame a second in, 960 pixels wide, as a JPEG.
+await promisify(execFile)("ffmpeg", ["-ss", "1", "-i", "film.mp4", "-frames:v", "1", "-vf", "scale=960:-2", "-y", "frame.jpg"]);
+await ff.files.sendFrame(file.id, new Blob([await readFile("frame.jpg")]));
+```
+
+A video's picture is a JPEG of at most 2 MB, sent once. A file under Shard
+Protection has no previews.
+
 ## Saving from a link
 
 `get` saves what a share link or a public page holds. It needs no key, and

package/dist/client.d.ts

@@ -36,6 +36,13 @@ export declare class FileFreak {
     readonly files: Api["files"] & {
         /** Everything in a folder, read to the end a page at a time. */
         each(query?: Omit<FilesListQuery, "cursor">, options?: CallOptions): AsyncIterable<Item>;
+        /**
+         * Give a video its picture in listings: a JPEG of one of its frames, at
+         * most 2 MB, which the service makes small and gives as the video's
+         * thumbnailUrl within a few minutes. Once for each video. In a web page,
+         * upload() does it itself.
+         */
+        sendFrame(id: string, jpeg: Blob, options?: CallOptions): Promise<void>;
     };
     readonly folders: Api["folders"];
     readonly tree: Api["tree"] & {

package/dist/client.js

@@ -3,8 +3,10 @@
 // otherwise write around them: sending a file in parts, fetching one in
 // ranges, and reading a listing or the changes to the end.
 import { bind, OPERATIONS, } from "./generated.js";
+import { sendFrame } from "./frames.js";
 import { fetchRanges } from "./ranges.js";
 import { asItIsKept, readProtected } from "./reader.js";
+import { READS_FORMATS } from "./shards.js";
 import { FileFreakError, sleep, Transport } from "./transport.js";
 import { upload } from "./uploads.js";
 /** How long a follow of the changes waits for one before asking again, unless told. */
@@ -57,7 +59,11 @@ export class FileFreak {
     constructor(options) {
         this.transport = new Transport(options);
         const api = bind((operation, input, callOptions) => this.call(operation, input, callOptions));
-        this.files = { ...api.files, each: (query = {}, callOptions) => pages(api.files.list, query, callOptions) };
+        this.files = {
+            ...api.files,
+            each: (query = {}, callOptions) => pages(api.files.list, query, callOptions),
+            sendFrame: (id, jpeg, callOptions) => sendFrame(api.files.frame, this.transport.fetch, id, jpeg, callOptions),
+        };
         this.folders = api.folders;
         this.tree = { ...api.tree, walk: (query = {}, callOptions) => new Walk(api.tree.list, query, callOptions) };
         this.changes = { ...api.changes, follow: (cursor, followOptions = {}) => follow(api.changes.list, cursor ?? null, followOptions) };
@@ -94,7 +100,7 @@ export class FileFreak {
      * to storage. See UploadOptions, and UploadStopped for carrying on.
      */
     upload(source, options = {}) {
-        return upload({ ...this.uploads, file: this.files.get }, this.transport.fetch, source, options);
+        return upload({ ...this.uploads, file: this.files.get, frame: this.files.frame }, this.transport.fetch, source, options);
     }
     /**
      * Fetch a file straight from storage into `sink`: as up to six ranges at
@@ -134,7 +140,7 @@ export class FileFreak {
             const { url } = await this.files.downloadUrl(item.id, {}, { signal });
             await fetchRanges({ url, sizeBytes: item.sizeBytes, sink, signal, progress, ranges: options.ranges, fetch: this.transport.fetch, sleep: (ms) => sleep(ms, signal) });
         }, () => readProtected({
-            pages: (from, pageSignal) => this.files.shards(item.id, { from }, { signal: pageSignal }),
+            pages: (from, pageSignal) => this.files.shards(item.id, { from, formats: READS_FORMATS }, { signal: pageSignal }),
             sink,
             sizeBytes: item.sizeBytes,
             signal,

package/dist/frames.d.ts

@@ -0,0 +1,21 @@
+import type { FilesFrameAnswer } from "./generated.js";
+import { type CallOptions } from "./transport.js";
+/** The most the service keeps of a picture of a video. Anything larger is not made into one. */
+export declare const FRAME_MAX_BYTES = 2000000;
+/** Whether the service takes a picture for a file of this type and name. Its word is final: files.frame refuses any other with 409 no_frame_wanted. */
+export declare function takesFrame(contentType: string | null, name: string): boolean;
+/**
+ * Sends a JPEG of a video's frame to be its picture: asks files.frame where,
+ * and puts it there. Throws if it is not a JPEG of at most FRAME_MAX_BYTES,
+ * if the service wants none for the file (409 no_frame_wanted: not a video,
+ * protected, or given one already), or if storage refuses it.
+ */
+export declare function sendFrame(frame: (id: string, options?: CallOptions) => Promise<FilesFrameAnswer>, fetcher: typeof fetch, id: string, jpeg: Blob, options?: CallOptions): Promise<void>;
+/** Whether this is a web page, which can draw a video. */
+export declare function canDrawFrames(): boolean;
+/**
+ * A frame about a second in, or halfway through a shorter video, as a JPEG,
+ * or null where this browser cannot play the video or draw it. A second in
+ * rather than the first frame, which is black more often than not.
+ */
+export declare function drawFrame(video: Blob): Promise<Blob | null>;

package/dist/frames.js

@@ -0,0 +1,124 @@
+// A picture of a video, for its place in a listing (an item's thumbnailUrl).
+//
+// The service never reads a video: making a picture of one would take a
+// video decoder reading anybody's upload where the service's keys are.
+// Whoever has the video in hand draws a frame and sends it, as the website
+// does; files.frame says where, and the service makes it small and keeps
+// it. In a web page, upload() does this itself once a video is stored, from
+// the file the page already has, so nothing is fetched. Anywhere else, a
+// program that can make a JPEG of a frame (with ffmpeg, say) sends it with
+// files.sendFrame.
+import { FileFreakError } from "./transport.js";
+/** The most the service keeps of a picture of a video. Anything larger is not made into one. */
+export const FRAME_MAX_BYTES = 2_000_000;
+/** The longest side of a frame drawn here, in pixels. The service makes it smaller again. */
+const EDGE = 960;
+/** Long enough for a browser to load the start of a video it can play. One it cannot is given up on. */
+const WAIT_MS = 15_000;
+/**
+ * Videos by name, as the service knows them, for one typed as nothing in
+ * particular. Not by video/mp2t, which is how browsers type a TypeScript
+ * file (.ts).
+ */
+const VIDEO_EXTENSIONS = new Set(["mp4", "m4v", "webm", "mov", "mkv", "avi", "ogv"]);
+/** Whether the service takes a picture for a file of this type and name. Its word is final: files.frame refuses any other with 409 no_frame_wanted. */
+export function takesFrame(contentType, name) {
+    const type = (contentType ?? "").toLowerCase();
+    const dot = name.lastIndexOf(".");
+    const ext = dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
+    return (type.startsWith("video/") && type !== "video/mp2t") || VIDEO_EXTENSIONS.has(ext);
+}
+/**
+ * Sends a JPEG of a video's frame to be its picture: asks files.frame where,
+ * and puts it there. Throws if it is not a JPEG of at most FRAME_MAX_BYTES,
+ * if the service wants none for the file (409 no_frame_wanted: not a video,
+ * protected, or given one already), or if storage refuses it.
+ */
+export async function sendFrame(frame, fetcher, id, jpeg, options = {}) {
+    const start = new Uint8Array(await jpeg.slice(0, 3).arrayBuffer());
+    if (jpeg.size > FRAME_MAX_BYTES || start[0] !== 0xff || start[1] !== 0xd8 || start[2] !== 0xff) {
+        throw new TypeError(`A video's picture is a JPEG of at most ${FRAME_MAX_BYTES} bytes.`);
+    }
+    const to = await frame(id, options);
+    let res;
+    try {
+        res = await fetcher(to.url, { method: "PUT", headers: to.headers, body: jpeg, signal: options.signal });
+    }
+    catch (e) {
+        if (options.signal?.aborted)
+            throw options.signal.reason;
+        throw new FileFreakError(0, "network_error", `Storage could not be reached: ${e instanceof Error ? e.message : String(e)}.`);
+    }
+    await res.body?.cancel().catch(() => undefined);
+    if (!res.ok)
+        throw new FileFreakError(res.status, "storage_refused", `Storage refused the picture with ${res.status}.`);
+}
+/** The page this runs in, or null outside a web page: in Node, or in a worker. */
+function page() {
+    const document = globalThis.document;
+    return typeof document?.createElement === "function" ? document : null;
+}
+/** Whether this is a web page, which can draw a video. */
+export function canDrawFrames() {
+    return page() !== null && typeof URL.createObjectURL === "function";
+}
+/**
+ * A frame about a second in, or halfway through a shorter video, as a JPEG,
+ * or null where this browser cannot play the video or draw it. A second in
+ * rather than the first frame, which is black more often than not.
+ */
+export async function drawFrame(video) {
+    const document = page();
+    if (!document)
+        return null;
+    const element = document.createElement("video");
+    const src = URL.createObjectURL(video);
+    element.muted = true;
+    element.playsInline = true;
+    element.preload = "auto";
+    try {
+        await within(new Promise((resolve, reject) => {
+            element.addEventListener("loadedmetadata", () => resolve(), { once: true });
+            element.addEventListener("error", () => reject(new Error("cannot play")), { once: true });
+            element.src = src;
+        }));
+        const at = Number.isFinite(element.duration) && element.duration > 0 ? Math.min(1, element.duration / 2) : 0;
+        await within(new Promise((resolve, reject) => {
+            element.addEventListener("seeked", () => resolve(), { once: true });
+            element.addEventListener("error", () => reject(new Error("cannot seek")), { once: true });
+            element.currentTime = at;
+        }));
+        if (!element.videoWidth || !element.videoHeight)
+            return null;
+        const scale = Math.min(1, EDGE / Math.max(element.videoWidth, element.videoHeight));
+        const canvas = document.createElement("canvas");
+        canvas.width = Math.max(1, Math.round(element.videoWidth * scale));
+        canvas.height = Math.max(1, Math.round(element.videoHeight * scale));
+        const context = canvas.getContext("2d");
+        if (!context)
+            return null;
+        context.drawImage(element, 0, 0, canvas.width, canvas.height);
+        return await new Promise((resolve) => canvas.toBlob(resolve, "image/jpeg", 0.85));
+    }
+    catch {
+        // A video this browser cannot play.
+        return null;
+    }
+    finally {
+        element.removeAttribute("src");
+        element.load();
+        URL.revokeObjectURL(src);
+    }
+}
+function within(work) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error("too slow")), WAIT_MS);
+        work.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (e) => {
+            clearTimeout(timer);
+            reject(e instanceof Error ? e : new Error(String(e)));
+        });
+    });
+}

package/dist/generated.d.ts

@@ -23,6 +23,10 @@ export interface Item {
     revision: number;
     /** The SHA-256 the uploader gave when it completed the upload of this content, in lower-case hex, or null. The uploader's word: this service never sees a file's bytes and does not check it. */
     clientSha256: string | null;
+    /** A small picture of the file, as WebP no more than 480 pixels on its longest side, once the service has made one: of an image, a photo from an iPhone, a PDF's first page, the cover in an audio file's tags, or a frame of a video, sent with files.frame. Made within a few minutes of an upload. The address is on storage itself and needs no key. It is the same for the rest of the day, so that it can be cached, and works for a day after that. Fetching it counts as nothing. Null for a folder, and for a file with none. */
+    thumbnailUrl: string | null;
+    /** The first lines of a text or code file, a Word or OpenDocument text, a deck's first slide or the top left of a spreadsheet's first sheet, as UTF-8 text, once the service has made them, at an address like thumbnailUrl's. Never of a file whose name says it holds keys or passwords. Null otherwise. */
+    previewTextUrl: string | null;
     /** Whether the file is under Shard Protection: kept as sealed fragments, and read through its map (files.shards) rather than from an address. */
     protected: boolean;
     /** Its own Shard Protection setting. inherit follows the nearest folder above it that has one, and with none the drive's default: the app's, which its owner turns on from the app's page, or for a device the account's. The nearest setting wins. A file is converted within a few minutes of a change, and protected says when it has been. */
@@ -153,11 +157,13 @@ export interface SendTo {
 }
 /** A page of a protected file's map: its key, and where each fragment is. */
 export interface ShardMap {
-    /** The content's own id, which each fragment's check is bound to with its place and the count. */
+    /** The content's own id, which each fragment's check is bound to with its place and the count, and in version 2 the outline. */
     contentId: string;
+    /** The version of the shard format the file is written in: 1, or 2, in which the file is cut into blocks by its content and its next version keeps the blocks that did not change. Only a version named in formats is answered. */
+    format: number;
     /** The file's size. */
     sizeBytes: number;
-    /** How many bytes of the file each fragment holds, except the last, which holds what remains. */
+    /** How many bytes of the file each fragment holds, except the last, which holds what remains. In version 2, the largest block's: each block's own length is in the outline. */
     fragmentBytes: number;
     /** How many fragments the file is. */
     count: number;
@@ -167,11 +173,23 @@ export interface ShardMap {
     contentType: string | null;
     /** The file's revision whose content this is. Its fragments never change, however late they are read. */
     revision: number;
+    /** Version 2, on the first page: every block of the file and the MAC over them. Null on a later page, and in version 1. */
+    outline: {
+        /** The MAC over the content id, the size and every block's id and length, in base64. Check it with the file's key, as the SDK's checkOutline does, before using a byte of the file. */
+        mac: string;
+        /** Every block of the file, in order of place. */
+        blocks: Array<{
+            /** The block's id in base64: 32 bytes, the HMAC of its bytes under the file's key. Each block is checked against it once opened. */
+            id: string;
+            /** How many bytes of the file the block holds. */
+            length: number;
+        }>;
+    } | null;
     /** The first place on this page. */
     from: number;
     /** Up to 1000, in order of place. */
     fragments: Array<{
-        /** Counted from zero. Its bytes of the file begin at place times fragmentBytes. */
+        /** Counted from zero. In version 1 its bytes of the file begin at place times fragmentBytes; in version 2 after the blocks before it in the outline. */
         place: number;
         /** Where to fetch the stored fragment, with a plain GET and no key: the address is the permission. */
         url: string;
@@ -310,6 +328,8 @@ export type UploadsBeginBody = {
     }>;
     /** true when this program can seal fragments as it sends them, as the SDK and the CLI do. Into a protected place the answer's shards is then set, and each part is a fragment. */
     protectable?: boolean;
+    /** With protectable: the versions of the shard format this program can write. Left out, 1 alone. With 2, a sealed file of more than 16 MiB is written in version 2. */
+    shardFormats?: Array<number>;
 };
 /** What POST /v1/uploads answers with. */
 export type UploadsBeginAnswer = {
@@ -320,11 +340,13 @@ export type UploadsBeginAnswer = {
     reused: Array<number>;
     /** Set when the upload is sealed as it is sent: how the file is cut into fragments. The key to seal them with is given by uploads.get. Null for an upload sent as it is. */
     shards: {
-        /** The content's own id, which each fragment's seal is bound to with its place and the count. */
+        /** The version of the shard format to write it in: 1, or 2 when shardFormats names it and the file is large enough. */
+        format: number;
+        /** The content's own id, which each fragment's seal is bound to with its place and the count, and in version 2 the outline. */
         contentId: string;
-        /** How many bytes of the file each fragment holds, except the last, which holds what remains. */
+        /** How many bytes of the file each fragment holds, except the last, which holds what remains. In version 2, 0: the blocks are declared with uploads.blocks. */
         fragmentBytes: number;
-        /** How many fragments, one to each part. */
+        /** How many fragments, one to each part. In version 2, 0 until the blocks are declared. */
         count: number;
     } | null;
 };
@@ -342,16 +364,42 @@ export type UploadsGetAnswer = {
     reused: Array<number>;
     /** For an upload sealed as it is sent: how the file is cut, and the key to seal each fragment with. Null for an upload sent as it is, and for one that has ended. */
     shards: {
-        /** The content's own id, which each fragment's seal is bound to with its place and the count. */
+        /** The version of the shard format to write it in. */
+        format: number;
+        /** The content's own id, which each fragment's seal is bound to with its place and the count, and in version 2 the outline. */
         contentId: string;
         /** The file's own key, in base64: 32 bytes, which open its fragments. In this answer and nowhere else. */
         key: string;
-        /** How many bytes of the file each fragment holds, except the last, which holds what remains. */
+        /** How many bytes of the file each fragment holds, except the last, which holds what remains. In version 2, the largest block's once they are declared, and 0 before. */
         fragmentBytes: number;
-        /** How many fragments, one to each part. */
+        /** How many fragments, one to each part. In version 2, how many blocks once they are declared, and 0 before. */
         count: number;
+        /** Version 2: the blocks as declared, in order, or null until they are. Null in version 1. */
+        blocks: Array<{
+            size: number;
+            /** Its id, in base64. */
+            id: string;
+        }> | null;
     } | null;
 };
+/** What POST /v1/uploads/:id/blocks takes as its body. */
+export type UploadsBlocksBody = {
+    /** Every block of the file, in order. */
+    blocks: Array<{
+        /** How many bytes of the file the block holds. */
+        size: number;
+        /** The block's id, in base64: 32 bytes. */
+        id: string;
+    }>;
+};
+/** What POST /v1/uploads/:id/blocks answers with. */
+export type UploadsBlocksAnswer = {
+    upload: Upload;
+    /** The places whose block the file has already, under its key. Never sent, and counted as arrived. */
+    reused: Array<number>;
+    /** Addresses for the first blocks to send, each at its place. Places in reused are not among them. */
+    parts: Array<Part>;
+};
 /** What GET /v1/uploads/:id/parts takes in its query. */
 export type UploadsPartsQuery = {
     /** The first part wanted, counted from zero. */
@@ -380,6 +428,8 @@ export type UploadsFragmentsAnswer = {
 export type UploadsCompleteBody = {
     /** The file's SHA-256 in hex, as you worked it out. Kept with the file as your word, since this service never sees the bytes, and given back as clientSha256, so a copy can be checked later without reading the file again. */
     sha256?: string;
+    /** For an upload written in version 2 of the shard format, and required for one: the outline's MAC in base64, as the SDK's outlineMac makes it from the content id, the size and the declared blocks. Checked with the file's key. */
+    outline?: string;
 };
 /** What POST /v1/uploads/:id/complete answers with. */
 export type UploadsCompleteAnswer = {
@@ -387,6 +437,15 @@ export type UploadsCompleteAnswer = {
 } | Pending;
 /** What DELETE /v1/uploads/:id answers with. */
 export type UploadsCancelAnswer = Ok;
+/** What POST /v1/files/:id/frame answers with. */
+export type FilesFrameAnswer = {
+    /** Where to PUT the JPEG. Needs no key: the address is the permission. */
+    url: string;
+    /** Headers the request must carry. */
+    headers: Record<string, string>;
+    /** When the address stops working. */
+    expiresAt: string;
+};
 /** What GET /v1/files/:id/download takes in its query. */
 export type FilesDownloadUrlQuery = {
     /** true to have a browser show it, for the types that are safe to show. Anything else is saved, whatever is asked. */
@@ -404,6 +463,8 @@ export type FilesDownloadUrlAnswer = {
 export type FilesShardsQuery = {
     /** The first fragment wanted, counted from zero: 0, or the `next` of the page before. */
     from?: number;
+    /** The versions of the shard format this program reads, as 1,2. Left out, 1 alone. */
+    formats?: string;
 };
 /** What GET /v1/files/:id/shards answers with. */
 export type FilesShardsAnswer = ShardMap;
@@ -676,6 +737,12 @@ export declare const OPERATIONS: {
         readonly idempotent: false;
         readonly repeatable: false;
     };
+    readonly "uploads.blocks": {
+        readonly method: "POST";
+        readonly path: "/v1/uploads/:id/blocks";
+        readonly idempotent: false;
+        readonly repeatable: true;
+    };
     readonly "uploads.parts": {
         readonly method: "GET";
         readonly path: "/v1/uploads/:id/parts";
@@ -700,6 +767,12 @@ export declare const OPERATIONS: {
         readonly idempotent: false;
         readonly repeatable: false;
     };
+    readonly "files.frame": {
+        readonly method: "POST";
+        readonly path: "/v1/files/:id/frame";
+        readonly idempotent: false;
+        readonly repeatable: false;
+    };
     readonly "files.downloadUrl": {
         readonly method: "GET";
         readonly path: "/v1/files/:id/download";
@@ -870,6 +943,14 @@ export declare function bind(call: Call): {
          * POST /v1/files/:id/restore. Needs the scope files:write.
          */
         restore: (id: string, options?: CallOptions) => Promise<FilesRestoreAnswer>;
+        /**
+         * Give a video its picture.
+         *
+         * The service never reads a video, so a video's picture (its thumbnailUrl) is a frame of it that a program sends. This answers where to send one: PUT a JPEG of at most 2 MB to url, with headers, within 2 minutes, so have it ready before asking. The service makes it small and keeps it, and the video's thumbnailUrl gives it within a few minutes. Anything else sent is not made into a picture. Once for each video: one that has been sent a picture, or was given an address for one in the last few minutes, is answered with 409 no_frame_wanted. In a web page, the SDK's upload draws a frame about a second in and sends it itself; anywhere else, the SDK's files.sendFrame sends a JPEG made by anything that can make one, ffmpeg for one. A file under Shard Protection is given no picture, and is answered with 409 no_frame_wanted.
+         *
+         * POST /v1/files/:id/frame. Needs the scope files:write.
+         */
+        frame: (id: string, options?: CallOptions) => Promise<FilesFrameAnswer>;
         /**
          * An address to download a file from.
          *
@@ -883,6 +964,8 @@ export declare function bind(call: Call): {
          *
          * A file under Shard Protection is kept as fragments, each sealed with the file's own key and stored across several storage accounts. Its map says where each fragment is, up to 1,000 at a time, with the key. Fetch each fragment from its address (no key: the address is the permission), check and open it as the SDK's openFragment does, and write it at its place. The first page counts the file's size toward the month's downloads; later pages count nothing. Addresses work for four hours: before then, ask for the page again from the first fragment not yet fetched. The key is in this answer and nowhere else. This API never keeps it, and neither should a program, beyond the read.
          *
+         * A file in version 2 of the shard format (format 2) is kept as blocks of their own lengths, cut by its content. The first page carries its outline: check it with the key before using a byte, open each block as the SDK's openBlock does, and write it after the blocks before it. A program says which versions it reads with formats, and a file in another is answered with 409 format_unsupported, so a program made before version 2 is told to update rather than failing on the file.
+         *
          * GET /v1/files/:id/shards. Needs the scope files:read.
          */
         shards: (id: string, query?: FilesShardsQuery, options?: CallOptions) => Promise<FilesShardsAnswer>;
@@ -939,6 +1022,8 @@ export declare function bind(call: Call): {
          *
          * Into a place under Shard Protection, an upload begun with protectable true is sealed as it is sent. A place is protected by the setting nearest it (files.update's protection), or with none by the drive's default: an app's, which its owner turns on from the app's page, or for a device the account's. The answer's shards then says how the file is cut, and uploads.get gives its key. Each part is a fragment: the file's bytes from its number times fragmentBytes, sealed with that key as the SDK's sealFragment does, under a nonce of its own, and sent to the part's address. uploads.fragments confirms them, and completing makes the file, protected from its first byte, with a null clientSha256. A sealed upload sets blocks aside: none is kept, and none reused. Begun without protectable, a file lands as an ordinary file and the service protects it within a few minutes; from then on it is read through its map (files.shards).
          *
+         * A program that writes version 2 of the shard format says so with shardFormats. A sealed file of more than 16 MiB is then written in it: shards says format 2, with no fragments and no parts yet. Get the key from uploads.get, cut the file into blocks by its content with it, and declare them with uploads.blocks, which answers with the parts to send. Replacing a file whose content is in version 2, with a key that may read the file, the key is the file's own, and the blocks the file has already are not sent again. Complete it with outline, the outline's MAC.
+         *
          * POST /v1/uploads. Needs the scope files:write. Honours an Idempotency-Key.
          */
         begin: (body: UploadsBeginBody, options?: CallOptions) => Promise<UploadsBeginAnswer>;
@@ -950,6 +1035,14 @@ export declare function bind(call: Call): {
          * GET /v1/uploads/:id. Needs the scope files:write.
          */
         get: (id: string, options?: CallOptions) => Promise<UploadsGetAnswer>;
+        /**
+         * Declare a sealed upload's blocks.
+         *
+         * For an upload written in version 2 of the shard format (its shards say format 2): the blocks the file is cut into by its content with the file's key, in order, each its size and its id, the HMAC of its bytes under the file's key. From 2 to 10,000 blocks of 1 byte to 64 MiB, adding up to sizeBytes. Answers with the places not to send, whose block the file has already under its key, and addresses for the first of the rest: ask for more with uploads.parts, and confirm them with uploads.fragments. Each part is its block, sealed as the SDK's sealBlock does. Declared once: the same blocks again are answered the same, and other blocks are refused with 409 blocks_declared.
+         *
+         * POST /v1/uploads/:id/blocks. Needs the scope files:write. Safe to send again.
+         */
+        blocks: (id: string, body: UploadsBlocksBody, options?: CallOptions) => Promise<UploadsBlocksAnswer>;
         /**
          * Addresses for more parts.
          *

package/dist/generated.js

@@ -16,10 +16,12 @@ export const OPERATIONS = {
     "changes.list": { method: "GET", path: "/v1/changes", idempotent: false, repeatable: false },
     "uploads.begin": { method: "POST", path: "/v1/uploads", idempotent: true, repeatable: false },
     "uploads.get": { method: "GET", path: "/v1/uploads/:id", idempotent: false, repeatable: false },
+    "uploads.blocks": { method: "POST", path: "/v1/uploads/:id/blocks", idempotent: false, repeatable: true },
     "uploads.parts": { method: "GET", path: "/v1/uploads/:id/parts", idempotent: false, repeatable: false },
     "uploads.fragments": { method: "POST", path: "/v1/uploads/:id/fragments", idempotent: false, repeatable: true },
     "uploads.complete": { method: "POST", path: "/v1/uploads/:id/complete", idempotent: false, repeatable: true },
     "uploads.cancel": { method: "DELETE", path: "/v1/uploads/:id", idempotent: false, repeatable: false },
+    "files.frame": { method: "POST", path: "/v1/files/:id/frame", idempotent: false, repeatable: false },
     "files.downloadUrl": { method: "GET", path: "/v1/files/:id/download", idempotent: false, repeatable: false },
     "files.shards": { method: "GET", path: "/v1/files/:id/shards", idempotent: false, repeatable: false },
     "files.image": { method: "GET", path: "/v1/files/:id/image", idempotent: false, repeatable: false },
@@ -93,6 +95,14 @@ export function bind(call) {
              * POST /v1/files/:id/restore. Needs the scope files:write.
              */
             restore: (id, options) => call("files.restore", { params: { id } }, options),
+            /**
+             * Give a video its picture.
+             *
+             * The service never reads a video, so a video's picture (its thumbnailUrl) is a frame of it that a program sends. This answers where to send one: PUT a JPEG of at most 2 MB to url, with headers, within 2 minutes, so have it ready before asking. The service makes it small and keeps it, and the video's thumbnailUrl gives it within a few minutes. Anything else sent is not made into a picture. Once for each video: one that has been sent a picture, or was given an address for one in the last few minutes, is answered with 409 no_frame_wanted. In a web page, the SDK's upload draws a frame about a second in and sends it itself; anywhere else, the SDK's files.sendFrame sends a JPEG made by anything that can make one, ffmpeg for one. A file under Shard Protection is given no picture, and is answered with 409 no_frame_wanted.
+             *
+             * POST /v1/files/:id/frame. Needs the scope files:write.
+             */
+            frame: (id, options) => call("files.frame", { params: { id } }, options),
             /**
              * An address to download a file from.
              *
@@ -106,6 +116,8 @@ export function bind(call) {
              *
              * A file under Shard Protection is kept as fragments, each sealed with the file's own key and stored across several storage accounts. Its map says where each fragment is, up to 1,000 at a time, with the key. Fetch each fragment from its address (no key: the address is the permission), check and open it as the SDK's openFragment does, and write it at its place. The first page counts the file's size toward the month's downloads; later pages count nothing. Addresses work for four hours: before then, ask for the page again from the first fragment not yet fetched. The key is in this answer and nowhere else. This API never keeps it, and neither should a program, beyond the read.
              *
+             * A file in version 2 of the shard format (format 2) is kept as blocks of their own lengths, cut by its content. The first page carries its outline: check it with the key before using a byte, open each block as the SDK's openBlock does, and write it after the blocks before it. A program says which versions it reads with formats, and a file in another is answered with 409 format_unsupported, so a program made before version 2 is told to update rather than failing on the file.
+             *
              * GET /v1/files/:id/shards. Needs the scope files:read.
              */
             shards: (id, query, options) => call("files.shards", { params: { id }, query }, options),
@@ -162,6 +174,8 @@ export function bind(call) {
              *
              * Into a place under Shard Protection, an upload begun with protectable true is sealed as it is sent. A place is protected by the setting nearest it (files.update's protection), or with none by the drive's default: an app's, which its owner turns on from the app's page, or for a device the account's. The answer's shards then says how the file is cut, and uploads.get gives its key. Each part is a fragment: the file's bytes from its number times fragmentBytes, sealed with that key as the SDK's sealFragment does, under a nonce of its own, and sent to the part's address. uploads.fragments confirms them, and completing makes the file, protected from its first byte, with a null clientSha256. A sealed upload sets blocks aside: none is kept, and none reused. Begun without protectable, a file lands as an ordinary file and the service protects it within a few minutes; from then on it is read through its map (files.shards).
              *
+             * A program that writes version 2 of the shard format says so with shardFormats. A sealed file of more than 16 MiB is then written in it: shards says format 2, with no fragments and no parts yet. Get the key from uploads.get, cut the file into blocks by its content with it, and declare them with uploads.blocks, which answers with the parts to send. Replacing a file whose content is in version 2, with a key that may read the file, the key is the file's own, and the blocks the file has already are not sent again. Complete it with outline, the outline's MAC.
+             *
              * POST /v1/uploads. Needs the scope files:write. Honours an Idempotency-Key.
              */
             begin: (body, options) => call("uploads.begin", { body }, options),
@@ -173,6 +187,14 @@ export function bind(call) {
              * GET /v1/uploads/:id. Needs the scope files:write.
              */
             get: (id, options) => call("uploads.get", { params: { id } }, options),
+            /**
+             * Declare a sealed upload's blocks.
+             *
+             * For an upload written in version 2 of the shard format (its shards say format 2): the blocks the file is cut into by its content with the file's key, in order, each its size and its id, the HMAC of its bytes under the file's key. From 2 to 10,000 blocks of 1 byte to 64 MiB, adding up to sizeBytes. Answers with the places not to send, whose block the file has already under its key, and addresses for the first of the rest: ask for more with uploads.parts, and confirm them with uploads.fragments. Each part is its block, sealed as the SDK's sealBlock does. Declared once: the same blocks again are answered the same, and other blocks are refused with 409 blocks_declared.
+             *
+             * POST /v1/uploads/:id/blocks. Needs the scope files:write. Safe to send again.
+             */
+            blocks: (id, body, options) => call("uploads.blocks", { params: { id }, body }, options),
             /**
              * Addresses for more parts.
              *

package/dist/index.d.ts

@@ -1,7 +1,8 @@
 export { FileFreak, Walk, type DownloadOptions, type FollowOptions } from "./client.js";
 export * from "./generated.js";
+export { FRAME_MAX_BYTES, takesFrame } from "./frames.js";
 export { get, type GetOptions, type Got, type Into, type LinkedFile } from "./links.js";
 export { type Sink } from "./ranges.js";
-export { checkOutline, fileKeys, MOST_BLOCK_BYTES, openBlock, openFragment, outlineMac, sealBlock, sealFragment, SHARD_OVERHEAD, SHARD_VERSION, SHARD_VERSION_2, ShardError, shardKey, ShardLayout, type FileKeys, type FragmentAt, type Outline, type OutlineBlock, type ShardErrorCode, type ShardKey, } from "./shards.js";
+export { BlockLayout, checkOutline, fileKeys, MOST_BLOCK_BYTES, openBlock, openFragment, outlineMac, READS_FORMATS, sealBlock, sealFragment, SHARD_OVERHEAD, SHARD_VERSION, SHARD_VERSION_2, ShardError, shardKey, ShardLayout, type FileKeys, type FragmentAt, type Layout, type Outline, type OutlineBlock, type ShardErrorCode, type ShardKey, } from "./shards.js";
 export { FileFreakError, type CallOptions, type ClientOptions, type TokenSource } from "./transport.js";
 export { UploadStopped, type Source, type UploadOptions } from "./uploads.js";

package/dist/index.js

@@ -11,7 +11,8 @@
 //   await get("https://filefreak.link/share/...", toFolder("downloads"));
 export { FileFreak, Walk } from "./client.js";
 export * from "./generated.js";
+export { FRAME_MAX_BYTES, takesFrame } from "./frames.js";
 export { get } from "./links.js";
-export { checkOutline, fileKeys, MOST_BLOCK_BYTES, openBlock, openFragment, outlineMac, sealBlock, sealFragment, SHARD_OVERHEAD, SHARD_VERSION, SHARD_VERSION_2, ShardError, shardKey, ShardLayout, } from "./shards.js";
+export { BlockLayout, checkOutline, fileKeys, MOST_BLOCK_BYTES, openBlock, openFragment, outlineMac, READS_FORMATS, sealBlock, sealFragment, SHARD_OVERHEAD, SHARD_VERSION, SHARD_VERSION_2, ShardError, shardKey, ShardLayout, } from "./shards.js";
 export { FileFreakError } from "./transport.js";
 export { UploadStopped } from "./uploads.js";

package/dist/links.js

@@ -17,6 +17,7 @@
 // API call is counted, since no key is used.
 import { fetchRanges } from "./ranges.js";
 import { asItIsKept, readProtected } from "./reader.js";
+import { READS_FORMATS, SHARD_VERSION } from "./shards.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). */
@@ -106,8 +107,30 @@ class Reader {
             this.fail();
         if (!isCount(v.sizeBytes) || !isCount(v.fragmentBytes) || !isCount(v.count) || !Array.isArray(v.fragments))
             this.fail();
+        // A site from before version 2 of the format says no version, and every file it has is in version 1.
+        const format = v.format === undefined ? SHARD_VERSION : v.format;
+        if (!isCount(format))
+            this.fail();
+        const outline = v.outline === undefined || v.outline === null ? null : this.outline(v.outline);
         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 };
+        return {
+            contentId: v.contentId,
+            format,
+            sizeBytes: v.sizeBytes,
+            fragmentBytes: v.fragmentBytes,
+            count: v.count,
+            key: v.key,
+            outline,
+            fragments,
+            expiresAt: v.expiresAt,
+            grant: v.grant,
+        };
+    }
+    outline(v) {
+        if (!isObject(v) || typeof v.mac !== "string" || !Array.isArray(v.blocks))
+            this.fail();
+        const blocks = v.blocks.map((b) => (isObject(b) && typeof b.id === "string" && isCount(b.length) ? { id: b.id, length: b.length } : this.fail()));
+        return { mac: v.mac, blocks };
     }
 }
 /** The link's own site, asked with nothing that says who is asking. */
@@ -216,7 +239,7 @@ async function openShare(site, token, password) {
         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)),
+        page: async (id, from, read, signal) => site.read.map(await site.ask(`${base}/files/${id}/shards?from=${from}&formats=${READS_FORMATS}`, { share, read }, undefined, signal)),
     };
 }
 async function openPublic(site, id, username) {
@@ -232,7 +255,7 @@ async function openPublic(site, id, username) {
         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)),
+        page: async (file, from, read, signal) => site.read.map(await site.ask(`/api/public/files/${file}/shards?from=${from}&formats=${READS_FORMATS}`, { read }, undefined, signal)),
     };
 }
 /** Every file in a shared folder, with the folders it is in, read folder by folder. */

package/dist/reader.d.ts

@@ -10,11 +10,22 @@ export declare const NOT_FETCHED = "Part of this file could not be fetched from
 /** A page of a protected file's map, as the reader uses it: files.shards's answer, or a link's. */
 export interface MapPage {
     contentId: string;
+    /** The version of the shard format the file is in, 1 or 2. */
+    format: number;
     sizeBytes: number;
+    /** In version 2, the largest block. */
     fragmentBytes: number;
     count: number;
     /** The file's key, in base64. */
     key: string;
+    /** In version 2, on the first page only: the outline's MAC, and each block's id and length, in base64. */
+    outline: {
+        mac: string;
+        blocks: ReadonlyArray<{
+            id: string;
+            length: number;
+        }>;
+    } | null;
     fragments: ReadonlyArray<{
         place: number;
         url: string;

package/dist/reader.js

@@ -28,7 +28,13 @@
 //
 // The key is a WebCrypto key that cannot be exported, held inside one read
 // and let go of with it. No error here carries it.
-import { openFragment, ShardError, shardKey, ShardLayout, SHARD_OVERHEAD } from "./shards.js";
+//
+// A file in version 2 of the format is read the same way, a block at each
+// place, once its outline is checked: the map's first page carries it, and
+// nothing is fetched until its MAC holds under the file's key, since a map
+// whose blocks were reordered or swapped would otherwise be written out in
+// the wrong order with every block passing its own check.
+import { BlockLayout, checkOutline, fileKeys, openBlock, openFragment, ShardError, shardKey, ShardLayout, SHARD_OVERHEAD, SHARD_VERSION, SHARD_VERSION_2, } from "./shards.js";
 import { backoff, FileFreakError, sleep } from "./transport.js";
 const MIB = 1024 * 1024;
 /** The most bytes of fragments being fetched, or fetched and not yet written, at once in this program: five of the largest. */
@@ -131,11 +137,17 @@ function unreadable(what) {
 const damaged = (cause) => stopped("fragment_damaged", NOT_WHAT_WAS_STORED, cause);
 const notFetched = (cause) => stopped("fragment_unavailable", NOT_FETCHED, cause);
 /**
- * A page whose count, or one of whose places, the file's size and fragment
- * size do not allow: a map that does not add up is not read from.
+ * A page whose count, or one of whose places, the file's layout does not
+ * allow: a map that does not add up is not read from. In version 2 its
+ * count and fragment size are the outline's, its block count and largest.
  */
 function agrees(page, layout) {
-    if (page.count !== layout.count) {
+    if (layout instanceof BlockLayout) {
+        if (page.count !== layout.count || page.fragmentBytes !== layout.fragmentSize) {
+            throw stopped("layout", `This file's map does not add up: it says ${page.count} blocks of at most ${page.fragmentBytes} bytes, and its outline names ${layout.count} of at most ${layout.fragmentSize}. Nothing was saved.`);
+        }
+    }
+    else if (page.count !== layout.count) {
         throw stopped("layout", `This file's map does not add up: it says ${page.count} fragments, where ${layout.size} bytes in fragments of ${layout.fragmentSize} make ${layout.count}. Nothing was saved.`);
     }
     const wrong = page.fragments.find((f) => !Number.isInteger(f.place) || f.place < 0 || f.place >= layout.count);
@@ -143,17 +155,50 @@ function agrees(page, layout) {
         throw stopped("layout", `This file's map names fragment ${wrong.place}, and the file has ${layout.count}, numbered from 0. Nothing was saved.`);
     }
 }
-async function keyOf(text) {
-    let raw;
+/** Base64 from the map, as bytes, or the map is unreadable. */
+function bytesOf(text, what) {
     try {
-        raw = Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
+        return Uint8Array.from(atob(text), (c) => c.charCodeAt(0));
     }
     catch {
-        throw unreadable("key");
+        throw unreadable(what);
     }
+}
+/**
+ * The file's pieces as its first page describes them. In version 2 the
+ * outline is checked under the key here, before a block is fetched, and one
+ * that fails is the same failure as a fragment that fails its check.
+ */
+async function piecesOf(first) {
+    const raw = bytesOf(first.key, "key");
     if (raw.length !== 32)
         throw unreadable("key");
-    return await shardKey(raw);
+    try {
+        if (first.format === SHARD_VERSION) {
+            const layout = new ShardLayout(first.sizeBytes, first.fragmentBytes);
+            const key = await shardKey(raw);
+            return { layout, open: (place, blob) => openFragment(key, { contentId: first.contentId, layout, place }, blob) };
+        }
+        if (first.format === SHARD_VERSION_2) {
+            if (!first.outline)
+                throw unreadable("outline");
+            const outline = {
+                contentId: first.contentId,
+                size: first.sizeBytes,
+                blocks: first.outline.blocks.map((b) => ({ id: bytesOf(b.id, "outline"), length: b.length })),
+            };
+            const layout = new BlockLayout(outline);
+            const keys = await fileKeys(raw);
+            await checkOutline(keys, outline, bytesOf(first.outline.mac, "outline"));
+            return { layout, open: (place, blob) => openBlock(keys, outline.blocks[place], blob) };
+        }
+    }
+    catch (e) {
+        if (e instanceof ShardError)
+            throw e.code === "layout" ? stopped("layout", `${e.message} Nothing was saved.`) : damaged(e);
+        throw e;
+    }
+    throw stopped("format_unsupported", `This file is in version ${first.format} of the shard format, which this version of the SDK does not read. Update it to read the file.`);
 }
 /**
  * Read the protected file whose map `pages` gives into `sink`. Resolves once
@@ -172,19 +217,11 @@ export async function readProtected(options) {
         const first = await options.pages(0, stop.signal);
         if (options.sizeBytes !== undefined && first.sizeBytes !== options.sizeBytes)
             throw stopped("content_changed", CHANGED);
-        let layout;
-        try {
-            layout = new ShardLayout(first.sizeBytes, first.fragmentBytes);
-        }
-        catch (e) {
-            if (e instanceof ShardError)
-                throw stopped("layout", `${e.message} Nothing was saved.`);
-            throw e;
-        }
-        agrees(first, layout);
         if (!UUID.test(first.contentId))
             throw unreadable("content id");
-        const reading = new Reading(options, stop, layout, first.contentId, await keyOf(first.key));
+        const pieces = await piecesOf(first);
+        agrees(first, pieces.layout);
+        const reading = new Reading(options, stop, pieces, first.contentId, first.format);
         reading.hold(first);
         await reading.fill();
     }
@@ -216,9 +253,9 @@ export async function asItIsKept(isProtected, plain, mapped) {
 class Reading {
     options;
     stop;
-    layout;
+    pieces;
     contentId;
-    key;
+    format;
     addresses = new Map();
     /** Held while a page is asked for, so that fragments waiting on the same page ask once. */
     asking = new Gate(1);
@@ -230,13 +267,15 @@ class Reading {
     wait;
     now;
     quietMs;
+    layout;
     written = 0;
-    constructor(options, stop, layout, contentId, key) {
+    constructor(options, stop, pieces, contentId, format) {
         this.options = options;
         this.stop = stop;
-        this.layout = layout;
+        this.pieces = pieces;
         this.contentId = contentId;
-        this.key = key;
+        this.format = format;
+        this.layout = pieces.layout;
         this.budget = options.budget ?? shared();
         this.fetcher = options.fetch ?? fetch.bind(globalThis);
         this.wait = options.sleep ?? sleep;
@@ -248,7 +287,10 @@ class Reading {
     }
     /** Keep a page's addresses, once it is known to be a page of this file's map. */
     hold(page) {
-        if (page.contentId !== this.contentId || page.sizeBytes !== this.layout.size || page.fragmentBytes !== this.layout.fragmentSize) {
+        if (page.contentId !== this.contentId ||
+            page.format !== this.format ||
+            page.sizeBytes !== this.layout.size ||
+            page.fragmentBytes !== this.layout.fragmentSize) {
             throw stopped("content_changed", CHANGED);
         }
         agrees(page, this.layout);
@@ -424,7 +466,7 @@ class Reading {
         }
         let plain;
         try {
-            plain = await openFragment(this.key, { contentId: this.contentId, layout: this.layout, place }, blob);
+            plain = await this.pieces.open(place, blob);
         }
         catch (e) {
             throw damaged(e);

package/dist/shards.d.ts

@@ -25,6 +25,8 @@ export declare class ShardLayout {
     };
     /** How many bytes of the file fragment `place` holds. */
     length(place: number): number;
+    /** The place of the fragment that holds byte `offset` of the file. */
+    placeAt(offset: number): number;
 }
 /**
  * A content's key as WebCrypto holds it. Named through crypto.subtle and not
@@ -59,6 +61,8 @@ export declare function sealWithNonce(key: ShardKey, at: FragmentAt, plaintext:
  */
 export declare function openFragment(key: ShardKey, at: FragmentAt, blob: Uint8Array): Promise<Uint8Array<ArrayBuffer>>;
 export declare const SHARD_VERSION_2 = 2;
+/** The versions of the format this reads, as a reader asks for a map in them (formats). */
+export declare const READS_FORMATS = "1,2";
 /** The most bytes of a file one block holds, as the API takes blocks. */
 export declare const MOST_BLOCK_BYTES: number;
 /** A block id: the HMAC-SHA256 of its bytes under the file's block key. */
@@ -108,6 +112,33 @@ export declare function sealBlockWithNonce(keys: FileKeys, id: Uint8Array, plain
  * returned.
  */
 export declare function openBlock(keys: FileKeys, block: OutlineBlock, blob: Uint8Array): Promise<Uint8Array<ArrayBuffer>>;
+/**
+ * Where each block of a file in version 2 is, from its outline: what
+ * ShardLayout is for version 1, to a reader that writes each block at its
+ * place in the file, or reads a range from the blocks that hold it. It
+ * refuses an outline that describes no file, before anything is fetched by
+ * it; that the outline is the file's is checkOutline's to say.
+ */
+export declare class BlockLayout {
+    readonly size: number;
+    readonly count: number;
+    /** The largest block, which is what a map of a file in version 2 gives as its fragment size. */
+    readonly fragmentSize: number;
+    /** Where each block begins, then the file's size: count + 1 offsets, rising. */
+    private readonly starts;
+    constructor(outline: Outline);
+    /** Where in the file block `place` begins, and where it ends (exclusive). */
+    range(place: number): {
+        start: number;
+        end: number;
+    };
+    /** How many bytes of the file block `place` holds. */
+    length(place: number): number;
+    /** The place of the block that holds byte `offset` of the file: the last that begins at or before it. */
+    placeAt(offset: number): number;
+}
+/** Where each piece of a file is, in either version: the reader's view of it, whichever the map says. */
+export type Layout = ShardLayout | BlockLayout;
 /** The outline's MAC, which the writer sends with the upload's completion and every reader checks before it releases a byte. */
 export declare function outlineMac(keys: FileKeys, outline: Outline): Promise<Uint8Array<ArrayBuffer>>;
 /**

package/dist/shards.js

@@ -60,6 +60,13 @@ export class ShardLayout {
         const { start, end } = this.range(place);
         return end - start;
     }
+    /** The place of the fragment that holds byte `offset` of the file. */
+    placeAt(offset) {
+        if (!Number.isSafeInteger(offset) || offset < 0 || offset >= this.size) {
+            throw new RangeError(`There is no byte ${offset}: this file has ${this.size}, numbered from 0.`);
+        }
+        return Math.floor(offset / this.fragmentSize);
+    }
 }
 /** A content's key, 32 bytes, made usable for its fragments and nothing else. */
 export function shardKey(raw) {
@@ -136,6 +143,8 @@ export async function openFragment(key, at, blob) {
 // Version 2: blocks cut by content, under a file's key that versions share
 // ---------------------------------------------------------------------------
 export const SHARD_VERSION_2 = 2;
+/** The versions of the format this reads, as a reader asks for a map in them (formats). */
+export const READS_FORMATS = `${SHARD_VERSION},${SHARD_VERSION_2}`;
 /** The most bytes of a file one block holds, as the API takes blocks. */
 export const MOST_BLOCK_BYTES = 64 * 1024 * 1024;
 /** A block id: the HMAC-SHA256 of its bytes under the file's block key. */
@@ -249,6 +258,61 @@ function checkShape(outline) {
     if (total !== size)
         throw new ShardError("layout", `The blocks hold ${total} bytes, and the file is ${size}.`);
 }
+/**
+ * Where each block of a file in version 2 is, from its outline: what
+ * ShardLayout is for version 1, to a reader that writes each block at its
+ * place in the file, or reads a range from the blocks that hold it. It
+ * refuses an outline that describes no file, before anything is fetched by
+ * it; that the outline is the file's is checkOutline's to say.
+ */
+export class BlockLayout {
+    size;
+    count;
+    /** The largest block, which is what a map of a file in version 2 gives as its fragment size. */
+    fragmentSize;
+    /** Where each block begins, then the file's size: count + 1 offsets, rising. */
+    starts;
+    constructor(outline) {
+        checkShape(outline);
+        this.size = outline.size;
+        this.count = outline.blocks.length;
+        this.starts = [0];
+        let largest = 0;
+        for (const b of outline.blocks) {
+            this.starts.push(this.starts[this.starts.length - 1] + b.length);
+            largest = Math.max(largest, b.length);
+        }
+        this.fragmentSize = largest;
+    }
+    /** Where in the file block `place` begins, and where it ends (exclusive). */
+    range(place) {
+        if (!Number.isInteger(place) || place < 0 || place >= this.count) {
+            throw new RangeError(`There is no block ${place}: this file has ${this.count}, numbered from 0.`);
+        }
+        return { start: this.starts[place], end: this.starts[place + 1] };
+    }
+    /** How many bytes of the file block `place` holds. */
+    length(place) {
+        const { start, end } = this.range(place);
+        return end - start;
+    }
+    /** The place of the block that holds byte `offset` of the file: the last that begins at or before it. */
+    placeAt(offset) {
+        if (!Number.isSafeInteger(offset) || offset < 0 || offset >= this.size) {
+            throw new RangeError(`There is no byte ${offset}: this file has ${this.size}, numbered from 0.`);
+        }
+        let low = 0;
+        let high = this.count - 1;
+        while (low < high) {
+            const middle = Math.ceil((low + high) / 2);
+            if (this.starts[middle] <= offset)
+                low = middle;
+            else
+                high = middle - 1;
+        }
+        return low;
+    }
+}
 /** The bytes the outline's MAC is over: the label, the content id, the size, the count, and each block's id and length in order. */
 function outlineBytes(outline) {
     const head = OUTLINE_LABEL.length + 16 + 8 + 4;

package/dist/uploads.d.ts

@@ -1,4 +1,4 @@
-import type { FilesGetAnswer, Item, Upload, UploadsBeginAnswer, UploadsBeginBody, UploadsCompleteAnswer, UploadsCompleteBody, UploadsFragmentsAnswer, UploadsFragmentsBody, UploadsGetAnswer, UploadsPartsAnswer, UploadsPartsQuery } from "./generated.js";
+import type { FilesFrameAnswer, FilesGetAnswer, Item, Upload, UploadsBeginAnswer, UploadsBeginBody, UploadsCompleteAnswer, UploadsCompleteBody, UploadsFragmentsAnswer, UploadsFragmentsBody, UploadsGetAnswer, UploadsPartsAnswer, UploadsPartsQuery } from "./generated.js";
 import { type CallOptions } from "./transport.js";
 /** What can be uploaded. A File's name and type are used when none are given. */
 export type Source = Blob | ArrayBuffer | Uint8Array;
@@ -34,6 +34,13 @@ export interface UploadOptions {
     signal?: AbortSignal;
     /** For beginning: the caller's own key, so that a begin sent again makes one upload. */
     idempotencyKey?: string;
+    /**
+     * In a web page, a video is given its picture in listings (its
+     * thumbnailUrl): a frame about a second in, drawn from the file here and
+     * sent once it is stored, without the upload waiting for it. false sends
+     * none. Anywhere else nothing is drawn: send one with files.sendFrame.
+     */
+    frame?: boolean;
 }
 /** An upload that stopped part way. What arrived stays in storage until the upload expires: carry on with `resume: uploadId`, or cancel it. */
 export declare class UploadStopped extends Error {
@@ -48,6 +55,7 @@ export interface UploadCalls {
     fragments(id: string, body: UploadsFragmentsBody, options?: CallOptions): Promise<UploadsFragmentsAnswer>;
     complete(id: string, body?: UploadsCompleteBody, options?: CallOptions): Promise<UploadsCompleteAnswer>;
     file(id: string, options?: CallOptions): Promise<FilesGetAnswer>;
+    frame(id: string, options?: CallOptions): Promise<FilesFrameAnswer>;
 }
 /** The part size to ask for: 32 MiB, halved while that would leave fewer parts than are sent at once. */
 export declare function partSizeFor(fileBytes: number, atOnce: number): number;

package/dist/uploads.js

@@ -30,6 +30,7 @@
 // Carrying on, every fragment not recorded is confirmed before it is sent
 // again, since storage may hold it already. A fragment is up to 64 MiB and
 // sealed in memory, so the memory a sealed upload needs is the same.
+import { canDrawFrames, drawFrame, sendFrame, takesFrame } from "./frames.js";
 import { base64, Md5 } from "./md5.js";
 import { sealFragment, ShardError, shardKey, ShardLayout } from "./shards.js";
 import { FileFreakError, sleep } from "./transport.js";
@@ -170,16 +171,25 @@ export async function upload(calls, fetcher, source, options = {}) {
         }
     }
     options.onBegun?.(job.upload);
+    let item;
     try {
         tally(job, options);
         await deliver(calls, fetcher, job, atOnce, options);
-        return await finish(calls, fetcher, job, atOnce, options);
+        item = await finish(calls, fetcher, job, atOnce, options);
     }
     catch (e) {
         if (signal?.aborted)
             throw signal.reason;
         throw new UploadStopped(job.upload.id, e);
     }
+    if (options.frame !== false && source instanceof Blob && !item.protected && takesFrame(item.contentType, item.name) && canDrawFrames()) {
+        // Not waited for, and nothing said if it fails: the file is stored, and
+        // without a picture a video is listed as it was before there were any.
+        void drawFrame(source)
+            .then((jpeg) => (jpeg ? sendFrame(calls.frame, fetcher, item.id, jpeg) : undefined))
+            .catch(() => undefined);
+    }
+    return item;
 }
 function tally(job, options) {
     let sent = 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@filefreak.io/sdk",
-  "version": "0.3.2",
+  "version": "0.5.0",
   "description": "FileFreak's developer API for Node and the browser: every endpoint, uploads straight to storage in parts, downloads in ranges, and the changes to follow.",
   "license": "Apache-2.0",
   "homepage": "https://filefreak.io/developers/reference",