@insignia-education/api-sdk-js 0.24.3 → 0.25.1

package/README.md

@@ -276,6 +276,30 @@ await v1.organizations.create(data);
 await v1.organizations.edit(1, data);
 ```
 
+### Games
+
+```js
+await v1.games.get();                         // paginated: get(null, { search, page, perPage })
+await v1.games.get(1);
+await v1.games.create({ title: 'Quiz night', type: 'kahoot' });   // type: kahoot | jeopardy
+await v1.games.edit(1, { status: 'lobby' });  // draft | lobby | in_progress | finished
+await v1.games.delete(1);
+await v1.games.restore(1);
+await v1.games.players(1);
+await v1.games.join(1);
+await v1.games.removePlayer(1, 5);
+await v1.games.regenerateShare(1);            // new share_token; old link stops working
+await v1.games.shared(token).get();           // public — no login needed
+await v1.games.shared(token).join();          // logged-in user
+await v1.games.shared(token).guestJoin('Ana'); // non-logged user, needs allow_guests; returns guest_token
+await v1.games.shared(token).guestQuestions(guestToken);
+await v1.games.questions(1).get();
+await v1.games.questions(1).create(data);
+await v1.games.questions(1).edit(2, { enabled: false });
+await v1.games.questions(1).delete(2);
+await v1.games.questions(1).restore(2);
+```
+
 ### Quizzes
 
 ```js

package/package.json

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

package/src/api/v1/Admin.js

@@ -23,7 +23,7 @@ export default class Admin {
         });
     }
 
-    /** Date-range sales report: totals by status (pending/approved/rejected), and the same split by course, payment method and currency. */
+    /** Date-range sales report: totals by status (pending/approved/rejected), and the same split by course, payment method, currency, owner and seller (`by_seller`: `[{ seller: { id|null, name, username }, pending, approved, rejected, total }]`). */
     statisticsSales({ fromDate, toDate } = {}) {
         return this.#client.get('/admin/statistics/sales', { from_date: fromDate, to_date: toDate });
     }
@@ -188,6 +188,20 @@ export default class Admin {
         });
     }
 
+    /** Paginated per-seller sales report for a date range: line count and base-currency amount per status (pending/approved/rejected) and in total, biggest first. Payments with no seller are one row with `seller_id: null`. */
+    reportsSalesBySeller({ fromDate, toDate, page, perPage } = {}) {
+        return this.#client.get('/admin/reports/sales-by-seller', {
+            from_date: fromDate, to_date: toDate, page, per_page: perPage,
+        });
+    }
+
+    /** Direct download link for the sales-by-seller report (format: 'csv' | 'xlsx'). */
+    reportsSalesBySellerExportUrl({ fromDate, toDate, format = 'csv' } = {}) {
+        return Admin.#buildUrl(this.#client.baseUrl, '/admin/reports/sales-by-seller/export', {
+            from_date: fromDate, to_date: toDate, format,
+        });
+    }
+
     /** Organization-wide OpenAI completion usage, model breakdown and spend for a date range. Resolves `{ available: false }` when the API server has no valid OpenAI Admin API key. */
     reportsOpenAiUsage({ fromDate, toDate } = {}) {
         return this.#client.get('/admin/reports/openai-usage', {

package/src/api/v1/Games.js

@@ -0,0 +1,69 @@
+export default class Games {
+    #client;
+
+    constructor(client) {
+        this.#client = client;
+    }
+
+    /**
+     * With no id: paginated list of the games the authenticated user hosts or plays in
+     * (admins get every game). Pass search/page/perPage to filter and page it.
+     * Write methods (create/edit/delete/restore) are teacher+ and, except for admins, host-only.
+     */
+    get(id = null, { search = null, page = null, perPage = null } = {}) {
+        if (id) return this.#client.get(`/games/${id}`);
+        return this.#client.get('/games', { search, page, per_page: perPage ?? 15 });
+    }
+    /** `data`: `{ title, type }` — type is `kahoot` or `jeopardy`. The creator becomes the host. */
+    create(data)    { return this.#client.put('/games', data); }
+    /** `data`: `{ title?, status?, allow_guests? }` — `allow_guests` lets non-logged users join through the share link; status is `draft`, `lobby`, `in_progress` or `finished`. */
+    edit(id, data)  { return this.#client.patch(`/games/${id}`, data); }
+    delete(id)      { return this.#client.del(`/games/${id}`); }
+    /** Undoes delete() — brings a soft-deleted game back. */
+    restore(id)     { return this.#client.post(`/games/${id}/restore`); }
+
+    /** Host and players of a game. */
+    players(id)     { return this.#client.get(`/games/${id}/players`); }
+    /** Takes a seat as a player — only while the game's status is `lobby`. */
+    join(id)        { return this.#client.post(`/games/${id}/join`); }
+    /** Host/admin only; hosts themselves can't be removed. */
+    removePlayer(id, userId) { return this.#client.del(`/games/${id}/players/${userId}`); }
+
+    /** Host/admin only. Issues a new share token — the old link stops working; anyone already seated keeps their seat. */
+    regenerateShare(id) { return this.#client.post(`/games/${id}/share/regenerate`); }
+
+    /**
+     * Share-link endpoints, keyed by the `share_token` only the host/admin sees on get(id).
+     * `get` is public (no login): `{ id, title, type, status, allow_guests }`. `join` is for a logged-in
+     * user. `guestJoin(name)` seats a non-logged user (host must have enabled `allow_guests`) and returns
+     * a `guest_token`, which `guestQuestions(guestToken)` then needs to read the enabled questions.
+     */
+    shared(token) {
+        const client = this.#client;
+        const base = `/games/shared/${token}`;
+        return {
+            get:            ()           => client.get(base),
+            join:           ()           => client.post(`${base}/join`),
+            guestJoin:      (name)       => client.post(`${base}/guest`, { name }),
+            guestQuestions: (guestToken) => client.get(`${base}/questions`, { guest_token: guestToken }),
+        };
+    }
+
+    /**
+     * Hosts/admins get every question (answers included); players only the enabled ones,
+     * without answers. Kahoot data: `{ question, options: [{ text, is_correct }], points?, time_limit? }`;
+     * Jeopardy data: `{ question, category, answer, points? }`. `enabled` toggles a question on/off.
+     */
+    questions(gameId) {
+        const client = this.#client;
+        const base = `/games/${gameId}/questions`;
+        return {
+            get:    ()          => client.get(base),
+            create: (data)      => client.put(base, data),
+            edit:   (id, data)  => client.patch(`${base}/${id}`, data),
+            delete: (id)        => client.del(`${base}/${id}`),
+            /** Undoes delete() — brings a soft-deleted question back. */
+            restore: (id)       => client.post(`${base}/${id}/restore`),
+        };
+    }
+}

package/src/api/v1/index.js

@@ -17,6 +17,7 @@ import Dashboard from './Dashboard.js';
 import EducationCenter from './EducationCenter.js';
 import Employee from './Employee.js';
 import Files from './Files.js';
+import Games from './Games.js';
 import Forums from './Forums.js';
 import Hashes from './Hashes.js';
 import Insignias from './Insignias.js';
@@ -88,6 +89,7 @@ export default class InsigniaApiV1 extends InsigniaApi {
         this.organizations        = new Organizations(this);
         this.paymentMethods       = new PaymentMethods(this);
         this.payments             = new Payments(this);
+        this.games                = new Games(this);
         this.quizzes              = new Quizzes(this);
         this.sales                = new Sales(this);
         this.search               = new Search(this);