@snugdesk/core 0.2.41 → 0.2.42

package/README.md

@@ -18,7 +18,7 @@ To purchase licenses or for assistance with implementing the Snugdesk libraries
 
 ## ✨ Features
 
-- Centralized session management using `tenantId` and `userId`
+- Token-based session management — your backend issues a Snugdesk session token, the library establishes the session from it
 - Shared services for authentication, token reuse, and lifecycle handling
 - Lightweight, plug-and-play design for host Angular applications
 - Built-in support for multi-widget communication and coordination
@@ -30,7 +30,6 @@ To purchase licenses or for assistance with implementing the Snugdesk libraries
 ### Step 1: Install Required Peer Dependencies
 
 ```bash
-npm install @angular/animations
 npm install @auth0/angular-jwt crypto-js moment-timezone uuid
 ```
 
@@ -48,9 +47,86 @@ Peer dependency ranges (from the package manifest):
 - RxJS: ~7.8.0
 - aws-amplify: ^5.0.0, @aws-amplify/api-graphql: ^3.0.0
 
+> `@angular/animations` is **not** required by this library. Install it only if your own app (or another Snugdesk widget) calls `provideAnimations()`.
+
+---
+
+## 🛠 Workspace Configuration (required)
+
+The AWS SDK for JavaScript expects Node-style globals (`global`, `process`) to exist. Without them the first `require` throws `ReferenceError: global is not defined` **before Angular bootstraps** — the symptom is a blank page with a single console error and no Angular output. Add the following once in your host application:
+
+1. **Create `src/custom-polyfills.ts`**
+
+   ```ts
+   // src/custom-polyfills.ts
+   (window as any).global = window;
+   (window as any).process = { env: { DEBUG: undefined } };
+   ```
+
+   Keep additional polyfills above if your app already uses this file.
+
+2. **Register the polyfill file in `angular.json`**
+
+   ```json
+   {
+     "projects": {
+       "your-app": {
+         "architect": {
+           "build": {
+             "options": {
+               "polyfills": [
+                 "zone.js",
+                 "src/custom-polyfills.ts"
+               ]
+             }
+           },
+           "test": {
+             "options": {
+               "polyfills": [
+                 "zone.js",
+                 "zone.js/testing",
+                 "src/custom-polyfills.ts"
+               ]
+             }
+           }
+         }
+       }
+     }
+   }
+   ```
+
+3. **Let TypeScript know about the polyfill file**
+
+   Only needed if your `tsconfig.app.json` / `tsconfig.spec.json` use an explicit `files` array — an `include` of `src/**/*.ts` already covers it.
+
+   ```json
+   {
+     "files": [
+       "src/custom-polyfills.ts"
+     ]
+   }
+   ```
+
+These changes ensure the library and its client SDKs run reliably in both builds and tests.
+
+---
+
 ### Step 3: Setup
 
-#### 1) Import the module (if you use the shared components)
+#### 1) Provide `HttpClient`
+
+The library's helpers use `HttpClient`, so the host application must provide it:
+
+```ts
+// main.ts (standalone bootstrap)
+import { provideHttpClient } from '@angular/common/http';
+
+bootstrapApplication(AppComponent, {
+  providers: [provideHttpClient()],
+});
+```
+
+#### 2) Import the module (if you use the shared components)
 
 ```ts
 import { SnugdeskCoreModule } from '@snugdesk/core';
@@ -61,30 +137,96 @@ import { SnugdeskCoreModule } from '@snugdesk/core';
 export class AppModule {}
 ```
 
-#### 2) Initialize authentication
+`SnugdeskCoreModule` exports the shared `ErrorComponent`, `FooterComponent` and `LoaderComponent`. The services are `providedIn: 'root'`, so you do **not** need this import just to use them.
+
+#### 3) Obtain a session token
+
+A `tenantId` and `userId` alone can no longer start a session — neither value is secret. Your **backend** exchanges a tenant integration credential for a short-lived session token.
+
+Create an integration credential once, as a tenant administrator, from **Settings → Developers → API Credentials**. Then, from your server:
+
+```http
+POST https://api.snugdesk.com/auth/library
+x-api-key: <your API gateway key>
+Authorization: Bearer <keyId>.<secret>
+Content-Type: application/json
+
+{ "userId": "<the user to open the session as>" }
+```
+
+The tenant is derived from the verified credential, so only `userId` goes in the body. The response contains a short-lived `sessionToken`:
+
+```json
+{ "data": { "sessionToken": "eyJhbGciOi..." } }
+```
+
+> **Never put the integration credential in browser code.** Anything the page can read, so can its visitors. Fetch the token server-side and pass it to the page.
+
+#### 4) Initialize authentication
 
 ```ts
 import { SnugdeskAuthenticationService } from '@snugdesk/core';
 
 constructor(private authenticationService: SnugdeskAuthenticationService) {}
 
-ngOnInit() {
-  this.authenticationService.login('yourTenantId', 'yourUserId');
+async ngOnInit(): Promise<void> {
+  const isAuthenticated = await this.authenticationService.authenticate(sessionToken);
+  if (!isAuthenticated) {
+    // The token was missing, malformed or expired — see the console for the reason.
+    return;
+  }
+
+  // The token carries every id, so nothing else needs to be supplied.
+  const tenantId = this.authenticationService.getTenantId();
+  const userId = this.authenticationService.getUserId();
+  const userSessionId = this.authenticationService.getUserSessionId();
 }
 ```
 
 > Other Snugdesk libraries will automatically retrieve and reuse the session.
 
+**Token lifetime and storage.** Tokens are short-lived and held in `sessionStorage`, so a session does not outlive the browser tab. Supply a fresh token on every app initialization rather than relying on a stored one. Passing a new token replaces whatever is stored, so switching user in the same tab works without clearing storage first.
+
+#### 5) React to session changes
+
+```ts
+this.authenticationService.isAuthenticated$.subscribe((isAuthenticated: boolean) => {
+  // Fires on authenticate(), on logout(), and once on subscribe with the current value.
+});
+```
+
+#### 6) End the session
+
+```ts
+await this.authenticationService.logout(userSessionId); // userSessionId is optional
+```
+
+---
+
 ## What you get
-- Authentication utilities (`SnugdeskAuthenticationService`)
-- Common pipes, components, and shared helpers
-- AppSync helper (`AppSyncHelperService`) that handles query/mutate/subscribe
+
+**`SnugdeskAuthenticationService`**
+- `authenticate(token)` – establish a session from a Snugdesk-issued token
+- `logout(userSessionId?)` – end the session and clear the stored token
+- `getToken()` / `getDecodedToken()` – the raw or decoded session token
+- `getTenantId()` / `getUserId()` / `getUserSessionId()` – ids read back from the token
+- `isAuthenticated()` – synchronous check; `isAuthenticated$` – observable stream
+- `getUserPreferences()` – user preferences, falling back to tenant preferences
+
+**Helpers**
+- `AppSyncHelperService` – handles query / mutate / subscribe against AppSync. Configures Amplify with bundled defaults; override with `provideAmplifyConfig({ ... })` if you point at your own endpoint.
+- `S3HelperService` – `getS3Config(token, region)` returns scoped, temporary S3 credentials for the session.
+
+**Shared code**
+- Common pipes, components (`ErrorComponent`, `FooterComponent`, `LoaderComponent`) and utilities
 - GraphQL services and shared models used by Snugdesk widgets
 
+---
+
 ## Support and licensing
 
 This library is a proprietary product of Snugdesk and is protected under applicable intellectual property laws. 
 
 > **Note**: Usage of this library requires a valid license or an active Snugdesk subscription. Unauthorized distribution or usage is strictly prohibited.
 
-For licensing inquiries or to obtain a valid subscription, please contact [sales@snugdesk.com](mailto:sales@snugdesk.com).
+For licensing inquiries or to obtain a valid subscription, please contact [sales@snug.in](mailto:sales@snug.in).