@struktoai/mirage-core/dist/vfs/gdocs/gdocs.d.ts

A Unified Virtual Filesystem For AI Agents

import { GDocsAccessor } from '../../accessor/gdocs.ts';
import type { GoogleConfig } from '../../core/google/config.ts';
import type { DeltaHook } from '../../events/base.ts';
import type { FileStat, PathSpec } from '../../types.ts';
import { type DirListing } from '../../types.ts';
import { BaseVFS } from '../base.ts';
import type { RedactedSchema } from '../secrets.ts';
import type { ConfigState, Handed } from '../types.ts';
import { GDocsConfig } from './config.ts';
export declare const VFS_MD = "```text\n{prefix}\n  owned/     # docs you created\n    <YYYY-MM-DD>_<title>__<doc-id>.gdoc.json\n  shared/    # docs others shared with you\n    <YYYY-MM-DD>_<title>__<doc-id>.gdoc.json\n```\n\n- `<YYYY-MM-DD>` is the file's `modifiedTime`, so a date glob such as\n  `2026-05-*` narrows by it.\n- `<title>` is sanitized: spaces and any character outside\n  `[A-Za-z0-9_.-]` become `_`, at most 100 characters.\n- `<doc-id>` is the Google Docs document id.\n- `shared/` holds docs shared with you by others; ones you own\n  and shared with others are still in `owned/`.\n\nA `.gdoc.json` holds the Google Docs API `documents.get` response, read\nwith `includeTabsContent=true` so every tab is present:\n\n```jsonc\n{\n  \"documentId\": \"...\",\n  \"title\": \"...\",\n  \"tabs\": [                            // one entry per top-level tab\n    {\n      \"tabProperties\": {\n        \"tabId\": \"t.0\",                // names a tab for gws docs write\n        \"title\": \"Tab 1\",\n        \"index\": 0\n      },\n      \"documentTab\": {\n        \"body\": {\n          \"content\": [\n            {                          // one element per block\n              \"paragraph\": {\n                \"elements\": [\n                  { \"textRun\": { \"content\": \"the actual text\\n\",\n                                 \"textStyle\": {...} } }\n                ],\n                \"paragraphStyle\": {...}\n              }\n            },\n            { \"table\": {...} },\n            { \"sectionBreak\": {...} }\n          ]\n        },\n        \"documentStyle\": {...},\n        \"namedStyles\": {...}\n      },\n      \"childTabs\": [ { ...same shape, nested to any depth... } ]\n                                       // a nested tab also carries\n                                       // parentTabId and nestingLevel;\n                                       // a root tab carries neither\n    }\n  ],\n  \"revisionId\": \"...\"\n}\n```\n\nThere is no top-level .body. A tab-aware response leaves the singleton\nfields (`.body`, `.documentStyle`, `.namedStyles`) empty and hangs every\ntab's content off `.tabs[].documentTab` instead. Tabs also nest, so text\ncan sit at any depth under `.childTabs`; the recursive recipes below read\na one-tab and a fifty-tab document alike.\n\nUseful `jq` paths:\n\n```jq\n.title\n[.. | .tabProperties? // empty | .title]             # every tab name\n[.. | .textRun? // empty | .content] | add           # all text, any depth\n[.. | .tabProperties? // empty] | length             # tab count\n[.tabs[0].documentTab.body.content[]\n      | .paragraph?.elements[]?.textRun.content] | add   # first tab only\n.revisionId\n```\n\nThe first block of a body is always a `sectionBreak`, which carries no\n`.paragraph`, so a path through `.paragraph` needs the `?` or it fails\nwith `Cannot iterate over null`.\n\nDelete, on a `write` path:\n\n```sh\nrm {prefix}/owned/<file>.gdoc.json   # deletes it from Drive for good\nrm -f <path>                       # ignores a missing file\n```\n\nOnly `.gdoc.json` files can be removed; `owned/` and `shared/` cannot.\n\nRename to a new title, on a `write` path:\n\n```sh\nmv {prefix}/owned/<date>_<old>__<id>.gdoc.json \\\n   {prefix}/owned/<date>_<new>__<id>.gdoc.json\n```\n\nKeep the folder, the date and the id, and spell the title the way the\nlisting does (spaces become `_`); any other name is refused.";
export declare class GDocsVFS extends BaseVFS {
    readonly name: string;
    readonly cachesReads: boolean;
    readonly indexTtl: number;
    readonly readRevalidatable: boolean;
    vfsMd: string;
    readonly wholeWordSearch: boolean;
    readonly config: GDocsConfig;
    readonly accessor: GDocsAccessor;
    constructor(config: GDocsConfig);
    readonly handed: {
        readonly unlink: readonly ["entry"];
        readonly rename: readonly ["entry"];
    };
    readonly renderers: Readonly<Record<string, string>>;
    /**
     * Whether this VFS answers `name`; with no walk limit it reads every
     * file rather than ask the service's search.
     */
    supports(name: string): boolean;
    filesContaining(path: PathSpec, text: string, opts: {
        wholeWord: boolean;
        ignoreCase: boolean;
    }): Promise<PathSpec[] | null>;
    readdir(path: PathSpec): Promise<FileStat[] | DirListing>;
    /** Render the file as the JSON its `.gdoc.json` name holds. */
    readDoc(path: PathSpec, _handed?: Handed, offset?: number, size?: number | null): Promise<Uint8Array>;
    stat(path: PathSpec): Promise<FileStat>;
    unlink(path: PathSpec, handed?: Handed): Promise<void>;
    rename(src: PathSpec, dst: PathSpec, handed?: Handed): Promise<void>;
    deltaHook(): DeltaHook;
    getState(): Promise<ConfigState<RedactedSchema<typeof GoogleConfig>>>;
}
//# sourceMappingURL=gdocs.d.ts.map