import { type DecodedCursor } from './storage/cursor.js'; import type { ListOptions, ListResult } from './storage/types.js'; export interface FileBrowser { name: string; url: string; /** * Bytes. Every object store already reports this in its listing (S3's * `Size`, Azure's `contentLength`, GCS's `metadata.size`), so it costs * nothing extra; local reads it with one `stat` per file on the page. * * Optional because a provider written before this existed will not set it. * The browser renders without it rather than showing a wrong number. */ size?: number; /** * Media type derived from the file extension — see `lib/util/mime.ts` for * why the extension and not the provider's stored content type. * * There is deliberately no `width`/`height` here. No listing API on any * provider reports image dimensions; getting them server-side would mean * reading every file's header, one request each on cloud storage. The * browser already downloads an image to draw its thumbnail, so the UI reads * `naturalWidth`/`naturalHeight` off the loaded element instead — free, and * absent for the non-images where dimensions are meaningless anyway. */ mimeType?: string; } export type { ListOptions, ListResult } from './storage/types.js'; /** * Entries per page when the caller does not say. A folder listing is rendered * as a thumbnail grid, so this is "enough to fill a tall screen and a bit * more". */ export declare const DEFAULT_LIST_LIMIT = 100; export interface BrowseOptions { limit?: number; cursor?: string; prefix?: string; } /** * List one level of the media folder, one page at a time. * * PAGING IS ON BY DEFAULT: `browFiles(path)` returns at most * `DEFAULT_LIST_LIMIT` entries plus a `nextCursor`. To walk a whole folder, * loop until the cursor is gone: * * ```ts * let cursor: string | undefined; * do { * const page = await browFiles(path, { cursor }); * // …use page.files / page.folders… * cursor = page.nextCursor; * } while (cursor); * ``` * * Entries come back in name order, ascending. That is not a preference — S3, * Azure Blob and GCS all list in lexicographic key order and offer no other, * so it is the only ordering every backend can serve without reading the whole * folder. For the same reason there is no total count and no page number. * * @param path the folder path, relative to the media root */ export declare const browFiles: (path: string, options?: BrowseOptions) => Promise; /** * Turn whatever the provider returned into exactly one page. * * Exported for tests: this encodes the compatibility contract that lets a * provider written before pagination keep working, and that contract is worth * pinning down. * * Two modes, decided by whether the provider produced a cursor of its own: * * PROVIDER PAGED (a native cursor came back). Its page is authoritative and is * passed through untouched apart from ordering. The native token is opaque — * it is NOT a file name, so it must never be compared against one. * * PROVIDER DID NOT PAGE (no cursor). Either the listing ended, or the provider * ignored `options` and handed back the whole folder; both are handled the * same way, because they are indistinguishable when the folder is smaller than * one page, and treating them alike costs nothing. The service applies the * prefix and the cursor itself, sorts, and cuts the page — so a third-party * provider that predates pagination still gets correct pages and a working * search, just at the cost of a full listing per page. * * The prefix is re-applied in BOTH modes. It is idempotent — a provider that * already filtered returns only matching names, so filtering again removes * nothing — and applying it unconditionally is what stops search from silently * doing nothing on a legacy provider whose folder happens to fit in one page. * That case had no other tell. */ export declare function normalizePage(result: ListResult, options: ListOptions, provider: string, cursor?: DecodedCursor): ListResult;