@vue-skuilder/db 0.1.11-9 → 0.1.12

package/src/impl/couch/auth.ts

@@ -39,10 +39,14 @@ export async function getCurrentSession(): Promise<SessionResponse> {
   try {
     // Handle case where ENV variables might not be properly set
     if (ENV.COUCHDB_SERVER_URL === NOT_SET || ENV.COUCHDB_SERVER_PROTOCOL === NOT_SET) {
-      throw new Error('CouchDB server configuration not properly initialized');
+      throw new Error(`CouchDB server configuration not properly initialized. Protocol: "${ENV.COUCHDB_SERVER_PROTOCOL}", URL: "${ENV.COUCHDB_SERVER_URL}"`);
     }
     
-    const url = `${ENV.COUCHDB_SERVER_PROTOCOL}://${ENV.COUCHDB_SERVER_URL}_session`;
+    // Ensure URL has proper slash before _session endpoint
+    const baseUrl = ENV.COUCHDB_SERVER_URL.endsWith('/') 
+      ? ENV.COUCHDB_SERVER_URL.slice(0, -1) 
+      : ENV.COUCHDB_SERVER_URL;
+    const url = `${ENV.COUCHDB_SERVER_PROTOCOL}://${baseUrl}/_session`;
     logger.debug(`Attempting session check at: ${url}`);
     
     const response = await fetch(url, {
@@ -57,8 +61,13 @@ export async function getCurrentSession(): Promise<SessionResponse> {
     const resp: SessionResponse = await response.json();
     return resp;
   } catch (error) {
-    logger.error(`Session check error: ${error}`);
-    throw new Error(`Session check failed: ${error}`);
+    // Use same URL construction logic for error reporting
+    const baseUrl = ENV.COUCHDB_SERVER_URL.endsWith('/') 
+      ? ENV.COUCHDB_SERVER_URL.slice(0, -1) 
+      : ENV.COUCHDB_SERVER_URL;
+    const url = `${ENV.COUCHDB_SERVER_PROTOCOL}://${baseUrl}/_session`;
+    logger.error(`Session check error attempting to connect to: ${url} - ${error}`);
+    throw new Error(`Session check failed connecting to ${url}: ${error}`);
   }
 }
 

package/src/impl/couch/classroomDB.ts

@@ -8,12 +8,7 @@ import { ENV } from '@db/factory';
 import { logger } from '@db/util/logger';
 import moment from 'moment';
 import pouch from './pouchdb-setup';
-import {
-  getCourseDB,
-  getStartAndEndKeys,
-  pouchDBincludeCredentialsConfig,
-  REVIEW_TIME_FORMAT,
-} from '.';
+import { getCourseDB, getStartAndEndKeys, createPouchDBConfig, REVIEW_TIME_FORMAT } from '.';
 import { CourseDB, getTag } from './courseDB';
 
 import { UserDBInterface } from '@db/core';
@@ -97,7 +92,7 @@ export class StudentClassroomDB
     const dbName = `classdb-student-${this._id}`;
     this._db = new pouch(
       ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,
-      pouchDBincludeCredentialsConfig
+      createPouchDBConfig()
     );
     try {
       const cfg = await this._db.get<ClassroomConfig>(CLASSROOM_CONFIG);
@@ -181,10 +176,13 @@ export class StudentClassroomDB
       }
     }
 
-    logger.info(`New Cards from classroom ${this._cfg.name}: ${ret.map((c) => c.qualifiedID)}`);
+    logger.info(
+      `New Cards from classroom ${this._cfg.name}: ${ret.map((c) => `${c.courseID}-${c.cardID}`)}`
+    );
 
     return ret.filter((c) => {
-      if (activeCards.some((ac) => c.qualifiedID.includes(ac))) {
+      if (activeCards.some((ac) => c.cardID === ac.cardID)) {
+        // [ ] almost certainly broken after removing qualifiedID from StudySessionItem
         return false;
       } else {
         return true;
@@ -209,11 +207,11 @@ export class TeacherClassroomDB extends ClassroomDBBase implements TeacherClassr
     const stuDbName = `classdb-student-${this._id}`;
     this._db = new pouch(
       ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,
-      pouchDBincludeCredentialsConfig
+      createPouchDBConfig()
     );
     this._stuDb = new pouch(
       ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + stuDbName,
-      pouchDBincludeCredentialsConfig
+      createPouchDBConfig()
     );
     try {
       return this._db
@@ -297,7 +295,7 @@ export function getClassroomDB(classID: string, version: 'student' | 'teacher'):
 
   return new pouch(
     ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,
-    pouchDBincludeCredentialsConfig
+    createPouchDBConfig()
   );
 }
 

package/src/impl/couch/courseAPI.ts

@@ -1,5 +1,5 @@
 import pouch from './pouchdb-setup';
-import { pouchDBincludeCredentialsConfig } from '.';
+import { createPouchDBConfig } from '.';
 import { ENV } from '@db/factory';
 // import { DataShape } from '../..base-course/Interfaces/DataShape';
 import { NameSpacer, ShapeDescriptor } from '@vue-skuilder/common';
@@ -279,6 +279,6 @@ export function getCourseDB(courseID: string): PouchDB.Database {
   const dbName = `coursedb-${courseID}`;
   return new pouch(
     ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,
-    pouchDBincludeCredentialsConfig
+    createPouchDBConfig()
   );
 }

package/src/impl/couch/courseDB.ts

@@ -18,7 +18,15 @@ import {
   StudySessionNewItem,
   StudySessionReviewItem,
 } from '../../core/interfaces/contentSource';
-import { CardData, DocType, SkuilderCourseData, Tag, TagStub } from '../../core/types/types-legacy';
+import {
+  CardData,
+  DocType,
+  QualifiedCardID,
+  SkuilderCourseData,
+  Tag,
+  TagStub,
+  DocTypePrefixes,
+} from '../../core/types/types-legacy';
 import { logger } from '../../util/logger';
 import { GET_CACHED } from './clientCache';
 import { addNote55, addTagToCard, getCredentialledCourseConfig, getTagID } from './courseAPI';
@@ -217,7 +225,29 @@ export class CourseDB implements StudyContentSource, CourseDBInterface {
     if (!doc.docType || !(doc.docType === DocType.CARD)) {
       throw new Error(`failed to remove ${id} from course ${this.id}. id does not point to a card`);
     }
-    // TODO: remove card from tags lists (getTagsByCards)
+    
+    // Remove card from all associated tags before deleting the card
+    try {
+      const appliedTags = await this.getAppliedTags(id);
+      const results = await Promise.allSettled(
+        appliedTags.rows.map(async (tagRow) => {
+          const tagId = tagRow.id;
+          await this.removeTagFromCard(id, tagId);
+        })
+      );
+      
+      // Log any individual tag cleanup failures
+      results.forEach((result, index) => {
+        if (result.status === 'rejected') {
+          const tagId = appliedTags.rows[index].id;
+          logger.error(`Failed to remove card ${id} from tag ${tagId}: ${result.reason}`);
+        }
+      });
+    } catch (error) {
+      logger.error(`Error removing card ${id} from tags: ${error}`);
+      // Continue with card deletion even if tag cleanup fails
+    }
+    
     return this.db.remove(doc);
   }
 
@@ -263,7 +293,7 @@ export class CourseDB implements StudyContentSource, CourseDBInterface {
       limit: aboveLimit,
       startkey: elo + 1,
     });
-    // console.log(JSON.stringify(below));
+    // logger.log(JSON.stringify(below));
 
     let cards = below.rows;
     cards = cards.concat(above.rows);
@@ -277,7 +307,13 @@ export class CourseDB implements StudyContentSource, CourseDBInterface {
           return s;
         }
       })
-      .map((c) => `${this.id}-${c.id}-${c.key}`);
+      .map((c) => {
+        return {
+          courseID: this.id,
+          cardID: c.id,
+          elo: c.key,
+        };
+      });
 
     const str = `below:\n${below.rows.map((r) => `\t${r.id}-${r.key}\n`)}
 
@@ -342,7 +378,13 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
     tagId: string,
     updateELO?: boolean
   ): Promise<PouchDB.Core.Response> {
-    return await addTagToCard(this.id, cardId, tagId, (await this._getCurrentUser()).getUsername(), updateELO);
+    return await addTagToCard(
+      this.id,
+      cardId,
+      tagId,
+      (await this._getCurrentUser()).getUsername(),
+      updateELO
+    );
   }
 
   async removeTagFromCard(cardId: string, tagId: string): Promise<PouchDB.Core.Response> {
@@ -437,40 +479,38 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
 
   getNavigationStrategy(id: string): Promise<ContentNavigationStrategyData> {
     logger.debug(`[courseDB] Getting navigation strategy: ${id}`);
-    // For now, just return the ELO strategy regardless of the ID
-    const strategy: ContentNavigationStrategyData = {
-      id: 'ELO',
-      docType: DocType.NAVIGATION_STRATEGY,
-      name: 'ELO',
-      description: 'ELO-based navigation strategy for ordering content by difficulty',
-      implementingClass: Navigators.ELO,
-      course: this.id,
-      serializedData: '', // serde is a noop for ELO navigator.
-    };
-    return Promise.resolve(strategy);
-  }
 
-  getAllNavigationStrategies(): Promise<ContentNavigationStrategyData[]> {
-    logger.debug('[courseDB] Returning hard-coded navigation strategies');
-    const strategies: ContentNavigationStrategyData[] = [
-      {
-        id: 'ELO',
+    if (id == '') {
+      const strategy: ContentNavigationStrategyData = {
+        _id: 'NAVIGATION_STRATEGY-ELO',
         docType: DocType.NAVIGATION_STRATEGY,
         name: 'ELO',
         description: 'ELO-based navigation strategy for ordering content by difficulty',
         implementingClass: Navigators.ELO,
         course: this.id,
         serializedData: '', // serde is a noop for ELO navigator.
-      },
-    ];
-    return Promise.resolve(strategies);
+      };
+      return Promise.resolve(strategy);
+    } else {
+      return this.db.get(id);
+    }
   }
 
-  addNavigationStrategy(data: ContentNavigationStrategyData): Promise<void> {
-    logger.debug(`[courseDB] Adding navigation strategy: ${data.id}`);
-    // For now, just log the data and return success
-    logger.debug(JSON.stringify(data));
-    return Promise.resolve();
+  async getAllNavigationStrategies(): Promise<ContentNavigationStrategyData[]> {
+    const prefix = DocTypePrefixes[DocType.NAVIGATION_STRATEGY];
+    const result = await this.db.allDocs<ContentNavigationStrategyData>({
+      startkey: prefix,
+      endkey: `${prefix}\ufff0`,
+      include_docs: true,
+    });
+    return result.rows.map((row) => row.doc!);
+  }
+
+  async addNavigationStrategy(data: ContentNavigationStrategyData): Promise<void> {
+    logger.debug(`[courseDB] Adding navigation strategy: ${data._id}`);
+    // // For now, just log the data and return success
+    // logger.debug(JSON.stringify(data));
+    return this.db.put(data).then(() => {});
   }
   updateNavigationStrategy(id: string, data: ContentNavigationStrategyData): Promise<void> {
     logger.debug(`[courseDB] Updating navigation strategy: ${id}`);
@@ -480,9 +520,35 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
   }
 
   async surfaceNavigationStrategy(): Promise<ContentNavigationStrategyData> {
+    try {
+      const config = await this.getCourseConfig();
+      // @ts-expect-error tmp: defaultNavigationStrategyId property does not yet exist
+      if (config.defaultNavigationStrategyId) {
+        try {
+          // @ts-expect-error tmp: defaultNavigationStrategyId property does not yet exist
+          const strategy = await this.getNavigationStrategy(config.defaultNavigationStrategyId);
+          if (strategy) {
+            logger.debug(`Surfacing strategy ${strategy.name} from course config`);
+            return strategy;
+          }
+        } catch (e) {
+          logger.warn(
+            // @ts-expect-error tmp: defaultNavigationStrategyId property does not yet exist
+            `Failed to load strategy '${config.defaultNavigationStrategyId}' specified in course config. Falling back to ELO.`,
+            e
+          );
+        }
+      }
+    } catch (e) {
+      logger.warn(
+        'Could not retrieve course config to determine navigation strategy. Falling back to ELO.',
+        e
+      );
+    }
+
     logger.warn(`Returning hard-coded default ELO navigator`);
     const ret: ContentNavigationStrategyData = {
-      id: 'ELO',
+      _id: 'NAVIGATION_STRATEGY-ELO',
       docType: DocType.NAVIGATION_STRATEGY,
       name: 'ELO',
       description: 'ELO-based navigation strategy',
@@ -535,7 +601,7 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
       limit: 99,
       elo: 'user',
     },
-    filter?: (a: string) => boolean
+    filter?: (a: QualifiedCardID) => boolean
   ): Promise<StudySessionItem[]> {
     let targetElo: number;
 
@@ -554,12 +620,12 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
     } else if (options.elo === 'random') {
       const bounds = await GET_CACHED(`elo-bounds-${this.id}`, () => this.getELOBounds());
       targetElo = Math.round(bounds.low + Math.random() * (bounds.high - bounds.low));
-      // console.log(`Picked ${targetElo} from [${bounds.low}, ${bounds.high}]`);
+      // logger.log(`Picked ${targetElo} from [${bounds.low}, ${bounds.high}]`);
     } else {
       targetElo = options.elo;
     }
 
-    let cards: string[] = [];
+    let cards: (QualifiedCardID & { elo?: number })[] = [];
     let mult: number = 4;
     let previousCount: number = -1;
     let newCount: number = 0;
@@ -579,7 +645,11 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
       mult *= 2;
     }
 
-    const selectedCards: string[] = [];
+    const selectedCards: {
+      courseID: string;
+      cardID: string;
+      elo?: number;
+    }[] = [];
 
     while (selectedCards.length < options.limit && cards.length > 0) {
       const index = randIntWeightedTowardZero(cards.length);
@@ -588,17 +658,113 @@ above:\n${above.rows.map((r) => `\t${r.id}-${r.key}\n`)}`;
     }
 
     return selectedCards.map((c) => {
-      const split = c.split('-');
       return {
         courseID: this.id,
-        cardID: split[1],
-        qualifiedID: `${split[0]}-${split[1]}`,
+        cardID: c.cardID,
         contentSourceType: 'course',
         contentSourceID: this.id,
+        elo: c.elo,
         status: 'new',
       };
     });
   }
+
+  // Admin search methods
+  public async searchCards(query: string): Promise<any[]> {
+    logger.log(`[CourseDB ${this.id}] Searching for: "${query}"`);
+
+    // Try multiple search approaches
+    let displayableData;
+
+    try {
+      // Try regex search on the correct data structure: data[0].data
+      displayableData = await this.db.find({
+        selector: {
+          docType: 'DISPLAYABLE_DATA',
+          'data.0.data': { $regex: `.*${query}.*` },
+        },
+      });
+      logger.log(`[CourseDB ${this.id}] Regex search on data[0].data successful`);
+    } catch (regexError) {
+      logger.log(
+        `[CourseDB ${this.id}] Regex search failed, falling back to manual search:`,
+        regexError
+      );
+
+      // Fallback: get all displayable data and filter manually
+      const allDisplayable = await this.db.find({
+        selector: {
+          docType: 'DISPLAYABLE_DATA',
+        },
+      });
+
+      logger.log(
+        `[CourseDB ${this.id}] Retrieved ${allDisplayable.docs.length} documents for manual filtering`
+      );
+
+      displayableData = {
+        docs: allDisplayable.docs.filter((doc) => {
+          // Search entire document as JSON string - inclusive approach for admin tool
+          const docString = JSON.stringify(doc).toLowerCase();
+          const match = docString.includes(query.toLowerCase());
+          if (match) {
+            logger.log(`[CourseDB ${this.id}] Manual match found in document: ${doc._id}`);
+          }
+          return match;
+        }),
+      };
+    }
+
+    logger.log(
+      `[CourseDB ${this.id}] Found ${displayableData.docs.length} displayable data documents`
+    );
+
+    if (displayableData.docs.length === 0) {
+      // Debug: Let's see what displayable data exists
+      const allDisplayableData = await this.db.find({
+        selector: {
+          docType: 'DISPLAYABLE_DATA',
+        },
+        limit: 5, // Just sample a few
+      });
+
+      logger.log(
+        `[CourseDB ${this.id}] Sample displayable data:`,
+        allDisplayableData.docs.map((d) => ({
+          id: d._id,
+          docType: (d as any).docType,
+          dataStructure: (d as any).data ? Object.keys((d as any).data) : 'no data field',
+          dataContent: (d as any).data,
+          fullDoc: d,
+        }))
+      );
+    }
+
+    const allResults: any[] = [];
+
+    for (const dd of displayableData.docs) {
+      const cards = await this.db.find({
+        selector: {
+          docType: 'CARD',
+          id_displayable_data: { $in: [dd._id] },
+        },
+      });
+
+      logger.log(
+        `[CourseDB ${this.id}] Displayable data ${dd._id} linked to ${cards.docs.length} cards`
+      );
+      allResults.push(...cards.docs);
+    }
+
+    logger.log(`[CourseDB ${this.id}] Total cards found: ${allResults.length}`);
+    return allResults;
+  }
+
+  public async find(
+    request: PouchDB.Find.FindRequest<any>
+  ): Promise<PouchDB.Find.FindResponse<any>> {
+    return this.db.find(request);
+  }
 }
 
 /**

package/src/impl/couch/courseLookupDB.ts

@@ -105,15 +105,15 @@ export default class CourseLookup {
    * @returns Promise<void>
    */
   static async addWithId(
-    courseId: string, 
-    courseName: string, 
+    courseId: string,
+    courseName: string,
     disambiguator?: string
   ): Promise<void> {
     const doc: Omit<CourseLookupDoc, '_rev'> = {
       _id: courseId,
       name: courseName,
     };
-    
+
     if (disambiguator) {
       doc.disambiguator = disambiguator;
     }
@@ -130,6 +130,7 @@ export default class CourseLookup {
     return await CourseLookup._db.remove(doc);
   }
 
+  // [ ] rename to allCourses()
   static async allCourseWare(): Promise<CourseLookupDoc[]> {
     const resp = await CourseLookup._db.allDocs<CourseLookupDoc>({
       include_docs: true,

package/src/impl/couch/index.ts

@@ -38,7 +38,7 @@ export function hexEncode(str: string): string {
 
   return returnStr;
 }
-export const pouchDBincludeCredentialsConfig: PouchDB.Configuration.RemoteDatabaseConfiguration = {
+const pouchDBincludeCredentialsConfig: PouchDB.Configuration.RemoteDatabaseConfiguration = {
   fetch(url: string | Request, opts: RequestInit): Promise<Response> {
     opts.credentials = 'include';
 
@@ -46,10 +46,42 @@ export const pouchDBincludeCredentialsConfig: PouchDB.Configuration.RemoteDataba
   },
 } as PouchDB.Configuration.RemoteDatabaseConfiguration;
 
+/**
+ * Creates PouchDB configuration with appropriate authentication method
+ * - Uses HTTP Basic Auth when credentials are available (Node.js/MCP)
+ * - Falls back to cookie auth for browser environments
+ */
+export function createPouchDBConfig(): PouchDB.Configuration.RemoteDatabaseConfiguration {
+  // Check if running in Node.js with explicit credentials
+  const hasExplicitCredentials = ENV.COUCHDB_USERNAME && ENV.COUCHDB_PASSWORD;
+  const isNodeEnvironment = typeof window === 'undefined';
+  
+  if (hasExplicitCredentials && isNodeEnvironment) {
+    // Use HTTP Basic Auth for Node.js environments (MCP server)
+    return {
+      fetch(url: string | Request, opts: RequestInit = {}): Promise<Response> {
+        const basicAuth = btoa(`${ENV.COUCHDB_USERNAME}:${ENV.COUCHDB_PASSWORD}`);
+        const headers = new Headers(opts.headers || {});
+        headers.set('Authorization', `Basic ${basicAuth}`);
+        
+        const newOpts = {
+          ...opts,
+          headers: headers
+        };
+        
+        return (pouch as any).fetch(url, newOpts);
+      }
+    } as PouchDB.Configuration.RemoteDatabaseConfiguration;
+  }
+  
+  // Use cookie-based auth for browser environments or when no explicit credentials
+  return pouchDBincludeCredentialsConfig;
+}
+
 function getCouchDB(dbName: string): PouchDB.Database {
   return new pouch(
     ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,
-    pouchDBincludeCredentialsConfig
+    createPouchDBConfig()
   );
 }
 
@@ -57,7 +89,7 @@ export function getCourseDB(courseID: string): PouchDB.Database {
   // todo: keep a cache of opened courseDBs? need to benchmark this somehow
   return new pouch(
     ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + 'coursedb-' + courseID,
-    pouchDBincludeCredentialsConfig
+    createPouchDBConfig()
   );
 }
 
@@ -188,7 +220,7 @@ export function getCouchUserDB(username: string): PouchDB.Database {
   // see: https://github.com/pouchdb-community/pouchdb-authentication/issues/239
   const ret = new pouch(
     ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,
-    pouchDBincludeCredentialsConfig
+    createPouchDBConfig()
   );
   if (guestAccount) {
     updateGuestAccountExpirationDate(ret);

package/src/impl/couch/pouchdb-setup.ts

@@ -8,9 +8,9 @@ PouchDB.plugin(PouchDBAuth);
 
 // Configure PouchDB globally
 PouchDB.defaults({
-  ajax: {
-    timeout: 60000,
-  },
+  // ajax: {
+  //   timeout: 60000,
+  // },
 });
 
 export default PouchDB;

package/src/impl/couch/updateQueue.ts

@@ -44,51 +44,74 @@ export default class UpdateQueue extends Loggable {
   ): Promise<T & PouchDB.Core.GetMeta & PouchDB.Core.RevisionIdMeta> {
     logger.debug(`Applying updates on doc: ${id}`);
     if (this.inprogressUpdates[id]) {
-      // console.log(`Updates in progress...`);
-      await this.readDB.info(); // stall for a round trip
-      // console.log(`Retrying...`);
+      // Poll instead of recursing to avoid infinite recursion
+      while (this.inprogressUpdates[id]) {
+        await new Promise(resolve => setTimeout(resolve, Math.random() * 50));
+      }
       return this.applyUpdates<T>(id);
     } else {
       if (this.pendingUpdates[id] && this.pendingUpdates[id].length > 0) {
         this.inprogressUpdates[id] = true;
 
-        try {
-          let doc = await this.readDB.get<T>(id);
-          logger.debug(`Retrieved doc: ${id}`);
-          while (this.pendingUpdates[id].length !== 0) {
-            const update = this.pendingUpdates[id].splice(0, 1)[0];
-            if (typeof update === 'function') {
-              doc = { ...doc, ...update(doc) };
-            } else {
-              doc = {
-                ...doc,
-                ...update,
-              };
+        const MAX_RETRIES = 5;
+        for (let i = 0; i < MAX_RETRIES; i++) {
+          try {
+            const doc = await this.readDB.get<T>(id);
+            logger.debug(`Retrieved doc: ${id}`);
+
+            // Create a new doc object to apply updates to for this attempt
+            let updatedDoc = { ...doc };
+
+            // Note: This loop is not fully safe if updates are functions that depend on a specific doc state
+            // that might change between retries. But for simple object merges, it's okay.
+            const updatesToApply = [...this.pendingUpdates[id]];
+            for (const update of updatesToApply) {
+              if (typeof update === 'function') {
+                updatedDoc = { ...updatedDoc, ...update(updatedDoc) };
+              } else {
+                updatedDoc = {
+                  ...updatedDoc,
+                  ...update,
+                };
+              }
             }
-          }
-          // for (const k in doc) {
-          //   console.log(`${k}: ${typeof k}`);
-          // }
-          // console.log(`Applied updates to doc: ${JSON.stringify(doc)}`);
-          await this.writeDB.put<T>(doc);
-          logger.debug(`Put doc: ${id}`);
 
-          if (this.pendingUpdates[id].length === 0) {
-            this.inprogressUpdates[id] = false;
-            delete this.inprogressUpdates[id];
-          } else {
-            return this.applyUpdates<T>(id);
-          }
-          return doc;
-        } catch (e) {
-          // Clean up queue state before re-throwing
-          delete this.inprogressUpdates[id];
-          if (this.pendingUpdates[id]) {
-            delete this.pendingUpdates[id];
+            await this.writeDB.put<T>(updatedDoc);
+            logger.debug(`Put doc: ${id}`);
+
+            // Success! Remove the updates we just applied.
+            this.pendingUpdates[id].splice(0, updatesToApply.length);
+
+            if (this.pendingUpdates[id].length === 0) {
+              this.inprogressUpdates[id] = false;
+              delete this.inprogressUpdates[id];
+            } else {
+              // More updates came in, run again.
+              return this.applyUpdates<T>(id);
+            }
+            return updatedDoc as any; // success, exit loop and function
+          } catch (e: any) {
+            if (e.name === 'conflict' && i < MAX_RETRIES - 1) {
+              logger.warn(`Conflict on update for doc ${id}, retry #${i + 1}`);
+              await new Promise((res) => setTimeout(res, 50 * Math.random()));
+              // continue to next iteration of the loop
+            } else if (e.name === 'not_found' && i === 0) {
+              // Document not present - throw to caller for initialization
+              logger.warn(`Update failed for ${id} - does not exist. Throwing to caller.`);
+              throw e; // Let caller handle
+            } else {
+              // Max retries reached or a non-conflict error
+              delete this.inprogressUpdates[id];
+              if (this.pendingUpdates[id]) {
+                delete this.pendingUpdates[id];
+              }
+              logger.error(`Error on attemped update (retry ${i}): ${JSON.stringify(e)}`);
+              throw e; // Let caller handle
+            }
           }
-          logger.error(`Error on attemped update: ${JSON.stringify(e)}`);
-          throw e; // Let caller handle (e.g., putCardRecord's 404 handling)
         }
+        // This should be unreachable, but it satisfies the compiler that a value is always returned or an error thrown.
+        throw new Error(`UpdateQueue failed for doc ${id} after ${MAX_RETRIES} retries.`);
       } else {
         throw new Error(`Empty Updates Queue Triggered`);
       }