@more-ink/irt-edge 1.1.0 → 1.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +46 -0
- package/examples/sdk-usage.ts +7 -3
- package/package.json +1 -1
- package/sdk/client.d.ts +27 -10
- package/sdk/client.d.ts.map +1 -1
- package/sdk/client.js +21 -4
- package/sdk/client.js.map +1 -1
- package/sdk/index.d.ts +21 -1
- package/sdk/index.d.ts.map +1 -1
- package/sdk/index.js +21 -1
- package/sdk/index.js.map +1 -1
- package/sdk/types.d.ts +105 -22
- package/sdk/types.d.ts.map +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,51 @@
|
|
|
1
1
|
# @more-ink/irt-edge
|
|
2
2
|
|
|
3
|
+
## 1.2.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- Improve SDK typings with comprehensive JSDoc on every request and response shape, clarifying field semantics for IDE hovers and generated docs.
|
|
8
|
+
|
|
9
|
+
## 1.2.0
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- Add generic type parameter support for type-safe skill identifiers
|
|
14
|
+
|
|
15
|
+
The SDK now supports generic type parameters (`TSkillId`) for compile-time type safety, following the same pattern as @more-ink/irt-core. This enables:
|
|
16
|
+
|
|
17
|
+
- Type-safe skill identifiers with TypeScript union types or enums
|
|
18
|
+
- IDE autocomplete for skill names
|
|
19
|
+
- Compile-time validation preventing invalid skill identifiers
|
|
20
|
+
- 100% backward compatible (defaults to `string`)
|
|
21
|
+
|
|
22
|
+
Example usage:
|
|
23
|
+
|
|
24
|
+
```typescript
|
|
25
|
+
type MySkills = "grammar" | "vocabulary" | "listening";
|
|
26
|
+
const client = new IrtClient<MySkills>({ baseUrl: "..." });
|
|
27
|
+
|
|
28
|
+
// TypeScript ensures skillId is valid at compile time
|
|
29
|
+
await client.recordAnswer({
|
|
30
|
+
userId: "user123",
|
|
31
|
+
skillId: "grammar", // ✅ Type-checked
|
|
32
|
+
itemId: "item456",
|
|
33
|
+
score: 0.8,
|
|
34
|
+
});
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
All SDK types now support the generic parameter:
|
|
38
|
+
|
|
39
|
+
- `IrtClient<TSkillId>`
|
|
40
|
+
- `RecordAnswerRequest<TSkillId>`
|
|
41
|
+
- `RecordAnswerResponse<TSkillId>`
|
|
42
|
+
- `SelectNextItemRequest<TSkillId>`
|
|
43
|
+
- `SelectNextItemResponse<TSkillId>`
|
|
44
|
+
- `UserStateResponse<TSkillId>`
|
|
45
|
+
- `ItemStateResponse<TSkillId>`
|
|
46
|
+
- And all other related types
|
|
47
|
+
|
|
48
|
+
|
|
3
49
|
## 1.1.0
|
|
4
50
|
|
|
5
51
|
### Minor Changes
|
package/examples/sdk-usage.ts
CHANGED
|
@@ -1,14 +1,18 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Example usage of the @more-ink/irt-edge SDK
|
|
3
3
|
*
|
|
4
|
-
* This demonstrates how frontend applications can consume the IRT Edge API
|
|
4
|
+
* This demonstrates how frontend applications can consume the IRT Edge API,
|
|
5
|
+
* including type-safe skill identifiers.
|
|
5
6
|
*/
|
|
6
7
|
|
|
7
8
|
import { IrtClient } from '../sdk/index'
|
|
8
9
|
|
|
10
|
+
// Define your app's skill types for compile-time type safety
|
|
11
|
+
type AppSkills = 'math-algebra' | 'math-geometry' | 'reading' | 'writing'
|
|
12
|
+
|
|
9
13
|
async function main() {
|
|
10
|
-
// Initialize the client
|
|
11
|
-
const client = new IrtClient({
|
|
14
|
+
// Initialize the client with type-safe skills
|
|
15
|
+
const client = new IrtClient<AppSkills>({
|
|
12
16
|
baseUrl: 'http://localhost:9000',
|
|
13
17
|
headers: {
|
|
14
18
|
// Add any authentication headers here if needed
|
package/package.json
CHANGED
package/sdk/client.d.ts
CHANGED
|
@@ -4,17 +4,26 @@ import type { IrtClientConfig, RecordAnswerRequest, RecordAnswerResponse, Select
|
|
|
4
4
|
*
|
|
5
5
|
* Lightweight client for consuming the IRT Edge API from JavaScript/TypeScript frontends.
|
|
6
6
|
*
|
|
7
|
+
* @typeParam TSkillId - Type for skill identifiers (defaults to string for backward compatibility)
|
|
8
|
+
*
|
|
7
9
|
* @example
|
|
8
10
|
* ```ts
|
|
11
|
+
* // Basic usage (string skills)
|
|
9
12
|
* const client = new IrtClient({
|
|
10
13
|
* baseUrl: 'https://your-api.example.com',
|
|
11
14
|
* headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
|
|
12
15
|
* })
|
|
13
16
|
*
|
|
17
|
+
* // Type-safe usage with skill enum
|
|
18
|
+
* type MySkills = 'grammar' | 'vocabulary' | 'listening'
|
|
19
|
+
* const typedClient = new IrtClient<MySkills>({
|
|
20
|
+
* baseUrl: 'https://your-api.example.com'
|
|
21
|
+
* })
|
|
22
|
+
*
|
|
14
23
|
* // Record an answer and get the next item
|
|
15
|
-
* const result = await
|
|
24
|
+
* const result = await typedClient.recordAnswer({
|
|
16
25
|
* userId: 'user123',
|
|
17
|
-
* skillId: '
|
|
26
|
+
* skillId: 'grammar', // ✅ Type-checked
|
|
18
27
|
* itemId: 'item456',
|
|
19
28
|
* score: 0.8
|
|
20
29
|
* })
|
|
@@ -23,7 +32,7 @@ import type { IrtClientConfig, RecordAnswerRequest, RecordAnswerResponse, Select
|
|
|
23
32
|
* console.log('Next item:', result.nextItem)
|
|
24
33
|
* ```
|
|
25
34
|
*/
|
|
26
|
-
export declare class IrtClient {
|
|
35
|
+
export declare class IrtClient<TSkillId = string> {
|
|
27
36
|
private readonly baseUrl;
|
|
28
37
|
private readonly headers;
|
|
29
38
|
private readonly timeout;
|
|
@@ -38,14 +47,14 @@ export declare class IrtClient {
|
|
|
38
47
|
* @param params - Answer recording parameters
|
|
39
48
|
* @returns Updated user state, standard error, and next item
|
|
40
49
|
*/
|
|
41
|
-
recordAnswer(params: RecordAnswerRequest): Promise<RecordAnswerResponse
|
|
50
|
+
recordAnswer(params: RecordAnswerRequest<TSkillId>): Promise<RecordAnswerResponse<TSkillId>>;
|
|
42
51
|
/**
|
|
43
52
|
* Select the next item for a user without recording a response
|
|
44
53
|
*
|
|
45
54
|
* @param params - Next item selection parameters
|
|
46
55
|
* @returns User state and next item
|
|
47
56
|
*/
|
|
48
|
-
selectNextItem(params: SelectNextItemRequest): Promise<SelectNextItemResponse
|
|
57
|
+
selectNextItem(params: SelectNextItemRequest<TSkillId>): Promise<SelectNextItemResponse<TSkillId>>;
|
|
49
58
|
/**
|
|
50
59
|
* Get current user skill state for a specific skill
|
|
51
60
|
*
|
|
@@ -53,14 +62,14 @@ export declare class IrtClient {
|
|
|
53
62
|
* @param skillId - Skill identifier
|
|
54
63
|
* @returns User state with standard error
|
|
55
64
|
*/
|
|
56
|
-
getUserState(userId: string, skillId:
|
|
65
|
+
getUserState(userId: string, skillId: TSkillId): Promise<UserStateResponse<TSkillId>>;
|
|
57
66
|
/**
|
|
58
67
|
* Get all skill states for a user
|
|
59
68
|
*
|
|
60
69
|
* @param userId - User identifier
|
|
61
70
|
* @returns All user skill states with standard errors
|
|
62
71
|
*/
|
|
63
|
-
getUserStates(userId: string): Promise<UserStatesResponse
|
|
72
|
+
getUserStates(userId: string): Promise<UserStatesResponse<TSkillId>>;
|
|
64
73
|
/**
|
|
65
74
|
* Get item parameters for a specific skill
|
|
66
75
|
*
|
|
@@ -68,14 +77,14 @@ export declare class IrtClient {
|
|
|
68
77
|
* @param skillId - Skill identifier
|
|
69
78
|
* @returns Item parameters and metadata
|
|
70
79
|
*/
|
|
71
|
-
getItemState(itemId: string, skillId:
|
|
80
|
+
getItemState(itemId: string, skillId: TSkillId): Promise<ItemStateResponse<TSkillId>>;
|
|
72
81
|
/**
|
|
73
82
|
* Get all skill instances for an item
|
|
74
83
|
*
|
|
75
84
|
* @param itemId - Item identifier
|
|
76
85
|
* @returns All item instances across skills
|
|
77
86
|
*/
|
|
78
|
-
getItemStates(itemId: string): Promise<ItemStatesResponse
|
|
87
|
+
getItemStates(itemId: string): Promise<ItemStatesResponse<TSkillId>>;
|
|
79
88
|
/**
|
|
80
89
|
* Check API health status
|
|
81
90
|
*
|
|
@@ -86,15 +95,23 @@ export declare class IrtClient {
|
|
|
86
95
|
/**
|
|
87
96
|
* Factory function to create an IRT client instance
|
|
88
97
|
*
|
|
98
|
+
* @typeParam TSkillId - Type for skill identifiers (defaults to string)
|
|
89
99
|
* @param config - Client configuration
|
|
90
100
|
* @returns Configured IRT client
|
|
91
101
|
*
|
|
92
102
|
* @example
|
|
93
103
|
* ```ts
|
|
104
|
+
* // Basic usage
|
|
94
105
|
* const client = createIrtClient({
|
|
95
106
|
* baseUrl: 'https://your-api.example.com'
|
|
96
107
|
* })
|
|
108
|
+
*
|
|
109
|
+
* // Type-safe skills
|
|
110
|
+
* type Skills = 'math' | 'reading' | 'science'
|
|
111
|
+
* const typedClient = createIrtClient<Skills>({
|
|
112
|
+
* baseUrl: 'https://your-api.example.com'
|
|
113
|
+
* })
|
|
97
114
|
* ```
|
|
98
115
|
*/
|
|
99
|
-
export declare function createIrtClient(config: IrtClientConfig): IrtClient
|
|
116
|
+
export declare function createIrtClient<TSkillId = string>(config: IrtClientConfig): IrtClient<TSkillId>;
|
|
100
117
|
//# sourceMappingURL=client.d.ts.map
|
package/sdk/client.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/sdk/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EAEf,MAAM,SAAS,CAAA;AAEhB
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/sdk/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EAEf,MAAM,SAAS,CAAA;AAEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,SAAS,CAAC,QAAQ,GAAG,MAAM;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;gBAEpB,MAAM,EAAE,eAAe;IASnC;;OAEG;YACW,OAAO;IAgDrB;;;;;OAKG;IACG,YAAY,CAAC,MAAM,EAAE,mBAAmB,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAOlG;;;;;OAKG;IACG,cAAc,CAAC,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,sBAAsB,CAAC,QAAQ,CAAC,CAAC;IAOxG;;;;;;OAMG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAI3F;;;;;OAKG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAI1E;;;;;;OAMG;IACG,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAI3F;;;;;OAKG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAI1E;;;;OAIG;IACG,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;CAGxC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,eAAe,CAAC,QAAQ,GAAG,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,SAAS,CAAC,QAAQ,CAAC,CAE/F"}
|
package/sdk/client.js
CHANGED
|
@@ -7,17 +7,26 @@ exports.createIrtClient = createIrtClient;
|
|
|
7
7
|
*
|
|
8
8
|
* Lightweight client for consuming the IRT Edge API from JavaScript/TypeScript frontends.
|
|
9
9
|
*
|
|
10
|
+
* @typeParam TSkillId - Type for skill identifiers (defaults to string for backward compatibility)
|
|
11
|
+
*
|
|
10
12
|
* @example
|
|
11
13
|
* ```ts
|
|
14
|
+
* // Basic usage (string skills)
|
|
12
15
|
* const client = new IrtClient({
|
|
13
16
|
* baseUrl: 'https://your-api.example.com',
|
|
14
17
|
* headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
|
|
15
18
|
* })
|
|
16
19
|
*
|
|
20
|
+
* // Type-safe usage with skill enum
|
|
21
|
+
* type MySkills = 'grammar' | 'vocabulary' | 'listening'
|
|
22
|
+
* const typedClient = new IrtClient<MySkills>({
|
|
23
|
+
* baseUrl: 'https://your-api.example.com'
|
|
24
|
+
* })
|
|
25
|
+
*
|
|
17
26
|
* // Record an answer and get the next item
|
|
18
|
-
* const result = await
|
|
27
|
+
* const result = await typedClient.recordAnswer({
|
|
19
28
|
* userId: 'user123',
|
|
20
|
-
* skillId: '
|
|
29
|
+
* skillId: 'grammar', // ✅ Type-checked
|
|
21
30
|
* itemId: 'item456',
|
|
22
31
|
* score: 0.8
|
|
23
32
|
* })
|
|
@@ -110,7 +119,7 @@ class IrtClient {
|
|
|
110
119
|
* @returns User state with standard error
|
|
111
120
|
*/
|
|
112
121
|
async getUserState(userId, skillId) {
|
|
113
|
-
return this.request(`/api/irt/users/${encodeURIComponent(userId)}/${encodeURIComponent(skillId)}`);
|
|
122
|
+
return this.request(`/api/irt/users/${encodeURIComponent(userId)}/${encodeURIComponent(String(skillId))}`);
|
|
114
123
|
}
|
|
115
124
|
/**
|
|
116
125
|
* Get all skill states for a user
|
|
@@ -129,7 +138,7 @@ class IrtClient {
|
|
|
129
138
|
* @returns Item parameters and metadata
|
|
130
139
|
*/
|
|
131
140
|
async getItemState(itemId, skillId) {
|
|
132
|
-
return this.request(`/api/irt/items/${encodeURIComponent(itemId)}/${encodeURIComponent(skillId)}`);
|
|
141
|
+
return this.request(`/api/irt/items/${encodeURIComponent(itemId)}/${encodeURIComponent(String(skillId))}`);
|
|
133
142
|
}
|
|
134
143
|
/**
|
|
135
144
|
* Get all skill instances for an item
|
|
@@ -153,14 +162,22 @@ exports.IrtClient = IrtClient;
|
|
|
153
162
|
/**
|
|
154
163
|
* Factory function to create an IRT client instance
|
|
155
164
|
*
|
|
165
|
+
* @typeParam TSkillId - Type for skill identifiers (defaults to string)
|
|
156
166
|
* @param config - Client configuration
|
|
157
167
|
* @returns Configured IRT client
|
|
158
168
|
*
|
|
159
169
|
* @example
|
|
160
170
|
* ```ts
|
|
171
|
+
* // Basic usage
|
|
161
172
|
* const client = createIrtClient({
|
|
162
173
|
* baseUrl: 'https://your-api.example.com'
|
|
163
174
|
* })
|
|
175
|
+
*
|
|
176
|
+
* // Type-safe skills
|
|
177
|
+
* type Skills = 'math' | 'reading' | 'science'
|
|
178
|
+
* const typedClient = createIrtClient<Skills>({
|
|
179
|
+
* baseUrl: 'https://your-api.example.com'
|
|
180
|
+
* })
|
|
164
181
|
* ```
|
|
165
182
|
*/
|
|
166
183
|
function createIrtClient(config) {
|
package/sdk/client.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/sdk/client.ts"],"names":[],"mappings":";;;
|
|
1
|
+
{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/sdk/client.ts"],"names":[],"mappings":"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"}
|
package/sdk/index.d.ts
CHANGED
|
@@ -2,8 +2,9 @@
|
|
|
2
2
|
* @more-ink/irt-edge - API Client SDK
|
|
3
3
|
*
|
|
4
4
|
* Lightweight client for consuming the IRT Edge API from JavaScript/TypeScript frontends.
|
|
5
|
+
* Supports generic type parameters for type-safe skill identifiers.
|
|
5
6
|
*
|
|
6
|
-
* @example
|
|
7
|
+
* @example Basic usage (string skills)
|
|
7
8
|
* ```ts
|
|
8
9
|
* import { IrtClient } from '@more-ink/irt-edge'
|
|
9
10
|
*
|
|
@@ -19,6 +20,25 @@
|
|
|
19
20
|
* score: 0.8
|
|
20
21
|
* })
|
|
21
22
|
* ```
|
|
23
|
+
*
|
|
24
|
+
* @example Type-safe skills
|
|
25
|
+
* ```ts
|
|
26
|
+
* import { IrtClient } from '@more-ink/irt-edge'
|
|
27
|
+
*
|
|
28
|
+
* type MySkills = 'grammar' | 'vocabulary' | 'listening'
|
|
29
|
+
*
|
|
30
|
+
* const client = new IrtClient<MySkills>({
|
|
31
|
+
* baseUrl: 'https://your-api.example.com'
|
|
32
|
+
* })
|
|
33
|
+
*
|
|
34
|
+
* // TypeScript ensures skillId is one of MySkills
|
|
35
|
+
* const result = await client.recordAnswer({
|
|
36
|
+
* userId: 'user123',
|
|
37
|
+
* skillId: 'grammar', // ✅ Type-checked at compile time
|
|
38
|
+
* itemId: 'item456',
|
|
39
|
+
* score: 0.8
|
|
40
|
+
* })
|
|
41
|
+
* ```
|
|
22
42
|
*/
|
|
23
43
|
export { IrtClient, createIrtClient } from './client';
|
|
24
44
|
export type { IrtClientConfig, RecordAnswerRequest, RecordAnswerResponse, SelectNextItemRequest, SelectNextItemResponse, UserStateResponse, UserStatesResponse, ItemStateResponse, ItemStatesResponse, HealthResponse, ApiResponse, GetUserStateRequest, GetUserStatesRequest, GetItemStateRequest, GetItemStatesRequest, } from './types';
|
package/sdk/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/sdk/index.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/sdk/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AAEH,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACrD,YAAY,EACV,eAAe,EACf,mBAAmB,EACnB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,cAAc,EACd,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,SAAS,CAAA;AAGhB,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,eAAe,GAChB,MAAM,oBAAoB,CAAA"}
|
package/sdk/index.js
CHANGED
|
@@ -3,8 +3,9 @@
|
|
|
3
3
|
* @more-ink/irt-edge - API Client SDK
|
|
4
4
|
*
|
|
5
5
|
* Lightweight client for consuming the IRT Edge API from JavaScript/TypeScript frontends.
|
|
6
|
+
* Supports generic type parameters for type-safe skill identifiers.
|
|
6
7
|
*
|
|
7
|
-
* @example
|
|
8
|
+
* @example Basic usage (string skills)
|
|
8
9
|
* ```ts
|
|
9
10
|
* import { IrtClient } from '@more-ink/irt-edge'
|
|
10
11
|
*
|
|
@@ -20,6 +21,25 @@
|
|
|
20
21
|
* score: 0.8
|
|
21
22
|
* })
|
|
22
23
|
* ```
|
|
24
|
+
*
|
|
25
|
+
* @example Type-safe skills
|
|
26
|
+
* ```ts
|
|
27
|
+
* import { IrtClient } from '@more-ink/irt-edge'
|
|
28
|
+
*
|
|
29
|
+
* type MySkills = 'grammar' | 'vocabulary' | 'listening'
|
|
30
|
+
*
|
|
31
|
+
* const client = new IrtClient<MySkills>({
|
|
32
|
+
* baseUrl: 'https://your-api.example.com'
|
|
33
|
+
* })
|
|
34
|
+
*
|
|
35
|
+
* // TypeScript ensures skillId is one of MySkills
|
|
36
|
+
* const result = await client.recordAnswer({
|
|
37
|
+
* userId: 'user123',
|
|
38
|
+
* skillId: 'grammar', // ✅ Type-checked at compile time
|
|
39
|
+
* itemId: 'item456',
|
|
40
|
+
* score: 0.8
|
|
41
|
+
* })
|
|
42
|
+
* ```
|
|
23
43
|
*/
|
|
24
44
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
25
45
|
exports.createIrtClient = exports.IrtClient = void 0;
|
package/sdk/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/sdk/index.ts"],"names":[],"mappings":";AAAA
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/sdk/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;;;AAEH,mCAAqD;AAA5C,mGAAA,SAAS,OAAA;AAAE,yGAAA,eAAe,OAAA"}
|
package/sdk/types.d.ts
CHANGED
|
@@ -2,73 +2,156 @@
|
|
|
2
2
|
* Type definitions for the IRT Edge API SDK
|
|
3
3
|
*/
|
|
4
4
|
import type { UserSkillState, ItemWithMetadata, UpdateOptions, NextItemOptions } from '@more-ink/irt-core';
|
|
5
|
-
|
|
5
|
+
/**
|
|
6
|
+
* Payload for recording a learner's response to an item.
|
|
7
|
+
* @template TSkillId Identifier type for skills (defaults to string).
|
|
8
|
+
*/
|
|
9
|
+
export interface RecordAnswerRequest<TSkillId = string> {
|
|
10
|
+
/** Unique learner identifier (stable across sessions). */
|
|
6
11
|
userId: string;
|
|
7
|
-
|
|
12
|
+
/** Skill that the item targets (`RS.fluency`, `RS`, etc.). */
|
|
13
|
+
skillId: TSkillId;
|
|
14
|
+
/** Unique item identifier supplied by the content pipeline. */
|
|
8
15
|
itemId: string;
|
|
16
|
+
/** Observed performance score in [0, 1] or scaled equivalent. */
|
|
9
17
|
score: number;
|
|
18
|
+
/** Optional event timestamp (ms). Defaults to `Date.now()` on server. */
|
|
10
19
|
timestamp?: number;
|
|
20
|
+
/** Optional overrides for the IRT update (learning rate, clamps, etc.). */
|
|
11
21
|
updateOptions?: Partial<UpdateOptions>;
|
|
22
|
+
/** Optional overrides for the follow-up item selection call. */
|
|
12
23
|
selectionOptions?: Partial<NextItemOptions>;
|
|
13
24
|
}
|
|
14
|
-
|
|
25
|
+
/**
|
|
26
|
+
* Request payload for fetching the next recommended item for a skill.
|
|
27
|
+
*/
|
|
28
|
+
export interface SelectNextItemRequest<TSkillId = string> {
|
|
29
|
+
/** Learner requesting the recommendation. */
|
|
15
30
|
userId: string;
|
|
16
|
-
|
|
31
|
+
/** Target skill for which we want the next item. */
|
|
32
|
+
skillId: TSkillId;
|
|
33
|
+
/** Optional knobs for selector behavior (difficulty window, filters, etc.). */
|
|
17
34
|
selectionOptions?: Partial<NextItemOptions>;
|
|
18
35
|
}
|
|
19
|
-
|
|
36
|
+
/**
|
|
37
|
+
* Request shape for fetching a single user skill state.
|
|
38
|
+
*/
|
|
39
|
+
export interface GetUserStateRequest<TSkillId = string> {
|
|
40
|
+
/** Learner identifier. */
|
|
20
41
|
userId: string;
|
|
21
|
-
|
|
42
|
+
/** Skill identifier we want to inspect. */
|
|
43
|
+
skillId: TSkillId;
|
|
22
44
|
}
|
|
45
|
+
/**
|
|
46
|
+
* Request shape for listing all skill states for a user.
|
|
47
|
+
*/
|
|
23
48
|
export interface GetUserStatesRequest {
|
|
49
|
+
/** Learner identifier. */
|
|
24
50
|
userId: string;
|
|
25
51
|
}
|
|
26
|
-
|
|
52
|
+
/**
|
|
53
|
+
* Request shape for reading an item state for a particular skill.
|
|
54
|
+
*/
|
|
55
|
+
export interface GetItemStateRequest<TSkillId = string> {
|
|
56
|
+
/** Item identifier. */
|
|
27
57
|
itemId: string;
|
|
28
|
-
|
|
58
|
+
/** Skill identifier (items can be calibrated per skill). */
|
|
59
|
+
skillId: TSkillId;
|
|
29
60
|
}
|
|
61
|
+
/**
|
|
62
|
+
* Request shape for listing all skill calibrations for an item.
|
|
63
|
+
*/
|
|
30
64
|
export interface GetItemStatesRequest {
|
|
65
|
+
/** Item identifier. */
|
|
31
66
|
itemId: string;
|
|
32
67
|
}
|
|
68
|
+
/** Generic REST response envelope used by the SDK helpers. */
|
|
33
69
|
export interface ApiResponse<T> {
|
|
70
|
+
/** True when the API call succeeded. */
|
|
34
71
|
success: boolean;
|
|
72
|
+
/** Response payload when successful. */
|
|
35
73
|
data?: T;
|
|
74
|
+
/** Short error code or message when `success` is false. */
|
|
36
75
|
error?: string;
|
|
76
|
+
/** Human-readable description of the outcome. */
|
|
37
77
|
message?: string;
|
|
38
78
|
}
|
|
39
|
-
|
|
79
|
+
/**
|
|
80
|
+
* Response payload returned after recording an answer.
|
|
81
|
+
*/
|
|
82
|
+
export interface RecordAnswerResponse<TSkillId = string> {
|
|
83
|
+
/** Updated learner ability estimate for the requested skill. */
|
|
40
84
|
theta: number;
|
|
85
|
+
/** Standard error associated with the updated theta. */
|
|
41
86
|
se: number;
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
87
|
+
/** Optional next recommended item (if selection was requested). */
|
|
88
|
+
nextItem: ItemWithMetadata<TSkillId> | null;
|
|
89
|
+
/** Full snapshot of the learner skill state after the update. */
|
|
90
|
+
updatedUser: UserSkillState<TSkillId>;
|
|
91
|
+
/** Updated item calibration metadata. */
|
|
92
|
+
updatedItem: ItemWithMetadata<TSkillId>;
|
|
45
93
|
}
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
94
|
+
/**
|
|
95
|
+
* Response payload returned when requesting the next item only.
|
|
96
|
+
*/
|
|
97
|
+
export interface SelectNextItemResponse<TSkillId = string> {
|
|
98
|
+
/** Latest learner state for the requested skill. */
|
|
99
|
+
user: UserSkillState<TSkillId>;
|
|
100
|
+
/** Next item recommendation or `null` when no item qualifies. */
|
|
101
|
+
nextItem: ItemWithMetadata<TSkillId> | null;
|
|
49
102
|
}
|
|
50
|
-
|
|
51
|
-
|
|
103
|
+
/**
|
|
104
|
+
* Wrapper around a single skill state returned from the API.
|
|
105
|
+
*/
|
|
106
|
+
export interface UserStateResponse<TSkillId = string> {
|
|
107
|
+
/** Skill state snapshot. */
|
|
108
|
+
user: UserSkillState<TSkillId>;
|
|
109
|
+
/** Standard error for the reported theta (mirrors `user.se`). */
|
|
52
110
|
se: number;
|
|
53
111
|
}
|
|
54
|
-
|
|
112
|
+
/**
|
|
113
|
+
* Response structure when fetching many skill states for a user.
|
|
114
|
+
*/
|
|
115
|
+
export interface UserStatesResponse<TSkillId = string> {
|
|
116
|
+
/** Learner identifier echoed back for convenience. */
|
|
55
117
|
userId: string;
|
|
56
|
-
|
|
118
|
+
/** Ordered list of the learner's skill states. */
|
|
119
|
+
skills: UserStateResponse<TSkillId>[];
|
|
120
|
+
/** Count of returned skill states (mirrors `skills.length`). */
|
|
57
121
|
count: number;
|
|
58
122
|
}
|
|
59
|
-
|
|
123
|
+
/**
|
|
124
|
+
* Item-level response for a single skill calibration.
|
|
125
|
+
*/
|
|
126
|
+
export interface ItemStateResponse<TSkillId = string> extends ItemWithMetadata<TSkillId> {
|
|
60
127
|
}
|
|
61
|
-
|
|
128
|
+
/**
|
|
129
|
+
* Response structure when listing all skill calibrations for an item.
|
|
130
|
+
*/
|
|
131
|
+
export interface ItemStatesResponse<TSkillId = string> {
|
|
132
|
+
/** Item identifier echoed back for convenience. */
|
|
62
133
|
itemId: string;
|
|
63
|
-
|
|
134
|
+
/** Calibrations for each skill the item supports. */
|
|
135
|
+
skills: ItemWithMetadata<TSkillId>[];
|
|
136
|
+
/** Count of returned calibrations. */
|
|
64
137
|
count: number;
|
|
65
138
|
}
|
|
139
|
+
/**
|
|
140
|
+
* Simple health check response from the Edge service.
|
|
141
|
+
*/
|
|
66
142
|
export interface HealthResponse {
|
|
143
|
+
/** Indicates whether the service is healthy. */
|
|
67
144
|
success: boolean;
|
|
145
|
+
/** Logical service name (helps in multi-instance deployments). */
|
|
68
146
|
service: string;
|
|
147
|
+
/** Free-form status string (`"ok"`, `"degraded"`, etc.). */
|
|
69
148
|
status: string;
|
|
149
|
+
/** Timestamp (ms) when the health snapshot was generated. */
|
|
70
150
|
timestamp: number;
|
|
71
151
|
}
|
|
152
|
+
/**
|
|
153
|
+
* Configuration accepted by the SDK client factory.
|
|
154
|
+
*/
|
|
72
155
|
export interface IrtClientConfig {
|
|
73
156
|
/**
|
|
74
157
|
* Base URL of the IRT Edge API server
|
package/sdk/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/sdk/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,eAAe,EAChB,MAAM,oBAAoB,CAAA;AAM3B,MAAM,WAAW,mBAAmB;
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/sdk/types.ts"],"names":[],"mappings":"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"}
|