@intellectif/lk-core 0.2.1 → 0.3.1

package/dist/xapi.cjs

@@ -3,12 +3,12 @@
 
 
 
-var _chunkPJFDAP54cjs = require('./chunk-PJFDAP54.cjs');
-require('./chunk-DV466SBJ.cjs');
+var _chunkRUGIOQZYcjs = require('./chunk-RUGIOQZY.cjs');
+require('./chunk-PIMX4B4D.cjs');
 
 
 
 
 
-exports.XAPIVerb = _chunkPJFDAP54cjs.XAPIVerb; exports.XAPI_VERB_DISPLAY = _chunkPJFDAP54cjs.XAPI_VERB_DISPLAY; exports.validateXAPIStatement = _chunkPJFDAP54cjs.validateXAPIStatement; exports.xAPIBuilder = _chunkPJFDAP54cjs.xAPIBuilder;
+exports.XAPIVerb = _chunkRUGIOQZYcjs.XAPIVerb; exports.XAPI_VERB_DISPLAY = _chunkRUGIOQZYcjs.XAPI_VERB_DISPLAY; exports.validateXAPIStatement = _chunkRUGIOQZYcjs.validateXAPIStatement; exports.xAPIBuilder = _chunkRUGIOQZYcjs.xAPIBuilder;
 //# sourceMappingURL=xapi.cjs.map

package/dist/xapi.d.cts

@@ -1,4 +1,4 @@
-import { X as XAPIActor, i as ScoringResult, l as XAPIContext, o as XAPIResult, q as XAPIStatement } from './activity-D5tqgx8A.cjs';
+import { X as XAPIActor, m as ScoringResult, t as XAPIContext, x as XAPIResult, z as XAPIStatement } from './activity-zdcAMtFB.cjs';
 
 /**
  * The set of xAPI verbs emitted by SDK activities, keyed by a stable
@@ -13,6 +13,14 @@ declare const XAPIVerb: {
     readonly PASSED: "http://adlnet.gov/expapi/verbs/passed";
     readonly FAILED: "http://adlnet.gov/expapi/verbs/failed";
     readonly WATCHED: "https://w3id.org/xapi/video/verbs/watched";
+    /**
+     * Emitted for deferred-grading submissions (e.g. written-response): the
+     * learner has submitted work whose grade does not exist yet, so `answered`
+     * (which implies a scored response) would be wrong. xAPI 1.0.3 defines no
+     * canonical "submit" verb; the Activity Streams 1.0 IRI is the established
+     * community choice (design decision recorded per Task 25.4).
+     */
+    readonly SUBMITTED: "http://activitystrea.ms/schema/1.0/submit";
 };
 /** Union of the valid `XAPIVerb` keys. */
 type XAPIVerbKey = keyof typeof XAPIVerb;
@@ -30,6 +38,15 @@ interface XAPIObjectParams {
     description?: Record<string, string>;
     /** Activity type IRI. */
     type?: string;
+    /** xAPI cmi.interaction type (e.g. `choice`, `fill-in`, `long-fill-in`). */
+    interactionType?: string;
+    /** Correct-responses patterns, per the xAPI CRP format. */
+    correctResponsesPattern?: string[];
+    /** For choice-family interactions: the available components. */
+    choices?: Array<{
+        id: string;
+        description?: Record<string, string>;
+    }>;
 }
 /** Parameters for the generic {@link xAPIBuilder.buildStatement}. */
 interface XAPIStatementParams {
@@ -50,6 +67,20 @@ interface AnsweredStatementParams {
     context?: XAPIContext;
     resultExtensions?: Record<string, unknown>;
 }
+/**
+ * Parameters for {@link xAPIBuilder.buildSubmittedStatement} (verb =
+ * SUBMITTED — deferred-grading submissions). Carries NO score, success, or
+ * completion: the grade does not exist yet (Req 22.7).
+ */
+interface SubmittedStatementParams {
+    actor: XAPIActor;
+    object: XAPIObjectParams;
+    timeSpentMs: number;
+    /** Serialized learner response string (e.g. the submitted text). */
+    response?: string;
+    context?: XAPIContext;
+    resultExtensions?: Record<string, unknown>;
+}
 /** Parameters for {@link xAPIBuilder.buildCompletedStatement} (verb = COMPLETED). */
 interface CompletedStatementParams {
     actor: XAPIActor;
@@ -67,6 +98,13 @@ interface CompletedStatementParams {
 declare const xAPIBuilder: {
     buildStatement(params: XAPIStatementParams): XAPIStatement;
     buildAnsweredStatement(params: AnsweredStatementParams): XAPIStatement;
+    /**
+     * Builds a statement for a deferred-grading submission (e.g. a written
+     * response). Verb is SUBMITTED and the result deliberately omits `score`,
+     * `success`, and `completion` — none of them exist until the asynchronous
+     * grader runs; only `duration`, `response`, and extensions are recorded.
+     */
+    buildSubmittedStatement(params: SubmittedStatementParams): XAPIStatement;
     buildCompletedStatement(params: CompletedStatementParams): XAPIStatement;
 };
 
@@ -85,4 +123,4 @@ declare const xAPIBuilder: {
  */
 declare function validateXAPIStatement(statement: XAPIStatement): void;
 
-export { type AnsweredStatementParams, type CompletedStatementParams, type XAPIObjectParams, type XAPIStatementParams, XAPIVerb, type XAPIVerbKey, XAPI_VERB_DISPLAY, validateXAPIStatement, xAPIBuilder };
+export { type AnsweredStatementParams, type CompletedStatementParams, type SubmittedStatementParams, type XAPIObjectParams, type XAPIStatementParams, XAPIVerb, type XAPIVerbKey, XAPI_VERB_DISPLAY, validateXAPIStatement, xAPIBuilder };

package/dist/xapi.d.ts

@@ -1,4 +1,4 @@
-import { X as XAPIActor, i as ScoringResult, l as XAPIContext, o as XAPIResult, q as XAPIStatement } from './activity-D5tqgx8A.js';
+import { X as XAPIActor, m as ScoringResult, t as XAPIContext, x as XAPIResult, z as XAPIStatement } from './activity-zdcAMtFB.js';
 
 /**
  * The set of xAPI verbs emitted by SDK activities, keyed by a stable
@@ -13,6 +13,14 @@ declare const XAPIVerb: {
     readonly PASSED: "http://adlnet.gov/expapi/verbs/passed";
     readonly FAILED: "http://adlnet.gov/expapi/verbs/failed";
     readonly WATCHED: "https://w3id.org/xapi/video/verbs/watched";
+    /**
+     * Emitted for deferred-grading submissions (e.g. written-response): the
+     * learner has submitted work whose grade does not exist yet, so `answered`
+     * (which implies a scored response) would be wrong. xAPI 1.0.3 defines no
+     * canonical "submit" verb; the Activity Streams 1.0 IRI is the established
+     * community choice (design decision recorded per Task 25.4).
+     */
+    readonly SUBMITTED: "http://activitystrea.ms/schema/1.0/submit";
 };
 /** Union of the valid `XAPIVerb` keys. */
 type XAPIVerbKey = keyof typeof XAPIVerb;
@@ -30,6 +38,15 @@ interface XAPIObjectParams {
     description?: Record<string, string>;
     /** Activity type IRI. */
     type?: string;
+    /** xAPI cmi.interaction type (e.g. `choice`, `fill-in`, `long-fill-in`). */
+    interactionType?: string;
+    /** Correct-responses patterns, per the xAPI CRP format. */
+    correctResponsesPattern?: string[];
+    /** For choice-family interactions: the available components. */
+    choices?: Array<{
+        id: string;
+        description?: Record<string, string>;
+    }>;
 }
 /** Parameters for the generic {@link xAPIBuilder.buildStatement}. */
 interface XAPIStatementParams {
@@ -50,6 +67,20 @@ interface AnsweredStatementParams {
     context?: XAPIContext;
     resultExtensions?: Record<string, unknown>;
 }
+/**
+ * Parameters for {@link xAPIBuilder.buildSubmittedStatement} (verb =
+ * SUBMITTED — deferred-grading submissions). Carries NO score, success, or
+ * completion: the grade does not exist yet (Req 22.7).
+ */
+interface SubmittedStatementParams {
+    actor: XAPIActor;
+    object: XAPIObjectParams;
+    timeSpentMs: number;
+    /** Serialized learner response string (e.g. the submitted text). */
+    response?: string;
+    context?: XAPIContext;
+    resultExtensions?: Record<string, unknown>;
+}
 /** Parameters for {@link xAPIBuilder.buildCompletedStatement} (verb = COMPLETED). */
 interface CompletedStatementParams {
     actor: XAPIActor;
@@ -67,6 +98,13 @@ interface CompletedStatementParams {
 declare const xAPIBuilder: {
     buildStatement(params: XAPIStatementParams): XAPIStatement;
     buildAnsweredStatement(params: AnsweredStatementParams): XAPIStatement;
+    /**
+     * Builds a statement for a deferred-grading submission (e.g. a written
+     * response). Verb is SUBMITTED and the result deliberately omits `score`,
+     * `success`, and `completion` — none of them exist until the asynchronous
+     * grader runs; only `duration`, `response`, and extensions are recorded.
+     */
+    buildSubmittedStatement(params: SubmittedStatementParams): XAPIStatement;
     buildCompletedStatement(params: CompletedStatementParams): XAPIStatement;
 };
 
@@ -85,4 +123,4 @@ declare const xAPIBuilder: {
  */
 declare function validateXAPIStatement(statement: XAPIStatement): void;
 
-export { type AnsweredStatementParams, type CompletedStatementParams, type XAPIObjectParams, type XAPIStatementParams, XAPIVerb, type XAPIVerbKey, XAPI_VERB_DISPLAY, validateXAPIStatement, xAPIBuilder };
+export { type AnsweredStatementParams, type CompletedStatementParams, type SubmittedStatementParams, type XAPIObjectParams, type XAPIStatementParams, XAPIVerb, type XAPIVerbKey, XAPI_VERB_DISPLAY, validateXAPIStatement, xAPIBuilder };

package/dist/xapi.js

@@ -3,8 +3,8 @@ import {
   XAPI_VERB_DISPLAY,
   validateXAPIStatement,
   xAPIBuilder
-} from "./chunk-ZHOX6TO4.js";
-import "./chunk-6VOCV4EX.js";
+} from "./chunk-HS7BYCGE.js";
+import "./chunk-3YAVDV5F.js";
 export {
   XAPIVerb,
   XAPI_VERB_DISPLAY,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intellectif/lk-core",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Schemas, scoring engine, and xAPI builder for learning-kit",
   "repository": {
     "type": "git",
@@ -34,7 +34,8 @@
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "LICENSE"
   ],
   "dependencies": {
     "zod": "^3.25.0"
@@ -46,6 +47,10 @@
     "vitest": "^4.1.6"
   },
   "license": "MIT",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "build": "tsup",
     "test": "vitest run",

package/dist/activity-D5tqgx8A.d.cts

@@ -1,330 +0,0 @@
-/**
- * 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 };