@vue-skuilder/db 0.1.16 → 0.1.18

package/dist/{index-Bmll7Xse.d.mts → index-D-Fa4Smt.d.cts}

@@ -1,4 +1,4 @@
-import { P as PackerConfig, a as PackedCourseData, S as StaticCourseManifest } from './types-Dbp5DaRR.mjs';
+import { P as PackerConfig, a as PackedCourseData, S as StaticCourseManifest } from './types-CzPDLAK6.cjs';
 
 /**
  * Abstraction for file system operations needed by the migrator.

package/dist/{index.d.mts → index.d.cts}

@@ -1,15 +1,15 @@
-import { U as UserDBInterface, r as CourseRegistrationDoc, k as StudySessionItem, i as StudyContentSource } from './userDB-BqwxtJ_7.mjs';
-export { I as ActivityRecord, A as AdminDBInterface, u as AssignedCard, h as AssignedContent, t as AssignedCourse, s as AssignedTag, c as ClassroomDBInterface, E as ClassroomRegistration, B as ClassroomRegistrationDesignation, F as ClassroomRegistrationDoc, p as ContentSourceID, C as CourseDBInterface, d as CourseInfo, J as CourseRegistration, b as CoursesDBInterface, K as DocumentUpdater, g as ScheduledCard, G as SessionTrackingData, j as StudentClassroomDBInterface, l as StudySessionFailedItem, m as StudySessionFailedNewItem, n as StudySessionFailedReviewItem, S as StudySessionNewItem, f as StudySessionReviewItem, T as TeacherClassroomDBInterface, H as UserConfig, y as UserCourseSetting, x as UserCourseSettings, w as UserDBAuthenticator, a as UserDBReader, v as UserDBWriter, z as UsrCrsDataInterface, q as getStudySource, o as isReview, L as newInterval } from './userDB-BqwxtJ_7.mjs';
-import { D as DataLayerProvider } from './dataLayerProvider-VlngD19_.mjs';
-import { C as CardHistory, c as CardRecord } from './types-legacy-6ettoclI.mjs';
-export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, i as QuestionRecord, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-6ettoclI.mjs';
-import { Loggable } from './core/index.mjs';
-export { BulkCardProcessorConfig, ContentNavigator, ImportResult, Navigators, areQuestionRecords, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig } from './core/index.mjs';
-import { S as StaticCourseManifest } from './types-Dbp5DaRR.mjs';
-export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-Dbp5DaRR.mjs';
-import { F as FileSystemAdapter } from './index-Bmll7Xse.mjs';
-export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-Bmll7Xse.mjs';
-import '@vue-skuilder/common';
+import { U as UserDBInterface, s as CourseRegistrationDoc, l as StudySessionItem, i as StudyContentSource, S as StudySessionNewItem, f as StudySessionReviewItem, g as ScheduledCard, W as WeightedCard } from './classroomDB-CTOenngH.cjs';
+export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, h as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, k as ContentNavigator, q as ContentSourceID, C as CourseDBInterface, d as CourseInfo, K as CourseRegistration, b as CoursesDBInterface, V as DocumentUpdater, O as NavigatorRole, P as NavigatorRoles, N as Navigators, H as SessionTrackingData, L as StrategyContribution, j as StudentClassroomDBInterface, m as StudySessionFailedItem, n as StudySessionFailedNewItem, o as StudySessionFailedReviewItem, T as TeacherClassroomDBInterface, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, M as getCardOrigin, r as getStudySource, R as isFilter, Q as isGenerator, p as isReview, X as newInterval } from './classroomDB-CTOenngH.cjs';
+import { D as DataLayerProvider } from './dataLayerProvider-D6PoCwS6.cjs';
+import { C as CardHistory, c as CardRecord } from './types-legacy-6ettoclI.cjs';
+export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, i as QuestionRecord, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-6ettoclI.cjs';
+import { Loggable } from './core/index.cjs';
+export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, CardGenerator, CardGeneratorFactory, FilterContext, GeneratorContext, ImportResult, areQuestionRecords, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig } from './core/index.cjs';
+import { TagFilter } from '@vue-skuilder/common';
+import { S as StaticCourseManifest } from './types-CzPDLAK6.cjs';
+export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-CzPDLAK6.cjs';
+import { F as FileSystemAdapter } from './index-D-Fa4Smt.cjs';
+export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-D-Fa4Smt.cjs';
 import 'moment';
 
 /**
@@ -336,6 +336,10 @@ declare class SessionController<TView = unknown> extends Loggable {
      * Used by SessionControllerDebug component for runtime inspection.
      */
     getDebugInfo(): {
+        api: {
+            mode: string;
+            description: string;
+        };
         reviewQueue: {
             length: number;
             dequeueCount: number;
@@ -369,7 +373,29 @@ declare class SessionController<TView = unknown> extends Loggable {
             items: any[];
         };
     };
+    /**
+     * Fetch content using the new getWeightedCards API.
+     *
+     * This method uses getWeightedCards() to get scored candidates, then uses the
+     * scores to determine ordering. For reviews, we still need the full ScheduledCard
+     * data from getPendingReviews(), so we fetch both and use scores for ordering.
+     *
+     * The hybrid approach:
+     * 1. Fetch weighted cards to get scoring/ordering information
+     * 2. Fetch full review data via legacy getPendingReviews()
+     * 3. Order reviews by their weighted scores
+     * 4. Add new cards ordered by their weighted scores
+     */
+    private getWeightedContent;
+    /**
+     * @deprecated Use getWeightedContent() instead. This method is kept for backward
+     * compatibility with sources that don't support getWeightedCards().
+     */
     private getScheduledReviews;
+    /**
+     * @deprecated Use getWeightedContent() instead. This method is kept for backward
+     * compatibility with sources that don't support getWeightedCards().
+     */
     private getNewCards;
     private _selectNextItemToHydrate;
     nextCard(action?: SessionAction): Promise<HydratedCard<TView> | null>;
@@ -395,6 +421,64 @@ declare class SessionController<TView = unknown> extends Loggable {
     private removeItemFromQueue;
 }
 
+/**
+ * A StudyContentSource that filters cards based on tag inclusion/exclusion.
+ *
+ * This enables ephemeral, tag-scoped study sessions where users can focus
+ * on specific topics within a course without permanent configuration.
+ *
+ * Filter logic:
+ * - If `include` is non-empty: card must have at least one of the included tags
+ * - If `exclude` is non-empty: card must not have any of the excluded tags
+ * - Both filters are applied (include first, then exclude)
+ */
+declare class TagFilteredContentSource implements StudyContentSource {
+    private courseId;
+    private filter;
+    private user;
+    private resolvedCardIds;
+    constructor(courseId: string, filter: TagFilter, user: UserDBInterface);
+    /**
+     * Resolves the TagFilter to a set of eligible card IDs.
+     *
+     * - Cards in `include` tags are OR'd together (card needs at least one)
+     * - Cards in `exclude` tags are removed from the result
+     */
+    private resolveFilteredCardIds;
+    /**
+     * Gets new cards that match the tag filter and are not already active for the user.
+     */
+    getNewCards(limit?: number): Promise<StudySessionNewItem[]>;
+    /**
+     * Gets pending reviews, filtered to only include cards that match the tag filter.
+     */
+    getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
+    /**
+     * Get cards with suitability scores for presentation.
+     *
+     * This implementation wraps the legacy getNewCards/getPendingReviews methods,
+     * assigning score=1.0 to all cards. TagFilteredContentSource does not currently
+     * support pluggable navigation strategies - it returns flat-scored candidates.
+     *
+     * @param limit - Maximum number of cards to return
+     * @returns Cards sorted by score descending (all scores = 1.0)
+     */
+    getWeightedCards(limit: number): Promise<WeightedCard[]>;
+    /**
+     * Clears the cached resolved card IDs.
+     * Call this if the underlying tag data may have changed during a session.
+     */
+    clearCache(): void;
+    /**
+     * Returns the course ID this source is filtering.
+     */
+    getCourseId(): string;
+    /**
+     * Returns the active tag filter.
+     */
+    getFilter(): TagFilter;
+}
+
 interface CourseLookupDoc {
     _id: string;
     _rev: string;
@@ -493,4 +577,4 @@ interface CouchDbUserDoc extends PouchDB.Authentication.User {
     entitlements: UserEntitlements;
 }
 
-export { type AggregatedDocument, type AttachmentUploadResult, CardHistory, CardRecord, type CouchDbUserDoc, CourseLookup, CourseRegistrationDoc, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, Loggable, type MigrationOptions, type MigrationResult, NOT_SET, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, _resetDataLayer, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, getLogFilePath, initializeDataDirectory, initializeDataLayer, initializeTuiLogging, logger, showUserError, showUserMessage, validateMigration, validateStaticCourse };
+export { type AggregatedDocument, type AttachmentUploadResult, CardHistory, CardRecord, type CouchDbUserDoc, CourseLookup, CourseRegistrationDoc, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, Loggable, type MigrationOptions, type MigrationResult, NOT_SET, type ResponseResult, type RestoreProgress, ScheduledCard, type SessionAction, SessionController, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, StudySessionNewItem, type StudySessionRecord, StudySessionReviewItem, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, getLogFilePath, initializeDataDirectory, initializeDataLayer, initializeTuiLogging, logger, showUserError, showUserMessage, validateMigration, validateStaticCourse };

package/dist/index.d.ts

@@ -1,15 +1,15 @@
-import { U as UserDBInterface, r as CourseRegistrationDoc, k as StudySessionItem, i as StudyContentSource } from './userDB-DNa0XPtn.js';
-export { I as ActivityRecord, A as AdminDBInterface, u as AssignedCard, h as AssignedContent, t as AssignedCourse, s as AssignedTag, c as ClassroomDBInterface, E as ClassroomRegistration, B as ClassroomRegistrationDesignation, F as ClassroomRegistrationDoc, p as ContentSourceID, C as CourseDBInterface, d as CourseInfo, J as CourseRegistration, b as CoursesDBInterface, K as DocumentUpdater, g as ScheduledCard, G as SessionTrackingData, j as StudentClassroomDBInterface, l as StudySessionFailedItem, m as StudySessionFailedNewItem, n as StudySessionFailedReviewItem, S as StudySessionNewItem, f as StudySessionReviewItem, T as TeacherClassroomDBInterface, H as UserConfig, y as UserCourseSetting, x as UserCourseSettings, w as UserDBAuthenticator, a as UserDBReader, v as UserDBWriter, z as UsrCrsDataInterface, q as getStudySource, o as isReview, L as newInterval } from './userDB-DNa0XPtn.js';
-import { D as DataLayerProvider } from './dataLayerProvider-BV5iZqt_.js';
+import { U as UserDBInterface, s as CourseRegistrationDoc, l as StudySessionItem, i as StudyContentSource, S as StudySessionNewItem, f as StudySessionReviewItem, g as ScheduledCard, W as WeightedCard } from './classroomDB-BgfrVb8d.js';
+export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, h as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, k as ContentNavigator, q as ContentSourceID, C as CourseDBInterface, d as CourseInfo, K as CourseRegistration, b as CoursesDBInterface, V as DocumentUpdater, O as NavigatorRole, P as NavigatorRoles, N as Navigators, H as SessionTrackingData, L as StrategyContribution, j as StudentClassroomDBInterface, m as StudySessionFailedItem, n as StudySessionFailedNewItem, o as StudySessionFailedReviewItem, T as TeacherClassroomDBInterface, I as UserConfig, z as UserCourseSetting, y as UserCourseSettings, x as UserDBAuthenticator, a as UserDBReader, w as UserDBWriter, B as UsrCrsDataInterface, M as getCardOrigin, r as getStudySource, R as isFilter, Q as isGenerator, p as isReview, X as newInterval } from './classroomDB-BgfrVb8d.js';
+import { D as DataLayerProvider } from './dataLayerProvider-CZxC9GtB.js';
 import { C as CardHistory, c as CardRecord } from './types-legacy-6ettoclI.js';
 export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, D as DocType, b as DocTypePrefixes, F as Field, G as GuestUsername, Q as QualifiedCardID, h as QuestionData, i as QuestionRecord, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from './types-legacy-6ettoclI.js';
 import { Loggable } from './core/index.js';
-export { BulkCardProcessorConfig, ContentNavigator, ImportResult, Navigators, areQuestionRecords, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig } from './core/index.js';
+export { BulkCardProcessorConfig, CardFilter, CardFilterFactory, CardGenerator, CardGeneratorFactory, FilterContext, GeneratorContext, ImportResult, areQuestionRecords, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig } from './core/index.js';
+import { TagFilter } from '@vue-skuilder/common';
 import { S as StaticCourseManifest } from './types-CewsN87z.js';
 export { A as AttachmentData, C as ChunkMetadata, D as DesignDocument, I as IndexMetadata, a as PackedCourseData, P as PackerConfig } from './types-CewsN87z.js';
 import { F as FileSystemAdapter } from './index-CD8BZz2k.js';
 export { C as CouchDBToStaticPacker, a as FileStats, b as FileSystemError } from './index-CD8BZz2k.js';
-import '@vue-skuilder/common';
 import 'moment';
 
 /**
@@ -336,6 +336,10 @@ declare class SessionController<TView = unknown> extends Loggable {
      * Used by SessionControllerDebug component for runtime inspection.
      */
     getDebugInfo(): {
+        api: {
+            mode: string;
+            description: string;
+        };
         reviewQueue: {
             length: number;
             dequeueCount: number;
@@ -369,7 +373,29 @@ declare class SessionController<TView = unknown> extends Loggable {
             items: any[];
         };
     };
+    /**
+     * Fetch content using the new getWeightedCards API.
+     *
+     * This method uses getWeightedCards() to get scored candidates, then uses the
+     * scores to determine ordering. For reviews, we still need the full ScheduledCard
+     * data from getPendingReviews(), so we fetch both and use scores for ordering.
+     *
+     * The hybrid approach:
+     * 1. Fetch weighted cards to get scoring/ordering information
+     * 2. Fetch full review data via legacy getPendingReviews()
+     * 3. Order reviews by their weighted scores
+     * 4. Add new cards ordered by their weighted scores
+     */
+    private getWeightedContent;
+    /**
+     * @deprecated Use getWeightedContent() instead. This method is kept for backward
+     * compatibility with sources that don't support getWeightedCards().
+     */
     private getScheduledReviews;
+    /**
+     * @deprecated Use getWeightedContent() instead. This method is kept for backward
+     * compatibility with sources that don't support getWeightedCards().
+     */
     private getNewCards;
     private _selectNextItemToHydrate;
     nextCard(action?: SessionAction): Promise<HydratedCard<TView> | null>;
@@ -395,6 +421,64 @@ declare class SessionController<TView = unknown> extends Loggable {
     private removeItemFromQueue;
 }
 
+/**
+ * A StudyContentSource that filters cards based on tag inclusion/exclusion.
+ *
+ * This enables ephemeral, tag-scoped study sessions where users can focus
+ * on specific topics within a course without permanent configuration.
+ *
+ * Filter logic:
+ * - If `include` is non-empty: card must have at least one of the included tags
+ * - If `exclude` is non-empty: card must not have any of the excluded tags
+ * - Both filters are applied (include first, then exclude)
+ */
+declare class TagFilteredContentSource implements StudyContentSource {
+    private courseId;
+    private filter;
+    private user;
+    private resolvedCardIds;
+    constructor(courseId: string, filter: TagFilter, user: UserDBInterface);
+    /**
+     * Resolves the TagFilter to a set of eligible card IDs.
+     *
+     * - Cards in `include` tags are OR'd together (card needs at least one)
+     * - Cards in `exclude` tags are removed from the result
+     */
+    private resolveFilteredCardIds;
+    /**
+     * Gets new cards that match the tag filter and are not already active for the user.
+     */
+    getNewCards(limit?: number): Promise<StudySessionNewItem[]>;
+    /**
+     * Gets pending reviews, filtered to only include cards that match the tag filter.
+     */
+    getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
+    /**
+     * Get cards with suitability scores for presentation.
+     *
+     * This implementation wraps the legacy getNewCards/getPendingReviews methods,
+     * assigning score=1.0 to all cards. TagFilteredContentSource does not currently
+     * support pluggable navigation strategies - it returns flat-scored candidates.
+     *
+     * @param limit - Maximum number of cards to return
+     * @returns Cards sorted by score descending (all scores = 1.0)
+     */
+    getWeightedCards(limit: number): Promise<WeightedCard[]>;
+    /**
+     * Clears the cached resolved card IDs.
+     * Call this if the underlying tag data may have changed during a session.
+     */
+    clearCache(): void;
+    /**
+     * Returns the course ID this source is filtering.
+     */
+    getCourseId(): string;
+    /**
+     * Returns the active tag filter.
+     */
+    getFilter(): TagFilter;
+}
+
 interface CourseLookupDoc {
     _id: string;
     _rev: string;
@@ -493,4 +577,4 @@ interface CouchDbUserDoc extends PouchDB.Authentication.User {
     entitlements: UserEntitlements;
 }
 
-export { type AggregatedDocument, type AttachmentUploadResult, CardHistory, CardRecord, type CouchDbUserDoc, CourseLookup, CourseRegistrationDoc, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, Loggable, type MigrationOptions, type MigrationResult, NOT_SET, type ResponseResult, type RestoreProgress, type SessionAction, SessionController, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, type StudySessionRecord, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, _resetDataLayer, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, getLogFilePath, initializeDataDirectory, initializeDataLayer, initializeTuiLogging, logger, showUserError, showUserMessage, validateMigration, validateStaticCourse };
+export { type AggregatedDocument, type AttachmentUploadResult, CardHistory, CardRecord, type CouchDbUserDoc, CourseLookup, CourseRegistrationDoc, DEFAULT_MIGRATION_OPTIONS, type DataLayerConfig, DataLayerProvider, type DocumentCounts, ENV, type Entitlement, FileSystemAdapter, Loggable, type MigrationOptions, type MigrationResult, NOT_SET, type ResponseResult, type RestoreProgress, ScheduledCard, type SessionAction, SessionController, StaticCourseManifest, type StaticCourseValidation, StaticToCouchDBMigrator, StudyContentSource, StudySessionItem, StudySessionNewItem, type StudySessionRecord, StudySessionReviewItem, TagFilteredContentSource, type UserAccountStatus, UserDBInterface, type UserEntitlements, type ValidationIssue, type ValidationResult, WeightedCard, _resetDataLayer, ensureAppDataDirectory, getAppDataDirectory, getDataLayer, getDbPath, getLogFilePath, initializeDataDirectory, initializeDataLayer, initializeTuiLogging, logger, showUserError, showUserMessage, validateMigration, validateStaticCourse };