@lessonkit/xapi 0.1.1 → 0.3.0
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/README.md +10 -1
- package/dist/index.cjs +75 -11
- package/dist/index.d.cts +17 -4
- package/dist/index.d.ts +17 -4
- package/dist/index.js +74 -11
- package/package.json +3 -2
package/README.md
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
# `@lessonkit/xapi`
|
|
2
2
|
|
|
3
|
+
[](https://github.com/eddiethedean/lessonkit/actions/workflows/checks.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/@lessonkit/xapi)
|
|
5
|
+
[](../../LICENSE)
|
|
6
|
+
|
|
3
7
|
xAPI statement generation primitives.
|
|
4
8
|
|
|
5
9
|
## Install
|
|
@@ -20,6 +24,11 @@ const xapi = createXAPIClient({
|
|
|
20
24
|
},
|
|
21
25
|
});
|
|
22
26
|
|
|
23
|
-
xapi.completeLesson({ lessonId: "phishing-101" });
|
|
27
|
+
xapi.completeLesson({ lessonId: "phishing-101", durationMs: 1500, success: true, score: 7, maxScore: 10 });
|
|
24
28
|
```
|
|
25
29
|
|
|
30
|
+
## Notes (0.3.0)
|
|
31
|
+
|
|
32
|
+
- If the transport throws/rejects, statements are queued in-memory.
|
|
33
|
+
- You can call `await xapi.flush()` to retry queued statements.
|
|
34
|
+
|
package/dist/index.cjs
CHANGED
|
@@ -20,45 +20,109 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
|
|
|
20
20
|
// src/index.ts
|
|
21
21
|
var index_exports = {};
|
|
22
22
|
__export(index_exports, {
|
|
23
|
+
createInMemoryXAPIQueue: () => createInMemoryXAPIQueue,
|
|
23
24
|
createXAPIClient: () => createXAPIClient
|
|
24
25
|
});
|
|
25
26
|
module.exports = __toCommonJS(index_exports);
|
|
26
27
|
var import_core = require("@lessonkit/core");
|
|
28
|
+
function createInMemoryXAPIQueue() {
|
|
29
|
+
const buffer = [];
|
|
30
|
+
return {
|
|
31
|
+
enqueue: (statement) => {
|
|
32
|
+
buffer.push(statement);
|
|
33
|
+
},
|
|
34
|
+
size: () => buffer.length,
|
|
35
|
+
flush: async (transport) => {
|
|
36
|
+
while (buffer.length) {
|
|
37
|
+
const statement = buffer[0];
|
|
38
|
+
try {
|
|
39
|
+
await transport(statement);
|
|
40
|
+
buffer.shift();
|
|
41
|
+
} catch {
|
|
42
|
+
return;
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
};
|
|
47
|
+
}
|
|
48
|
+
var XAPIVerbs = {
|
|
49
|
+
started: "http://adlnet.gov/expapi/verbs/initialized",
|
|
50
|
+
completed: "http://adlnet.gov/expapi/verbs/completed"
|
|
51
|
+
};
|
|
27
52
|
function createXAPIClient(opts) {
|
|
28
53
|
const transport = opts?.transport;
|
|
29
54
|
const baseId = opts?.baseId ?? "urn:lessonkit";
|
|
55
|
+
const queue = opts?.queue ?? createInMemoryXAPIQueue();
|
|
56
|
+
const sendOrQueue = (statement) => {
|
|
57
|
+
if (!transport) {
|
|
58
|
+
queue.enqueue(statement);
|
|
59
|
+
return;
|
|
60
|
+
}
|
|
61
|
+
void Promise.resolve().then(() => transport(statement)).catch(() => {
|
|
62
|
+
queue.enqueue(statement);
|
|
63
|
+
});
|
|
64
|
+
};
|
|
30
65
|
return {
|
|
31
66
|
send: (statement) => {
|
|
32
|
-
|
|
67
|
+
sendOrQueue(statement);
|
|
68
|
+
},
|
|
69
|
+
queueSize: () => queue.size(),
|
|
70
|
+
flush: async () => {
|
|
71
|
+
if (!transport) return;
|
|
72
|
+
await queue.flush(transport);
|
|
33
73
|
},
|
|
34
74
|
startedLesson: ({ lessonId }) => {
|
|
35
|
-
const statement = statementFor(`${baseId}:lesson:${lessonId}`,
|
|
36
|
-
|
|
75
|
+
const statement = statementFor(`${baseId}:lesson:${lessonId}`, XAPIVerbs.started);
|
|
76
|
+
sendOrQueue(statement);
|
|
37
77
|
},
|
|
38
|
-
completeLesson: ({ lessonId }) => {
|
|
39
|
-
const
|
|
40
|
-
|
|
78
|
+
completeLesson: ({ lessonId, durationMs, score, maxScore, success }) => {
|
|
79
|
+
const result = {};
|
|
80
|
+
if (typeof durationMs === "number") result.duration = formatDurationMs(durationMs);
|
|
81
|
+
if (typeof success === "boolean") result.success = success;
|
|
82
|
+
if (typeof score === "number" || typeof maxScore === "number") {
|
|
83
|
+
const max = typeof maxScore === "number" ? maxScore : void 0;
|
|
84
|
+
const raw = typeof score === "number" ? score : void 0;
|
|
85
|
+
result.score = {
|
|
86
|
+
raw,
|
|
87
|
+
max,
|
|
88
|
+
min: 0,
|
|
89
|
+
scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
const statement = statementFor(`${baseId}:lesson:${lessonId}`, XAPIVerbs.completed, {
|
|
93
|
+
result: Object.keys(result).length ? result : void 0
|
|
94
|
+
});
|
|
95
|
+
sendOrQueue(statement);
|
|
41
96
|
},
|
|
42
97
|
completeCourse: () => {
|
|
43
|
-
const statement = statementFor(`${baseId}:course`,
|
|
44
|
-
|
|
98
|
+
const statement = statementFor(`${baseId}:course`, XAPIVerbs.completed);
|
|
99
|
+
sendOrQueue(statement);
|
|
45
100
|
}
|
|
46
101
|
};
|
|
47
102
|
}
|
|
48
|
-
function statementFor(objectId, verb) {
|
|
103
|
+
function statementFor(objectId, verb, extra) {
|
|
49
104
|
return {
|
|
50
105
|
id: cryptoRandomId(),
|
|
51
106
|
timestamp: (0, import_core.nowIso)(),
|
|
52
107
|
verb,
|
|
53
|
-
object: { id: objectId }
|
|
108
|
+
object: { id: objectId },
|
|
109
|
+
result: extra?.result,
|
|
110
|
+
context: extra?.context
|
|
54
111
|
};
|
|
55
112
|
}
|
|
56
113
|
function cryptoRandomId() {
|
|
57
114
|
const g = globalThis;
|
|
58
115
|
if (g.crypto?.randomUUID) return g.crypto.randomUUID();
|
|
59
|
-
return Math.random().toString(
|
|
116
|
+
return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
|
|
117
|
+
}
|
|
118
|
+
function formatDurationMs(ms) {
|
|
119
|
+
const safe = Math.max(0, ms);
|
|
120
|
+
const seconds = safe / 1e3;
|
|
121
|
+
const fixed = Number.isInteger(seconds) ? String(seconds) : seconds.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
|
|
122
|
+
return `PT${fixed}S`;
|
|
60
123
|
}
|
|
61
124
|
// Annotate the CommonJS export names for ESM import in node:
|
|
62
125
|
0 && (module.exports = {
|
|
126
|
+
createInMemoryXAPIQueue,
|
|
63
127
|
createXAPIClient
|
|
64
128
|
});
|
package/dist/index.d.cts
CHANGED
|
@@ -12,19 +12,32 @@ type XAPIStatement = {
|
|
|
12
12
|
context?: Record<string, unknown>;
|
|
13
13
|
};
|
|
14
14
|
type XAPITransport = (statement: XAPIStatement) => void | Promise<void>;
|
|
15
|
+
type XAPIQueue = {
|
|
16
|
+
enqueue: (statement: XAPIStatement) => void;
|
|
17
|
+
flush: (transport: XAPITransport) => Promise<void>;
|
|
18
|
+
size: () => number;
|
|
19
|
+
};
|
|
20
|
+
declare function createInMemoryXAPIQueue(): XAPIQueue;
|
|
15
21
|
type XAPIClient = {
|
|
16
22
|
send: (statement: XAPIStatement) => void;
|
|
17
|
-
|
|
23
|
+
flush: () => Promise<void>;
|
|
24
|
+
queueSize: () => number;
|
|
25
|
+
startedLesson: (opts: {
|
|
18
26
|
lessonId: LessonId;
|
|
19
27
|
}) => void;
|
|
20
|
-
|
|
28
|
+
completeLesson: (opts: {
|
|
21
29
|
lessonId: LessonId;
|
|
30
|
+
durationMs?: number;
|
|
31
|
+
success?: boolean;
|
|
32
|
+
score?: number;
|
|
33
|
+
maxScore?: number;
|
|
22
34
|
}) => void;
|
|
23
|
-
completeCourse: (
|
|
35
|
+
completeCourse: () => void;
|
|
24
36
|
};
|
|
25
37
|
declare function createXAPIClient(opts?: {
|
|
26
38
|
transport?: XAPITransport;
|
|
27
39
|
baseId?: string;
|
|
40
|
+
queue?: XAPIQueue;
|
|
28
41
|
}): XAPIClient;
|
|
29
42
|
|
|
30
|
-
export { type XAPIClient, type XAPIStatement, type XAPITransport, createXAPIClient };
|
|
43
|
+
export { type XAPIClient, type XAPIQueue, type XAPIStatement, type XAPITransport, createInMemoryXAPIQueue, createXAPIClient };
|
package/dist/index.d.ts
CHANGED
|
@@ -12,19 +12,32 @@ type XAPIStatement = {
|
|
|
12
12
|
context?: Record<string, unknown>;
|
|
13
13
|
};
|
|
14
14
|
type XAPITransport = (statement: XAPIStatement) => void | Promise<void>;
|
|
15
|
+
type XAPIQueue = {
|
|
16
|
+
enqueue: (statement: XAPIStatement) => void;
|
|
17
|
+
flush: (transport: XAPITransport) => Promise<void>;
|
|
18
|
+
size: () => number;
|
|
19
|
+
};
|
|
20
|
+
declare function createInMemoryXAPIQueue(): XAPIQueue;
|
|
15
21
|
type XAPIClient = {
|
|
16
22
|
send: (statement: XAPIStatement) => void;
|
|
17
|
-
|
|
23
|
+
flush: () => Promise<void>;
|
|
24
|
+
queueSize: () => number;
|
|
25
|
+
startedLesson: (opts: {
|
|
18
26
|
lessonId: LessonId;
|
|
19
27
|
}) => void;
|
|
20
|
-
|
|
28
|
+
completeLesson: (opts: {
|
|
21
29
|
lessonId: LessonId;
|
|
30
|
+
durationMs?: number;
|
|
31
|
+
success?: boolean;
|
|
32
|
+
score?: number;
|
|
33
|
+
maxScore?: number;
|
|
22
34
|
}) => void;
|
|
23
|
-
completeCourse: (
|
|
35
|
+
completeCourse: () => void;
|
|
24
36
|
};
|
|
25
37
|
declare function createXAPIClient(opts?: {
|
|
26
38
|
transport?: XAPITransport;
|
|
27
39
|
baseId?: string;
|
|
40
|
+
queue?: XAPIQueue;
|
|
28
41
|
}): XAPIClient;
|
|
29
42
|
|
|
30
|
-
export { type XAPIClient, type XAPIStatement, type XAPITransport, createXAPIClient };
|
|
43
|
+
export { type XAPIClient, type XAPIQueue, type XAPIStatement, type XAPITransport, createInMemoryXAPIQueue, createXAPIClient };
|
package/dist/index.js
CHANGED
|
@@ -1,39 +1,102 @@
|
|
|
1
1
|
// src/index.ts
|
|
2
2
|
import { nowIso } from "@lessonkit/core";
|
|
3
|
+
function createInMemoryXAPIQueue() {
|
|
4
|
+
const buffer = [];
|
|
5
|
+
return {
|
|
6
|
+
enqueue: (statement) => {
|
|
7
|
+
buffer.push(statement);
|
|
8
|
+
},
|
|
9
|
+
size: () => buffer.length,
|
|
10
|
+
flush: async (transport) => {
|
|
11
|
+
while (buffer.length) {
|
|
12
|
+
const statement = buffer[0];
|
|
13
|
+
try {
|
|
14
|
+
await transport(statement);
|
|
15
|
+
buffer.shift();
|
|
16
|
+
} catch {
|
|
17
|
+
return;
|
|
18
|
+
}
|
|
19
|
+
}
|
|
20
|
+
}
|
|
21
|
+
};
|
|
22
|
+
}
|
|
23
|
+
var XAPIVerbs = {
|
|
24
|
+
started: "http://adlnet.gov/expapi/verbs/initialized",
|
|
25
|
+
completed: "http://adlnet.gov/expapi/verbs/completed"
|
|
26
|
+
};
|
|
3
27
|
function createXAPIClient(opts) {
|
|
4
28
|
const transport = opts?.transport;
|
|
5
29
|
const baseId = opts?.baseId ?? "urn:lessonkit";
|
|
30
|
+
const queue = opts?.queue ?? createInMemoryXAPIQueue();
|
|
31
|
+
const sendOrQueue = (statement) => {
|
|
32
|
+
if (!transport) {
|
|
33
|
+
queue.enqueue(statement);
|
|
34
|
+
return;
|
|
35
|
+
}
|
|
36
|
+
void Promise.resolve().then(() => transport(statement)).catch(() => {
|
|
37
|
+
queue.enqueue(statement);
|
|
38
|
+
});
|
|
39
|
+
};
|
|
6
40
|
return {
|
|
7
41
|
send: (statement) => {
|
|
8
|
-
|
|
42
|
+
sendOrQueue(statement);
|
|
43
|
+
},
|
|
44
|
+
queueSize: () => queue.size(),
|
|
45
|
+
flush: async () => {
|
|
46
|
+
if (!transport) return;
|
|
47
|
+
await queue.flush(transport);
|
|
9
48
|
},
|
|
10
49
|
startedLesson: ({ lessonId }) => {
|
|
11
|
-
const statement = statementFor(`${baseId}:lesson:${lessonId}`,
|
|
12
|
-
|
|
50
|
+
const statement = statementFor(`${baseId}:lesson:${lessonId}`, XAPIVerbs.started);
|
|
51
|
+
sendOrQueue(statement);
|
|
13
52
|
},
|
|
14
|
-
completeLesson: ({ lessonId }) => {
|
|
15
|
-
const
|
|
16
|
-
|
|
53
|
+
completeLesson: ({ lessonId, durationMs, score, maxScore, success }) => {
|
|
54
|
+
const result = {};
|
|
55
|
+
if (typeof durationMs === "number") result.duration = formatDurationMs(durationMs);
|
|
56
|
+
if (typeof success === "boolean") result.success = success;
|
|
57
|
+
if (typeof score === "number" || typeof maxScore === "number") {
|
|
58
|
+
const max = typeof maxScore === "number" ? maxScore : void 0;
|
|
59
|
+
const raw = typeof score === "number" ? score : void 0;
|
|
60
|
+
result.score = {
|
|
61
|
+
raw,
|
|
62
|
+
max,
|
|
63
|
+
min: 0,
|
|
64
|
+
scaled: typeof raw === "number" && typeof max === "number" && max > 0 ? raw / max : void 0
|
|
65
|
+
};
|
|
66
|
+
}
|
|
67
|
+
const statement = statementFor(`${baseId}:lesson:${lessonId}`, XAPIVerbs.completed, {
|
|
68
|
+
result: Object.keys(result).length ? result : void 0
|
|
69
|
+
});
|
|
70
|
+
sendOrQueue(statement);
|
|
17
71
|
},
|
|
18
72
|
completeCourse: () => {
|
|
19
|
-
const statement = statementFor(`${baseId}:course`,
|
|
20
|
-
|
|
73
|
+
const statement = statementFor(`${baseId}:course`, XAPIVerbs.completed);
|
|
74
|
+
sendOrQueue(statement);
|
|
21
75
|
}
|
|
22
76
|
};
|
|
23
77
|
}
|
|
24
|
-
function statementFor(objectId, verb) {
|
|
78
|
+
function statementFor(objectId, verb, extra) {
|
|
25
79
|
return {
|
|
26
80
|
id: cryptoRandomId(),
|
|
27
81
|
timestamp: nowIso(),
|
|
28
82
|
verb,
|
|
29
|
-
object: { id: objectId }
|
|
83
|
+
object: { id: objectId },
|
|
84
|
+
result: extra?.result,
|
|
85
|
+
context: extra?.context
|
|
30
86
|
};
|
|
31
87
|
}
|
|
32
88
|
function cryptoRandomId() {
|
|
33
89
|
const g = globalThis;
|
|
34
90
|
if (g.crypto?.randomUUID) return g.crypto.randomUUID();
|
|
35
|
-
return Math.random().toString(
|
|
91
|
+
return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 11)}`;
|
|
92
|
+
}
|
|
93
|
+
function formatDurationMs(ms) {
|
|
94
|
+
const safe = Math.max(0, ms);
|
|
95
|
+
const seconds = safe / 1e3;
|
|
96
|
+
const fixed = Number.isInteger(seconds) ? String(seconds) : seconds.toFixed(3).replace(/0+$/, "").replace(/\.$/, "");
|
|
97
|
+
return `PT${fixed}S`;
|
|
36
98
|
}
|
|
37
99
|
export {
|
|
100
|
+
createInMemoryXAPIQueue,
|
|
38
101
|
createXAPIClient
|
|
39
102
|
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lessonkit/xapi",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.3.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"description": "xAPI statement generation primitives for LessonKit.",
|
|
6
6
|
"license": "Apache-2.0",
|
|
@@ -41,10 +41,11 @@
|
|
|
41
41
|
"prepublishOnly": "npm run build",
|
|
42
42
|
"typecheck": "tsc -p tsconfig.json",
|
|
43
43
|
"test": "vitest run --passWithNoTests",
|
|
44
|
+
"test:coverage": "vitest run --coverage --passWithNoTests=false",
|
|
44
45
|
"lint": "echo \"(no lint configured yet)\""
|
|
45
46
|
},
|
|
46
47
|
"dependencies": {
|
|
47
|
-
"@lessonkit/core": "0.
|
|
48
|
+
"@lessonkit/core": "0.3.0"
|
|
48
49
|
},
|
|
49
50
|
"devDependencies": {
|
|
50
51
|
"tsup": "^8.5.0",
|