@pie-players/pie-players-shared 0.2.0

package/dist/types/index.d.ts

@@ -0,0 +1,761 @@
+/**
+ * This contains copies of the data types we use in PIEOneer. These types, unlike
+ * the ones in the datastore package, should not have any dependencies, and might in some
+ * cases be more shallow than their originals. The main reason for these is that they should
+ * be able to be used in front-end code (as well as the PIEOneer backend code).
+ *
+ * INCLUDING REFERENCES TO THE DATASTORE PACKAGE INSTEAD WILL MAKE PIEONEER THROW 500
+ * EVERYWHERE WITHOUT ANY FURTHER EXPLANATION
+ */
+export interface BaseEntity {
+    id?: string;
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+export interface CollectionEntity extends BaseEntity {
+    name: string;
+    organization: string | OrganizationEntity;
+}
+export interface OrganizationEntity extends BaseEntity {
+    name: string;
+    defaultCollection?: string | CollectionEntity;
+}
+export interface UserEntity extends BaseEntity {
+    email: string;
+    name?: string;
+}
+export interface ClientEntity extends BaseEntity {
+    name: string;
+    secret: string;
+    user: string | UserEntity;
+    organization: string | OrganizationEntity;
+}
+export interface AssignmentEntity extends BaseEntity {
+    organization: string | OrganizationEntity;
+}
+export interface SessionEntity extends BaseEntity {
+    item: ItemEntity;
+    assignment?: string | AssignmentEntity;
+    organization?: string | OrganizationEntity;
+}
+export declare enum SessionEventType {
+    SAVE = "save",
+    MODEL = "model",
+    SCORE = "score",
+    MANUAL_SCORE = "manual-score"
+}
+export declare enum ScoreType {
+    AUTO = "auto",
+    MANUAL = "manual"
+}
+export interface SessionScore {
+    points?: number;
+    max?: number;
+    type?: ScoreType;
+    partialScoring?: boolean;
+    message?: string;
+    errors?: string[];
+}
+export interface SessionAutoScore extends SessionScore {
+    elements?: any[];
+    extraProps?: any;
+}
+export interface SessionManualScore extends SessionScore {
+}
+export interface SessionEventEntity extends BaseEntity {
+    session: string | SessionEntity;
+    type?: SessionEventType;
+    saveEventId?: string;
+    score?: number;
+}
+export declare enum ModeType {
+    GATHER = "gather",
+    VIEW = "view",
+    EVALUATE = "evaluate"
+}
+export interface FlatSession {
+    id: string;
+    assignment: AssignmentEntity;
+    item: string;
+    data: any[];
+    createdAt: Date;
+    updatedAt: Date;
+    mode: ModeType;
+    autoScore: SessionAutoScore;
+    manualScore: SessionManualScore;
+    events: SessionEventEntity[];
+}
+export interface SemVerPrerelease {
+    tag: string;
+    version: number;
+}
+export interface SemVer {
+    major: number;
+    minor: number;
+    patch: number;
+    prerelease?: SemVerPrerelease;
+}
+export interface VersionEntity extends BaseEntity {
+    baseId: string;
+    signature?: string;
+    version: SemVer;
+}
+export interface SearchMetaData {
+    [key: string]: any;
+}
+export interface SearchMetaDataEntity extends BaseEntity {
+    searchMetaData?: SearchMetaData;
+}
+export interface ConfigElements {
+    [key: string]: string;
+}
+export interface PieModel {
+    id: string;
+    element: string;
+    [key: string]: any;
+}
+export interface ConfigEntity {
+    id?: string;
+    markup: string;
+    elements: ConfigElements;
+    models: PieModel[];
+    configuration?: Record<string, any>;
+    /**
+     * QTI 3.0: Extracted accessibility catalogs from embedded SSML.
+     * Automatically generated by SSMLExtractor when <speak> tags are found in content.
+     */
+    extractedCatalogs?: AccessibilityCatalog[];
+    [key: string]: any;
+}
+export interface ConfigContainerEntity extends BaseEntity {
+    config: ConfigEntity;
+}
+export interface PassageEntity extends VersionEntity, ConfigContainerEntity, SearchMetaDataEntity {
+    name: string;
+    retired?: boolean;
+    published?: boolean;
+    highlights?: Record<string, string[]>;
+}
+export interface ItemEntity extends VersionEntity, ConfigContainerEntity, SearchMetaDataEntity {
+    name?: string;
+    passage?: string | PassageEntity;
+    retired?: boolean;
+    published?: boolean;
+    configuration?: any;
+    highlights?: Record<string, string[]>;
+}
+export interface AssignmentSessionData {
+    assignment: AssignmentEntity;
+    sessions: FlatSession[];
+    items: ItemEntity[];
+    error?: string;
+}
+/**
+ * Metadata specifically for interpretation by clients, typically containing
+ * options that are relevant for the user interface. This is not indexed for search.
+ */
+export interface SettingsMetaData {
+    [key: string]: any;
+}
+/**
+ * Objects that contain metadata in the settings property, which is NOT indexed for search
+ * but typically only relevant for particular client cases.
+ */
+export interface SettingsMetaDataEntity {
+    settings?: SettingsMetaData;
+}
+/**
+ * A reference to an item with optionally a title, settings and metadata.
+ */
+export interface QuestionEntity extends SearchMetaDataEntity, SettingsMetaDataEntity {
+    id?: string;
+    title?: string;
+    itemVId: string;
+    item?: ItemEntity;
+}
+export interface RubricBlock {
+    identifier?: string;
+    view: "author" | "candidate" | "proctor" | "scorer" | "testConstructor" | "tutor";
+    class?: "stimulus" | "instructions" | "rubric";
+    /**
+     * Versioned ID reference to the passage (when class="stimulus").
+     */
+    passageVId?: string;
+    /**
+     * Embedded passage entity (PIE-native approach).
+     * The passage is rendered using the same ItemPlayer infrastructure as items.
+     * Contains a PIE config with markup, elements, and models.
+     */
+    passage?: PassageEntity;
+    /**
+     * Simple HTML content string (for basic use cases).
+     * Alternative to the passage entity approach.
+     */
+    content?: string;
+}
+/**
+ * QTI-aligned assessment item reference (maps to qti-assessment-item-ref).
+ * References an item within a section. The item property contains the resolved
+ * ItemEntity with its PIE config.
+ */
+export interface AssessmentItemRef extends SearchMetaDataEntity {
+    id?: string;
+    identifier: string;
+    title?: string;
+    required?: boolean;
+    /**
+     * Item virtual ID - stable identifier for the item across versions
+     */
+    itemVId?: string;
+    /**
+     * Resolved item entity with PIE config.
+     * This is populated by the client before passing to the player.
+     */
+    item?: ItemEntity;
+    /** Item-level settings for tool requirements and customization */
+    settings?: ItemSettings;
+}
+export interface QtiAssessmentSection extends SearchMetaDataEntity, SettingsMetaDataEntity {
+    id?: string;
+    identifier: string;
+    title?: string;
+    visible?: boolean;
+    required?: boolean;
+    keepTogether?: boolean;
+    sections?: QtiAssessmentSection[];
+    /**
+     * QTI 3.0: Assessment item references (items in this section).
+     * Maps to qti-assessment-item-ref in QTI 3.0 XML.
+     */
+    assessmentItemRefs?: AssessmentItemRef[];
+    rubricBlocks?: RubricBlock[];
+    sort?: string;
+}
+export interface TestPart {
+    id?: string;
+    identifier: string;
+    navigationMode: "linear" | "nonlinear";
+    submissionMode: "individual" | "simultaneous";
+    sections: QtiAssessmentSection[];
+}
+export interface ContextDeclaration {
+    identifier: string;
+    baseType: "boolean" | "integer" | "float" | "string" | "identifier" | "point" | "pair" | "directedPair" | "duration" | "file" | "uri";
+    cardinality: "single" | "multiple" | "ordered" | "record";
+    defaultValue?: any;
+}
+export interface CatalogCard {
+    catalog: string;
+    language?: string;
+    content: string;
+}
+export interface AccessibilityCatalog {
+    identifier: string;
+    cards: CatalogCard[];
+}
+export interface PersonalNeedsProfile {
+    supports: string[];
+    prohibitedSupports?: string[];
+    activateAtInit?: string[];
+}
+/**
+ * QTI 3.0: Reference to a shared stimulus (passage).
+ * Maps to qti-assessment-stimulus-ref element.
+ *
+ * NOTE: Not currently used. We embed PassageEntity directly in RubricBlock instead.
+ * Kept for potential future use if we need to support external stimulus references.
+ */
+/**
+ * Reference to question and sorting info within a section.
+ */
+export interface SectionQuestionRef {
+    questionId: string;
+    sort?: string;
+}
+/**
+ * Questions can optionally be grouped in sections (legacy).
+ */
+export interface AssessmentSection extends SearchMetaDataEntity, SettingsMetaDataEntity {
+    id?: string;
+    title?: string;
+    sort?: string;
+    questions: SectionQuestionRef[];
+}
+export interface AssessmentEntity extends BaseEntity, SearchMetaDataEntity {
+    name?: string;
+    title?: string;
+    identifier?: string;
+    description?: string;
+    /** Enhanced structured settings for assessment configuration */
+    settings?: AssessmentSettings;
+    /** QTI version - '3.0' for QTI 3.0 format */
+    qtiVersion?: "3.0";
+    /** QTI 3.0: Context declarations (global shared variables) */
+    contextDeclarations?: ContextDeclaration[];
+    /** QTI 3.0: Integrated APIP accessibility catalogs */
+    accessibilityCatalogs?: AccessibilityCatalog[];
+    /** QTI 3.0: Personal Needs Profile (PNP 3.0) */
+    personalNeedsProfile?: PersonalNeedsProfile;
+    /** Legacy: Flat questions array */
+    questions?: QuestionEntity[];
+    /** Legacy: Simple sections */
+    sections?: AssessmentSection[];
+    /**
+     * QTI 3.0: testParts structure (authoritative for QTI format).
+     */
+    testParts?: TestPart[];
+    /** QTI 3.0: Stimulus material references (Phase 3 - placeholder) */
+    stimulusRefs?: any[];
+}
+/**
+ * Enhanced settings structure for assessment configuration.
+ * Provides structured fields for district policies, test administration,
+ * tool configurations, and theme settings while remaining extensible.
+ */
+export interface AssessmentSettings {
+    /** District/organization policies */
+    districtPolicy?: {
+        blockedTools?: string[];
+        requiredTools?: string[];
+        policies?: Record<string, any>;
+    };
+    /** Test administration configuration */
+    testAdministration?: {
+        mode?: "practice" | "test" | "benchmark";
+        toolOverrides?: Record<string, boolean>;
+        startDate?: string;
+        endDate?: string;
+    };
+    /** Tool-specific provider configurations */
+    toolConfigs?: {
+        calculator?: {
+            provider?: "desmos" | "ti" | "mathjs";
+            type?: "basic" | "scientific" | "graphing" | "ti-84" | "ti-108";
+            settings?: Record<string, any>;
+        };
+        /**
+         * Text-to-speech configuration.
+         *
+         * Standard parameters (voice, rate, pitch) are portable across providers
+         * and follow W3C Web Speech API specifications.
+         *
+         * Provider-specific extensions should be placed in providerOptions.
+         *
+         * @see https://w3c.github.io/speech-api/
+         */
+        textToSpeech?: {
+            /**
+             * TTS provider
+             *
+             * @standard "browser" uses W3C Web Speech API
+             * @extension "polly" and "custom" are provider-specific
+             */
+            provider?: "browser" | "polly" | "custom";
+            /**
+             * Voice identifier (provider-specific names)
+             *
+             * @standard W3C Web Speech API (concept)
+             * @example "Joanna" (Polly), "en-US-Standard-A" (Google), browser voices
+             */
+            voice?: string;
+            /**
+             * Speech rate (speed multiplier)
+             *
+             * @standard W3C Web Speech API
+             * @range 0.25 to 4.0
+             * @default 1.0
+             */
+            rate?: number;
+            /**
+             * Pitch adjustment
+             *
+             * @standard W3C Web Speech API
+             * @range 0 to 2 (as multiplier)
+             * @default 1.0
+             */
+            pitch?: number;
+            /**
+             * Provider-specific options (extensions)
+             *
+             * @extension Not portable across providers
+             * @example For AWS Polly: { engine: "neural", region: "us-east-1" }
+             * @example For Google Cloud: { audioEncoding: "MP3", effectsProfileId: ["headphone-class-device"] }
+             */
+            providerOptions?: Record<string, any>;
+        };
+        [toolId: string]: any;
+    };
+    /** Theme configuration (not in PNP) */
+    themeConfig?: {
+        colorScheme?: "default" | "high-contrast" | "dark";
+        fontSize?: number;
+        fontFamily?: string;
+        lineHeight?: number;
+        reducedMotion?: boolean;
+    };
+    /** Product-specific extensions */
+    [key: string]: any;
+}
+/**
+ * Item-level settings for tool requirements.
+ * Used in AssessmentItemRef.settings to specify item-specific tool needs.
+ */
+export interface ItemSettings {
+    requiredTools?: string[];
+    restrictedTools?: string[];
+    toolParameters?: Record<string, any>;
+    [key: string]: any;
+}
+export interface SanctionedVersionEntity extends BaseEntity {
+    organization?: string | OrganizationEntity;
+    match: string;
+    pie: string;
+    version: string;
+}
+export declare enum SanctionedVersionChangeStatus {
+    PENDING = "pending",
+    IN_PROGRESS = "in_progress",
+    COMPLETED = "completed",
+    FAILED = "failed"
+}
+export interface SanctionedVersionChangeRequest {
+    pie: string;
+    match: string;
+    version: string;
+}
+export interface SanctionedVersionChangeEntity extends BaseEntity {
+    organization?: string | OrganizationEntity;
+    createdBy: string | UserEntity;
+    status: SanctionedVersionChangeStatus;
+    requestedChanges: SanctionedVersionChangeRequest[];
+    beforeState: SanctionedVersionEntity[];
+    summary?: string;
+    jobId: string;
+}
+export type PlayerMode = "gather" | "view" | "evaluate" | "browse" | "author";
+export type PlayerRole = "student" | "instructor";
+export interface Env {
+    mode: PlayerMode;
+    role: PlayerRole;
+    partialScoring?: boolean;
+}
+export interface OutcomeResponse {
+    id: string;
+    element: string;
+    score?: number;
+    empty?: boolean;
+    completed?: boolean;
+    [key: string]: any;
+}
+export interface PieController {
+    model(model: PieModel, sessionData: any[], env?: any): Promise<PieModel>;
+    outcome(sessionData: any[], env?: any): Promise<OutcomeResponse>;
+    score: (config: object, session: object, env: object) => Promise<object>;
+    createCorrectResponseSession: (config: object, env: object) => Promise<object>;
+    validate: (model: object, config: object) => any;
+}
+export interface PieItemElement {
+    [elementName: string]: string;
+}
+export type BundleInfo = {
+    url: string;
+    hash: string;
+};
+interface PieDefaultModel {
+    [x: string]: any;
+}
+interface PieContent {
+    id: string;
+    /**
+     * Set of elements to include in the pie, provided in the format `{'element-name': 'mpm-package-name'}`
+     */
+    elements: PieItemElement;
+    /** Models for each PIE included in the item */
+    models: PieModel[];
+    markup: string;
+    bundle?: BundleInfo;
+    defaultExtraModels?: {
+        [key: string]: PieDefaultModel;
+    };
+}
+interface AdvancedItemConfig {
+    id: string;
+    pie: PieContent;
+    passage?: PieContent;
+    instructorResources?: [PieContent];
+    defaultExtraModels?: {
+        [key: string]: PieDefaultModel;
+    };
+}
+export type ItemConfig = PieContent | AdvancedItemConfig;
+/**
+ * During the loading of elements from PIE bundles, we do a trick where we make
+ * editor components available as web components by appending this to the element name.
+ */
+export declare const editorPostFix = "-pie-editor--";
+export type ModelUpdatedDetail = {
+    update: any;
+    reset: boolean;
+};
+export declare class ModelUpdatedEvent extends CustomEvent<ModelUpdatedDetail> {
+    readonly update: any;
+    readonly reset: boolean;
+    static TYPE: string;
+    constructor(update: any, reset?: boolean);
+}
+export type DeleteDone = (e?: Error) => void;
+export type DeleteImageDetail = {
+    src: string;
+    done: DeleteDone;
+};
+export declare class DeleteImageEvent extends CustomEvent<DeleteImageDetail> {
+    readonly src: string;
+    readonly done: DeleteDone;
+    static TYPE: string;
+    constructor(src: string, done: DeleteDone);
+}
+export interface ImageHandler {
+    isPasted?: boolean;
+    cancel: () => void;
+    done: (err?: Error, src?: string) => void;
+    fileChosen: (file: File) => void;
+    progress: (percent: number, bytes: number, total: number) => void;
+}
+export declare class InsertImageEvent extends CustomEvent<ImageHandler> {
+    readonly handler: ImageHandler;
+    static TYPE: string;
+    constructor(handler: ImageHandler);
+}
+export type DeleteSoundDetail = {
+    src: string;
+    done: DeleteDone;
+};
+export declare class DeleteSoundEvent extends CustomEvent<DeleteSoundDetail> {
+    readonly src: string;
+    readonly done: DeleteDone;
+    static TYPE: string;
+    constructor(src: string, done: DeleteDone);
+}
+export interface SoundHandler {
+    cancel: () => void;
+    done: (err?: Error, src?: string) => void;
+    fileChosen: File;
+    progress: (percent: number, bytes: number, total: number) => void;
+}
+export declare class InsertSoundEvent extends CustomEvent<SoundHandler> {
+    readonly handler: SoundHandler;
+    static TYPE: string;
+    constructor(handler: SoundHandler);
+}
+export declare const isPassageEntity: (passage: string | PassageEntity | undefined) => passage is PassageEntity;
+export declare function isPrerelease(version: any): version is SemVer;
+export declare function formatVersion(semVer: SemVer): string;
+export interface PieElement extends HTMLElement {
+    model: PieModel;
+    configuration: any;
+    session: any[];
+}
+export type SessionChangedDetail = {
+    complete: boolean;
+    component: any;
+};
+export declare class SessionChangedEvent extends CustomEvent<SessionChangedDetail> {
+    readonly component: string;
+    readonly complete: boolean;
+    static TYPE: string;
+    constructor(component: string, complete: boolean);
+}
+interface ItemCfg extends ConfigEntity {
+}
+interface ItemWPassageCfg {
+    pie: ItemCfg;
+    passage: ConfigEntity;
+}
+export interface LoadResponse {
+    js: {
+        view: string[];
+    };
+    item: ItemCfg | ItemWPassageCfg;
+    session: {
+        id: string;
+        data: any[];
+    };
+}
+export interface Tracker {
+    track(message: string, ...args: any[]): void;
+    start(label: string): void;
+    end(label: string, metadata?: {
+        [key: string]: any;
+    }): void;
+}
+/**
+ * Interface for storing tracker messages with timestamps
+ */
+/**
+ * Interface for storing tracker messages with timestamps
+ */
+export interface TrackerMessage {
+    timestamp: Date;
+    message: string;
+    args: any[];
+    formattedMessage: string;
+}
+/**
+ * Enhanced tracker that stores messages with timestamps
+ */
+export interface EnhancedTracker extends Tracker {
+    /**
+     * Get all raw tracker messages ordered by timestamp (ascending)
+     */
+    getMessages(): TrackerMessage[];
+    /**
+     * Get a formatted multi-line representation of all tracker messages
+     */
+    getFormattedMessages(): string;
+}
+export interface ScoreResponse {
+    session: FlatSession;
+    score: SessionScore;
+    empty?: boolean;
+    [key: string]: any;
+}
+export interface VersionDiff {
+    version: SemVer;
+    previousVersion: SemVer | null;
+    createdAt: Date;
+    changes: {
+        added: Record<string, any>;
+        removed: Record<string, any>;
+        modified: Record<string, {
+            previous: any;
+            current: any;
+        }>;
+    };
+    changeCount: number;
+}
+export interface RoleToOrganizationsMapping {
+    id?: string;
+    role: string;
+    organizations: OrganizationEntity[] | string[];
+    createdAt?: Date;
+    updatedAt?: Date;
+}
+export declare enum StandardType {
+    ROOT = 0,
+    SUBJECT = 1,
+    LEVEL = 2,
+    STANDARD = 3
+}
+export interface HierarchyInfo {
+    root?: {
+        id: string;
+        guid: string;
+        title: string;
+    };
+    subject?: {
+        id: string;
+        guid: string;
+        title: string;
+    };
+    level?: {
+        id: string;
+        guid: string;
+        title: string;
+        grades: number[];
+    };
+}
+export interface CmsLearningStandardEntity extends BaseEntity {
+    guid: string;
+    abbr?: string;
+    type: StandardType;
+    parentId?: string;
+    parentGuid?: string;
+    path?: string;
+    depth: number;
+    ancestors: string[];
+    hierarchy?: HierarchyInfo;
+    title?: string;
+    description?: string;
+    sequence?: string;
+    orderIndex?: number;
+    subjectArea?: string;
+    subjectName?: string;
+    category?: string;
+    abType?: string;
+    abLabel?: string;
+    setName?: string;
+    publication?: string;
+    adopted?: string;
+    grades: number[];
+    gradeNames?: string[];
+    properties: Record<string, string>;
+    status?: "active" | "retired" | "deprecated";
+    lastModifiedAt?: Date;
+    replacesGuid?: string;
+    replacedByGuid?: string;
+    descriptionHtml?: string;
+    lastSyncedAt?: Date;
+}
+export interface ItemBankConfig {
+    collectionId: string;
+    subject?: string;
+    gradeLevels?: number[];
+    orderIndex: number;
+}
+export interface DOKDistribution {
+    dok1?: number;
+    dok2?: number;
+    dok3?: number;
+    dok4?: number;
+}
+export interface AssessmentGoal {
+    dokDistribution?: DOKDistribution;
+    constructedResponseCount?: number;
+    passageGoals?: string;
+    totalItemCount?: {
+        target?: number;
+        min?: number;
+        max?: number;
+    };
+}
+export interface StudioImportMetadata {
+    studioAssessmentProgramId?: string;
+    studioPublicId?: string;
+    importedAt?: Date;
+}
+export interface CmsBlueprintEntity extends BaseEntity {
+    name: string;
+    description?: string;
+    subject?: string;
+    standardSet?: string;
+    gradeLevels: number[];
+    states?: string[];
+    itemBankConfigs: ItemBankConfig[];
+    assessmentGoal?: AssessmentGoal;
+    claimFramework?: "SBAC" | "PARCC" | "STATE" | "CUSTOM";
+    claimTargets?: string[];
+    useSBACClusterTarget?: boolean;
+    clusters?: string[];
+    studioImportMetadata?: StudioImportMetadata;
+    originalPrompt?: string;
+}
+export interface CmsBlueprintItemEntity extends BaseEntity {
+    blueprintId: string;
+    standardGuid: string;
+    count: number;
+    details?: string;
+    assessmentId?: string;
+}
+export type AssessmentMode = "view" | "author";
+export interface AssessmentAuthoringCallbacks {
+    onItemAdded?: (item: QuestionEntity, index: number) => void;
+    onItemRemoved?: (itemId: string, index: number) => void;
+    onItemMoved?: (fromIndex: number, toIndex: number) => void;
+    onItemUpdated?: (itemId: string, updates: Partial<QuestionEntity>) => void;
+    onAssessmentUpdated?: (assessment: AssessmentEntity) => void;
+    onSectionAdded?: (section: AssessmentSection, index: number) => void;
+    onSectionRemoved?: (sectionId: string, index: number) => void;
+    onSectionUpdated?: (sectionId: string, updates: Partial<AssessmentSection>) => void;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map