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

A Unified Virtual Filesystem For AI Agents

import type { BoxAccessor } from '../../accessor/box.ts';
import { Delta, type FileEvent, type JsonValue, type PathSpec } from '../../types.ts';
import type { DeltaHook } from '../../events/base.ts';
/**
 * What changed on a Box mount since the last stream position, for the
 * consumer to call when Box pings.
 *
 * Box's push (`realtime_server`'s long poll answering `new_change`) carries no
 * change, so each ping is answered by one read of the user event stream from
 * the stored position, each event mapped as `BoxEventHook` maps it, with the
 * places it remembers kept in the checkpoint. A baseline takes the stream's
 * present position and lists nothing.
 *
 * Box never refuses an old `stream_position`: user events are kept for two
 * weeks to two months, and a stale position replays whatever is left, so a
 * checkpoint older than `EVENT_REPLAY_DAYS` answers UNKNOWN on the event root
 * and starts again at the present. Box may also send an event twice or out of
 * order, so each pull maps its events once each, in `created_at` order.
 *
 * Mirrors Python `BoxDeltaHook` (`core/box/events.py`).
 */
export declare class BoxDeltaHook implements DeltaHook {
    private readonly accessor;
    constructor(accessor: BoxAccessor);
    pull(root: PathSpec, checkpoint: string | null): Promise<Delta>;
}
/**
 * Map one Box user event onto mount paths.
 *
 * The consumer owns the long poll: `realtimeServer` gives the URL, a
 * `new_change` answer means read `eventsSince` from the last position, and
 * each event read goes through `toEvents` with its `event_type`. Nothing here
 * runs a loop.
 *
 * An event names the item's new place only, and a trashed item's place is the
 * Trash, so the hook remembers where each item it has mapped was, and moves
 * or forgets a folder's contents along with it. An item it has never seen
 * gets the honest answer instead: a move or rename of one is UNKNOWN on the
 * directory it landed in, and a trash of one maps to nothing and rides the
 * index TTL, as Slack's unmapped deletes do.
 *
 * A folder stands for everything below it, which Box sends no events for, so
 * a place a folder leaves or lands on is UNKNOWN, which takes the whole subtree
 * whatever the index holds; only a folder created empty (`ITEM_CREATE`) is a
 * CREATE. The mount root has no path of its own, so its trash or restore is
 * UNKNOWN on the whole mount.
 *
 * Upload of a new version and of a new file are the same `ITEM_UPLOAD`, so the
 * split between CREATE and UPDATE is also whether the item was seen before.
 */
export declare class BoxEventHook {
    private readonly accessor;
    private places;
    constructor(accessor: BoxAccessor, paths?: Readonly<Record<string, string>>);
    /** Where each item the hook has mapped is, by ref. */
    get paths(): Record<string, string>;
    toEvents(root: PathSpec, eventType: string, payload: JsonValue): Promise<readonly FileEvent[]>;
    /** Forget an item that left the mount, and report where it was. */
    private leave;
    /** Follow an item that moved within the mount. */
    private move;
    private map;
}
export declare function buildDeltaHook(accessor: BoxAccessor): DeltaHook;
//# sourceMappingURL=events.d.ts.map