@insignia-education/api-sdk-js 0.9.24 → 0.9.26

package/.nvmrc

@@ -0,0 +1 @@
+24

package/AGENTS.md

@@ -0,0 +1,73 @@
+# Insignia Education — API SDK (JavaScript)
+
+## Requirements
+- Node 24 LTS (`nvm use 24`)
+
+## Quick start
+```bash
+nvm use 24
+npm install
+npm test       # runs Jest test suite
+npm run lint   # ESLint
+```
+
+## What this is
+A zero-dependency JavaScript SDK that wraps the Insignia Education API (`/api/v1`).
+Consumed by `insignia-education/front` via `@insignia-education/api-sdk-js`.
+
+## API versioning
+The SDK is versioned to match the API:
+
+- `src/index.js` — base client
+- `src/api/index.js` — appends `/api` to the base URL
+- `src/api/v1/index.js` — appends `/v1` → all requests land at `<host>/api/v1/...`
+- **v1 is being finalized. Once stable it is permanently frozen.**
+- A future v2 API will live in `src/api/v2/index.js` (new class, new resource modules).
+- Never modify the URL construction logic in `v1/` to point at a different version.
+- Tests for each version live in `tests/integration/api/v1/` — mirror this structure for v2+.
+- The `upload(path, formData)` method on `Client` sends multipart — use `api.files.upload(fd)` for any file upload, never raw `fetch()`.
+
+## Structure
+```
+src/
+├── index.js            ← main export
+├── api/v1/
+│   ├── index.js        ← InsigniaApiV1 class (root client)
+│   ├── Auth.js         ← /auth endpoints
+│   ├── Courses.js      ← /courses endpoints
+│   ├── Users.js        ← /users endpoints
+│   └── ...             ← one file per API resource
+```
+
+## Usage pattern
+```js
+import InsigniaApiV1 from '@insignia-education/api-sdk-js/api/v1';
+const api = new InsigniaApiV1('http://localhost:8000');
+
+api.auth.login({ email, password });
+api.courses.get(null, { page: 1 });
+api.users.cashReceivers();
+```
+
+## Conventions
+- One class per API resource
+- Methods match HTTP verbs: `get`, `post`, `put`, `patch`, `delete`
+- No external runtime dependencies — only Node built-ins
+- ESM modules (`"type": "module"`)
+
+## Adding a new resource
+1. Create `src/api/v1/ResourceName.js` with a class that receives the client
+2. Register it in `src/api/v1/index.js`
+3. Write integration tests in `tests/integration/api/v1/resource-name.test.js`
+
+## Internationalisation (i18n)
+The SDK is language-neutral — it must never contain human-readable strings.
+
+- Do not include hardcoded error messages or labels in SDK source.
+- Error objects thrown by the SDK must expose a machine-readable `status` (HTTP code) and `data` (raw API body). The consuming app handles translation.
+- Do not add locale/language logic to the SDK — that belongs to the frontend.
+
+## Never do
+- Don't add runtime dependencies
+- Don't change the constructor signature of `InsigniaApiV1`
+- Don't hardcode API base URLs — always receive from constructor

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insignia-education/api-sdk-js",
-  "version": "0.9.24",
+  "version": "0.9.26",
   "description": "JavaScript SDK for the Insignia Education API",
   "main": "index.js",
   "type": "module",
@@ -20,7 +20,7 @@
   "author": "Insignia Education",
   "license": "MIT",
   "engines": {
-    "node": ">=25.5.0"
+    "node": ">=24"
   },
   "bugs": {
     "url": "https://github.com/insignia-education/api-sdk-js/issues"

package/src/Client.js

@@ -76,6 +76,30 @@ export default class InsigniaClient {
         if (body !== null) options.body = JSON.stringify(body);
         const response = await fetch(`${this.#baseUrl}${path}`, options);
         this.#storeCookies(response);
+        if (!response.ok) {
+            const err = new Error(`HTTP ${response.status}`);
+            err.status = response.status;
+            try { err.data = await this.#parseResponse(response); } catch (_) {}
+            throw err;
+        }
+        const data = await this.#parseResponse(response);
+        return data?.success ? data.response : data;
+    }
+
+    async upload(path, formData) {
+        const headers = { 'Accept': 'application/json' };
+        const cookie  = this.#cookieHeader();
+        if (cookie) headers.Cookie = cookie;
+        const response = await fetch(`${this.#baseUrl}${path}`, {
+            method: 'PUT', headers, credentials: 'include', body: formData,
+        });
+        this.#storeCookies(response);
+        if (!response.ok) {
+            const err = new Error(`HTTP ${response.status}`);
+            err.status = response.status;
+            try { err.data = await this.#parseResponse(response); } catch (_) {}
+            throw err;
+        }
         const data = await this.#parseResponse(response);
         return data?.success ? data.response : data;
     }

package/src/api/v1/Files.js

@@ -5,6 +5,7 @@ export default class Files {
         this.#client = client;
     }
 
-    get(id = null)  { return id ? this.#client.get(`/files/${id}`) : this.#client.get('/files'); }
-    delete(id)      { return this.#client.del(`/files/${id}`); }
+    get(id = null)              { return id ? this.#client.get(`/files/${id}`) : this.#client.get('/files'); }
+    upload(formData)            { return this.#client.upload('/files', formData); }
+    delete(id)                  { return this.#client.del(`/files/${id}`); }
 }

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

@@ -1,3 +1,4 @@
+import { Blob } from 'buffer';
 import InsigniaApiV1 from '../../../../src/api/v1/index.js';
 
 const api = new InsigniaApiV1(process.env.INSIGNIA_EDUCATION_API_BASE_URL);
@@ -16,10 +17,23 @@ describe('api/v1/files', () => {
                 expect(Array.isArray(response)).toBe(true);
                 response.forEach(file => {
                     expect(file["id"]).toBeDefined();
-                    expect(file["path"]).toBeDefined();
                     expect(file["created_at"]).toBeDefined();
                     expect(file["updated_at"]).toBeDefined();
                 });
             });
     });
+
+    test('upload | authenticated', async () => {
+        await login();
+        const blob = new Blob(['test'], { type: 'image/png' });
+        const fd   = new FormData();
+        fd.append('file', blob, 'test.png');
+        fd.append('type', 'uploads');
+        await api.files.upload(fd)
+            .then(response => {
+                expect(response).toBeDefined();
+                expect(response['url']).toBeDefined();
+                expect(response['id']).toBeDefined();
+            });
+    });
 });