@snugdesk/core

@snugdesk/core is the foundational Angular library that powers Snugdesk widgets and shared modules. It provides authentication, shared helpers, and other essential services required for seamless integration of Snugdesk modules such as @snugdesk/avaya-ipo-widget, @snugdesk/whatsapp-widget, and others.

To purchase licenses or for assistance with implementing the Snugdesk libraries in your Angular web application, please contact:

SNUG Technologies Pvt Ltd
📧 [email protected]

🔐 Mandatory Dependency

IMPORTANT: This library must be installed and initialized before using any other Snugdesk widget or library.
All other Snugdesk packages depend on @snugdesk/core for centralized session management, configuration, and shared services.

✨ Features

• 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

🧩 Usage

Step 1: Install Required Peer Dependencies

npm install @auth0/angular-jwt crypto-js moment-timezone uuid

Step 2: Install the package

npm install @snugdesk/core
npm install aws-amplify@^5 @aws-amplify/api-graphql@^3

Amplify v5 is required. Other Snugdesk widgets rely on this package for AppSync configuration.

Peer dependency ranges (from the package manifest):

• Angular: >=21.0.0 (@angular/common, @angular/core, @angular/forms, @angular/platform-browser)
• 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

   // 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

   {
     "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.

   {
     "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) Provide HttpClient

The library's helpers use HttpClient, so the host application must provide it:

// main.ts (standalone bootstrap)
import { provideHttpClient } from '@angular/common/http';

bootstrapApplication(AppComponent, {
  providers: [provideHttpClient()],
});

2) Import the module (if you use the shared components)

import { SnugdeskCoreModule } from '@snugdesk/core';

@NgModule({
  imports: [SnugdeskCoreModule],
})
export class AppModule {}

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:

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:

{ "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

import { SnugdeskAuthenticationService } from '@snugdesk/core';

constructor(private authenticationService: SnugdeskAuthenticationService) {}

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

this.authenticationService.isAuthenticated$.subscribe((isAuthenticated: boolean) => {
  // Fires on authenticate(), on logout(), and once on subscribe with the current value.
});

6) End the session

await this.authenticationService.logout(userSessionId); // userSessionId is optional

What you get

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 [email protected].