@eduskit/server-sdk 0.1.1

package/README.md

@@ -0,0 +1,158 @@
+# @eduskit/server-sdk
+
+Node.js / TypeScript B 端 Server SDK。`sdk.client` 调课堂 server-api，`sdk.whiteboardClient` 调白板 server-api。
+
+概念与方法表见仓库 [docs/overview.md](../../docs/overview.md)、[docs/api.md](../../docs/api.md)。
+
+## 安装
+
+```bash
+npm install @eduskit/server-sdk
+```
+
+要求 Node.js 18+（使用内置 `fetch`）。本仓库开发：
+
+```bash
+cd packages/nodejs
+npm install
+npm test
+```
+
+## 初始化
+
+```ts
+import { Eduskit, EduskitError } from '@eduskit/server-sdk'
+
+const sdk = new Eduskit({
+  timeoutMs: 10_000,
+  lang: 'zh-CN',
+  client: {
+    baseUrl: 'http://localhost:3112',
+    appId: process.env.EDU_APP_ID!,
+    appKey: process.env.EDU_APP_KEY!,
+    appSecret: process.env.EDU_APP_SECRET!,
+  },
+  whiteboardClient: {
+    baseUrl: 'http://localhost:3012',
+    appId: process.env.WB_APP_ID!,
+    appKey: process.env.WB_APP_KEY!,
+    appSecret: process.env.WB_APP_SECRET!,
+  },
+})
+```
+
+`client` 与 `whiteboardClient` 均可选。也可单独构造：
+
+```ts
+import { ClassroomClient, WhiteboardClient } from '@eduskit/server-sdk'
+```
+
+## 课堂 `sdk.client`
+
+```ts
+const user = await sdk.client.users.register({
+  originId: 'stu_001',
+  nickname: '小明',
+  avatar: 'https://example.com/a.png',
+})
+
+const token = await sdk.client.auth.issueToken({
+  eduUserId: user.eduUserId,
+  originId: 'stu_001',
+  role: 'student',
+  expiresIn: 86400,
+})
+
+const classroom = await sdk.client.classrooms.create({
+  name: '一年级数学',
+  startsAt: '2026-08-17T10:00:00.000Z',
+  endsAt: '2026-08-17T11:00:00.000Z',
+  teacherEduUserId: user.eduUserId,
+})
+
+await sdk.client.classrooms.start(classroom.classroomId)
+await sdk.client.classrooms.members.add(classroom.classroomId, {
+  eduUserId: user.eduUserId,
+  role: 'student',
+})
+await sdk.client.classrooms.members.replaceStudents(classroom.classroomId, {
+  eduUserIds: [user.eduUserId],
+})
+await sdk.client.classrooms.permissions.set(classroom.classroomId, user.eduUserId, {
+  permission: 'camera',
+  effect: 'grant',
+  operatorEduUserId: user.eduUserId,
+})
+await sdk.client.classrooms.coursewares.bind(classroom.classroomId, {
+  coursewareIds: ['cw_xxx'],
+})
+await sdk.client.app.getUiConfig()
+```
+
+| 方法 | 说明 |
+|------|------|
+| `users.register(input)` | 注册/更新 C 端用户 |
+| `auth.issueToken(input)` | 签发 C 端 accessToken |
+| `classrooms.create(input)` | 创建课堂 |
+| `classrooms.start(id)` / `end(id)` | 开课 / 结课 |
+| `classrooms.members.add(id, input)` | 加人 |
+| `classrooms.members.list(id)` | 成员列表 |
+| `classrooms.members.replaceStudents(id, input)` | 全量替换学生 |
+| `classrooms.permissions.get/set/clear(...)` | 代老师管权限 |
+| `classrooms.coursewares.list/bind/unbind(...)` | 课件绑定 |
+| `app.getUiConfig()` / `setUiConfig(input)` | App UI |
+
+## 白板 `sdk.whiteboardClient`
+
+```ts
+const credential = await sdk.whiteboardClient.auth.issueRoomToken({
+  roomId: 'room_1',
+  userId: user.eduUserId,
+  role: 'host',
+  expiresIn: 3600,
+})
+
+const session = await sdk.whiteboardClient.recordings.start('room_1', {
+  externalRef: 'lesson_001',
+})
+await sdk.whiteboardClient.recordings.stop('room_1', {
+  recordingId: session.recordingId,
+})
+await sdk.whiteboardClient.recordings.enqueueVideoExport(session.recordingId, {
+  profile: 'hd',
+})
+
+await sdk.whiteboardClient.captures.create('room_1', { pageId: 'page_1' })
+await sdk.whiteboardClient.files.convert({
+  sourceUrl: 'https://cdn.example.com/lesson.pptx',
+  fileName: 'lesson.pptx',
+})
+```
+
+| 方法 | 说明 |
+|------|------|
+| `auth.issueRoomToken(input)` | 签发 Room Token |
+| `recordings.start/stop/list/get` | 录制会话 |
+| `recordings.registerMediaAsset` / `deleteMediaAsset` | 媒体资产 |
+| `recordings.enqueueVideoExport` / `getVideoExport` | 视频导出（stop 不自动出片） |
+| `captures.create/list` | 页截图 |
+| `files.convert` / `getConvertJob` | 文件转码 |
+
+## 错误
+
+```ts
+try {
+  await sdk.client.auth.issueToken({ eduUserId: '' })
+} catch (error) {
+  if (error instanceof EduskitError) {
+    console.error(error.errorCode, error.status, error.traceId, error.source)
+  }
+}
+```
+
+`sdk.client.lastTraceId` / `sdk.whiteboardClient.lastTraceId` 为最近一次调用的 trace。
+
+## 示例
+
+- [examples/classroom-quickstart.ts](examples/classroom-quickstart.ts)
+- [examples/whiteboard-quickstart.ts](examples/whiteboard-quickstart.ts)

package/dist/src/classroom/client.d.ts

@@ -0,0 +1,61 @@
+import type { SideClientOptions } from '../config.js';
+import { HttpTransport } from '../http.js';
+import { type LocalTokenSigner } from '../token.js';
+import type { AddMemberInput, AppUiConfig, BindCoursewaresInput, BindCoursewaresResult, Classroom, ClearPermissionInput, CoursewareList, CreateClassroomInput, EduUser, EduUserToken, IssueTokenInput, MemberList, Membership, Permissions, RegisterEduUserInput, ReplaceStudentsInput, ReplaceStudentsResult, SetAppUiConfigInput, SetPermissionInput, UnbindCoursewaresResult } from './types.js';
+export declare class ClassroomClient {
+    readonly users: ClassroomUsersApi;
+    readonly auth: ClassroomAuthApi;
+    readonly classrooms: ClassroomClassroomsApi;
+    readonly app: ClassroomAppApi;
+    private readonly http;
+    constructor(options: SideClientOptions);
+    get lastTraceId(): string;
+}
+declare class ClassroomUsersApi {
+    private readonly http;
+    constructor(http: HttpTransport);
+    register(input: RegisterEduUserInput): Promise<EduUser>;
+}
+declare class ClassroomAuthApi {
+    private readonly signer;
+    constructor(signer: LocalTokenSigner);
+    issueToken(input: IssueTokenInput): Promise<EduUserToken>;
+}
+declare class ClassroomMembersApi {
+    private readonly http;
+    constructor(http: HttpTransport);
+    add(classroomId: string, input: AddMemberInput): Promise<Membership>;
+    list(classroomId: string): Promise<MemberList>;
+    replaceStudents(classroomId: string, input: ReplaceStudentsInput): Promise<ReplaceStudentsResult>;
+}
+declare class ClassroomPermissionsApi {
+    private readonly http;
+    constructor(http: HttpTransport);
+    get(classroomId: string, eduUserId: string): Promise<Permissions>;
+    set(classroomId: string, eduUserId: string, input: SetPermissionInput): Promise<Permissions>;
+    clear(classroomId: string, eduUserId: string, permission: string, input: ClearPermissionInput): Promise<Permissions>;
+}
+declare class ClassroomCoursewaresApi {
+    private readonly http;
+    constructor(http: HttpTransport);
+    list(classroomId: string): Promise<CoursewareList>;
+    bind(classroomId: string, input: BindCoursewaresInput): Promise<BindCoursewaresResult>;
+    unbind(classroomId: string, input: BindCoursewaresInput): Promise<UnbindCoursewaresResult>;
+}
+declare class ClassroomClassroomsApi {
+    private readonly http;
+    readonly members: ClassroomMembersApi;
+    readonly permissions: ClassroomPermissionsApi;
+    readonly coursewares: ClassroomCoursewaresApi;
+    constructor(http: HttpTransport);
+    create(input: CreateClassroomInput): Promise<Classroom>;
+    start(classroomId: string): Promise<Classroom>;
+    end(classroomId: string): Promise<Classroom>;
+}
+declare class ClassroomAppApi {
+    private readonly http;
+    constructor(http: HttpTransport);
+    getUiConfig(): Promise<AppUiConfig>;
+    setUiConfig(input: SetAppUiConfigInput): Promise<AppUiConfig>;
+}
+export {};

package/dist/src/classroom/client.js

@@ -0,0 +1,140 @@
+import { encodePath, HttpTransport } from '../http.js';
+import { EDU_TOKEN_AUDIENCE, EDU_TOKEN_ISSUER, requireText, signHs256, } from '../token.js';
+export class ClassroomClient {
+    users;
+    auth;
+    classrooms;
+    app;
+    http;
+    constructor(options) {
+        this.http = new HttpTransport({ ...options, source: 'classroom' });
+        this.users = new ClassroomUsersApi(this.http);
+        this.auth = new ClassroomAuthApi({
+            appId: options.appId,
+            appSecret: options.appSecret,
+            source: 'classroom',
+        });
+        this.classrooms = new ClassroomClassroomsApi(this.http);
+        this.app = new ClassroomAppApi(this.http);
+    }
+    get lastTraceId() {
+        return this.http.lastTraceId;
+    }
+}
+class ClassroomUsersApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    register(input) {
+        return this.http.request('POST', '/v1/users', input);
+    }
+}
+class ClassroomAuthApi {
+    signer;
+    constructor(signer) {
+        this.signer = signer;
+    }
+    async issueToken(input) {
+        const eduUserId = requireText(input.eduUserId, 'eduUserId', 'classroom');
+        const expiresIn = input.expiresIn ?? 86_400;
+        const signed = signHs256(this.signer, {
+            appId: this.signer.appId,
+            ...(input.originId ? { originId: input.originId } : {}),
+            ...(input.role ? { role: input.role } : {}),
+        }, {
+            issuer: EDU_TOKEN_ISSUER,
+            audience: EDU_TOKEN_AUDIENCE,
+            subject: eduUserId,
+            expiresIn,
+        });
+        return {
+            accessToken: signed.token,
+            expiresIn,
+            expiresAt: new Date(signed.expiresAt * 1000).toISOString(),
+            tokenType: 'Bearer',
+            appId: this.signer.appId,
+            eduUserId,
+            originId: input.originId ?? '',
+            role: input.role ?? '',
+        };
+    }
+}
+class ClassroomMembersApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    add(classroomId, input) {
+        return this.http.request('POST', `/v1/classrooms/${encodePath(classroomId)}/members`, input);
+    }
+    list(classroomId) {
+        return this.http.request('GET', `/v1/classrooms/${encodePath(classroomId)}/members`);
+    }
+    replaceStudents(classroomId, input) {
+        return this.http.request('PUT', `/v1/classrooms/${encodePath(classroomId)}/members/students`, input);
+    }
+}
+class ClassroomPermissionsApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    get(classroomId, eduUserId) {
+        return this.http.request('GET', `/v1/classrooms/${encodePath(classroomId)}/members/${encodePath(eduUserId)}/permissions`);
+    }
+    set(classroomId, eduUserId, input) {
+        return this.http.request('POST', `/v1/classrooms/${encodePath(classroomId)}/members/${encodePath(eduUserId)}/permissions`, input);
+    }
+    clear(classroomId, eduUserId, permission, input) {
+        return this.http.request('DELETE', `/v1/classrooms/${encodePath(classroomId)}/members/${encodePath(eduUserId)}/permissions/${encodePath(permission)}`, input);
+    }
+}
+class ClassroomCoursewaresApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    list(classroomId) {
+        return this.http.request('GET', `/v1/classrooms/${encodePath(classroomId)}/coursewares`);
+    }
+    bind(classroomId, input) {
+        return this.http.request('POST', `/v1/classrooms/${encodePath(classroomId)}/coursewares`, input);
+    }
+    unbind(classroomId, input) {
+        return this.http.request('DELETE', `/v1/classrooms/${encodePath(classroomId)}/coursewares`, input);
+    }
+}
+class ClassroomClassroomsApi {
+    http;
+    members;
+    permissions;
+    coursewares;
+    constructor(http) {
+        this.http = http;
+        this.members = new ClassroomMembersApi(http);
+        this.permissions = new ClassroomPermissionsApi(http);
+        this.coursewares = new ClassroomCoursewaresApi(http);
+    }
+    create(input) {
+        return this.http.request('POST', '/v1/classrooms', input);
+    }
+    start(classroomId) {
+        return this.http.request('POST', `/v1/classrooms/${encodePath(classroomId)}/start`);
+    }
+    end(classroomId) {
+        return this.http.request('POST', `/v1/classrooms/${encodePath(classroomId)}/end`);
+    }
+}
+class ClassroomAppApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    getUiConfig() {
+        return this.http.request('GET', '/v1/app/ui-config');
+    }
+    setUiConfig(input) {
+        return this.http.request('PUT', '/v1/app/ui-config', input);
+    }
+}

package/dist/src/classroom/types.d.ts

@@ -0,0 +1,184 @@
+export type ClassroomMemberRole = 'teacher' | 'assistant' | 'student' | 'inspector';
+export type ClassroomPermission = 'camera' | 'microphone' | 'whiteboard' | 'screen_share' | 'chat';
+export type PermissionEffect = 'grant' | 'revoke';
+export type RegisterEduUserInput = {
+    originId?: string;
+    nickname: string;
+    avatar: string;
+};
+export type EduUser = {
+    eduUserId: string;
+    appId: string;
+    originId?: string;
+    nickname: string;
+    avatar: string;
+    status: string;
+};
+export type IssueTokenInput = {
+    /** POST /v1/users 返回的平台 C 端用户 ID。 */
+    eduUserId: string;
+    originId?: string;
+    role?: ClassroomMemberRole;
+    expiresIn?: number;
+};
+export type EduUserToken = {
+    accessToken: string;
+    expiresIn: number;
+    tokenType: string;
+    appId: string;
+    eduUserId: string;
+    originId: string;
+    role: string;
+    expiresAt: string;
+};
+export type CreateClassroomInput = {
+    name: string;
+    startsAt: string;
+    endsAt: string;
+    teacherEduUserId: string;
+    resolution?: '360p' | '480p' | '720p' | '1080p';
+    maxOnStage?: number;
+    defaultOnStage?: boolean;
+    videoOnly?: boolean;
+    recordMode?: 'none' | 'classroom' | 'mix';
+    allowTeacherControlDevice?: boolean;
+    avSubscribeMode?: 'teacher_only' | 'self_only' | 'on_stage_all';
+    uiConfig?: Record<string, unknown>;
+    overtimeMinutes?: number;
+    classroomType?: 'live' | 'realtime';
+    pushStreamUrl?: string;
+    autoStartOnSchedule?: boolean;
+    recordBackgroundUrl?: string;
+    joinPolicy?: 'invite_only' | 'open_app';
+    studentEduUserIds?: string[];
+    coursewareIds?: string[];
+};
+export type ClassroomTeacher = {
+    eduUserId: string;
+    nickname: string;
+    avatar: string;
+    status: string;
+};
+export type Classroom = {
+    classroomId: string;
+    appId: string;
+    name: string;
+    status: string;
+    createdBy?: string;
+    maxOnStage?: number;
+    defaultOnStage?: boolean;
+    startsAt: string;
+    endsAt: string;
+    actualStartedAt?: string;
+    endedAt?: string;
+    effectiveEndsAt?: string;
+    resolution?: string;
+    teacherEduUserId?: string;
+    teacher?: ClassroomTeacher | null;
+    recordMode?: string;
+    allowTeacherControlDevice?: boolean;
+    avSubscribeMode?: string;
+    overtimeMinutes?: number;
+    classroomType?: string;
+    pushStreamUrl?: string;
+    autoStartOnSchedule?: boolean;
+    recordBackgroundUrl?: string;
+    joinPolicy?: string;
+    videoOnly?: boolean;
+    schedulePhase?: string;
+    startOverdue?: boolean;
+    uiConfig?: Record<string, unknown>;
+};
+export type AddMemberInput = {
+    eduUserId: string;
+    role?: ClassroomMemberRole;
+};
+export type Membership = {
+    success?: boolean;
+    classroomId: string;
+    eduUserId: string;
+    role: string;
+    stageStatus?: string;
+};
+export type MembershipItem = {
+    eduUserId: string;
+    role: string;
+    joinedAt?: string;
+    stageStatus?: string;
+};
+export type MemberList = {
+    members: MembershipItem[];
+};
+export type ReplaceStudentsInput = {
+    eduUserIds: string[];
+};
+export type ReplaceStudentsResult = {
+    classroomId: string;
+    studentCount: number;
+    eduUserIds: string[];
+};
+export type PermissionEntry = {
+    permission: string;
+    allowed: boolean;
+    source?: string;
+    status?: string;
+    detail?: string;
+};
+export type Permissions = {
+    classroomId: string;
+    eduUserId: string;
+    role: string;
+    permissions: PermissionEntry[];
+};
+export type SetPermissionInput = {
+    permission: ClassroomPermission;
+    effect: PermissionEffect;
+    operatorEduUserId: string;
+};
+export type ClearPermissionInput = {
+    operatorEduUserId: string;
+};
+export type Courseware = {
+    coursewareId: string;
+    ownerEduUserId?: string;
+    appId?: string;
+    name?: string;
+    originalName?: string;
+    format?: string;
+    sizeBytes?: number;
+    status?: string;
+    progress?: number;
+    jobId?: string;
+    objectKey?: string;
+    sourceUrl?: string;
+    resultManifestUrl?: string;
+    coursewareBaseUrl?: string;
+    wbCoursewareId?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    contentHash?: string;
+    createdAt?: string;
+    updatedAt?: string;
+};
+export type CoursewareList = {
+    items: Courseware[];
+};
+export type BindCoursewaresInput = {
+    coursewareIds: string[];
+};
+export type BindCoursewaresResult = {
+    boundCount?: number;
+    skippedCount?: number;
+    boundCoursewareIds?: string[];
+    skippedCoursewareIds?: string[];
+};
+export type UnbindCoursewaresResult = {
+    unboundCount?: number;
+};
+export type AppUiConfig = {
+    appId: string;
+    uiConfig: Record<string, unknown>;
+};
+export type SetAppUiConfigInput = {
+    uiConfig: Record<string, unknown>;
+};

package/dist/src/classroom/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/config.d.ts

@@ -0,0 +1,18 @@
+import type { FetchLike } from './http.js';
+export type ClientCredentials = {
+    baseUrl: string;
+    /** 租户应用 ID；用于客户后端本地签发 SDK Token。 */
+    appId: string;
+    appKey: string;
+    appSecret: string;
+};
+export type SharedClientOptions = {
+    timeoutMs?: number;
+    lang?: string;
+    fetch?: FetchLike;
+};
+export type EduskitOptions = SharedClientOptions & {
+    client?: ClientCredentials;
+    whiteboardClient?: ClientCredentials;
+};
+export type SideClientOptions = ClientCredentials & SharedClientOptions;

package/dist/src/config.js

@@ -0,0 +1 @@
+export {};

package/dist/src/eduskit.d.ts

@@ -0,0 +1,12 @@
+import { ClassroomClient } from './classroom/client.js';
+import type { EduskitOptions, SideClientOptions } from './config.js';
+import { WhiteboardClient } from './whiteboard/client.js';
+export declare class Eduskit {
+    private readonly classroom?;
+    private readonly whiteboard?;
+    constructor(options: EduskitOptions);
+    get client(): ClassroomClient;
+    get whiteboardClient(): WhiteboardClient;
+}
+export declare function createClassroomClient(options: SideClientOptions): ClassroomClient;
+export declare function createWhiteboardClient(options: SideClientOptions): WhiteboardClient;

package/dist/src/eduskit.js

@@ -0,0 +1,49 @@
+import { ClassroomClient } from './classroom/client.js';
+import { EduskitError } from './errors.js';
+import { WhiteboardClient } from './whiteboard/client.js';
+export class Eduskit {
+    classroom;
+    whiteboard;
+    constructor(options) {
+        const shared = {
+            timeoutMs: options.timeoutMs,
+            lang: options.lang,
+            fetch: options.fetch,
+        };
+        if (options.client) {
+            this.classroom = new ClassroomClient({ ...shared, ...options.client });
+        }
+        if (options.whiteboardClient) {
+            this.whiteboard = new WhiteboardClient({
+                ...shared,
+                ...options.whiteboardClient,
+            });
+        }
+    }
+    get client() {
+        if (!this.classroom) {
+            throw new EduskitError({
+                message: 'classroom client is not configured',
+                errorCode: 'SDK_CLIENT_NOT_CONFIGURED',
+                source: 'classroom',
+            });
+        }
+        return this.classroom;
+    }
+    get whiteboardClient() {
+        if (!this.whiteboard) {
+            throw new EduskitError({
+                message: 'whiteboard client is not configured',
+                errorCode: 'SDK_CLIENT_NOT_CONFIGURED',
+                source: 'whiteboard',
+            });
+        }
+        return this.whiteboard;
+    }
+}
+export function createClassroomClient(options) {
+    return new ClassroomClient(options);
+}
+export function createWhiteboardClient(options) {
+    return new WhiteboardClient(options);
+}

package/dist/src/errors.d.ts

@@ -0,0 +1,17 @@
+export type EduskitSource = 'classroom' | 'whiteboard';
+export type EduskitErrorInit = {
+    message: string;
+    status?: number;
+    errorCode?: string;
+    traceId?: string;
+    path?: string;
+    source?: EduskitSource;
+};
+export declare class EduskitError extends Error {
+    readonly status?: number;
+    readonly errorCode?: string;
+    readonly traceId?: string;
+    readonly path?: string;
+    readonly source?: EduskitSource;
+    constructor(init: EduskitErrorInit);
+}

package/dist/src/errors.js

@@ -0,0 +1,16 @@
+export class EduskitError extends Error {
+    status;
+    errorCode;
+    traceId;
+    path;
+    source;
+    constructor(init) {
+        super(init.message);
+        this.name = 'EduskitError';
+        this.status = init.status;
+        this.errorCode = init.errorCode;
+        this.traceId = init.traceId;
+        this.path = init.path;
+        this.source = init.source;
+    }
+}

package/dist/src/http.d.ts

@@ -0,0 +1,24 @@
+import { type EduskitSource } from './errors.js';
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+export type HttpConfig = {
+    baseUrl: string;
+    appKey: string;
+    appSecret: string;
+    timeoutMs?: number;
+    lang?: string;
+    fetch?: FetchLike;
+    source: EduskitSource;
+};
+export declare class HttpTransport {
+    lastTraceId: string;
+    private readonly baseUrl;
+    private readonly appKey;
+    private readonly appSecret;
+    private readonly timeoutMs;
+    private readonly lang;
+    private readonly fetchImpl;
+    private readonly source;
+    constructor(config: HttpConfig);
+    request<T>(method: string, path: string, body?: unknown): Promise<T>;
+}
+export declare function encodePath(value: string): string;

package/dist/src/http.js

@@ -0,0 +1,96 @@
+import { EduskitError } from './errors.js';
+export class HttpTransport {
+    lastTraceId = '';
+    baseUrl;
+    appKey;
+    appSecret;
+    timeoutMs;
+    lang;
+    fetchImpl;
+    source;
+    constructor(config) {
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        this.appKey = config.appKey;
+        this.appSecret = config.appSecret;
+        this.timeoutMs = config.timeoutMs ?? 10_000;
+        this.lang = config.lang ?? 'zh-CN';
+        this.fetchImpl = config.fetch ?? fetch;
+        this.source = config.source;
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const traceId = crypto.randomUUID().replace(/-/g, '').slice(0, 16);
+        const headers = {
+            'content-type': 'application/json',
+            accept: 'application/json',
+            'x-app-key': this.appKey,
+            'x-app-secret': this.appSecret,
+            'x-lang': this.lang,
+            'x-trace-id': traceId,
+        };
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        catch (error) {
+            clearTimeout(timer);
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new EduskitError({
+                    message: `request timeout after ${this.timeoutMs}ms`,
+                    errorCode: 'SDK_TIMEOUT',
+                    path,
+                    source: this.source,
+                    traceId,
+                });
+            }
+            throw new EduskitError({
+                message: error instanceof Error ? error.message : String(error),
+                errorCode: 'SDK_NETWORK_ERROR',
+                path,
+                source: this.source,
+                traceId,
+            });
+        }
+        clearTimeout(timer);
+        const headerTrace = response.headers.get('x-trace-id') ?? traceId;
+        const text = await response.text();
+        let payload = {};
+        if (text) {
+            try {
+                payload = JSON.parse(text);
+            }
+            catch {
+                throw new EduskitError({
+                    message: text || `invalid json (HTTP ${response.status})`,
+                    status: response.status,
+                    errorCode: 'SDK_INVALID_JSON',
+                    path,
+                    source: this.source,
+                    traceId: headerTrace,
+                });
+            }
+        }
+        this.lastTraceId = String(payload.traceId || headerTrace);
+        if (!response.ok || (payload.code != null && payload.code !== 0)) {
+            throw new EduskitError({
+                message: payload.message || `HTTP ${response.status}`,
+                status: response.status,
+                errorCode: payload.errorCode || `HTTP_${response.status}`,
+                path: payload.path || path,
+                source: this.source,
+                traceId: this.lastTraceId,
+            });
+        }
+        return (payload.data ?? payload);
+    }
+}
+export function encodePath(value) {
+    return encodeURIComponent(value);
+}

package/dist/src/index.d.ts

@@ -0,0 +1,9 @@
+export { Eduskit, createClassroomClient, createWhiteboardClient } from './eduskit.js';
+export { ClassroomClient } from './classroom/client.js';
+export { WhiteboardClient } from './whiteboard/client.js';
+export { EduskitError } from './errors.js';
+export { EDU_TOKEN_AUDIENCE, EDU_TOKEN_ISSUER, ROOM_TOKEN_AUDIENCE, ROOM_TOKEN_ISSUER, } from './token.js';
+export type { EduskitSource, EduskitErrorInit } from './errors.js';
+export type { ClientCredentials, EduskitOptions, SharedClientOptions, SideClientOptions, } from './config.js';
+export type * from './classroom/types.js';
+export type * from './whiteboard/types.js';

package/dist/src/index.js

@@ -0,0 +1,5 @@
+export { Eduskit, createClassroomClient, createWhiteboardClient } from './eduskit.js';
+export { ClassroomClient } from './classroom/client.js';
+export { WhiteboardClient } from './whiteboard/client.js';
+export { EduskitError } from './errors.js';
+export { EDU_TOKEN_AUDIENCE, EDU_TOKEN_ISSUER, ROOM_TOKEN_AUDIENCE, ROOM_TOKEN_ISSUER, } from './token.js';

package/dist/src/token.d.ts

@@ -0,0 +1,22 @@
+import { EduskitError, type EduskitSource } from './errors.js';
+export declare const EDU_TOKEN_ISSUER = "eduskit-edu-auth";
+export declare const EDU_TOKEN_AUDIENCE = "eduskit-edu";
+export declare const ROOM_TOKEN_ISSUER = "eduskit";
+export declare const ROOM_TOKEN_AUDIENCE = "eduskit-room";
+export type LocalTokenSigner = {
+    appId: string;
+    appSecret: string;
+    source: EduskitSource;
+};
+export declare function signHs256(signer: LocalTokenSigner, claims: Record<string, unknown>, options: {
+    issuer: string;
+    audience: string;
+    subject: string;
+    expiresIn: number;
+}): {
+    token: string;
+    issuedAt: number;
+    expiresAt: number;
+};
+export declare function requireText(value: unknown, field: string, source: EduskitSource): string;
+export declare function sdkTokenError(message: string, source: EduskitSource): EduskitError;

package/dist/src/token.js

@@ -0,0 +1,42 @@
+import { createHmac } from 'node:crypto';
+import { EduskitError } from './errors.js';
+export const EDU_TOKEN_ISSUER = 'eduskit-edu-auth';
+export const EDU_TOKEN_AUDIENCE = 'eduskit-edu';
+export const ROOM_TOKEN_ISSUER = 'eduskit';
+export const ROOM_TOKEN_AUDIENCE = 'eduskit-room';
+export function signHs256(signer, claims, options) {
+    requireText(signer.appId, 'appId', signer.source);
+    requireText(signer.appSecret, 'appSecret', signer.source);
+    requireText(options.subject, 'subject', signer.source);
+    if (!Number.isInteger(options.expiresIn) || options.expiresIn < 60 || options.expiresIn > 604_800) {
+        throw sdkTokenError('expiresIn must be an integer between 60 and 604800', signer.source);
+    }
+    const issuedAt = Math.floor(Date.now() / 1000);
+    const expiresAt = issuedAt + options.expiresIn;
+    const header = encode({ alg: 'HS256', typ: 'JWT' });
+    const payload = encode({
+        ...claims,
+        iss: options.issuer,
+        aud: options.audience,
+        sub: options.subject,
+        iat: issuedAt,
+        exp: expiresAt,
+    });
+    const content = `${header}.${payload}`;
+    const signature = createHmac('sha256', signer.appSecret)
+        .update(content)
+        .digest('base64url');
+    return { token: `${content}.${signature}`, issuedAt, expiresAt };
+}
+export function requireText(value, field, source) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw sdkTokenError(`${field} is required`, source);
+    }
+    return value;
+}
+export function sdkTokenError(message, source) {
+    return new EduskitError({ message, errorCode: 'SDK_TOKEN_INPUT_INVALID', source });
+}
+function encode(value) {
+    return Buffer.from(JSON.stringify(value), 'utf8').toString('base64url');
+}

package/dist/src/whiteboard/client.d.ts

@@ -0,0 +1,49 @@
+import type { SideClientOptions } from '../config.js';
+import { HttpTransport } from '../http.js';
+import { type LocalTokenSigner } from '../token.js';
+import type { Capture, ConvertJob, CreateCaptureInput, CreateConvertJobInput, EnqueueVideoExportInput, IssueRoomTokenInput, MediaAsset, RecordingSession, RegisterMediaAssetInput, RoomToken, StartRecordingInput, StopRecordingInput, VideoExportJob, AttachRoomCoursewareInput, AttachedRoomCourseware } from './types.js';
+export declare class WhiteboardClient {
+    readonly auth: WhiteboardAuthApi;
+    readonly recordings: WhiteboardRecordingsApi;
+    readonly captures: WhiteboardCapturesApi;
+    readonly files: WhiteboardFilesApi;
+    readonly rooms: WhiteboardRoomsApi;
+    private readonly http;
+    constructor(options: SideClientOptions);
+    get lastTraceId(): string;
+}
+declare class WhiteboardRoomsApi {
+    private readonly http;
+    constructor(http: HttpTransport);
+    attachCourseware(roomId: string, input: AttachRoomCoursewareInput): Promise<AttachedRoomCourseware>;
+}
+declare class WhiteboardAuthApi {
+    private readonly signer;
+    constructor(signer: LocalTokenSigner);
+    issueRoomToken(input: IssueRoomTokenInput): Promise<RoomToken>;
+}
+declare class WhiteboardRecordingsApi {
+    private readonly http;
+    constructor(http: HttpTransport);
+    start(roomId: string, input?: StartRecordingInput): Promise<RecordingSession>;
+    stop(roomId: string, input: StopRecordingInput): Promise<RecordingSession>;
+    list(roomId: string): Promise<RecordingSession[]>;
+    get(recordingId: string): Promise<RecordingSession>;
+    registerMediaAsset(recordingId: string, input: RegisterMediaAssetInput): Promise<MediaAsset>;
+    deleteMediaAsset(recordingId: string, assetId: string): Promise<MediaAsset>;
+    enqueueVideoExport(recordingId: string, input?: EnqueueVideoExportInput): Promise<VideoExportJob>;
+    getVideoExport(recordingId: string, jobId: string): Promise<VideoExportJob>;
+}
+declare class WhiteboardCapturesApi {
+    private readonly http;
+    constructor(http: HttpTransport);
+    create(roomId: string, input: CreateCaptureInput): Promise<Capture>;
+    list(roomId: string): Promise<Capture[]>;
+}
+declare class WhiteboardFilesApi {
+    private readonly http;
+    constructor(http: HttpTransport);
+    convert(input: CreateConvertJobInput): Promise<ConvertJob>;
+    getConvertJob(jobId: string): Promise<ConvertJob>;
+}
+export {};

package/dist/src/whiteboard/client.js

@@ -0,0 +1,122 @@
+import { encodePath, HttpTransport } from '../http.js';
+import { ROOM_TOKEN_AUDIENCE, ROOM_TOKEN_ISSUER, requireText, sdkTokenError, signHs256, } from '../token.js';
+export class WhiteboardClient {
+    auth;
+    recordings;
+    captures;
+    files;
+    rooms;
+    http;
+    constructor(options) {
+        this.http = new HttpTransport({ ...options, source: 'whiteboard' });
+        this.auth = new WhiteboardAuthApi({
+            appId: options.appId,
+            appSecret: options.appSecret,
+            source: 'whiteboard',
+        });
+        this.recordings = new WhiteboardRecordingsApi(this.http);
+        this.captures = new WhiteboardCapturesApi(this.http);
+        this.files = new WhiteboardFilesApi(this.http);
+        this.rooms = new WhiteboardRoomsApi(this.http);
+    }
+    get lastTraceId() {
+        return this.http.lastTraceId;
+    }
+}
+class WhiteboardRoomsApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    attachCourseware(roomId, input) {
+        return this.http.request('POST', `/v1/rooms/${encodePath(roomId)}/coursewares`, input);
+    }
+}
+class WhiteboardAuthApi {
+    signer;
+    constructor(signer) {
+        this.signer = signer;
+    }
+    async issueRoomToken(input) {
+        const roomId = requireText(input.roomId, 'roomId', 'whiteboard');
+        const userId = requireText(input.userId, 'userId', 'whiteboard');
+        if (!['host', 'participant', 'observer'].includes(input.role)) {
+            throw sdkTokenError('role must be host, participant, or observer', 'whiteboard');
+        }
+        const expiresIn = input.expiresIn ?? 3600;
+        const signed = signHs256(this.signer, {
+            app_id: this.signer.appId,
+            room_id: roomId,
+            role: input.role,
+            source: 'server_sdk',
+        }, {
+            issuer: ROOM_TOKEN_ISSUER,
+            audience: ROOM_TOKEN_AUDIENCE,
+            subject: userId,
+            expiresIn,
+        });
+        return {
+            token: signed.token,
+            appId: this.signer.appId,
+            roomId,
+            userId,
+            role: input.role,
+            expiresIn,
+            expiresAt: new Date(signed.expiresAt * 1000).toISOString(),
+        };
+    }
+}
+class WhiteboardRecordingsApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    start(roomId, input = {}) {
+        return this.http.request('POST', `/v1/rooms/${encodePath(roomId)}/recording/start`, input);
+    }
+    stop(roomId, input) {
+        return this.http.request('POST', `/v1/rooms/${encodePath(roomId)}/recording/stop`, input);
+    }
+    list(roomId) {
+        return this.http.request('GET', `/v1/rooms/${encodePath(roomId)}/recordings`);
+    }
+    get(recordingId) {
+        return this.http.request('GET', `/v1/recordings/${encodePath(recordingId)}`);
+    }
+    registerMediaAsset(recordingId, input) {
+        return this.http.request('POST', `/v1/recordings/${encodePath(recordingId)}/media-assets`, input);
+    }
+    deleteMediaAsset(recordingId, assetId) {
+        return this.http.request('DELETE', `/v1/recordings/${encodePath(recordingId)}/media-assets/${encodePath(assetId)}`);
+    }
+    enqueueVideoExport(recordingId, input = {}) {
+        return this.http.request('POST', `/v1/recordings/${encodePath(recordingId)}/video-exports`, input);
+    }
+    getVideoExport(recordingId, jobId) {
+        return this.http.request('GET', `/v1/recordings/${encodePath(recordingId)}/video-exports/${encodePath(jobId)}`);
+    }
+}
+class WhiteboardCapturesApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    create(roomId, input) {
+        return this.http.request('POST', `/v1/rooms/${encodePath(roomId)}/captures`, { roomId, ...input });
+    }
+    list(roomId) {
+        return this.http.request('GET', `/v1/rooms/${encodePath(roomId)}/captures`);
+    }
+}
+class WhiteboardFilesApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    convert(input) {
+        return this.http.request('POST', '/v1/files/convert', input);
+    }
+    getConvertJob(jobId) {
+        return this.http.request('GET', `/v1/files/convert/${encodePath(jobId)}`);
+    }
+}

package/dist/src/whiteboard/types.d.ts

@@ -0,0 +1,140 @@
+export type RoomRole = 'host' | 'participant' | 'observer';
+export type IssueRoomTokenInput = {
+    roomId: string;
+    userId: string;
+    role: RoomRole;
+    expiresIn?: number;
+};
+export type RoomToken = {
+    token: string;
+    roomId: string;
+    userId: string;
+    role: string;
+    expiresIn: number;
+    expiresAt: string;
+    appId: string;
+};
+export type StartRecordingInput = {
+    externalRef?: string;
+};
+export type StopRecordingInput = {
+    recordingId: string;
+};
+export type MediaAsset = {
+    assetId: string;
+    recordingId: string;
+    kind: string;
+    url: string;
+    contentType?: string;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+    metadataJson?: string;
+    createdAt: string;
+};
+export type RecordingSession = {
+    recordingId: string;
+    appId: string;
+    roomId: string;
+    status: string;
+    externalRef?: string;
+    wallStart?: string;
+    wallEnd?: string;
+    startServerSeq?: number | string;
+    endServerSeq?: number | string;
+    checkpointSeqAtStart?: number | string;
+    bundleObjectKey?: string;
+    bundleChecksumSha256?: string;
+    bundleSizeBytes?: number | string;
+    bundleReadyAt?: string;
+    startedAt?: string;
+    stoppedAt?: string;
+    mediaAssets?: MediaAsset[];
+};
+export type RegisterMediaAssetInput = {
+    kind: string;
+    url: string;
+    contentType?: string;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+};
+export type EnqueueVideoExportInput = {
+    profile?: 'standard' | 'hd';
+    sampleMode?: 'change' | 'fixed';
+    fps?: number;
+    width?: number;
+    height?: number;
+};
+export type VideoExportJob = {
+    jobId: string;
+    recordingId: string;
+    appId: string;
+    roomId: string;
+    status: string;
+    fromSeq?: number | string;
+    toSeq?: number | string;
+    wallStart?: string;
+    wallEnd?: string;
+    profile?: string;
+    sampleMode?: string;
+    fps?: number;
+    width?: number;
+    height?: number;
+    assetId?: string;
+    publicUrl?: string;
+    objectKey?: string;
+    lastError?: string;
+    createdAt?: string;
+    finishedAt?: string;
+};
+export type CreateCaptureInput = {
+    pageId: string;
+    url?: string;
+};
+export type Capture = {
+    captureId: string;
+    appId: string;
+    roomId: string;
+    pageId: string;
+    url: string;
+    createdAt: string;
+};
+export type CreateConvertJobInput = {
+    sourceUrl?: string;
+    fileName?: string;
+    objectKey?: string;
+    clientReference?: string;
+};
+export type ConvertJob = {
+    jobId: string;
+    appId: string;
+    sourceUrl?: string;
+    fileName?: string;
+    status: string;
+    progress: number;
+    stage?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    resultManifestUrl?: string;
+    coursewareBaseUrl?: string;
+    resultManifestObjectKey?: string;
+    coursewareObjectPrefix?: string;
+    coursewareId?: string;
+    coursewareVersion?: string;
+    clientReference?: string;
+    createdAt: string;
+    updatedAt: string;
+};
+export type AttachRoomCoursewareInput = {
+    coursewareId: string;
+    convertJobId: string;
+    requestId: string;
+};
+export type AttachedRoomCourseware = {
+    coursewareId: string;
+    whiteboardFileId: string;
+    opId: string;
+    serverSeq: number;
+    serverReceivedAt: number;
+    pageCount: number;
+    duplicated: boolean;
+};

package/dist/src/whiteboard/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@eduskit/server-sdk",
+  "version": "0.1.1",
+  "description": "Eduskit B-end server SDK for classroom and whiteboard APIs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eduskit/server-sdk-node.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js",
+      "default": "./dist/src/index.js"
+    }
+  },
+  "files": ["dist/src"],
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test dist/test/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED",
+  "devDependencies": {
+    "@types/node": "^22.13.0",
+    "typescript": "^5.7.3"
+  }
+}