@keepkit/core 0.28.5 → 0.28.6

package/dist/core.js

@@ -13,13 +13,14 @@ import {
   isKeepItemMetadataStale,
   mergeKeepItems,
   migrateKeepItems,
+  migrateLegacyCollectionMemberships,
   moveKeepItem,
   orderKeepItems,
   queryKeepItems,
   reconcileKeepItems,
   reorderKeepItems,
   revalidateKeepItems
-} from "./chunk-AUNFZU3A.js";
+} from "./chunk-5XSSH3TO.js";
 import {
   KeepSchemaValidationError,
   parseKeepMeta,
@@ -53,7 +54,7 @@ import {
   isKeepSyncAuthError,
   isSameKeepScope,
   normalizeKeepTags
-} from "./chunk-NZLAW4LY.js";
+} from "./chunk-QRPQYE7K.js";
 
 // src/features/items/activity.ts
 var DEFAULT_KEEP_HISTORY_KEY = "keepkit:view-history";
@@ -61,6 +62,7 @@ var DEFAULT_KEEP_VIEWING_RECORDS_KEY = "keepkit:viewing-records";
 var DEFAULT_KEEP_HISTORY_LIMIT = 100;
 var LocalStorageKeepHistoryStorage = class {
   constructor(options = {}) {
+    this.writes = Promise.resolve();
     this.key = options.key ?? DEFAULT_KEEP_HISTORY_KEY;
     this.limitKey = `${this.key}:limit`;
     this.storage = options.storage ?? getBrowserStorage();
@@ -84,32 +86,49 @@ var LocalStorageKeepHistoryStorage = class {
   }
   async setLimit(limit) {
     const normalized = normalizeLimit(limit);
-    this.writeRaw(this.limitKey, JSON.stringify(normalized), "history-limit");
-    const entries = await this.getAll();
-    await this.writeEntries(entries.slice(0, normalized));
+    await this.withWriteLock(async () => {
+      this.writeRaw(this.limitKey, JSON.stringify(normalized), "history-limit");
+      const entries = await this.getAll();
+      await this.writeEntries(entries.slice(0, normalized));
+    });
   }
-  async record(itemId, viewedAt = this.now()) {
+  async record(itemId, viewedAt = this.now(), context) {
     const normalizedId = normalizeId(itemId);
     assertTimestamp(viewedAt);
-    const entries = await this.getAll();
-    const previous = entries.find((entry) => entry.itemId === normalizedId);
-    const next = [
-      { itemId: normalizedId, lastViewedAt: Math.max(previous?.lastViewedAt ?? 0, viewedAt) },
-      ...entries.filter((entry) => entry.itemId !== normalizedId)
-    ].sort((left, right) => right.lastViewedAt - left.lastViewedAt).slice(0, await this.getLimit());
-    await this.writeEntries(next);
-    return cloneHistoryEntries(next);
+    return this.withWriteLock(async () => {
+      const entries = await this.getAll();
+      const previous = entries.find((entry) => entry.itemId === normalizedId);
+      const isNewer = viewedAt >= (previous?.lastViewedAt ?? -1);
+      const nextContext = isNewer ? normalizeHistoryContext(context) : previous?.context;
+      const next = [
+        {
+          itemId: normalizedId,
+          lastViewedAt: Math.max(previous?.lastViewedAt ?? 0, viewedAt),
+          ...nextContext ? { context: nextContext } : {}
+        },
+        ...entries.filter((entry) => entry.itemId !== normalizedId)
+      ].sort((left, right) => right.lastViewedAt - left.lastViewedAt).slice(0, await this.getLimit());
+      await this.writeEntries(next);
+      return cloneHistoryEntries(next);
+    });
   }
   async remove(itemId) {
     const normalizedId = normalizeId(itemId);
-    await this.writeEntries((await this.getAll()).filter((entry) => entry.itemId !== normalizedId));
+    await this.withWriteLock(
+      async () => this.writeEntries((await this.getAll()).filter((entry) => entry.itemId !== normalizedId))
+    );
   }
   async clear() {
-    this.writeRaw(this.key, "[]", "history");
+    await this.withWriteLock(async () => this.writeRaw(this.key, "[]", "history"));
   }
   async writeEntries(entries) {
     this.writeRaw(this.key, JSON.stringify(entries), "history");
   }
+  withWriteLock(operation) {
+    const next = this.writes.then(operation);
+    this.writes = next.catch(() => void 0);
+    return next;
+  }
   async read(key, validate, label) {
     const raw = this.readRaw(key, label);
     if (raw === null) return [];
@@ -125,8 +144,10 @@ var LocalStorageKeepHistoryStorage = class {
     }
   }
   writeRaw(key, value, label) {
+    if (!this.storage)
+      throw new KeepActivityStorageError(`KeepKit cannot persist ${label} data without browser storage.`, key);
     try {
-      this.storage?.setItem(key, value);
+      this.storage.setItem(key, value);
     } catch (cause) {
       throw new KeepActivityStorageError(`KeepKit could not write ${label} data.`, key, cause);
     }
@@ -134,6 +155,7 @@ var LocalStorageKeepHistoryStorage = class {
 };
 var LocalStorageKeepViewingRecordStorage = class {
   constructor(options = {}) {
+    this.writes = Promise.resolve();
     this.key = options.key ?? DEFAULT_KEEP_VIEWING_RECORDS_KEY;
     this.storage = options.storage ?? getBrowserStorage();
     this.now = options.now ?? Date.now;
@@ -145,29 +167,48 @@ var LocalStorageKeepViewingRecordStorage = class {
     return filtered.sort((left, right) => right.viewedAt - left.viewedAt).map((record) => ({ ...record }));
   }
   async set(record) {
-    const normalized = normalizeViewingRecord(record);
-    const records = await this.readRecords();
-    this.writeRecords([...records.filter((entry) => entry.id !== normalized.id), normalized]);
+    await this.saveRecord(record);
   }
   async add(itemId, options = {}) {
+    const timestamp = this.now();
     const record = {
       id: this.createId(),
       itemId: normalizeId(itemId),
-      viewedAt: options.viewedAt ?? this.now(),
+      viewedAt: options.viewedAt ?? timestamp,
+      createdAt: timestamp,
+      updatedAt: timestamp,
       ...options.note?.trim() ? { note: options.note.trim() } : {}
     };
-    await this.set(record);
-    return { ...record };
+    return this.saveRecord(record);
+  }
+  async saveRecord(record) {
+    const normalized = normalizeViewingRecord(record);
+    return this.withWriteLock(async () => {
+      const records = await this.readRecords();
+      const previous = records.find((entry) => entry.id === normalized.id);
+      const now = this.now();
+      const next = {
+        ...normalized,
+        createdAt: previous?.createdAt ?? normalized.createdAt ?? now,
+        updatedAt: now
+      };
+      this.writeRecords([...records.filter((entry) => entry.id !== normalized.id), next]);
+      return { ...next };
+    });
   }
   async remove(id) {
-    this.writeRecords((await this.readRecords()).filter((record) => record.id !== id));
+    await this.withWriteLock(
+      async () => this.writeRecords((await this.readRecords()).filter((record) => record.id !== id))
+    );
   }
   async removeForItem(itemId) {
     const normalizedId = normalizeId(itemId);
-    this.writeRecords((await this.readRecords()).filter((record) => record.itemId !== normalizedId));
+    await this.withWriteLock(
+      async () => this.writeRecords((await this.readRecords()).filter((record) => record.itemId !== normalizedId))
+    );
   }
   async clear() {
-    this.writeRecords([]);
+    await this.withWriteLock(async () => this.writeRecords([]));
   }
   async readRecords() {
     const raw = this.readRaw();
@@ -186,12 +227,20 @@ var LocalStorageKeepViewingRecordStorage = class {
     }
   }
   writeRecords(records) {
+    if (!this.storage) {
+      throw new KeepActivityStorageError("KeepKit cannot persist viewing records without browser storage.", this.key);
+    }
     try {
-      this.storage?.setItem(this.key, JSON.stringify(records));
+      this.storage.setItem(this.key, JSON.stringify(records));
     } catch (cause) {
       throw new KeepActivityStorageError("KeepKit could not write viewing records.", this.key, cause);
     }
   }
+  withWriteLock(operation) {
+    const next = this.writes.then(operation);
+    this.writes = next.catch(() => void 0);
+    return next;
+  }
 };
 var KeepActivityStorageError = class extends Error {
   constructor(message, storageKey, cause) {
@@ -203,20 +252,22 @@ var KeepActivityStorageError = class extends Error {
 };
 function isHistoryEntryArray(value) {
   return Array.isArray(value) && value.every(
-    (entry) => isRecord(entry) && typeof entry.itemId === "string" && entry.itemId.length > 0 && typeof entry.lastViewedAt === "number" && Number.isFinite(entry.lastViewedAt)
+    (entry) => isRecord(entry) && typeof entry.itemId === "string" && entry.itemId.length > 0 && typeof entry.lastViewedAt === "number" && Number.isFinite(entry.lastViewedAt) && (entry.context === void 0 || isHistoryContext(entry.context))
   );
 }
 function isViewingRecordArray(value) {
   return Array.isArray(value) && value.every(isViewingRecord);
 }
 function isViewingRecord(value) {
-  return isRecord(value) && typeof value.id === "string" && value.id.length > 0 && typeof value.itemId === "string" && value.itemId.length > 0 && typeof value.viewedAt === "number" && Number.isFinite(value.viewedAt) && value.viewedAt >= 0 && (value.note === void 0 || typeof value.note === "string");
+  return isRecord(value) && typeof value.id === "string" && value.id.length > 0 && typeof value.itemId === "string" && value.itemId.length > 0 && typeof value.viewedAt === "number" && Number.isFinite(value.viewedAt) && value.viewedAt >= 0 && (value.createdAt === void 0 || typeof value.createdAt === "number" && Number.isFinite(value.createdAt)) && (value.updatedAt === void 0 || typeof value.updatedAt === "number" && Number.isFinite(value.updatedAt)) && (value.note === void 0 || typeof value.note === "string");
 }
 function normalizeViewingRecord(record) {
   const normalized = {
     id: normalizeId(record.id),
     itemId: normalizeId(record.itemId),
     viewedAt: record.viewedAt,
+    ...record.createdAt !== void 0 ? { createdAt: record.createdAt } : {},
+    ...record.updatedAt !== void 0 ? { updatedAt: record.updatedAt } : {},
     ...record.note?.trim() ? { note: record.note.trim() } : {}
   };
   assertTimestamp(normalized.viewedAt);
@@ -235,7 +286,15 @@ function assertTimestamp(value) {
   if (!Number.isFinite(value) || value < 0) throw new TypeError("KeepKit timestamps must be non-negative numbers.");
 }
 function cloneHistoryEntries(entries) {
-  return entries.map((entry) => ({ ...entry }));
+  return entries.map((entry) => ({ ...entry, ...entry.context ? { context: { ...entry.context } } : {} }));
+}
+function normalizeHistoryContext(context) {
+  if (!context) return void 0;
+  const entries = Object.entries(context).filter(([key, value]) => key.trim() && typeof value === "string");
+  return entries.length > 0 ? Object.fromEntries(entries) : void 0;
+}
+function isHistoryContext(value) {
+  return isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
 }
 function parseJson(raw, key, label) {
   try {
@@ -352,6 +411,7 @@ var createKeepKitSetup = createKeepKitPreset;
 var DEFAULT_KEEP_PROGRESS_KEY = "keepkit:progress";
 var LocalStorageKeepProgressStorage = class {
   constructor(options = {}) {
+    this.writes = Promise.resolve();
     this.key = options.key ?? DEFAULT_KEEP_PROGRESS_KEY;
     this.storage = options.storage ?? getBrowserStorage2();
     this.now = options.now ?? Date.now;
@@ -397,27 +457,34 @@ var LocalStorageKeepProgressStorage = class {
       kind: "item",
       itemId: normalizeId2(itemId, "item"),
       ...progress,
+      ...progress.audioId?.trim() ? { audioId: progress.audioId.trim() } : {},
       updatedAt: this.now()
     };
     await this.set(record);
     return record;
   }
   async set(record) {
-    const normalized = normalizeProgressRecord(record);
-    const records = await this.getAll();
-    const identity = getProgressIdentity(normalized);
-    this.writeRecords([...records.filter((entry) => getProgressIdentity(entry) !== identity), normalized]);
+    await this.withWriteLock(async () => {
+      const normalized = normalizeProgressRecord(record);
+      const records = await this.getAll();
+      const identity = getProgressIdentity(normalized);
+      this.writeRecords([...records.filter((entry) => getProgressIdentity(entry) !== identity), normalized]);
+    });
   }
   async resetCourse(courseId) {
     const id = normalizeId2(courseId, "course");
-    this.writeRecords((await this.getAll()).filter((entry) => entry.kind !== "course" || entry.courseId !== id));
+    await this.withWriteLock(
+      async () => this.writeRecords((await this.getAll()).filter((entry) => entry.kind !== "course" || entry.courseId !== id))
+    );
   }
   async resetItem(itemId) {
     const id = normalizeId2(itemId, "item");
-    this.writeRecords((await this.getAll()).filter((entry) => entry.kind !== "item" || entry.itemId !== id));
+    await this.withWriteLock(
+      async () => this.writeRecords((await this.getAll()).filter((entry) => entry.kind !== "item" || entry.itemId !== id))
+    );
   }
   async clear() {
-    this.writeRecords([]);
+    await this.withWriteLock(async () => this.writeRecords([]));
   }
   readRaw() {
     try {
@@ -427,12 +494,20 @@ var LocalStorageKeepProgressStorage = class {
     }
   }
   writeRecords(records) {
+    if (!this.storage) {
+      throw new KeepProgressStorageError("KeepKit cannot persist progress without browser storage.", this.key);
+    }
     try {
-      this.storage?.setItem(this.key, JSON.stringify(records));
+      this.storage.setItem(this.key, JSON.stringify(records));
     } catch (cause) {
       throw new KeepProgressStorageError("KeepKit could not write progress data.", this.key, cause);
     }
   }
+  withWriteLock(operation) {
+    const next = this.writes.then(operation);
+    this.writes = next.catch(() => void 0);
+    return next;
+  }
 };
 function isProgressCompatible(record, compatibility) {
   if (record.language !== void 0 && record.language !== compatibility?.language) return false;
@@ -440,6 +515,8 @@ function isProgressCompatible(record, compatibility) {
   if (compatibility?.language !== void 0 && record.language !== compatibility.language) return false;
   if (compatibility?.contentVersion !== void 0 && record.contentVersion !== compatibility.contentVersion)
     return false;
+  if (record.audioId !== void 0 && record.audioId !== compatibility?.audioId) return false;
+  if (compatibility?.audioId !== void 0 && record.audioId !== compatibility.audioId) return false;
   return true;
 }
 var KeepProgressStorageError = class extends Error {
@@ -457,7 +534,7 @@ function isProgressRecord(value) {
     return typeof value.courseId === "string" && value.courseId.length > 0 && (value.currentItemId === void 0 || typeof value.currentItemId === "string");
   }
   if (value.kind !== "item") return false;
-  return typeof value.itemId === "string" && value.itemId.length > 0 && (value.audioPositionMs === void 0 || typeof value.audioPositionMs === "number" && Number.isFinite(value.audioPositionMs) && value.audioPositionMs >= 0) && (value.readingPosition === void 0 || typeof value.readingPosition === "number" && Number.isFinite(value.readingPosition) && value.readingPosition >= 0) && (value.language === void 0 || typeof value.language === "string") && (value.contentVersion === void 0 || typeof value.contentVersion === "string");
+  return typeof value.itemId === "string" && value.itemId.length > 0 && (value.audioPositionMs === void 0 || typeof value.audioPositionMs === "number" && Number.isFinite(value.audioPositionMs) && value.audioPositionMs >= 0) && (value.readingPosition === void 0 || typeof value.readingPosition === "number" && Number.isFinite(value.readingPosition) && value.readingPosition >= 0 || typeof value.readingPosition === "string" && value.readingPosition.trim().length > 0) && (value.audioId === void 0 || typeof value.audioId === "string" && value.audioId.length > 0) && (value.language === void 0 || typeof value.language === "string") && (value.contentVersion === void 0 || typeof value.contentVersion === "string");
 }
 function normalizeProgressRecord(record) {
   if (!isProgressRecord(record)) throw new TypeError("KeepKit progress record is invalid.");
@@ -474,6 +551,7 @@ function normalizeProgressRecord(record) {
     itemId: normalizeId2(record.itemId, "item"),
     ...record.audioPositionMs !== void 0 ? { audioPositionMs: record.audioPositionMs } : {},
     ...record.readingPosition !== void 0 ? { readingPosition: record.readingPosition } : {},
+    ...record.audioId !== void 0 ? { audioId: record.audioId } : {},
     ...record.language !== void 0 ? { language: record.language } : {},
     ...record.contentVersion !== void 0 ? { contentVersion: record.contentVersion } : {},
     updatedAt: record.updatedAt
@@ -969,6 +1047,7 @@ var AuthenticatedSyncStorageController = class {
 function createAuthenticatedRemote(options, scope) {
   const pull = options.transport.pull;
   const pullCollections = options.transport.pullCollections;
+  const pullMemberships = options.transport.pullMemberships;
   return {
     push: async (operation) => {
       try {
@@ -1001,6 +1080,22 @@ function createAuthenticatedRemote(options, scope) {
       } catch (cause) {
         return handleAuthFailure(cause, options, { scope });
       }
+    } : void 0,
+    pushMembership: options.transport.pushMembership ? async (membershipOperation) => {
+      try {
+        const token = await options.getAuthToken();
+        await options.transport.pushMembership?.(membershipOperation, { token, scope, membershipOperation });
+      } catch (cause) {
+        return handleAuthFailure(cause, options, { membershipOperation, scope });
+      }
+    } : void 0,
+    pullMemberships: pullMemberships ? async () => {
+      try {
+        const token = await options.getAuthToken();
+        return await pullMemberships({ token, scope });
+      } catch (cause) {
+        return handleAuthFailure(cause, options, { scope });
+      }
     } : void 0
   };
 }
@@ -1084,6 +1179,7 @@ export {
   mergeKeepItems,
   mergeKeepListQueryFromUrl,
   migrateKeepItems,
+  migrateLegacyCollectionMemberships,
   moveKeepItem,
   normalizeKeepTags,
   orderKeepItems,