@insignia-education/api-sdk-js 0.9.25 → 0.9.28

package/AGENTS.md

@@ -15,6 +15,18 @@ npm run lint   # ESLint
 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/
@@ -46,9 +58,25 @@ api.users.cashReceivers();
 ## 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 tests in `src/api/v1/__tests__/ResourceName.test.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.
+
+## API ↔ SDK sync rule
+
+**This SDK must stay in sync with [`insignia-education/api`](../api) at all times.** Any endpoint added, renamed, or removed in the API must be reflected here in the same task/commit.
+
+- New endpoint in `api` → new method in the correct `src/api/v1/*.js` class
+- Removed endpoint → remove or deprecate the corresponding SDK method
+- Never leave the SDK behind the API; the `front` repo relies solely on this SDK
 
 ## 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
+- Don't let the SDK lag behind `api` — update both in the same task

package/package.json

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

package/src/Client.js

@@ -86,6 +86,24 @@ export default class InsigniaClient {
         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;
+    }
+
     get(path)               { return this.#request('GET',    path); }
     post(path, body = null) { return this.#request('POST',   path, body); }
     put(path, body = null)  { return this.#request('PUT',    path, body); }

package/src/api/v1/Files.js

@@ -5,6 +5,21 @@ 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}`); }
+    /** List files in a directory. params: { organization_id, directory, per_page } */
+    list(params = {})           { return this.#client.get('/files', params); }
+
+    /** Get a single file record by ID. */
+    get(id)                     { return this.#client.get(`/files/${id}`); }
+
+    /** Upload a file (FormData). Supports: file, folder, organization_id, filename, generate_webp, … */
+    upload(formData)            { return this.#client.upload('/files', formData); }
+
+    /** Create a logical folder. body: { organization_id, path } */
+    createFolder(body)          { return this.#client.upload('/files/folder', body); }
+
+    /** Update file description. body: { description } */
+    update(id, body)            { return this.#client.patch(`/files/${id}`, body); }
+
+    /** Soft-delete a file. Pass s3=true to also remove from S3. */
+    delete(id, s3 = false)      { return this.#client.del(`/files/${id}${s3 ? '?s3=1' : ''}`); }
 }

package/src/api/v1/Users.js

@@ -5,8 +5,9 @@ export default class Users {
         this.#client = client;
     }
 
-    get(id = null)      { return id ? this.#client.get(`/users/${id}`) : this.#client.get('/users'); }
-    cashReceivers()     { return this.#client.get('/users/cash-receivers'); }
+    get(id = null)          { return id ? this.#client.get(`/users/${id}`) : this.#client.get('/users'); }
+    getByUsername(username) { return this.#client.get(`/users/username/${username}`); }
+    cashReceivers()         { return this.#client.get('/users/cash-receivers'); }
     edit(id, data)  { return this.#client.patch(`/users/${id}`, data); }
 
     #nested(userId, path) {
@@ -61,6 +62,17 @@ export default class Users {
 
     statistics(userId)     { return { get: () => this.#client.get(`/users/${userId}/statistics`) }; }
 
+    experiences(userId) {
+        const base = `/users/${userId}/experiences`;
+        const client = this.#client;
+        return {
+            get:    (id = null) => id ? client.get(`${base}/${id}`) : client.get(base),
+            create: (data)      => client.put(base, data),
+            edit:   (id, data)  => client.patch(`${base}/${id}`, data),
+            delete: (id)        => client.del(`${base}/${id}`),
+        };
+    }
+
     organizations(userId) {
         const base = `/users/${userId}/organizations`;
         const client = this.#client;

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();
+            });
+    });
 });