@filefreak.io/sdk 0.1.0 → 0.3.0

package/dist/generated.js

@@ -17,9 +17,11 @@ export const OPERATIONS = {
     "uploads.begin": { method: "POST", path: "/v1/uploads", idempotent: true, repeatable: false },
     "uploads.get": { method: "GET", path: "/v1/uploads/:id", idempotent: false, repeatable: false },
     "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.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 },
@@ -70,6 +72,8 @@ export function bind(call) {
              *
              * Any of the three, in one request. They are applied in that order, each as its own change: if the second is refused the first has still happened, and the answer says which was refused. Moving a folder moves everything in it and is one change however much that is. Making a folder public makes everything in it public, except what has a setting of its own.
              *
+             * protection is a fourth, applied last: on puts the file or folder under Shard Protection, off takes it out, and inherit has it follow the folder it is in. A folder's setting reaches everything in it that has none of its own. Turning it on is refused while the account's plan does not include it (402 shard_protection_needs_pro); turning it off never is. Nothing is converted in this request: the service converts each file within a few minutes, and its protected says when. A key confined to a folder decides about what is in it, and not about the folder.
+             *
              * PATCH /v1/files/:id. Needs the scope files:write.
              */
             update: (id, body, options) => call("files.update", { params: { id }, body }, options),
@@ -92,11 +96,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,13 +160,15 @@ 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 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).
+             *
              * POST /v1/uploads. Needs the scope files:write. Honours an Idempotency-Key.
              */
             begin: (body, options) => call("uploads.begin", { body }, options),
             /**
              * An upload, and which parts have arrived.
              *
-             * For carrying on after an interruption: storage itself says which parts it has, so nothing the client remembered is needed.
+             * For carrying on after an interruption: storage itself says which parts it has, so nothing the client remembered is needed. For an upload sealed as it is sent, uploadedParts are the fragments confirmed and recorded, and shards gives the key, which this API keeps nowhere else. Confirm any fragment that may have been sent before sending it again. This answer is never kept, by this API or anything between it and the caller.
              *
              * GET /v1/uploads/:id. Needs the scope files:write.
              */
@@ -162,11 +176,19 @@ export function bind(call) {
             /**
              * Addresses for more parts.
              *
-             * Addresses are given out a window at a time and each lasts half an hour. Ask again for any that have run out.
+             * Addresses are given out a window at a time and each lasts half an hour. Ask again for any that have run out. For an upload sealed as it is sent, each number is a fragment's place, and its address takes the sealed fragment, with its Content-MD5. Confirm fragments with uploads.fragments once they are sent.
              *
              * GET /v1/uploads/:id/parts. Needs the scope files:write.
              */
             parts: (id, query, options) => call("uploads.parts", { params: { id }, query }, options),
+            /**
+             * Confirm sealed fragments.
+             *
+             * Confirms fragments of a sealed upload that have been sent. Each is copied inside storage to its own name, measured, and recorded once it is the size its place holds. recorded: done, never send it again. pending: storage is still copying it, or another confirmation of it is under way, so ask again shortly. resend: not there, or not its size and removed, so seal it again, under a new nonce, send it and confirm it. Safe to send again.
+             *
+             * POST /v1/uploads/:id/fragments. Needs the scope files:write. Safe to send again.
+             */
+            fragments: (id, body, options) => call("uploads.fragments", { params: { id }, body }, options),
             /**
              * Finish an upload.
              *
@@ -188,7 +210,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 +220,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 +230,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 +256,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 +266,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 +274,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 +282,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 +290,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 +298,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 +306,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 +314,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 +322,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";

package/dist/links.d.ts

@@ -0,0 +1,72 @@
+import { type Sink } from "./ranges.js";
+/** A file a link holds, as get() hands it to the function that makes its sink. */
+export interface LinkedFile {
+    id: string;
+    /**
+     * Its name, as whoever shared it wrote it. A link can name any site, and
+     * that site can say anything, so never use it as a path unchecked:
+     * safeName and toFolder, in "@filefreak.io/sdk/node", check it.
+     */
+    name: string;
+    /** The folders it is in, from the shared folder, by its name, down. Empty for a link to one file. As unchecked as `name`. */
+    folders: string[];
+    sizeBytes: number;
+    contentType: string | null;
+    /** Under Shard Protection: put back together from its map, each part checked as it arrives. */
+    protected: boolean;
+}
+/** Where get() puts what a link holds: one Sink, for a link to one file, or a function that makes one for each file. */
+export type Into = Sink | ((file: LinkedFile) => Sink | Promise<Sink>);
+export interface GetOptions {
+    /** The link's password, for a link that has one. */
+    password?: string;
+    /** Stops the saving, and aborts the sink of the file being saved. */
+    signal?: AbortSignal;
+    /** Called as bytes are written, with how many have been and how many there are in all. */
+    onProgress?: (writtenBytes: number, totalBytes: number) => void;
+    /** Another fetch, for a runtime without one or for tests. */
+    fetch?: typeof fetch;
+}
+export interface Got {
+    /** What the link is to. */
+    kind: "file" | "folder";
+    /** Its name, as its sharer wrote it. */
+    name: string;
+    /** Every file saved, in the order they were saved. */
+    files: LinkedFile[];
+    /** Their bytes, together. */
+    sizeBytes: number;
+}
+/** What a link is to, and the site to ask about it. */
+export type Link = {
+    origin: string;
+} & ({
+    kind: "share";
+    token: string;
+} | {
+    kind: "public";
+    id: string;
+    username: string | null;
+});
+export declare const NOT_A_LINK = "That is not a FileFreak share link or public file address.";
+/**
+ * The link a web address is: `/share/<token>`, `/public/<username>/<id>`,
+ * or a public file's direct address, `/api/public/files/<id>/raw`. On https,
+ * or on http for the local stack only.
+ */
+export declare function linkOf(url: string | URL): Link;
+/**
+ * Save what a share link or a public page holds, with no key: one file into
+ * `into`, a Sink, or a folder and everything in it, each file into the Sink
+ * that `into`, a function, makes for it. Resolves once every file has been
+ * saved and its sink closed.
+ *
+ * Takes `https://<host>/share/<token>`, `https://<host>/public/<username>/<id>`
+ * and a public file's direct address. A protected file is put back together
+ * from its map and checked as it arrives. A failure is a FileFreakError, with
+ * the site's code and sentence or one of get's own: not_a_link, not_a_file
+ * (a folder's link given one Sink), password_required, not_enough_downloads,
+ * too_deep, fragment_damaged or fragment_unavailable. The file being saved
+ * when it stops has its sink aborted; files saved before it stay saved.
+ */
+export declare function get(url: string | URL, into: Into, options?: GetOptions): Promise<Got>;