@jwilleke/ngdpbase-types 0.0.0 → 5.18.0

package/lib/src/providers/BaseMediaProvider.d.ts

@@ -0,0 +1,308 @@
+/**
+ * BaseMediaProvider - Abstract base class for media providers
+ *
+ * Defines the interface that all media providers must implement.
+ * MediaManager uses this interface to interact with the underlying
+ * media storage / scanning implementation.
+ *
+ * Implements AssetProvider (Epic #405 Phase 1) so the AssetManager can
+ * consume any media backend through a single interface.
+ *
+ * @module BaseMediaProvider
+ */
+import type { AssetProvider, AssetRecord, AssetQuery, AssetPage, AssetInput, AssetMetadata, AssetMetadataPatch } from '../types/Asset.js';
+import type { CreativeWork } from '../types/Schema.js';
+import BaseProvider from './BaseProvider.js';
+/**
+ * Represents a single media item in the index.
+ */
+export interface MediaItem {
+    /** Unique identifier for this item (e.g. SHA-256 of file path) */
+    id: string;
+    /** Absolute path to the source file on disk */
+    filePath: string;
+    /** Original filename (basename) */
+    filename: string;
+    /** MIME type (e.g. "image/jpeg") */
+    mimeType: string;
+    /** Year extracted from EXIF DateTimeOriginal or path/filename fallback */
+    year?: number;
+    /** Source directory path (for display purposes) */
+    dirPath?: string;
+    /** Username of the content creator */
+    creator?: string;
+    /** File modification time in epoch milliseconds — used as a sort fallback when EXIF DateTimeOriginal is absent (#606). */
+    mtime?: number;
+    /** Structured metadata bag — EXIF, IPTC, XMP and custom fields */
+    metadata?: AssetMetadata;
+    /** Alternate-format paths for the same photo (e.g. the HEIC original when JPEG is primary) */
+    alternates?: string[];
+}
+/**
+ * Summary of a scan operation.
+ */
+export interface ScanResult {
+    /** Total number of files examined */
+    scanned: number;
+    /** Number of new items added to the index */
+    added: number;
+    /** Number of existing items updated in the index */
+    updated: number;
+    /** Number of files that could not be processed */
+    errors: number;
+    /** Number of files skipped by .ngdpbaseignore patterns or the ngdpbaseignore EXIF keyword */
+    excluded?: number;
+    /**
+     * WHICH files were skipped and why (#1056).
+     *
+     * `excluded` alone cannot answer "where did my file go", and before #1056 it
+     * did not even count four of the skip reasons — an ignored directory, a
+     * .ngdpbaseignore directory match, a dotfile and an unsupported extension
+     * all passed silently, so a file could be absent while the counter read 0.
+     *
+     * Capped at SKIPPED_REPORT_CAP entries; `skippedTruncated` says when the cap
+     * was reached, because a silently shortened list reads as a complete one.
+     */
+    skipped?: import('../utils/explainMediaPath.js').SkippedEntry[];
+    /** True when `skipped` was capped and does not list every skip. */
+    skippedTruncated?: boolean;
+    /** Number of indexed items with no usable capture date (EXIF/QuickTime) — they sort by file mtime (#807) */
+    noCaptureDate?: number;
+    /** Number of indexed items with a partial (year-only / year+month) EXIF date, defaulted to Jan 1 (#808) */
+    partialCaptureDate?: number;
+    /** Number of stale index entries pruned because their file vanished from a scanned folder (#867) */
+    removed?: number;
+    /** Total elapsed time in milliseconds */
+    elapsedMs?: number;
+    /** Folder paths that were configured but not found on disk */
+    missingFolders?: string[];
+}
+/**
+ * Abstract base class for media providers.
+ *
+ * Implement this class to add support for a new media storage backend
+ * (filesystem, S3, etc.). MediaManager always interacts through this interface.
+ */
+declare abstract class BaseMediaProvider extends BaseProvider implements AssetProvider {
+    /**
+     * Lifecycle method called once after construction to load persisted state.
+     * Default implementation is a no-op; override to load an index from disk.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Scan configured media folders and update the in-memory/persisted index.
+     *
+     * @param force      - When true, re-scan all files even if mtime is unchanged.
+     * @param onProgress - Optional callback invoked periodically with (processed, total).
+     * @returns Summary of what was scanned/added/updated/errored.
+     */
+    abstract scan(force?: boolean, onProgress?: (processed: number, total: number) => void): Promise<ScanResult>;
+    /**
+     * Return the list of years that have at least one media item, sorted
+     * descending (most recent first).
+     *
+     * @returns Array of four-digit years.
+     */
+    abstract getYears(): Promise<number[]>;
+    /**
+     * Retrieve a single media item by its unique identifier.
+     *
+     * @param id - The item identifier.
+     * @returns The MediaItem, or null if not found.
+     */
+    abstract getItem(id: string): Promise<MediaItem | null>;
+    /**
+     * Find the first media item whose filename (basename) exactly matches.
+     *
+     * Used by the `media://` URI scheme so authors can reference items by
+     * their original filename rather than an opaque SHA-256 id.
+     *
+     * Default implementation returns null; override in providers that maintain
+     * a filename-keyed index.
+     *
+     * @param filename - Basename to match (e.g. "IMG_1234.jpg").
+     * @returns The first matching MediaItem, or null if not found.
+     */
+    findByFilename(_filename: string): Promise<MediaItem | null>;
+    /**
+     * Retrieve all media items for a given year.
+     *
+     * @param year - Four-digit year (e.g. 2024).
+     * @returns Array of matching MediaItem objects (may be empty).
+     */
+    abstract getItemsByYear(year: number): Promise<MediaItem[]>;
+    /**
+     * How many items {@link getYears} and {@link getItemsByYear} cover — every
+     * item with a year (#1741). The default asks year by year, which is correct
+     * for any provider; override it where the count is one pass, because an
+     * index with many years makes the default a pass per year.
+     */
+    getItemCount(): Promise<number>;
+    /**
+     * Return items whose capture timestamp falls within [after, before], sorted
+     * ascending by capture date (#864). Either bound may be omitted. Items with
+     * no capture date are excluded. Default implementation returns [] so
+     * providers without date support degrade gracefully.
+     */
+    getItemsByDateRange(_after?: string, _before?: string): Promise<MediaItem[]>;
+    /**
+     * Generate (or retrieve cached) thumbnail data for an item.
+     *
+     * @param id   - The item identifier.
+     * @param size - Requested size string (e.g. "300x300").
+     * @returns JPEG buffer, or null if thumbnail cannot be generated.
+     */
+    abstract getThumbnailBuffer(id: string, size: string): Promise<Buffer | null>;
+    /**
+     * Retrieve all media items whose EXIF/XMP keywords name a wiki page.
+     *
+     * @param pageName - The wiki page name to match against each item's keywords.
+     * @returns Array of matching MediaItem objects (may be empty).
+     */
+    getItemsByPage(_pageName: string): Promise<MediaItem[]>;
+    /**
+     * Retrieve all media items whose EXIF/XMP keyword list contains the given keyword.
+     *
+     * Performs an exact, case-sensitive match against each entry in
+     * `metadata.keywords` (string or string[]). Items with no keywords are excluded.
+     *
+     * @param keyword - The keyword to match (e.g. "Molly's Cooking").
+     * @returns Array of matching MediaItem objects (may be empty).
+     */
+    getItemsByKeyword(_keyword: string): Promise<MediaItem[]>;
+    /**
+     * #895: all distinct EXIF/XMP keywords in the media index with item counts.
+     * Used by the admin keyword drift report (observed-media side). Default
+     * implementation returns an empty map; override in providers with an index.
+     */
+    getAllKeywordCounts(): Promise<Record<string, number>>;
+    /**
+     * #917: leaf→path map from hierarchical keyword tags. Default empty; overridden
+     * in providers that index `keywordPaths`.
+     */
+    getKeywordLeafPaths(): Promise<Record<string, string>>;
+    /**
+     * Rebuild the media index from scratch, discarding all existing entries.
+     *
+     * Default implementation returns an empty ScanResult; override in providers
+     * that maintain a persistent index.
+     *
+     * @param onProgress - Optional callback invoked periodically with (processed, total).
+     */
+    rebuild(onProgress?: (processed: number, total: number) => void): Promise<ScanResult>;
+    /**
+     * Full-text / keyword search across the media index.
+     *
+     * Renamed from `search` to avoid collision with the AssetProvider interface.
+     * MediaManager and all callers use this method name.
+     *
+     * @param query - Search query string.
+     * @returns Array of matching MediaItem objects (may be empty).
+     */
+    abstract searchItems(query: string): Promise<MediaItem[]>;
+    /**
+     * Write user-editable descriptive metadata into the source file and refresh
+     * the index entry. Only meaningful when 'edit' is in `capabilities`.
+     *
+     * Named `updateItemMetadata` (returning MediaItem) to avoid a return-type
+     * collision with AssetProvider.updateMetadata (returning AssetRecord) —
+     * same pattern as searchItems vs search.
+     *
+     * Default implementation rejects; override in providers that support writes.
+     *
+     * @param id    - The item identifier.
+     * @param patch - Fields to change (absent = keep, null = clear).
+     * @returns The refreshed MediaItem, or null if the id is unknown (or the
+     *          edit caused the item to leave the index, e.g. an
+     *          `ngdpbaseignore` keyword).
+     */
+    updateItemMetadata(_id: string, _patch: AssetMetadataPatch): Promise<MediaItem | null>;
+    /**
+     * Delegates to `utils/assetMetadataTags` (#999).
+     *
+     * The mapping moved there so attachments and media share ONE implementation
+     * — two copies of the #866 decisions (keywords-only, dual description tags,
+     * CreateDate for A/V) would drift, and each of those is subtly wrong in a way
+     * that is hard to notice.
+     *
+     * Original contract, unchanged:
+     * Map an AssetMetadataPatch onto the ExifTool tag names to write for a file
+     * of the given MIME type. Pure — no I/O; unit-testable without ExifTool.
+     *
+     * Tag choices mirror what processFile/extractCaptureDate READ back, so a
+     * post-write re-extract round-trips every edited field:
+     *   - title            → Title (XMP-dc)
+     *   - description      → Description (XMP-dc) + ImageDescription (EXIF) —
+     *                        the index reads `Description ?? ImageDescription`
+     *   - keywords         → Keywords only — ExifTool's MWG logic mirrors it to
+     *                        XMP-dc Subject; writing both doubles the list
+     *   - dateTimeOriginal → DateTimeOriginal for images; CreateDate for
+     *                        video/audio containers (QuickTime — see #750)
+     *
+     * @throws Error if `dateTimeOriginal` is present, non-null, and unparseable.
+     */
+    protected static buildMetadataWriteTags(patch: AssetMetadataPatch, mimeType: string): Record<string, unknown>;
+    /**
+     * @deprecated Use `normalizeExifDate` from `utils/assetMetadataTags`.
+     * Kept as a thin delegate so existing subclasses and tests keep working.
+     */
+    protected static normalizeExifDate(input: string): string;
+    /**
+     * Release any resources held by the provider (open file handles, worker
+     * processes, etc.).
+     */
+    abstract shutdown(): Promise<void>;
+    /** Stable provider identifier — override in subclasses. */
+    abstract readonly id: string;
+    /** Human-readable display name — override in subclasses. */
+    abstract readonly displayName: string;
+    /** Capabilities — override in subclasses. */
+    abstract readonly capabilities: import('../types/Asset.js').ProviderCapability[];
+    /**
+     * Convert a MediaItem to a schema.org-shaped CreativeWork (Slice 3 of #755).
+     *
+     * Discriminated by MIME prefix:
+     *   - image/* → ImageObject
+     *   - video/* → VideoObject
+     *   - audio/* → AudioObject
+     *   - anything else → ImageObject (best-effort; callers should filter
+     *     by mime upstream if they only want media subtypes)
+     *
+     * Internal consumers read AssetRecord (see `toAssetRecord` below);
+     * this method produces the canonical shape for JSON-LD render (Slice 6)
+     * and for CatalogSource.get() / list() fan-out from CatalogManager.
+     * Subclasses may override for provider-specific URL schemes.
+     *
+     * Public so MediaManager (the registered `CatalogSource`) can call it
+     * without exposing `toAssetRecord`'s internal projection.
+     */
+    toCreativeWork(item: MediaItem): CreativeWork;
+    /**
+     * Convert a MediaItem to a unified AssetRecord.
+     * Subclasses may override for provider-specific URL schemes.
+     */
+    protected toAssetRecord(item: MediaItem): AssetRecord;
+    /**
+     * AssetProvider.search() — fans out to searchItems() and maps results.
+     */
+    search(query: AssetQuery): Promise<AssetPage>;
+    /**
+     * AssetProvider.getById() — delegates to getItem().
+     */
+    getById(id: string): Promise<AssetRecord | null>;
+    /**
+     * AssetProvider.getThumbnail() — delegates to getThumbnailBuffer().
+     * Default size "300x300" when not specified.
+     */
+    getThumbnail(id: string, size: string): Promise<Buffer | null>;
+    /**
+     * AssetProvider.store() — media providers are read-only; always throws.
+     * Declared to satisfy the interface typing; runtime guard via capabilities check.
+     */
+    store(_buffer: Buffer, _info: AssetInput): Promise<AssetRecord>;
+    /**
+     * AssetProvider.delete() — media providers are read-only; always returns false.
+     */
+    delete(_id: string): Promise<boolean>;
+}
+export default BaseMediaProvider;

package/lib/src/providers/BasePageProvider.d.ts

@@ -0,0 +1,337 @@
+import type { ProviderInfo, SavedPage, StoreDeletedEntry, StoreFileLocation, StorePageEntry } from '../types/Provider.js';
+import { WikiPage, PageFrontmatter, PageInfo, PageSaveOptions, PageListOptions } from '../types/index.js';
+import { VersionHistoryEntry, VersionContent, VersionDiff } from '../types/index.js';
+import BaseProvider from './BaseProvider.js';
+import { type PrivateStoreLayout } from '../utils/privateStorePath.js';
+import { type StoreSearchDocument } from '../utils/storeSearchIndex.js';
+import type { ActorContext } from '../context/ActorContext.js';
+/**
+ * WikiEngine interface (simplified)
+ * TODO: Create full WikiEngine type definition in Phase 4
+ */
+interface WikiEngine {
+    getManager<T = unknown>(name: string): T | undefined;
+}
+/**
+ * BasePageProvider - Abstract interface for page storage providers
+ *
+ * All page storage providers must extend this class and implement its methods.
+ * Providers handle the actual storage and retrieval of wiki pages, whether
+ * from filesystem, database, cloud storage, or other backends.
+ *
+ * This follows JSPWiki's provider pattern for pluggable storage backends.
+ *
+ * @class BasePageProvider
+ * @abstract
+ *
+ * @property {WikiEngine} engine - Reference to the wiki engine
+ * @property {boolean} initialized - Whether provider has been initialized
+ *
+ * @see {@link FileSystemProvider} for filesystem implementation
+ * @see {@link PageManager} for usage
+ *
+ * @example
+ * class MyProvider extends BasePageProvider {
+ *   async initialize() {
+ *     const config = this.engine.getManager('ConfigurationManager');
+ *     this.storagePath = config.getProperty('myProvider.path');
+ *   }
+ *   async getPage(identifier: string) {
+ *     // Implementation
+ *   }
+ * }
+ */
+declare abstract class BasePageProvider extends BaseProvider {
+    /** Reference to the wiki engine */
+    protected engine: WikiEngine;
+    /** Whether provider has been initialized */
+    protected initialized: boolean;
+    /**
+     * Private-store folder names (#1382). ConfigurationManager is the only
+     * source; {@link applyPrivateStoreLayout} reads them in `initialize()`.
+     * Defaults match `config/app-default-config.json`.
+     */
+    protected privateStoreLayout: PrivateStoreLayout;
+    /**
+     * Create a new page provider
+     *
+     * @constructor
+     * @param {WikiEngine} engine - The WikiEngine instance
+     * @throws {Error} If engine is not provided
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Read the private-store folder names from ConfigurationManager (via
+     * getProperty, not getResolvedDataPath — they are segments under the pages
+     * storagedir, joined by the helpers in `src/utils/privateStorePath.ts`).
+     */
+    protected applyPrivateStoreLayout(configManager: {
+        getProperty(key: string, defaultValue: unknown): unknown;
+    }): void;
+    /**
+     * Which store a private page is saved into — one rule for every page
+     * provider (docs/private-stores.md, Store placement): the store the
+     * save names, else the store the page is already in, else the configured
+     * default. A store id is a plain slug.
+     *
+     * A save that names a different store for a page that already exists is
+     * refused unless it is an explicit move (#1505: `moveFrom`), which takes
+     * the page and its history with it.
+     *
+     * @param requested - `metadata.store` from the save, if any
+     * @param existing - the store the page is in now, when it is an existing private page
+     * @param moving - the save is an explicit move to another store
+     */
+    protected resolvePrivatePageStore(requested: unknown, existing: string | undefined, moving?: boolean): string;
+    /**
+     * Refuse a write into an encrypted store this caller cannot write (#1394).
+     * The one check every page provider calls before writing private bytes; the
+     * keys are reached through the caller's context, never ambiently (P1).
+     */
+    protected assertPrivateStoreWritable(ctx: ActorContext, pagesDirectory: string, owner: string, store: string): Promise<void>;
+    /** A store's pages, keyed by uuid. A store with no pages yet has none. */
+    protected readStorePages(pagesDirectory: string, location: StoreFileLocation): Promise<Record<string, StorePageEntry>>;
+    protected writeStorePages(pagesDirectory: string, location: StoreFileLocation, pages: Record<string, StorePageEntry>): Promise<void>;
+    /** Add or replace one page in its store's index. */
+    protected putStorePage(pagesDirectory: string, location: StoreFileLocation, entry: StorePageEntry): Promise<void>;
+    /** Remove one page from its store's index; false when it was not listed. */
+    protected dropStorePage(pagesDirectory: string, location: StoreFileLocation, uuid: string): Promise<boolean>;
+    /**
+     * A store's pages, read synchronously as `ctx` may: null when the store is
+     * encrypted and `ctx` does not hold its key. Page lookups are synchronous,
+     * and the index is one small file (#1456).
+     */
+    protected readStorePagesSync(pagesDirectory: string, owner: string, store: string, ctx: ActorContext | undefined): Record<string, StorePageEntry> | null;
+    /** One entry of a store's pages by uuid, title or slug (case-insensitive for the last two). */
+    protected static findInStorePages(pages: Record<string, StorePageEntry>, key: string): StorePageEntry | null;
+    /**
+     * One page of a store, by uuid, title or slug (case-insensitive for the
+     * last two) — titles are unique within a store, never across the site.
+     */
+    protected findStorePage(pagesDirectory: string, location: StoreFileLocation, key: string): Promise<StorePageEntry | null>;
+    /** A store's tombstones, keyed by page uuid. A store that has never had a delete has none. */
+    protected readStoreDeleted(pagesDirectory: string, location: StoreFileLocation): Promise<Record<string, StoreDeletedEntry>>;
+    protected writeStoreDeleted(pagesDirectory: string, location: StoreFileLocation, deleted: Record<string, StoreDeletedEntry>): Promise<void>;
+    /** Record one tombstone in its store's trash. */
+    protected putStoreDeleted(pagesDirectory: string, location: StoreFileLocation, entry: StoreDeletedEntry): Promise<void>;
+    /** Take one tombstone out; the entry it removed, or null when there was none. */
+    protected dropStoreDeleted(pagesDirectory: string, location: StoreFileLocation, uuid: string): Promise<StoreDeletedEntry | null>;
+    /** Where the store's search index lives — for a caller that must look at the file itself. */
+    protected storeSearchFile(pagesDirectory: string, owner: string, store: string): string;
+    /** True when this store has a saved search index; false means it must be built. */
+    protected storeSearchIndexExists(pagesDirectory: string, owner: string, store: string): Promise<boolean>;
+    /** A store's search documents, keyed by page uuid. A store with no index yet has none. */
+    protected readStoreSearch(pagesDirectory: string, location: StoreFileLocation): Promise<Record<string, StoreSearchDocument>>;
+    protected writeStoreSearch(pagesDirectory: string, location: StoreFileLocation, documents: Record<string, StoreSearchDocument>): Promise<void>;
+    /** Add or replace one page's document in its store's search index. */
+    protected putStoreSearchDocument(pagesDirectory: string, location: StoreFileLocation, document: StoreSearchDocument): Promise<void>;
+    /** Remove one page's document; false when it was not there. */
+    protected dropStoreSearchDocument(pagesDirectory: string, location: StoreFileLocation, uuid: string): Promise<boolean>;
+    /**
+     * Initialize the provider with configuration
+     *
+     * IMPORTANT: Providers MUST access configuration via ConfigurationManager:
+     *   const configManager = this.engine.getManager('ConfigurationManager');
+     *   const value = configManager.getProperty('key', 'default');
+     *
+     * Do NOT read configuration files directly.
+     *
+     * @async
+     * @abstract
+     * @returns {Promise<void>}
+     * @throws {Error} Always throws - must be implemented by subclass
+     */
+    abstract initialize(): Promise<void>;
+    /**
+     * Get complete page with content and metadata
+     *
+     * @async
+     * @abstract
+     * @param {string} identifier - Page UUID, title, or slug
+     * @returns {Promise<WikiPage|null>} Page object or null if not found
+     * @throws {Error} Always throws - must be implemented by subclass
+     */
+    abstract getPage(identifier: string, ctx: ActorContext): Promise<WikiPage | null>;
+    /**
+     * Get only page content (without metadata)
+     *
+     * @async
+     * @abstract
+     * @param {string} identifier - Page UUID, title, or slug
+     * @returns {Promise<string>} Markdown content
+     * @throws {Error} Always throws - must be implemented by subclass
+     */
+    abstract getPageContent(identifier: string, ctx: ActorContext): Promise<string>;
+    /**
+     * Get only page metadata (without content)
+     *
+     * @async
+     * @abstract
+     * @param {string} identifier - Page UUID, title, or slug
+     * @returns {Promise<PageFrontmatter|null>} Metadata object or null if not found
+     * @throws {Error} Always throws - must be implemented by subclass
+     */
+    abstract getPageMetadata(identifier: string, ctx: ActorContext): Promise<PageFrontmatter | null>;
+    /**
+     * Save page content and metadata
+     *
+     * @async
+     * @abstract
+     * @param {string} pageName - Page title
+     * @param {string} content - Markdown content
+     * @param {Partial<PageFrontmatter>} metadata - Frontmatter metadata
+     * @param ctx - Who is writing (#1179): the request's subject, or a JobContext. Mandatory and positional — a store write reaches this caller's keys through it (#1382)
+     * @param {PageSaveOptions} options - Save options
+     * @returns {Promise<void>}
+     * @throws {Error} Always throws - must be implemented by subclass
+     */
+    abstract savePage(pageName: string, content: string, metadata: Partial<PageFrontmatter> | undefined, ctx: ActorContext, options?: PageSaveOptions): Promise<SavedPage>;
+    /**
+     * Delete a page
+     * @param {string} identifier - Page UUID or title
+     * @param ctx - Who is deleting (#1179). Names the deleter on the record and reaches a private store's keys (#1382)
+     * @returns {Promise<boolean>} True if deleted, false if not found
+     */
+    abstract deletePage(identifier: string, ctx: ActorContext): Promise<boolean>;
+    invalidatePageCache(_identifier: string): string | null;
+    getPageUUID(_identifier: string, _ctx: ActorContext): string | null;
+    /**
+     * Check if page exists
+     * @param {string} identifier - Page UUID or title
+     * @returns {boolean}
+     */
+    abstract pageExists(identifier: string, ctx: ActorContext): boolean;
+    /**
+     * Get all page titles
+     * @returns {Promise<string[]>} Sorted array of page titles
+     */
+    abstract getAllPages(): Promise<string[]>;
+    /**
+     * Get all page titles (explicit alias for getAllPages)
+     * Prefer this for new code that only needs page names.
+     * Use getAllPageInfo() when you need uuid/slug/author etc.
+     * @returns {Promise<string[]>} Sorted array of page titles
+     */
+    getAllPageNames(): Promise<string[]>;
+    /**
+     * Get all page info objects
+     * @param {PageListOptions} options - List options
+     * @returns {Promise<PageInfo[]>} Array of page info objects
+     */
+    abstract getAllPageInfo(options?: PageListOptions): Promise<PageInfo[]>;
+    /**
+     * Find page by various identifiers
+     * @param {string} identifier - UUID, title, or slug
+     * @returns {string|null} Canonical page title or null
+     */
+    abstract findPage(identifier: string): string | null;
+    /**
+     * Get a page by its UUID
+     * @param {string} uuid - Page UUID
+     * @returns {Promise<WikiPage | null>} Page or null if not found
+     */
+    abstract getPageByUUID(uuid: string, ctx: ActorContext): Promise<WikiPage | null>;
+    /**
+     * Get a page by its slug
+     * @param {string} slug - URL-friendly slug
+     * @returns {Promise<WikiPage | null>} Page or null if not found
+     */
+    abstract getPageBySlug(slug: string, ctx: ActorContext): Promise<WikiPage | null>;
+    /**
+     * Refresh internal cache/index
+     * Re-scans storage and rebuilds indexes
+     * @returns {Promise<void>}
+     */
+    abstract refreshPageList(): Promise<void>;
+    /**
+     * Get version history for a page
+     *
+     * Returns an array of version metadata entries for the specified page.
+     * Providers that don't support versioning should not implement this method.
+     *
+     * @param {string} identifier - Page UUID or title
+     * @param {number} limit - Maximum number of versions to return
+     * @returns {Promise<VersionHistoryEntry[]>} Array of version history entries
+     * @example
+     * // Returns:
+     * [
+     *   {
+     *     version: 1,
+     *     timestamp: "2025-01-01T00:00:00.000Z",
+     *     author: "user@example.com",
+     *     changeType: "create",
+     *     message: "Initial version",
+     *     contentSize: 1234,
+     *     compressed: false
+     *   },
+     *   {
+     *     version: 2,
+     *     timestamp: "2025-01-02T10:30:00.000Z",
+     *     author: "editor@example.com",
+     *     changeType: "update",
+     *     message: "Added section",
+     *     contentSize: 567,
+     *     compressed: false
+     *   }
+     * ]
+     */
+    getVersionHistory(_identifier: string, _ctx: ActorContext, _limit?: number): Promise<VersionHistoryEntry[]>;
+    /**
+     * Get a specific version of a page
+     *
+     * Retrieves the content and metadata for a specific version number.
+     * For delta-based storage, this reconstructs the content by applying diffs.
+     *
+     * @param {string} identifier - Page UUID or title
+     * @param {number} version - Version number to retrieve
+     * @returns {Promise<VersionContent>} Version content and metadata
+     * @throws {Error} If version does not exist
+     */
+    getPageVersion(_identifier: string, _version: number, _ctx: ActorContext): Promise<VersionContent>;
+    /**
+     * Compare two versions of a page
+     *
+     * Generates a diff between two versions showing what changed.
+     * Returns structured diff data suitable for rendering.
+     *
+     * @param {string} identifier - Page UUID or title
+     * @param {number} v1 - First version number (older)
+     * @param {number} v2 - Second version number (newer)
+     * @returns {Promise<VersionDiff>} Diff data structure
+     */
+    compareVersions(_identifier: string, _v1: number, _v2: number, _ctx: ActorContext): Promise<VersionDiff>;
+    /**
+     * Purge old versions based on retention policy
+     *
+     * Removes old versions according to configuration settings (maxVersions, retentionDays).
+     * Always preserves v1 (needed for delta reconstruction) and recent versions.
+     *
+     * @param {string} identifier - Page UUID or title
+     * @param options - Purge options (keepLatest, retentionDays, keepMilestones, dryRun)
+     * @returns Purge result with versionsRemoved, versionsPurged, dryRun, spaceFreed, message
+     */
+    purgeOldVersions(_identifier: string, _options?: {
+        keepLatest?: number;
+        retentionDays?: number;
+        keepMilestones?: boolean;
+        dryRun?: boolean;
+    }): Promise<{
+        versionsRemoved: number;
+        versionsPurged: number[];
+        dryRun: boolean;
+        spaceFreed: number;
+        message: string;
+    }>;
+    /**
+     * Get provider information
+     * @returns {ProviderInfo} Provider metadata
+     */
+    getProviderInfo(): ProviderInfo;
+    /**
+     * Shutdown the provider (cleanup resources)
+     * @returns {Promise<void>}
+     */
+    shutdown(): void;
+}
+export default BasePageProvider;
+export { WikiEngine, ProviderInfo };