@singularlogic/coreplatts 0.0.5 → 0.0.7

package/README.md

@@ -1,6 +1,7 @@
 # @singularlogic/coreplatts
 
-A TypeScript client library to access the **BUILDSPACE** identity and storage APIs.  
+A TypeScript client library to access the **BUILDSPACE** identity and storage APIs.
+
 Built to work with [Keycloak](https://www.keycloak.org/) and [MinIO](https://min.io/), this library wraps REST endpoints and handles authentication, token refresh, organization and folder management.
 
 ---
@@ -35,19 +36,34 @@ const token = await client.login('user@example.com', 'password');
 console.log('Access token:', token.access_token);
 ```
 
-Tokens are stored in `localStorage` or `sessionStorage` and automatically refreshed when expired.
+Tokens are stored in `sessionStorage` and are **automatically refreshed when expired**.
+
+### ⚠️ For Web Applications: Use an OIDC or Keycloak Client
+
+We **strongly recommend** using an **OpenID Connect (OIDC)** or **Keycloak client** for web applications.
+
+**Why?**
+
+- ✅ More secure: handles redirect flows, token validation, and silent refresh securely.
+- 🔄 Seamless session management: avoids manual token handling and refresh logic.
+- 🔐 Built-in CSRF and token expiration protection.
+
+#### Great frontend OIDC libraries:
+
+- [oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts)
+- [keycloak-js](https://www.npmjs.com/package/keycloak-js)
+
+> The `client.login(email, password)` method is designed for **CLI tools, backend services, development, and test automation** — not for production browser-based apps.
 
 ---
 
 ## 👤 User Management
 
 ```ts
-const me = await client.myUser(); // auto-includes access token
+const me = await client.myUser();
 console.log(me.username);
 ```
 
-Register new users:
-
 ```ts
 await client.register(
   'new@user.com',
@@ -81,71 +97,30 @@ await client.addToOrganization('MyNewOrg', {
 ## 📂 Folder & File Management
 
 ```ts
-const folder = await client.getFolderByName('project-data');
-console.log(folder.files);
-```
 
-You can also upload and download files using `Folder` and `File` methods.
+const folder = await client.getFolderByName('project-data');
 
-Example:
+const folderItems = await folder.listItems();
 
-```ts
 const file = await folder.getFileByName('report.pdf');
 await file.download();
 ```
 
----
-
-## 🔁 Automatic Token Handling
-
-All token-sensitive methods use a utility that:
-- Checks if the access token is expired
-- Refreshes it using `refresh_token` if needed
-- Uses `localStorage` or `sessionStorage` automatically
-
----
-
-## 🧪 Example in Angular Service
+### Upload a File
 
 ```ts
-import { Injectable } from '@angular/core';
-import { Client } from '@singularlogic/coreplatts';
-import { environment } from '../environments/environment';
-
-@Injectable({ providedIn: 'root' })
-export class AuthService {
-  client = new Client(environment.managementURL, environment.accountURL);
-
-  getCurrentUser() {
-    return this.client.myUser();
-  }
-}
+await folder.uploadFile(
+  myFile,
+  { title: 'dataset.csv' },
+  5 * 1024 * 1024, // chunk size
+  10, // concurrency
+  3600 // timeout
+);
 ```
 
 ---
 
-## 🧱 Core Classes
-
-### `Client`
-
-- Handles auth, session, and proxies to:
-  - `UserConsumer`
-  - `GroupConsumer`
-  - `BucketConsumer`
-  - `FolderConsumer`
-
-### `Folder`
-
-- Can fetch files
-- Can upload files with chunking and concurrency control
-
-### `File`
-
-- Can be downloaded by ID or name
-
----
-
-## 📘 API Summary
+### 📘 Main Client
 
 | Method | Description |
 |--------|-------------|
@@ -161,6 +136,34 @@ export class AuthService {
 
 ---
 
+### 📘 Folder Class
+
+| Method | Description |
+|--------|-------------|
+| `listItems()` | List folder contents |
+| `getFileByID(id)` | Retrieve file by ID |
+| `getFileByName(name)` | Retrieve file by name |
+| `uploadFile(...)` | Upload file with chunked multipart support |
+
+---
+
+### 📘 File Class
+
+| Method | Description |
+|--------|-------------|
+| `download()` | Download file with chunked concurrency |
+| `getFilename()` | Get complete file name from metadata |
+
+---
+
+## 🔁 Automatic Token Handling
+
+All token-sensitive methods use a utility that:
+
+- Checks token expiration
+- Automatically refreshes access tokens
+- Uses `sessionStorage` only
+
 ## 📄 License
 
 MIT © [SingularLogic S.A.](https://www.singularlogic.eu)

package/dist/index.d.ts

@@ -155,7 +155,8 @@ declare class Client implements IClient$1 {
     private _bucketConsumer;
     private _folderConsumer;
     constructor(_managementURL: string, _accountURL: string);
-    private _setSession;
+    setSession(session: OidcToken): void;
+    getSessionVariable(key: string): string | null;
     login(email: string, password: string): Promise<OidcToken>;
     myUser(token?: string): Promise<User$1>;
     allOrganizations(token?: string): Promise<Group$1[]>;

package/dist/index.js

@@ -272,20 +272,40 @@ var BucketConsumer = class extends BaseConsumer {
 function withValidToken(fn, accountsAPI) {
   return function(...args) {
     return __async(this, null, function* () {
-      const isStorageAvailable = typeof localStorage !== "undefined";
       const now = Math.floor(Date.now() / 1e3);
-      if (!isStorageAvailable) {
-        console.warn("\u26A0\uFE0F localStorage not available. You must pass token manually.");
-        return Promise.resolve(fn.apply(this, args));
+      const storage = typeof window !== "undefined" ? window.sessionStorage : globalThis.sessionStorage;
+      if (!storage) {
+        console.warn("\u26A0\uFE0F sessionStorage not available");
+        return fn.apply(this, args);
       }
-      let token = localStorage.getItem("token");
-      const refreshToken = localStorage.getItem("refresh_token");
-      const exp = Number(localStorage.getItem("exp") || "0");
-      const refreshExp = Number(localStorage.getItem("refresh_exp") || "0");
-      if (!token || now >= exp) {
-        if (!refreshToken || now >= refreshExp) {
-          console.warn("\u26A0\uFE0F Session expired. Please log in again.");
-          return Promise.resolve(fn.apply(this, args));
+      let token = storage.getItem("access_token");
+      let refreshToken = storage.getItem("refresh_token");
+      let exp = 0;
+      let refreshExp = 0;
+      const claimsRaw = storage.getItem("id_token_claims_obj");
+      if (claimsRaw) {
+        try {
+          const claims = JSON.parse(claimsRaw);
+          if (claims.exp) exp = claims.exp;
+          if (claims.iat && claims.exp) {
+            const duration = claims.exp - claims.iat;
+            refreshExp = claims.iat + 3 * duration;
+          }
+        } catch (e) {
+          console.warn("\u26A0\uFE0F Could not parse id_token_claims_obj:", e);
+        }
+      } else {
+        exp = Number(storage.getItem("refresh_expires_in") || "0");
+        refreshExp = Number(storage.getItem("refresh_exp") || "0");
+      }
+      if (!token || !refreshToken) {
+        console.warn("\u26A0\uFE0F No tokens found in sessionStorage.");
+        return fn.apply(this, args);
+      }
+      if (now >= exp) {
+        if (now >= refreshExp) {
+          console.warn("\u26A0\uFE0F Both access and refresh tokens expired.");
+          return fn.apply(this, args);
         }
         try {
           const response = yield fetch(`${accountsAPI}/user/refresh`, {
@@ -295,20 +315,20 @@ function withValidToken(fn, accountsAPI) {
           });
           if (!response.ok) throw new Error("Token refresh failed");
           const session = yield response.json();
+          token = session.access_token;
+          refreshToken = session.refresh_token;
           const newExp = now + session.expires_in;
           const newRefreshExp = now + session.refresh_expires_in;
-          localStorage.setItem("token", session.access_token);
-          localStorage.setItem("refresh_token", session.refresh_token);
-          localStorage.setItem("exp", String(newExp));
-          localStorage.setItem("refresh_exp", String(newRefreshExp));
-          token = session.access_token;
-        } catch (e) {
-          console.error("\u{1F510} Token refresh failed:", e);
+          storage.setItem("access_token", token);
+          storage.setItem("refresh_token", refreshToken);
+          storage.setItem("refresh_expires_in", String(newExp));
+          storage.setItem("refresh_exp", String(newRefreshExp));
+        } catch (err) {
+          console.error("\u{1F510} Token refresh failed:", err);
           throw new Error("Could not refresh session.");
         }
       }
-      const result = fn.apply(this, [...args, token]);
-      return result instanceof Promise ? result : Promise.resolve(result);
+      return yield fn.apply(this, [...args, token]);
     });
   };
 }
@@ -787,36 +807,37 @@ var Client = class {
     this.getFolderByName = withValidToken(this.getFolderByName.bind(this), _accountURL);
     this.getFolderByID = withValidToken(this.getFolderByID.bind(this), _accountURL);
   }
-  // public setSession(session: OidcToken): void {
-  //   const storage = typeof window !== "undefined" ? sessionStorage : global.sessionStorage;
-  //   if (storage) {
-  //       storage.setItem('token', session.access_token);
-  //       storage.setItem('refresh_token', session.refresh_token);
-  //       storage.setItem('exp', String(session.expires_in));
-  //       storage.setItem('refresh_exp', String(session.refresh_expires_in));
-  //   } else {
-  //       console.warn("Session storage is not available.");
-  //   }
-  // }
-  // public getSessionVariable(key: string): string | null {
-  //     const storage = typeof window !== "undefined" ? sessionStorage : global.sessionStorage;
-  //     return storage ? storage.getItem(key) : null;
-  // }
-  _setSession(session) {
+  setSession(session) {
+    const storage = typeof window !== "undefined" ? sessionStorage : global.sessionStorage;
     const now = Math.floor(Date.now() / 1e3);
-    if (typeof localStorage !== "undefined") {
-      localStorage.setItem("token", session.access_token);
-      localStorage.setItem("refresh_token", session.refresh_token);
-      localStorage.setItem("exp", String(now + session.expires_in));
-      localStorage.setItem("refresh_exp", String(now + session.refresh_expires_in));
+    if (storage) {
+      storage.setItem("access_token", session.access_token);
+      storage.setItem("refresh_token", session.refresh_token);
+      storage.setItem("refresh_expires_in", String(now + session.expires_in));
+      storage.setItem("refresh_exp", String(now + session.refresh_expires_in));
     } else {
-      console.warn("\u26A0\uFE0F Local Storage not available. You will need to pass tokens manually.");
+      console.warn("Session storage is not available.");
     }
   }
+  getSessionVariable(key) {
+    const storage = typeof window !== "undefined" ? sessionStorage : global.sessionStorage;
+    return storage ? storage.getItem(key) : null;
+  }
+  // private _setSession(session: OidcToken): void {
+  //   const now = Math.floor(Date.now() / 1000);
+  //   if (typeof localStorage !== "undefined") {
+  //     localStorage.setItem('token', session.access_token);
+  //     localStorage.setItem('refresh_token', session.refresh_token);
+  //     localStorage.setItem('exp', String(now + session.expires_in));
+  //     localStorage.setItem('refresh_exp', String(now + session.refresh_expires_in));
+  //   } else {
+  //     console.warn("⚠️ Local Storage not available. You will need to pass tokens manually.");
+  //   }
+  // }
   login(email, password) {
     return this._userConsumer.login(email, password).then(
       (resp) => {
-        this._setSession(resp);
+        this.setSession(resp);
         return resp;
       }
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@singularlogic/coreplatts",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [