@filefreak.io/sdk 0.1.0 → 0.2.0

package/README.md

@@ -6,8 +6,10 @@ later and in browsers. No dependencies.
 Every endpoint is a function, typed from the same table the API is built
 from. Around them: uploads sent straight to storage in parts and carried on
 after an interruption, downloads fetched in ranges, listings and changes read
-to the end, and requests sent again only when that cannot make anything
-twice. The reference is at https://filefreak.io/developers/reference.
+to the end, files under Shard Protection read through their maps, what a
+share link holds saved with no key, and requests sent again only when that
+cannot make anything twice. The reference is at
+https://filefreak.io/developers/reference.
 
 ## On a server
 
@@ -30,6 +32,8 @@ const bytes = await ff.bytes(file.id); // for a file small enough to hold in mem
 `fromPath` reads the file a part at a time as it is sent, so a file larger
 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.
 
 Keep keys on a server. A key sent from a web page is refused.
 
@@ -66,12 +70,44 @@ 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.
 
+## Saving from a link
+
+`get` saves what a share link or a public page holds. It needs no key, and
+sends nothing that says who is asking: no key, and from a browser no
+cookies. A file goes into one sink; a folder needs somewhere for each of its
+files, which `toFolder` makes on disk.
+
+```ts
+import { get } from "@filefreak.io/sdk";
+import { toFolder, toPath } from "@filefreak.io/sdk/node";
+
+await get("https://filefreak.link/share/...", await toPath("report.pdf"));
+
+const got = await get("https://filefreak.link/share/...", toFolder("downloads"), {
+  password: "open sesame", // for a link that has one
+  onProgress: (written, total) => console.log(`${written} of ${total} bytes`),
+});
+console.log(`${got.files.length} files, ${got.sizeBytes} bytes`);
+```
+
+It takes a share link, a public file's or folder's page, and a file's direct
+address. A folder comes whole: each file goes to the sink the function makes
+for it, given its name and the folders it is in. Each file saved is one of
+the link's downloads, as on its page, and a link with fewer left than there
+are files saves nothing (`not_enough_downloads`). A file under Shard
+Protection is read through the link's map, and counted once.
+
+Every name a link gives is its sharer's, and can be anything: `../../.bashrc`,
+or one that reads backwards. `toFolder` makes each one safe with `safeName`
+before writing, and never writes outside the folder it is given. A program
+that names files from a link itself should use `safeName` too.
+
 ## Every endpoint
 
 The functions are grouped as the reference groups the endpoints:
 `ff.files`, `ff.folders`, `ff.tree`, `ff.changes`, `ff.uploads`, `ff.usage`,
 `ff.me`, `ff.tokens` and `ff.shares` (share links, which only a device signed
-in with `ff login` may make). Ids in the address come first, then the body or
+in with `filefreak login` may make). Ids in the address come first, then the body or
 the query, then options:
 
 ```ts

package/dist/client.d.ts

@@ -66,7 +66,9 @@ export declare class FileFreak {
     /**
      * Fetch a file straight from storage into `sink`: as up to six ranges at
      * once for a large one. One download address is asked for, so the file is
-     * counted toward the month's downloads once. Resolves to the file.
+     * counted toward the month's downloads once. A file under Shard Protection
+     * has no address, and is read through its map instead (files.shards), each
+     * fragment checked as it arrives. Resolves to the file.
      */
     download(id: string, sink: Sink, options?: DownloadOptions): Promise<Item>;
     /** A file's bytes, in memory: for a file small enough to hold. */

package/dist/client.js

@@ -4,6 +4,7 @@
 // ranges, and reading a listing or the changes to the end.
 import { bind, OPERATIONS, } from "./generated.js";
 import { fetchRanges } from "./ranges.js";
+import { asItIsKept, readProtected } from "./reader.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. */
@@ -90,7 +91,9 @@ export class FileFreak {
     /**
      * Fetch a file straight from storage into `sink`: as up to six ranges at
      * once for a large one. One download address is asked for, so the file is
-     * counted toward the month's downloads once. Resolves to the file.
+     * counted toward the month's downloads once. A file under Shard Protection
+     * has no address, and is read through its map instead (files.shards), each
+     * fragment checked as it arrives. Resolves to the file.
      */
     async download(id, sink, options = {}) {
         try {
@@ -117,18 +120,19 @@ export class FileFreak {
         // Nothing to fetch, and an address would count a download of nothing.
         if (item.sizeBytes === 0)
             return;
-        const { url } = await this.files.downloadUrl(item.id, {}, { signal: options.signal });
-        const progress = options.onProgress;
-        await fetchRanges({
-            url,
-            sizeBytes: item.sizeBytes,
+        const { signal, onProgress } = options;
+        const progress = onProgress && ((written) => onProgress(written, item.sizeBytes));
+        await asItIsKept(item.protected, async () => {
+            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 }),
             sink,
-            signal: options.signal,
-            progress: progress && ((written) => progress(written, item.sizeBytes)),
-            ranges: options.ranges,
+            sizeBytes: item.sizeBytes,
+            signal,
+            progress,
             fetch: this.transport.fetch,
-            sleep: (ms) => sleep(ms, options.signal),
-        });
+        }));
     }
 }
 /** Every item in a listing, a page at a time. */

package/dist/generated.d.ts

@@ -23,6 +23,8 @@ 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;
+    /** 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;
     createdAt: string;
     updatedAt: string;
 }
@@ -122,7 +124,7 @@ export interface SiteDeploy {
     number: number;
     /** uploading: files are being declared and sent. ready: every file is stored, and it can be made live. cancelled or expired: given up on, and it holds nothing. */
     state: "uploading" | "ready" | "cancelled" | "expired";
-    /** upload: sent by ff. folder: copied from a folder in the drive, on the website. */
+    /** upload: sent from a computer, by the CLI or a program. folder: copied from a folder in the drive, on the website. */
     source: "upload" | "folder";
     fileCount: number;
     /** What its files add up to. */
@@ -147,6 +149,36 @@ export interface SendTo {
     /** When the address stops working. sites.sendAgain gives fresh ones. */
     expiresAt: string;
 }
+/** 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. */
+    contentId: string;
+    /** The file's size. */
+    sizeBytes: number;
+    /** How many bytes of the file each fragment holds, except the last, which holds what remains. */
+    fragmentBytes: number;
+    /** How many fragments the file is. */
+    count: number;
+    /** The file's own key, in base64: 32 bytes, which open its fragments. In this answer and nowhere else. */
+    key: string;
+    name: string;
+    contentType: string | null;
+    /** The file's revision whose content this is. Its fragments never change, however late they are read. */
+    revision: number;
+    /** 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. */
+        place: number;
+        /** Where to fetch the stored fragment, with a plain GET and no key: the address is the permission. */
+        url: string;
+    }>;
+    /** The from of the next page, or null when this page reaches the last fragment. */
+    next: number | null;
+    /** When this page's addresses stop working. Ask for the page again before then, from the first fragment not yet fetched. */
+    expiresAt: string;
+}
 /** What GET /v1/files takes in its query. */
 export type FilesListQuery = {
     /** The folder to list. Left out, the top of the app (or of the folder the key is confined to). */
@@ -328,6 +360,13 @@ export type FilesDownloadUrlAnswer = {
     inline: boolean;
     contentType: string | null;
 };
+/** What GET /v1/files/:id/shards takes in its query. */
+export type FilesShardsQuery = {
+    /** The first fragment wanted, counted from zero: 0, or the `next` of the page before. */
+    from?: number;
+};
+/** What GET /v1/files/:id/shards answers with. */
+export type FilesShardsAnswer = ShardMap;
 /** What GET /v1/files/:id/image takes in its query. */
 export type FilesImageQuery = {
     /** One of 64, 128, 256, 512, 1024. */
@@ -367,7 +406,7 @@ export type UsageGetAnswer = {
 };
 /** What GET /v1/me answers with. */
 export type MeGetAnswer = {
-    /** key: an app's key, on a server. token: a token a key made for a web page. device: a person, signed in with ff login. */
+    /** key: an app's key, on a server. token: a token a key made for a web page. device: a person, signed in with filefreak login. */
     via: "key" | "token" | "device";
     account: {
         username: string;
@@ -621,6 +660,12 @@ export declare const OPERATIONS: {
         readonly idempotent: false;
         readonly repeatable: false;
     };
+    readonly "files.shards": {
+        readonly method: "GET";
+        readonly path: "/v1/files/:id/shards";
+        readonly idempotent: false;
+        readonly repeatable: false;
+    };
     readonly "files.image": {
         readonly method: "GET";
         readonly path: "/v1/files/:id/image";
@@ -780,11 +825,19 @@ export declare function bind(call: Call): {
         /**
          * An address to download a file from.
          *
-         * A short-lived address on storage itself. Anybody holding it can fetch the file until it expires, with no key, so it can be handed to a browser. Each one issued counts the file's size toward the month's downloads. For an address that does not expire, make the file public and use its publicUrl. A file under Shard Protection is answered with 409 shard_protected: the developer API cannot read protected files yet.
+         * A short-lived address on storage itself. Anybody holding it can fetch the file until it expires, with no key, so it can be handed to a browser. Each one issued counts the file's size toward the month's downloads. For an address that does not expire, make the file public and use its publicUrl. A file under Shard Protection has no address: it is answered with 409 shard_protected, and read through its map with files.shards.
          *
          * GET /v1/files/:id/download. Needs the scope files:read.
          */
         downloadUrl: (id: string, query?: FilesDownloadUrlQuery, options?: CallOptions) => Promise<FilesDownloadUrlAnswer>;
+        /**
+         * A protected file's map.
+         *
+         * 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.
+         *
+         * GET /v1/files/:id/shards. Needs the scope files:read.
+         */
+        shards: (id: string, query?: FilesShardsQuery, options?: CallOptions) => Promise<FilesShardsAnswer>;
         /**
          * An image at a smaller size.
          *
@@ -836,6 +889,8 @@ export declare function bind(call: Call): {
          *
          * The room is set aside now, so an upload that would not fit is refused before a byte is sent. The parts can be sent by anything that can make a PUT request, including a browser that has never seen the API key: hand it the addresses.
          *
+         * Into a folder under Shard Protection, which its owner turns on from the website, a file lands as an ordinary file, as it would anywhere else, and the service protects it within a few minutes: its content, and every kept version, are spread over the storage lanes as fragments. Until then it can be read like any other file. From then on it is read through its map (files.shards), and its clientSha256 is null. An upload from a program is not sealed as it is sent yet.
+         *
          * POST /v1/uploads. Needs the scope files:write. Honours an Idempotency-Key.
          */
         begin: (body: UploadsBeginBody, options?: CallOptions) => Promise<UploadsBeginAnswer>;
@@ -876,7 +931,7 @@ export declare function bind(call: Call): {
         /**
          * What the app is using.
          *
-         * What this app holds, against the ceiling set for it if there is one; and what the account it belongs to has used this calendar month, across its personal files and all its apps, against what its plan includes. An app's files count toward the account's one storage allowance. For a device signed in with ff login, which uses the personal drive, app is null.
+         * What this app holds, against the ceiling set for it if there is one; and what the account it belongs to has used this calendar month, across its personal files and all its apps, against what its plan includes. An app's files count toward the account's one storage allowance. For a device signed in with filefreak login, which uses the personal drive, app is null.
          *
          * GET /v1/usage. Needs the scope usage:read.
          */
@@ -886,7 +941,7 @@ export declare function bind(call: Call): {
         /**
          * Who this is.
          *
-         * The account a key, a token or a device acts for, and what it may do there. A key's program and a page's token are told the account's username and plan, never its email address: only a device signed in with ff login, which is the person, is told that.
+         * The account a key, a token or a device acts for, and what it may do there. A key's program and a page's token are told the account's username and plan, never its email address: only a device signed in with filefreak login, which is the person, is told that.
          *
          * GET /v1/me. Any key may call it.
          */
@@ -896,25 +951,25 @@ export declare function bind(call: Call): {
         /**
          * Make a share link.
          *
-         * A link that opens one file or folder for whoever holds it, separate from making it public: a private file can have one. It can have a password, an end date and a number of downloads after which it stops. Share links are a person's, so only a device signed in with ff login can make them here, as on the website; an app's key cannot.
+         * A link that opens one file or folder for whoever holds it, separate from making it public: a private file can have one. It can have a password, an end date and a number of downloads after which it stops. Share links are a person's, so only a device signed in with filefreak login can make them here, as on the website; an app's key cannot. A link to a file under Shard Protection is a shard link: whoever opens it is given the file's key with its map, so their browser can put the file back together, show it and save it. The storage it is kept in still gives nobody anything on its own.
          *
-         * POST /v1/shares. Only a device signed in with ff login may call it. Honours an Idempotency-Key.
+         * POST /v1/shares. Only a device signed in with filefreak login may call it. Honours an Idempotency-Key.
          */
         create: (body: SharesCreateBody, options?: CallOptions) => Promise<SharesCreateAnswer>;
         /**
          * List share links.
          *
-         * The links on one file or folder, or every link the account has, newest first. Removed links are not listed. Only a device signed in with ff login.
+         * The links on one file or folder, or every link the account has, newest first. Removed links are not listed. Only a device signed in with filefreak login.
          *
-         * GET /v1/shares. Only a device signed in with ff login may call it.
+         * GET /v1/shares. Only a device signed in with filefreak login may call it.
          */
         list: (query?: SharesListQuery, options?: CallOptions) => Promise<SharesListAnswer>;
         /**
          * Remove a share link.
          *
-         * It stops working with the next request, and cannot be brought back. Only a device signed in with ff login.
+         * It stops working with the next request, and cannot be brought back. Only a device signed in with filefreak login.
          *
-         * DELETE /v1/shares/:id. Only a device signed in with ff login may call it.
+         * DELETE /v1/shares/:id. Only a device signed in with filefreak login may call it.
          */
         revoke: (id: string, options?: CallOptions) => Promise<SharesRevokeAnswer>;
     };
@@ -922,9 +977,9 @@ export declare function bind(call: Call): {
         /**
          * List sites.
          *
-         * The account's static sites, by name, with the deploy each serves. A site is a person's, so only a device signed in with ff login reaches sites, as on the website; an app's key cannot. Sites are part of Pro.
+         * The account's static sites, by name, with the deploy each serves. A site is a person's, so only a device signed in with filefreak login reaches sites, as on the website; an app's key cannot. Sites are part of Pro.
          *
-         * GET /v1/sites. Only a device signed in with ff login may call it.
+         * GET /v1/sites. Only a device signed in with filefreak login may call it.
          */
         list: (options?: CallOptions) => Promise<SitesListAnswer>;
         /**
@@ -932,7 +987,7 @@ export declare function bind(call: Call): {
          *
          * A site with no deploy yet. Its name is its address: 3 to 40 lower-case letters, digits and single hyphens, and not a name FileFreak keeps, another account's username, or one that looks like another company's (invalid_site_name, site_name_taken). Refused with sites_need_pro on a plan without sites.
          *
-         * POST /v1/sites. Only a device signed in with ff login may call it. Honours an Idempotency-Key.
+         * POST /v1/sites. Only a device signed in with filefreak login may call it. Honours an Idempotency-Key.
          */
         create: (body: SitesCreateBody, options?: CallOptions) => Promise<SitesCreateAnswer>;
         /**
@@ -940,7 +995,7 @@ export declare function bind(call: Call): {
          *
          * A site, and its deploys newest first. A site keeps its 10 newest deploys that have ended besides the live one.
          *
-         * GET /v1/sites/:id. Only a device signed in with ff login may call it.
+         * GET /v1/sites/:id. Only a device signed in with filefreak login may call it.
          */
         get: (id: string, options?: CallOptions) => Promise<SitesGetAnswer>;
         /**
@@ -948,7 +1003,7 @@ export declare function bind(call: Call): {
          *
          * Begins a deploy with up to 1000 of its files: each one's path, size and SHA-256. Declare the rest with sites.declareFiles, more set to false on the last list. The answer says which files to send: PUT each one's bytes to its address, then call sites.finishDeploy. Bytes the site has stored already are not asked for. A deploy may have 20000 files, 100 MB each and 1 GB together, and what it adds counts as storage from the moment it is declared (quota_exceeded). An unfinished deploy nothing has asked about for an hour is given up on.
          *
-         * POST /v1/sites/:id/deploys. Only a device signed in with ff login may call it. Honours an Idempotency-Key.
+         * POST /v1/sites/:id/deploys. Only a device signed in with filefreak login may call it. Honours an Idempotency-Key.
          */
         startDeploy: (id: string, body: SitesStartDeployBody, options?: CallOptions) => Promise<SitesStartDeployAnswer>;
         /**
@@ -956,7 +1011,7 @@ export declare function bind(call: Call): {
          *
          * The next 1000 files of a deploy at most, as sites.startDeploy takes them. A path declared twice is refused (path_declared_twice).
          *
-         * POST /v1/sites/deploys/:id/files. Only a device signed in with ff login may call it. Honours an Idempotency-Key.
+         * POST /v1/sites/deploys/:id/files. Only a device signed in with filefreak login may call it. Honours an Idempotency-Key.
          */
         declareFiles: (id: string, body: SitesDeclareFilesBody, options?: CallOptions) => Promise<SitesDeclareFilesAnswer>;
         /**
@@ -964,7 +1019,7 @@ export declare function bind(call: Call): {
          *
          * New addresses for files of an unfinished deploy whose bytes have not arrived, when the first ones ran out or a finish answered deploy_incomplete. Files whose bytes have arrived are left out.
          *
-         * POST /v1/sites/deploys/:id/send. Only a device signed in with ff login may call it. Safe to send again.
+         * POST /v1/sites/deploys/:id/send. Only a device signed in with filefreak login may call it. Safe to send again.
          */
         sendAgain: (id: string, body: SitesSendAgainBody, options?: CallOptions) => Promise<SitesSendAgainAnswer>;
         /**
@@ -972,7 +1027,7 @@ export declare function bind(call: Call): {
          *
          * Storage puts each file in place and is asked its size, and the deploy is ready, and live if live is true. Safe to call again: storage may take longer than one request waits, and the answer is then 202 with how long to wait before asking again. A file whose bytes have not arrived, or arrived at another size, is answered with deploy_incomplete and the SHA-256s to send again.
          *
-         * POST /v1/sites/deploys/:id/finish. Only a device signed in with ff login may call it. Safe to send again.
+         * POST /v1/sites/deploys/:id/finish. Only a device signed in with filefreak login may call it. Safe to send again.
          */
         finishDeploy: (id: string, body?: SitesFinishDeployBody, options?: CallOptions) => Promise<SitesFinishDeployAnswer>;
         /**
@@ -980,7 +1035,7 @@ export declare function bind(call: Call): {
          *
          * Cancels a deploy that is uploading, and what it set aside is given back at once. Deletes one that has ended, with whatever bytes no other deploy of the site uses. Never the live one (deploy_live).
          *
-         * DELETE /v1/sites/deploys/:id. Only a device signed in with ff login may call it.
+         * DELETE /v1/sites/deploys/:id. Only a device signed in with filefreak login may call it.
          */
         removeDeploy: (id: string, options?: CallOptions) => Promise<SitesRemoveDeployAnswer>;
         /**
@@ -988,7 +1043,7 @@ export declare function bind(call: Call): {
          *
          * Makes a ready deploy the one visitors are served, which is also how a site is rolled back; null takes the site offline. Visitors see the change within a minute.
          *
-         * POST /v1/sites/:id/live. Only a device signed in with ff login may call it. Safe to send again.
+         * POST /v1/sites/:id/live. Only a device signed in with filefreak login may call it. Safe to send again.
          */
         setLive: (id: string, body: SitesSetLiveBody, options?: CallOptions) => Promise<SitesSetLiveAnswer>;
     };

package/dist/generated.js

@@ -20,6 +20,7 @@ export const OPERATIONS = {
     "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.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 },
     "usage.get": { method: "GET", path: "/v1/usage", idempotent: false, repeatable: false },
     "me.get": { method: "GET", path: "/v1/me", idempotent: false, repeatable: false },
@@ -92,11 +93,19 @@ export function bind(call) {
             /**
              * An address to download a file from.
              *
-             * A short-lived address on storage itself. Anybody holding it can fetch the file until it expires, with no key, so it can be handed to a browser. Each one issued counts the file's size toward the month's downloads. For an address that does not expire, make the file public and use its publicUrl. A file under Shard Protection is answered with 409 shard_protected: the developer API cannot read protected files yet.
+             * A short-lived address on storage itself. Anybody holding it can fetch the file until it expires, with no key, so it can be handed to a browser. Each one issued counts the file's size toward the month's downloads. For an address that does not expire, make the file public and use its publicUrl. A file under Shard Protection has no address: it is answered with 409 shard_protected, and read through its map with files.shards.
              *
              * GET /v1/files/:id/download. Needs the scope files:read.
              */
             downloadUrl: (id, query, options) => call("files.downloadUrl", { params: { id }, query }, options),
+            /**
+             * A protected file's map.
+             *
+             * 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.
+             *
+             * GET /v1/files/:id/shards. Needs the scope files:read.
+             */
+            shards: (id, query, options) => call("files.shards", { params: { id }, query }, options),
             /**
              * An image at a smaller size.
              *
@@ -148,6 +157,8 @@ export function bind(call) {
              *
              * The room is set aside now, so an upload that would not fit is refused before a byte is sent. The parts can be sent by anything that can make a PUT request, including a browser that has never seen the API key: hand it the addresses.
              *
+             * Into a folder under Shard Protection, which its owner turns on from the website, a file lands as an ordinary file, as it would anywhere else, and the service protects it within a few minutes: its content, and every kept version, are spread over the storage lanes as fragments. Until then it can be read like any other file. From then on it is read through its map (files.shards), and its clientSha256 is null. An upload from a program is not sealed as it is sent yet.
+             *
              * POST /v1/uploads. Needs the scope files:write. Honours an Idempotency-Key.
              */
             begin: (body, options) => call("uploads.begin", { body }, options),
@@ -188,7 +199,7 @@ export function bind(call) {
             /**
              * What the app is using.
              *
-             * What this app holds, against the ceiling set for it if there is one; and what the account it belongs to has used this calendar month, across its personal files and all its apps, against what its plan includes. An app's files count toward the account's one storage allowance. For a device signed in with ff login, which uses the personal drive, app is null.
+             * What this app holds, against the ceiling set for it if there is one; and what the account it belongs to has used this calendar month, across its personal files and all its apps, against what its plan includes. An app's files count toward the account's one storage allowance. For a device signed in with filefreak login, which uses the personal drive, app is null.
              *
              * GET /v1/usage. Needs the scope usage:read.
              */
@@ -198,7 +209,7 @@ export function bind(call) {
             /**
              * Who this is.
              *
-             * The account a key, a token or a device acts for, and what it may do there. A key's program and a page's token are told the account's username and plan, never its email address: only a device signed in with ff login, which is the person, is told that.
+             * The account a key, a token or a device acts for, and what it may do there. A key's program and a page's token are told the account's username and plan, never its email address: only a device signed in with filefreak login, which is the person, is told that.
              *
              * GET /v1/me. Any key may call it.
              */
@@ -208,25 +219,25 @@ export function bind(call) {
             /**
              * Make a share link.
              *
-             * A link that opens one file or folder for whoever holds it, separate from making it public: a private file can have one. It can have a password, an end date and a number of downloads after which it stops. Share links are a person's, so only a device signed in with ff login can make them here, as on the website; an app's key cannot.
+             * A link that opens one file or folder for whoever holds it, separate from making it public: a private file can have one. It can have a password, an end date and a number of downloads after which it stops. Share links are a person's, so only a device signed in with filefreak login can make them here, as on the website; an app's key cannot. A link to a file under Shard Protection is a shard link: whoever opens it is given the file's key with its map, so their browser can put the file back together, show it and save it. The storage it is kept in still gives nobody anything on its own.
              *
-             * POST /v1/shares. Only a device signed in with ff login may call it. Honours an Idempotency-Key.
+             * POST /v1/shares. Only a device signed in with filefreak login may call it. Honours an Idempotency-Key.
              */
             create: (body, options) => call("shares.create", { body }, options),
             /**
              * List share links.
              *
-             * The links on one file or folder, or every link the account has, newest first. Removed links are not listed. Only a device signed in with ff login.
+             * The links on one file or folder, or every link the account has, newest first. Removed links are not listed. Only a device signed in with filefreak login.
              *
-             * GET /v1/shares. Only a device signed in with ff login may call it.
+             * GET /v1/shares. Only a device signed in with filefreak login may call it.
              */
             list: (query, options) => call("shares.list", { query }, options),
             /**
              * Remove a share link.
              *
-             * It stops working with the next request, and cannot be brought back. Only a device signed in with ff login.
+             * It stops working with the next request, and cannot be brought back. Only a device signed in with filefreak login.
              *
-             * DELETE /v1/shares/:id. Only a device signed in with ff login may call it.
+             * DELETE /v1/shares/:id. Only a device signed in with filefreak login may call it.
              */
             revoke: (id, options) => call("shares.revoke", { params: { id } }, options),
         },
@@ -234,9 +245,9 @@ export function bind(call) {
             /**
              * List sites.
              *
-             * The account's static sites, by name, with the deploy each serves. A site is a person's, so only a device signed in with ff login reaches sites, as on the website; an app's key cannot. Sites are part of Pro.
+             * The account's static sites, by name, with the deploy each serves. A site is a person's, so only a device signed in with filefreak login reaches sites, as on the website; an app's key cannot. Sites are part of Pro.
              *
-             * GET /v1/sites. Only a device signed in with ff login may call it.
+             * GET /v1/sites. Only a device signed in with filefreak login may call it.
              */
             list: (options) => call("sites.list", {}, options),
             /**
@@ -244,7 +255,7 @@ export function bind(call) {
              *
              * A site with no deploy yet. Its name is its address: 3 to 40 lower-case letters, digits and single hyphens, and not a name FileFreak keeps, another account's username, or one that looks like another company's (invalid_site_name, site_name_taken). Refused with sites_need_pro on a plan without sites.
              *
-             * POST /v1/sites. Only a device signed in with ff login may call it. Honours an Idempotency-Key.
+             * POST /v1/sites. Only a device signed in with filefreak login may call it. Honours an Idempotency-Key.
              */
             create: (body, options) => call("sites.create", { body }, options),
             /**
@@ -252,7 +263,7 @@ export function bind(call) {
              *
              * A site, and its deploys newest first. A site keeps its 10 newest deploys that have ended besides the live one.
              *
-             * GET /v1/sites/:id. Only a device signed in with ff login may call it.
+             * GET /v1/sites/:id. Only a device signed in with filefreak login may call it.
              */
             get: (id, options) => call("sites.get", { params: { id } }, options),
             /**
@@ -260,7 +271,7 @@ export function bind(call) {
              *
              * Begins a deploy with up to 1000 of its files: each one's path, size and SHA-256. Declare the rest with sites.declareFiles, more set to false on the last list. The answer says which files to send: PUT each one's bytes to its address, then call sites.finishDeploy. Bytes the site has stored already are not asked for. A deploy may have 20000 files, 100 MB each and 1 GB together, and what it adds counts as storage from the moment it is declared (quota_exceeded). An unfinished deploy nothing has asked about for an hour is given up on.
              *
-             * POST /v1/sites/:id/deploys. Only a device signed in with ff login may call it. Honours an Idempotency-Key.
+             * POST /v1/sites/:id/deploys. Only a device signed in with filefreak login may call it. Honours an Idempotency-Key.
              */
             startDeploy: (id, body, options) => call("sites.startDeploy", { params: { id }, body }, options),
             /**
@@ -268,7 +279,7 @@ export function bind(call) {
              *
              * The next 1000 files of a deploy at most, as sites.startDeploy takes them. A path declared twice is refused (path_declared_twice).
              *
-             * POST /v1/sites/deploys/:id/files. Only a device signed in with ff login may call it. Honours an Idempotency-Key.
+             * POST /v1/sites/deploys/:id/files. Only a device signed in with filefreak login may call it. Honours an Idempotency-Key.
              */
             declareFiles: (id, body, options) => call("sites.declareFiles", { params: { id }, body }, options),
             /**
@@ -276,7 +287,7 @@ export function bind(call) {
              *
              * New addresses for files of an unfinished deploy whose bytes have not arrived, when the first ones ran out or a finish answered deploy_incomplete. Files whose bytes have arrived are left out.
              *
-             * POST /v1/sites/deploys/:id/send. Only a device signed in with ff login may call it. Safe to send again.
+             * POST /v1/sites/deploys/:id/send. Only a device signed in with filefreak login may call it. Safe to send again.
              */
             sendAgain: (id, body, options) => call("sites.sendAgain", { params: { id }, body }, options),
             /**
@@ -284,7 +295,7 @@ export function bind(call) {
              *
              * Storage puts each file in place and is asked its size, and the deploy is ready, and live if live is true. Safe to call again: storage may take longer than one request waits, and the answer is then 202 with how long to wait before asking again. A file whose bytes have not arrived, or arrived at another size, is answered with deploy_incomplete and the SHA-256s to send again.
              *
-             * POST /v1/sites/deploys/:id/finish. Only a device signed in with ff login may call it. Safe to send again.
+             * POST /v1/sites/deploys/:id/finish. Only a device signed in with filefreak login may call it. Safe to send again.
              */
             finishDeploy: (id, body, options) => call("sites.finishDeploy", { params: { id }, body }, options),
             /**
@@ -292,7 +303,7 @@ export function bind(call) {
              *
              * Cancels a deploy that is uploading, and what it set aside is given back at once. Deletes one that has ended, with whatever bytes no other deploy of the site uses. Never the live one (deploy_live).
              *
-             * DELETE /v1/sites/deploys/:id. Only a device signed in with ff login may call it.
+             * DELETE /v1/sites/deploys/:id. Only a device signed in with filefreak login may call it.
              */
             removeDeploy: (id, options) => call("sites.removeDeploy", { params: { id } }, options),
             /**
@@ -300,7 +311,7 @@ export function bind(call) {
              *
              * Makes a ready deploy the one visitors are served, which is also how a site is rolled back; null takes the site offline. Visitors see the change within a minute.
              *
-             * POST /v1/sites/:id/live. Only a device signed in with ff login may call it. Safe to send again.
+             * POST /v1/sites/:id/live. Only a device signed in with filefreak login may call it. Safe to send again.
              */
             setLive: (id, body, options) => call("sites.setLive", { params: { id }, body }, options),
         },

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export { FileFreak, Walk, type DownloadOptions, type FollowOptions } from "./client.js";
 export * from "./generated.js";
+export { get, type GetOptions, type Got, type Into, type LinkedFile } from "./links.js";
 export { type Sink } from "./ranges.js";
 export { openFragment, sealFragment, SHARD_OVERHEAD, SHARD_VERSION, ShardError, shardKey, ShardLayout, type FragmentAt, type ShardErrorCode, type ShardKey, } from "./shards.js";
 export { FileFreakError, type CallOptions, type ClientOptions, type TokenSource } from "./transport.js";

package/dist/index.js

@@ -5,8 +5,13 @@
 //
 // In a web page, give it a token the page's own server made with its key
 // (ff.tokens.create), never the key. Files on disk are in "@filefreak.io/sdk/node".
+//
+// Saving what a share link or a public page holds needs no key at all:
+//
+//   await get("https://filefreak.link/share/...", toFolder("downloads"));
 export { FileFreak, Walk } from "./client.js";
 export * from "./generated.js";
+export { get } from "./links.js";
 export { openFragment, sealFragment, SHARD_OVERHEAD, SHARD_VERSION, ShardError, shardKey, ShardLayout, } from "./shards.js";
 export { FileFreakError } from "./transport.js";
 export { UploadStopped } from "./uploads.js";