@vue-skuilder/db 0.1.3 → 0.1.5

package/src/impl/common/SyncStrategy.ts

@@ -0,0 +1,90 @@
+// packages/db/src/impl/common/SyncStrategy.ts
+
+import type { AccountCreationResult, AuthenticationResult } from './types';
+
+/**
+ * Strategy interface for handling user data synchronization
+ * Different implementations handle remote sync vs local-only storage
+ */
+export interface SyncStrategy {
+  /**
+   * Set up the remote database for a user
+   * @param username The username to set up remote DB for
+   * @returns PouchDB database instance (may be same as local for no-op)
+   */
+  setupRemoteDB(username: string): PouchDB.Database;
+
+  /**
+   * Start synchronization between local and remote databases
+   * @param localDB The local PouchDB instance
+   * @param remoteDB The remote PouchDB instance
+   */
+  startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database): void;
+
+  /**
+   * Stop synchronization (optional - for cleanup)
+   */
+  stopSync?(): void;
+
+  /**
+   * Whether this strategy supports account creation
+   */
+  canCreateAccount(): boolean;
+
+  /**
+   * Whether this strategy supports authentication
+   */
+  canAuthenticate(): boolean;
+
+  /**
+   * Create a new user account (if supported)
+   * @param username The username for the new account
+   * @param password The password for the new account
+   */
+  createAccount?(username: string, password: string): Promise<AccountCreationResult>;
+
+  /**
+   * Authenticate a user (if supported)
+   * @param username The username to authenticate
+   * @param password The password to authenticate with
+   */
+  authenticate?(username: string, password: string): Promise<AuthenticationResult>;
+
+  /**
+   * Log out the current user (if supported)
+   */
+  logout?(): Promise<AuthenticationResult>;
+
+  /**
+   * Get the current logged-in username
+   * Returns the username if logged in, or a default guest username
+   */
+  getCurrentUsername(): Promise<string>;
+}
+
+/**
+ * Base class for sync strategies with common functionality
+ */
+export abstract class BaseSyncStrategy implements SyncStrategy {
+  abstract setupRemoteDB(username: string): PouchDB.Database;
+  abstract startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database): void;
+  abstract canCreateAccount(): boolean;
+  abstract canAuthenticate(): boolean;
+  abstract getCurrentUsername(): Promise<string>;
+
+  stopSync?(): void {
+    // Default no-op implementation
+  }
+
+  async createAccount(_username: string, _password: string): Promise<AccountCreationResult> {
+    throw new Error('Account creation not supported by this sync strategy');
+  }
+
+  async authenticate(_username: string, _password: string): Promise<AuthenticationResult> {
+    throw new Error('Authentication not supported by this sync strategy');
+  }
+
+  async logout(): Promise<AuthenticationResult> {
+    throw new Error('Logout not supported by this sync strategy');
+  }
+}

package/src/impl/common/index.ts

@@ -0,0 +1,23 @@
+// packages/db/src/impl/common/index.ts
+
+export type { SyncStrategy } from './SyncStrategy';
+export { BaseSyncStrategy } from './SyncStrategy';
+export type {
+  AccountCreationResult,
+  AuthenticationResult,
+  UserSession,
+  SyncConfig,
+  SyncStatus,
+} from './types';
+export { BaseUser } from './BaseUserDB';
+export {
+  REVIEW_PREFIX,
+  REVIEW_TIME_FORMAT,
+  hexEncode,
+  filterAllDocsByPrefix,
+  getStartAndEndKeys,
+  updateGuestAccountExpirationDate,
+  getLocalUserDB,
+  scheduleCardReviewLocal,
+  removeScheduledCardReviewLocal,
+} from './userDBHelpers';

package/src/impl/common/types.ts

@@ -0,0 +1,50 @@
+// packages/db/src/impl/common/types.ts
+
+/**
+ * Common types used by UserDB implementations across different sync strategies
+ */
+
+import { Status } from '@vue-skuilder/common';
+
+/**
+ * Result type for account creation operations
+ */
+export interface AccountCreationResult {
+  status: Status;
+  error?: string;
+}
+
+/**
+ * Result type for authentication operations
+ */
+export interface AuthenticationResult {
+  ok: boolean;
+  error?: string;
+}
+
+/**
+ * User session information
+ */
+export interface UserSession {
+  username: string;
+  isLoggedIn: boolean;
+  isGuest: boolean;
+}
+
+/**
+ * Configuration for sync behavior
+ */
+export interface SyncConfig {
+  live?: boolean;
+  retry?: boolean;
+  continuous?: boolean;
+}
+
+/**
+ * Sync status information
+ */
+export interface SyncStatus {
+  active: boolean;
+  lastSync?: Date;
+  error?: string;
+}

package/src/impl/common/userDBHelpers.ts

@@ -0,0 +1,144 @@
+// packages/db/src/impl/common/userDBHelpers.ts
+
+import moment from 'moment';
+import { logger } from '../../util/logger';
+import { ScheduledCard } from '@db/core/types/user';
+
+export const REVIEW_PREFIX: string = 'card_review_';
+export const REVIEW_TIME_FORMAT: string = 'YYYY-MM-DD--kk:mm:ss-SSS';
+
+import pouch from '../couch/pouchdb-setup';
+
+const log = (s: any) => {
+  logger.info(s);
+};
+
+export function hexEncode(str: string): string {
+  let hex: string;
+  let returnStr: string = '';
+
+  for (let i = 0; i < str.length; i++) {
+    hex = str.charCodeAt(i).toString(16);
+    returnStr += ('000' + hex).slice(3);
+  }
+
+  return returnStr;
+}
+
+export function filterAllDocsByPrefix<T>(
+  db: PouchDB.Database,
+  prefix: string,
+  opts?: PouchDB.Core.AllDocsOptions
+) {
+  // see couchdb docs 6.2.2:
+  //   Guide to Views -> Views Collation -> String Ranges
+  const options: PouchDB.Core.AllDocsWithinRangeOptions = {
+    startkey: prefix,
+    endkey: prefix + '\ufff0',
+    include_docs: true,
+  };
+
+  if (opts) {
+    Object.assign(options, opts);
+  }
+  return db.allDocs<T>(options);
+}
+
+export function getStartAndEndKeys(key: string): {
+  startkey: string;
+  endkey: string;
+} {
+  return {
+    startkey: key,
+    endkey: key + '\ufff0',
+  };
+}
+
+export function updateGuestAccountExpirationDate(guestDB: PouchDB.Database<object>) {
+  const currentTime = moment.utc();
+  const expirationDate: string = currentTime.add(2, 'months').toISOString();
+  const expiryDocID: string = 'GuestAccountExpirationDate';
+
+  void guestDB
+    .get(expiryDocID)
+    .then((doc) => {
+      return guestDB.put({
+        _id: expiryDocID,
+        _rev: doc._rev,
+        date: expirationDate,
+      });
+    })
+    .catch(() => {
+      return guestDB.put({
+        _id: expiryDocID,
+        date: expirationDate,
+      });
+    });
+}
+
+/**
+ * Get local user database with appropriate adapter for environment
+ */
+export function getLocalUserDB(username: string): PouchDB.Database {
+  // // Choose adapter based on environment
+  //
+  // Not certain of this is required. Let's let pouch's auto detection
+  // handle it until we specifically know we need to intervene.
+  //
+  // let adapter: string;
+  // if (typeof window !== 'undefined') {
+  //   // Browser environment - use IndexedDB
+  //   adapter = 'idb';
+  // } else {
+  //   // Node.js environment (tests) - use memory adapter
+  //   adapter = 'memory';
+  // }
+
+  return new pouch(`userdb-${username}`, {});
+}
+
+/**
+ * Schedule a card review (strategy-agnostic version)
+ */
+export function scheduleCardReviewLocal(
+  userDB: PouchDB.Database,
+  review: {
+    card_id: PouchDB.Core.DocumentId;
+    time: moment.Moment;
+    course_id: string;
+    scheduledFor: ScheduledCard['scheduledFor'];
+    schedulingAgentId: ScheduledCard['schedulingAgentId'];
+  }
+) {
+  const now = moment.utc();
+  logger.info(`Scheduling for review in: ${review.time.diff(now, 'h') / 24} days`);
+  void userDB.put<ScheduledCard>({
+    _id: REVIEW_PREFIX + review.time.format(REVIEW_TIME_FORMAT),
+    cardId: review.card_id,
+    reviewTime: review.time,
+    courseId: review.course_id,
+    scheduledAt: now,
+    scheduledFor: review.scheduledFor,
+    schedulingAgentId: review.schedulingAgentId,
+  });
+}
+
+/**
+ * Remove a scheduled card review (strategy-agnostic version)
+ */
+export async function removeScheduledCardReviewLocal(
+  userDB: PouchDB.Database,
+  reviewDocID: string
+) {
+  const reviewDoc = await userDB.get(reviewDocID);
+  userDB
+    .remove(reviewDoc)
+    .then((res) => {
+      if (res.ok) {
+        log(`Removed Review Doc: ${reviewDocID}`);
+      }
+    })
+    .catch((err) => {
+      log(`Failed to remove Review Doc: ${reviewDocID},\n${JSON.stringify(err)}`);
+    });
+}

package/src/impl/couch/CouchDBSyncStrategy.ts

@@ -0,0 +1,209 @@
+// packages/db/src/impl/couch/CouchDBSyncStrategy.ts
+
+import { ENV } from '@db/factory';
+import { GuestUsername } from '../../core/types/types-legacy';
+import { logger } from '../../util/logger';
+import { Status } from '@vue-skuilder/common';
+import type { SyncStrategy } from '../common/SyncStrategy';
+import type { AccountCreationResult, AuthenticationResult } from '../common/types';
+import { getLocalUserDB, hexEncode, updateGuestAccountExpirationDate } from '../common';
+import pouch from './pouchdb-setup';
+import { pouchDBincludeCredentialsConfig } from './index';
+import { getLoggedInUsername } from './auth';
+
+const log = (s: any) => {
+  logger.info(s);
+};
+
+/**
+ * Sync strategy that implements full CouchDB remote synchronization
+ * Handles account creation, authentication, and live sync with remote CouchDB server
+ */
+export class CouchDBSyncStrategy implements SyncStrategy {
+  private syncHandle?: any; // Handle to cancel sync if needed
+
+  setupRemoteDB(username: string): PouchDB.Database {
+    if (username === GuestUsername || username.startsWith(GuestUsername)) {
+      // For guest users, remote is same as local (no remote sync)
+      return getLocalUserDB(username);
+    } else {
+      // For real users, connect to remote CouchDB
+      return this.getUserDB(username);
+    }
+  }
+
+  startSync(localDB: PouchDB.Database, remoteDB: PouchDB.Database): void {
+    // Only sync if local and remote are different instances
+    if (localDB !== remoteDB) {
+      this.syncHandle = pouch.sync(localDB, remoteDB, {
+        live: true,
+        retry: true,
+      });
+    }
+    // If they're the same (guest mode), no sync needed
+  }
+
+  stopSync?(): void {
+    if (this.syncHandle) {
+      this.syncHandle.cancel();
+      this.syncHandle = undefined;
+    }
+  }
+
+  canCreateAccount(): boolean {
+    return true;
+  }
+
+  canAuthenticate(): boolean {
+    return true;
+  }
+
+  async createAccount(username: string, password: string): Promise<AccountCreationResult> {
+    try {
+      const signupRequest = await this.getRemoteCouchRootDB().signUp(username, password);
+
+      if (signupRequest.ok) {
+        log(`CREATEACCOUNT: Successfully created account for ${username}`);
+
+        // Log out any existing session
+        try {
+          const logoutResult = await this.getRemoteCouchRootDB().logOut();
+          log(`CREATEACCOUNT: logged out: ${logoutResult.ok}`);
+        } catch {
+          // Ignore logout errors - might not be logged in
+        }
+
+        // Log in as the new user
+        const loginResult = await this.getRemoteCouchRootDB().logIn(username, password);
+        log(`CREATEACCOUNT: logged in as new user: ${loginResult.ok}`);
+
+        if (loginResult.ok) {
+          // TODO: Handle guest data migration here if needed
+          // Set up databases for the new user:
+          // const newLocal = getLocalUserDB(username);
+          // const newRemote = this.getUserDB(username);
+
+          // For now, just return success
+          return {
+            status: Status.ok,
+            error: undefined,
+          };
+        } else {
+          return {
+            status: Status.error,
+            error: 'Failed to log in after account creation',
+          };
+        }
+      } else {
+        logger.warn(`Signup not OK: ${JSON.stringify(signupRequest)}`);
+        return {
+          status: Status.error,
+          error: 'Account creation failed',
+        };
+      }
+    } catch (e: any) {
+      if (e.reason === 'Document update conflict.') {
+        return {
+          status: Status.error,
+          error: 'This username is taken!',
+        };
+      }
+      logger.error(`Error on signup: ${JSON.stringify(e)}`);
+      return {
+        status: Status.error,
+        error: e.message || 'Unknown error during account creation',
+      };
+    }
+  }
+
+  async authenticate(username: string, password: string): Promise<AuthenticationResult> {
+    try {
+      const loginResult = await this.getRemoteCouchRootDB().logIn(username, password);
+
+      if (loginResult.ok) {
+        log(`Successfully logged in as ${username}`);
+        return {
+          ok: true,
+        };
+      } else {
+        log(`Login failed for ${username}`);
+        return {
+          ok: false,
+          error: 'Invalid username or password',
+        };
+      }
+    } catch (error: any) {
+      logger.error(`Authentication error for ${username}:`, error);
+      return {
+        ok: false,
+        error: error.message || 'Authentication failed',
+      };
+    }
+  }
+
+  async logout(): Promise<AuthenticationResult> {
+    try {
+      const result = await this.getRemoteCouchRootDB().logOut();
+      return {
+        ok: result.ok,
+        error: result.ok ? undefined : 'Logout failed',
+      };
+    } catch (error: any) {
+      logger.error('Logout error:', error);
+      return {
+        ok: false,
+        error: error.message || 'Logout failed',
+      };
+    }
+  }
+
+  async getCurrentUsername(): Promise<string> {
+    try {
+      return await getLoggedInUsername();
+    } catch {
+      return GuestUsername;
+    }
+  }
+
+  /**
+   * Get remote CouchDB root database for authentication operations
+   */
+  private getRemoteCouchRootDB(): PouchDB.Database {
+    const remoteStr: string =
+      ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + 'skuilder';
+
+    try {
+      return new pouch(remoteStr, {
+        skip_setup: true,
+      });
+    } catch (error) {
+      logger.error('Failed to initialize remote CouchDB connection:', error);
+      throw new Error(`Failed to initialize CouchDB: ${JSON.stringify(error)}`);
+    }
+  }
+
+  /**
+   * Get remote user database for a specific user
+   */
+  private getUserDB(username: string): PouchDB.Database {
+    const guestAccount: boolean = false;
+
+    const hexName = hexEncode(username);
+    const dbName = `userdb-${hexName}`;
+    log(`Fetching user database: ${dbName} (${username})`);
+
+    // Odd construction here the result of a bug in the
+    // interaction between pouch, pouch-auth.
+    // see: https://github.com/pouchdb-community/pouchdb-authentication/issues/239
+    const ret = new pouch(
+      ENV.COUCHDB_SERVER_PROTOCOL + '://' + ENV.COUCHDB_SERVER_URL + dbName,
+      pouchDBincludeCredentialsConfig
+    );
+
+    if (guestAccount) {
+      updateGuestAccountExpirationDate(ret);
+    }
+
+    return ret;
+  }
+}

package/src/impl/{pouch → couch}/PouchDataLayerProvider.ts

@@ -1,4 +1,4 @@
-// db/src/impl/pouch/PouchDataLayerProvider.ts
+// db/src/impl/couch/PouchDataLayerProvider.ts
 
 import {
   AdminDBInterface,
@@ -16,9 +16,10 @@ import { AdminDB } from './adminDB';
 import { StudentClassroomDB, TeacherClassroomDB } from './classroomDB';
 import { CourseDB, CoursesDB } from './courseDB';
 
-import { User } from './userDB';
+import { BaseUser } from '../common';
+import { CouchDBSyncStrategy } from './CouchDBSyncStrategy';
 
-export class PouchDataLayerProvider implements DataLayerProvider {
+export class CouchDataLayerProvider implements DataLayerProvider {
   private initialized: boolean = false;
   private userDB!: UserDBInterface;
   private currentUsername: string = '';
@@ -42,8 +43,11 @@ export class PouchDataLayerProvider implements DataLayerProvider {
 
     if (isNodeEnvironment) {
       logger.info(
-        'PouchDataLayerProvider: Running in Node.js environment, skipping user session check and user DB initialization.'
+        'CouchDataLayerProvider: Running in Node.js environment, creating guest UserDB for testing.'
       );
+      // In Node.js (testing) environment, create a guest user instance
+      const syncStrategy = new CouchDBSyncStrategy();
+      this.userDB = await BaseUser.instance(syncStrategy);
     } else {
       // Assume browser-like environment, proceed with user session logic
       try {
@@ -53,13 +57,14 @@ export class PouchDataLayerProvider implements DataLayerProvider {
 
         // Create the user db instance if a username was found
         if (this.currentUsername) {
-          this.userDB = await User.instance(this.currentUsername);
+          const syncStrategy = new CouchDBSyncStrategy();
+          this.userDB = await BaseUser.instance(syncStrategy, this.currentUsername);
         } else {
-          logger.warn('PouchDataLayerProvider: No logged-in username found in session.');
+          logger.warn('CouchDataLayerProvider: No logged-in username found in session.');
         }
       } catch (error) {
         logger.error(
-          'PouchDataLayerProvider: Error during user session check or user DB initialization:',
+          'CouchDataLayerProvider: Error during user session check or user DB initialization:',
           error
         );
       }

package/src/impl/{pouch → couch}/adminDB.ts

@@ -1,5 +1,5 @@
 import pouch from './pouchdb-setup';
-import { ENV } from '@/factory';
+import { ENV } from '@db/factory';
 import {
   pouchDBincludeCredentialsConfig,
   getStartAndEndKeys,
@@ -9,9 +9,9 @@ import {
 import { TeacherClassroomDB, ClassroomLookupDB } from './classroomDB';
 import { PouchError } from './types';
 
-import { AdminDBInterface } from '@/core';
+import { AdminDBInterface } from '@db/core';
 import CourseLookup from './courseLookupDB';
-import { logger } from '@/util/logger';
+import { logger } from '@db/util/logger';
 
 export class AdminDB implements AdminDBInterface {
   private usersDB!: PouchDB.Database;

package/src/impl/{pouch → couch}/auth.ts

@@ -1,6 +1,6 @@
-import { ENV } from '@/factory';
+import { ENV } from '@db/factory';
 import { GuestUsername } from '../../core/types/types-legacy';
-import { logger } from '@/util/logger';
+import { logger } from '@db/util/logger';
 
 interface SessionResponse {
   info: unknown;

package/src/impl/{pouch → couch}/classroomDB.ts

@@ -2,10 +2,10 @@ import {
   StudyContentSource,
   StudySessionNewItem,
   StudySessionReviewItem,
-} from '@/core/interfaces/contentSource';
+} from '@db/core/interfaces/contentSource';
 import { ClassroomConfig } from '@vue-skuilder/common';
-import { ENV } from '@/factory';
-import { logger } from '@/util/logger';
+import { ENV } from '@db/factory';
+import { logger } from '@db/util/logger';
 import moment from 'moment';
 import pouch from './pouchdb-setup';
 import {
@@ -16,15 +16,15 @@ import {
 } from '.';
 import { CourseDB, getTag } from './courseDB';
 
-import { UserDBInterface } from '@/core';
+import { UserDBInterface } from '@db/core';
 import {
   AssignedContent,
   AssignedCourse,
   AssignedTag,
   StudentClassroomDBInterface,
   TeacherClassroomDBInterface,
-} from '@/core/interfaces/classroomDB';
-import { ScheduledCard } from '@/core/types/user';
+} from '@db/core/interfaces/classroomDB';
+import { ScheduledCard } from '@db/core/types/user';
 
 const classroomLookupDBTitle = 'classdb-lookup';
 export const CLASSROOM_CONFIG = 'ClassroomConfig';