@insignia-education/api-sdk-js 0.15.62 → 0.15.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insignia-education/api-sdk-js",
-  "version": "0.15.62",
+  "version": "0.15.63",
   "description": "JavaScript SDK for the Insignia Education API",
   "main": "index.js",
   "type": "module",

package/src/api/v1/Courses.js

@@ -45,6 +45,8 @@ export default class Courses {
             syncTelegramToUsers: (id) => this.#client.post(`${base}/${id}/sync-user-courses`),
             /** Reconciles this date's sessions with its current teacher/config set: creates missing ones, reassigns the teacher on existing ones, deletes untouched ones that no longer match the schedule. Safe to re-run any time the config, date range or teacher changes. */
             syncSessions: (id) => this.#client.post(`${base}/${id}/sync-sessions`),
+            /** Reconciles per-student attendance rows for this date's generated sessions against who's currently enrolled (UserCourse). Safe to re-run any time the roster changes. */
+            syncAttendances: (id) => this.#client.post(`${base}/${id}/sync-attendances`),
             /** Sessions already generated for this date. */
             sessions: (id) => this.#client.get(`${base}/${id}/sessions`),
             /** Create a Zoom meeting for one of this date's generated sessions. */

package/src/api/v1/Telegram.js

@@ -10,4 +10,10 @@ export default class Telegram {
 
     /** Admin-only: starts (or continues) a QR-code login. */
     qrLogin() { return this.#client.post('/telegram/qr-login'); }
+
+    /** Admin-only: current webhook registration for the main bot (account linking + notifications). */
+    webhookStatus() { return this.#client.get('/telegram/webhook'); }
+
+    /** Admin-only: (re)registers this API's /webhooks/telegram endpoint with Telegram. Idempotent. */
+    setWebhook() { return this.#client.post('/telegram/webhook'); }
 }

package/src/api/v1/Users.js

@@ -202,4 +202,16 @@ export default class Users {
             reject: () => client.post(`${base}/reject`),
         };
     }
+
+    /** Verified Telegram account linking for this user. Owner or staff only. */
+    telegram(userId) {
+        const base = `/users/${userId}/telegram`;
+        const client = this.#client;
+        return {
+            /** Mints a { hash, link, expires_at } deep link — tapping it in Telegram links this user's chat_id via the bot webhook. */
+            linkToken: () => client.post(`${base}/link-token`),
+            /** Fallback flow: completes a link the bot proposed after an organic (no-payload) /start, given the { chat_id, username, expires_at, signature } it replied with. */
+            connect: (data) => client.post(`${base}/connect`, data),
+        };
+    }
 }

package/tests/integration/api/v1/telegram.test.js

@@ -0,0 +1,33 @@
+import {
+    api,
+    loginAdmin,
+    loginCustomer,
+} from '../../../helpers.js';
+
+describe('api/v1/telegram', () => {
+    test('webhookStatus | requires authentication', async () => {
+        await expect(api.telegram.webhookStatus()).rejects.toMatchObject({ status: 401 });
+    });
+
+    test('webhookStatus | forbidden below admin', async () => {
+        await loginCustomer();
+        await expect(api.telegram.webhookStatus()).rejects.toMatchObject({ status: 403 });
+    });
+
+    test('webhookStatus | reachable by admin', async () => {
+        await loginAdmin();
+        await api.telegram.webhookStatus()
+            .then(response => {
+                expect(typeof response).toBe('object');
+            });
+    });
+
+    test('setWebhook | requires authentication', async () => {
+        await expect(api.telegram.setWebhook()).rejects.toMatchObject({ status: 401 });
+    });
+
+    test('setWebhook | forbidden below admin', async () => {
+        await loginCustomer();
+        await expect(api.telegram.setWebhook()).rejects.toMatchObject({ status: 403 });
+    });
+});

package/tests/integration/api/v1/users/telegram.test.js

@@ -0,0 +1,36 @@
+import {
+    api,
+    loginCustomer,
+} from '../../../../helpers.js';
+
+describe('api/v1/users/{id}/telegram', () => {
+    test('linkToken | authenticated owner returns a deep link', async () => {
+        await loginCustomer();
+        const me = await api.users.get();
+        await api.users.telegram(me["id"]).linkToken()
+            .then(response => {
+                expect(response["hash"]).toBeDefined();
+                expect(response["link"]).toContain(response["hash"]);
+                expect(response["link"]).toMatch(/^https:\/\/t\.me\//);
+                expect(response["expires_at"]).toBeDefined();
+            });
+    });
+
+    test('connect | rejects an invalid signature', async () => {
+        await loginCustomer();
+        const me = await api.users.get();
+        await expect(api.users.telegram(me["id"]).connect({
+            chat_id: '12345',
+            username: 'someuser',
+            expires_at: Math.floor(Date.now() / 1000) + 600,
+            signature: 'not-a-real-signature',
+        })).rejects.toMatchObject({ status: 422 });
+    });
+
+    test('connect | missing params returns a validation error', async () => {
+        await loginCustomer();
+        const me = await api.users.get();
+        await expect(api.users.telegram(me["id"]).connect({}))
+            .rejects.toMatchObject({ status: 422 });
+    });
+});