@keepkit/core 0.28.4 → 0.28.6

package/dist/core.d.ts

@@ -1,13 +1,115 @@
-import { K as KeepListQuery } from './store-45yaDeER.js';
-export { D as DEFAULT_KEEP_URL_PARAMS, I as ImportItemsOptions, a as ImportItemsResult, b as KEEP_BACKUP_FORMAT, c as KEEP_BACKUP_VERSION, d as KeepAutoRevalidationOptions, e as KeepBackup, f as KeepBackupImportError, g as KeepBackupParseError, h as KeepCollectionMeta, i as KeepItemMetadataRefresher, j as KeepItemResolver, k as KeepItemRevalidationRecord, l as KeepItemRevalidationResult, m as KeepItemRevalidationSummary, n as KeepItemRevalidator, o as KeepNavigationState, p as KeepRediscoveryOptions, q as KeepRediscoveryStrategy, r as KeepStore, s as KeepStoreActions, t as KeepStoreState, u as KeepUrlParamNames, v as KeepUrlState, w as KeepUrlSyncOptions, Q as QueryKeepItemsResult, R as RevalidateKeepItemsOptions, x as createInboxQuery, y as createRediscoveryQuery, z as decodeKeepListQuery, A as encodeKeepListQuery, B as exportItems, C as getKeepNavigationState, E as getTagCounts, F as importItems, G as isKeepItemMetadataStale, H as mergeKeepListQueryFromUrl, J as moveKeepItem, L as orderKeepItems, M as queryKeepItems, N as reconcileKeepItems, O as reorderKeepItems, P as revalidateKeepItems, S as serializeKeepListQuery } from './store-45yaDeER.js';
-import { K as KeepScope } from './scope-Dtkxpnof.js';
-export { S as ScopedStorageAdapter, a as ScopedSyncQueueAdapter, c as createScopedStorageAdapter, g as getKeepScopeKey, i as isSameKeepScope } from './scope-Dtkxpnof.js';
-import { R as RemoteSyncDriver, a as StorageAdapter, b as KeepItem, e as KeepPluginContext, f as KeepPlugin, d as SyncOperation, S as SyncScope, g as SyncCapableStorageAdapter, h as RemoteSyncResult, i as KeepSyncAuthError } from './types-C_U5Q44o.js';
-export { j as KeepAction, k as KeepChangeContext, l as KeepChangePhase, K as KeepCollectionDefinition, m as KeepConflictContext, n as KeepConflictResolver, o as KeepErrorContext, p as KeepErrorHandler, q as KeepEventHandlers, r as KeepInvalidItemPolicy, s as KeepItemInput, t as KeepItemStatus, u as KeepSchema, v as KeepSchemaParseResult, w as KeepStorageAccessError, x as KeepStorageError, y as KeepStorageOperation, z as KeepStorageParseError, A as KeepStorageQuotaError, B as KeepSyncAuthStatus, C as KeepSyncConflict, D as KeepSyncResolution, E as KeepSyncState, F as KeepSyncStatus, G as KeepUndoState, c as SyncQueueAdapter, H as isKeepSyncAuthError, I as normalizeKeepTags } from './types-C_U5Q44o.js';
+import { a as StorageAdapter, b as KeepCollectionMembership, c as KeepItem, R as RemoteSyncDriver, k as KeepPluginContext, l as KeepPlugin, m as SyncOperation, n as KeepCollectionSyncOperation, o as KeepMembershipSyncOperation, S as SyncScope, p as SyncCapableStorageAdapter, q as RemoteSyncResult, K as KeepCollectionDefinition, r as KeepSyncAuthError } from './types-GTCMFt5T.js';
+export { s as KeepAction, i as KeepChangeContext, t as KeepChangePhase, u as KeepCollectionSyncConflict, v as KeepCollectionSyncResult, w as KeepConflictContext, x as KeepConflictResolver, y as KeepErrorContext, z as KeepErrorHandler, A as KeepEventHandlers, h as KeepInvalidItemPolicy, B as KeepItemInput, f as KeepItemStatus, g as KeepSchema, C as KeepSchemaParseResult, D as KeepStorageAccessError, E as KeepStorageError, F as KeepStorageOperation, G as KeepStorageParseError, H as KeepStorageQuotaError, I as KeepSyncAuthStatus, J as KeepSyncConflict, e as KeepSyncQueueOperation, L as KeepSyncResolution, M as KeepSyncState, N as KeepSyncStatus, j as KeepUndoState, d as SyncQueueAdapter, O as isKeepSyncAuthError, P as normalizeKeepTags } from './types-GTCMFt5T.js';
+import { K as KeepListQuery } from './store-98vWM3tV.js';
+export { D as DEFAULT_KEEP_URL_PARAMS, I as ImportItemsOptions, a as ImportItemsResult, b as KEEP_BACKUP_FORMAT, c as KEEP_BACKUP_VERSION, d as KeepAutoRevalidationOptions, e as KeepBackup, f as KeepBackupAppliedCounts, g as KeepBackupDataType, h as KeepBackupImportError, i as KeepBackupParseError, j as KeepBackupV1, k as KeepBackupV2, l as KeepCollectionMeta, m as KeepItemMetadataRefresher, n as KeepItemResolver, o as KeepItemRevalidationRecord, p as KeepItemRevalidationResult, q as KeepItemRevalidationSummary, r as KeepItemRevalidator, s as KeepNavigationState, t as KeepRediscoveryOptions, u as KeepRediscoveryStrategy, v as KeepStore, w as KeepStoreActions, x as KeepStoreState, y as KeepUrlParamNames, z as KeepUrlState, A as KeepUrlSyncOptions, Q as QueryKeepItemsResult, R as RevalidateKeepItemsOptions, B as createInboxQuery, C as createRediscoveryQuery, E as decodeKeepListQuery, F as encodeKeepListQuery, G as exportItems, H as getKeepNavigationState, J as getTagCounts, L as importItems, M as isKeepItemMetadataStale, N as mergeKeepListQueryFromUrl, O as moveKeepItem, P as orderKeepItems, S as queryKeepItems, T as reconcileKeepItems, U as reorderKeepItems, V as revalidateKeepItems, W as serializeKeepListQuery } from './store-98vWM3tV.js';
+import { K as KeepScope } from './scope-1bxGd68Y.js';
+export { S as ScopedStorageAdapter, a as ScopedSyncQueueAdapter, c as createScopedStorageAdapter, g as getKeepScopeKey, i as isSameKeepScope } from './scope-1bxGd68Y.js';
 export { KeepSchemaValidationError, parseKeepMeta, validateKeepItem } from './schema.js';
 import { SyncStorageAdapterOptions, BrowserStorageAdapterOptions } from './storage.js';
 export { DEFAULT_INDEXEDDB_DATABASE, DEFAULT_INDEXEDDB_STORE, DEFAULT_STORAGE_KEY, DEFAULT_SYNC_QUEUE_DATABASE, DEFAULT_SYNC_QUEUE_KEY, DEFAULT_SYNC_QUEUE_STORE, FallbackStorageAdapter, FallbackStorageAdapterOptions, FallbackSyncQueueAdapter, FallbackSyncQueueAdapterOptions, IndexedDBAdapter, IndexedDBAdapterOptions, IndexedDBSyncQueueAdapter, IndexedDBSyncQueueOptions, LocalStorageAdapter, LocalStorageAdapterOptions, LocalStorageSyncQueueAdapter, LocalStorageSyncQueueOptions, StorageAdapterFactoryOptions, SyncStorageAdapter, createBrowserStorageAdapter, createStorageAdapter } from './storage.js';
 
+type KeepHistoryEntry = {
+    itemId: string;
+    lastViewedAt: number;
+    context?: KeepHistoryContext;
+};
+/** Application-owned revisit details such as language or deck. */
+type KeepHistoryContext = Record<string, string>;
+type KeepViewingRecord = {
+    id: string;
+    itemId: string;
+    viewedAt: number;
+    /** Omitted on legacy records written before timestamp tracking was added. */
+    createdAt?: number;
+    /** Omitted on legacy records written before timestamp tracking was added. */
+    updatedAt?: number;
+    note?: string;
+};
+interface KeepHistoryStorage {
+    getAll(): Promise<KeepHistoryEntry[]>;
+    getLimit(): Promise<number>;
+    setLimit(limit: number): Promise<void>;
+    record(itemId: string, viewedAt?: number, context?: KeepHistoryContext): Promise<KeepHistoryEntry[]>;
+    remove(itemId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+interface KeepViewingRecordStorage {
+    getAll(itemId?: string): Promise<KeepViewingRecord[]>;
+    set(record: KeepViewingRecord): Promise<void>;
+    add(itemId: string, options?: {
+        viewedAt?: number;
+        note?: string;
+    }): Promise<KeepViewingRecord>;
+    remove(id: string): Promise<void>;
+    removeForItem(itemId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+type LocalStorageActivityOptions = {
+    key?: string;
+    storage?: Storage;
+    maxEntries?: number;
+    now?: () => number;
+    createId?: () => string;
+};
+declare const DEFAULT_KEEP_HISTORY_KEY = "keepkit:view-history";
+declare const DEFAULT_KEEP_VIEWING_RECORDS_KEY = "keepkit:viewing-records";
+declare const DEFAULT_KEEP_HISTORY_LIMIT = 100;
+/** Local history of opened guides. It never reads or mutates saved items. */
+declare class LocalStorageKeepHistoryStorage implements KeepHistoryStorage {
+    private readonly key;
+    private readonly limitKey;
+    private readonly storage;
+    private readonly initialLimit;
+    private readonly now;
+    private writes;
+    constructor(options?: LocalStorageActivityOptions);
+    getAll(): Promise<KeepHistoryEntry[]>;
+    getLimit(): Promise<number>;
+    setLimit(limit: number): Promise<void>;
+    record(itemId: string, viewedAt?: number, context?: KeepHistoryContext): Promise<KeepHistoryEntry[]>;
+    remove(itemId: string): Promise<void>;
+    clear(): Promise<void>;
+    private writeEntries;
+    private withWriteLock;
+    private read;
+    private readRaw;
+    private writeRaw;
+}
+/** Explicit user-reported viewing events, kept separate from open history and saved items. */
+declare class LocalStorageKeepViewingRecordStorage implements KeepViewingRecordStorage {
+    private readonly key;
+    private readonly storage;
+    private readonly now;
+    private readonly createId;
+    private writes;
+    constructor(options?: LocalStorageActivityOptions);
+    getAll(itemId?: string): Promise<KeepViewingRecord[]>;
+    set(record: KeepViewingRecord): Promise<void>;
+    add(itemId: string, options?: {
+        viewedAt?: number;
+        note?: string;
+    }): Promise<KeepViewingRecord>;
+    private saveRecord;
+    remove(id: string): Promise<void>;
+    removeForItem(itemId: string): Promise<void>;
+    clear(): Promise<void>;
+    private readRecords;
+    private readRaw;
+    private writeRecords;
+    private withWriteLock;
+}
+declare class KeepActivityStorageError extends Error {
+    readonly storageKey: string;
+    readonly cause?: unknown;
+    constructor(message: string, storageKey: string, cause?: unknown);
+}
+
+declare function getKeepCollectionItems<TMeta>(storage: StorageAdapter<TMeta>, collectionId: string): Promise<KeepItem<TMeta>[]>;
+declare function addKeepItemToCollection<TMeta>(storage: StorageAdapter<TMeta>, collectionId: string, itemId: string, order?: number): Promise<KeepCollectionMembership>;
+declare function removeKeepItemFromCollection<TMeta>(storage: StorageAdapter<TMeta>, collectionId: string, itemId: string): Promise<void>;
+/** Reorders only the requested collection and leaves other course membership orders untouched. */
+declare function reorderKeepCollectionItems<TMeta>(storage: StorageAdapter<TMeta>, collectionId: string, itemIds: string[]): Promise<KeepCollectionMembership[]>;
+
 type KeepKitPresetMode = "local" | "sync" | "backup";
 type KeepKitPresetOptions<TMeta = Record<string, unknown>> = {
     mode?: KeepKitPresetMode;
@@ -29,6 +131,74 @@ type KeepKitSetup<TMeta = Record<string, unknown>> = {
 declare function createKeepKitPreset<TMeta = Record<string, unknown>>(options?: KeepKitPresetOptions<TMeta>): KeepKitSetup<TMeta>;
 declare const createKeepKitSetup: typeof createKeepKitPreset;
 
+type KeepCourseProgress = {
+    kind: "course";
+    courseId: string;
+    currentItemId?: string;
+    updatedAt: number;
+};
+type KeepItemProgress = {
+    kind: "item";
+    itemId: string;
+    audioPositionMs?: number;
+    /** App-defined heading ID or legacy numeric offset. */
+    readingPosition?: number | string;
+    audioId?: string;
+    language?: string;
+    contentVersion?: string;
+    updatedAt: number;
+};
+type KeepProgressRecord = KeepCourseProgress | KeepItemProgress;
+type KeepProgressCompatibility = {
+    language?: string;
+    contentVersion?: string;
+    audioId?: string;
+};
+interface KeepProgressStorage {
+    getAll(): Promise<KeepProgressRecord[]>;
+    getCourse(courseId: string): Promise<KeepCourseProgress | undefined>;
+    getItem(itemId: string, compatibility?: KeepProgressCompatibility): Promise<KeepItemProgress | undefined>;
+    saveCourse(courseId: string, currentItemId?: string): Promise<KeepCourseProgress>;
+    saveItem(itemId: string, progress: Omit<KeepItemProgress, "kind" | "itemId" | "updatedAt">): Promise<KeepItemProgress>;
+    set(record: KeepProgressRecord): Promise<void>;
+    resetCourse(courseId: string): Promise<void>;
+    resetItem(itemId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+type LocalStorageProgressOptions = {
+    key?: string;
+    storage?: Storage;
+    now?: () => number;
+};
+declare const DEFAULT_KEEP_PROGRESS_KEY = "keepkit:progress";
+/** Stores course and reader progress independently of saved items and open history. */
+declare class LocalStorageKeepProgressStorage implements KeepProgressStorage {
+    private readonly key;
+    private readonly storage;
+    private readonly now;
+    private writes;
+    constructor(options?: LocalStorageProgressOptions);
+    getAll(): Promise<KeepProgressRecord[]>;
+    getCourse(courseId: string): Promise<KeepCourseProgress | undefined>;
+    getItem(itemId: string, compatibility?: KeepProgressCompatibility): Promise<KeepItemProgress | undefined>;
+    saveCourse(courseId: string, currentItemId?: string): Promise<KeepCourseProgress>;
+    saveItem(itemId: string, progress: Omit<KeepItemProgress, "kind" | "itemId" | "updatedAt">): Promise<KeepItemProgress>;
+    set(record: KeepProgressRecord): Promise<void>;
+    resetCourse(courseId: string): Promise<void>;
+    resetItem(itemId: string): Promise<void>;
+    clear(): Promise<void>;
+    private readRaw;
+    private writeRecords;
+    private withWriteLock;
+}
+/** Reject stale reader offsets when the selected language or content revision changed. */
+declare function isProgressCompatible(record: KeepItemProgress, compatibility?: KeepProgressCompatibility): boolean;
+declare class KeepProgressStorageError extends Error {
+    readonly storageKey: string;
+    readonly cause?: unknown;
+    constructor(message: string, storageKey: string, cause?: unknown);
+}
+
 type KeepSavedView<TMeta = Record<string, unknown>> = {
     id: string;
     name: string;
@@ -63,6 +233,13 @@ declare class LocalStorageKeepSavedViewStorage<TMeta = Record<string, unknown>>
 declare function mergeKeepItems<TMeta>(localItems: KeepItem<TMeta>[], target: StorageAdapter<TMeta>): Promise<KeepItem<TMeta>[]>;
 /** Read anonymous items, merge them into the target, then clear the source. */
 declare function migrateKeepItems<TMeta>(source: StorageAdapter<TMeta>, target: StorageAdapter<TMeta>): Promise<KeepItem<TMeta>[]>;
+type LegacyCollectionMigrationResult = {
+    migrated: number;
+    skipped: number;
+    missingCollectionIds: string[];
+};
+/** Move legacy single-collection item fields into course-specific memberships once. */
+declare function migrateLegacyCollectionMemberships<TMeta>(storage: StorageAdapter<TMeta>): Promise<LegacyCollectionMigrationResult>;
 
 type KeepInvalidationPluginOptions<TMeta = Record<string, unknown>> = {
     /** Query keys to invalidate after a successful local KeepKit mutation. */
@@ -78,14 +255,22 @@ type AuthenticatedSyncRequestContext<TMeta = Record<string, unknown>> = {
     token: string | null;
     scope?: SyncScope;
     operation?: SyncOperation<TMeta>;
+    collectionOperation?: KeepCollectionSyncOperation;
+    membershipOperation?: KeepMembershipSyncOperation;
 };
 /** Transport boundary for auth-aware requests; cookies and bearer tokens remain host concerns. */
 type AuthenticatedSyncTransport<TMeta = Record<string, unknown>> = {
     push: (operation: SyncOperation<TMeta>, context: AuthenticatedSyncRequestContext<TMeta>) => Promise<RemoteSyncResult<TMeta>>;
     pull?: (context: AuthenticatedSyncRequestContext<TMeta>) => Promise<KeepItem<TMeta>[]>;
+    pushCollection?: (operation: KeepCollectionSyncOperation, context: AuthenticatedSyncRequestContext<TMeta>) => Promise<void>;
+    pullCollections?: (context: AuthenticatedSyncRequestContext<TMeta>) => Promise<KeepCollectionDefinition[]>;
+    pushMembership?: (operation: KeepMembershipSyncOperation, context: AuthenticatedSyncRequestContext<TMeta>) => Promise<void>;
+    pullMemberships?: (context: AuthenticatedSyncRequestContext<TMeta>) => Promise<KeepCollectionMembership[]>;
 };
 type AuthenticatedSyncAuthContext<TMeta = Record<string, unknown>> = {
     operation?: SyncOperation<TMeta>;
+    collectionOperation?: KeepCollectionSyncOperation;
+    membershipOperation?: KeepMembershipSyncOperation;
     scope?: SyncScope;
 };
 type AuthenticatedSyncKitOptions<TMeta = Record<string, unknown>> = Omit<SyncStorageAdapterOptions<TMeta>, "local" | "remote" | "scope"> & {
@@ -116,4 +301,4 @@ type AuthenticatedSyncKit<TMeta = Record<string, unknown>> = {
 /** Creates auth-independent sync wiring with per-request tokens and isolated account scopes. */
 declare function createAuthenticatedSyncKit<TMeta = Record<string, unknown>>(options: AuthenticatedSyncKitOptions<TMeta>): AuthenticatedSyncKit<TMeta>;
 
-export { type AuthenticatedSyncAuthContext, type AuthenticatedSyncKit, type AuthenticatedSyncKitOptions, type AuthenticatedSyncRequestContext, type AuthenticatedSyncTransport, BrowserStorageAdapterOptions, DEFAULT_SAVED_VIEWS_STORAGE_KEY, type KeepInvalidationPluginOptions, KeepItem, type KeepKitPresetMode, type KeepKitPresetOptions, type KeepKitSetup, KeepListQuery, KeepPlugin, KeepPluginContext, type KeepSavedView, type KeepSavedViewStorage, KeepScope, KeepSyncAuthError, LocalStorageKeepSavedViewStorage, RemoteSyncDriver, RemoteSyncResult, StorageAdapter, SyncCapableStorageAdapter, SyncOperation, SyncScope, SyncStorageAdapterOptions, createAuthenticatedSyncKit, createKeepInvalidationPlugin, createKeepKitPreset, createKeepKitSetup, mergeKeepItems, migrateKeepItems };
+export { type AuthenticatedSyncAuthContext, type AuthenticatedSyncKit, type AuthenticatedSyncKitOptions, type AuthenticatedSyncRequestContext, type AuthenticatedSyncTransport, BrowserStorageAdapterOptions, DEFAULT_KEEP_HISTORY_KEY, DEFAULT_KEEP_HISTORY_LIMIT, DEFAULT_KEEP_PROGRESS_KEY, DEFAULT_KEEP_VIEWING_RECORDS_KEY, DEFAULT_SAVED_VIEWS_STORAGE_KEY, KeepActivityStorageError, KeepCollectionDefinition, KeepCollectionMembership, KeepCollectionSyncOperation, type KeepCourseProgress, type KeepHistoryContext, type KeepHistoryEntry, type KeepHistoryStorage, type KeepInvalidationPluginOptions, KeepItem, type KeepItemProgress, type KeepKitPresetMode, type KeepKitPresetOptions, type KeepKitSetup, KeepListQuery, KeepMembershipSyncOperation, KeepPlugin, KeepPluginContext, type KeepProgressCompatibility, type KeepProgressRecord, type KeepProgressStorage, KeepProgressStorageError, type KeepSavedView, type KeepSavedViewStorage, KeepScope, KeepSyncAuthError, type KeepViewingRecord, type KeepViewingRecordStorage, type LegacyCollectionMigrationResult, type LocalStorageActivityOptions, LocalStorageKeepHistoryStorage, LocalStorageKeepProgressStorage, LocalStorageKeepSavedViewStorage, LocalStorageKeepViewingRecordStorage, type LocalStorageProgressOptions, RemoteSyncDriver, RemoteSyncResult, StorageAdapter, SyncCapableStorageAdapter, SyncOperation, SyncScope, SyncStorageAdapterOptions, addKeepItemToCollection, createAuthenticatedSyncKit, createKeepInvalidationPlugin, createKeepKitPreset, createKeepKitSetup, getKeepCollectionItems, isProgressCompatible, mergeKeepItems, migrateKeepItems, migrateLegacyCollectionMemberships, removeKeepItemFromCollection, reorderKeepCollectionItems };