@intellectif/lk-core 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Intellectif LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/activity-D5tqgx8A.d.cts

@@ -0,0 +1,330 @@
+/**
+ * An xAPI Activity object — the thing a statement is about.
+ * This SDK only builds Activity-type objects (xAPI 1.0.3 §4.1.4.1).
+ */
+interface XAPIObject {
+    objectType: 'Activity';
+    /** IRI uniquely identifying the activity. */
+    id: string;
+    definition?: {
+        /** Language-map of human-readable names for the activity. */
+        name?: Record<string, string>;
+        /** Language-map of human-readable descriptions. */
+        description?: Record<string, string>;
+        /** IRI identifying the activity type. */
+        type?: string;
+        extensions?: Record<string, unknown>;
+    };
+}
+/**
+ * An xAPI Agent (person or system) that performed the statement's verb.
+ * Exactly one of `mbox` or `account` must be present.
+ */
+interface XAPIActor {
+    objectType: 'Agent';
+    /** Display name for the actor. */
+    name?: string;
+    /** Mailto IRI uniquely identifying the actor (e.g. `mailto:user@example.com`). */
+    mbox?: string;
+    /** Account-based actor identifier. */
+    account?: {
+        /** IRI of the home page of the account's service provider. */
+        homePage: string;
+        /** The actor's unique name on that service. */
+        name: string;
+    };
+}
+/** An xAPI Verb — the action performed in the statement. */
+interface XAPIVerbObject {
+    /** IRI uniquely identifying this verb (e.g. from adlnet.gov/expapi/verbs). */
+    id: string;
+    /** Language-map of human-readable verb labels. */
+    display: Record<string, string>;
+}
+/** Score sub-object within an xAPI Result. */
+interface XAPIScore {
+    /** Normalized score in the range [0, 1]. */
+    scaled: number;
+    /** Raw score in the instrument's native scale. */
+    raw?: number;
+    /** Minimum possible raw score. */
+    min?: number;
+    /** Maximum possible raw score. */
+    max?: number;
+}
+/** Result information attached to an xAPI Statement. */
+interface XAPIResult {
+    score?: XAPIScore;
+    /** Whether the actor's performance was successful. */
+    success?: boolean;
+    /** Whether the activity was completed. */
+    completion?: boolean;
+    /** ISO 8601 duration string representing time spent (e.g. `PT5M30S`). */
+    duration?: string;
+    /** A string representation of the learner's response. */
+    response?: string;
+    extensions?: Record<string, unknown>;
+}
+/** Context information attached to an xAPI Statement. */
+interface XAPIContext {
+    /** Name of the software used to record the statement. */
+    platform?: string;
+    /** BCP 47 language tag for the activity content. */
+    language?: string;
+    extensions?: Record<string, unknown>;
+}
+/** A complete xAPI 1.0.3 Statement. */
+interface XAPIStatement {
+    /** UUID v4 uniquely identifying this statement. */
+    id: string;
+    actor: XAPIActor;
+    verb: XAPIVerbObject;
+    object: XAPIObject;
+    result?: XAPIResult;
+    context?: XAPIContext;
+    /** ISO 8601 timestamp of when the statement occurred. */
+    timestamp: string;
+    version: '1.0.3';
+}
+/**
+ * Configuration passed to `useXAPI` to connect to an LRS endpoint.
+ * The `auth` field supports both HTTP Basic and Bearer token authentication.
+ */
+interface XAPIConfig {
+    /** Full URL of the LRS statements endpoint. */
+    endpoint: string;
+    /** Authentication credentials for the LRS. */
+    auth: {
+        type: 'basic';
+        username: string;
+        password: string;
+    } | {
+        type: 'bearer';
+        token: string;
+    };
+    /** IRI identifying the activity in all statements sent by this hook instance. */
+    activityId: string;
+    actor: XAPIActor;
+    /** Called after all retry attempts are exhausted. */
+    onError?: (err: XAPIError) => void;
+}
+/** Error payload delivered to `XAPIConfig.onError` after retries are exhausted. */
+interface XAPIError {
+    /** The statement that failed to send. */
+    statement: XAPIStatement;
+    /** The 1-based attempt number on which the final failure occurred. */
+    attempt: number;
+    /** HTTP status code from the LRS, if a response was received. */
+    statusCode?: number;
+    /** Human-readable error description. */
+    message: string;
+}
+
+/** The set of activity types supported by learning-kit. */
+type ActivityType = 'multiple-choice' | 'fill-in-the-blanks';
+/** Maps each ActivityType string to its corresponding data shape. */
+interface ActivityDataMap {
+    'multiple-choice': MultipleChoiceData;
+    'fill-in-the-blanks': FillInTheBlanksData;
+}
+/** Union of all valid activity data shapes. */
+type ActivityData = MultipleChoiceData | FillInTheBlanksData;
+/**
+ * Optional media (image/audio/video) shown above a question or passage.
+ * URL-only: hosting/delivery is the consuming application's responsibility.
+ */
+interface ActivityMedia {
+    /** The kind of media; selects the rendered element. `embed` → sandboxed iframe. */
+    type: 'image' | 'audio' | 'video' | 'embed';
+    /**
+     * Source URL. For `embed` this MUST be the provider's embeddable URL
+     * (e.g. `https://www.youtube.com/embed/<id>`), not the watch page.
+     */
+    url: string;
+    /** Alternative text. Required for `image` and `embed`; optional label for audio/video. */
+    alt?: string;
+    /** Optional WebVTT captions track URL for `audio`/`video`. */
+    captionsUrl?: string;
+}
+/**
+ * Optional authored "overall feedback" shown after submission, chosen by
+ * whether the learner passed (h5p-style overall feedback). Distinct from
+ * per-option feedback; either field may be omitted.
+ */
+interface ActivityFeedback {
+    /** Shown when the learner passes (score ≥ pass threshold). */
+    correct?: string;
+    /** Shown when the learner does not pass. */
+    incorrect?: string;
+}
+/** A single selectable option within a Multiple Choice activity. */
+interface MultipleChoiceOption {
+    /** Unique identifier for this option within the activity. */
+    id: string;
+    /** Display text shown to the learner. */
+    text: string;
+    /** Whether this option is part of the correct answer. */
+    isCorrect: boolean;
+    /** Optional per-option feedback shown after submission. */
+    feedback?: string;
+}
+/** Data contract for a Multiple Choice activity. */
+interface MultipleChoiceData {
+    schemaVersion: '1.0';
+    type: 'multiple-choice';
+    /** Unique identifier for this activity. */
+    id: string;
+    /** Human-readable title used in xAPI statements and error boundaries. */
+    title: string;
+    /** The question stem presented to the learner. */
+    question: string;
+    /** `single` allows one selection; `multi` allows multiple. */
+    mode: 'single' | 'multi';
+    /** Ordered list of answer options. */
+    options: MultipleChoiceOption[];
+    /** Scoring algorithm applied when the learner submits. */
+    scoringStrategy: 'all-or-nothing' | 'partial';
+    /** Optional media shown above the question. */
+    media?: ActivityMedia;
+    /** Optional authored overall feedback shown after submission. */
+    feedback?: ActivityFeedback;
+    /** Minimum scaled score [0–1] required to pass. Defaults to 0.6 when absent. */
+    passThreshold?: number;
+    /** When true, options are shuffled deterministically per session. */
+    shuffle?: boolean;
+    /** BCP 47 language tag for the activity content. */
+    locale?: string;
+    /** IRI references to learning objectives addressed by this activity. */
+    learningObjectives?: string[];
+    /** Subjective difficulty on a 1–5 scale. */
+    difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+}
+/** Configuration for a single fill-in-the-blank slot. */
+interface BlankConfig {
+    /** Unique identifier matching the `{{blank_id}}` placeholder in the passage. */
+    id: string;
+    /** List of strings accepted as correct answers for this blank. */
+    acceptedAnswers: string[];
+    /** Whether answer matching is case-sensitive. Defaults to false. */
+    caseSensitive?: boolean;
+    /** Whether leading/trailing whitespace is stripped before matching. Defaults to true. */
+    trimWhitespace?: boolean;
+    /** Optional hint text revealed on learner request. */
+    hint?: string;
+    /** Optional feedback shown inline next to this blank after submission. */
+    feedback?: string;
+}
+/** Data contract for a Fill-in-the-Blanks activity. */
+interface FillInTheBlanksData {
+    schemaVersion: '1.0';
+    type: 'fill-in-the-blanks';
+    /** Unique identifier for this activity. */
+    id: string;
+    /** Human-readable title used in xAPI statements and error boundaries. */
+    title: string;
+    /** Passage text containing `{{blank_id}}` placeholders. */
+    passage: string;
+    /** Configuration for each blank in the passage. */
+    blanks: BlankConfig[];
+    /** Scoring algorithm applied when the learner submits. */
+    scoringStrategy: 'all-or-nothing' | 'partial';
+    /** Optional media shown above the passage. */
+    media?: ActivityMedia;
+    /** Optional authored overall feedback shown after submission. */
+    feedback?: ActivityFeedback;
+    /** Minimum scaled score [0–1] required to pass. Defaults to 0.6 when absent. */
+    passThreshold?: number;
+    /** BCP 47 language tag for the activity content. */
+    locale?: string;
+    /** IRI references to learning objectives addressed by this activity. */
+    learningObjectives?: string[];
+    /** Subjective difficulty on a 1–5 scale. */
+    difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+}
+/** Union of all learner response shapes. */
+type LearnerResponse = MultipleChoiceLearnerResponse | FillInTheBlanksLearnerResponse;
+/** Learner response for a Multiple Choice activity. */
+interface MultipleChoiceLearnerResponse {
+    type: 'multiple-choice';
+    /** IDs of the options the learner selected. */
+    selectedOptionIds: string[];
+}
+/** Learner response for a Fill-in-the-Blanks activity. */
+interface FillInTheBlanksLearnerResponse {
+    type: 'fill-in-the-blanks';
+    /** Map of blank ID to the learner's typed answer. */
+    answers: Record<string, string>;
+}
+/** Per-item scoring breakdown returned by the scoring engine. */
+interface ScoringDetail {
+    /** ID of the option or blank this detail refers to. */
+    itemId: string;
+    /** Whether the learner's response for this item was correct. */
+    correct: boolean;
+    /** The learner's actual response for this item. */
+    learnerResponse: string | string[];
+    /** The expected correct response(s) for this item. */
+    correctResponse: string | string[];
+    /** Optional weight applied to this item's contribution to the overall score. */
+    weight?: number;
+}
+/** Full scoring result returned by the scoring engine. */
+interface ScoringResult {
+    /** Scaled score in the range [0, 1]. */
+    score: number;
+    /** Maximum possible scaled score (always 1). */
+    maxScore: number;
+    /** Whether the score meets or exceeds the activity's pass threshold. */
+    passed: boolean;
+    /** Optional top-level feedback message, or null when absent. */
+    feedback: string | null;
+    /** Per-item scoring breakdown. */
+    details: ScoringDetail[];
+}
+/** A single validation error produced by `validateActivity`. */
+interface ValidationError {
+    /** JSON-path-style location of the invalid field. */
+    path: string[];
+    /** Human-readable description of the validation failure. */
+    message: string;
+    /** Machine-readable error code. */
+    code: string;
+}
+/**
+ * Result of a `validateActivity` call.
+ * On success, `data` is the validated and typed activity data.
+ * On failure, `errors` contains one entry per violated constraint.
+ */
+type ValidationResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: ValidationError[];
+};
+/** The payload delivered to an activity's `onComplete` callback. */
+interface ActivityResult {
+    /** Scaled score in the range [0, 1]. */
+    score: number;
+    /** Maximum possible scaled score (always 1). */
+    maxScore: number;
+    /** Whether the learner passed based on the activity's pass threshold. */
+    passed: boolean;
+    /** Time in milliseconds from first interaction to submission. */
+    timeSpent: number;
+    /** The xAPI statement built and (optionally) sent for this attempt. */
+    xapiStatement: XAPIStatement;
+}
+/** Fired by activity components on every discrete learner interaction. */
+interface InteractionEvent {
+    /** The kind of interaction that occurred. */
+    type: 'option-selected' | 'option-deselected' | 'blank-filled' | 'hint-requested' | 'submitted';
+    /** ID of the activity that produced the event. */
+    activityId: string;
+    /** Unix timestamp (ms) of when the interaction occurred. */
+    timestamp: number;
+    /** Additional event-specific data. */
+    payload: Record<string, unknown>;
+}
+
+export type { ActivityData as A, BlankConfig as B, FillInTheBlanksData as F, InteractionEvent as I, LearnerResponse as L, MultipleChoiceData as M, ScoringDetail as S, ValidationError as V, XAPIActor as X, ActivityDataMap as a, ActivityFeedback as b, ActivityMedia as c, ActivityResult as d, ActivityType as e, FillInTheBlanksLearnerResponse as f, MultipleChoiceLearnerResponse as g, MultipleChoiceOption as h, ScoringResult as i, ValidationResult as j, XAPIConfig as k, XAPIContext as l, XAPIError as m, XAPIObject as n, XAPIResult as o, XAPIScore as p, XAPIStatement as q, XAPIVerbObject as r };

package/dist/activity-D5tqgx8A.d.ts

@@ -0,0 +1,330 @@
+/**
+ * An xAPI Activity object — the thing a statement is about.
+ * This SDK only builds Activity-type objects (xAPI 1.0.3 §4.1.4.1).
+ */
+interface XAPIObject {
+    objectType: 'Activity';
+    /** IRI uniquely identifying the activity. */
+    id: string;
+    definition?: {
+        /** Language-map of human-readable names for the activity. */
+        name?: Record<string, string>;
+        /** Language-map of human-readable descriptions. */
+        description?: Record<string, string>;
+        /** IRI identifying the activity type. */
+        type?: string;
+        extensions?: Record<string, unknown>;
+    };
+}
+/**
+ * An xAPI Agent (person or system) that performed the statement's verb.
+ * Exactly one of `mbox` or `account` must be present.
+ */
+interface XAPIActor {
+    objectType: 'Agent';
+    /** Display name for the actor. */
+    name?: string;
+    /** Mailto IRI uniquely identifying the actor (e.g. `mailto:user@example.com`). */
+    mbox?: string;
+    /** Account-based actor identifier. */
+    account?: {
+        /** IRI of the home page of the account's service provider. */
+        homePage: string;
+        /** The actor's unique name on that service. */
+        name: string;
+    };
+}
+/** An xAPI Verb — the action performed in the statement. */
+interface XAPIVerbObject {
+    /** IRI uniquely identifying this verb (e.g. from adlnet.gov/expapi/verbs). */
+    id: string;
+    /** Language-map of human-readable verb labels. */
+    display: Record<string, string>;
+}
+/** Score sub-object within an xAPI Result. */
+interface XAPIScore {
+    /** Normalized score in the range [0, 1]. */
+    scaled: number;
+    /** Raw score in the instrument's native scale. */
+    raw?: number;
+    /** Minimum possible raw score. */
+    min?: number;
+    /** Maximum possible raw score. */
+    max?: number;
+}
+/** Result information attached to an xAPI Statement. */
+interface XAPIResult {
+    score?: XAPIScore;
+    /** Whether the actor's performance was successful. */
+    success?: boolean;
+    /** Whether the activity was completed. */
+    completion?: boolean;
+    /** ISO 8601 duration string representing time spent (e.g. `PT5M30S`). */
+    duration?: string;
+    /** A string representation of the learner's response. */
+    response?: string;
+    extensions?: Record<string, unknown>;
+}
+/** Context information attached to an xAPI Statement. */
+interface XAPIContext {
+    /** Name of the software used to record the statement. */
+    platform?: string;
+    /** BCP 47 language tag for the activity content. */
+    language?: string;
+    extensions?: Record<string, unknown>;
+}
+/** A complete xAPI 1.0.3 Statement. */
+interface XAPIStatement {
+    /** UUID v4 uniquely identifying this statement. */
+    id: string;
+    actor: XAPIActor;
+    verb: XAPIVerbObject;
+    object: XAPIObject;
+    result?: XAPIResult;
+    context?: XAPIContext;
+    /** ISO 8601 timestamp of when the statement occurred. */
+    timestamp: string;
+    version: '1.0.3';
+}
+/**
+ * Configuration passed to `useXAPI` to connect to an LRS endpoint.
+ * The `auth` field supports both HTTP Basic and Bearer token authentication.
+ */
+interface XAPIConfig {
+    /** Full URL of the LRS statements endpoint. */
+    endpoint: string;
+    /** Authentication credentials for the LRS. */
+    auth: {
+        type: 'basic';
+        username: string;
+        password: string;
+    } | {
+        type: 'bearer';
+        token: string;
+    };
+    /** IRI identifying the activity in all statements sent by this hook instance. */
+    activityId: string;
+    actor: XAPIActor;
+    /** Called after all retry attempts are exhausted. */
+    onError?: (err: XAPIError) => void;
+}
+/** Error payload delivered to `XAPIConfig.onError` after retries are exhausted. */
+interface XAPIError {
+    /** The statement that failed to send. */
+    statement: XAPIStatement;
+    /** The 1-based attempt number on which the final failure occurred. */
+    attempt: number;
+    /** HTTP status code from the LRS, if a response was received. */
+    statusCode?: number;
+    /** Human-readable error description. */
+    message: string;
+}
+
+/** The set of activity types supported by learning-kit. */
+type ActivityType = 'multiple-choice' | 'fill-in-the-blanks';
+/** Maps each ActivityType string to its corresponding data shape. */
+interface ActivityDataMap {
+    'multiple-choice': MultipleChoiceData;
+    'fill-in-the-blanks': FillInTheBlanksData;
+}
+/** Union of all valid activity data shapes. */
+type ActivityData = MultipleChoiceData | FillInTheBlanksData;
+/**
+ * Optional media (image/audio/video) shown above a question or passage.
+ * URL-only: hosting/delivery is the consuming application's responsibility.
+ */
+interface ActivityMedia {
+    /** The kind of media; selects the rendered element. `embed` → sandboxed iframe. */
+    type: 'image' | 'audio' | 'video' | 'embed';
+    /**
+     * Source URL. For `embed` this MUST be the provider's embeddable URL
+     * (e.g. `https://www.youtube.com/embed/<id>`), not the watch page.
+     */
+    url: string;
+    /** Alternative text. Required for `image` and `embed`; optional label for audio/video. */
+    alt?: string;
+    /** Optional WebVTT captions track URL for `audio`/`video`. */
+    captionsUrl?: string;
+}
+/**
+ * Optional authored "overall feedback" shown after submission, chosen by
+ * whether the learner passed (h5p-style overall feedback). Distinct from
+ * per-option feedback; either field may be omitted.
+ */
+interface ActivityFeedback {
+    /** Shown when the learner passes (score ≥ pass threshold). */
+    correct?: string;
+    /** Shown when the learner does not pass. */
+    incorrect?: string;
+}
+/** A single selectable option within a Multiple Choice activity. */
+interface MultipleChoiceOption {
+    /** Unique identifier for this option within the activity. */
+    id: string;
+    /** Display text shown to the learner. */
+    text: string;
+    /** Whether this option is part of the correct answer. */
+    isCorrect: boolean;
+    /** Optional per-option feedback shown after submission. */
+    feedback?: string;
+}
+/** Data contract for a Multiple Choice activity. */
+interface MultipleChoiceData {
+    schemaVersion: '1.0';
+    type: 'multiple-choice';
+    /** Unique identifier for this activity. */
+    id: string;
+    /** Human-readable title used in xAPI statements and error boundaries. */
+    title: string;
+    /** The question stem presented to the learner. */
+    question: string;
+    /** `single` allows one selection; `multi` allows multiple. */
+    mode: 'single' | 'multi';
+    /** Ordered list of answer options. */
+    options: MultipleChoiceOption[];
+    /** Scoring algorithm applied when the learner submits. */
+    scoringStrategy: 'all-or-nothing' | 'partial';
+    /** Optional media shown above the question. */
+    media?: ActivityMedia;
+    /** Optional authored overall feedback shown after submission. */
+    feedback?: ActivityFeedback;
+    /** Minimum scaled score [0–1] required to pass. Defaults to 0.6 when absent. */
+    passThreshold?: number;
+    /** When true, options are shuffled deterministically per session. */
+    shuffle?: boolean;
+    /** BCP 47 language tag for the activity content. */
+    locale?: string;
+    /** IRI references to learning objectives addressed by this activity. */
+    learningObjectives?: string[];
+    /** Subjective difficulty on a 1–5 scale. */
+    difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+}
+/** Configuration for a single fill-in-the-blank slot. */
+interface BlankConfig {
+    /** Unique identifier matching the `{{blank_id}}` placeholder in the passage. */
+    id: string;
+    /** List of strings accepted as correct answers for this blank. */
+    acceptedAnswers: string[];
+    /** Whether answer matching is case-sensitive. Defaults to false. */
+    caseSensitive?: boolean;
+    /** Whether leading/trailing whitespace is stripped before matching. Defaults to true. */
+    trimWhitespace?: boolean;
+    /** Optional hint text revealed on learner request. */
+    hint?: string;
+    /** Optional feedback shown inline next to this blank after submission. */
+    feedback?: string;
+}
+/** Data contract for a Fill-in-the-Blanks activity. */
+interface FillInTheBlanksData {
+    schemaVersion: '1.0';
+    type: 'fill-in-the-blanks';
+    /** Unique identifier for this activity. */
+    id: string;
+    /** Human-readable title used in xAPI statements and error boundaries. */
+    title: string;
+    /** Passage text containing `{{blank_id}}` placeholders. */
+    passage: string;
+    /** Configuration for each blank in the passage. */
+    blanks: BlankConfig[];
+    /** Scoring algorithm applied when the learner submits. */
+    scoringStrategy: 'all-or-nothing' | 'partial';
+    /** Optional media shown above the passage. */
+    media?: ActivityMedia;
+    /** Optional authored overall feedback shown after submission. */
+    feedback?: ActivityFeedback;
+    /** Minimum scaled score [0–1] required to pass. Defaults to 0.6 when absent. */
+    passThreshold?: number;
+    /** BCP 47 language tag for the activity content. */
+    locale?: string;
+    /** IRI references to learning objectives addressed by this activity. */
+    learningObjectives?: string[];
+    /** Subjective difficulty on a 1–5 scale. */
+    difficultyLevel?: 1 | 2 | 3 | 4 | 5;
+}
+/** Union of all learner response shapes. */
+type LearnerResponse = MultipleChoiceLearnerResponse | FillInTheBlanksLearnerResponse;
+/** Learner response for a Multiple Choice activity. */
+interface MultipleChoiceLearnerResponse {
+    type: 'multiple-choice';
+    /** IDs of the options the learner selected. */
+    selectedOptionIds: string[];
+}
+/** Learner response for a Fill-in-the-Blanks activity. */
+interface FillInTheBlanksLearnerResponse {
+    type: 'fill-in-the-blanks';
+    /** Map of blank ID to the learner's typed answer. */
+    answers: Record<string, string>;
+}
+/** Per-item scoring breakdown returned by the scoring engine. */
+interface ScoringDetail {
+    /** ID of the option or blank this detail refers to. */
+    itemId: string;
+    /** Whether the learner's response for this item was correct. */
+    correct: boolean;
+    /** The learner's actual response for this item. */
+    learnerResponse: string | string[];
+    /** The expected correct response(s) for this item. */
+    correctResponse: string | string[];
+    /** Optional weight applied to this item's contribution to the overall score. */
+    weight?: number;
+}
+/** Full scoring result returned by the scoring engine. */
+interface ScoringResult {
+    /** Scaled score in the range [0, 1]. */
+    score: number;
+    /** Maximum possible scaled score (always 1). */
+    maxScore: number;
+    /** Whether the score meets or exceeds the activity's pass threshold. */
+    passed: boolean;
+    /** Optional top-level feedback message, or null when absent. */
+    feedback: string | null;
+    /** Per-item scoring breakdown. */
+    details: ScoringDetail[];
+}
+/** A single validation error produced by `validateActivity`. */
+interface ValidationError {
+    /** JSON-path-style location of the invalid field. */
+    path: string[];
+    /** Human-readable description of the validation failure. */
+    message: string;
+    /** Machine-readable error code. */
+    code: string;
+}
+/**
+ * Result of a `validateActivity` call.
+ * On success, `data` is the validated and typed activity data.
+ * On failure, `errors` contains one entry per violated constraint.
+ */
+type ValidationResult<T> = {
+    success: true;
+    data: T;
+} | {
+    success: false;
+    errors: ValidationError[];
+};
+/** The payload delivered to an activity's `onComplete` callback. */
+interface ActivityResult {
+    /** Scaled score in the range [0, 1]. */
+    score: number;
+    /** Maximum possible scaled score (always 1). */
+    maxScore: number;
+    /** Whether the learner passed based on the activity's pass threshold. */
+    passed: boolean;
+    /** Time in milliseconds from first interaction to submission. */
+    timeSpent: number;
+    /** The xAPI statement built and (optionally) sent for this attempt. */
+    xapiStatement: XAPIStatement;
+}
+/** Fired by activity components on every discrete learner interaction. */
+interface InteractionEvent {
+    /** The kind of interaction that occurred. */
+    type: 'option-selected' | 'option-deselected' | 'blank-filled' | 'hint-requested' | 'submitted';
+    /** ID of the activity that produced the event. */
+    activityId: string;
+    /** Unix timestamp (ms) of when the interaction occurred. */
+    timestamp: number;
+    /** Additional event-specific data. */
+    payload: Record<string, unknown>;
+}
+
+export type { ActivityData as A, BlankConfig as B, FillInTheBlanksData as F, InteractionEvent as I, LearnerResponse as L, MultipleChoiceData as M, ScoringDetail as S, ValidationError as V, XAPIActor as X, ActivityDataMap as a, ActivityFeedback as b, ActivityMedia as c, ActivityResult as d, ActivityType as e, FillInTheBlanksLearnerResponse as f, MultipleChoiceLearnerResponse as g, MultipleChoiceOption as h, ScoringResult as i, ValidationResult as j, XAPIConfig as k, XAPIContext as l, XAPIError as m, XAPIObject as n, XAPIResult as o, XAPIScore as p, XAPIStatement as q, XAPIVerbObject as r };