@jwilleke/ngdpbase-types 0.0.0 → 5.19.0

package/lib/src/managers/MediaManager.d.ts

@@ -0,0 +1,279 @@
+/**
+ * MediaManager - Manages external media files (photos, videos, etc.)
+ *
+ * Provides browsing, searching, and thumbnail access for pre-existing
+ * media files stored on external drives. Unlike AttachmentManager, this
+ * manager is read-only with respect to source files and is independent
+ * of wiki pages. A page's media are the items whose EXIF/XMP keywords name
+ * it — there is no other link, and no per-item privacy: any subject that
+ * reaches this manager sees every item, except that a share visitor is held
+ * to the share's ceiling in {@link getItem} (#1427).
+ *
+ * STUB: Actual filesystem scanning is not yet wired up (Phase 4).
+ * The manager compiles and registers cleanly; all index queries return
+ * empty results until a real FileSystemMediaProvider scan is implemented.
+ *
+ * Enabled via config: ngdpbase.media.enabled = true
+ *
+ * @class MediaManager
+ * @extends BaseManager
+ */
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import WikiContext from '../context/WikiContext.js';
+import BaseMediaProvider, { MediaItem, ScanResult } from '../providers/BaseMediaProvider.js';
+import type { CatalogSource, CatalogQuery, CatalogPage, CreativeWork, SchemaType, RebuildOpts } from '../types/Schema.js';
+declare class MediaManager extends BaseManager implements CatalogSource {
+    /** CatalogSource identifier (Slice 3 of #755 / #758). */
+    readonly sourceId = "media";
+    /** Subtypes this source produces — MIME-discriminated at item level. */
+    readonly types: readonly SchemaType[];
+    /**
+     * On-disk schema version for media-index.json (Decision 6).
+     * Bump when the persisted MediaIndexEntry shape changes; current v1 is
+     * the post-Slice-3 (#758) shape including duration/bitrate/codecs.
+     */
+    static readonly CURRENT_SCHEMA_VERSION = 1;
+    readonly currentSchemaVersion = 1;
+    /** Active media provider (null when not yet initialized) */
+    private _provider;
+    /** The configured media folders, for the degraded-state reason (#1167). */
+    private mediaFolders;
+    /** Return the active media provider for use by AssetManager. */
+    get provider(): BaseMediaProvider | null;
+    /** Thumbnail (and transcode) cache directory */
+    private _thumbnailDir;
+    /** Handle for the periodic rescan interval timer */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the MediaManager.
+     *
+     * - Creates the thumbnail directory if it does not exist.
+     * - Instantiates the FileSystemMediaProvider with config-driven settings.
+     * - Loads any existing media-index.json from disk (stub: no-op).
+     * - Schedules a periodic background rescan based on ngdpbase.media.scaninterval.
+     *
+     * @param config - Configuration overrides (passed by BaseManager pattern).
+     */
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * CatalogSource.list — query media records and emit CreativeWork shapes.
+     *
+     * Currently maps `query.text` to the underlying provider's free-text search
+     * and applies `types` filtering MIME-side. Cursor pagination is not yet
+     * implemented (initial slice); `limit` caps the page size. Source-specific
+     * filters live in `query.filters` and are ignored by this initial impl.
+     */
+    list(query: CatalogQuery): Promise<CatalogPage>;
+    /**
+     * CatalogSource.get — fetch a single media record by stable identifier
+     * (the sha256-derived media id). Returns null for not-found and for
+     * ACL-filtered (linked private page the caller can't access).
+     *
+     * CatalogManager passes through any `WikiContext` it has via a future
+     * `opts.wikiContext`; for the initial slice we accept no context and
+     * therefore can't enforce private-page ACL here — callers that need
+     * permission-aware access should continue using `getItem(id, ctx)`.
+     */
+    get(identifier: string): Promise<CreativeWork | null>;
+    /**
+     * CatalogSource.rebuild — full media index rebuild. Wraps `rebuildIndex()`
+     * so the CatalogSource contract is honoured even though MediaManager's
+     * existing admin route prefers the named method.
+     */
+    rebuild(_opts?: RebuildOpts): Promise<void>;
+    /**
+     * Every media-index write goes through here (#1751): it writes, then bumps
+     * the media-data version, so cached renders that show media re-render.
+     */
+    private writeMedia;
+    /**
+     * Rebuild the media index from scratch.
+     *
+     * Clears the in-memory index, deletes the persisted index file, then runs a
+     * full scan. All items on disk are re-indexed; stale entries for deleted
+     * files are removed because the index starts empty.
+     *
+     * @returns ScanResult summary.
+     */
+    rebuildIndex(onProgress?: (processed: number, total: number) => void): Promise<ScanResult>;
+    /**
+     * Degraded while any configured media folder cannot be read, ready otherwise (#1167).
+     *
+     * Degraded rather than a warning, even for one folder in fourteen: the
+     * operator asked for those files to be indexed and they are not, which is
+     * what degraded means (#1155) — configured, wanted, not working.
+     */
+    private recordFolderState;
+    /**
+     * Surface scan/rebuild anomalies to admins via /admin/notifications and the
+     * server log (#807). Missing folders, capture-date gaps, and processing
+     * errors otherwise pass silently — admins only see them if they read the log.
+     *
+     * One summary notification per category (not per file) to avoid flooding the
+     * notification centre on a large library.
+     *
+     * @param result - The ScanResult returned by the provider.
+     * @param label  - "Scan" or "Rebuild", for notification wording.
+     */
+    private surfaceScanNotifications;
+    /**
+     * Trigger a media folder scan.
+     *
+     * STUB: Delegates to FileSystemMediaProvider.scan() which logs a warning and
+     * returns an empty ScanResult. Real implementation comes in Phase 4.
+     *
+     * @param force - Pass true to force a full rescan ignoring cached mtimes.
+     * @returns ScanResult summary.
+     */
+    scanFolders(force?: boolean, onProgress?: (processed: number, total: number) => void): Promise<ScanResult>;
+    /**
+     * Retrieve a single media item, held to a share visitor's ceiling.
+     *
+     * With a WikiContext whose subject arrived through a share, the item must
+     * be covered by that share (PolicyInformationPoint.canUserAccessMediaItem);
+     * a refusal returns null, treated as not found.
+     *
+     * @param id          - Item identifier.
+     * @param wikiContext - Caller's WikiContext (pass undefined for admin/internal calls).
+     * @returns The MediaItem or null.
+     */
+    getItem(id: string, wikiContext?: WikiContext): Promise<MediaItem | null>;
+    /**
+     * Update user-editable metadata (title, description, keywords,
+     * dateTimeOriginal) on a media item. Writes into the source file's
+     * EXIF/IPTC/XMP and refreshes the index entry.
+     *
+     * Caller is responsible for the asset-edit permission check; this method
+     * only enforces provider capability.
+     *
+     * @param id    - 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 evicted the item, e.g. an ngdpbaseignore keyword).
+     * @throws Error when the provider lacks the 'edit' capability, the patch is
+     *         invalid, or the underlying write fails.
+     */
+    updateItemMetadata(id: string, patch: import('../types/Asset.js').AssetMetadataPatch): Promise<MediaItem | null>;
+    /**
+     * Explain why one absolute path is, or is not, in the media index (#848).
+     *
+     * Admin-only diagnostic for "why isn't my file showing?" — #814 reported
+     * media as undiscovered when in fact every missing file was correctly
+     * skipped by a rule that leaves no visible trace.
+     *
+     * Returns null when the configured provider cannot answer, rather than
+     * inventing a verdict: a different provider has different rules, and a
+     * confident wrong answer here sends the operator to fix the wrong thing.
+     */
+    explainPath(target: string): Promise<import('../utils/explainMediaPath.js').MediaPathExplanation | null>;
+    /**
+     * The skip report from the most recent scan (#1056).
+     *
+     * Answers "where did my file go?" across the whole library, where
+     * {@link explainPath} answers it for one path the operator can already name.
+     * Both exist because an operator who cannot find a file often cannot state
+     * its path either.
+     *
+     * Null when the provider keeps no report — the same reasoning as
+     * `explainPath`: a different provider skips for different reasons, and an
+     * empty report would be read as "nothing was skipped".
+     */
+    getSkipReport(): Promise<import('../utils/explainMediaPath.js').MediaSkipReport | null>;
+    /**
+     * List all media items for a given year.
+     *
+     * @param year - Four-digit year.
+     * @returns Array of MediaItem objects.
+     */
+    listByYear(year: number): Promise<MediaItem[]>;
+    /**
+     * How many items the year listing covers (#1741) — the number
+     * `getYears()` + `listByYear()` add up to, without listing them.
+     */
+    count(): Promise<number>;
+    /**
+     * List media items whose capture timestamp falls within [after, before],
+     * ascending by capture date (#864 — Dawarich adapter). Items without a
+     * capture date are excluded by the provider.
+     *
+     * @param after  - Inclusive lower bound (ISO-ish string), optional.
+     * @param before - Inclusive upper bound (ISO-ish string), optional.
+     */
+    listByDateRange(after?: string, before?: string): Promise<MediaItem[]>;
+    /**
+     * List all media items whose EXIF/XMP keywords name a wiki page.
+     *
+     * @param pageName - Wiki page name to match against each item's keywords.
+     * @returns Array of MediaItem objects.
+     */
+    listByPage(pageName: string): Promise<MediaItem[]>;
+    /**
+     * List all media items whose EXIF/XMP keywords contain the given keyword.
+     *
+     * @param keyword - Exact keyword to match (e.g. "Molly's Cooking").
+     * @returns Array of MediaItem objects.
+     */
+    listByKeyword(keyword: string): Promise<MediaItem[]>;
+    /**
+     * #895: all distinct media keywords with item counts, for the admin keyword
+     * drift report. Aggregate counts only (no item data) — admin-only caller;
+     * counts include private items.
+     */
+    getAllKeywordCounts(): Promise<Record<string, number>>;
+    /**
+     * #917: library-wide leaf→path map from hierarchical media tags
+     * (HierarchicalSubject / TagsList). Empty when the provider doesn't index
+     * hierarchy. Consumed by #918 to preserve digiKam tag trees on write-back.
+     */
+    getKeywordLeafPaths(): Promise<Record<string, string>>;
+    /**
+     * Search media items.
+     *
+     * @param query - Search query string.
+     * @returns Array of MediaItem objects.
+     */
+    search(query: string): Promise<MediaItem[]>;
+    /**
+     * Find a media item by its original filename (basename).
+     *
+     * Used to resolve `media://filename.jpg` URIs in wiki page content.
+     * No privacy filtering is applied here — the caller (resolveAttachmentSrc)
+     * only uses the resulting URL; actual file delivery goes through the
+     * `/media/file/:id` route which enforces access control.
+     *
+     * @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 a thumbnail buffer for an item.
+     *
+     * @param id   - Item identifier.
+     * @param size - Requested size string (e.g. "300x300").
+     * @returns JPEG buffer or null.
+     */
+    getThumbnailBuffer(id: string, size: string): Promise<Buffer | null>;
+    /**
+     * Return a transcoded full-resolution buffer for a HEIC/RAW item (#514).
+     * Transcoded result is cached to the thumbnail directory.
+     *
+     * @param id     - Item identifier.
+     * @param format - Target format: 'jpeg' or 'webp'.
+     * @returns Transcoded buffer, or null if unavailable.
+     */
+    getTranscodedBuffer(id: string, format: 'jpeg' | 'webp'): Promise<Buffer | null>;
+    /**
+     * Return the list of years that have at least one media item, sorted
+     * descending (most recent first).
+     *
+     * @returns Sorted year list.
+     */
+    getYears(): Promise<number[]>;
+    /**
+     * Shut down the MediaManager, releasing provider resources. Its rescan
+     * job is stopped by BackgroundJobManager's shutdown handoff (#1721).
+     */
+    shutdown(): Promise<void>;
+}
+export default MediaManager;

package/lib/src/managers/MetricsManager.d.ts

@@ -0,0 +1,89 @@
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { RequestHandler } from 'express';
+/**
+ * MetricsManager - OpenTelemetry metrics with Prometheus export
+ *
+ * Provides application-level observability for page load times, index rebuild
+ * duration, save throughput, and HTTP request metrics. When disabled, all
+ * recording methods are no-ops.
+ *
+ * @class MetricsManager
+ * @extends BaseManager
+ */
+declare class MetricsManager extends BaseManager {
+    private enabled;
+    private meterProvider;
+    private prometheusExporter;
+    private otlpReader;
+    private meter;
+    private prefix;
+    private pageViewsTotal;
+    private pageSavesTotal;
+    private pageDeletesTotal;
+    private searchRebuildsTotal;
+    private pageIndexSavesTotal;
+    private loginAttemptsTotal;
+    private httpRequestsTotal;
+    private cacheLookupsTotal;
+    private importConversionsTotal;
+    private pageViewDuration;
+    private pageSaveDuration;
+    private pageDeleteDuration;
+    private searchRebuildDuration;
+    private pageIndexSaveDuration;
+    private engineInitDuration;
+    private httpRequestDuration;
+    private processResidentMemory;
+    private processHeapTotal;
+    private processHeapUsed;
+    private processExternalMemory;
+    private processArrayBuffers;
+    constructor(engine: WikiEngine);
+    initialize(_config?: Record<string, unknown>): Promise<void>;
+    private createInstruments;
+    isEnabled(): boolean;
+    recordPageView(durationMs: number): void;
+    recordPageSave(durationMs: number): void;
+    recordPageDelete(durationMs: number): void;
+    recordSearchRebuild(durationMs: number): void;
+    recordPageIndexSave(durationMs: number): void;
+    recordLoginAttempt(): void;
+    recordEngineInit(durationMs: number): void;
+    recordHttpRequest(durationMs: number, attributes: {
+        method: string;
+        route: string;
+        status: string;
+    }): void;
+    /**
+     * Record an identity-manager cache lookup (#620). Cardinality is bounded —
+     * 7 caches × 2 results = 14 series — so attributes are safe.
+     */
+    recordCacheLookup(attributes: {
+        manager: string;
+        cache: string;
+        result: 'hit' | 'miss';
+    }): void;
+    /**
+     * Record an NCM / import conversion outcome (#738). Increment once per
+     * ConversionWarning emitted by a converter run. Cardinality is bounded
+     * by the size of the `kind` namespace — today ~5 kinds × 2 outcomes =
+     * 10 series; grows with each new structured kind. No-op when telemetry
+     * is disabled, matches the rest of MetricsManager's API.
+     *
+     * Called from ImportManager and (when it ships) the #685 data-ingestion
+     * framework — anywhere a converter run produces ConversionResult.
+     */
+    recordImportConversion(attributes: {
+        kind: string;
+        outcome: 'warning' | 'error';
+    }): void;
+    /**
+     * Returns a handler that serves Prometheus metrics on the main Express app.
+     * The PrometheusExporter runs its own HTTP server on a separate port,
+     * but this handler allows serving metrics through the main app as well.
+     */
+    getMetricsHandler(): RequestHandler | null;
+    shutdown(): Promise<void>;
+}
+export default MetricsManager;

package/lib/src/managers/NotificationManager.d.ts

@@ -0,0 +1,165 @@
+import BaseManager from './BaseManager.js';
+import type { WikiEngine } from '../types/WikiEngine.js';
+import type { ActorContext } from '../context/ActorContext.js';
+/**
+ * Notification object structure
+ */
+export interface Notification {
+    id: string;
+    type: 'maintenance' | 'system' | 'user';
+    title: string;
+    message: string;
+    level: 'info' | 'warning' | 'error' | 'success';
+    targetUsers: string[];
+    createdAt: Date;
+    expiresAt: Date | null;
+    dismissedBy: string[];
+}
+/**
+ * Input for creating a notification
+ */
+export interface NotificationInput {
+    type?: 'maintenance' | 'system' | 'user';
+    title?: string;
+    message?: string;
+    level?: 'info' | 'warning' | 'error' | 'success';
+    targetUsers?: string[];
+    expiresAt?: Date | null;
+}
+/**
+ * Notification statistics
+ */
+export interface NotificationStats {
+    total: number;
+    active: number;
+    expired: number;
+    byType: Record<string, number>;
+    byLevel: Record<string, number>;
+}
+/**
+ * Maintenance configuration
+ */
+export interface MaintenanceConfig {
+    [key: string]: unknown;
+}
+/**
+ * NotificationManager - Handles system notifications and user alerts
+ *
+ * Manages user-facing notifications and system alerts with persistent storage.
+ * Extends BaseManager following the modular manager pattern.
+ *
+ * @class NotificationManager
+ * @extends BaseManager
+ *
+ * @property {Map<string, Notification>} notifications - Active notifications by ID
+ * @property {number} notificationId - Auto-incrementing notification ID
+ * @property {string|null} storagePath - Path to notifications storage file
+ *
+ * @see {@link BaseManager} for base functionality
+ *
+ * @example
+ * const notificationManager = engine.getManager('NotificationManager');
+ * notificationManager.addNotification({ title: 'Welcome!', level: 'info' });
+ */
+declare class NotificationManager extends BaseManager {
+    protected notifications: Map<string, Notification>;
+    protected notificationId: number;
+    private storagePath;
+    private saveInterval;
+    private logger;
+    /**
+     * Creates a new NotificationManager instance
+     *
+     * @constructor
+     * @param {any} engine - The wiki engine instance
+     */
+    constructor(engine: WikiEngine);
+    /**
+     * Initialize the notification manager
+     *
+     * @async
+     * @param {Record<string, unknown>} [config={}] - Configuration object
+     * @returns {Promise<void>}
+     */
+    initialize(config?: Record<string, unknown>): Promise<void>;
+    /**
+     * Load notifications from storage
+     */
+    private loadNotifications;
+    /**
+     * Save notifications to storage
+     */
+    private saveNotifications;
+    /**
+     * Create a new notification
+     * @param {NotificationInput} notification - Notification object
+     * @param {string} notification.type - Type of notification (maintenance, system, user)
+     * @param {string} notification.title - Notification title
+     * @param {string} notification.message - Notification message
+     * @param {string} notification.level - Severity level (info, warning, error, success)
+     * @param {Array} notification.targetUsers - Array of usernames to notify (empty for all)
+     * @param {Date} notification.expiresAt - When notification expires
+     * @returns {Promise<string>} Notification ID
+     */
+    createNotification(notification: NotificationInput): Promise<string>;
+    /**
+     * Add a notification (alias for createNotification for backward compatibility)
+     * @param {NotificationInput} notification - Notification object
+     * @returns {Promise<string>} Notification ID
+     */
+    addNotification(notification: NotificationInput): Promise<string>;
+    /**
+     * Get notifications for a specific user
+     * @param {string} username - Username to get notifications for
+     * @param {boolean} includeExpired - Include expired notifications
+     * @returns {Notification[]} Array of notifications
+     */
+    getUserNotifications(username: string, includeExpired?: boolean): Notification[];
+    /**
+     * Dismiss a notification for the caller.
+     *
+     * #1235: takes the caller's context, not a name, for a uniform door — the
+     * dismisser is `ctx.username`. Hides the banner from that one person and
+     * changes nothing else; recorded in the log line, not the audit trail.
+     * @param {string} notificationId - Notification ID
+     * @param ctx - Who is dismissing: the request's subject, forwarded
+     * @returns {Promise<boolean>} Success status
+     */
+    dismissNotification(notificationId: string, ctx: ActorContext): Promise<boolean>;
+    /**
+     * Create maintenance mode notification
+     * @param {boolean} enabled - Whether maintenance mode is enabled
+     * @param {string} adminUsername - Admin who toggled maintenance mode
+     * @param {MaintenanceConfig} config - Maintenance configuration
+     * @returns {Promise<string>} Notification ID
+     */
+    createMaintenanceNotification(enabled: boolean, adminUsername: string, _config?: MaintenanceConfig): Promise<string>;
+    /**
+     * Get all active notifications
+     * @param {boolean} includeExpired - Include expired notifications
+     * @returns {Notification[]} Array of all notifications
+     */
+    getAllNotifications(includeExpired?: boolean): Notification[];
+    /**
+     * Clean up expired notifications
+     */
+    cleanupExpiredNotifications(): Promise<void>;
+    /**
+     * Clear all active (non-expired) notifications
+     * @returns {Promise<number>} Number of cleared notifications
+     */
+    clearAllActive(): Promise<number>;
+    /**
+     * Get notification statistics
+     * @returns {NotificationStats} Statistics object
+     */
+    getStats(): NotificationStats;
+    private validateEscalationConfig;
+    private escalateByEmail;
+    private _doEscalateByEmail;
+    /**
+     * Shutdown the notification manager
+     */
+    shutdown(): Promise<void>;
+}
+export default NotificationManager;