@gandalan/weblibs 1.5.19 → 1.5.20

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 +42 -94
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -3,122 +3,70 @@
3
3
  ## Deutsch
4
4
 
5
5
  ### Zweck
6
- `@gandalan/weblibs` stellt Hilfsfunktionen für die Authentifizierung und API-Kommunikation mit IDAS sowie lokale API-Aufrufe bereit.
6
+ `@gandalan/weblibs` stellt Fluent-APIs fuer IDAS und lokale REST-Aufrufe sowie das passende Auth-Handling bereit.
7
+
8
+ - `fetchEnvConfig(...)` fuer Endpunktkonfiguration
9
+ - `fluentIdasAuthManager(...)` fuer Authentifizierung
10
+ - `idasFluentApi(...)` fuer IDAS-Business-APIs
11
+ - `fluentApi(...)` fuer eigene oder lokale REST-Endpunkte
7
12
 
8
13
  ### Referenz
9
14
  - IDAS API (Swagger): https://api.dev.idas-cloudservices.net/swagger/
15
+ - JSDoc-Regeln und Typing-Konventionen: [JSDOC.md](./JSDOC.md)
10
16
 
11
17
  ### Voraussetzungen
12
- - Browser-Umgebung (es werden `window`, `localStorage`, URL-Redirects und `fetch` verwendet)
13
- - Gültiger App-Token als UUID (wird auf Anfrage von Gandalan ausgegeben)
14
- - Kontakt für Zugangsdaten/App-Token: dev-support@gandalan.de
15
- - IDAS/Auth-Base-URL vorzugsweise aus `fetchEnvConfig(...)` (z. B. `envConfig.idas`)
16
- - Falls die URL manuell gesetzt wird: mit abschließendem Slash (z. B. `https://api.dev.idas-cloudservices.net/api/`)
18
+ - Browser-Umgebung
19
+ - Gueltiger App-Token im UUID-Format
20
+ - Zugangsdaten/App-Token ueber dev-support@gandalan.de
21
+ - IDAS-Basis-URL vorzugsweise aus `fetchEnvConfig(...)`
17
22
 
18
23
  ### Installation
19
24
  ```bash
20
25
  npm i @gandalan/weblibs
21
26
  ```
22
27
 
23
- ### Schnellstart (Fluent API + Auth)
28
+ ### Schnellstart
24
29
  ```js
25
- import { fetchEnvConfig, fluentApi, fluentIdasAuthManager } from '@gandalan/weblibs';
26
-
27
- async function initializeAuthAndApi() {
28
- const serviceName = 'myService';
29
- const appToken = '00000000-0000-0000-0000-000000000000'; // UUID
30
- const envConfig = await fetchEnvConfig('dev'); // envConfig.idas kommt aus fetchEnvConfig(...)
30
+ import {
31
+ fetchEnvConfig,
32
+ fluentApi,
33
+ fluentIdasAuthManager,
34
+ idasFluentApi
35
+ } from "@gandalan/weblibs";
36
+
37
+ async function initializeApis() {
38
+ const appToken = "00000000-0000-0000-0000-000000000000";
39
+ const serviceName = "myService";
40
+ const envConfig = await fetchEnvConfig("dev");
31
41
 
32
42
  let authManager;
33
- try {
34
- authManager = await fluentIdasAuthManager(appToken, envConfig.idas).init();
35
- } catch {
36
- // init() kann auf Login umleiten und dabei eine Exception werfen.
37
- // In diesem Fall Seite verlassen / später erneut starten.
38
- return;
39
- }
40
-
41
- const idas = fluentApi(envConfig.idas, authManager, serviceName);
42
- const api = fluentApi('/api/', authManager, serviceName);
43
-
44
- const mandanten = await idas.get('mandanten');
45
- console.log(mandanten[0]?.Name);
46
-
47
- const localResult = await api.get('some-endpoint');
48
- console.log(localResult);
49
- }
50
- ```
51
-
52
- ### Exportierte APIs (Kurzüberblick)
53
- - `fetchEnvConfig(env)` lädt Endpunktkonfiguration (z. B. `dev`, `staging`, `produktiv`)
54
- - `fluentIdasAuthManager(appToken, authBaseUrl)` erzeugt Auth-Manager
55
- - `fluentApi(baseUrl, authManager, serviceName)` erzeugt API-Client mit `get/put/post/delete`
56
- - `createAuthManager()`, `createApi()`, `restClient()` für manuelle Konfiguration
57
- - Legacy zusätzlich vorhanden: `initIDAS`, `IDASFactory`, `RESTClient`
58
-
59
- ### Wichtige Hinweise
60
- - `init()` gibt nicht immer nur `null` zurück, sondern kann beim Redirect eine Exception auslösen.
61
- - Refresh-Token wird aus URL-Parameter `t` gelesen und in `localStorage` (`idas-refresh-token`) persistiert.
62
- - Ohne gültigen Auth-Status werden Requests ggf. intern per `ensureAuthenticated()` nachgezogen.
63
-
64
- ---
65
-
66
- ## English
67
43
 
68
- ### Purpose
69
- `@gandalan/weblibs` provides helpers for authentication and API communication with IDAS as well as local API calls.
70
-
71
- ### Reference
72
- - IDAS API (Swagger): https://api.dev.idas-cloudservices.net/swagger/
73
-
74
- ### Requirements
75
- - Browser environment (uses `window`, `localStorage`, URL redirects, and `fetch`)
76
- - Valid app token in UUID format (issued by Gandalan on request)
77
- - Contact for credentials/app token: dev-support@gandalan.de
78
- - Prefer the IDAS/auth base URL from `fetchEnvConfig(...)` (for example `envConfig.idas`)
79
- - If the URL is set manually, use a trailing slash (for example `https://api.dev.idas-cloudservices.net/api/`)
80
-
81
- ### Installation
82
- ```bash
83
- npm i @gandalan/weblibs
84
- ```
85
-
86
- ### Quick start (Fluent API + auth)
87
- ```js
88
- import { fetchEnvConfig, fluentApi, fluentIdasAuthManager } from '@gandalan/weblibs';
89
-
90
- async function initializeAuthAndApi() {
91
- const serviceName = 'myService';
92
- const appToken = '00000000-0000-0000-0000-000000000000'; // UUID
93
- const envConfig = await fetchEnvConfig('dev'); // envConfig.idas is provided by fetchEnvConfig(...)
94
-
95
- let authManager;
96
44
  try {
97
45
  authManager = await fluentIdasAuthManager(appToken, envConfig.idas).init();
98
46
  } catch {
99
- // init() may redirect to login and throw while doing so.
100
- return;
47
+ return null;
101
48
  }
102
49
 
103
- const idas = fluentApi(envConfig.idas, authManager, serviceName);
104
- const api = fluentApi('/api/', authManager, serviceName);
105
-
106
- const mandanten = await idas.get('mandanten');
107
- console.log(mandanten[0]?.Name);
50
+ const idas = idasFluentApi(envConfig.idas, authManager, serviceName);
51
+ const api = fluentApi("/api/", authManager, serviceName);
108
52
 
109
- const localResult = await api.get('some-endpoint');
110
- console.log(localResult);
53
+ return { idas, api, authManager };
111
54
  }
112
55
  ```
113
56
 
114
- ### Exported APIs (short overview)
115
- - `fetchEnvConfig(env)` loads endpoint configuration (for example `dev`, `staging`, `produktiv`)
116
- - `fluentIdasAuthManager(appToken, authBaseUrl)` creates an auth manager
117
- - `fluentApi(baseUrl, authManager, serviceName)` creates an API client with `get/put/post/delete`
118
- - `createAuthManager()`, `createApi()`, `restClient()` for manual composition
119
- - Legacy exports still available: `initIDAS`, `IDASFactory`, `RESTClient`
57
+ ### `init()`
58
+ - Liest Refresh-Token zuerst aus der URL, danach aus `localStorage`
59
+ - Versucht bei vorhandenem Refresh-Token ein JWT zu erneuern
60
+ - Kann bei fehlender gueltiger Session auf Login umleiten und dabei werfen
120
61
 
121
- ### Important notes
122
- - `init()` does not only return `null`; it may throw during login redirect.
123
- - Refresh token can be read from URL parameter `t` and is stored in `localStorage` (`idas-refresh-token`).
124
- - Without valid auth state, requests may trigger `ensureAuthenticated()` internally.
62
+ ### Wichtige Exporte
63
+ - `fetchEnvConfig(env)`
64
+ - `fluentIdasAuthManager(appToken, authBaseUrl)`
65
+ - `fluentApi(baseUrl, authManager, serviceName)`
66
+ - `idasFluentApi(baseUrl, authManager, serviceName)`
67
+
68
+ ### Wichtige Hinweise
69
+ - `idasFluentApi(...)` fuer IDAS-Business-Routinen verwenden
70
+ - `fluentApi(...)` fuer generische REST-Endpunkte verwenden
71
+ - `authManager.userInfo` und `idas.userInfo` enthalten dekodierte JWT-Claims
72
+ - Fuer JSDoc- und DTO-Typing-Regeln siehe [JSDOC.md](./JSDOC.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gandalan/weblibs",
3
- "version": "1.5.19",
3
+ "version": "1.5.20",
4
4
  "description": "WebLibs for Gandalan JS/TS projects",
5
5
  "keywords": [
6
6
  "gandalan"