@learnlab/datashop-logger/dist/index.d.ts

TypeScript SDK for logging educational data to Carnegie Mellon's DataShop system

interface LogConfiguration {
    session_id?: string;
    context_message_id?: string;
    log_service_url?: string;
    class_name?: string;
    school_name?: string;
    period_name?: string;
    class_description?: string;
    instructor_name?: string;
    dataset_name?: string;
    problem_name?: string;
    problem_context?: string;
    user_guid?: string;
    auth_token?: string;
    source_id?: string;
    [key: string]: unknown;
}
interface SAI {
    selection: string | string[];
    action: string | string[];
    input: string | string[];
}
interface ActionEvaluation {
    evaluation: 'CORRECT' | 'INCORRECT' | 'HINT' | 'BUG' | 'NO_MATCH';
    classification?: string;
    currentHintNumber?: number;
    totalHintsAvailable?: number;
    hintID?: string;
}
interface CustomField {
    name: string;
    value: string | number | boolean;
}
interface LogMessage {
    transaction_id: string;
    timestamp: Date;
    type: 'tool_message' | 'tutor_message' | 'context_message';
}
interface ToolMessage extends LogMessage {
    type: 'tool_message';
    sai: SAI;
    semantic_event: string;
    semantic_event_subtype?: string;
    custom_fields?: CustomField[];
}
interface Skill {
    name: string;
    category?: string;
    opportunities?: number;
    predicted_error_rate?: number;
}
interface LogAttemptParams {
    selection: string | string[];
    action: string | string[];
    input: string | string[];
    customFields?: Record<string, unknown>;
}
interface LogAttemptSAIParams {
    sai: SAI;
    customFields?: Record<string, unknown>;
}
interface LogHintRequestParams {
    selection: string | string[];
    action: string | string[];
    input: string | string[];
    customFields?: Record<string, unknown>;
}
interface LogResponseParams {
    transactionId: string;
    selection: string | string[];
    action: string | string[];
    input: string | string[];
    semanticName: string;
    evaluation: string | ActionEvaluation;
    advice?: string;
    customFields?: Record<string, unknown>;
    skills?: Skill[];
}
interface LogResponseSAIParams {
    transactionId: string;
    sai: SAI;
    semanticName: string;
    evaluation: string | ActionEvaluation;
    advice?: string;
    customFields?: Record<string, unknown>;
    skills?: Skill[];
}
interface LogHintResponseParams {
    transactionId: string;
    selection: string | string[];
    action: string | string[];
    input: string | string[];
    currentHintNumber: number;
    totalHintsAvailable: number;
    hintText: string;
    customFields?: Record<string, unknown>;
}
interface ResetParams {
    configuration?: LogConfiguration;
}
interface SetLogFormatParams {
    format: 'DATASHOP' | 'XAPI';
}
interface SetLoggingURLParams {
    url: string;
}
interface SetContextNameParams {
    name: string;
}
interface SetContextMessageIDParams {
    id: string;
}
interface SetUserIDParams {
    id: string;
}
interface SetProblemNameParams {
    name: string;
}
interface SetProblemContextParams {
    context: string;
}
interface SetDatasetNameParams {
    name: string;
}
interface SetSchoolParams {
    school: string;
}
interface SetPeriodParams {
    period: string;
}
interface SetInstructorParams {
    instructor: string;
}
interface SetDescriptionParams {
    description: string;
}
interface SetLogClassNameParams {
    className: string;
}
interface SetDatasetLevelNameParams {
    level: number;
    name: string;
}
interface SetDatasetLevelTypeParams {
    level: number;
    type: string;
}
interface SetUseSessionLogParams {
    use: boolean;
}
interface SetLogListenerParams {
    listener: (message: string) => void;
}
interface TutorMessage extends LogMessage {
    type: 'tutor_message';
    sai: SAI;
    semantic_event: string;
    semantic_event_subtype?: string;
    evaluation: ActionEvaluation;
    feedback?: string;
    skills?: Skill[];
    custom_fields?: CustomField[];
}
interface ContextMessage extends LogMessage {
    type: 'context_message';
    name: string;
    context_message_id: string;
}
interface LoggingLibraryOptions {
    configuration?: LogConfiguration;
    logFormat?: 'DATASHOP' | 'XAPI';
    useSessionLog?: boolean;
}
interface IDataShopLogger {
    start(): string;
    resume(sessionId: string): void;
    reset(params: ResetParams): void;
    endSession(): void;
    logInterfaceAttempt(params: LogAttemptParams): string;
    logInterfaceAttemptSAI(params: LogAttemptSAIParams): string;
    logInterfaceHintRequest(params: LogHintRequestParams): string;
    logHintResponse(params: LogHintResponseParams): void;
    logResponse(params: LogResponseParams): void;
    logResponseSAI(params: LogResponseSAIParams): void;
    setLogFormat(params: SetLogFormatParams): void;
    getLogFormat(): 'DATASHOP' | 'XAPI';
    setLoggingURL(params: SetLoggingURLParams): void;
    setLoggingURLQA(): void;
    setLoggingURLProduction(): void;
    setContextName(params: SetContextNameParams): void;
    getContextName(): string;
    setContextMessageID(params: SetContextMessageIDParams): void;
    getContextMessageID(): string;
    setUserID(params: SetUserIDParams): void;
    setProblemName(params: SetProblemNameParams): void;
    setProblemContext(params: SetProblemContextParams): void;
    setDatasetName(params: SetDatasetNameParams): void;
    setSchool(params: SetSchoolParams): void;
    setPeriod(params: SetPeriodParams): void;
    setInstructor(params: SetInstructorParams): void;
    setDescription(params: SetDescriptionParams): void;
    setLogClassName(params: SetLogClassNameParams): void;
    setDatasetLevelName(params: SetDatasetLevelNameParams): void;
    setDatasetLevelType(params: SetDatasetLevelTypeParams): void;
    setUseSessionLog(params: SetUseSessionLogParams): void;
    getLastSAI(): SAI | null;
    getSessionId(): string | undefined;
    getUserGuid(): string | undefined;
    getContextMessageId(): string | undefined;
    setLogListener(params: SetLogListenerParams): void;
    /** @deprecated Use object parameter version instead */
    logInterfaceAttempt(selection: string | string[], action: string | string[], input: string | string[], customFields?: Record<string, unknown>): string;
    /** @deprecated Use object parameter version instead */
    logResponse(transactionID: string, selection: string | string[], action: string | string[], input: string | string[], semanticName: string, evaluation: string | ActionEvaluation, advice: string, customFields?: Record<string, unknown>, skills?: Skill[]): void;
}

declare class DataShopLogger implements IDataShopLogger {
    private configuration;
    private logFormat;
    private useSessionLog;
    private lastTransactionID;
    private lastSAI;
    private messageBuilder;
    private logListener?;
    private readonly defaultConfiguration;
    constructor(options?: LoggingLibraryOptions);
    private initializeSession;
    start(): string;
    resume(sessionId: string): void;
    reset(params: ResetParams): void;
    reset(configuration?: LogConfiguration): void;
    logInterfaceAttempt(params: LogAttemptParams): string;
    logInterfaceAttempt(selection: string | string[], action: string | string[], input: string | string[], customFields?: Record<string, unknown>): string;
    logInterfaceAttemptSAI(params: LogAttemptSAIParams): string;
    logInterfaceAttemptSAI(sai: SAI, customFields?: Record<string, unknown>): string;
    logInterfaceHintRequest(params: LogHintRequestParams): string;
    logInterfaceHintRequest(selection: string | string[], action: string | string[], input: string | string[], customFields?: Record<string, unknown>): string;
    logHintResponse(params: LogHintResponseParams): void;
    logHintResponse(transactionID: string, selection: string | string[], action: string | string[], input: string | string[], currentHintNumber: number, totalHintsAvailable: number, hintText: string, customFields?: Record<string, unknown>): void;
    logResponse(params: LogResponseParams): void;
    logResponse(transactionID: string, selection: string | string[], action: string | string[], input: string | string[], semanticName: string, evaluation: string | ActionEvaluation, advice: string, customFields?: Record<string, unknown>, skills?: Skill[]): void;
    logResponseSAI(params: LogResponseSAIParams): void;
    logResponseSAI(transactionID: string, sai: SAI, semanticName: string, evaluation: string | ActionEvaluation, advice: string, customFields?: Record<string, unknown>, skills?: Skill[]): void;
    private sendMessage;
    setLogFormat(params: SetLogFormatParams): void;
    getLogFormat(): "DATASHOP" | "XAPI";
    setLoggingURL(params: SetLoggingURLParams): void;
    setLoggingURLQA(): void;
    setLoggingURLProduction(): void;
    setContextName(params: SetContextNameParams): void;
    getContextName(): string;
    setContextMessageID(params: SetContextMessageIDParams): void;
    getContextMessageID(): string;
    setUserID(params: SetUserIDParams): void;
    setProblemName(params: SetProblemNameParams): void;
    setProblemContext(params: SetProblemContextParams): void;
    setDatasetName(params: SetDatasetNameParams): void;
    setSchool(params: SetSchoolParams): void;
    setPeriod(params: SetPeriodParams): void;
    setInstructor(params: SetInstructorParams): void;
    setDescription(params: SetDescriptionParams): void;
    setLogClassName(params: SetLogClassNameParams): void;
    setDatasetLevelName(params: SetDatasetLevelNameParams): void;
    setDatasetLevelType(params: SetDatasetLevelTypeParams): void;
    setUseSessionLog(params: SetUseSessionLogParams): void;
    getLastSAI(): SAI | null;
    getSessionId(): string | undefined;
    getUserGuid(): string | undefined;
    getContextMessageId(): string | undefined;
    endSession(): void;
    setLogListener(params: SetLogListenerParams): void;
}

declare class SAIBuilder {
    private selectionArray;
    private actionArray;
    private inputArray;
    constructor(selection?: string | string[], action?: string | string[], input?: string | string[]);
    setSelection(selection: string | string[]): SAIBuilder;
    setAction(action: string | string[]): SAIBuilder;
    setInput(input: string | string[]): SAIBuilder;
    build(): SAI;
    toXMLString(): string;
    private escapeXML;
}

declare class LogMessageBuilder {
    private configuration;
    private readonly xmlProlog;
    private readonly DTDVersion;
    private customFields;
    constructor(configuration: LogConfiguration);
    resetCustomFields(): void;
    addCustomField(name: string, value: string | number | boolean): void;
    addCustomFields(fields?: Record<string, unknown>): void;
    formatTimeStamp(date: Date): string;
    formatTimeStampOLI(date: Date): string;
    createLogSessionStart(): string;
    createContextMessage(): string;
    createSemanticEventToolMessage(sai: SAI, transactionID: string, semanticEventName: string, semanticEventSubtype?: string, trigger?: string): string;
    createTutorMessage(sai: SAI, transactionID: string, semanticEventName: string, evaluation: ActionEvaluation, feedback: string, semanticEventSubtype?: string, skills?: Array<{
        name: string;
        category?: string;
    }>): string;
    wrapForDataShop(message: string): string;
    wrapForOLI(message: string): string;
    private makeMetaElement;
    private escapeXML;
}

declare class DataShopLoggerError extends Error {
    readonly code: string;
    readonly details?: unknown;
    constructor(message: string, code: string, details?: unknown);
}

export { type ActionEvaluation, type ContextMessage, type CustomField, DataShopLogger, DataShopLoggerError, type IDataShopLogger, type LogAttemptParams, type LogAttemptSAIParams, type LogConfiguration, type LogHintRequestParams, type LogHintResponseParams, type LogMessage, LogMessageBuilder, type LogResponseParams, type LogResponseSAIParams, type LoggingLibraryOptions, type ResetParams, type SAI, SAIBuilder, type SetContextMessageIDParams, type SetContextNameParams, type SetDatasetLevelNameParams, type SetDatasetLevelTypeParams, type SetDatasetNameParams, type SetDescriptionParams, type SetInstructorParams, type SetLogClassNameParams, type SetLogFormatParams, type SetLogListenerParams, type SetLoggingURLParams, type SetPeriodParams, type SetProblemContextParams, type SetProblemNameParams, type SetSchoolParams, type SetUseSessionLogParams, type SetUserIDParams, type Skill, type ToolMessage, type TutorMessage };