filestow 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aplance Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,169 @@
-# Temporary Holding Version
+# filestow
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The TypeScript SDK for [Filestow](https://hub.docker.com/r/aplance/filestow), file storage for
+your projects over any S3 store: a typed client for its project API, every type in the API, zod
+schemas for them, and the checks for what Filestow sends to your server.
+
+## Install
+
+```bash
+npm install filestow
+```
+
+It has no dependencies and needs Node 20 or later, or any runtime with `fetch` and Web Crypto;
+it is an ES module. The zod schemas, at `filestow/zod`, need `zod` 4 beside it.
+
+## Quick start
+
+A project's server holds the key; a phone or browser never does. Make the project, its key and
+a bucket in Filestow's console, then:
+
+```ts
+import { Filestow } from "filestow";
+
+const filestow = new Filestow({
+  url: "https://filestow.example.com",
+  key: process.env.FILESTOW_KEY,
+  filesUrl: "https://files.example.com", // the public bucket's address, for url()
+});
+
+// On the server: a ticket for exactly `size` bytes of this type, into this folder of
+// its bucket; `bucket: "media"` instead stores it in no folder.
+const upload = await filestow.createUpload({ folder: "covers", type: "image/jpeg", size, owner: "user:42" });
+
+// On the client: PUT the bytes to upload.url with upload.headers.
+
+// Back on the server, the same call any number of times.
+const file = await filestow.completeUpload(upload.id);
+// file.url is public and final. Save file.key: it builds the address, and names the
+// file to look it up, list or restore its versions, or delete it.
+```
+
+A server can store a file in one call instead: `upload({ bucket, body, type })`, where `body` is
+anything `fetch` sends, or a Node stream, which is sent once.
+
+A file of 100 MB or more (by default) comes with `upload.parts` in place of `upload.url`: the
+client PUTs each part to its URL and keeps the ETag each answers with, and the server passes
+them to `completeUpload(upload.id, parts)`. `signUploadParts` signs the parts again once their
+URLs stop working.
+
+A video comes back `processing`, with no URL yet; once its job is done, `get` returns it
+`ready`, with its `url`, `posterUrl` and `durationMs`, and `hlsUrl` in a bucket that streams.
+The project's webhook is told too (below).
+
+A document in a bucket that makes previews gets its `previewUrl` once the preview is drawn, a
+moment after it is stored; in a private bucket, sign it with `size: "preview"`.
+
+`createUpload({ type, size, replaceKey })` or `upload({ body, type, replaceKey })` replaces the
+file at that key, where it is: a replacement names no bucket or folder, and needs a `full` key.
+Where its bucket keeps versions, its earlier bytes are kept: `versions(key)` lists them, each
+with a signed link, and `restoreVersion(key, n)` puts one back; elsewhere they are deleted.
+
+## Addresses
+
+`url(key)` builds a public file's address with no call: `filesUrl`, a slash and the key. A
+project with several public buckets gives one address per bucket, `filesUrl: { media:
+"https://media.example.com", docs: "https://docs.example.com" }`, and names the file's:
+`url(file.key, { bucket: file.bucket })`.
+
+Each kind that makes an image names its own smaller copies: images of themselves, videos of
+their poster, documents of their preview. `url(file.key, { size: "thumb" })` builds one's
+address, and `url(file.key, { size: "preview" })` a document's preview. In a private bucket,
+`sign(keys, { size })` signs them instead of the files, leaving out a file without that copy,
+and `sign(keys, { download,
+downloadName })` opens a file in the browser (`download: false`) or saves it (`true`), under its
+own name or the one given.
+
+## Methods
+
+| What | Methods | Key scope |
+| --- | --- | --- |
+| Files | `list` (the live files, or the trash), `get`, `upload` (or `createUpload`, `signUploadParts` and `completeUpload`), `update` (name, alt text, tags), `place` (into a folder, or a new place in its order), `unplace`, `move` (to another bucket), `delete` (to trash, or `purge`), `restore`, `sign`, `url` (no call) | read, uploads or full |
+| Versions | `versions`, `restoreVersion`, `deleteVersion` | read or full |
+| Folders | `folders`, `folder`, `createFolder`, `updateFolder` (what is given changes; a null `maxFiles` removes its cap), `deleteFolder` (its files stay) | read or full |
+| Buckets | `buckets`, each with its rules, what its files take, and where a public one serves them | read |
+| Tags | `tags`, the ones in use, the most used first | read |
+| Upload links | `links`, `createLink` (its page and its API address, once), `revokeLink` and `reactivateLink` (each answers the link, and twice is once), `deleteLink` (once it takes no more files) | read or full |
+| Owners | `usage`, `deleteOwner` | read or full |
+| Checks | `health` (no key), `verifyWebhook` and `verifyUsageCheck` (no call) | |
+
+A key has a scope: `full`; `read` (lists, gets and signs; changes nothing); or `uploads` (new
+files only: it cannot read, replace or delete files). It may be limited to some buckets, outside
+which it finds nothing. Give each server the least it needs. Every call, with its scope, is in
+the API reference at `/docs` on your Filestow, and in its contract at `/openapi.json`.
+
+A bucket and a folder each say what they take now, kind by kind (`intake`: the formats, the
+largest file, and whether files are made again on the way in), so an upload form can say it and
+check a file before it asks for a ticket.
+
+`list()` takes one bucket or several, one folder or several, an owner, kinds, a tag and a search,
+in one folder's own order (its default with one folder), newest first or by name, a page at a
+time. It lists the buckets and folders the project API may list; an owner's files list from all
+of them; a file in two folders listed comes once. With `trashed: true` it gives the files in
+trash instead, each with `trashedAt` and `purgeAt`. Pass a page's `nextCursor` as `cursor` for
+the next, with the same filters; `folders()` and `links()` page the same way. What is added,
+renamed, moved or deleted between two pages never breaks the next.
+
+## Webhooks and usage checks
+
+Filestow calls a project's server at two addresses, each set on the project's page in the
+console with a signing secret shown once: its webhook, told when a video is ready or failed
+(`file.ready`, `file.failed`) or sent a `test`; and its usage check, asked which files are still
+in use before the console moves any to trash. Both carry `Filestow-Signature`, checked against
+the body exactly as it was sent, so the route reads the raw text before any JSON parser does.
+When each is sent, how it is retried and what it answers is under Webhooks in the API
+reference.
+
+```ts
+import express from "express";
+import { Filestow, type UsageCheckAnswer, type UsageCheckRequest } from "filestow";
+
+const filestow = new Filestow({
+  url: "https://filestow.example.com",
+  key: process.env.FILESTOW_KEY,
+  webhookSecret: process.env.FILESTOW_WEBHOOK_SECRET,
+  usageCheckSecret: process.env.FILESTOW_USAGE_CHECK_SECRET,
+});
+const raw = express.text({ type: "application/json" });
+
+app.post("/filestow/webhook", raw, async (req, res) => {
+  const event = await filestow.verifyWebhook({ body: req.body, signature: req.get("Filestow-Signature") ?? null });
+  if (!event) return res.sendStatus(401); // not Filestow's, or signed too long ago
+  if (event.type === "file.ready") await markReady(event.file!.key, event.file!.url);
+  if (event.type === "file.failed") await markFailed(event.file!.key, event.reason);
+  res.sendStatus(204); // event.id is the same on a repeat: act on it once
+});
+
+app.post("/filestow/usage-check", raw, async (req, res) => {
+  if (!(await filestow.verifyUsageCheck({ body: req.body, signature: req.get("Filestow-Signature") ?? null }))) {
+    return res.sendStatus(401);
+  }
+  const { keys } = JSON.parse(req.body) as UsageCheckRequest; // up to 500 keys a request
+  const answer: UsageCheckAnswer = { inUse: {} };
+  for (const use of await usesOf(keys)) answer.inUse[use.key] = `Used by ${use.what}`;
+  res.json(answer);
+});
+```
+
+## Errors and retries
+
+Every call returns its data or throws a `FilestowError`. Branch on its `code`, one of the API's
+stable codes or the SDK's own `NETWORK_ERROR` (no answer) and `INVALID_RESPONSE` (an answer it
+could not read), never on its `message`. It also carries `status` (0 when there was no answer),
+`requestId` to quote when reporting a problem, `fieldErrors` for forms, and `retryAfterSeconds`.
+
+A call that fails on the network, a 502 or 504, `SERVICE_UNAVAILABLE`, a request still
+running, a busy file or a project moving to another store is tried again, twice by default
+(`retries`), waiting as long as Filestow says, or a moment. Calls that change something carry
+an idempotency key, so a repeat never happens twice; a stream body is sent once, never again.
+One attempt may take 30 seconds (`timeoutMs`); an upload and its completion are not timed.
+`fetch` in the options takes the place of the global one, for a proxy or a test.
+
+## Licence
+
+MIT: see [LICENSE](LICENSE). Filestow itself is a Docker image, free to use:
+[aplance/filestow](https://hub.docker.com/r/aplance/filestow).
+
+## Feedback
+
+Questions and feedback: info@aplance.com

package/dist/client.d.ts

@@ -0,0 +1,270 @@
+import type { Bucket, CompletedPart, CreateFolderRequest, CreateLinkRequest, CreateUploadRequest, File, FileKind, FileSort, FileTag, FileVersion, Folder, Health, NewLink, OwnerDeletion, OwnerUsage, SignedURL, UpdateFileRequest, UpdateFolderRequest, Upload, UploadLink, UploadParts } from "./gen/contract.js";
+import type { WebhookEvent } from "./webhook.js";
+export type FilestowOptions = {
+    /** Filestow's address, like `https://filestow.example.com`. */
+    url: string;
+    /** A project API key (`ak_...`). Every call but `health()` needs one. */
+    key?: string;
+    /**
+     * Where the project's public buckets serve their files, for `url()`: each
+     * bucket's `publicUrl`. One address when the project has one public bucket,
+     * or one per bucket, by its name.
+     */
+    filesUrl?: string | Record<string, string>;
+    /** The usage-check signing secret, for `verifyUsageCheck()`. */
+    usageCheckSecret?: string;
+    /** The webhook signing secret, for `verifyWebhook()`. */
+    webhookSecret?: string;
+    /**
+     * How long one attempt may take, in milliseconds. Default 30 000.
+     * `upload()` and `completeUpload()` are not timed: their time is the
+     * file's.
+     */
+    timeoutMs?: number;
+    /**
+     * How many times a call is tried again after a network failure, a 502 or
+     * 504, `SERVICE_UNAVAILABLE`, a request still running, a busy file or a
+     * project moving to another store. Default 2.
+     */
+    retries?: number;
+    /** A fetch to use instead of the global one. */
+    fetch?: typeof fetch;
+};
+/**
+ * A file to store: into a bucket, into a folder, which names its bucket, or
+ * both; a replacement names neither, and goes where its file is.
+ */
+export type UploadInput = {
+    bucket?: string;
+    folder?: string;
+    /**
+     * The file: anything `fetch` can send, or a Node stream. A stream is sent
+     * once, never retried.
+     */
+    body: BodyInit | AsyncIterable<Uint8Array>;
+    /** The file's content type. */
+    type: string;
+    name?: string;
+    owner?: string;
+    ownerLimitBytes?: number;
+    /** For screen readers. Not with `replaceKey`. */
+    altText?: string;
+    /** Not with `replaceKey`. */
+    tags?: string[];
+    /**
+     * The key of a file to replace: the new bytes take its key, and where its
+     * bucket keeps versions its bytes as they were are kept. Needs a `full` key.
+     */
+    replaceKey?: string;
+};
+/** What to list. With none, every file of the buckets and folders the project API may list, newest first. */
+export type ListInput = {
+    /** Files of a bucket, or of several, by name. */
+    bucket?: string | string[];
+    /** Files of a folder, or of several, by slug. */
+    folder?: string | string[];
+    /** Files of one owner. */
+    owner?: string;
+    /** Files of these kinds. */
+    kind?: FileKind | FileKind[];
+    /** Files that carry this tag. */
+    tag?: string;
+    /** Files whose name or key holds this text, in any case. */
+    q?: string;
+    /** `order`, one folder's own order and its default; `newest`, the default otherwise; or `name`. */
+    sort?: FileSort;
+    /** The files in trash instead of the live ones, each with its `trashedAt` and `purgeAt`. */
+    trashed?: boolean;
+    /** `nextCursor` from the previous page, with the same filters and sort. */
+    cursor?: string;
+    /** At most 100. */
+    limit?: number;
+};
+export type FilePage = {
+    files: File[];
+    /** Pass as `cursor` for the next page. Missing on the last page. */
+    nextCursor?: string;
+};
+/** Which folders to list. With none, every folder of the project. */
+export type ListFoldersInput = {
+    /** Folders of one bucket, by its name. */
+    bucket?: string;
+    /** `nextCursor` from the previous page, with the same bucket. */
+    cursor?: string;
+    /** At most 100. */
+    limit?: number;
+};
+export type FolderPage = {
+    folders: Folder[];
+    /** Pass as `cursor` for the next page. Missing on the last page. */
+    nextCursor?: string;
+};
+/** Which upload links to list. With none, every link of the project. */
+export type ListLinksInput = {
+    /** Links into one bucket, its folders' included, by its name. */
+    bucket?: string;
+    /** Links into one folder, by its slug. */
+    folder?: string;
+    /** `nextCursor` from the previous page, with the same bucket and folder. */
+    cursor?: string;
+    /** At most 100. */
+    limit?: number;
+};
+export type LinkPage = {
+    links: UploadLink[];
+    /** Pass as `cursor` for the next page. Missing on the last page. */
+    nextCursor?: string;
+};
+export type SignOptions = {
+    /** Seconds the links stay valid. */
+    expiresIn?: number;
+    /**
+     * True saves the file; false opens it in the browser. Left out, as it is
+     * served: images, video and audio open, the rest download.
+     */
+    download?: boolean;
+    /** The name it saves under, in place of the file's own. */
+    downloadName?: string;
+    /** One of the files' smaller copies by its name, or "preview" for a document's preview, signed in their place; a file without it is left out. */
+    size?: string;
+};
+/**
+ * The Filestow client. Every call returns the answer's data, or throws an
+ * {@link FilestowError}.
+ *
+ * Calls that change something carry an idempotency key, so a call lost to the
+ * network can be repeated and the first answer comes back instead of it
+ * happening twice.
+ */
+export declare class Filestow {
+    #private;
+    constructor(options: FilestowOptions);
+    /**
+     * Start an upload: the client sends the bytes to `url`, then call
+     * `completeUpload`. A large file comes back with `parts` instead: the
+     * client sends each part to its URL and keeps the ETag each answers with.
+     */
+    createUpload(input: CreateUploadRequest): Promise<Upload>;
+    /** Sign a large upload's parts again, every one or those numbered, once their URLs stopped working. */
+    signUploadParts(uploadId: string, numbers?: number[]): Promise<UploadParts>;
+    /**
+     * Finish an upload and get the file; a large file names each part with its
+     * ETag. Calling it again returns the same file. Not timed: Filestow checks
+     * and processes the file before it answers.
+     */
+    completeUpload(uploadId: string, parts?: CompletedPart[]): Promise<File>;
+    /** Store a file from a server, in one call. Not timed: its time is the file's. */
+    upload(input: UploadInput): Promise<File>;
+    /**
+     * The public address of a file, with no network call: `filesUrl`, a slash
+     * and its key, and for one of its smaller copies `.` and its name. Name
+     * the file's bucket when `filesUrl` holds one address per bucket.
+     */
+    url(key: string, options?: {
+        bucket?: string;
+        size?: string;
+    }): string;
+    /** Signed links, for private files. Keys the project does not have are left out. */
+    sign(keys: string[], options?: SignOptions): Promise<SignedURL[]>;
+    /** One page of files: one folder's in its own order, otherwise newest first, as `sort` says. A file in two folders listed comes once. */
+    list(input?: ListInput): Promise<FilePage>;
+    /** One file, by its key (`file.key`). */
+    get(key: string): Promise<File>;
+    /** Change a file's name, alt text or tags, by its key. An empty alt text removes it; `tags` replaces them all. */
+    update(key: string, changes: UpdateFileRequest): Promise<File>;
+    /**
+     * Move a file to another bucket of the project, by its key: the bucket
+     * named, or the bucket of the folder named, where it goes first. Its key
+     * stays; it leaves the folders of the bucket it leaves, and takes the new
+     * bucket's smaller copies.
+     */
+    move(key: string, to: {
+        bucket: string;
+        folder?: string;
+    } | {
+        bucket?: string;
+        folder: string;
+    }): Promise<File>;
+    /**
+     * Put a file in a folder of its bucket, by slug: right after the file keyed
+     * `after`, or first. A file in the folder already takes the new place.
+     */
+    place(key: string, folder: string, options?: {
+        after?: string;
+    }): Promise<File>;
+    /** Take a file out of a folder, by slug. It stays in its bucket and its other folders. */
+    unplace(key: string, folder: string): Promise<File>;
+    /**
+     * Delete a file, by its key: to trash, where its address keeps working for
+     * the grace period, or with `purge`, for good at once.
+     */
+    delete(key: string, options?: {
+        purge?: boolean;
+    }): Promise<File>;
+    /** Bring a file back from trash, by its key. */
+    restore(key: string): Promise<File>;
+    /** Trash everything an owner has, private at once; restorable for `trash.retention_days` unless `purge`. */
+    deleteOwner(owner: string, options?: {
+        purge?: boolean;
+    }): Promise<OwnerDeletion>;
+    /** A file's versions, by its key: the bytes it kept as it was replaced, newest first, each with a signed link. */
+    versions(key: string): Promise<FileVersion[]>;
+    /** Restore version n of a file, by its key: its bytes take the key again, and the bytes there now are kept as a version. */
+    restoreVersion(key: string, n: number): Promise<File>;
+    /** Delete version n of a file for good, by its key. */
+    deleteVersion(key: string, n: number): Promise<File>;
+    /** The tags the project's live files carry, the most used first. */
+    tags(): Promise<FileTag[]>;
+    /** Bytes and files an owner has. Trash is not counted. */
+    usage(owner: string): Promise<OwnerUsage>;
+    /** The project's buckets: each with its rules, what its files take, and where a public one serves them. */
+    buckets(): Promise<Bucket[]>;
+    /** One page of the project's folders, by slug: collections of their buckets' files. */
+    folders(input?: ListFoldersInput): Promise<FolderPage>;
+    /** One folder, by its slug. */
+    folder(slug: string): Promise<Folder>;
+    /** Add a folder to one of the project's buckets, listing what the bucket takes or less. */
+    createFolder(input: CreateFolderRequest): Promise<Folder>;
+    /**
+     * Change a folder, by its slug: what is given changes, the rest stays. Its
+     * name, what it lists, its max file size per kind (`{}` removes them all),
+     * its cap (`null` removes it), and whether the API lists it.
+     */
+    updateFolder(slug: string, changes: UpdateFolderRequest): Promise<Folder>;
+    /** Delete a folder, by its slug. Its files stay in their bucket and their other folders. */
+    deleteFolder(slug: string): Promise<void>;
+    /** One page of the project's upload links, the newest first. */
+    links(input?: ListLinksInput): Promise<LinkPage>;
+    /** Make an upload link into a bucket, or a folder of it. Its address comes back this once. */
+    createLink(input: CreateLinkRequest): Promise<NewLink>;
+    /** Revoke an upload link: it stops taking files at once. The files it brought stay. */
+    revokeLink(id: string): Promise<UploadLink>;
+    /** Reactivate a revoked upload link, at the same address, while it would take files: not expired, not used up. */
+    reactivateLink(id: string): Promise<UploadLink>;
+    /** Delete an upload link that takes no more files: revoked, expired or used up. The files it brought stay. */
+    deleteLink(id: string): Promise<void>;
+    /**
+     * Health of Filestow and what it depends on. A degraded answer comes back
+     * with `status: "degraded"`; an unavailable one throws `SERVICE_UNAVAILABLE`.
+     */
+    health(): Promise<Health>;
+    /**
+     * Checks a usage-check request really came from Filestow: call it first in
+     * the server's usage-check route, with the raw body and the
+     * `Filestow-Signature` header.
+     */
+    verifyUsageCheck(request: {
+        body: string;
+        signature: string | null;
+    }): Promise<boolean>;
+    /**
+     * Checks a webhook delivery really came from Filestow, and reads it: call it
+     * first in the server's webhook route, with the raw body and the
+     * `Filestow-Signature` header. Null for anything Filestow did not sign, or
+     * signed too long ago. Every attempt of one event has the same `id`.
+     */
+    verifyWebhook(request: {
+        body: string;
+        signature: string | null;
+    }): Promise<WebhookEvent | null>;
+}