uapp-communication-sdk 1.0.0-dev.101

package/README.md

@@ -0,0 +1,747 @@
+# UAPP Communication SDK
+
+Embed Communication Hub modules inside your own web application with a small, typed JavaScript SDK.
+
+The SDK can show these widgets:
+
+- **Chat** — conversations, messages, calls, and media.
+- **Bookings** — booking and managing meetings.
+- **Schedule** — calendar and availability screens.
+- **Feed** — posts, updates, and notifications.
+
+Package name: `uapp-communication-sdk`
+
+> The package is published from the `develop` branch as prerelease builds tagged `dev`.
+> Until a stable release is published, install the dev channel with:
+>
+> ```bash
+> npm install uapp-communication-sdk@dev
+> ```
+
+---
+
+## 1. What this SDK does
+
+The SDK gives you ready-made Communication Hub widgets that you can place in another website or product.
+
+You do **not** build chat, feed, booking, or schedule UI yourself. You only:
+
+1. Create an SDK API key in Communication Hub.
+2. Add your site origin to the key allowlist.
+3. Add a small server endpoint that signs the current user.
+4. Install this package and register the widgets.
+5. Place a widget tag such as `<uapp-chat>` on your page.
+
+The widget then talks directly to the Communication Hub API using short-lived credentials issued for the current user.
+
+---
+
+## 2. Requirements
+
+Your app needs:
+
+- **React 18** and **React DOM 18** when using the npm package through a bundler.
+- A Communication Hub **client key**.
+- A Communication Hub **client secret**.
+- A backend endpoint in your own app that can sign a short-lived assertion for the logged-in user.
+- Your website origin added to the SDK key allowlist, for example `https://example.com`.
+
+### Important security rule
+
+The **client key** can be visible in the browser.
+
+The **client secret must never be sent to the browser**. Keep it only on your server, environment variables, or secret manager. Anyone with the secret can sign in as users for that SDK key.
+
+---
+
+## 3. Installation
+
+For the current prerelease/dev channel:
+
+```bash
+npm install uapp-communication-sdk@dev
+```
+
+After a stable release exists, normal installation will be:
+
+```bash
+npm install uapp-communication-sdk
+```
+
+Peer dependencies:
+
+```bash
+npm install react@^18.3.1 react-dom@^18.3.1
+```
+
+---
+
+## 4. Quick start: React, Vite, Next.js, or any bundler
+
+Register the custom elements once in your application entry file.
+
+Example: `src/main.tsx`, `src/App.tsx`, or your layout/bootstrap file.
+
+```ts
+import { defineCustomElements } from 'uapp-communication-sdk';
+
+// Safe to call more than once. Existing elements are not registered again.
+defineCustomElements();
+```
+
+Then place the widget in your page and assign its `config` property.
+
+```tsx
+import { useEffect, useRef } from 'react';
+
+type UappChatElement = HTMLElement & {
+  config?: Record<string, unknown>;
+};
+
+export function CommunicationHubChat() {
+  const chatRef = useRef<UappChatElement | null>(null);
+
+  useEffect(() => {
+    if (!chatRef.current) return;
+
+    chatRef.current.config = {
+      clientKey: 'YOUR_CLIENT_KEY',
+      apiBaseUrl: 'https://YOUR_COMMUNICATION_HUB_API_URL',
+      modules: ['commhub.chat'],
+      auth: {
+        kind: 'signed',
+        getAssertion: async () => {
+          const response = await fetch('/api/commhub-assertion', {
+            credentials: 'include',
+          });
+
+          if (!response.ok) {
+            throw new Error('Failed to get Communication Hub assertion');
+          }
+
+          return response.text();
+        },
+      },
+      onEvent: (event) => {
+        console.log('[Communication Hub]', event.type, event.payload);
+      },
+    };
+  }, []);
+
+  return (
+    <uapp-chat
+      ref={chatRef}
+      style={{ display: 'block', height: 'calc(100vh - 120px)' }}
+    />
+  );
+}
+```
+
+### TypeScript custom element note
+
+If TypeScript does not know the widget tags, add a small declaration file such as `src/uapp-sdk.d.ts`:
+
+```ts
+import type { DetailedHTMLProps, HTMLAttributes } from 'react';
+
+declare module 'react/jsx-runtime' {
+  namespace JSX {
+    interface IntrinsicElements {
+      'uapp-chat': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+      'uapp-bookings': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+      'uapp-schedule': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+      'uapp-feed': DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement>;
+    }
+  }
+}
+```
+
+---
+
+## 5. Available widgets and module scopes
+
+Each widget needs the matching module scope. Ask only for the modules used on that page.
+
+| Widget tag        | Required module scope | What it shows                                   |
+| ----------------- | --------------------- | ----------------------------------------------- |
+| `<uapp-chat>`     | `commhub.chat`        | Messaging, conversations, calls, and chat media |
+| `<uapp-bookings>` | `commhub.bookings`    | Meeting booking and booking management          |
+| `<uapp-schedule>` | `commhub.schedule`    | Calendar, availability, and schedule blocks     |
+| `<uapp-feed>`     | `commhub.feed`        | Feed posts, updates, and notifications          |
+
+Example with multiple widgets on one page:
+
+```tsx
+useEffect(() => {
+  const config = {
+    clientKey: 'YOUR_CLIENT_KEY',
+    apiBaseUrl: 'https://YOUR_COMMUNICATION_HUB_API_URL',
+    modules: ['commhub.chat', 'commhub.feed'],
+    auth: {
+      kind: 'signed',
+      getAssertion: async () => {
+        const response = await fetch('/api/commhub-assertion', {
+          credentials: 'include',
+        });
+        return response.text();
+      },
+    },
+  };
+
+  chatRef.current!.config = config;
+  feedRef.current!.config = config;
+}, []);
+```
+
+If a token is missing a required scope, the widget may load but API calls will fail with permission errors.
+
+---
+
+## 6. Configuration reference
+
+Every widget receives configuration through its DOM `config` property.
+
+```ts
+const config = {
+  clientKey: 'YOUR_CLIENT_KEY',
+  apiBaseUrl: 'https://YOUR_COMMUNICATION_HUB_API_URL',
+  modules: ['commhub.chat'],
+  auth: {
+    kind: 'signed',
+    getAssertion: async () => 'SIGNED_ASSERTION_FROM_YOUR_SERVER',
+  },
+  theme: {
+    brand: [221, 83, 53],
+    accent: [271, 76, 53],
+    radius: 10,
+    density: 'comfortable',
+    mode: 'system',
+    font: 'Inter, system-ui, sans-serif',
+  },
+  onEvent: (event) => console.log(event),
+};
+```
+
+### `clientKey`
+
+Your SDK client key from Communication Hub.
+
+This is safe to place in browser code. It identifies the SDK client but does not authenticate users by itself.
+
+### `apiBaseUrl`
+
+The base URL of the Communication Hub API.
+
+Example:
+
+```ts
+apiBaseUrl: 'https://api.your-communication-hub.com';
+```
+
+Do not point this to your own app API. Point it to the Communication Hub API that issues SDK tokens and serves widget data.
+
+### `modules`
+
+The Communication Hub modules this page needs.
+
+Allowed values:
+
+```ts
+['commhub.chat', 'commhub.bookings', 'commhub.schedule', 'commhub.feed'];
+```
+
+Best practice:
+
+- Use `['commhub.chat']` for a chat-only page.
+- Use `['commhub.feed']` for a feed-only page.
+- Use multiple scopes only when the page truly renders multiple modules.
+
+Requesting a scope that the API key is not allowed to use fails the token request with `invalid_scope`.
+
+### `auth`
+
+For browser custom elements, use signed auth:
+
+```ts
+auth: {
+  kind: 'signed',
+  getAssertion: async () => {
+    const response = await fetch('/api/commhub-assertion', {
+      credentials: 'include',
+    });
+    return response.text();
+  },
+}
+```
+
+`getAssertion` should call your own backend. Your backend signs an assertion for the current logged-in user. The browser should never sign assertions itself.
+
+### `theme`
+
+Optional visual customization.
+
+```ts
+theme: {
+  brand: [221, 83, 53],       // HSL: hue, saturation %, lightness %
+  accent: [271, 76, 53],      // HSL: hue, saturation %, lightness %
+  radius: 10,                 // corner radius in pixels
+  density: 'comfortable',     // 'comfortable' or 'compact'
+  mode: 'system',             // 'light', 'dark', or 'system'
+  font: 'Inter, sans-serif',
+}
+```
+
+### `onEvent`
+
+Optional callback for widget lifecycle and errors.
+
+```ts
+onEvent: (event) => {
+  if (event.type === 'error') {
+    console.error('Communication Hub widget error:', event.payload);
+  }
+};
+```
+
+Events:
+
+| Event          | Meaning                                                                               |
+| -------------- | ------------------------------------------------------------------------------------- |
+| `ready`        | The widget received a token and is ready. The payload lists granted modules.          |
+| `scope-denied` | The token exists but does not include a module required by this widget.               |
+| `auth-expired` | A request was rejected as unauthenticated. The widget will ask for another assertion. |
+| `error`        | Something failed inside the widget. Log this for support/debugging.                   |
+
+---
+
+## 7. Server side: signing user assertions
+
+The widget needs a short-lived signed assertion to exchange for a Communication Hub token.
+
+Your server should:
+
+1. Verify the user is logged in to your app.
+2. Build a JWT payload for that user.
+3. Sign it with your Communication Hub client secret using `HS256`.
+4. Return the assertion as plain text.
+
+### Required assertion claims
+
+| Claim   | Value                                                             |
+| ------- | ----------------------------------------------------------------- |
+| `iss`   | Your Communication Hub client key                                 |
+| `aud`   | The Communication Hub audience/API URL expected by your Hub setup |
+| `sub`   | The current user's ID in your system                              |
+| `email` | The current user's email                                          |
+| `name`  | The current user's display name                                   |
+| `roles` | Your app's role names for this user                               |
+| `exp`   | Expiry time, maximum 5 minutes from now                           |
+| `jti`   | Unique random ID per assertion                                    |
+
+Each assertion should be short-lived and single-use. Do not cache it in the browser.
+
+### Node.js / Express example
+
+Install JWT support:
+
+```bash
+npm install jsonwebtoken
+npm install --save-dev @types/jsonwebtoken
+```
+
+Server route:
+
+```ts
+import crypto from 'node:crypto';
+import jwt from 'jsonwebtoken';
+import type { Request, Response } from 'express';
+
+const CLIENT_KEY = process.env.COMMHUB_CLIENT_KEY!;
+const CLIENT_SECRET = process.env.COMMHUB_CLIENT_SECRET!;
+const AUDIENCE = process.env.COMMHUB_AUDIENCE!;
+
+function signCommunicationHubAssertion(user: {
+  id: string;
+  email: string;
+  fullName: string;
+  roles: string[];
+}) {
+  return jwt.sign(
+    {
+      iss: CLIENT_KEY,
+      aud: AUDIENCE,
+      sub: user.id,
+      email: user.email,
+      name: user.fullName,
+      roles: user.roles,
+    },
+    CLIENT_SECRET,
+    {
+      algorithm: 'HS256',
+      expiresIn: '5m',
+      jwtid: crypto.randomUUID(),
+    },
+  );
+}
+
+app.get('/api/commhub-assertion', requireLogin, (req: Request, res: Response) => {
+  const assertion = signCommunicationHubAssertion(req.user);
+  res.type('text/plain').send(assertion);
+});
+```
+
+Browser side:
+
+```ts
+getAssertion: async () => {
+  const response = await fetch('/api/commhub-assertion', {
+    credentials: 'include',
+  });
+
+  if (!response.ok) {
+    throw new Error('Could not create Communication Hub assertion');
+  }
+
+  return response.text();
+};
+```
+
+### PHP example
+
+Install Firebase JWT:
+
+```bash
+composer require firebase/php-jwt
+```
+
+Example:
+
+```php
+<?php
+use Firebase\JWT\JWT;
+
+$clientKey = getenv('COMMHUB_CLIENT_KEY');
+$clientSecret = getenv('COMMHUB_CLIENT_SECRET');
+$audience = getenv('COMMHUB_AUDIENCE');
+
+$payload = [
+    'iss' => $clientKey,
+    'aud' => $audience,
+    'iat' => time(),
+    'exp' => time() + 300,
+    'jti' => bin2hex(random_bytes(16)),
+    'sub' => $user->id,
+    'email' => $user->email,
+    'name' => $user->fullName,
+    'roles' => $user->roles,
+];
+
+$assertion = JWT::encode($payload, $clientSecret, 'HS256');
+
+header('Content-Type: text/plain');
+echo $assertion;
+```
+
+---
+
+## 8. Full working HTML example after registration
+
+This example assumes your app has already imported the SDK and called `defineCustomElements()`.
+
+```html
+<uapp-chat id="commhub-chat" style="display:block;height:600px"></uapp-chat>
+
+<script>
+  document.getElementById('commhub-chat').config = {
+    clientKey: 'YOUR_CLIENT_KEY',
+    apiBaseUrl: 'https://YOUR_COMMUNICATION_HUB_API_URL',
+    modules: ['commhub.chat'],
+    auth: {
+      kind: 'signed',
+      getAssertion: async () => {
+        const response = await fetch('/api/commhub-assertion', {
+          credentials: 'include',
+        });
+        return response.text();
+      },
+    },
+    theme: {
+      mode: 'system',
+      density: 'comfortable',
+    },
+    onEvent: (event) => console.log('[commhub]', event),
+  };
+</script>
+```
+
+---
+
+## 9. Layout rules
+
+Give each widget a real height.
+
+Good:
+
+```html
+<uapp-chat style="display:block;height:600px"></uapp-chat>
+```
+
+Good:
+
+```html
+<uapp-chat style="display:block;height:calc(100vh - 120px)"></uapp-chat>
+```
+
+Inside a flex layout:
+
+```html
+<div style="display:flex;flex-direction:column;height:100vh">
+  <header>Header</header>
+  <uapp-chat style="display:block;flex:1;min-height:0"></uapp-chat>
+</div>
+```
+
+Avoid using only `height: 100%` unless every parent element up to the viewport also has a fixed height. Without a definite height, chat panels and composers may appear in the wrong place.
+
+---
+
+## 10. Common integration flow
+
+1. In Communication Hub, create an SDK key.
+2. Enable the modules the site needs: chat, bookings, schedule, or feed.
+3. Add allowed origins, for example:
+   - `http://localhost:3000`
+   - `https://yourdomain.com`
+4. Save the client key and client secret.
+5. Store the client secret on your server only.
+6. Create `/api/commhub-assertion` in your server app.
+7. Install the SDK package.
+8. Register the custom elements with `defineCustomElements()`.
+9. Add the widget tag to your page.
+10. Assign the config object to the widget element.
+11. Open the browser console and check for the `ready` event.
+
+---
+
+## 11. Troubleshooting
+
+### Widget tag appears in the DOM but nothing renders
+
+Make sure `defineCustomElements()` was called before or shortly after the tag is placed on the page.
+
+```ts
+import { defineCustomElements } from 'uapp-communication-sdk';
+defineCustomElements();
+```
+
+### Widget renders but API calls return 403
+
+Usually the `modules` array is missing or does not contain the scope required by the widget.
+
+Example for chat:
+
+```ts
+modules: ['commhub.chat'];
+```
+
+### Token request fails with `invalid_scope`
+
+The page requested a module that the SDK key is not allowed to use. Enable that module for the key or remove the scope from `modules`.
+
+### Token request fails with `invalid_grant`
+
+Common causes:
+
+- `iss` is not the client key.
+- `aud` does not match the Communication Hub audience.
+- The assertion expired.
+- The assertion lifetime is longer than 5 minutes.
+- The same assertion was reused.
+- The JWT was not signed with `HS256` and the correct client secret.
+
+### Token request fails with `unauthorized_client`
+
+The current browser origin is not in the key allowlist.
+
+Add the exact origin. Include scheme and domain. Include port for local development.
+
+Examples:
+
+```text
+http://localhost:3000
+https://example.com
+```
+
+### Token request fails with `invalid_client`
+
+The client key is wrong, disabled, or not known by the Communication Hub API.
+
+### Layout looks broken
+
+Give the widget a definite height. See [Layout rules](#9-layout-rules).
+
+### Browser says the custom element is already defined
+
+Calling `defineCustomElements()` from this SDK is idempotent. If you manually register elements elsewhere, remove the manual registration and let the SDK do it.
+
+---
+
+## 12. Security checklist
+
+Before going live, verify:
+
+- The client secret is not in frontend code.
+- The assertion endpoint requires your normal user login/session.
+- The assertion endpoint returns an assertion only for the current authenticated user.
+- Assertions expire within 5 minutes.
+- Each assertion has a unique `jti`.
+- The SDK key allowlist contains only trusted origins.
+- The `modules` array asks only for the modules used on the current page.
+- Errors from `onEvent` are logged somewhere useful.
+
+---
+
+## 13. Without a widget: status and notifications
+
+A widget only exists on the page it is mounted on, and the person using your application is usually
+somewhere else in it. Two headless clients cover that. Both render nothing, hold no React, and take
+the same options as a widget — including `getAssertion`, which must mint a **fresh** assertion every
+time it is called.
+
+### Their own status
+
+The widgets show everyone **else's** status beside their name — Available, Busy, In a meeting, Focus,
+Away — but they have no chrome of their own to set one from. This is how your header gets a status
+control:
+
+```ts
+import { createPresenceClient } from 'uapp-communication-sdk';
+
+const presence = createPresenceClient({
+  apiBaseUrl: 'https://api.commhub.example',
+  clientKey: 'sk_live_…',
+  getAssertion: () => fetch('/api/commhub-assertion').then((r) => r.text()),
+});
+
+const current = await presence.getMine(); // { status: 'available', source: 'connection', … }
+await presence.setMine({ status: 'busy', minutes: 30, note: 'On a call' });
+await presence.clearMine();
+```
+
+Three things to build against:
+
+- **`minutes`, not an end time.** The server resolves the duration against its own clock and caps it
+  at 24 hours, so a device with a wrong clock cannot extend its own status. Every status ends: there
+  is no "until I turn it off", because a status nobody remembers to clear is still showing days later
+  and an indicator nobody believes is worse than none.
+- **Render the answer, not the request.** All three calls return the RESOLVED presence, which is not
+  always what you asked for — a calendar block can outrank a self-set status. `source` tells you which
+  input won (`override`, `activity`, `calendar`, `connection`), so your UI can say "from your calendar"
+  instead of leaving somebody to wonder why they look busy.
+- **Offer "clear" only when `hasOverride` is true.** A status that came from a calendar is not theirs
+  to clear, and a dead control is a promise the feature does not keep.
+
+Every call answers `null` rather than throwing — on a failed exchange, an unreachable API, or a
+response that does not match the contract. A half-parsed status in your header is worse than none.
+
+This client reads and writes; it opens no socket. It will not tell you when somebody **else's**
+status changes — mount a widget for that: every widget polls `presence/of` for the people it is
+actually showing (every 30 seconds, visible ids only), so badges inside widgets stay fresh with no
+work on your side. If you render your own people-list OUTSIDE the widgets, poll
+`GET /api/app/presence/of?Ids=…` the same way — at most 100 ids, only the ones on screen.
+
+### Notifications
+
+```ts
+import { createNotificationClient } from 'uapp-communication-sdk';
+
+const client = createNotificationClient({
+  apiBaseUrl: 'https://api.commhub.example',
+  clientKey: 'sk_live_…',
+  getAssertion: () => fetch('/api/commhub-assertion').then((r) => r.text()),
+  onNotification: (n) => bell.add(n),
+});
+await client.start();
+```
+
+`start()` loads what is already unread and then opens the live connection — without the first half a
+badge reads zero on every page load however long the person was away. `markAsRead(id)` keeps the count
+agreeing with the Hub. Requires the `commhub.feed` scope: that is what the notification hub is scoped
+to.
+
+**Chat messages do not appear here.** This client lists stored notifications, and a chat message
+deliberately stores none — unread for a conversation is already answered by its own read pointer, and a
+second store of the same fact is a second thing to keep in step. Mount a chat widget for live messages,
+or take the webhook below.
+
+#### This client, or a webhook?
+
+|          | `createNotificationClient`                | `notification.created` webhook               |
+| -------- | ----------------------------------------- | -------------------------------------------- |
+| Runs in  | the browser, while a page is open         | your server, always                          |
+| Covers   | feed and meeting notifications            | **every** notification, chat included        |
+| Good for | a bell in a web app you already have open | push to a phone, email, anything server-side |
+
+They are not alternatives so much as different reach. A web host that only needs a badge wants the
+client; anything that must survive the tab being closed wants the webhook. Register it in
+Settings → Webhooks → Registry; the contract, including how to verify the signature and why recipients
+are matched by email rather than user id, is in [`../INTEGRATION.md`](../INTEGRATION.md) §5.
+
+---
+
+## 14. Package exports
+
+```ts
+import {
+  defineCustomElements,
+  registerChatWidget,
+  registerFeedWidget,
+  registerBookingsWidget,
+  registerScheduleWidget,
+  CommsProvider,
+  WidgetRoot,
+  SDK_MODULE_SCOPES,
+  createPresenceClient,
+  createNotificationClient,
+} from 'uapp-communication-sdk';
+
+import type {
+  AuthConfig,
+  CommsProviderProps,
+  SdkEvent,
+  SdkModuleScope,
+  ThemeConfig,
+  ThemeDensity,
+  ThemeMode,
+  WidgetRootProps,
+  PresenceClient,
+  PresenceClientOptions,
+  SdkPresence,
+  SdkPresenceSource,
+  SdkPresenceStatus,
+  SetSdkPresenceInput,
+  NotificationClient,
+  NotificationClientOptions,
+  SdkNotification,
+} from 'uapp-communication-sdk';
+```
+
+Most integrations only need `defineCustomElements()`.
+
+---
+
+## 15. Support information to collect
+
+If an integration fails, collect:
+
+- Package version from `npm list uapp-communication-sdk`.
+- Browser and browser version.
+- Widget tag used, for example `<uapp-chat>`.
+- `clientKey` value, but **not** the client secret.
+- `apiBaseUrl`.
+- `modules` array.
+- Browser console errors.
+- `onEvent` output.
+- Network response body for the failed token/API request.
+
+Never share the client secret in tickets, screenshots, chat, email, or frontend code.