@vue-skuilder/db 0.1.18 → 0.1.21

package/dist/core/index.d.ts

@@ -1,8 +1,8 @@
-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 { W as WeightedCard, U as UserDBInterface, C as CourseDBInterface } from '../contentSource-BP9hznNV.js';
+export { J as ActivityRecord, A as AdminDBInterface, v as AssignedCard, g as AssignedContent, u as AssignedCourse, t as AssignedTag, c as ClassroomDBInterface, F as ClassroomRegistration, E as ClassroomRegistrationDesignation, G as ClassroomRegistrationDoc, f 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, j as ScheduledCard, H as SessionTrackingData, L as StrategyContribution, i as StudentClassroomDBInterface, h as StudyContentSource, k as StudySessionFailedItem, l as StudySessionFailedNewItem, m as StudySessionFailedReviewItem, S as StudySessionItem, n as StudySessionNewItem, o 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 '../contentSource-BP9hznNV.js';
+export { D as DataLayerProvider } from '../dataLayerProvider-MDTxXq2l.js';
+import { b as DocTypePrefixes, D as DocType, C as CardHistory, c as CardRecord, i as QuestionRecord } from '../types-legacy-DDY4N-Uq.js';
+export { d as CardData, e as CourseListData, g as DataShapeData, f as DisplayableData, 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-DDY4N-Uq.js';
 import { DataShape, ParsedCard } from '@vue-skuilder/common';
 import 'moment';
 
@@ -169,6 +169,80 @@ interface CardGenerator {
  */
 type CardGeneratorFactory<TConfig = unknown> = (config: TConfig) => CardGenerator;
 
+/**
+ * Template literal type for strategy state document IDs.
+ *
+ * Format: `STRATEGY_STATE-{courseId}-{strategyKey}`
+ */
+type StrategyStateId = `${(typeof DocTypePrefixes)[DocType.STRATEGY_STATE]}::${string}::${string}`;
+/**
+ * Document storing strategy-specific state in the user database.
+ *
+ * Each strategy can persist its own state (user preferences, learned patterns,
+ * temporal tracking, etc.) using this document type. The state is scoped to
+ * a (user, course, strategy) tuple.
+ *
+ * ## Use Cases
+ *
+ * 1. **Explicit user preferences**: User configures tag filters, difficulty
+ *    preferences, or learning goals. UI writes to strategy state.
+ *
+ * 2. **Learned/temporal state**: Strategy tracks patterns over time, e.g.,
+ *    "when did I last introduce confusable concepts together?"
+ *
+ * 3. **Adaptive personalization**: Strategy infers user preferences from
+ *    behavior and stores them for future sessions.
+ *
+ * ## Storage Location
+ *
+ * These documents live in the **user database**, not the course database.
+ * They sync with the user's data across devices.
+ *
+ * ## Document ID Format
+ *
+ * `STRATEGY_STATE::{courseId}::{strategyKey}`
+ *
+ * Example: `STRATEGY_STATE::piano-basics::UserTagPreferenceFilter`
+ *
+ * @template T - The shape of the strategy-specific data payload
+ */
+interface StrategyStateDoc<T = unknown> {
+    _id: StrategyStateId;
+    _rev?: string;
+    docType: DocType.STRATEGY_STATE;
+    /**
+     * The course this state applies to.
+     */
+    courseId: string;
+    /**
+     * Unique key identifying the strategy instance.
+     * Typically the strategy class name (e.g., "UserTagPreferenceFilter",
+     * "InterferenceMitigatorNavigator").
+     *
+     * If a course has multiple instances of the same strategy type with
+     * different configurations, use a more specific key.
+     */
+    strategyKey: string;
+    /**
+     * Strategy-specific data payload.
+     * Each strategy defines its own schema for this field.
+     */
+    data: T;
+    /**
+     * ISO timestamp of last update.
+     * Use `moment.utc(updatedAt)` to parse into a Moment object.
+     */
+    updatedAt: string;
+}
+/**
+ * Build the document ID for a strategy state document.
+ *
+ * @param courseId - The course ID
+ * @param strategyKey - The strategy key (typically class name)
+ * @returns The document ID in format `STRATEGY_STATE::{courseId}::{strategyKey}`
+ */
+declare function buildStrategyStateId(courseId: string, strategyKey: string): StrategyStateId;
+
 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;
@@ -227,4 +301,4 @@ declare function validateProcessorConfig(config: Partial<BulkCardProcessorConfig
     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 };
+export { type BulkCardProcessorConfig, type CardFilter, type CardFilterFactory, type CardGenerator, type CardGeneratorFactory, CardHistory, CardRecord, CourseDBInterface, DocType, DocTypePrefixes, type FilterContext, type GeneratorContext, type ImportResult, Loggable, QuestionRecord, type StrategyStateDoc, type StrategyStateId, UserDBInterface, WeightedCard, areQuestionRecords, buildStrategyStateId, docIsDeleted, getCardHistoryID, importParsedCards, isQuestionRecord, parseCardHistoryID, validateProcessorConfig };