@more-ink/irt-edge 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# @more-ink/irt-edge
+
+## 1.2.0
+
+### Minor Changes
+
+- Add generic type parameter support for type-safe skill identifiers
+
+  The SDK now supports generic type parameters (`TSkillId`) for compile-time type safety, following the same pattern as @more-ink/irt-core. This enables:
+
+  - Type-safe skill identifiers with TypeScript union types or enums
+  - IDE autocomplete for skill names
+  - Compile-time validation preventing invalid skill identifiers
+  - 100% backward compatible (defaults to `string`)
+
+  Example usage:
+
+  ```typescript
+  type MySkills = "grammar" | "vocabulary" | "listening";
+  const client = new IrtClient<MySkills>({ baseUrl: "..." });
+
+  // TypeScript ensures skillId is valid at compile time
+  await client.recordAnswer({
+    userId: "user123",
+    skillId: "grammar", // ✅ Type-checked
+    itemId: "item456",
+    score: 0.8,
+  });
+  ```
+
+  All SDK types now support the generic parameter:
+
+  - `IrtClient<TSkillId>`
+  - `RecordAnswerRequest<TSkillId>`
+  - `RecordAnswerResponse<TSkillId>`
+  - `SelectNextItemRequest<TSkillId>`
+  - `SelectNextItemResponse<TSkillId>`
+  - `UserStateResponse<TSkillId>`
+  - `ItemStateResponse<TSkillId>`
+  - And all other related types
+
+## 1.1.0
+
+### Minor Changes
+
+- Initial SDK release: Add lightweight API client for JavaScript/TypeScript frontends
+
+  - New `IrtClient` class for consuming IRT Edge API
+  - Full TypeScript support with type definitions
+  - Complete API methods: recordAnswer, selectNextItem, getUserState, getItemState, health
+  - Zero runtime dependencies (only peer dependency on @more-ink/irt-core)
+  - Comprehensive documentation and examples
+  - Backend server code remains private (not published to npm)
+
+## 1.0.0
+
+### Major Changes
+
+- First major release
+
+### Patch Changes
+
+- Updated dependencies
+  - @more-ink/irt-core@1.0.0

package/README.md

@@ -1,20 +1,209 @@
 # @more-ink/irt-edge
 
-Production HTTP API server for the streaming IRT engine, built with Hono for deployment on Aliyun Function Compute.
+**Two packages in one:**
+1. **SDK** - Lightweight API client for JavaScript/TypeScript frontends (published to npm)
+2. **Backend Server** - Production HTTP API server built with Hono for Aliyun Function Compute (not published)
 
-## Features
+---
+
+## Table of Contents
+
+- [SDK Usage (Frontend)](#sdk-usage-frontend)
+  - [Installation](#installation)
+  - [Quick Start](#quick-start)
+  - [Configuration](#configuration)
+  - [API Methods](#api-methods)
+  - [Error Handling](#error-handling)
+  - [Best Practices](#best-practices)
+- [Backend Server Setup](#backend-server-setup)
+- [Backend Deployment](#backend-deployment-aliyun-fc)
+- [SDK Publishing](#sdk-publishing-npm)
+- [Package Scripts](#package-scripts)
+
+---
+
+## SDK Usage (Frontend)
+
+### Installation
+
+```bash
+npm install @more-ink/irt-edge @more-ink/irt-core
+# or
+pnpm add @more-ink/irt-edge @more-ink/irt-core
+# or
+yarn add @more-ink/irt-edge @more-ink/irt-core
+```
+
+**Note:** `@more-ink/irt-core` is a peer dependency that provides type definitions.
+
+### Quick Start
+
+```typescript
+import { IrtClient } from '@more-ink/irt-edge'
+
+const client = new IrtClient({
+  baseUrl: 'https://your-api.example.com',
+  headers: {
+    'Authorization': 'Bearer YOUR_TOKEN' // Optional
+  },
+  timeout: 10000 // Optional (default: 10000ms)
+})
+
+// Record an answer and get the next item
+const result = await client.recordAnswer({
+  userId: 'user123',
+  skillId: 'math',
+  itemId: 'item456',
+  score: 0.8,
+  timestamp: Date.now()
+})
+
+console.log('Updated ability:', result.theta)
+console.log('Next item:', result.nextItem)
+```
+
+### Configuration
+
+#### IrtClientConfig
+
+```typescript
+interface IrtClientConfig {
+  baseUrl: string                      // API server base URL (required)
+  headers?: Record<string, string>     // Custom headers (e.g., auth tokens)
+  timeout?: number                     // Request timeout in ms (default: 10000)
+}
+```
+
+### API Methods
+
+#### recordAnswer()
+
+Record a user's response and get the next recommended item.
+
+```typescript
+async recordAnswer(params: RecordAnswerRequest): Promise<RecordAnswerResponse>
+```
+
+**Parameters:**
+```typescript
+interface RecordAnswerRequest {
+  userId: string          // User identifier
+  skillId: string         // Skill identifier
+  itemId: string          // Item identifier
+  score: number           // Response score [0,1] (0=wrong, 1=correct)
+  timestamp?: number      // When response occurred (ms)
+  updateOptions?: Partial<UpdateOptions>      // Override learning rates
+  selectionOptions?: Partial<NextItemOptions> // Override selection behavior
+}
+```
+
+**Returns:** Updated ability (theta), standard error (se), next item, and updated states.
+
+**Example:**
+```typescript
+const result = await client.recordAnswer({
+  userId: 'alice',
+  skillId: 'geometry',
+  itemId: 'q100',
+  score: 1.0,
+  timestamp: Date.now()
+})
+
+console.log(`Ability: ${result.theta.toFixed(2)} ± ${result.se.toFixed(2)}`)
+if (result.nextItem) {
+  console.log(`Next question: ${result.nextItem.id}`)
+}
+```
+
+#### selectNextItem()
+
+Get the next recommended item without recording a response.
+
+```typescript
+async selectNextItem(params: SelectNextItemRequest): Promise<SelectNextItemResponse>
+```
+
+#### getUserState() / getUserStates()
+
+Get current user ability estimates.
+
+```typescript
+async getUserState(userId: string, skillId: string): Promise<UserStateResponse>
+async getUserStates(userId: string): Promise<UserStatesResponse>
+```
+
+#### getItemState() / getItemStates()
+
+Get item parameters and metadata.
+
+```typescript
+async getItemState(itemId: string, skillId: string): Promise<ItemStateResponse>
+async getItemStates(itemId: string): Promise<ItemStatesResponse>
+```
+
+#### health()
+
+Check API server health status.
+
+```typescript
+async health(): Promise<HealthResponse>
+```
+
+See `examples/sdk-usage.ts` for complete working examples.
+
+### Error Handling
+
+All methods throw errors for network failures, HTTP errors, timeouts, and invalid responses.
+
+```typescript
+try {
+  const result = await client.recordAnswer({...})
+  // Handle success
+} catch (error) {
+  if (error instanceof Error) {
+    console.error('API error:', error.message)
+    if (error.message.includes('timeout')) {
+      // Retry logic
+    }
+  }
+}
+```
+
+### Best Practices
+
+1. **Reuse client instances** - Create one client and reuse it
+2. **Use timestamps** - Always provide client-side timestamps for accurate analytics
+3. **Handle errors gracefully** - Show user-friendly messages on errors
+4. **Check for null items** - The API may return `null` if no suitable item is available
+
+```typescript
+const result = await client.selectNextItem({...})
+if (result.nextItem) {
+  // Show item to user
+} else {
+  // No more items available
+}
+```
+
+---
+
+## Backend Server Setup
+
+The backend server is **not published** to npm. It runs as a service on Aliyun Function Compute.
+
+### Features
 
 - RESTful IRT API with Redis storage (Upstash)
 - Aliyun FC lifecycle hooks (`/initialize`, `/pre-stop`)
 - Graceful shutdown and health checks
 
-## Quick Start
+### Development Setup
 
 ```bash
 # From repo root
 pnpm install
 
-# Create .env file
+# Create .env file with:
 # UPSTASH_REDIS_REST_URL=https://...
 # UPSTASH_REDIS_REST_TOKEN=...
 
@@ -25,53 +214,181 @@ pnpm --filter @more-ink/irt-edge dev
 pnpm --filter @more-ink/irt-edge seed
 ```
 
-## Deployment
+### Backend Environment Variables
 
-To deploy to Aliyun FC from the repo root, run:
-
-```bash
-pnpm --filter @more-ink/irt-edge run deploy
-```
-or
 ```bash
-pnpm dp
-```
+# Aliyun Function Compute
+ALIYUN_ACCESS_KEY="YOUR_ALIYUN_ACCESS_KEY"
+ALIYUN_SECRET_ACCESS_KEY="YOUR_ALIYUN_SECRET_KEY"
 
-### How Deployment Works
+# Upstash Redis
+UPSTASH_REDIS_URL_DK="https://upstash-redis-dk.duoink.co"
+UPSTASH_REDIS_TOKEN_DK="YOUR_UPSTASH_TOKEN"
+
+# Feishu (Lark) Integration
+FEISHU_APP_ID="YOUR_FEISHU_APP_ID"
+FEISHU_APP_SECRET="YOUR_FEISHU_APP_SECRET"
+FEISHU_CHAT_ID="YOUR_FEISHU_CHAT_ID"
 
-The deploy process handles pnpm's symlinked `node_modules` by:
-1. Building TypeScript to `dist/`
-2. Running `pnpm deploy --prod` to create `deploy-output/` with flat, real `node_modules` (no symlinks)
-3. Uploading from `deploy-output/` as an FC layer
+# Optional Redis fallback
+REDIS_URL=""
+REDIS_DB=2
 
-This ensures all dependencies are included in the layer, not just symlinks to pnpm's store.
+# Debug mode for Function Compute
+DEBUG_FC="true"
 
-## API Endpoints
+# Server port (optional, default: 9000)
+PORT=9000
+```
 
-### IRT Operations
+See `src/index.ts` for default IRT engine parameters (learning rates, selection options).
+
+### API Endpoints
+
+**IRT Operations:**
 - `POST /api/irt/answer` - Record response and get next item
 - `POST /api/irt/next-item` - Get next item without recording response
 - `GET /api/irt/health` - Health check
 
-### Aliyun FC Lifecycle
+**Aliyun FC Lifecycle:**
 - `POST /initialize` - Instance startup (verifies Redis)
 - `GET /pre-stop` - Instance shutdown (closes Redis)
 
-### System
+**System:**
 - `GET /` - Service info
 
-## Environment Variables
+---
+
+## Backend Deployment (Aliyun FC)
+
+Deploy the backend server to Aliyun FC:
 
 ```bash
-UPSTASH_REDIS_URL_DK=https://...
-UPSTASH_REDIS_TOKEN_DK=...
-ALIYUN_ACCESS_KEY=...
-ALIYUN_SECRET_ACCESS_KEY=...
-FEISHU_APP_ID=...
-FEISHU_APP_SECRET=...
-FEISHU_CHAT_ID=...
-PORT=9000  # optional
+pnpm --filter @more-ink/irt-edge run deploy
+# or from root
+pnpm dp
 ```
 
-See `src/index.ts` for default IRT engine parameters (learning rates, selection options).
+### How Deployment Works
+
+The deploy process handles pnpm's symlinked `node_modules`:
+1. Build TypeScript to `dist/`
+2. Run `pnpm deploy --prod` to create `deploy-output/` with flat `node_modules`
+3. Upload from `deploy-output/` as an FC layer
+
+This ensures all dependencies are included, not just symlinks to pnpm's store.
+
+---
+
+## SDK Publishing (npm)
+
+Publish the SDK to npm (backend code stays private):
+
+```bash
+# From repo root (recommended)
+pnpm pub
+
+# Or from package directory
+cd packages/irt-edge
+pnpm publish:sdk
+
+# Or using npm directly
+npm publish --access public
+```
+
+### What Gets Published
+
+**Published to npm:**
+- ✅ `sdk/` - Compiled SDK code (~40KB unpacked)
+- ✅ `README.md`, `CHANGELOG.md` - Documentation
+- ✅ `examples/` - Usage examples
+- ✅ `package.json` - Package metadata
+
+**NOT published (stays private):**
+- ❌ Backend server code (`src/index.ts`, `routes.ts`, `storage/`)
+- ❌ Scripts and tests (`scripts/`, `tests/`)
+- ❌ Config files (`.env`, `tsconfig.json`, etc.)
+- ❌ Backend build output (`dist/`, `deploy-output/`)
+
+The `.npmignore` file ensures only SDK files are published.
+
+### Publishing Checklist
+
+Before publishing:
+
+1. **Version Management**
+   - Update version in `package.json` (follow [semver](https://semver.org/))
+   - Update `CHANGELOG.md` with changes
+
+2. **Code Quality**
+   - Build SDK: `pnpm build:sdk`
+   - Run tests: `pnpm test`
+   - Check TypeScript: `tsc -p tsconfig.sdk.json --noEmit`
+
+3. **Verify Package**
+   - Dry-run: `npm pack --dry-run`
+   - Check package size (<50KB)
+   - Verify only SDK files included
+
+4. **Publish**
+   - `pnpm pub` (auto-builds before publishing)
+
+5. **Post-Publishing**
+   - Verify on npm: https://www.npmjs.com/package/@more-ink/irt-edge
+   - Tag release: `git tag v1.0.0 && git push origin v1.0.0`
+   - Create GitHub release
+
+### Test Installation
+
+```bash
+mkdir /tmp/test-irt-sdk && cd /tmp/test-irt-sdk
+npm init -y
+npm install @more-ink/irt-edge @more-ink/irt-core
+node -e "const { IrtClient } = require('@more-ink/irt-edge'); console.log('OK')"
+```
+
+---
+
+## Package Scripts
+
+### Development & Backend
+- `pnpm dev` - Run dev server with hot reload
+- `pnpm build` - Build backend server to `dist/`
+- `pnpm start` - Start production backend server
+- `pnpm seed` - Seed Redis with test data
+- `pnpm deploy` - Deploy backend to Aliyun FC
+
+### SDK Publishing
+- `pnpm build:sdk` - Build SDK to `sdk/`
+- `pnpm publish:sdk` - Build and publish SDK to npm
+- `pnpm pub` - Shortcut for `pnpm publish:sdk` (from root)
+
+### Testing
+- `pnpm test` - Run test suite
+- `pnpm test:watch` - Run tests in watch mode
+
+---
+
+## Architecture
+
+```
+irt-edge/
+├── src/
+│   ├── sdk/              # ✅ SDK source (published)
+│   │   ├── types.ts      # Type definitions
+│   │   ├── client.ts     # IrtClient class
+│   │   └── index.ts      # Public exports
+│   ├── index.ts          # ❌ Backend server (not published)
+│   ├── routes.ts         # ❌ Backend routes
+│   └── storage/          # ❌ Backend storage layer
+├── sdk/                  # ✅ Compiled SDK (published)
+├── dist/                 # ❌ Backend build (not published)
+├── examples/             # ✅ SDK examples (published)
+├── tsconfig.json         # Backend build config
+└── tsconfig.sdk.json     # SDK build config
+```
+
+## License
+
+Proprietary - All Rights Reserved
 

package/examples/sdk-usage.ts

@@ -0,0 +1,111 @@
+/**
+ * Example usage of the @more-ink/irt-edge SDK
+ * 
+ * This demonstrates how frontend applications can consume the IRT Edge API,
+ * including type-safe skill identifiers.
+ */
+
+import { IrtClient } from '../sdk/index'
+
+// Define your app's skill types for compile-time type safety
+type AppSkills = 'math-algebra' | 'math-geometry' | 'reading' | 'writing'
+
+async function main() {
+  // Initialize the client with type-safe skills
+  const client = new IrtClient<AppSkills>({
+    baseUrl: 'http://localhost:9000',
+    headers: {
+      // Add any authentication headers here if needed
+      // 'Authorization': 'Bearer YOUR_TOKEN'
+    },
+    timeout: 10000, // 10 seconds
+  })
+
+  try {
+    // 1. Check API health
+    console.log('=== Health Check ===')
+    const health = await client.health()
+    console.log('API Status:', health)
+    console.log()
+
+    // 2. Record an answer and get the next item
+    console.log('=== Record Answer & Get Next Item ===')
+    const answerResult = await client.recordAnswer({
+      userId: 'demo-user-001',
+      skillId: 'math-algebra',
+      itemId: 'question-42',
+      score: 0.8, // 80% correct
+      timestamp: Date.now(),
+      // Optional: override default update/selection options
+      updateOptions: {
+        thetaLR: 0.05,
+        aLR: 0.001,
+        bLR: 0.01,
+      },
+      selectionOptions: {
+        topKRandomize: 5,
+        explorationChance: 0.1,
+      },
+    })
+
+    console.log('Updated Ability (theta):', answerResult.theta.toFixed(3))
+    console.log('Standard Error (SE):', answerResult.se.toFixed(3))
+    console.log('Next Item:', answerResult.nextItem)
+    console.log()
+
+    // 3. Get current user state
+    console.log('=== Get User State ===')
+    const userState = await client.getUserState('demo-user-001', 'math-algebra')
+    console.log('Current Theta:', userState.user.theta.toFixed(3))
+    console.log('Information Sum:', userState.user.infoSum.toFixed(3))
+    console.log('Standard Error:', userState.se.toFixed(3))
+    console.log()
+
+    // 4. Get all skill states for a user
+    console.log('=== Get All User Skills ===')
+    const allUserStates = await client.getUserStates('demo-user-001')
+    console.log(`User has ${allUserStates.count} skill(s):`)
+    allUserStates.skills.forEach(skill => {
+      console.log(`  - ${skill.user.skillId}: theta=${skill.user.theta.toFixed(3)}, se=${skill.se.toFixed(3)}`)
+    })
+    console.log()
+
+    // 5. Select next item without recording a response
+    console.log('=== Select Next Item (without answer) ===')
+    const nextItem = await client.selectNextItem({
+      userId: 'demo-user-001',
+      skillId: 'math-algebra',
+      selectionOptions: {
+        topKRandomize: 3,
+        explorationChance: 0.15,
+      },
+    })
+
+    console.log('User Theta:', nextItem.user?.theta.toFixed(3))
+    console.log('Recommended Item:', nextItem.nextItem)
+    console.log()
+
+    // 6. Get item state
+    if (nextItem.nextItem) {
+      console.log('=== Get Item State ===')
+      const itemState = await client.getItemState(
+        nextItem.nextItem.id,
+        'math-algebra'
+      )
+      console.log('Item Parameters:')
+      console.log('  - Discrimination (a):', itemState.a.toFixed(3))
+      console.log('  - Difficulty (b):', itemState.b.toFixed(3))
+      console.log('  - Times Seen:', itemState.timesSeen)
+      console.log()
+    }
+
+    console.log('✅ All operations completed successfully!')
+
+  } catch (error) {
+    console.error('❌ Error:', error instanceof Error ? error.message : error)
+    process.exit(1)
+  }
+}
+
+// Run the example
+main()

package/package.json

@@ -1,27 +1,40 @@
 {
   "name": "@more-ink/irt-edge",
-  "version": "1.0.0",
-  "description": "Edge-function wrapper around the node-irt core library.",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "version": "1.2.0",
+  "description": "IRT Edge API client SDK for JavaScript/TypeScript frontends.",
+  "main": "sdk/index.js",
+  "types": "sdk/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./sdk/index.d.ts",
+      "import": "./sdk/index.js",
+      "require": "./sdk/index.js"
+    }
+  },
   "files": [
-    "dist"
+    "sdk",
+    "README.md",
+    "CHANGELOG.md",
+    "examples"
   ],
-  "dependencies": {
-    "@hono/node-server": "^1.19.6",
-    "hono": "^4.10.7",
-    "ioredis": "^5.8.2",
-    "@more-ink/irt-core": "1.0.0"
+  "peerDependencies": {
+    "@more-ink/irt-core": "^1.0.0"
   },
+  "dependencies": {},
   "devDependencies": {
+    "@hono/node-server": "^1.19.6",
     "@larksuiteoapi/node-sdk": "^1.55.0",
     "@upstash/redis": "^1.35.7",
     "dotenv": "^16.6.1",
     "fc-deploy": "^1.2.3",
-    "tslib": "^2.8.1"
+    "hono": "^4.10.7",
+    "ioredis": "^5.8.2",
+    "tslib": "^2.8.1",
+    "@more-ink/irt-core": "1.0.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
+    "build:sdk": "tsc -p tsconfig.sdk.json",
     "start": "node dist/index.js",
     "test": "vitest run",
     "test:watch": "vitest watch",