@vue-skuilder/db 0.1.16 → 0.1.18

package/dist/core/index.d.cts

@@ -0,0 +1,230 @@
+import { W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } 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, d as CourseInfo, K as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, O as NavigatorRole, P as NavigatorRoles, N as Navigators, g as ScheduledCard, H as SessionTrackingData, L as StrategyContribution, j as StudentClassroomDBInterface, i as StudyContentSource, m as StudySessionFailedItem, n as StudySessionFailedNewItem, o as StudySessionFailedReviewItem, l as StudySessionItem, S as StudySessionNewItem, f as StudySessionReviewItem, 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 } from '../classroomDB-CTOenngH.cjs';
+export { D as DataLayerProvider } from '../dataLayerProvider-D6PoCwS6.cjs';
+import { C as CardHistory, c as CardRecord, i as QuestionRecord } 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, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-6ettoclI.cjs';
+import { DataShape, ParsedCard } from '@vue-skuilder/common';
+import 'moment';
+
+declare abstract class Loggable {
+    protected abstract readonly _className: string;
+    protected log(...args: unknown[]): void;
+    protected error(...args: unknown[]): void;
+}
+
+/**
+ * Shared context available to all filters in a pipeline.
+ *
+ * Built once per getWeightedCards() call and passed to each filter.
+ * This avoids repeated lookups for common data like user ELO.
+ */
+interface FilterContext {
+    /** User database interface */
+    user: UserDBInterface;
+    /** Course database interface */
+    course: CourseDBInterface;
+    /** User's global ELO score for this course */
+    userElo: number;
+}
+/**
+ * A filter that transforms a list of weighted cards.
+ *
+ * Filters are pure transforms - they receive cards and context,
+ * and return a modified list of cards. No delegate wrapping,
+ * no side effects beyond provenance tracking.
+ *
+ * ## Implementation Guidelines
+ *
+ * 1. **Append provenance**: Every filter should add a StrategyContribution
+ *    entry documenting its decision for each card.
+ *
+ * 2. **Use multipliers**: Adjust scores by multiplying, not replacing.
+ *    This ensures filter order doesn't matter.
+ *
+ * 3. **Score 0 for exclusion**: To exclude a card, set score to 0.
+ *    Don't filter it out - let provenance show why it was excluded.
+ *
+ * 4. **Don't sort**: The Pipeline handles final sorting.
+ *    Filters just transform scores.
+ *
+ * ## Example Implementation
+ *
+ * ```typescript
+ * const myFilter: CardFilter = {
+ *   name: 'My Filter',
+ *   async transform(cards, context) {
+ *     return cards.map(card => {
+ *       const multiplier = computeMultiplier(card, context);
+ *       const newScore = card.score * multiplier;
+ *       return {
+ *         ...card,
+ *         score: newScore,
+ *         provenance: [...card.provenance, {
+ *           strategy: 'myFilter',
+ *           strategyName: 'My Filter',
+ *           strategyId: 'MY_FILTER',
+ *           action: multiplier < 1 ? 'penalized' : 'passed',
+ *           score: newScore,
+ *           reason: 'Explanation of decision'
+ *         }]
+ *       };
+ *     });
+ *   }
+ * };
+ * ```
+ */
+interface CardFilter {
+    /** Human-readable name for this filter */
+    name: string;
+    /**
+     * Transform a list of weighted cards.
+     *
+     * @param cards - Cards to transform (already scored by generator)
+     * @param context - Shared context (user, course, userElo, etc.)
+     * @returns Transformed cards with updated scores and provenance
+     */
+    transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]>;
+}
+/**
+ * Factory function type for creating filters from configuration.
+ *
+ * Used by PipelineAssembler to instantiate filters from strategy documents.
+ */
+type CardFilterFactory<TConfig = unknown> = (config: TConfig) => CardFilter;
+
+/**
+ * Context available to generators when producing candidates.
+ *
+ * Built once per getWeightedCards() call by the Pipeline.
+ */
+interface GeneratorContext {
+    /** User database interface */
+    user: UserDBInterface;
+    /** Course database interface */
+    course: CourseDBInterface;
+    /** User's global ELO score for this course */
+    userElo: number;
+}
+/**
+ * A generator that produces candidate cards with initial scores.
+ *
+ * Generators are the "source" stage of a navigation pipeline.
+ * They query the database for eligible cards and assign initial
+ * suitability scores based on their strategy (ELO proximity,
+ * review urgency, fixed order, etc.).
+ *
+ * ## Implementation Guidelines
+ *
+ * 1. **Create provenance**: Each card should have a provenance entry
+ *    with action='generated' documenting why it was selected.
+ *
+ * 2. **Score semantics**: Higher scores = more suitable for presentation.
+ *    Scores should be in [0, 1] range for composability.
+ *
+ * 3. **Limit handling**: Respect the limit parameter, but may over-fetch
+ *    internally if needed for scoring accuracy.
+ *
+ * 4. **Sort before returning**: Return cards sorted by score descending.
+ *
+ * ## Example Implementation
+ *
+ * ```typescript
+ * const myGenerator: CardGenerator = {
+ *   name: 'My Generator',
+ *   async getWeightedCards(limit, context) {
+ *     const candidates = await fetchCandidates(context.course, limit);
+ *     return candidates.map(c => ({
+ *       cardId: c.id,
+ *       courseId: context.course.getCourseID(),
+ *       score: computeScore(c, context),
+ *       provenance: [{
+ *         strategy: 'myGenerator',
+ *         strategyName: 'My Generator',
+ *         strategyId: 'MY_GENERATOR',
+ *         action: 'generated',
+ *         score: computeScore(c, context),
+ *         reason: 'Explanation of selection'
+ *       }]
+ *     }));
+ *   }
+ * };
+ * ```
+ */
+interface CardGenerator {
+    /** Human-readable name for this generator */
+    name: string;
+    /**
+     * Produce candidate cards with initial scores.
+     *
+     * @param limit - Maximum number of cards to return
+     * @param context - Shared context (user, course, userElo, etc.)
+     * @returns Cards sorted by score descending, with provenance
+     */
+    getWeightedCards(limit: number, context: GeneratorContext): Promise<WeightedCard[]>;
+}
+/**
+ * Factory function type for creating generators from configuration.
+ *
+ * Used by PipelineAssembler to instantiate generators from strategy documents.
+ */
+type CardGeneratorFactory<TConfig = unknown> = (config: TConfig) => CardGenerator;
+
+declare function areQuestionRecords(h: CardHistory<CardRecord>): h is CardHistory<QuestionRecord>;
+declare function isQuestionRecord(c: CardRecord): c is QuestionRecord;
+declare function getCardHistoryID(courseID: string, cardID: string): PouchDB.Core.DocumentId;
+declare function parseCardHistoryID(id: string): {
+    courseID: string;
+    cardID: string;
+};
+interface PouchDBError extends Error {
+    error?: string;
+    reason?: string;
+}
+declare function docIsDeleted(e: PouchDBError): boolean;
+
+/**
+ * Interface representing the result of a bulk import operation for a single card
+ */
+interface ImportResult {
+    /** The original text input for the card */
+    originalText: string;
+    /** Status of the import operation */
+    status: 'success' | 'error';
+    /** Message describing the result or error */
+    message: string;
+    /** ID of the newly created card (only for success) */
+    cardId?: string;
+}
+/**
+ * Configuration for the bulk card processor
+ */
+interface BulkCardProcessorConfig {
+    /** The data shape to use for the cards */
+    dataShape: DataShape;
+    /** The course code used for adding notes */
+    courseCode: string;
+    /** The username of the current user */
+    userName: string;
+}
+
+/**
+ * Processes multiple cards from bulk text input
+ *
+ * @param parsedCards - Array of parsed cards to import
+ * @param courseDB - Course database interface
+ * @param config - Configuration for the card processor
+ * @returns Array of import results
+ */
+declare function importParsedCards(parsedCards: ParsedCard[], courseDB: CourseDBInterface, config: BulkCardProcessorConfig): Promise<ImportResult[]>;
+/**
+ * Validates the configuration for bulk card processing
+ *
+ * @param config - Configuration to validate
+ * @returns Object with validation result and error message if any
+ */
+declare function validateProcessorConfig(config: Partial<BulkCardProcessorConfig>): {
+    isValid: boolean;
+    errorMessage?: string;
+};
+
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, type FilterContext, type GeneratorContext, type ImportResult, Loggable, QuestionRecord, UserDBInterface, WeightedCard, areQuestionRecords, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig };

package/dist/core/index.d.ts

@@ -1,6 +1,6 @@
-import { i as StudyContentSource, U as UserDBInterface, C as CourseDBInterface, e as ContentNavigationStrategyData, f as StudySessionReviewItem, g as ScheduledCard, S as StudySessionNewItem } 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, d as CourseInfo, J as CourseRegistration, r as CourseRegistrationDoc, b as CoursesDBInterface, G as SessionTrackingData, j as StudentClassroomDBInterface, l as StudySessionFailedItem, m as StudySessionFailedNewItem, n as StudySessionFailedReviewItem, k as StudySessionItem, 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 } from '../userDB-DNa0XPtn.js';
-export { D as DataLayerProvider } from '../dataLayerProvider-BV5iZqt_.js';
+import { W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } 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, d as CourseInfo, K as CourseRegistration, s as CourseRegistrationDoc, b as CoursesDBInterface, O as NavigatorRole, P as NavigatorRoles, N as Navigators, g as ScheduledCard, H as SessionTrackingData, L as StrategyContribution, j as StudentClassroomDBInterface, i as StudyContentSource, m as StudySessionFailedItem, n as StudySessionFailedNewItem, o as StudySessionFailedReviewItem, l as StudySessionItem, S as StudySessionNewItem, f as StudySessionReviewItem, 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 } from '../classroomDB-BgfrVb8d.js';
+export { D as DataLayerProvider } from '../dataLayerProvider-CZxC9GtB.js';
 import { C as CardHistory, c as CardRecord, i as QuestionRecord } 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, S as SkuilderCourseData, a as Tag, T as TagStub, l as log } from '../types-legacy-6ettoclI.js';
 import { DataShape, ParsedCard } from '@vue-skuilder/common';
@@ -12,6 +12,163 @@ declare abstract class Loggable {
     protected error(...args: unknown[]): void;
 }
 
+/**
+ * Shared context available to all filters in a pipeline.
+ *
+ * Built once per getWeightedCards() call and passed to each filter.
+ * This avoids repeated lookups for common data like user ELO.
+ */
+interface FilterContext {
+    /** User database interface */
+    user: UserDBInterface;
+    /** Course database interface */
+    course: CourseDBInterface;
+    /** User's global ELO score for this course */
+    userElo: number;
+}
+/**
+ * A filter that transforms a list of weighted cards.
+ *
+ * Filters are pure transforms - they receive cards and context,
+ * and return a modified list of cards. No delegate wrapping,
+ * no side effects beyond provenance tracking.
+ *
+ * ## Implementation Guidelines
+ *
+ * 1. **Append provenance**: Every filter should add a StrategyContribution
+ *    entry documenting its decision for each card.
+ *
+ * 2. **Use multipliers**: Adjust scores by multiplying, not replacing.
+ *    This ensures filter order doesn't matter.
+ *
+ * 3. **Score 0 for exclusion**: To exclude a card, set score to 0.
+ *    Don't filter it out - let provenance show why it was excluded.
+ *
+ * 4. **Don't sort**: The Pipeline handles final sorting.
+ *    Filters just transform scores.
+ *
+ * ## Example Implementation
+ *
+ * ```typescript
+ * const myFilter: CardFilter = {
+ *   name: 'My Filter',
+ *   async transform(cards, context) {
+ *     return cards.map(card => {
+ *       const multiplier = computeMultiplier(card, context);
+ *       const newScore = card.score * multiplier;
+ *       return {
+ *         ...card,
+ *         score: newScore,
+ *         provenance: [...card.provenance, {
+ *           strategy: 'myFilter',
+ *           strategyName: 'My Filter',
+ *           strategyId: 'MY_FILTER',
+ *           action: multiplier < 1 ? 'penalized' : 'passed',
+ *           score: newScore,
+ *           reason: 'Explanation of decision'
+ *         }]
+ *       };
+ *     });
+ *   }
+ * };
+ * ```
+ */
+interface CardFilter {
+    /** Human-readable name for this filter */
+    name: string;
+    /**
+     * Transform a list of weighted cards.
+     *
+     * @param cards - Cards to transform (already scored by generator)
+     * @param context - Shared context (user, course, userElo, etc.)
+     * @returns Transformed cards with updated scores and provenance
+     */
+    transform(cards: WeightedCard[], context: FilterContext): Promise<WeightedCard[]>;
+}
+/**
+ * Factory function type for creating filters from configuration.
+ *
+ * Used by PipelineAssembler to instantiate filters from strategy documents.
+ */
+type CardFilterFactory<TConfig = unknown> = (config: TConfig) => CardFilter;
+
+/**
+ * Context available to generators when producing candidates.
+ *
+ * Built once per getWeightedCards() call by the Pipeline.
+ */
+interface GeneratorContext {
+    /** User database interface */
+    user: UserDBInterface;
+    /** Course database interface */
+    course: CourseDBInterface;
+    /** User's global ELO score for this course */
+    userElo: number;
+}
+/**
+ * A generator that produces candidate cards with initial scores.
+ *
+ * Generators are the "source" stage of a navigation pipeline.
+ * They query the database for eligible cards and assign initial
+ * suitability scores based on their strategy (ELO proximity,
+ * review urgency, fixed order, etc.).
+ *
+ * ## Implementation Guidelines
+ *
+ * 1. **Create provenance**: Each card should have a provenance entry
+ *    with action='generated' documenting why it was selected.
+ *
+ * 2. **Score semantics**: Higher scores = more suitable for presentation.
+ *    Scores should be in [0, 1] range for composability.
+ *
+ * 3. **Limit handling**: Respect the limit parameter, but may over-fetch
+ *    internally if needed for scoring accuracy.
+ *
+ * 4. **Sort before returning**: Return cards sorted by score descending.
+ *
+ * ## Example Implementation
+ *
+ * ```typescript
+ * const myGenerator: CardGenerator = {
+ *   name: 'My Generator',
+ *   async getWeightedCards(limit, context) {
+ *     const candidates = await fetchCandidates(context.course, limit);
+ *     return candidates.map(c => ({
+ *       cardId: c.id,
+ *       courseId: context.course.getCourseID(),
+ *       score: computeScore(c, context),
+ *       provenance: [{
+ *         strategy: 'myGenerator',
+ *         strategyName: 'My Generator',
+ *         strategyId: 'MY_GENERATOR',
+ *         action: 'generated',
+ *         score: computeScore(c, context),
+ *         reason: 'Explanation of selection'
+ *       }]
+ *     }));
+ *   }
+ * };
+ * ```
+ */
+interface CardGenerator {
+    /** Human-readable name for this generator */
+    name: string;
+    /**
+     * Produce candidate cards with initial scores.
+     *
+     * @param limit - Maximum number of cards to return
+     * @param context - Shared context (user, course, userElo, etc.)
+     * @returns Cards sorted by score descending, with provenance
+     */
+    getWeightedCards(limit: number, context: GeneratorContext): Promise<WeightedCard[]>;
+}
+/**
+ * Factory function type for creating generators from configuration.
+ *
+ * Used by PipelineAssembler to instantiate generators from strategy documents.
+ */
+type CardGeneratorFactory<TConfig = unknown> = (config: TConfig) => CardGenerator;
+
 declare function areQuestionRecords(h: CardHistory<CardRecord>): h is CardHistory<QuestionRecord>;
 declare function isQuestionRecord(c: CardRecord): c is QuestionRecord;
 declare function getCardHistoryID(courseID: string, cardID: string): PouchDB.Core.DocumentId;
@@ -25,25 +182,6 @@ interface PouchDBError extends Error {
 }
 declare function docIsDeleted(e: PouchDBError): boolean;
 
-declare enum Navigators {
-    ELO = "elo",
-    HARDCODED = "hardcodedOrder"
-}
-/**
- * A content-navigator provides runtime steering of study sessions.
- */
-declare abstract class ContentNavigator implements StudyContentSource {
-    /**
-     *
-     * @param user
-     * @param strategyData
-     * @returns the runtime object used to steer a study session.
-     */
-    static create(user: UserDBInterface, course: CourseDBInterface, strategyData: ContentNavigationStrategyData): Promise<ContentNavigator>;
-    abstract getPendingReviews(): Promise<(StudySessionReviewItem & ScheduledCard)[]>;
-    abstract getNewCards(n?: number): Promise<StudySessionNewItem[]>;
-}
-
 /**
  * Interface representing the result of a bulk import operation for a single card
  */
@@ -89,4 +227,4 @@ declare function validateProcessorConfig(config: Partial<BulkCardProcessorConfig
     errorMessage?: string;
 };
 
-export { type BulkCardProcessorConfig, CardHistory, CardRecord, ContentNavigator, CourseDBInterface, type ImportResult, Loggable, Navigators, QuestionRecord, ScheduledCard, StudyContentSource, StudySessionNewItem, StudySessionReviewItem, UserDBInterface, areQuestionRecords, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, type FilterContext, type GeneratorContext, type ImportResult, Loggable, QuestionRecord, UserDBInterface, WeightedCard, areQuestionRecords, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig };