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

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,7 +58,14 @@ 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.
 
 ## Never do
 - Don't add runtime dependencies

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@insignia-education/api-sdk-js",
-  "version": "0.9.25",
+  "version": "0.9.26",
   "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,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();
+            });
+    });
 });