@filefreak.io/sdk 0.0.0-stage → 0.2.0

package/dist/generated.js

@@ -0,0 +1,329 @@
+// The developer API's endpoints, and the shapes they take and answer with,
+// written out from the table in api/src/routes/v1.ts by
+// api/src/scripts/clientTypes.ts. Change the table, not this, and run
+// `npm run clients:types`: tests/checks/clients-are-current.mjs fails while
+// this is behind it.
+/** Every endpoint, by the name its entry gives it. */
+export const OPERATIONS = {
+    "files.list": { method: "GET", path: "/v1/files", idempotent: false, repeatable: false },
+    "files.byPath": { method: "GET", path: "/v1/files/by-path", idempotent: false, repeatable: false },
+    "files.get": { method: "GET", path: "/v1/files/:id", idempotent: false, repeatable: false },
+    "files.update": { method: "PATCH", path: "/v1/files/:id", idempotent: false, repeatable: false },
+    "files.delete": { method: "DELETE", path: "/v1/files/:id", idempotent: false, repeatable: false },
+    "files.restore": { method: "POST", path: "/v1/files/:id/restore", idempotent: false, repeatable: false },
+    "folders.create": { method: "POST", path: "/v1/folders", idempotent: true, repeatable: false },
+    "tree.list": { method: "GET", path: "/v1/tree", idempotent: false, repeatable: false },
+    "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.parts": { method: "GET", path: "/v1/uploads/:id/parts", idempotent: false, repeatable: false },
+    "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 },
+    "shares.create": { method: "POST", path: "/v1/shares", idempotent: true, repeatable: false },
+    "shares.list": { method: "GET", path: "/v1/shares", idempotent: false, repeatable: false },
+    "shares.revoke": { method: "DELETE", path: "/v1/shares/:id", idempotent: false, repeatable: false },
+    "sites.list": { method: "GET", path: "/v1/sites", idempotent: false, repeatable: false },
+    "sites.create": { method: "POST", path: "/v1/sites", idempotent: true, repeatable: false },
+    "sites.get": { method: "GET", path: "/v1/sites/:id", idempotent: false, repeatable: false },
+    "sites.startDeploy": { method: "POST", path: "/v1/sites/:id/deploys", idempotent: true, repeatable: false },
+    "sites.declareFiles": { method: "POST", path: "/v1/sites/deploys/:id/files", idempotent: true, repeatable: false },
+    "sites.sendAgain": { method: "POST", path: "/v1/sites/deploys/:id/send", idempotent: false, repeatable: true },
+    "sites.finishDeploy": { method: "POST", path: "/v1/sites/deploys/:id/finish", idempotent: false, repeatable: true },
+    "sites.removeDeploy": { method: "DELETE", path: "/v1/sites/deploys/:id", idempotent: false, repeatable: false },
+    "sites.setLive": { method: "POST", path: "/v1/sites/:id/live", idempotent: false, repeatable: true },
+    "tokens.create": { method: "POST", path: "/v1/tokens", idempotent: false, repeatable: true },
+};
+/** Every endpoint as a function, grouped by what it is about. */
+export function bind(call) {
+    return {
+        files: {
+            /**
+             * List a folder.
+             *
+             * What is in a folder, a page at a time: folders first, then files, each by name. Pass nextCursor back as cursor for the next page; when it is null there is no more. Things in the trash are not listed. A page never repeats or skips something because of what was added or removed between two requests.
+             *
+             * GET /v1/files. Needs the scope files:read.
+             */
+            list: (query, options) => call("files.list", { query }, options),
+            /**
+             * A file or folder by its path.
+             *
+             * Found by the names of the folders down to it from the top of the app (or of the folder the key is confined to), separated by /. A name matches whatever its case, as names in one folder do. Nothing in the trash is found, nor anything inside something that is.
+             *
+             * GET /v1/files/by-path. Needs the scope files:read.
+             */
+            byPath: (query, options) => call("files.byPath", { query }, options),
+            /**
+             * One file or folder.
+             *
+             * By its id. Something in the trash is still returned, with trashedAt set.
+             *
+             * GET /v1/files/:id. Needs the scope files:read.
+             */
+            get: (id, options) => call("files.get", { params: { id } }, options),
+            /**
+             * Rename, move, or make public.
+             *
+             * 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.
+             *
+             * PATCH /v1/files/:id. Needs the scope files:write.
+             */
+            update: (id, body, options) => call("files.update", { params: { id }, body }, options),
+            /**
+             * Put in the trash, or delete for good.
+             *
+             * Without permanent, the file or folder goes to the trash: it can be restored, it still counts toward storage, and it is removed for good after thirty days. With permanent=true it is removed now, with everything inside it, and cannot be brought back.
+             *
+             * DELETE /v1/files/:id. Needs the scope files:delete.
+             */
+            delete: (id, query, options) => call("files.delete", { params: { id }, query }, options),
+            /**
+             * Take out of the trash.
+             *
+             * It goes back where it was. If that folder has gone it goes to the top, and if its name has been taken in the meantime it comes back with a number after it.
+             *
+             * POST /v1/files/:id/restore. Needs the scope files:write.
+             */
+            restore: (id, options) => call("files.restore", { params: { id } }, options),
+            /**
+             * 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 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.
+             *
+             * A copy of an image no more than size pixels on its longest side, as WebP, with the camera's metadata removed. The sizes are 64, 128, 256, 512, 1024 and no others. Each is made once, the first time it is asked for, and kept: until it has been made the answer is 202. Name the sizes when the image is uploaded and they are ready by the time they are wanted. For a public file, add ?size= to its publicUrl. A file under Shard Protection has no smaller copies, and is answered with 409 shard_protected.
+             *
+             * GET /v1/files/:id/image. Needs the scope files:read.
+             */
+            image: (id, query, options) => call("files.image", { params: { id }, query }, options),
+        },
+        folders: {
+            /**
+             * Make a folder.
+             *
+             * Folders can be nested up to 32 deep. With ifExists=use, a folder of that name that is already there is returned and nothing is made, which is what a program that makes its folders on every start wants.
+             *
+             * POST /v1/folders. Needs the scope files:write. Honours an Idempotency-Key.
+             */
+            create: (body, options) => call("folders.create", { body }, options),
+        },
+        tree: {
+            /**
+             * Everything under a folder.
+             *
+             * Every file and folder under a folder, at every level, a page at a time, each folder before what is inside it. Pass nextCursor back as cursor for the next page; when it is null there is no more. Things in the trash are not listed. Every page carries changesCursor: the place in GET /v1/changes from before the first page was read. Something that changes while the pages are being read may be listed or not, and is in the changes after that place either way. It is null for a key confined to a folder, which cannot follow the changes.
+             *
+             * GET /v1/tree. Needs the scope files:read.
+             */
+            list: (query, options) => call("tree.list", { query }, options),
+        },
+        changes: {
+            /**
+             * What has changed.
+             *
+             * Every change to the app's files and folders after cursor, oldest first, each saying what the thing is now. A folder's change stands for everything in it: a folder moved, put in the trash or deleted is one change, and what is inside goes with it. Without cursor, no changes and the cursor for now. Pass cursor back each time; while more is true, ask again at once. With wait, an answer that would be empty waits up to that many seconds for something to change, and comes back empty, with the same cursor, if nothing does.
+             *
+             * To keep a copy: list everything with GET /v1/tree and keep its changesCursor, then apply each change in order. A change that is not live, or whose parentId is a folder the copy does not have, takes that thing and everything inside it out of the copy. A live change puts it in, or moves or renames it; a folder that was not in the copy is then listed with GET /v1/tree?parent= for what it holds, and if that is answered 404 the folder has gone since, which a later change says. A file whose revision has gone up has new content. Changes are kept for 30 days, and a cursor from before that is answered 410 cursor_expired: start again from a listing. A key confined to a folder cannot follow the changes, and lists its folder again instead.
+             *
+             * While the service is asleep, after a while with nobody using it, nothing can change, and a question with a cursor is answered without waking it: no changes, the same cursor, after the wait asked for. Asking is not counted as using the service, so a program that asks all night does not keep it awake.
+             *
+             * GET /v1/changes. Needs the scope files:read.
+             */
+            list: (query, options) => call("changes.list", { query }, options),
+        },
+        uploads: {
+            /**
+             * Begin an upload.
+             *
+             * Says what is about to be sent, and answers with where to send it. A file's bytes never pass through this API: they go straight to storage, in parts, each with a plain PUT to the address given for it. The first addresses come back here; ask for the rest as they are needed. Then complete the upload, and it becomes a file.
+             *
+             * 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),
+            /**
+             * 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.
+             *
+             * GET /v1/uploads/:id. Needs the scope files:write.
+             */
+            get: (id, options) => call("uploads.get", { params: { id } }, options),
+            /**
+             * 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.
+             *
+             * GET /v1/uploads/:id/parts. Needs the scope files:write.
+             */
+            parts: (id, query, options) => call("uploads.parts", { params: { id }, query }, options),
+            /**
+             * Finish an upload.
+             *
+             * Turns the parts into a file. Safe to call again: a second call for an upload that has finished answers with the same file. For a very large file storage may still be putting it together, and the answer is then 202 with how long to wait before asking again.
+             *
+             * POST /v1/uploads/:id/complete. Needs the scope files:write. Safe to send again.
+             */
+            complete: (id, body, options) => call("uploads.complete", { params: { id }, body }, options),
+            /**
+             * Cancel an upload.
+             *
+             * Whatever had arrived is deleted, and the room it held comes back at once.
+             *
+             * DELETE /v1/uploads/:id. Needs the scope files:write.
+             */
+            cancel: (id, options) => call("uploads.cancel", { params: { id } }, options),
+        },
+        usage: {
+            /**
+             * 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 filefreak login, which uses the personal drive, app is null.
+             *
+             * GET /v1/usage. Needs the scope usage:read.
+             */
+            get: (options) => call("usage.get", {}, options),
+        },
+        me: {
+            /**
+             * 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 filefreak login, which is the person, is told that.
+             *
+             * GET /v1/me. Any key may call it.
+             */
+            get: (options) => call("me.get", {}, options),
+        },
+        shares: {
+            /**
+             * 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 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 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 filefreak login.
+             *
+             * 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 filefreak login.
+             *
+             * DELETE /v1/shares/:id. Only a device signed in with filefreak login may call it.
+             */
+            revoke: (id, options) => call("shares.revoke", { params: { id } }, options),
+        },
+        sites: {
+            /**
+             * 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 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 filefreak login may call it.
+             */
+            list: (options) => call("sites.list", {}, options),
+            /**
+             * Make a site.
+             *
+             * 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 filefreak login may call it. Honours an Idempotency-Key.
+             */
+            create: (body, options) => call("sites.create", { body }, options),
+            /**
+             * A site and its deploys.
+             *
+             * 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 filefreak login may call it.
+             */
+            get: (id, options) => call("sites.get", { params: { id } }, options),
+            /**
+             * Begin a deploy.
+             *
+             * 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 filefreak login may call it. Honours an Idempotency-Key.
+             */
+            startDeploy: (id, body, options) => call("sites.startDeploy", { params: { id }, body }, options),
+            /**
+             * Declare more of a deploy's files.
+             *
+             * 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 filefreak login may call it. Honours an Idempotency-Key.
+             */
+            declareFiles: (id, body, options) => call("sites.declareFiles", { params: { id }, body }, options),
+            /**
+             * Fresh addresses for a deploy's files.
+             *
+             * 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 filefreak login may call it. Safe to send again.
+             */
+            sendAgain: (id, body, options) => call("sites.sendAgain", { params: { id }, body }, options),
+            /**
+             * Finish a deploy.
+             *
+             * 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 filefreak login may call it. Safe to send again.
+             */
+            finishDeploy: (id, body, options) => call("sites.finishDeploy", { params: { id }, body }, options),
+            /**
+             * Cancel or delete a deploy.
+             *
+             * 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 filefreak login may call it.
+             */
+            removeDeploy: (id, options) => call("sites.removeDeploy", { params: { id } }, options),
+            /**
+             * Choose the live deploy.
+             *
+             * 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 filefreak login may call it. Safe to send again.
+             */
+            setLive: (id, body, options) => call("sites.setLive", { params: { id }, body }, options),
+        },
+        tokens: {
+            /**
+             * A token for a web page.
+             *
+             * A key belongs on a server, and one sent from a web page is refused, because anybody who opens the page can read it. A page that should reach this API itself, to upload straight from the browser or to list a folder, is given a token instead: the server makes one with its key and hands it to the page, which sends it as it would a key. A token may do what its key may, or less: the scopes asked for, inside the folder asked for, until it expires. It is checked against its key on every request, so revoking the key stops its tokens at once, and its calls count as the key's. Nothing about a token is kept, so making one is safe to send again. A token cannot make another. Once Pro has ended and a key can only read, it can still make tokens, which can only read too.
+             *
+             * POST /v1/tokens. Any key may call it. Safe to send again.
+             */
+            create: (body, options) => call("tokens.create", { body }, options),
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+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";
+export { UploadStopped, type Source, type UploadOptions } from "./uploads.js";

package/dist/index.js

@@ -0,0 +1,17 @@
+// @filefreak.io/sdk: FileFreak's developer API, for Node and the browser.
+//
+//   const ff = new FileFreak({ apiKey: process.env.FILEFREAK_KEY });
+//   const { items } = await ff.files.list();
+//
+// 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>;