@struktoai/mirage-core/dist/core/box/resolve.d.ts

A Unified Virtual Filesystem For AI Agents

import type { BoxAccessor } from '../../accessor/box.ts';
import { type FileStat, type PathSpec } from '../../types.ts';
import { type BoxFileInfo, type BoxItem, type BoxSearchItem } from './api.ts';
export declare function pathParts(path: PathSpec): string[];
/**
 * Walk folder listings to resolve each component of a path.
 *
 * Box has no path-addressing endpoint, so ids are resolved by listing each
 * level from the mount root. Returns the Box item for every component that
 * resolved, in order; a missing component, or one below a non-folder, ends
 * the chain early.
 */
export declare function resolveChain(accessor: BoxAccessor, parts: string[]): Promise<BoxItem[]>;
/**
 * Resolve a mount-relative path to its Box item.
 *
 * Returns null if any component is missing, or a non-final component is not
 * a folder.
 */
export declare function resolveItem(accessor: BoxAccessor, parts: string[]): Promise<BoxItem | null>;
/**
 * The Box item a listed row names, in the shape a lookup answers. Mirrors
 * Python's `item_of`.
 */
export declare function itemOf(row: FileStat | null | undefined): BoxItem | null;
/**
 * The folder a create at `path` lands in: the mount root's, or what is at the
 * parent path. A missing or non-directory parent names the operand, as
 * mkdir(2) does. Mirrors Python's `parent_folder`.
 */
export declare function parentFolder(accessor: BoxAccessor, path: PathSpec, parent: FileStat | null | undefined): string;
/**
 * Mount-relative path of an item, from its `path_collection`.
 *
 * Box lists an item's ancestors from the account root down to its immediate
 * parent, excluding the item itself; everything up to and including the mount
 * root folder is trimmed. Null when the mount root is not among the
 * ancestors, which is every item outside the mount.
 */
export declare function mountRelativeKey(item: Pick<BoxSearchItem, 'name' | 'path_collection'>, rootFolderId: string): string | null;
/**
 * Whether a live `GET /files/{id}` answer is the active file at `path`.
 *
 * Box enforces unique names per folder, so a file whose live chain of names
 * from the mount root equals the path is the very item walking the path would
 * reach. Four checks: the item is a file, its `item_status` is active, its
 * `path_collection` starts at All Files and passes no Trash folder, and its
 * names below the mount root equal the path. The name comparison alone
 * already rejects a trashed chain below the mount root; the All Files check
 * also refuses a chain that does not start at All Files yet passes through
 * the mount root with the right names below it, which the name comparison
 * alone would accept, and with the Trash check catches the mount root itself
 * in Trash.
 */
export declare function namesThisPath(accessor: BoxAccessor, item: BoxFileInfo, path: PathSpec): boolean;
/**
 * The item a listed row names, as `liveItem` finds it at `path` now; null for
 * no row. Mirrors Python's `live_item_of`.
 */
export declare function liveItemOf(accessor: BoxAccessor, path: PathSpec, row: FileStat | null | undefined): Promise<BoxItem | null>;
/**
 * What is at `path` now, asked live. A listed row can be older than the
 * path's item: another client may have moved, renamed or trashed it, and a
 * change made by its id would land at another path. So a check and every
 * change ask again: one `GET /files/{id}` or `GET /folders/{id}` by the id the
 * row names, when the answer is still the active item at exactly this path,
 * else a walk of the listings from the mount root. Only the walk may call a
 * path gone, so a 404 or 403 by id falls back to it rather than answering
 * null. Mirrors Python's `live_item`.
 */
export declare function liveItem(accessor: BoxAccessor, path: PathSpec, lead: BoxItem | null): Promise<BoxItem | null>;
//# sourceMappingURL=resolve.d.ts.map