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

A Unified Virtual Filesystem For AI Agents

import type { WriteCondition } from '../../cache/types.ts';
import type { StaleWriteError } from '../../errors/types.ts';
import { ByteSpool } from '../../io/spool.ts';
import type { PathSpec } from '../../types.ts';
import type { ByteWindow } from '../../utils/ranges.ts';
import type { BoxTokenManager } from './client.ts';
/**
 * The refusal an `If-Match` request met (412 changed, 404 gone), null for any
 * other or a request that went plain. Mirrors Python's `refused`.
 */
export declare function refused(path: PathSpec, err: unknown, cond: WriteCondition | null, etag: string | null): Promise<StaleWriteError | null>;
/** The header that conditions a request on `etag`, empty to go plain. */
export declare function ifMatch(etag: string | null): Record<string, string>;
export declare function absentOn404<T>(virtual: string, call: () => Promise<T>): Promise<T>;
type BoxItemType = 'file' | 'folder' | 'web_link';
export interface BoxItem {
    type: BoxItemType;
    id: string;
    name: string;
    size?: number;
    modified_at?: string;
    etag?: string;
    sha1?: string;
    parent?: {
        id: string;
        type: 'folder';
    } | null;
}
interface BoxPathCollectionEntry {
    type: 'folder';
    id: string;
    name: string;
}
export interface BoxSearchItem {
    type: BoxItemType;
    id: string;
    name: string;
    path_collection?: {
        total_count: number;
        entries: BoxPathCollectionEntry[];
    };
}
/**
 * List every item in a Box folder, following offset pagination: `pageSize`
 * items per request, and no request past the one that brings `limit` items
 * other than web links (bookmarks no listing names). Mirrors Python's
 * `list_folder_items`.
 */
export declare function listFolderItems(tm: BoxTokenManager, folderId: string, opts?: {
    pageSize?: number;
    limit?: number;
}): Promise<BoxItem[]>;
/** One user event from `GET /events`; `source` is the item it is about. */
export interface BoxEvent {
    type?: string;
    event_id?: string;
    event_type?: string;
    created_at?: string;
    source?: unknown;
}
/** A `realtime_server` entry from `OPTIONS /events`. */
export interface BoxRealtimeServer {
    type: 'realtime_server';
    url: string;
    ttl?: string | number;
    max_retries?: string | number;
    retry_timeout?: number;
}
/** The current head of the user's event stream. */
export declare function eventsNow(tm: BoxTokenManager, streamType: string): Promise<string>;
/**
 * Every user event after `streamPosition`, and the new position.
 *
 * Box may answer with fewer events than `limit` while more remain, so only an
 * empty page ends the read. A page of events that does not move the position
 * on is refused: reading it again would return the same page for as long as
 * the server keeps answering that way.
 */
export declare function eventsSince(tm: BoxTokenManager, streamPosition: string, streamType: string, opts?: {
    limit?: number;
}): Promise<{
    entries: BoxEvent[];
    position: string;
}>;
/**
 * The long-poll server for the user's event stream.
 *
 * `OPTIONS /events` hands back a `realtime_server` entry; a GET on its `url`
 * with `&stream_position=<position>` blocks until Box answers `new_change`
 * (read the events) or `reconnect` (ask for a new server). The loop is the
 * caller's.
 */
export declare function realtimeServer(tm: BoxTokenManager): Promise<BoxRealtimeServer>;
export declare function getFolderInfo(tm: BoxTokenManager, folderId: string): Promise<BoxItem>;
/** `GET /files/{id}`: a file's live metadata, with its ancestry and status. */
export interface BoxFileInfo extends BoxItem {
    path_collection?: {
        total_count: number;
        entries: BoxPathCollectionEntry[];
    };
    item_status?: string;
}
/** One file's live metadata: its sha1, name, ancestry and status. */
export declare function getFileInfo(tm: BoxTokenManager, fileId: string): Promise<BoxFileInfo>;
export declare function downloadFile(tm: BoxTokenManager, fileId: string, window?: ByteWindow): Promise<Uint8Array>;
export declare function downloadFileStream(tm: BoxTokenManager, fileId: string): AsyncIterable<Uint8Array>;
/**
 * Name+content search scoped to a folder subtree. Pages Box `/search` with
 * `ancestor_folder_ids` scoping and `content_types=name,file_content` so the
 * query matches file names and the server-indexed body text. Each returned
 * item carries `path_collection` (its ancestor chain) for mount-relative path
 * reconstruction. The boolean is true when the result reached the
 * 10,000-match ceiling (a truncated set is not a trustworthy superset).
 */
export declare function searchContent(tm: BoxTokenManager, query: string, ancestorFolderId: string): Promise<{
    items: BoxSearchItem[];
    truncated: boolean;
}>;
export declare function uploadNewFile(tm: BoxTokenManager, parentId: string, name: string, data: Uint8Array | ByteSpool): Promise<unknown>;
export declare function uploadFileVersion(tm: BoxTokenManager, fileId: string, name: string, data: Uint8Array | ByteSpool, etag?: string | null): Promise<unknown>;
export declare function createFolder(tm: BoxTokenManager, parentId: string, name: string): Promise<BoxItem>;
export declare function deleteFile(tm: BoxTokenManager, fileId: string, etag?: string | null): Promise<void>;
export declare function deleteWebLink(tm: BoxTokenManager, linkId: string): Promise<void>;
export declare function deleteFolder(tm: BoxTokenManager, folderId: string, recursive?: boolean): Promise<void>;
export declare function updateFile(tm: BoxTokenManager, fileId: string, opts: {
    name?: string;
    parentId?: string;
}): Promise<BoxItem>;
export declare function updateFolder(tm: BoxTokenManager, folderId: string, opts: {
    name?: string;
    parentId?: string;
}): Promise<BoxItem>;
export declare function copyFile(tm: BoxTokenManager, fileId: string, parentId: string, name?: string): Promise<BoxItem>;
export declare function copyFolder(tm: BoxTokenManager, folderId: string, parentId: string, name?: string): Promise<BoxItem>;
export {};
//# sourceMappingURL=api.d.ts.map