@timeback/qti 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -1,30 +1,1409 @@
+import * as _timeback_internal_client_infra from '@timeback/internal-client-infra';
+import { RequestOptions, PaginatedResponse, ClientConfig, TransportOnlyConfig, ProviderClientConfig, Paginator as Paginator$1, ListParams, BaseTransport, BaseTransportConfig, ProviderRegistry, TimebackProvider, AuthCheckResult } from '@timeback/internal-client-infra';
+export { AuthCheckResult, EnvAuth, Environment, ExplicitAuth, ListParams, PageResult } from '@timeback/internal-client-infra';
+
 /**
- * QTI API client SDK for Timeback.
+ * 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'
+}
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// 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'
+
+/**
+ * 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
+}
+
+/**
+ * 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[]
+}
+
+/**
+ * Transport interface for QTI client.
+ *
+ * Required when using transport mode with QtiClient.
+ */
+interface QtiTransportLike {
+    /** Base URL of the API */
+    baseUrl: string;
+    /** Make an authenticated request */
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+    /** Make a paginated request */
+    requestPaginated<T>(path: string, options?: RequestOptions): Promise<PaginatedResponse<T>>;
+}
+/**
+ * All supported QTI client configuration types.
+ *
+ * Supports four modes:
+ * - **Provider mode**: `{ provider: TimebackProvider }` — pre-built provider with token sharing
+ * - **Environment mode**: `{ platform?, env, auth }` — Timeback hosted APIs
+ * - **Explicit mode**: `{ baseUrl, auth: { authUrl } }` — custom API URLs
+ * - **Transport mode**: `{ transport }` — custom transport
+ *
+ * The `platform` field (in env mode) selects which Timeback implementation to use:
+ * - `'BEYOND_AI'` (default): BeyondAI's Timeback platform
+ * - `'LEARNWITH_AI'`: Samy's LearnWith.AI platform
+ */
+type QtiClientConfig = ClientConfig | TransportOnlyConfig<QtiTransportLike> | ProviderClientConfig;
+/**
+ * Instance type of QtiClient.
+ */
+type QtiClientInstance = InstanceType<typeof QtiClient>;
+
+/**
+ * Pagination Utilities
+ *
+ * Re-exports the common Paginator with QTI-specific configuration.
+ */
+
+/**
+ * QTI-specific Paginator that uses page-based pagination.
+ *
+ * QTI APIs use `page` and `limit` params (1-indexed pages) instead of
+ * `offset` and `limit`. The base Paginator handles this via `paginationStyle: 'page'`.
+ *
+ * @typeParam T - The type of items being paginated
+ */
+declare class Paginator<T> extends Paginator$1<T> {
+    /**
+     * Create a new QTI Paginator.
+     *
+     * @param transport - QTI transport instance
+     * @param path - API endpoint path
+     * @param params - List parameters including optional max
+     */
+    constructor(transport: QtiTransportLike, path: string, params?: ListParams);
+}
+
+/**
+ * Transport Layer
+ *
+ * HTTP transport for QTI API communication.
+ */
+
+/**
+ * Configuration for QTI transport.
+ */
+type QtiTransportConfig = BaseTransportConfig;
+/**
+ * HTTP transport layer for QTI API communication.
+ *
+ * Uses body-based pagination with page/limit params.
+ */
+declare class Transport extends BaseTransport {
+    constructor(config: QtiTransportConfig);
+    /**
+     * Make a paginated request using body-based pagination.
+     *
+     * QTI APIs return pagination metadata in the response body:
+     * - `items`: Array of items
+     * - `total`: Total items across all pages
+     * - `pages`: Total number of pages
+     * - `page`: Current page (1-indexed)
+     * - `limit`: Items per page
+     * - `sort`: Sort field
+     * - `order`: Sort order
+     *
+     * @template T - Expected item type in the response
+     * @param path - API endpoint path
+     * @param options - Request options
+     * @returns Normalized paginated response for Paginator compatibility
+     */
+    requestPaginated<T>(path: string, options?: RequestOptions): Promise<PaginatedResponse<T>>;
+}
+
+type input<T> = T extends {
+    _zod: {
+        input: any;
+    };
+} ? T["_zod"]["input"] : unknown;
+
+/**
+ * QTI Schemas
+ *
+ * Strict Zod schemas for QTI-related CLI/API inputs.
+ *
+ * These are intentionally "full-shape" schemas so CLI code can validate input
+ * and then pass typed values directly into the QTI SDK without widening/casting.
+ */
+
+
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// LIST PARAMS
+// ═══════════════════════════════════════════════════════════════════════════════
+
+declare const QtiPaginationParams = z
+	.object({
+		page: z.number().int().positive().optional(),
+		limit: z.number().int().positive().optional(),
+		sort: z.string().optional(),
+		order: z.enum(['asc', 'desc']).optional(),
+	})
+	.strict()
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ASSESSMENT ITEMS (REQUEST INPUTS)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * XML-format creation input.
+ *
+ * The preferred way to create assessment items — send raw QTI 3.0 XML and the
+ * server validates it against IMS QTI XSDs.
+ */
+declare const QtiAssessmentItemXmlCreateInput = z
+	.object({
+		format: z.string().pipe(z.literal('xml')),
+		xml: z.string().min(1),
+		metadata: QtiItemMetadata.optional(),
+	})
+	.strict()
+
+/**
+ * JSON-format creation input (experimental on the server side).
+ *
+ * Sends a structured/parsed representation of a QTI item.
+ */
+declare const QtiAssessmentItemJsonCreateInput = z
+	.object({
+		identifier: z.string().min(1),
+		title: z.string().min(1),
+		type: QtiAssessmentItemType,
+		qtiVersion: z.string().optional(),
+		timeDependent: z.boolean().optional(),
+		adaptive: z.boolean().optional(),
+		responseDeclarations: z.array(QtiResponseDeclaration).optional(),
+		outcomeDeclarations: z.array(QtiOutcomeDeclaration).optional(),
+		responseProcessing: QtiResponseProcessing.optional(),
+		metadata: QtiItemMetadata.optional(),
+		modalFeedback: z.array(QtiModalFeedback).optional(),
+		feedbackInline: z.array(QtiFeedbackInline).optional(),
+		feedbackBlock: z.array(QtiFeedbackBlock).optional(),
+	})
+	.strict()
+
+/**
+ * Union of XML and JSON creation inputs for assessment items.
+ *
+ * Accepts either `{ format: 'xml', xml, metadata? }` or the structured JSON
+ * shape with `{ identifier, title, type, ... }`.
+ */
+declare const QtiAssessmentItemCreateInput = z.union([
+	QtiAssessmentItemXmlCreateInput,
+	QtiAssessmentItemJsonCreateInput,
+])
+
+declare const QtiAssessmentItemUpdateInput = z
+	.object({
+		identifier: z.string().min(1).optional(),
+		title: z.string().min(1),
+		type: QtiAssessmentItemType,
+		qtiVersion: z.string().optional(),
+		timeDependent: z.boolean().optional(),
+		adaptive: z.boolean().optional(),
+		responseDeclarations: z.array(QtiResponseDeclaration).optional(),
+		outcomeDeclarations: z.array(QtiOutcomeDeclaration).optional(),
+		responseProcessing: QtiResponseProcessing.optional(),
+		metadata: QtiItemMetadata.optional(),
+		modalFeedback: z.array(QtiModalFeedback).optional(),
+		feedbackInline: z.array(QtiFeedbackInline).optional(),
+		feedbackBlock: z.array(QtiFeedbackBlock).optional(),
+		rawXml: z.string(),
+		content: z.record(z.string(), z.unknown()),
+	})
+	.strict()
+
+declare const QtiAssessmentItemProcessResponseInput = z
+	.object({
+		response: z.union([z.string(), z.array(z.string())]),
+	})
+	.strict()
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// ASSESSMENT TESTS (REQUEST INPUTS)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+declare const QtiAssessmentItemRef = z
+	.object({
+		identifier: z.string().min(1),
+		href: z.union([z.string(), z.array(z.string()), z.array(z.array(z.string()))]).optional(),
+		sequence: z.number().optional(),
+	})
+	.strict()
+
+declare const QtiAssessmentSection = z
+	.object({
+		identifier: z.string().min(1),
+		title: z.string().min(1),
+		visible: z.boolean(),
+		required: z.boolean().optional(),
+		fixed: z.boolean().optional(),
+		sequence: z.number().optional(),
+		'qti-assessment-item-ref': z.array(QtiAssessmentItemRef).optional(),
+	})
+	.strict()
+
+declare const QtiTestPart = z
+	.object({
+		identifier: z.string().min(1),
+		navigationMode: z.string().pipe(QtiNavigationMode),
+		submissionMode: z.string().pipe(QtiSubmissionMode),
+		'qti-assessment-section': z.array(QtiAssessmentSection),
+	})
+	.strict()
+
+declare const QtiReorderItemsInput = z
+	.object({
+		items: z.array(QtiAssessmentItemRef).min(1),
+	})
+	.strict()
+
+declare const QtiAssessmentTestMetadataUpdateInput = z
+	.object({
+		metadata: z.record(z.string(), z.unknown()).optional(),
+	})
+	.strict()
+
+declare const QtiAssessmentTestCreateInput = z
+	.object({
+		identifier: z.string().min(1),
+		title: z.string().min(1),
+		qtiVersion: z.string().optional(),
+		toolName: z.string().optional(),
+		toolVersion: z.string().optional(),
+		timeLimit: z.number().optional(),
+		maxAttempts: z.number().optional(),
+		toolsEnabled: z.record(z.string(), z.boolean()).optional(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+		'qti-test-part': z.array(QtiTestPart),
+		'qti-outcome-declaration': z.array(QtiTestOutcomeDeclaration).optional(),
+	})
+	.strict()
+
+declare const QtiAssessmentTestUpdateInput = z
+	.object({
+		identifier: z.string().min(1).optional(),
+		title: z.string().min(1),
+		qtiVersion: z.string().optional(),
+		toolName: z.string().optional(),
+		toolVersion: z.string().optional(),
+		timeLimit: z.number().optional(),
+		maxAttempts: z.number().optional(),
+		toolsEnabled: z.record(z.string(), z.boolean()).optional(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+		'qti-test-part': z.array(QtiTestPart),
+		'qti-outcome-declaration': z.array(QtiTestOutcomeDeclaration).optional(),
+	})
+	.strict()
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// STIMULI (REQUEST INPUTS)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+declare const QtiStimulusCreateInput = z
+	.object({
+		identifier: z.string().min(1),
+		title: z.string().min(1),
+		label: z.string().optional(),
+		language: z.string().optional(),
+		stylesheet: QtiStylesheet.optional(),
+		content: z.string(),
+		catalogInfo: z.array(QtiCatalogInfo).optional(),
+		toolName: z.string().optional(),
+		toolVersion: z.string().optional(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+	})
+	.strict()
+
+declare const QtiStimulusUpdateInput = z
+	.object({
+		identifier: z.string().min(1).optional(),
+		title: z.string().min(1),
+		label: z.string().optional(),
+		language: z.string().optional(),
+		stylesheet: QtiStylesheet.optional(),
+		content: z.string(),
+		catalogInfo: z.array(QtiCatalogInfo).optional(),
+		toolName: z.string().optional(),
+		toolVersion: z.string().optional(),
+		metadata: z.record(z.string(), z.unknown()).optional(),
+	})
+	.strict()
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// VALIDATION (REQUEST INPUTS)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+declare const QtiValidateInput = z
+	.object({
+		xml: z.string().optional(),
+		schema: QtiValidationSchema,
+		entityId: z.string().optional(),
+	})
+	.strict()
+
+declare const QtiValidateBatchInput = z
+	.object({
+		xml: z.array(z.string()),
+		schema: QtiValidationSchema,
+		entityIds: z.array(z.string()),
+	})
+	.strict()
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// LESSON FEEDBACK (REQUEST INPUTS)
+// ═══════════════════════════════════════════════════════════════════════════════
+
+declare const QtiLessonFeedbackInput = z
+	.object({
+		questionId: z.string().optional(),
+		userId: z.string().min(1),
+		feedback: z.string().min(1),
+		lessonId: z.string().min(1),
+		humanApproved: z.boolean().optional(),
+	})
+	.strict()
+
+type ListAssessmentTestsParams = input<typeof QtiPaginationParams>
+type ListTestPartsParams = input<typeof QtiPaginationParams>
+type ListSectionsParams = input<typeof QtiPaginationParams>
+type ListAssessmentItemsParams = input<typeof QtiPaginationParams>
+type ListStimuliParams = input<typeof QtiPaginationParams>
+
+type CreateAssessmentTestRequest = input<typeof QtiAssessmentTestCreateInput>
+type UpdateAssessmentTestRequest = input<typeof QtiAssessmentTestUpdateInput>
+type UpdateTestMetadataRequest = input<typeof QtiAssessmentTestMetadataUpdateInput>
+type CreateTestPartRequest = input<typeof QtiTestPart>
+type UpdateTestPartRequest = input<typeof QtiTestPart>
+type CreateSectionRequest = input<typeof QtiAssessmentSection>
+type UpdateSectionRequest = input<typeof QtiAssessmentSection>
+type AddItemRequest = input<typeof QtiAssessmentItemRef>
+type ReorderItemsRequest = input<typeof QtiReorderItemsInput>
+
+type CreateAssessmentItemXmlRequest = input<typeof QtiAssessmentItemXmlCreateInput>
+type CreateAssessmentItemJsonRequest = input<typeof QtiAssessmentItemJsonCreateInput>
+type CreateAssessmentItemRequest = input<typeof QtiAssessmentItemCreateInput>
+type UpdateAssessmentItemRequest = input<typeof QtiAssessmentItemUpdateInput>
+type ProcessResponseRequest = input<typeof QtiAssessmentItemProcessResponseInput>
+
+type CreateStimulusRequest = input<typeof QtiStimulusCreateInput>
+type UpdateStimulusRequest = input<typeof QtiStimulusUpdateInput>
+
+type ValidateRequest = input<typeof QtiValidateInput>
+type ValidateBatchRequest = input<typeof QtiValidateBatchInput>
+
+type SubmitLessonRequest = input<typeof QtiLessonFeedbackInput>
+type SubmitQuestionRequest = input<typeof QtiLessonFeedbackInput>
+
+/**
+ * Assessment Items Resource
+ *
+ * CRUD operations for QTI assessment items.
+ */
+
+/**
+ * Assessment items resource for managing QTI assessment items.
+ *
+ * Provides methods to list, get, create, update, delete items,
+ * and process responses.
+ */
+declare class AssessmentItemsResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * List assessment items with pagination.
+     *
+     * @param params - Pagination and filter parameters
+     * @returns Paginated list of assessment items
+     */
+    list(params?: ListAssessmentItemsParams): Promise<ListResponse<AssessmentItem>>;
+    /**
+     * Stream assessment items with automatic pagination.
+     *
+     * QTI list endpoints use page-based pagination; this returns a Paginator
+     * that converts to the correct `page`/`limit` params.
+     *
+     * @param params - Optional pagination params (offset/limit) + max cap
+     * @returns Paginator for async iteration
+     */
+    stream(params?: ListParams & {
+        max?: number;
+    }): Paginator<AssessmentItem>;
+    /**
+     * Get a single assessment item by identifier.
+     *
+     * @param identifier - Assessment item identifier
+     * @returns The assessment item
+     */
+    get(identifier: string): Promise<AssessmentItem>;
+    /**
+     * Create a new assessment item.
+     *
+     * @param body - Assessment item data
+     * @returns The created assessment item
+     */
+    create(body: CreateAssessmentItemRequest): Promise<AssessmentItem>;
+    /**
+     * Update an assessment item.
+     *
+     * @param identifier - Assessment item identifier
+     * @param body - Updated assessment item data
+     * @returns The updated assessment item
+     */
+    update(identifier: string, body: UpdateAssessmentItemRequest): Promise<AssessmentItem>;
+    /**
+     * Delete an assessment item.
+     *
+     * @param identifier - Assessment item identifier
+     * @returns Delete response
+     */
+    delete(identifier: string): Promise<DeleteResponse>;
+    /**
+     * Process a response for an assessment item.
+     *
+     * Validates and scores the response against the item's correct answer.
+     *
+     * @param identifier - Assessment item identifier
+     * @param body - Response to process
+     * @returns Score and feedback
+     */
+    processResponse(identifier: string, body: Omit<ProcessResponseRequest, 'identifier'>): Promise<ProcessResponseResult>;
+    /**
+     * Create an assessment item from raw QTI 3.0 XML.
+     *
+     * This is the preferred creation method — the server validates the XML
+     * against IMS QTI XSDs. Optionally include metadata (subject, grade, etc.).
+     *
+     * @param body - XML string and optional metadata
+     * @returns The created assessment item
+     *
+     * @example
+     * ```typescript
+     * const item = await client.assessmentItems.createFromXml({
+     *   format: 'xml',
+     *   xml: '<qti-assessment-item ...>...</qti-assessment-item>',
+     *   metadata: { subject: 'Math', difficulty: 'easy' },
+     * })
+     * ```
+     */
+    createFromXml(body: CreateAssessmentItemXmlRequest): Promise<AssessmentItem>;
+    /**
+     * Create an assessment item from metadata.
+     *
+     * Alternative creation endpoint that accepts metadata-focused input.
+     *
+     * @param body - Assessment item metadata
+     * @returns The created assessment item
+     */
+    createFromMetadata(body: CreateAssessmentItemJsonRequest): Promise<AssessmentItem>;
+}
+
+/**
+ * Assessment Tests Resource
+ *
+ * CRUD operations for QTI assessment tests including nested test parts,
+ * sections, and items.
+ */
+
+/**
+ * Helper for managing items within a section.
+ */
+declare class SectionItemsHelper {
+    private readonly transport;
+    private readonly testId;
+    private readonly testPartId;
+    private readonly sectionId;
+    constructor(transport: Transport, testId: string, testPartId: string, sectionId: string);
+    /**
+     * Add an item to the section.
+     *
+     * @param body - Item reference data
+     * @returns The updated section
+     */
+    add(body: AddItemRequest): Promise<AssessmentSection>;
+    /**
+     * Remove an item from the section.
+     *
+     * @param itemIdentifier - Item identifier to remove
+     * @returns Delete response
+     */
+    remove(itemIdentifier: string): Promise<DeleteResponse>;
+    /**
+     * Reorder items in the section.
+     *
+     * @param body - New item order
+     * @returns The updated section
+     */
+    reorder(body: ReorderItemsRequest): Promise<AssessmentSection>;
+}
+/**
+ * Helper for managing sections within a test part.
+ */
+declare class TestPartSectionsHelper {
+    private readonly transport;
+    private readonly testId;
+    private readonly testPartId;
+    constructor(transport: Transport, testId: string, testPartId: string);
+    /**
+     * List sections in a test part.
+     *
+     * @param params - Pagination parameters
+     * @returns Paginated list of sections
+     */
+    list(params?: ListSectionsParams): Promise<ListResponse<AssessmentSection>>;
+    /**
+     * Get a section by identifier.
+     *
+     * @param identifier - Section identifier
+     * @returns The section
+     */
+    get(identifier: string): Promise<AssessmentSection>;
+    /**
+     * Create a new section.
+     *
+     * @param body - Section data
+     * @returns The created section
+     */
+    create(body: CreateSectionRequest): Promise<AssessmentSection>;
+    /**
+     * Update a section.
+     *
+     * @param identifier - Section identifier
+     * @param body - Updated section data
+     * @returns The updated section
+     */
+    update(identifier: string, body: UpdateSectionRequest): Promise<AssessmentSection>;
+    /**
+     * Delete a section.
+     *
+     * @param identifier - Section identifier
+     * @returns Delete response
+     */
+    delete(identifier: string): Promise<DeleteResponse>;
+    /**
+     * Get items helper for a specific section.
+     *
+     * @param sectionId - Section identifier
+     * @returns Items helper
+     */
+    items(sectionId: string): SectionItemsHelper;
+}
+/**
+ * Helper for managing test parts within an assessment test.
+ */
+declare class AssessmentTestPartsHelper {
+    private readonly transport;
+    private readonly testId;
+    constructor(transport: Transport, testId: string);
+    /**
+     * List test parts.
+     *
+     * @param params - Pagination parameters
+     * @returns Paginated list of test parts
+     */
+    list(params?: ListTestPartsParams): Promise<ListResponse<TestPart>>;
+    /**
+     * Get a test part by identifier.
+     *
+     * @param identifier - Test part identifier
+     * @returns The test part
+     */
+    get(identifier: string): Promise<TestPart>;
+    /**
+     * Create a new test part.
+     *
+     * @param body - Test part data
+     * @returns The created test part
+     */
+    create(body: CreateTestPartRequest): Promise<TestPart>;
+    /**
+     * Update a test part.
+     *
+     * @param identifier - Test part identifier
+     * @param body - Updated test part data
+     * @returns The updated test part
+     */
+    update(identifier: string, body: UpdateTestPartRequest): Promise<TestPart>;
+    /**
+     * Delete a test part.
+     *
+     * @param identifier - Test part identifier
+     * @returns Delete response
+     */
+    delete(identifier: string): Promise<DeleteResponse>;
+    /**
+     * Get sections helper for a specific test part.
+     *
+     * @param testPartId - Test part identifier
+     * @returns Sections helper
+     */
+    sections(testPartId: string): TestPartSectionsHelper;
+}
+/**
+ * Assessment tests resource for managing QTI assessment tests.
+ *
+ * Provides methods to list, get, create, update, delete tests,
+ * and access nested test parts, sections, and items.
+ */
+declare class AssessmentTestsResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * List assessment tests with pagination.
+     *
+     * @param params - Pagination and filter parameters
+     * @returns Paginated list of assessment tests
+     */
+    list(params?: ListAssessmentTestsParams): Promise<ListResponse<AssessmentTest>>;
+    /**
+     * Stream assessment tests with automatic pagination.
+     *
+     * @param params - Optional pagination params (offset/limit) + max cap
+     * @returns Paginator for async iteration
+     */
+    stream(params?: ListParams & {
+        max?: number;
+    }): Paginator<AssessmentTest>;
+    /**
+     * Get a single assessment test by identifier.
+     *
+     * @param identifier - Assessment test identifier
+     * @returns The assessment test
+     */
+    get(identifier: string): Promise<AssessmentTest>;
+    /**
+     * Create a new assessment test.
+     *
+     * @param body - Assessment test data
+     * @returns The created assessment test
+     */
+    create(body: CreateAssessmentTestRequest): Promise<AssessmentTest>;
+    /**
+     * Update an assessment test.
+     *
+     * @param identifier - Assessment test identifier
+     * @param body - Updated assessment test data
+     * @returns The updated assessment test
+     */
+    update(identifier: string, body: UpdateAssessmentTestRequest): Promise<AssessmentTest>;
+    /**
+     * Delete an assessment test.
+     *
+     * @param identifier - Assessment test identifier
+     * @returns Delete response
+     */
+    delete(identifier: string): Promise<DeleteResponse>;
+    /**
+     * Update test metadata.
+     *
+     * @param identifier - Assessment test identifier
+     * @param body - Metadata to update
+     * @returns The updated assessment test
+     */
+    updateMetadata(identifier: string, body: UpdateTestMetadataRequest): Promise<AssessmentTest>;
+    /**
+     * Get all questions from an assessment test.
+     *
+     * Returns the full item details for each question referenced in the test.
+     *
+     * @param identifier - Assessment test identifier
+     * @returns Questions with their full item details
+     */
+    getQuestions(identifier: string): Promise<QuestionsResponse>;
+    /**
+     * Get test parts helper for a specific test.
+     *
+     * @param testId - Assessment test identifier
+     * @returns Test parts helper
+     */
+    testParts(testId: string): AssessmentTestPartsHelper;
+}
+
+/**
+ * General Resource
+ *
+ * General QTI endpoints that don't fit into other resources.
+ */
+
+/**
+ * General resource for miscellaneous QTI operations.
+ *
+ * Provides methods for general operations like delete-by-id.
+ */
+declare class GeneralResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Delete any entity by its ID.
+     *
+     * This is a general delete endpoint that can remove any QTI entity.
+     *
+     * @param id - Entity identifier
+     * @returns Delete confirmation message
+     */
+    deleteById(id: string): Promise<DeleteResponse>;
+}
+
+/**
+ * Lesson Resource
+ *
+ * Lesson and question feedback endpoints.
+ */
+
+/**
+ * Lesson resource for managing lesson and question feedback.
+ *
+ * Provides methods to submit and retrieve lesson/question feedback.
+ */
+declare class LessonResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Submit lesson feedback.
+     *
+     * @param body - Lesson feedback data
+     * @returns The created feedback
+     */
+    submitLesson(body: SubmitLessonRequest): Promise<LessonFeedback>;
+    /**
+     * Get lesson feedback by lesson ID.
+     *
+     * @param lessonId - Lesson identifier
+     * @returns The lesson feedback
+     */
+    getLesson(lessonId: string): Promise<LessonFeedback>;
+    /**
+     * Submit question feedback.
+     *
+     * @param body - Question feedback data
+     * @returns The created feedback
+     */
+    submitQuestion(body: SubmitQuestionRequest): Promise<LessonFeedback>;
+}
+
+/**
+ * Stimuli Resource
+ *
+ * CRUD operations for QTI stimuli.
+ */
+
+/**
+ * Stimuli resource for managing QTI stimulus materials.
+ *
+ * Provides methods to list, get, create, update, and delete stimuli.
+ */
+declare class StimuliResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * List stimuli with pagination.
+     *
+     * @param params - Pagination and filter parameters
+     * @returns Paginated list of stimuli
+     */
+    list(params?: ListStimuliParams): Promise<ListResponse<Stimulus>>;
+    /**
+     * Stream stimuli with automatic pagination.
+     *
+     * @param params - Optional pagination params (offset/limit) + max cap
+     * @returns Paginator for async iteration
+     */
+    stream(params?: ListParams & {
+        max?: number;
+    }): Paginator<Stimulus>;
+    /**
+     * Get a single stimulus by identifier.
+     *
+     * @param identifier - Stimulus identifier
+     * @returns The stimulus
+     */
+    get(identifier: string): Promise<Stimulus>;
+    /**
+     * Create a new stimulus.
+     *
+     * @param body - Stimulus data
+     * @returns The created stimulus
+     */
+    create(body: CreateStimulusRequest): Promise<Stimulus>;
+    /**
+     * Update a stimulus.
+     *
+     * @param identifier - Stimulus identifier
+     * @param body - Updated stimulus data
+     * @returns The updated stimulus
+     */
+    update(identifier: string, body: UpdateStimulusRequest): Promise<Stimulus>;
+    /**
+     * Delete a stimulus.
+     *
+     * @param identifier - Stimulus identifier
+     * @returns Delete response
+     */
+    delete(identifier: string): Promise<DeleteResponse>;
+}
+
+/**
+ * Validate Resource
+ *
+ * QTI XML validation endpoints.
+ */
+
+/**
+ * Validation resource for checking QTI XML validity.
+ *
+ * Provides methods to validate single items or batch validate multiple items.
+ */
+declare class ValidateResource {
+    private readonly transport;
+    constructor(transport: Transport);
+    /**
+     * Validate a single QTI XML document.
+     *
+     * @param body - Validation request with XML and schema type
+     * @returns Validation result
+     */
+    validate(body: ValidateRequest): Promise<ValidationResult>;
+    /**
+     * Validate multiple QTI XML documents in batch.
+     *
+     * @param body - Batch validation request
+     * @returns Batch validation results
+     */
+    batch(body: ValidateBatchRequest): Promise<BatchValidationResult>;
+}
+
+/**
+ * QTI Client
+ *
+ * Main entry point for the QTI SDK.
+ */
+/**
+ * QTI API client for assessment content management.
+ *
+ * Provides access to QTI endpoints including assessment items, tests,
+ * stimuli, validation, and lesson feedback.
  *
  * @example
  * ```typescript
  * // Environment mode (Timeback APIs)
- * import { QtiClient } from '@timeback/qti'
- *
  * const client = new QtiClient({
- *   env: 'staging',
+ *   env: 'staging', // or 'production'
  *   auth: {
  *     clientId: 'your-client-id',
  *     clientSecret: 'your-client-secret',
  *   },
  * })
+ * ```
  *
- * // List assessment items
- * const { items, total, page, pages } = await client.assessmentItems.list()
- *
- * // Get a specific item
- * const item = await client.assessmentItems.get('item-123')
+ * @example
+ * ```typescript
+ * // Provider mode (shared tokens)
+ * import { TimebackProvider } from '@timeback/internal-client-infra'
  *
- * // Validate XML
- * const result = await client.validate.validate({
- *   schema: 'item',
- *   xml: '<qti-assessment-item>...</qti-assessment-item>',
+ * const provider = new TimebackProvider({
+ *   platform: 'BEYOND_AI',
+ *   env: 'staging',
+ *   auth: { clientId: '...', clientSecret: '...' },
  * })
+ *
+ * const client = new QtiClient({ provider })
  * ```
  *
  * @example
@@ -39,12 +1418,73 @@
  *   },
  * })
  * ```
+ *
+ * @example
+ * ```typescript
+ * // Environment variables fallback
+ * // Set QTI_BASE_URL, QTI_TOKEN_URL,
+ * // QTI_CLIENT_ID, QTI_CLIENT_SECRET
+ * const client = new QtiClient()
+ * ```
+ */
+declare const QtiClient: {
+    new (config?: QtiClientConfig): {
+        readonly transport: QtiTransportLike;
+        readonly _provider?: _timeback_internal_client_infra.TimebackProvider | undefined;
+        readonly assessmentItems: AssessmentItemsResource;
+        readonly assessmentTests: AssessmentTestsResource;
+        readonly stimuli: StimuliResource;
+        readonly validate: ValidateResource;
+        readonly lesson: LessonResource;
+        readonly general: GeneralResource;
+        getTransport(): QtiTransportLike;
+        checkAuth(): Promise<_timeback_internal_client_infra.AuthCheckResult>;
+    };
+};
+
+/**
+ * QTI Client Factory
+ *
+ * Creates QtiClient classes bound to specific provider registries.
+ */
+
+/**
+ * Create a QtiClient class bound to a specific provider registry.
+ *
+ * @param registry - Provider registry to use (defaults to all Timeback platforms)
+ * @returns QtiClient class bound to the registry
  */
-export { QtiClient, type QtiClientInstance } from './client';
-export { createQtiClient } from './factory';
-export type { QtiClientConfig } from './types/client';
-export type { Environment, EnvAuth, ExplicitAuth } from './types/client';
-export type { AuthCheckResult, ListParams, PageResult } from '@timeback/internal-client-infra';
-export type { AssessmentItem, AssessmentItemType, AssessmentTest, ListResponse, Stimulus, ValidationResult, } from './types';
-export { Paginator, Transport } from './lib';
-//# sourceMappingURL=index.d.ts.map
+declare function createQtiClient(registry?: ProviderRegistry): {
+    new (config?: QtiClientConfig): {
+        /** @internal */
+        readonly transport: QtiTransportLike;
+        /** @internal */
+        readonly _provider?: TimebackProvider | undefined;
+        /** Query and manage assessment items (questions) */
+        readonly assessmentItems: AssessmentItemsResource;
+        /** Query and manage assessment tests with nested test parts, sections, and items */
+        readonly assessmentTests: AssessmentTestsResource;
+        /** Query and manage stimulus materials (passages, images, etc.) */
+        readonly stimuli: StimuliResource;
+        /** Validate QTI XML documents */
+        readonly validate: ValidateResource;
+        /** Submit and retrieve lesson/question feedback */
+        readonly lesson: LessonResource;
+        /** General operations like delete-by-id */
+        readonly general: GeneralResource;
+        /**
+         * Get the underlying transport for advanced use cases.
+         * @returns The transport instance used by this client
+         */
+        getTransport(): QtiTransportLike;
+        /**
+         * Verify that OAuth authentication is working.
+         * @returns Auth check result
+         * @throws {Error} If client was initialized with custom transport (no provider)
+         */
+        checkAuth(): Promise<AuthCheckResult>;
+    };
+};
+
+export { Paginator, QtiClient, Transport, createQtiClient };
+export type { AssessmentItem, AssessmentItemType, AssessmentTest, ListResponse, QtiClientConfig, QtiClientInstance, Stimulus, ValidationResult };