@telebort/question-banks 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Telebort Engineering
+
+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/README.md

@@ -0,0 +1,415 @@
+# @telebort/exit-tickets
+
+Exit Tickets SDK for Telebort educational assessments. Provides Zod schemas, validation clients, and full question access through a three-tier architecture.
+
+## Installation
+
+```bash
+npm install @telebort/exit-tickets zod
+```
+
+## Three-Tier Architecture
+
+| Tier | Access | Use Case |
+|------|--------|----------|
+| **Free** | Zod schemas | Offline validation, type safety |
+| **Standard** | Validation API | SaaS validation without answer exposure |
+| **Premium** | Full access + grading | LMS integration, misconception analysis |
+
+---
+
+## Free Tier - Schemas
+
+Import Zod schemas for offline validation. No API calls required.
+
+```typescript
+import { QuestionSchema, AssessmentSubmissionSchema } from '@telebort/exit-tickets/schemas'
+import { z } from 'zod'
+
+// Validate a question
+const result = QuestionSchema.safeParse(myQuestion)
+if (!result.success) {
+  console.error(result.error.issues)
+}
+
+// Type inference
+type Question = z.infer<typeof QuestionSchema>
+type Assessment = z.infer<typeof AssessmentSubmissionSchema>
+```
+
+### Available Schemas
+
+```typescript
+// Question schemas
+QuestionSchema          // Full question with v1.1 enhancements
+OptionSchema            // Answer option with misconception tracking
+FeedbackSchema          // Structured feedback (short/detailed/socraticHint)
+
+// Course schemas
+CourseSchema            // Course with lessons and questions
+LessonSchema            // Lesson with questions
+
+// Assessment schemas
+AssessmentSubmissionSchema  // User assessment submission
+GradedAssessmentSchema      // Graded result with misconception analysis
+ValidationResultSchema      // Schema validation result (no answers)
+```
+
+---
+
+## Standard Tier - Validation API
+
+Validate assessments without exposing correct answers. Requires API key.
+
+```typescript
+import { ValidationClient } from '@telebort/exit-tickets/validation'
+
+const client = new ValidationClient({
+  apiKey: 'sk_test_...',
+  baseUrl: 'https://api.telebort.com/exit-tickets/v1' // optional
+})
+
+// Validate an assessment
+const result = await client.validateAssessment({
+  courseId: 'ai-1',
+  lessonId: 'ai-1-lesson-1',
+  responses: [
+    { questionId: 'ai-1-l1-q1', selectedAnswer: 'B' },
+    { questionId: 'ai-1-l1-q2', selectedAnswer: 'A' }
+  ],
+  submittedAt: new Date().toISOString()
+})
+
+console.log(result)
+// { valid: true, isComplete: true, questionCount: 2, answeredCount: 2 }
+
+// Offline validation (no API call)
+const offlineResult = client.validateOffline(assessment)
+```
+
+### Rate Limits
+
+| Tier | Requests/minute |
+|------|-----------------|
+| Standard | 100 |
+
+---
+
+## Premium Tier - Full Access
+
+Full question access, grading, and misconception analysis. Requires JWT.
+
+```typescript
+import { PremiumClient } from '@telebort/exit-tickets/premium'
+
+const client = new PremiumClient({
+  token: 'eyJhbGciOiJIUzI1NiIs...',
+  baseUrl: 'https://api.telebort.com/exit-tickets/v1'
+})
+
+// Get questions with full content
+const { questions } = await client.getQuestions({
+  courseId: 'ai-1',
+  lessonNumber: 1
+})
+
+// Get all courses
+const courses = await client.getCourses()
+
+// Grade an assessment
+const result = await client.gradeAssessment({
+  courseId: 'ai-1',
+  responses: [
+    { questionId: 'ai-1-l1-q1', selectedAnswer: 'B' },
+    { questionId: 'ai-1-l1-q2', selectedAnswer: 'A' }
+  ],
+  submittedAt: new Date().toISOString()
+})
+
+console.log(result)
+// {
+//   score: 50,
+//   passed: false,
+//   correctCount: 1,
+//   incorrectCount: 1,
+//   misconceptions: [{ misconceptionId: 'INPUT_PROMPT_VS_OUTPUT', count: 1 }],
+//   responses: [...]
+// }
+
+// Get statistics
+const stats = await client.getStatistics()
+```
+
+### Rate Limits
+
+| Tier | Requests/minute |
+|------|-----------------|
+| Premium | 1000 |
+
+---
+
+## CDN Mode (Recommended for Dynamic Updates)
+
+Fetch questions from CDN for automatic updates without redeploying your app:
+
+```typescript
+import { createExitTicketsSDK } from '@telebort/exit-tickets'
+
+const CDN_BASE = 'https://content-warehouse.vercel.app/exit-tickets'
+
+const sdk = createExitTicketsSDK({
+  dataSource: {
+    async loadCourses() {
+      const res = await fetch(`${CDN_BASE}/v1.0/full/all.json`)
+      const data = await res.json()
+      return data.courses
+    }
+  }
+})
+
+// All SDK features work:
+const courses = await sdk.data.getCourses()
+const quiz = await sdk.quiz.generateQuiz({ questionCount: 5 })
+const result = await sdk.validate.checkAnswer('ai-1-l1-q1', 'B', 'formative')
+```
+
+**CDN Endpoints:** (Base: `https://content-warehouse.vercel.app`)
+- `GET /exit-tickets/v1.0/index.json` - Course catalog (6KB)
+- `GET /exit-tickets/v1.0/courses/AI1.json` - Single course (~400KB)
+- `GET /exit-tickets/v1.0/full/all.json` - All 17 courses (3.5MB)
+
+---
+
+## Static Mode (Bundled JSON)
+
+For offline-first apps, bundle the JSON with your app:
+
+```typescript
+import { createExitTicketsSDK } from '@telebort/exit-tickets'
+
+// Option 1: Fetch from local static exports
+const sdk = createExitTicketsSDK({
+  dataSource: {
+    async loadCourses() {
+      const res = await fetch('/exports/v1.0/full/all.json')
+      const data = await res.json()
+      return data.courses
+    }
+  }
+})
+
+// Option 2: Import bundled JSON (with bundler support)
+import coursesData from '../exit-tickets-api/exports/v1.0/full/all.json'
+
+const sdk = createExitTicketsSDK({
+  dataSource: {
+    async loadCourses() {
+      return coursesData.courses
+    }
+  }
+})
+
+// All SDK features work locally:
+const courses = await sdk.data.getCourses()           // ✅ Works
+const quiz = await sdk.quiz.generateQuiz({ questionCount: 5 }) // ✅ Works
+const result = await sdk.validate.checkAnswer(...)     // ✅ Works
+```
+
+> **Note:** `ValidationClient` and `PremiumClient` require an API endpoint. For static deployments, use the SDK Factory instead—it provides all the same features client-side.
+
+---
+
+## SDK Factory - Custom Data Source
+
+For self-hosted deployments or custom data sources:
+
+```typescript
+import { createExitTicketsSDK } from '@telebort/exit-tickets'
+import coursesData from './data/courses.json'
+
+const sdk = createExitTicketsSDK({
+  dataSource: {
+    async loadCourses() {
+      return coursesData // Or fetch from your own API
+    }
+  }
+})
+
+// Now use SDK methods
+const courses = await sdk.data.getCourses()
+const questions = await sdk.query.filterQuestions({ courseId: 'ai-1' })
+const quiz = await sdk.quiz.generateQuiz({ questionCount: 10 })
+const result = await sdk.validate.checkAnswer('ai-1-l1-q1', 'B', 'formative')
+```
+
+### SDK Interface
+
+```typescript
+interface ExitTicketsSDK {
+  data: {
+    getCourses(): Promise<Course[]>
+    getCourse(courseId: string): Promise<Course | null>
+    getLesson(courseId: string, lessonNumber: number): Promise<Lesson | null>
+    getQuestion(questionId: string): Promise<Question | null>
+    getAllQuestions(): Promise<Question[]>
+  }
+
+  query: {
+    filterQuestions(filters: QuestionFilters): Promise<QueryResult<Question>>
+    getRandomQuestions(count: number, filters?: QuestionFilters): Promise<Question[]>
+  }
+
+  quiz: {
+    generateQuiz(criteria: QuizCriteria): Promise<{ questions: Question[]; metadata: object }>
+    getLessonQuiz(courseId: string, lessonNumber: number): Promise<Question[]>
+  }
+
+  search: {
+    search(options: SearchOptions): Promise<QueryResult<Question>>
+    searchByTags(tags: string[], matchAll?: boolean): Promise<Question[]>
+  }
+
+  analytics: {
+    getStatistics(): Promise<Statistics>
+    getCourseStatistics(courseId: string): Promise<Statistics>
+  }
+
+  validate: {
+    checkAnswer(questionId: string, answer: string, mode: 'formative' | 'summative'): Promise<ValidationResult>
+  }
+}
+```
+
+---
+
+## CLI Tools
+
+The SDK includes command-line tools for working with exit ticket data:
+
+```bash
+# Install globally
+npm install -g @telebort/exit-tickets
+
+# Or use via npx
+npx @telebort/exit-tickets <command>
+```
+
+### Commands
+
+#### `validate` - Validate Course JSON Files
+
+```bash
+# Validate a single file
+exit-tickets validate ./data/courses/ai-1.json
+
+# Validate all files in a directory
+exit-tickets validate ./data/courses/
+
+# Show all validation errors (not just first 5)
+exit-tickets validate ./data/courses/ --verbose
+```
+
+#### `stats` - Show Statistics
+
+```bash
+# Show aggregate statistics across all courses
+exit-tickets stats --data-dir ./data/courses/
+
+# Show statistics for a specific course
+exit-tickets stats --course ai-1 --data-dir ./data/courses/
+
+# Output as JSON
+exit-tickets stats --json --data-dir ./data/courses/
+```
+
+#### `quiz` - Generate Sample Quizzes
+
+```bash
+# Generate 5 random questions
+exit-tickets quiz --data-dir ./data/courses/
+
+# Generate 10 questions from a specific course
+exit-tickets quiz --course ai-1 --count 10 --data-dir ./data/courses/
+
+# Filter by difficulty and show answers
+exit-tickets quiz --difficulty hard --show-answers --data-dir ./data/courses/
+
+# Output as JSON (for integration)
+exit-tickets quiz --count 20 --json --data-dir ./data/courses/
+```
+
+---
+
+## Question Schema (v1.1)
+
+> ⚠️ **Preview Feature**: v1.1 misconception tracking is currently available for ~5 questions (AI-1 only). Full course migration to v1.1 is planned. Questions without v1.1 data will have `misconceptionTargets: undefined` and options without feedback.
+
+Questions include v1.1 enhancements for misconception tracking:
+
+```typescript
+interface Question {
+  questionId: string           // "ai-1-l1-q1"
+  globalId: string             // "exit-ticket-0351"
+  questionType: QuestionType   // vocabulary, code_understanding, etc.
+  questionArchetype?: string   // vocabulary, trace, bebras, blockmodel
+
+  prompt: string
+  hasCodeBlock: boolean
+  codeLanguage: string | null
+  codeContent: string | null
+
+  // v1.1: Misconception targeting
+  misconceptionTargets?: string[]
+
+  options: Option[]            // 4 options with misconception feedback
+  correctAnswer: 'A' | 'B' | 'C' | 'D'
+
+  metadata: {
+    difficulty: 'easy' | 'medium' | 'hard' | 'challenge'
+    bloomsTaxonomy: 'remember' | 'understand' | 'apply' | ...
+    tags: string[]
+  }
+}
+
+interface Option {
+  key: 'A' | 'B' | 'C' | 'D'
+  text: string
+  isCorrect: boolean
+
+  // v1.1: Misconception feedback
+  misconceptionId?: string     // "INPUT_PROMPT_VS_OUTPUT"
+  feedback?: {
+    short: string              // "Not quite! That's the prompt."
+    detailed: string           // Full explanation
+    socraticHint?: string      // "Where does the program display its result?"
+  }
+}
+```
+
+---
+
+## TypeScript Support
+
+All types are inferred from Zod schemas:
+
+```typescript
+import type {
+  Question,
+  Course,
+  AssessmentSubmission,
+  GradedAssessment
+} from '@telebort/exit-tickets'
+```
+
+---
+
+## License
+
+MIT
+
+---
+
+## Support
+
+- Issues: [GitHub Issues](https://github.com/telebort/exit-tickets-sdk/issues)
+- Documentation: [API Docs](https://docs.telebort.com/exit-tickets)

package/bin/question-banks.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+/**
+ * Exit Tickets CLI - Binary Shim
+ *
+ * This file is the entry point for the `exit-tickets` command.
+ * It loads and executes the compiled CLI module.
+ */
+
+// Use dynamic import for ESM compatibility
+import('../dist/cli/index.js')
+  .then(({ run }) => run())
+  .catch((error) => {
+    console.error('Failed to start CLI:', error.message)
+    process.exit(2)
+  })