@filefreak.io/sdk 0.3.2 → 0.4.0

package/README.md

@@ -74,6 +74,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,6 +3,7 @@
 // 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 { FileFreakError, sleep, Transport } from "./transport.js";
@@ -57,7 +58,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 +99,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

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. */
@@ -387,6 +391,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. */
@@ -700,6 +713,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 +889,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.
          *

package/dist/generated.js

@@ -20,6 +20,7 @@ export const OPERATIONS = {
     "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 +94,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.
              *

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 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";

package/dist/index.js

@@ -11,6 +11,7 @@
 //   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 { FileFreakError } from "./transport.js";

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.4.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",