@timeback/qti 0.1.2 → 0.1.4

package/dist/public-types.d.ts

@@ -0,0 +1,570 @@
+/**
+ * QTI Primitives
+ *
+ * Enums and literal types specific to the QTI protocol.
+ * For shared Timeback primitives (TimebackGrade, TimebackSubject), see `@timeback/types`.
+ */
+
+/**
+ * Lesson types for PowerPath integration.
+ * Used to categorize assessment content by delivery mode.
+ */
+type LessonType =
+	| 'powerpath-100'
+	| 'quiz'
+	| 'test-out'
+	| 'placement'
+	| 'unit-test'
+	| 'alpha-read-article'
+	| null
+
+/**
+ * API Response Types
+ *
+ * Types for QTI API responses.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// LIST RESPONSE
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Paginated list response from QTI API.
+ *
+ * QTI returns pagination metadata directly in the response body alongside items.
+ */
+interface ListResponse<T> {
+	/** Array of items in this page */
+	items: T[]
+	/** Total items across all pages */
+	total: number
+	/** Current page number (1-indexed) */
+	page: number
+	/** Total number of pages */
+	pages: number
+	/** Items per page */
+	limit: number
+	/** Sort field */
+	sort: string
+	/** Sort order */
+	order: 'asc' | 'desc'
+}
+
+/**
+ * Raw paginated response shape from QTI API (alias for internal use).
+ */
+type RawPaginatedResponse<T> = ListResponse<T>
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// DELETE RESPONSE
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Response from DELETE operations.
+ */
+interface DeleteResponse {
+	message: string
+}
+
+/**
+ * Base Types
+ *
+ * Common types shared across QTI resources.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ENUMS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Assessment item interaction types.
+ */
+type AssessmentItemType =
+	| 'choice'
+	| 'text-entry'
+	| 'extended-text'
+	| 'inline-choice'
+	| 'match'
+	| 'order'
+	| 'associate'
+	| 'select-point'
+	| 'graphic-order'
+	| 'graphic-associate'
+	| 'graphic-gap-match'
+	| 'hotspot'
+	| 'hottext'
+	| 'slider'
+	| 'drawing'
+	| 'media'
+	| 'upload'
+
+/**
+ * Cardinality of a response or outcome variable.
+ */
+type Cardinality = 'single' | 'multiple' | 'ordered' | 'record'
+
+/**
+ * Base type of a response or outcome variable.
+ */
+type BaseType =
+	| 'identifier'
+	| 'boolean'
+	| 'integer'
+	| 'float'
+	| 'string'
+	| 'point'
+	| 'pair'
+	| 'directedPair'
+	| 'duration'
+	| 'file'
+	| 'uri'
+
+/**
+ * Difficulty level for assessment items.
+ */
+type Difficulty = 'easy' | 'medium' | 'hard'
+
+/**
+ * Grade level (K-12 + pre-K as -1).
+ */
+type Grade = -1 | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13
+
+/**
+ * Navigation mode for test parts.
+ */
+type NavigationMode = 'linear' | 'nonlinear'
+
+/**
+ * Submission mode for test parts.
+ */
+type SubmissionMode = 'individual' | 'simultaneous'
+
+/**
+ * Show/hide indicator for feedback.
+ */
+type ShowHide = 'show' | 'hide'
+
+/**
+ * Schema type for validation.
+ */
+type ValidationSchema = 'test' | 'item' | 'stimulus'
+
+/**
+ * Sort order for list responses.
+ */
+type SortOrder = 'asc' | 'desc'
+
+/**
+ * Feedback type.
+ */
+type FeedbackType = 'QUESTION' | 'LESSON'
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// COMMON STRUCTURES
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Correct response value.
+ */
+interface CorrectResponse {
+	value: string[]
+}
+
+/**
+ * Response declaration for assessment items.
+ */
+interface ResponseDeclaration {
+	identifier: string
+	cardinality: Cardinality
+	baseType?: BaseType
+	correctResponse: CorrectResponse
+}
+
+/**
+ * Outcome declaration for items and tests.
+ */
+interface OutcomeDeclaration {
+	identifier: string
+	cardinality: Cardinality
+	baseType?: BaseType
+}
+
+/**
+ * Test outcome declaration with additional properties.
+ */
+interface TestOutcomeDeclaration {
+	identifier: string
+	cardinality?: Cardinality
+	baseType: BaseType
+	normalMaximum?: number
+	normalMinimum?: number
+	defaultValue?: {
+		value?: unknown
+	}
+}
+
+/**
+ * Inline feedback configuration.
+ */
+interface InlineFeedback {
+	outcomeIdentifier: string
+	variableIdentifier: string
+}
+
+/**
+ * Response processing configuration.
+ */
+interface ResponseProcessing {
+	templateType: 'match_correct' | 'map_response'
+	responseDeclarationIdentifier: string
+	outcomeIdentifier: string
+	correctResponseIdentifier: string
+	incorrectResponseIdentifier: string
+	inlineFeedback?: InlineFeedback
+}
+
+/**
+ * Learning objective set for metadata.
+ */
+interface LearningObjectiveSet {
+	source: string
+	learningObjectiveIds: string[]
+}
+
+/**
+ * Item metadata.
+ */
+interface ItemMetadata {
+	subject?: string
+	grade?: Grade
+	difficulty?: Difficulty
+	learningObjectiveSet?: LearningObjectiveSet[]
+}
+
+/**
+ * Modal feedback element.
+ */
+interface ModalFeedback {
+	outcomeIdentifier: string
+	identifier: string
+	showHide: ShowHide
+	content: string
+	title: string
+}
+
+/**
+ * Inline feedback element.
+ */
+interface FeedbackInline {
+	outcomeIdentifier: string
+	identifier: string
+	showHide: ShowHide
+	content: string
+	class: string[]
+}
+
+/**
+ * Block feedback element.
+ */
+interface FeedbackBlock {
+	outcomeIdentifier: string
+	identifier: string
+	showHide: ShowHide
+	content: string
+	class: string[]
+}
+
+/**
+ * Stylesheet reference.
+ */
+interface Stylesheet {
+	href: string
+	type: string
+}
+
+/**
+ * Catalog info entry.
+ */
+interface CatalogInfo {
+	id: string
+	support: string
+	content: string
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// PAGINATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Pagination metadata from QTI list responses.
+ */
+interface PaginationMeta {
+	/** Total items across all pages */
+	total: number
+	/** Current page number (1-indexed) */
+	page: number
+	/** Total number of pages */
+	pages: number
+	/** Items per page */
+	limit: number
+	/** Sort field */
+	sort: string
+	/** Sort order */
+	order: SortOrder
+}
+
+/**
+ * Assessment Items Types
+ *
+ * Types for QTI assessment item resources.
+ */
+
+
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ASSESSMENT ITEM
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Assessment item entity.
+ */
+interface AssessmentItem {
+	identifier: string
+	title: string
+	type: AssessmentItemType
+	qtiVersion: string
+	timeDependent: boolean
+	adaptive: boolean
+	responseDeclarations?: ResponseDeclaration[]
+	outcomeDeclarations?: OutcomeDeclaration[]
+	responseProcessing?: ResponseProcessing
+	metadata?: ItemMetadata
+	/** Raw QTI XML string */
+	rawXml: string
+	/**
+	 * Parsed XML→JSON content.
+	 * Structure varies by item type.
+	 */
+	content: Record<string, unknown>
+	modalFeedback?: ModalFeedback[]
+	feedbackInline?: FeedbackInline[]
+	feedbackBlock?: FeedbackBlock[]
+	createdAt: string
+	updatedAt: string
+	__v?: number
+}
+
+/**
+ * Result of processing a response.
+ */
+interface ProcessResponseResult {
+	score: number
+	feedback: {
+		identifier: string
+		value: string
+	}
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SECTION ITEM REFERENCE
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Reference to an assessment item within a section.
+ */
+interface AssessmentItemRef {
+	identifier: string
+	/**
+	 * Item reference href.
+	 *
+	 * The QTI docs show this field as `string` in most responses, but it can also
+	 * appear as an array (and in one place, a nested array) in request/response
+	 * examples for test-part payloads.
+	 */
+	href?: string | string[] | string[][]
+	sequence?: number
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// SECTION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Assessment section within a test part.
+ */
+interface AssessmentSection {
+	identifier: string
+	title: string
+	visible: boolean
+	required?: boolean
+	fixed?: boolean
+	sequence?: number
+	'qti-assessment-item-ref'?: AssessmentItemRef[]
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// TEST PART
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Test part within an assessment test.
+ */
+interface TestPart {
+	identifier: string
+	navigationMode: NavigationMode
+	submissionMode: SubmissionMode
+	'qti-assessment-section': AssessmentSection | AssessmentSection[]
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ASSESSMENT TEST
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Assessment test entity.
+ */
+interface AssessmentTest {
+	identifier: string
+	title: string
+	qtiVersion: string
+	'qti-test-part': TestPart[]
+	'qti-outcome-declaration': TestOutcomeDeclaration[]
+	timeLimit?: number
+	maxAttempts?: number
+	toolsEnabled?: Record<string, boolean>
+	metadata?: Record<string, unknown>
+	/** Raw QTI XML string */
+	rawXml: string
+	/**
+	 * Parsed XML→JSON content.
+	 * Structure varies by test.
+	 */
+	content: Record<string, unknown>
+	createdAt: string
+	updatedAt: string
+	__v?: number
+	isValidXml?: boolean
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// QUESTIONS RESPONSE
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Question reference within a test.
+ */
+interface QuestionReference {
+	identifier: string
+	href: string
+	testPart: string
+	section: string
+}
+
+/**
+ * Question with full item details.
+ */
+interface QuestionWithItem {
+	reference: QuestionReference
+	question: AssessmentItem
+}
+
+/**
+ * Response from GET /assessment-tests/{identifier}/questions.
+ */
+interface QuestionsResponse {
+	assessmentTest: string
+	title: string
+	totalQuestions: number
+	questions: QuestionWithItem[]
+}
+
+/**
+ * Lesson Types
+ *
+ * Types for QTI lesson and question feedback resources.
+ */
+
+
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// LESSON FEEDBACK
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Lesson feedback entity.
+ */
+interface LessonFeedback {
+	questionId?: string
+	userId: string
+	feedback: string
+	type: FeedbackType
+	lessonId: string
+	humanApproved?: boolean | boolean[]
+}
+
+/**
+ * Stimuli Types
+ *
+ * Types for QTI stimulus resources.
+ */
+
+
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// STIMULUS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Stimulus entity.
+ */
+interface Stimulus {
+	identifier: string
+	title: string
+	label?: string
+	language?: string
+	stylesheet?: Stylesheet
+	catalogInfo: CatalogInfo[]
+	toolName?: string
+	toolVersion?: string
+	metadata?: Record<string, unknown>
+	/** Raw QTI XML string */
+	rawXml: string
+	/**
+	 * Parsed XML→JSON content.
+	 * Structure varies.
+	 */
+	content: Record<string, unknown>
+	createdAt: string
+	updatedAt: string
+	__v?: number
+}
+
+/**
+ * Validation Types
+ *
+ * Types for QTI XML validation resources.
+ */
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Single validation result.
+ */
+interface ValidationResult {
+	success: boolean
+	entityId: string
+	xmlContent: string
+	validationErrors: string[]
+	message: string
+}
+
+/**
+ * Batch validation result.
+ */
+interface BatchValidationResult {
+	results: ValidationResult[]
+}
+
+export type { AssessmentItem, AssessmentItemRef, AssessmentItemType, AssessmentSection, AssessmentTest, BaseType, BatchValidationResult, Cardinality, CatalogInfo, CorrectResponse, DeleteResponse, Difficulty, FeedbackBlock, FeedbackInline, FeedbackType, Grade, InlineFeedback, ItemMetadata, LearningObjectiveSet, LessonFeedback, LessonType, ListResponse, ModalFeedback, NavigationMode, OutcomeDeclaration, PaginationMeta, ProcessResponseResult, QuestionReference, QuestionWithItem, QuestionsResponse, RawPaginatedResponse, ResponseDeclaration, ResponseProcessing, ShowHide, SortOrder, Stimulus, Stylesheet, SubmissionMode, TestOutcomeDeclaration, TestPart, ValidationResult, ValidationSchema };

package/dist/public-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"public-types.d.ts","sourceRoot":"","sources":["../src/public-types.ts"],"names":[],"mappings":"AAAA,cAAc,+BAA+B,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@timeback/qti",
-	"version": "0.1.2",
+	"version": "0.1.4",
 	"type": "module",
 	"exports": {
 		".": {
@@ -12,8 +12,8 @@
 			"import": "./dist/errors.js"
 		},
 		"./types": {
-			"types": "./dist/types.d.ts",
-			"import": "./dist/types.js"
+			"types": "./dist/public-types.d.ts",
+			"import": "./dist/public-types.js"
 		}
 	},
 	"main": "dist/index.js",
@@ -35,7 +35,8 @@
 		"@timeback/internal-test": "0.0.0",
 		"@timeback/internal-utils": "0.0.0",
 		"@timeback/types": "0.0.0",
-		"@types/bun": "latest"
+		"@types/bun": "latest",
+		"esbuild": "^0.27.3"
 	},
 	"peerDependencies": {
 		"typescript": "^5"