wiki-graph-sdk 0.7.0

package/dist/archives.d.ts

@@ -0,0 +1,249 @@
+import { BuildJobTarget, ReadonlyDocument, WikiGraphProgressCallback, File, QueryIndexScope, ParsedWikiGraphLibraryUri, ArchiveFindOptions, ArchiveFindResult, ArchiveCollectionOptions, ArchiveCollectionResult, ArchiveSourceLocatorResult, readSearchIndexCapabilityStatus, rebuildArchiveSearchIndex, ChapterEntry, ChapterDetails, IndexArtifactKind, ChapterStage, setChapterSource, setChapterTitle, ChapterTree, applyChapterTree, ChapterTreeApplyResult, ArchivePage, ArchiveRelatedResult, ArchiveEvidence, ArchivePack, BookMeta } from 'wiki-graph-core';
+import { W as WikiGraphJobRuntime } from './jobs-Dd5PMSId.js';
+import { GenerationPlanningCost, GenerationPerformanceHint } from './planning.js';
+
+interface WikiGraphArchiveInspectImprovement {
+    readonly kind: "add-source" | "build" | "sync-index";
+    readonly missingChapters?: number;
+    readonly missingWords?: number;
+    readonly planning?: GenerationPlanningCost;
+    readonly recommendation: string;
+    readonly task?: BuildJobTarget;
+    readonly title: string;
+}
+interface WikiGraphArchiveInspectCoverage {
+    readonly coveredChapters: number;
+    readonly coveredWords: number;
+    readonly percent: string;
+    readonly totalChapters: number;
+    readonly totalWords: number;
+}
+interface WikiGraphArchiveInspectChapterReference {
+    readonly chapterId: number;
+    readonly locatedUri: string;
+    readonly title: string | null;
+    readonly uri: string;
+}
+interface WikiGraphArchiveInspectReport {
+    readonly archiveUri: string;
+    readonly uri: string;
+    readonly scope: {
+        readonly chapterId?: number;
+        readonly type: "archive" | "chapter";
+    };
+    readonly content: {
+        readonly chapters: {
+            readonly content: number;
+            readonly planned: number;
+            readonly total: number;
+        };
+        readonly sourceWords: number;
+        readonly summaryWords: number;
+    };
+    readonly localIndexCache: {
+        readonly blockedBy?: "missing-search-artifacts";
+        readonly current: boolean;
+        readonly impact?: string;
+        readonly resource?: string;
+        readonly status: "blocked" | "current" | "missing-or-outdated";
+        readonly syncAvailable: boolean;
+    };
+    readonly coverage: {
+        readonly ftsIndexArtifact: WikiGraphArchiveInspectCoverage;
+        readonly knowledgeGraph: WikiGraphArchiveInspectCoverage;
+        readonly readingGraph: WikiGraphArchiveInspectCoverage;
+        readonly summary: WikiGraphArchiveInspectCoverage;
+        readonly summaryEmbeddingIndexArtifact: WikiGraphArchiveInspectCoverage;
+        readonly sourceEmbeddingIndexArtifact: WikiGraphArchiveInspectCoverage;
+    };
+    readonly query: {
+        readonly ready: boolean;
+    };
+    readonly searchArtifacts: {
+        readonly blockedChapters: readonly WikiGraphArchiveInspectChapterReference[];
+        readonly ready: boolean;
+        readonly resource?: string;
+        readonly status: "incomplete" | "ready";
+    };
+    readonly retrievalGuidance: readonly string[];
+    readonly improvements: readonly WikiGraphArchiveInspectImprovement[];
+    readonly performanceHints: readonly GenerationPerformanceHint[];
+    readonly summaryCoverageNote: string;
+}
+declare function createWikiGraphArchiveInspectReport(document: ReadonlyDocument, options: {
+    readonly archiveUri: string;
+    readonly chapterId?: number;
+}): Promise<WikiGraphArchiveInspectReport>;
+
+interface WikiGraphOperationOptions {
+    readonly signal?: AbortSignal;
+}
+type SearchIndexCapabilityStatus = Awaited<ReturnType<typeof readSearchIndexCapabilityStatus>>;
+type SearchIndexProgressEvent = Parameters<NonNullable<Parameters<typeof rebuildArchiveSearchIndex>[1]>>[0];
+type WikiGraphChapterResetStage = Exclude<ChapterStage, "summarized">;
+type WikiGraphChapterSourceOptions = NonNullable<Parameters<typeof setChapterSource>[3]>;
+type WikiGraphChapterTreeInput = Parameters<typeof applyChapterTree>[1];
+interface WikiGraphArchiveLocation {
+    readonly archiveFile: File;
+    readonly archiveKey: string;
+    readonly archivePath: string;
+    readonly indexScope: QueryIndexScope;
+    readonly libraryArchiveTarget?: ParsedWikiGraphLibraryUri;
+    readonly libraryDirtyTarget?: ParsedWikiGraphLibraryUri;
+    readonly locatedUri: string;
+    readonly publicArchiveUri?: string;
+}
+interface WikiGraphArchiveCreateOptions extends WikiGraphOperationOptions {
+    readonly importPath?: string;
+    readonly onProgress?: WikiGraphProgressCallback;
+    readonly path: string;
+    readonly replace?: boolean;
+}
+interface WikiGraphArchiveCreateResult {
+    readonly locatedUri: string;
+    readonly path: string;
+}
+declare class WikiGraphArchiveExistsError extends Error {
+    readonly code = "WIKI_GRAPH_ARCHIVE_EXISTS";
+    readonly path: string;
+    constructor(path: string);
+}
+interface WikiGraphArchiveWriteOptions extends WikiGraphOperationOptions {
+    readonly onIndexSyncError?: (error: unknown) => void;
+    readonly refreshLibraryIndex?: boolean;
+    readonly searchIndexWritebackPolicy?: "archive" | "cache";
+}
+interface WikiGraphArchiveIndexStatus {
+    readonly capabilities: SearchIndexCapabilityStatus;
+    readonly current: boolean;
+}
+interface WikiGraphArchiveCover {
+    readonly data: Uint8Array;
+    readonly mediaType: string;
+    readonly path: string;
+}
+interface WikiGraphArchiveIndexSyncOptions extends WikiGraphOperationOptions {
+    readonly onProgress?: (event: SearchIndexProgressEvent) => void | Promise<void>;
+    readonly skipUnindexed?: boolean;
+}
+interface WikiGraphChapterArtifactStatus {
+    readonly artifact?: {
+        readonly createdAt: string;
+        readonly metadata: Readonly<Record<string, unknown>>;
+        readonly sourceRevision: number;
+    };
+    readonly chapterId: number;
+    readonly current: boolean;
+    readonly kind: IndexArtifactKind;
+    readonly missing: boolean;
+    readonly revision: number;
+}
+interface WikiGraphChapterMoveOptions {
+    readonly afterPath?: string;
+    readonly beforePath?: string;
+    readonly first?: boolean;
+    readonly last?: boolean;
+    readonly parentPath?: string;
+    readonly root?: boolean;
+}
+interface WikiGraphArchiveScopeOptions {
+    readonly chapters?: readonly number[];
+    readonly depth?: number;
+}
+interface WikiGraphArchiveSearchOptions extends Omit<ArchiveFindOptions, "archiveKey" | "chapters">, WikiGraphArchiveScopeOptions, WikiGraphOperationOptions {
+}
+interface WikiGraphArchiveListOptions extends Omit<ArchiveCollectionOptions, "chapters">, WikiGraphArchiveScopeOptions, WikiGraphOperationOptions {
+}
+interface WikiGraphArchivePageOptions extends WikiGraphOperationOptions {
+    readonly backlinks?: boolean;
+    readonly evidenceLimit?: number;
+    readonly order?: "doc-asc" | "doc-desc";
+    readonly sourceContext?: number;
+}
+interface WikiGraphArchiveRelatedOptions extends WikiGraphOperationOptions {
+    readonly cursor?: string;
+    readonly evidenceLimit?: number;
+    readonly limit?: number;
+    readonly order?: "doc-asc" | "doc-desc";
+    readonly query?: string;
+    readonly role?: "any" | "object" | "self" | "subject";
+    readonly skipUnindexed?: boolean;
+    readonly sourceContext?: number;
+}
+interface WikiGraphArchiveEvidenceOptions extends WikiGraphOperationOptions {
+    readonly cursor?: string;
+    readonly limit?: number;
+    readonly order?: "doc-asc" | "doc-desc";
+    readonly query?: string;
+    readonly skipUnindexed?: boolean;
+    readonly sourceContext?: number;
+}
+interface WikiGraphArchiveScope {
+    readonly chapterIds: readonly number[];
+    readonly entries: readonly ChapterEntry[];
+}
+declare class WikiGraphArchiveManager {
+    #private;
+    constructor(runtime: WikiGraphJobRuntime);
+    create(options: WikiGraphArchiveCreateOptions): Promise<WikiGraphArchiveCreateResult>;
+    open(uriOrPath: string, options?: WikiGraphOperationOptions): Promise<WikiGraphArchiveHandle>;
+}
+declare class WikiGraphArchiveHandle {
+    #private;
+    constructor(runtime: WikiGraphJobRuntime, location: WikiGraphArchiveLocation);
+    get archiveKey(): string;
+    get indexScope(): QueryIndexScope;
+    get locatedUri(): string;
+    get objectUri(): string;
+    get path(): string;
+    inspect(options?: WikiGraphOperationOptions & {
+        readonly chapterId?: number;
+    }): Promise<WikiGraphArchiveInspectReport>;
+    search(query: string, options?: WikiGraphArchiveSearchOptions): Promise<ArchiveFindResult>;
+    list(options?: WikiGraphArchiveListOptions): Promise<ArchiveCollectionResult | ArchiveSourceLocatorResult>;
+    ensureSearchIndex(options?: WikiGraphArchiveScopeOptions & WikiGraphOperationOptions): Promise<void>;
+    getSearchIndexStatus(options?: WikiGraphOperationOptions): Promise<WikiGraphArchiveIndexStatus>;
+    syncSearchIndex(options?: WikiGraphArchiveIndexSyncOptions): Promise<{
+        readonly rebuilt: boolean;
+    }>;
+    cleanSearchIndex(options?: WikiGraphOperationOptions): Promise<WikiGraphArchiveIndexStatus>;
+    listChapters(options?: WikiGraphOperationOptions): Promise<readonly ChapterEntry[]>;
+    getChapter(path: string, options?: WikiGraphOperationOptions): Promise<ChapterEntry>;
+    addChapter(options: {
+        readonly parentPath?: string;
+        readonly source?: string;
+        readonly title?: string;
+    }): Promise<ChapterDetails>;
+    getChapterArtifact(path: string, kind: IndexArtifactKind): Promise<WikiGraphChapterArtifactStatus>;
+    deleteChapterArtifact(path: string, kind: IndexArtifactKind): Promise<{
+        readonly chapterId: number;
+        readonly deleted: true;
+        readonly kind: IndexArtifactKind;
+    }>;
+    moveChapter(path: string, options: WikiGraphChapterMoveOptions): Promise<ChapterDetails>;
+    removeChapter(path: string, recursive?: boolean): Promise<void>;
+    resetChapter(path: string, stage: WikiGraphChapterResetStage): Promise<ChapterDetails>;
+    setChapterSource(path: string, source: string, options?: WikiGraphChapterSourceOptions): Promise<ChapterDetails>;
+    setChapterSummary(path: string, summary: string): Promise<ChapterDetails>;
+    setChapterTitle(path: string, title: Parameters<typeof setChapterTitle>[2]): Promise<ChapterDetails>;
+    getChapterTree(): Promise<ChapterTree>;
+    applyChapterTree(tree: WikiGraphChapterTreeInput, options?: {
+        readonly dryRun?: boolean;
+    }): Promise<ChapterTreeApplyResult>;
+    page(objectUri?: string, options?: WikiGraphArchivePageOptions): Promise<ArchivePage>;
+    related(objectUri?: string, options?: WikiGraphArchiveRelatedOptions): Promise<ArchiveRelatedResult>;
+    evidence(objectUri?: string, options?: WikiGraphArchiveEvidenceOptions): Promise<ArchiveEvidence>;
+    pack(objectUri?: string, budget?: number, options?: WikiGraphOperationOptions): Promise<ArchivePack>;
+    getMetadata(objectPath: string, options?: WikiGraphOperationOptions): Promise<Readonly<Record<string, unknown>>>;
+    readBookMeta(options?: WikiGraphOperationOptions): Promise<BookMeta | undefined>;
+    replaceBookMeta(meta: BookMeta, options?: WikiGraphArchiveWriteOptions): Promise<BookMeta>;
+    readCover(options?: WikiGraphOperationOptions): Promise<WikiGraphArchiveCover | undefined>;
+    replaceMetadata(objectPath: string, value: Readonly<Record<string, unknown>>, options?: WikiGraphArchiveWriteOptions): Promise<Readonly<Record<string, unknown>>>;
+    putMetadata(objectPath: string, key: string, value: unknown, options?: WikiGraphArchiveWriteOptions): Promise<Readonly<Record<string, unknown>>>;
+    deleteMetadata(objectPath: string, key: string, options?: WikiGraphArchiveWriteOptions): Promise<Readonly<Record<string, unknown>>>;
+    clearMetadata(objectPath: string, options?: WikiGraphArchiveWriteOptions): Promise<Readonly<Record<string, unknown>>>;
+    resolveScope(options?: WikiGraphArchiveScopeOptions & WikiGraphOperationOptions): Promise<WikiGraphArchiveScope | undefined>;
+}
+declare function resolveWikiGraphArchiveLocation(uriOrPath: string): Promise<WikiGraphArchiveLocation>;
+
+export { type WikiGraphArchiveCover, type WikiGraphArchiveCreateOptions, type WikiGraphArchiveCreateResult, type WikiGraphArchiveEvidenceOptions, WikiGraphArchiveExistsError, WikiGraphArchiveHandle, type WikiGraphArchiveIndexStatus, type WikiGraphArchiveIndexSyncOptions, type WikiGraphArchiveInspectChapterReference, type WikiGraphArchiveInspectCoverage, type WikiGraphArchiveInspectImprovement, type WikiGraphArchiveInspectReport, type WikiGraphArchiveListOptions, type WikiGraphArchiveLocation, WikiGraphArchiveManager, type WikiGraphArchivePageOptions, type WikiGraphArchiveRelatedOptions, type WikiGraphArchiveScope, type WikiGraphArchiveScopeOptions, type WikiGraphArchiveSearchOptions, type WikiGraphArchiveWriteOptions, type WikiGraphChapterArtifactStatus, type WikiGraphChapterMoveOptions, type WikiGraphChapterResetStage, type WikiGraphChapterSourceOptions, type WikiGraphChapterTreeInput, type WikiGraphOperationOptions, createWikiGraphArchiveInspectReport, resolveWikiGraphArchiveLocation };