wiki-graph-sdk 0.8.2 → 0.8.4

package/dist/host-IbqJ8WSV.d.ts

@@ -0,0 +1,18 @@
+import { WikiGraphPlatform, WikiGraphStorage } from 'wiki-graph-core/platform';
+
+interface WikiGraphSDKHostBase {
+    /** Process-wide runtime services. Concurrent SDKs must use one compatible platform. */
+    readonly platform?: WikiGraphPlatform;
+}
+type WikiGraphSDKHost = WikiGraphSDKHostBase & ({
+    /** Node state root for SDK configuration and other host-local state. */
+    readonly stateDir: string;
+    /** Storage roots scoped to this SDK instance or standalone operation. */
+    readonly storage: WikiGraphStorage;
+} | {
+    /** Node state root used by the default Node storage layout. */
+    readonly stateDir?: string;
+    readonly storage?: undefined;
+});
+
+export type { WikiGraphSDKHost as W };

package/dist/index-DQzLAnjf.d.ts

@@ -0,0 +1,346 @@
+import { ChapterEntry, IndexArtifactKind, ReadonlyDocument, ArchiveFindHit, ArchiveFindResult, ArchiveCollectionResult, ArchiveSourceLocator, ArchiveSourceLocatorResult, ArchiveListItem, ArchiveRelatedResult, ArchiveEvidence, WikiGraphLibrarySearchBucketPage, WikiGraphProgressCallback, SearchIndexQueryMode, QueryIndexScope, ArchiveFindOptions, ArchiveCollectionOptions, readSearchIndexCapabilityStatus, rebuildArchiveSearchIndex, ChapterDetails, ChapterStage, setChapterSource, setChapterTitle, ChapterTree, applyChapterTree, ChapterTreeApplyResult, ArchivePage, ArchivePack, BookMeta } from 'wiki-graph-core';
+import { W as WikiGraphJobRuntime } from './jobs-CRK-DZ40.js';
+import { W as WikiGraphArchiveTarget } from './target-CZ7elwmj.js';
+
+interface WikiGraphArchiveIndexArtifactInspection {
+    readonly current: boolean;
+    readonly exists: boolean;
+    readonly kind: IndexArtifactKind;
+    readonly sourceRevision?: number;
+}
+interface WikiGraphArchiveChapterInspection {
+    readonly capabilities: {
+        readonly knowledgeGraph: {
+            readonly completed: boolean;
+        };
+        readonly readingGraph: {
+            readonly completed: boolean;
+        };
+        readonly readingSummary: {
+            readonly completed: boolean;
+        };
+    };
+    readonly chapter: ChapterEntry;
+    readonly indexes: {
+        readonly fts: WikiGraphArchiveIndexArtifactInspection;
+        readonly sourceEmbedding: WikiGraphArchiveIndexArtifactInspection;
+        readonly summaryEmbedding: WikiGraphArchiveIndexArtifactInspection;
+    };
+    readonly revision: number;
+    readonly summaryWords: number;
+}
+interface WikiGraphArchiveInspection {
+    readonly archiveUri: string;
+    readonly chapters: readonly WikiGraphArchiveChapterInspection[];
+    readonly localIndexCache: {
+        readonly current: boolean;
+    };
+    readonly scope: {
+        readonly chapterId?: number;
+        readonly type: "archive" | "chapter";
+    };
+    readonly uri: string;
+}
+declare function inspectWikiGraphArchive(document: ReadonlyDocument, options: {
+    readonly archiveUri: string;
+    readonly chapterId?: number;
+}): Promise<WikiGraphArchiveInspection>;
+
+/** Options that may be changed while advancing an existing cursor. */
+interface CursorNextOptions {
+    readonly limit?: number;
+    readonly signal?: AbortSignal;
+}
+/** A runtime page constructor used for page-type identity and reconstruction. */
+type PageClass<P> = abstract new (...args: never[]) => P;
+/** The common, deliberately small surface shared by SDK result pages. */
+interface IPage<T> extends Iterable<T> {
+    nextCursor(): ICursor<this> | null;
+}
+/** A lazy continuation associated with a concrete page class. */
+interface ICursor<P extends IPage<unknown>> {
+    readonly pageClass: PageClass<P>;
+    next(options?: CursorNextOptions): Promise<P>;
+    token(): Promise<string>;
+    release(): Promise<void>;
+}
+interface CursorImplementation<P extends IPage<unknown>> {
+    readonly pageClass: PageClass<P>;
+    readonly next: (options: CursorNextOptions) => Promise<P>;
+    readonly token: () => Promise<string>;
+    readonly release?: () => Promise<void> | void;
+}
+interface PageCursorImplementation<P extends IPage<unknown>> {
+    readonly pageClass: PageClass<P>;
+    readonly rawCursor: string;
+    readonly next: (rawCursor: string, options: CursorNextOptions) => Promise<P>;
+    readonly createToken: (rawCursor: string) => Promise<string>;
+    readonly releaseToken?: (token: string) => Promise<void> | void;
+}
+/**
+ * Creates a cursor without retaining the page that created it. The callbacks
+ * are deliberately supplied by the SDK operation that owns continuation
+ * persistence; this type is only the lifecycle/typing facade.
+ */
+declare function createCursor<P extends IPage<unknown>>(implementation: CursorImplementation<P>): ICursor<P>;
+/** Adapts an existing raw cursor while creating durable state only on demand. */
+declare function createPageCursor<P extends IPage<unknown>>(implementation: PageCursorImplementation<P>): ICursor<P>;
+/** Iterates concrete pages and releases each page cursor after advancing. */
+declare function iteratePages<P extends IPage<T>, T>(firstPage: P, options?: CursorNextOptions): AsyncIterable<P>;
+/** Iterates items across all pages while managing every continuation cursor. */
+declare function iterateItems<P extends IPage<T>, T>(firstPage: P, options?: CursorNextOptions): AsyncIterable<T>;
+
+declare class ArchiveFindPage implements IPage<ArchiveFindHit> {
+    #private;
+    readonly result: ArchiveFindResult;
+    readonly chapters: ArchiveFindResult["chapters"];
+    readonly items: ArchiveFindResult["items"];
+    readonly lens: ArchiveFindResult["lens"];
+    readonly lensHint: ArchiveFindResult["lensHint"];
+    readonly limit: number;
+    readonly match: ArchiveFindResult["match"];
+    readonly rawNextCursor: string | null;
+    readonly order: ArchiveFindResult["order"];
+    readonly query: string;
+    readonly terms: readonly string[];
+    readonly types: ArchiveFindResult["types"];
+    constructor(result: ArchiveFindResult, cursor?: ICursor<ArchiveFindPage> | null);
+    static readonly pageClass: PageClass<ArchiveFindPage>;
+    [Symbol.iterator](): Iterator<ArchiveFindHit>;
+    nextCursor(): ICursor<this> | null;
+}
+declare class ArchiveCollectionPage implements IPage<ArchiveFindHit> {
+    #private;
+    readonly result: ArchiveCollectionResult;
+    readonly chapters: ArchiveCollectionResult["chapters"];
+    readonly ids: ArchiveCollectionResult["ids"];
+    readonly items: ArchiveCollectionResult["items"];
+    readonly limit: number;
+    readonly rawNextCursor: string | null;
+    readonly order: ArchiveCollectionResult["order"];
+    readonly types: ArchiveCollectionResult["types"];
+    constructor(result: ArchiveCollectionResult, cursor?: ICursor<ArchiveCollectionPage> | null);
+    static readonly pageClass: PageClass<ArchiveCollectionPage>;
+    [Symbol.iterator](): Iterator<ArchiveFindHit>;
+    nextCursor(): ICursor<this> | null;
+}
+declare class ArchiveEvidencePage implements IPage<ArchiveEvidence["items"][number]> {
+    #private;
+    readonly result: ArchiveEvidence;
+    readonly items: ArchiveEvidence["items"];
+    readonly limit: number;
+    readonly rawNextCursor: string | null;
+    constructor(result: ArchiveEvidence, cursor?: ICursor<ArchiveEvidencePage> | null);
+    static readonly pageClass: PageClass<ArchiveEvidencePage>;
+    [Symbol.iterator](): Iterator<ArchiveEvidence["items"][number]>;
+    nextCursor(): ICursor<this> | null;
+}
+declare class ArchiveRelatedPage implements IPage<ArchiveListItem> {
+    #private;
+    readonly result: ArchiveRelatedResult;
+    readonly items: ArchiveRelatedResult["items"];
+    readonly limit: number;
+    readonly rawNextCursor: string | null;
+    constructor(result: ArchiveRelatedResult, cursor?: ICursor<ArchiveRelatedPage> | null);
+    static readonly pageClass: PageClass<ArchiveRelatedPage>;
+    [Symbol.iterator](): Iterator<ArchiveListItem>;
+    nextCursor(): ICursor<this> | null;
+}
+declare class ArchiveSourceLocatorPage implements IPage<ArchiveSourceLocator> {
+    #private;
+    readonly result: ArchiveSourceLocatorResult;
+    readonly items: ArchiveSourceLocatorResult["items"];
+    readonly limit: number;
+    readonly rawNextCursor: string | null;
+    constructor(result: ArchiveSourceLocatorResult, cursor?: ICursor<ArchiveSourceLocatorPage> | null);
+    static readonly pageClass: PageClass<ArchiveSourceLocatorPage>;
+    [Symbol.iterator](): Iterator<ArchiveSourceLocator>;
+    nextCursor(): ICursor<this> | null;
+}
+declare function createArchiveFindPage(result: ArchiveFindResult, next: (cursor: string, options: CursorNextOptions) => Promise<ArchiveFindPage>, createToken: (cursor: string) => Promise<string>, releaseToken: (token: string) => Promise<void>): ArchiveFindPage;
+declare function createArchiveCollectionPage(result: ArchiveCollectionResult, next: (cursor: string, options: CursorNextOptions) => Promise<ArchiveCollectionPage>, createToken: (cursor: string) => Promise<string>, releaseToken: (token: string) => Promise<void>): ArchiveCollectionPage;
+declare function createArchiveEvidencePage(result: ArchiveEvidence, next: (cursor: string, options: CursorNextOptions) => Promise<ArchiveEvidencePage>, createToken: (cursor: string) => Promise<string>, releaseToken: (token: string) => Promise<void>): ArchiveEvidencePage;
+declare function createArchiveRelatedPage(result: ArchiveRelatedResult, next: (cursor: string, options: CursorNextOptions) => Promise<ArchiveRelatedPage>, createToken: (cursor: string) => Promise<string>, releaseToken: (token: string) => Promise<void>): ArchiveRelatedPage;
+declare function createArchiveSourceLocatorPage(result: ArchiveSourceLocatorResult, next: (cursor: string, options: CursorNextOptions) => Promise<ArchiveSourceLocatorPage>, createToken: (cursor: string) => Promise<string>, releaseToken: (token: string) => Promise<void>): ArchiveSourceLocatorPage;
+declare class LibraryBucketPage implements IPage<ArchiveFindHit> {
+    #private;
+    readonly id: string;
+    readonly items: readonly ArchiveFindHit[];
+    readonly rawNextCursor: string | null;
+    readonly query: string;
+    readonly terms: readonly string[];
+    readonly types: WikiGraphLibrarySearchBucketPage["types"];
+    constructor(result: WikiGraphLibrarySearchBucketPage, cursor?: ICursor<LibraryBucketPage> | null);
+    static readonly pageClass: PageClass<LibraryBucketPage>;
+    [Symbol.iterator](): Iterator<ArchiveFindHit>;
+    nextCursor(): ICursor<this> | null;
+}
+declare function createLibraryBucketPage(result: WikiGraphLibrarySearchBucketPage, next: (cursor: string, options: CursorNextOptions) => Promise<LibraryBucketPage>, createToken: (cursor: string) => Promise<string>, releaseToken: (token: string) => Promise<void>): LibraryBucketPage;
+
+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 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 queryMode?: SearchIndexQueryMode;
+    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 queryMode?: SearchIndexQueryMode;
+    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(target: WikiGraphArchiveTarget, options?: WikiGraphOperationOptions): Promise<WikiGraphArchiveHandle>;
+}
+declare class WikiGraphArchiveHandle {
+    #private;
+    constructor(runtime: WikiGraphJobRuntime, location: unknown);
+    get archiveKey(): string;
+    get indexScope(): QueryIndexScope;
+    get locatedUri(): string;
+    get objectUri(): string;
+    get path(): string;
+    get target(): WikiGraphArchiveTarget;
+    inspect(options?: WikiGraphOperationOptions & {
+        readonly chapterId?: number;
+    }): Promise<WikiGraphArchiveInspection>;
+    search(query: string, options?: WikiGraphArchiveSearchOptions): Promise<ArchiveFindPage>;
+    list(options?: WikiGraphArchiveListOptions): Promise<ArchiveCollectionPage | ArchiveSourceLocatorPage>;
+    ensureSearchIndex(options?: WikiGraphArchiveScopeOptions & WikiGraphOperationOptions): Promise<void>;
+    getSearchIndexStatus(options?: WikiGraphOperationOptions): Promise<WikiGraphArchiveIndexStatus>;
+    syncSearchIndex(options?: WikiGraphArchiveIndexSyncOptions): Promise<{
+        readonly rebuilt: boolean;
+    }>;
+    cleanSearchIndex(options?: WikiGraphOperationOptions): Promise<WikiGraphArchiveIndexStatus>;
+    /** Clear cached search sessions without changing the archive index. */
+    clearSearchSessions(options?: WikiGraphOperationOptions): Promise<void>;
+    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<ArchiveRelatedPage>;
+    evidence(objectUri?: string, options?: WikiGraphArchiveEvidenceOptions): Promise<ArchiveEvidencePage>;
+    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>;
+    setArchiveTitle(title: string | null, options?: WikiGraphArchiveWriteOptions): Promise<string | null>;
+    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>;
+}
+
+export { ArchiveFindPage as A, type WikiGraphChapterMoveOptions as B, type CursorImplementation as C, type WikiGraphChapterResetStage as D, type WikiGraphChapterSourceOptions as E, type WikiGraphChapterTreeInput as F, type WikiGraphOperationOptions as G, createArchiveCollectionPage as H, type ICursor as I, createArchiveEvidencePage as J, createArchiveFindPage as K, LibraryBucketPage as L, createArchiveRelatedPage as M, createArchiveSourceLocatorPage as N, createCursor as O, type PageClass as P, createLibraryBucketPage as Q, createPageCursor as R, inspectWikiGraphArchive as S, iterateItems as T, iteratePages as U, WikiGraphArchiveManager as W, ArchiveCollectionPage as a, ArchiveRelatedPage as b, ArchiveEvidencePage as c, ArchiveSourceLocatorPage as d, type CursorNextOptions as e, type IPage as f, type PageCursorImplementation as g, type WikiGraphArchiveChapterInspection as h, type WikiGraphArchiveCover as i, type WikiGraphArchiveCreateOptions as j, type WikiGraphArchiveCreateResult as k, type WikiGraphArchiveEvidenceOptions as l, WikiGraphArchiveExistsError as m, WikiGraphArchiveHandle as n, type WikiGraphArchiveIndexArtifactInspection as o, type WikiGraphArchiveIndexStatus as p, type WikiGraphArchiveIndexSyncOptions as q, type WikiGraphArchiveInspection as r, type WikiGraphArchiveListOptions as s, type WikiGraphArchivePageOptions as t, type WikiGraphArchiveRelatedOptions as u, type WikiGraphArchiveScope as v, type WikiGraphArchiveScopeOptions as w, type WikiGraphArchiveSearchOptions as x, type WikiGraphArchiveWriteOptions as y, type WikiGraphChapterArtifactStatus as z };