@singularlogic/coreplatts 0.0.6 → 0.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +60 -57
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,6 +1,7 @@
1
1
  # @singularlogic/coreplatts
2
2
 
3
- A TypeScript client library to access the **BUILDSPACE** identity and storage APIs.
3
+ A TypeScript client library to access the **BUILDSPACE** identity and storage APIs.
4
+
4
5
  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.
5
6
 
6
7
  ---
@@ -35,19 +36,34 @@ const token = await client.login('user@example.com', 'password');
35
36
  console.log('Access token:', token.access_token);
36
37
  ```
37
38
 
38
- Tokens are stored in `localStorage` or `sessionStorage` and automatically refreshed when expired.
39
+ Tokens are stored in `sessionStorage` and are **automatically refreshed when expired**.
40
+
41
+ ### ⚠️ For Web Applications: Use an OIDC or Keycloak Client
42
+
43
+ We **strongly recommend** using an **OpenID Connect (OIDC)** or **Keycloak client** for web applications.
44
+
45
+ **Why?**
46
+
47
+ - ✅ More secure: handles redirect flows, token validation, and silent refresh securely.
48
+ - 🔄 Seamless session management: avoids manual token handling and refresh logic.
49
+ - 🔐 Built-in CSRF and token expiration protection.
50
+
51
+ #### Great frontend OIDC libraries:
52
+
53
+ - [oidc-client-ts](https://www.npmjs.com/package/oidc-client-ts)
54
+ - [keycloak-js](https://www.npmjs.com/package/keycloak-js)
55
+
56
+ > The `client.login(email, password)` method is designed for **CLI tools, backend services, development, and test automation** — not for production browser-based apps.
39
57
 
40
58
  ---
41
59
 
42
60
  ## 👤 User Management
43
61
 
44
62
  ```ts
45
- const me = await client.myUser(); // auto-includes access token
63
+ const me = await client.myUser();
46
64
  console.log(me.username);
47
65
  ```
48
66
 
49
- Register new users:
50
-
51
67
  ```ts
52
68
  await client.register(
53
69
  'new@user.com',
@@ -81,71 +97,30 @@ await client.addToOrganization('MyNewOrg', {
81
97
  ## 📂 Folder & File Management
82
98
 
83
99
  ```ts
84
- const folder = await client.getFolderByName('project-data');
85
- console.log(folder.files);
86
- ```
87
100
 
88
- You can also upload and download files using `Folder` and `File` methods.
101
+ const folder = await client.getFolderByName('project-data');
89
102
 
90
- Example:
103
+ const folderItems = await folder.listItems();
91
104
 
92
- ```ts
93
105
  const file = await folder.getFileByName('report.pdf');
94
106
  await file.download();
95
107
  ```
96
108
 
97
- ---
98
-
99
- ## 🔁 Automatic Token Handling
100
-
101
- All token-sensitive methods use a utility that:
102
- - Checks if the access token is expired
103
- - Refreshes it using `refresh_token` if needed
104
- - Uses `localStorage` or `sessionStorage` automatically
105
-
106
- ---
107
-
108
- ## 🧪 Example in Angular Service
109
+ ### Upload a File
109
110
 
110
111
  ```ts
111
- import { Injectable } from '@angular/core';
112
- import { Client } from '@singularlogic/coreplatts';
113
- import { environment } from '../environments/environment';
114
-
115
- @Injectable({ providedIn: 'root' })
116
- export class AuthService {
117
- client = new Client(environment.managementURL, environment.accountURL);
118
-
119
- getCurrentUser() {
120
- return this.client.myUser();
121
- }
122
- }
112
+ await folder.uploadFile(
113
+ myFile,
114
+ { title: 'dataset.csv' },
115
+ 5 * 1024 * 1024, // chunk size
116
+ 10, // concurrency
117
+ 3600 // timeout
118
+ );
123
119
  ```
124
120
 
125
121
  ---
126
122
 
127
- ## 🧱 Core Classes
128
-
129
- ### `Client`
130
-
131
- - Handles auth, session, and proxies to:
132
- - `UserConsumer`
133
- - `GroupConsumer`
134
- - `BucketConsumer`
135
- - `FolderConsumer`
136
-
137
- ### `Folder`
138
-
139
- - Can fetch files
140
- - Can upload files with chunking and concurrency control
141
-
142
- ### `File`
143
-
144
- - Can be downloaded by ID or name
145
-
146
- ---
147
-
148
- ## 📘 API Summary
123
+ ### 📘 Main Client
149
124
 
150
125
  | Method | Description |
151
126
  |--------|-------------|
@@ -161,6 +136,34 @@ export class AuthService {
161
136
 
162
137
  ---
163
138
 
139
+ ### 📘 Folder Class
140
+
141
+ | Method | Description |
142
+ |--------|-------------|
143
+ | `listItems()` | List folder contents |
144
+ | `getFileByID(id)` | Retrieve file by ID |
145
+ | `getFileByName(name)` | Retrieve file by name |
146
+ | `uploadFile(...)` | Upload file with chunked multipart support |
147
+
148
+ ---
149
+
150
+ ### 📘 File Class
151
+
152
+ | Method | Description |
153
+ |--------|-------------|
154
+ | `download()` | Download file with chunked concurrency |
155
+ | `getFilename()` | Get complete file name from metadata |
156
+
157
+ ---
158
+
159
+ ## 🔁 Automatic Token Handling
160
+
161
+ All token-sensitive methods use a utility that:
162
+
163
+ - Checks token expiration
164
+ - Automatically refreshes access tokens
165
+ - Uses `sessionStorage` only
166
+
164
167
  ## 📄 License
165
168
 
166
169
  MIT © [SingularLogic S.A.](https://www.singularlogic.eu)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@singularlogic/coreplatts",
3
- "version": "0.0.6",
3
+ "version": "0.0.9",
4
4
  "main": "dist/index.js",
5
5
  "types": "dist/index.d.ts",
6
6
  "files": [