@omelhorsite/sdk 0.1.0

package/dist/types/resources/storage.d.ts

@@ -0,0 +1,527 @@
+/**
+ * The `storage` namespace: the virtual filesystem.
+ *
+ * A node is a file or a directory, identified by an opaque id. Since the ltree
+ * migration the id IS the address: there is no `path` column any more, and
+ * navigation goes parent id -> children, with `ancestors()` for a breadcrumb.
+ * Never build or parse a path string.
+ *
+ * {@link StorageNamespace.resolvePath} exists for humans typing `docs/a.pdf`,
+ * and it is exactly what it looks like: one request per segment, walking
+ * `name` + `parent_id` down the filtered index. It memoises what it learns per
+ * client instance so a CLI session does not re-walk the same prefix, but the
+ * cheap call is always the one that already has an id.
+ *
+ * Uploads do NOT stream through this namespace. Bytes go straight to object
+ * storage with a presigned URL; Rails only mints the plan and, at the end,
+ * binds the blob. That whole dance lives in `storage/upload.ts` and is reached
+ * through {@link StorageNamespace.upload}.
+ *
+ * Four throttles bound what this namespace can do, and they are far tighter
+ * than the API's general ceiling:
+ *
+ * - `fs_upload` - 300/min for the whole upload control plane. Paced by
+ *   {@link UploadManager}.
+ * - `fs_bulk_job` - TWELVE a minute for `copy`, `createDirectories`,
+ *   `emptyTrash` and `trash` together. Paced by {@link StorageNamespace.bulkGate}.
+ * - the general 600/min for everything else.
+ * - the direct PUTs at the object store, which rack-attack never sees at all.
+ */
+import { Resource, type ApiClient } from "../http";
+import type { BaseRecord, FileInput, FileOutput, Id, OperationOptions, Paginated, PageParams, RequestOptions } from "../types";
+import type { User } from "./account";
+import { StorageRateGate, UploadManager } from "./storage/upload";
+/** What a node is. */
+export type FsNodeKind = "file" | "directory";
+/**
+ * A node in the virtual filesystem.
+ *
+ * These are exactly the fields the server's blueprint emits - `id`,
+ * `created_at`, `updated_at`, `name`, `parent_id`, `kind`, `size`, `max_size` -
+ * and the `:extended` view adds nothing. In particular there is no
+ * `content_type` and no `path`: the type of a file is decided from its name at
+ * download time, and the path is gone.
+ */
+export interface FsNode extends BaseRecord {
+    readonly name: string;
+    readonly kind: FsNodeKind;
+    /** `null` only for a root (home, trash, vault). */
+    readonly parent_id: Id | null;
+    /** Bytes. For a directory, the recursive total. */
+    readonly size: number;
+    /** Quota ceiling. Set on roots only; `null` means no ceiling. */
+    readonly max_size: number | null;
+}
+/** One link in a breadcrumb chain. */
+export interface FsBreadcrumb {
+    readonly id: Id;
+    readonly name: string;
+    readonly kind: FsNodeKind;
+}
+/** `GET /fs_nodes/roots` - the ids a client needs to bootstrap navigation. */
+export interface FsRoots {
+    readonly home: Id | null;
+    readonly trash: Id | null;
+    /** `null` until the encrypted vault is used for the first time. */
+    readonly vault: Id | null;
+}
+/**
+ * A bulk operation the server runs in the background.
+ *
+ * `copy`, `createDirectories`, `trash` and `emptyTrash` all answer with nothing
+ * but a job id: the work happens in a worker and the response says only that it
+ * was enqueued. Poll it with `oms.jobs.wait(jobId)`; this namespace has no
+ * access to the jobs namespace and deliberately does not grow a second polling
+ * loop.
+ */
+export interface FsBulkJob {
+    /** Feed this to `oms.jobs.get` / `oms.jobs.wait`. */
+    readonly jobId: Id;
+}
+/**
+ * A response body streamed rather than buffered.
+ *
+ * The zip endpoint has no `Content-Length` (it is generated as it is sent) and
+ * a stored file can be larger than any sane heap, so both are handed over as a
+ * stream. The caller owns it and must consume or cancel it.
+ */
+export interface FsStream {
+    readonly stream: ReadableStream<Uint8Array>;
+    /** Filename the server suggested, from `Content-Disposition`. */
+    readonly filename: string | undefined;
+    readonly contentType: string | undefined;
+    /** Byte length when the server sent one. Always `undefined` for a zip. */
+    readonly size: number | undefined;
+}
+/** Filters for {@link StorageNamespace.list}. */
+export interface ListFsNodesParams extends PageParams {
+    /**
+     * Directory to list. `null` lists the caller's ROOT nodes (home, trash,
+     * vault), which the server selects through its `\b` null sentinel.
+     */
+    readonly parentId: Id | null;
+    /**
+     * Include nodes whose bytes never landed. Off by default, because a
+     * half-finished upload is not something a user wants to see - and because a
+     * node's absence from a normal listing is the only proof its blob is bound.
+     */
+    readonly includePending?: boolean;
+    /**
+     * Also return the parent itself, so one call gets both the folder's metadata
+     * and its children. It occupies a slot on the page like any other row.
+     */
+    readonly includeSelf?: boolean;
+}
+/** Arguments for creating directories. */
+export interface CreateDirectoriesInput {
+    /** Directory to create under. */
+    readonly parentId: Id;
+    /**
+     * Relative paths, e.g. `["fotos", "fotos/2024"]`. Intermediate levels are
+     * created as needed and an existing level is reused, so this is idempotent.
+     * A `..` segment is rejected by the server.
+     */
+    readonly paths: string[];
+}
+/** Arguments for copying nodes. */
+export interface CopyFsNodesInput {
+    readonly ids: Id[];
+    readonly newParentId: Id;
+}
+/**
+ * A sharing grant on a node.
+ *
+ * There is no expiry and no read/write enum: access is the single `editable`
+ * boolean, and a grant lives until someone deletes it.
+ */
+export interface FsGrant extends BaseRecord {
+    readonly fs_node_id: Id;
+    /** Who issued it. Always a real user. */
+    readonly grantor_id: Id;
+    /** Grantee, or `null` for a public link grant that anyone with the URL may read. */
+    readonly grantee_id: Id | null;
+    /** Write access. Always `false` on a public grant - the server validates it. */
+    readonly editable: boolean;
+    /** Only on the `:extended` view, i.e. from `get`, `create` and `update`. */
+    readonly fs_node?: FsNode;
+    readonly grantor?: User;
+    readonly grantee?: User | null;
+}
+/** Arguments for sharing a node. */
+export interface CreateFsGrantInput {
+    readonly fsNodeId: Id;
+    /**
+     * Grantee's user id. Omit it (or pass `null`) for a public link grant, which
+     * must be read-only.
+     */
+    readonly granteeId?: Id | null;
+    /** Write access. Rejected with `editable` on a public grant. */
+    readonly editable?: boolean;
+}
+/** The scoped view behind a share link, from `GET /fs_nodes/:id/shared`. */
+export interface SharedFsNodeView {
+    readonly node: FsNode;
+    /** Every descendant when `node` is a directory, and nothing else - never siblings, never ancestors. */
+    readonly descendants: FsNode[];
+    /** The grant that authorised the view, when one was found. */
+    readonly grant: {
+        readonly id: Id;
+        readonly editable: boolean;
+        readonly grantor_id: Id;
+        readonly public: boolean;
+    } | null;
+    readonly scope_root_id: Id;
+}
+/**
+ * Sharing grants, reachable as `oms.storage.grants`.
+ *
+ * Creating one with a `granteeId` notifies that user. Creating one WITHOUT a
+ * grantee mints a public link: the server also creates a short link in the `ss`
+ * namespace whose endpoint is the grant's own id, pointing at the frontend's
+ * `/storage/shared?id=<node>` page. Deleting the grant deletes that link.
+ */
+export declare class FsGrantsNamespace extends Resource {
+    /**
+     * `GET /fs_grants` - the grants you hold: issued by you, or issued to you.
+     *
+     * There is no server-side filter for the node. The controller allows only
+     * `id`, `created_at` and `updated_at` as search keys, and an unknown key is a
+     * 400, not a wider result - so narrowing to one node is a client-side filter
+     * over this listing. {@link StorageNamespace.shared} is the cheap way to ask
+     * "how is THIS node shared".
+     *
+     * @throws {OmsAuthError} 401 when anonymous.
+     */
+    list(params?: PageParams, options?: RequestOptions): Promise<Paginated<FsGrant>>;
+    /** `GET /fs_grants/:id` - one grant, with its node, grantor and grantee expanded. */
+    get(id: Id, options?: RequestOptions): Promise<FsGrant>;
+    /**
+     * `POST /fs_grants` - shares a node.
+     *
+     * @throws {OmsApiError} 400 when a public grant asks for `editable: true`,
+     *   401 when the caller cannot edit the node.
+     */
+    create(input: CreateFsGrantInput, options?: RequestOptions): Promise<FsGrant>;
+    /**
+     * `PATCH /fs_grants/:id` - changes the grantee or the write flag.
+     *
+     * Only the grantor may do this. There is nothing else to change: a grant has
+     * no expiry.
+     */
+    update(id: Id, input: {
+        granteeId?: Id | null;
+        editable?: boolean;
+    }, options?: RequestOptions): Promise<FsGrant>;
+    /** `DELETE /fs_grants/:id` - revokes a share and destroys its short link. */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}
+/** The `storage` namespace, reachable as `oms.storage`. */
+export declare class StorageNamespace extends Resource {
+    /** The presigned direct-upload driver. */
+    readonly uploads: UploadManager;
+    /** Sharing grants. */
+    readonly grants: FsGrantsNamespace;
+    /**
+     * Paces the four bulk-job endpoints against the `fs_bulk_job` throttle, which
+     * is twelve requests a minute for all of them together. A loop that trashes
+     * files one at a time waits here rather than collecting 429s.
+     */
+    readonly bulkGate: StorageRateGate;
+    /**
+     * Memoised `(parentId, name) -> id` lookups, plus the roots.
+     *
+     * Positive results only: caching a miss would hide a file created a second
+     * later. Invalidated whenever this client moves, renames, trashes or deletes
+     * a node - never when ANOTHER client does, which is the cache's one real
+     * limitation and the reason {@link clearCache} is public.
+     */
+    private readonly children;
+    private rootsCache;
+    private readonly transport;
+    /** Entries kept before the oldest is evicted. Bounds a long-lived isolate. */
+    private static readonly CACHE_LIMIT;
+    constructor(http: ApiClient);
+    /**
+     * `GET /fs_nodes/roots` - the home, trash and vault node ids. Call this once
+     * and navigate from there; there is no path to build.
+     *
+     * Memoised, because roots do not move. `vault` is `null` until the encrypted
+     * vault is used for the first time - {@link vaultRoot} creates it.
+     *
+     * @throws {OmsAuthError} 401 when anonymous.
+     */
+    roots(options?: RequestOptions): Promise<FsRoots>;
+    /**
+     * `GET /fs_nodes` - the children of a directory.
+     *
+     * Anonymous callers get an empty listing, always: the listing scope is the
+     * caller's own tree plus what was explicitly shared with them, and a public
+     * grant is deliberately NOT enumerable. Reach a publicly-shared node by id
+     * with {@link get} or {@link shared} instead.
+     *
+     * The endpoint is conditional-GET aware and answers 304 to a matching
+     * `If-None-Match`. The SDK never sends one, and asks the runtime not to
+     * revalidate on its own, because a 304 has no body and would surface here as
+     * an error rather than as an empty page.
+     */
+    list(params: ListFsNodesParams, options?: RequestOptions): Promise<Paginated<FsNode>>;
+    /**
+     * `GET /fs_nodes/:id` - one node.
+     *
+     * Resolves against the broader `viewable_by` scope, so a node reached through
+     * a public share link answers here even though it never appears in
+     * {@link list}.
+     *
+     * @throws {OmsApiError} 404 when the node does not exist or is not visible.
+     */
+    get(id: Id, options?: RequestOptions): Promise<FsNode>;
+    /** Alias for {@link get}, for callers who think in filesystem verbs. */
+    stat(id: Id, options?: RequestOptions): Promise<FsNode>;
+    /**
+     * `GET /fs_nodes/:id/ancestors` - the breadcrumb chain, root first, the node
+     * itself last. Ancestors the caller may not list are omitted, so a shared
+     * node never leaks the names of its parents - which also means the chain can
+     * be shorter than the real depth, and its first entry is not necessarily a
+     * root.
+     */
+    ancestors(id: Id, options?: RequestOptions): Promise<FsBreadcrumb[]>;
+    /**
+     * Resolves a slash-separated path under a starting node, walking children one
+     * level at a time.
+     *
+     * A convenience for humans and CLIs, NOT how the API works. The `path` column
+     * was dropped in the ltree migration and nothing on the server accepts a path
+     * string, so each segment costs one filtered listing. Results are memoised
+     * per client instance, which makes a second walk down the same prefix free,
+     * but the cheap call is always the one that already has an id.
+     *
+     * `.` is skipped and `..` climbs to the parent. A leading `/` means "from the
+     * home root" and ignores `from`.
+     *
+     * @param options.from Node to start at. Defaults to the home root.
+     * @param options.includePending Resolve through nodes whose bytes never
+     *   landed. Off by default.
+     * @throws {OmsApiError} 404 naming the segment that did not resolve.
+     */
+    resolvePath(path: string, options?: RequestOptions & {
+        from?: Id;
+        includePending?: boolean;
+    }): Promise<FsNode>;
+    /**
+     * Uploads files. Delegates to {@link UploadManager}, which batches the
+     * intake, presigns, sends the bytes straight to object storage, binds the
+     * blobs and reads the finished nodes back.
+     *
+     * Files at or above 32 MiB take the multipart path automatically, and that is
+     * not tuning: the object store sits behind Cloudflare with a request-body cap
+     * around 100 MB, so it is the only way a large file gets in.
+     *
+     * A per-file rejection - a quota that ran out, a name that collides with a
+     * directory - does not throw. It comes back in
+     * {@link UploadManager.upload}'s results, which is why that method is the one
+     * to call when partial success matters; this wrapper returns only the nodes
+     * that landed.
+     *
+     * Progress arrives per finished part or file, not per byte: `fetch` exposes
+     * no upload-progress event.
+     */
+    upload(input: {
+        parentId: Id;
+        files: FileInput[];
+        relativePaths?: string[];
+        concurrency?: number;
+    }, options?: OperationOptions): Promise<FsNode[]>;
+    /**
+     * `POST /fs_nodes/create_directories` - creates a subtree in one call.
+     *
+     * Asynchronous like every bulk operation: the answer is a job id, and the
+     * job's result is the list of directories that were created. Existing levels
+     * are reused, so re-running the same paths is a no-op that creates nothing.
+     *
+     * Costs one of the twelve `fs_bulk_job` requests a minute. Pass every path in
+     * one call rather than looping.
+     *
+     * @throws {OmsApiError} 400 when `paths` is empty or the parent is not a
+     *   writable directory.
+     */
+    createDirectories(input: CreateDirectoriesInput, options?: RequestOptions): Promise<FsBulkJob>;
+    /** Alias for {@link createDirectories}, for callers who think in filesystem verbs. */
+    mkdir(input: CreateDirectoriesInput, options?: RequestOptions): Promise<FsBulkJob>;
+    /**
+     * `POST /fs_nodes` - creates ONE empty directory, synchronously, and returns
+     * it.
+     *
+     * The counterpart to {@link createDirectories}: that one is a bulk job on the
+     * twelve-a-minute bucket and answers with a job id, this one is a plain
+     * create on the general bucket and answers with the node. Use this when you
+     * want the id back immediately; use the other one for a subtree.
+     *
+     * @throws {OmsApiError} 400 when the name collides with a sibling or contains
+     *   a `/`.
+     */
+    createDirectory(input: {
+        name: string;
+        parentId: Id;
+    }, options?: RequestOptions): Promise<FsNode>;
+    /**
+     * Downloads a file's bytes into memory.
+     *
+     * Goes through `data_url` and NOT through `GET /fs_nodes/:id/data`, on
+     * purpose. `data` answers 302 to the object store, and that redirect cannot
+     * be followed with a credential attached: the store answers
+     * `Access-Control-Allow-Origin: *`, which is illegal for a credentialed
+     * request, while dropping the credential makes `data` 404 before it ever
+     * redirects. Asking for the URL and fetching it anonymously separates the two
+     * concerns and works in every runtime.
+     *
+     * Buffers the whole file. Use {@link downloadStream} for anything that should
+     * not sit in memory.
+     *
+     * @throws {OmsApiError} 404 when the node has no data attached - which
+     *   includes a directory and an upload whose bytes never landed.
+     */
+    download(id: Id, options?: RequestOptions): Promise<FileOutput>;
+    /**
+     * Streams a file's bytes without buffering them.
+     *
+     * Same `data_url` hop as {@link download} and the same reason for it. The
+     * caller owns the stream and must consume or cancel it.
+     */
+    downloadStream(id: Id, options?: RequestOptions): Promise<FsStream>;
+    /**
+     * `GET /fs_nodes/:id/data_url` - a short-lived signed URL for the bytes, for
+     * a host that would rather hand the URL to a player or a browser than move
+     * the bytes itself.
+     *
+     * Good for six hours. That window is not generous, it is necessary: a media
+     * element re-requests the object on every seek, and a five-minute URL dies
+     * mid-playback with no way to recover.
+     *
+     * The URL is a credential. Anyone holding it can read the bytes until it
+     * expires, so do not log it or put it somewhere durable.
+     */
+    downloadUrl(id: Id, options?: RequestOptions): Promise<string>;
+    /**
+     * `GET /fs_nodes/:id/zip` - a directory and every file under it that the
+     * caller can see, as a zip archive.
+     *
+     * Streamed, and streamed for real: the server generates it with
+     * `ActionController::Live`, so there is no `Content-Length` and no way to
+     * know the size in advance. Never retried automatically either - a retry
+     * restarts the whole archive from zero.
+     *
+     * @throws {OmsApiError} 400 when the node is not a directory, 404 when it is
+     *   not visible.
+     */
+    zip(id: Id, options?: RequestOptions): Promise<FsStream>;
+    /**
+     * `PATCH /fs_nodes/:id` with a new name.
+     *
+     * The returned node is checked against what was asked for. The controller
+     * silently drops any field outside its update allowlist, so a 200 alone
+     * proves nothing about the write having happened.
+     *
+     * @throws {OmsApiError} 400 when the name collides with a sibling or contains
+     *   a `/`; 401 when the caller cannot edit the node.
+     */
+    rename(id: Id, name: string, options?: RequestOptions): Promise<FsNode>;
+    /**
+     * `PATCH /fs_nodes/:id` with a new parent.
+     *
+     * The server refuses a move that would make a node its own ancestor; that
+     * cycle check is the fix for the 2026-07-27 copy outage and must not be
+     * second-guessed client-side.
+     *
+     * Like {@link rename}, the answer is verified rather than assumed.
+     *
+     * @throws {OmsApiError} 400 on a cycle or a name collision in the target;
+     *   401 when the caller cannot edit both ends.
+     */
+    move(id: Id, newParentId: Id, options?: RequestOptions): Promise<FsNode>;
+    /**
+     * `POST /fs_nodes/copy` - copies nodes into another directory.
+     *
+     * Asynchronous: the answer is a job id. Copying a directory copies its whole
+     * subtree, so this is the operation most worth watching to completion.
+     *
+     * The selection is sent as an explicit id list and this method refuses an
+     * empty one. That is not defensive tidiness: the endpoint runs the same
+     * filters the index does, so a copy with NO selection would resolve to the
+     * caller's entire listable tree and duplicate it.
+     *
+     * Costs one of the twelve `fs_bulk_job` requests a minute.
+     */
+    copy(input: CopyFsNodesInput, options?: RequestOptions): Promise<FsBulkJob>;
+    /**
+     * `POST /fs_nodes/move_to_trash` - the reversible delete. Prefer it over
+     * {@link delete}.
+     *
+     * Asynchronous: the answer is a job id. The nodes move into the trash root,
+     * keep their bytes and keep spending quota until {@link emptyTrash} runs.
+     *
+     * Refuses an empty id list for the same reason {@link copy} does: with no
+     * selection the endpoint resolves to the caller's whole listable tree.
+     *
+     * Costs one of the twelve `fs_bulk_job` requests a minute, so trash the whole
+     * selection in one call.
+     */
+    trash(ids: Id[], options?: RequestOptions): Promise<FsBulkJob>;
+    /**
+     * `POST /fs_nodes/empty_trash` - permanent, and it frees the quota.
+     *
+     * Asynchronous: the answer is a job id. Nothing survives it.
+     */
+    emptyTrash(options?: RequestOptions): Promise<FsBulkJob>;
+    /**
+     * `DELETE /fs_nodes/:id` - permanent, skipping the trash, and synchronous.
+     *
+     * Destroys the whole subtree under a directory. {@link trash} is the
+     * reversible one; reach for this only when the caller asked for exactly this.
+     */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+    /**
+     * `GET /fs_nodes/:id/shared` - the scoped view behind a share link: the node,
+     * its descendants when it is a directory, and the grant that authorised the
+     * view. Never siblings, never ancestors, never the rest of the owner's tree.
+     *
+     * Works anonymously for a public grant, which is what makes it the right call
+     * for "what is behind this share link" - {@link list} would answer nothing.
+     *
+     * @throws {OmsApiError} 404 both when the node does not exist and when no
+     *   grant covers it, on purpose: existence is not leaked.
+     */
+    shared(id: Id, options?: RequestOptions): Promise<SharedFsNodeView>;
+    /**
+     * `GET /fs_nodes/vault_root` - the encrypted vault root, created on first
+     * use. The SDK does no cryptography: the vault's manifest and its contents
+     * are the host's to encrypt and decrypt.
+     *
+     * Unlike {@link roots}, this one creates the root if it is missing, which is
+     * why `roots().vault` can be `null` while this still succeeds.
+     *
+     * @throws {OmsAuthError} 401 when anonymous.
+     */
+    vaultRoot(options?: RequestOptions): Promise<FsNode>;
+    /**
+     * Empties the path cache and the memoised roots.
+     *
+     * The cache only knows about changes THIS client made. Call this when
+     * something else may have moved things - another session, a share that was
+     * revoked, a bulk job that has just finished.
+     */
+    clearCache(): void;
+    /** Records a resolved child, evicting the oldest entry when the cache is full. */
+    private remember;
+    /**
+     * Drops everything the cache knows about a node: the entry pointing AT it,
+     * and - since it may have been a directory - every entry that resolved
+     * THROUGH it.
+     */
+    private forget;
+    /**
+     * Fetches an object-storage URL on the injected transport with no credential
+     * of ours attached. The presigned signature in the URL IS the credential, and
+     * a bearer header alongside it is what makes MinIO reject the request.
+     */
+    private fetchObject;
+}