@spektra-cloudevents/application-copilot-widget 1.2.0 → 2.0.0

package/README.md

@@ -1,75 +1,126 @@
-# @spektra/application-copilot-widget
-
-A framework-agnostic, **CSS-library agnostic** copilot widget. It renders entirely
-inside a **Shadow DOM**, so the host app's styles (Bootstrap, Angular Material,
-Tailwind, etc.) cannot affect the widget and the widget's styles cannot leak out.
-It works in Angular, React, Vue, or plain HTML.
-
-## Build
-
-```bash
-cd packages/application-copilot-widget
-npm install
-npm run build      # outputs dist/ (ESM + CJS + types) via tsup
-```
-
-## Use (Angular example)
-
-```ts
-import { ApplicationCopilotWidget } from '@spektra/application-copilot-widget';
-
-ApplicationCopilotWidget.init({
-  projectKey: 'cloud-events',
-  environment: 'stage',
-  apiBaseUrl: environment.applicationCopilotApi,
-  signalRHubUrl: `${environment.applicationCopilotApi}/hubs/application-copilot`,
-  tenantUniqueName: this.tenantUniqueName,
-  getAuthToken: () => this.authService.accessToken,   // sent as Authorization: Bearer
-  // devUserEmail: 'someone@partner.com',              // local testing only
-
-  getContext: () => ({
-    projectKey: 'cloud-events',
-    environment: 'stage',
-    page: { pageKey: 'create-update-event', activeTab: this.activeTab, componentHint: 'ScheduleComponent' },
-    entities: { eventRequestId: this.eventRequestId },
-    uiState: {
-      disabledFields: [
-        ...(this.scheduleForm.get('startDateTime')?.disabled ? ['eventStartDate'] : []),
-        ...(this.scheduleForm.get('endDateTime')?.disabled ? ['eventEndDate'] : [])
-      ]
-    },
-    // Hint values for the Schedule rule (backend re-verifies the role):
-    clientSnapshot: {
-      sectionMode: this.sectionMode,
-      isDraftMode: this.isDraftMode,
-      isBudgetStatusClosed: this.isBudgetStatusClosed,
-      showPendingRegistrationBanner: this.showPendingRegistrationBanner,
-      eventPriorDays: this.editEventObj?.EventPriorDays,
-      controlSetting: {
-        canEdit: this.startDateControlSetting?.CanEdit,
-        priorDays: this.startDateControlSetting?.PriorDays
-      }
-    },
-    contextVersion: this.contextVersion,
-    capturedAt: new Date().toISOString()
-  })
-});
-```
-
-## Public API
-
-```ts
-ApplicationCopilotWidget.init(config);
-ApplicationCopilotWidget.open();
-ApplicationCopilotWidget.ask('Why are the dates disabled?');
-ApplicationCopilotWidget.setContext(context);
-ApplicationCopilotWidget.captureError(errorContext);
-ApplicationCopilotWidget.close();
-```
-
-## Why Shadow DOM
-
-The widget mounts a single host element and attaches `attachShadow({ mode: 'open' })`.
-All markup and CSS live inside that shadow root, and `:host { all: initial }` neutralises
-inherited styles. The result: pixel-identical rendering regardless of the host's CSS
-framework, with zero risk of class-name collisions in either direction.
+# @spektra-cloudevents/application-copilot-widget
+
+A framework-agnostic, **CSS-library agnostic** copilot widget. It renders entirely
+inside a **Shadow DOM**, so the host app's styles (Bootstrap, Angular Material,
+Tailwind, etc.) cannot affect the widget and the widget's styles cannot leak out.
+It works in Angular, React, Vue, or plain HTML.
+
+## Breaking changes in 2.0.0
+
+- The `environment` field was removed from `WidgetConfig` and `ApplicationContext`, and the
+  exported `Environment` type was removed. The Copilot API no longer uses an environment
+  parameter; each deployment has its own configuration.
+- Migration: delete `environment` from the `init()` config and from the object returned by
+  `getContext()`, remove `devUserEmail`, and provide `getAuthToken` (see below).
+- `devUserEmail` was removed and `getAuthToken` is now **required**: the Copilot API identifies the user only by
+  the validated bearer token (no `X-User-Email` header). The same token is used for the SignalR hub.
+- Sessions are opened for `tenantUniqueName` and bound to the signed-in user; the API verifies tenant membership,
+  Copilot enablement and role on every request.
+- Requires the Copilot API from Story 9453 B2 (token validation). Release the API before hosts upgrade to 2.x.
+
+## Additions in 2.0.0 (Story 9453 B4, all optional / backwards compatible)
+
+- **Knowledge-base references**: `CopilotAnswer.references: { title, url }[]` are shown under the answer as links.
+  Only absolute `https:` URLs are rendered (others are dropped); links are built with DOM APIs and open with
+  `target="_blank" rel="noopener noreferrer"`. Answer text is escaped and keeps line breaks (`white-space: pre-wrap`).
+- **Support-ticket offer**: when an answer has `supportTicketEligible: true` the widget shows `supportTicketPrompt`
+  and a "Raise a support ticket" action. Accepting fetches the server draft
+  (`GET /api/sessions/{id}/support-ticket/draft?requestId=`), shows an editable subject/description, and Send posts
+  `POST /api/sessions/{id}/support-ticket`; the response `message` is shown as confirmation. If the draft endpoint
+  is unavailable the widget falls back to a locally built draft. Older servers that do not send
+  `supportTicketEligible` keep the previous client-side heuristic.
+- **"This didn't help"**: shown under answers; resends the last question with `notHelpful: true`.
+- **Sessions**: new `resetSession()`. The widget also resets automatically when `init()` is called with a different
+  `tenantUniqueName`, when the configured tenant or the signed-in user (read from the token's `oid`/`sub`/email claim
+  for change detection only — never trusted) differs from the one the session was opened for, and when the API
+  answers **403 or 404** for a session-scoped call. A reset clears the conversation.
+- **`onOpenSupport?: () => void`**: when set, an "Open support" action appears with the ticket offer and confirmation.
+  The widget closes its panel first (synchronously) and then calls the callback, so the host can open its own
+  support UI (e.g. Zoho ASAP for the current tenant). `onOpenTicket` also closes the panel before it is called.
+- **Responsive**: below 480px the panel is full width; it is never taller than `calc(100vh - 32px)`; long text wraps
+  so there is no horizontal scroll at 375 / 768 / 1440px.
+- **`showKnowledgeUpload?: boolean`** (default `false`): the "Add to knowledge base" button in the panel header is
+  hidden unless the host sets this, e.g. only for users who may manage the knowledge base (CloudEvents Admin: System
+  Admin and Partner Admin). Re-applied on every `init()`. UI only: the Copilot API authorizes every upload.
+  **Behaviour change:** `promptUpload()` only opens the file picker when `showKnowledgeUpload` is true; otherwise it
+  just opens the panel.
+- New exported types: `CopilotReference`, `SupportTicketDraft`, `SupportTicketResult`.
+
+## Build
+
+```bash
+npm install
+npm run build      # outputs dist/ (ESM + CJS + types) via tsup
+npx tsc --noEmit   # type-check only
+```
+
+## Use (Angular example)
+
+```ts
+import { ApplicationCopilotWidget } from '@spektra-cloudevents/application-copilot-widget';
+
+ApplicationCopilotWidget.init({
+  projectKey: 'cloud-events',
+  apiBaseUrl: copilotApiUrl,
+  signalRHubUrl: `${copilotApiUrl}/hubs/application-copilot`,
+  tenantUniqueName: this.tenantUniqueName,
+  getAuthToken: () => this.currentBearerToken(),   // required: sent as Authorization: Bearer (and to SignalR)
+
+  getContext: () => ({
+    projectKey: 'cloud-events',
+    page: { pageKey: 'create-update-event', activeTab: this.activeTab, componentHint: 'ScheduleComponent' },
+    entities: { eventRequestId: this.eventRequestId },
+    uiState: {
+      disabledFields: [
+        ...(this.scheduleForm.get('startDateTime')?.disabled ? ['eventStartDate'] : []),
+        ...(this.scheduleForm.get('endDateTime')?.disabled ? ['eventEndDate'] : [])
+      ]
+    },
+    // Hints only. The backend re-verifies anything security-relevant (role, visibility).
+    clientSnapshot: {
+      sectionMode: this.sectionMode,
+      isBudgetStatusClosed: this.isBudgetStatusClosed
+    },
+    contextVersion: this.contextVersion,
+    capturedAt: new Date().toISOString()
+  }),
+
+  // Optional host hooks
+  onNavigate: (path) => this.router.navigateByUrl(path),
+  onOpenTicket: (ticket) => this.openSupportTicket(ticket),
+  onOpenSupport: () => this.supportWidget.open(),  // widget closes its panel before calling this
+  showKnowledgeUpload: this.canManageKnowledgeBase  // optional, default false: KB upload button only for KB admins
+});
+
+// On tenant switch / sign-out:
+ApplicationCopilotWidget.resetSession();
+```
+
+## Public API
+
+```ts
+ApplicationCopilotWidget.init(config);       // mount once with a WidgetConfig
+ApplicationCopilotWidget.open();
+ApplicationCopilotWidget.close();
+ApplicationCopilotWidget.show();             // show the launcher (e.g. after login / tenant check)
+ApplicationCopilotWidget.hide();             // hide launcher and panel
+ApplicationCopilotWidget.ask('Why are the dates disabled?');
+ApplicationCopilotWidget.setContext(context);
+ApplicationCopilotWidget.captureError(errorContext);
+ApplicationCopilotWidget.notify(text, suggestion?);  // show a proactive message, optional suggested question
+ApplicationCopilotWidget.promptUpload();     // open the KB upload picker (only with showKnowledgeUpload; server enforces admin rights)
+ApplicationCopilotWidget.resetSession();     // drop the session + conversation; next question opens a new session
+```
+
+## Backend endpoints used
+
+`POST /api/sessions`, `POST /api/sessions/{id}/messages` (optional `notHelpful: true`), `POST /api/sessions/{id}/intake/ask`,
+`GET /api/sessions/{id}/support-ticket/draft?requestId=`, `POST /api/sessions/{id}/support-ticket`,
+`POST /api/knowledge/upload`, and the optional SignalR hub.
+
+## Why Shadow DOM
+
+The widget mounts a single host element and attaches `attachShadow({ mode: 'open' })`.
+All markup and CSS live inside that shadow root, and `:host { all: initial }` neutralises
+inherited styles. The result: pixel-identical rendering regardless of the host's CSS
+framework, with zero risk of class-name collisions in either direction.