@zoomrx/zena-chatbot-client 1.0.0

package/README.md

@@ -0,0 +1,211 @@
+# Zena Chatbot
+
+`@zoomrx/zena-chatbot-client` is a standalone web component (`<zena-chatbot>`) built with Svelte 5 and bundled via Vite into a single IIFE file. It is embedded inside host applications as a script tag — no framework dependency required on the host side.
+
+## Quick start
+
+```bash
+npm install
+npm run dev    # dev server at http://localhost:5173
+```
+
+> Requires Node.js 24 or newer. Use `nvm use --lts` if you manage multiple runtimes.
+
+## Installation
+
+```bash
+npm install @zoomrx/zena-chatbot-client
+```
+
+---
+
+## Tech stack
+
+- **Framework**: Svelte 5 (runes: `$state`, `$derived`, `$effect`, `$props`)
+- **Build tool**: Vite 8 (outputs ES module + IIFE)
+- **Styles**: Tailwind CSS 4
+- **HTTP**: ky with a memoized instance factory
+- **Testing**: Vitest + @testing-library/svelte + MSW
+- **Error tracking**: Sentry (`@sentry/browser`)
+- **Analytics**: PostHog
+- **E2E**: Playwright
+
+---
+
+## Scripts
+
+| Command | Purpose |
+|---|---|
+| `npm run dev` | Dev server at http://localhost:5173 with MSW + PostHog stub |
+| `npm run build` | Production IIFE + ES module in `dist/` |
+| `npm run preview` | Serve the production build locally |
+| `npm test -- --run` | Run all unit tests once |
+| `npm run test:coverage` | Coverage report |
+| `node e2e-test.cjs` | Playwright E2E test against localhost:5173 |
+
+---
+
+## Web Component API
+
+### Usage
+
+The recommended approach is to pass **all configuration via `get-config`** — one event, one place.
+
+```html
+<script src="path/to/zena-chatbot-client.iife.js"></script>
+
+<zena-chatbot></zena-chatbot>
+
+<script>
+  const chatbot = document.querySelector('zena-chatbot');
+
+  // All config — URLs, user ID, tokens, analytics keys — resolved in one place.
+  chatbot.on('get-config', ({ resolve }) => {
+    resolve({
+      authToken: 'Bearer eyJ...',         // required
+      zenaServerUrl: 'https://your-zena-api.com',
+      panelistServerUrl: 'https://your-panelist-server.com',
+      userId: '12345',
+      availableSurveyIds: '[1, 2, 3]',
+      nativeApp: false,
+      fabStyle: { bottom: '20px', right: '20px' },
+      fabShape: 'circle',
+      autoSuggestions: ["I'm stuck in the survey"],
+      posthogKey: 'phc_xxx',
+      posthogHost: 'https://app.posthog.com',
+      sentryDsn: 'https://xxx@sentry.io/123',
+      sentryRelease: 'zena-chatbot-client@1.0.0', // optional
+    });
+  });
+</script>
+```
+
+HTML attributes are also supported as a fallback (e.g. for static HTML pages), but `get-config` values take precedence when both are provided.
+
+### HTML Attributes (fallback)
+
+All of these can alternatively be passed via `get-config` (see Events below). When both are provided, `get-config` wins.
+
+| Attribute | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `zena-server-url` | `string` | Yes* | — | Base URL for the Zena API |
+| `user-id` | `string` | No | `''` | User identifier passed to analytics |
+| `available-survey-ids` | `string` (JSON array) | No | `'[]'` | Array of IDs (or objects with `survey_id`) currently on the user's dashboard |
+| `panelist-server-url` | `string` | No | `''` | Base URL for the panelist server (survey fetching) |
+| `native-app` | `boolean` (presence) | No | `false` | Set to enable native app mode |
+| `fab-style` | `string` (JSON object) | No | `{}` | CSS properties for FAB position/size (e.g. `{"bottom":"20px","right":"20px"}`) |
+| `fab-shape` | `string` | No | `'circle'` | `'circle'` or `'rectangle'` |
+| `auto-suggestions` | `string` (JSON array) | No | `[]` | Priority suggestions prepended to defaults |
+
+*Not required if `zenaServerUrl` is passed via `get-config`.
+
+### Methods
+
+| Method | Returns | Description |
+|---|---|---|
+| `close()` | `void` | Programmatically close the chat panel |
+| `generateConversationSummary()` | `string` | Returns last user + bot message as plain text (useful for support ticket context) |
+| `setFabStyle(style)` | `void` | Update FAB position/style without remounting — preserves chat state |
+| `on(event, handler)` | `void` | Subscribe to a component event |
+| `off(event, handler)` | `void` | Unsubscribe from a component event |
+
+### Events
+
+| Event | Payload | Description |
+|---|---|---|
+| `get-config` | `{ resolve }` | Fired once on init. Call `resolve(config)` to provide sensitive credentials. See below. |
+| `before-send` | `{ message, resolve }` | Fired before each message is sent. Call `resolve(data)` with any extra data to merge into the request. |
+| `stuck-survey-selected` | `{ survey }` | Fire-and-forget. Fired when the user selects a survey from a stuck-survey dropdown, before the support ticket is created. |
+
+#### `get-config`
+
+Fired once when the component connects. The host must call `resolve` with a
+`ZenaChatbotConfig` object. If the host does not handle the event within 2 seconds
+the component mounts with an empty auth token (API calls will fail).
+
+```js
+chatbot.on('get-config', ({ resolve }) => {
+  resolve({
+    // Credentials (required / recommended)
+    authToken: 'Bearer eyJ...',             // required
+    sentryDsn: 'https://...',               // optional — omit to disable Sentry
+    sentryRelease: '1.0.0',                 // optional — defaults to package version
+    posthogKey: 'phc_xxx',                  // optional — omit to disable analytics
+    posthogHost: 'https://app.posthog.com', // optional
+
+    // Component config (can also be set via HTML attributes as fallback)
+    zenaServerUrl: 'https://your-zena-api.com',        // required
+    panelistServerUrl: 'https://your-panelist.com',    // optional
+    userId: '12345',                                   // optional
+    availableSurveyIds: '[1, 2, 3]',                   // optional
+    nativeApp: false,                                  // optional
+    fabStyle: { bottom: '20px', right: '20px' },       // optional
+    fabShape: 'circle',                                // optional — 'circle' | 'rectangle'
+    autoSuggestions: ["I'm stuck in the survey"],      // optional
+    defaultOpen: false,                                // optional — open panel on mount
+    initialMessage: {                                  // optional — hidden trigger sent to server;
+      type: 'assistant',                               //   only the assistant response is shown.
+      text: 'Hello! How can I help?',                  //   Skipped on page reload automatically.
+    },
+  });
+});
+```
+
+#### `before-send`
+
+```js
+chatbot.on('before-send', ({ message, resolve }) => {
+  resolve({ userId: 42, sessionToken: 'abc' });
+});
+```
+
+#### `stuck-survey-selected`
+
+Fired when the user picks a survey from a `stuck_survey_dropdown` response. Fires **before** the support-ticket API call — the host receives it even if ticket creation subsequently fails.
+
+```js
+chatbot.on('stuck-survey-selected', ({ survey }) => {
+  // survey — the selected survey object { name, survey_id, wave_id, users_wave_id, ... }
+  console.log('User is stuck in survey:', survey.name);
+});
+```
+
+---
+
+## Sentry Error Tracking
+
+The package ships with Sentry support but **does not auto-initialize it**. Provide
+`sentryDsn` via the `get-config` event — the component initialises Sentry after
+credentials are resolved:
+
+```js
+chatbot.on('get-config', ({ resolve }) => {
+  resolve({
+    authToken: '...',
+    sentryDsn: 'https://YOUR_DSN@oXXXXXX.ingest.sentry.io/XXXXXX',
+    sentryRelease: 'zena-chatbot-client@1.0.0', // optional
+  });
+});
+```
+
+- `sentryRelease` is optional. When omitted it defaults to `zena-chatbot-client@<package version>` and must match the release name used when uploading sourcemaps in CI (`sentry-cli sourcemaps upload`).
+- Omit `sentryDsn` from the resolved config in local / UAT environments and Sentry will never initialise.
+- `tracesSampleRate` is always `0` — errors only, no performance tracing overhead.
+
+### Capturing errors manually
+
+`captureError` is the only Sentry helper exported from the package:
+
+```js
+import { captureError } from '@zoomrx/zena-chatbot-client';
+
+try {
+  // ...
+} catch (err) {
+  captureError(err);
+}
+```
+
+---
+
+For contribution guidelines, staging workflow, and publishing instructions see [CONTRIBUTING.md](CONTRIBUTING.md).

package/dist/favicon.svg

@@ -0,0 +1,26 @@
+<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="32" height="32" fill="black"/>
+<path d="M15.3825 15.9305L7.84295 11.3761C7.59382 11.2254 7.36435 11.0374 7.17859 10.8079C5.90014 9.22135 6.94694 6.62292 9.13889 6.62292H21.6262C23.8181 6.62292 24.8671 9.22135 23.5887 10.8079C23.4051 11.0374 23.1735 11.2254 22.9243 11.3761L15.3847 15.9327L15.3825 15.9305Z" fill="url(#paint0_linear_281_133)"/>
+<path d="M16.4403 15.8912L23.9799 20.4477C24.229 20.5985 24.4585 20.7864 24.6442 21.0159C25.9227 22.6047 24.8759 25.2009 22.6839 25.2009H10.1966C8.00468 25.2009 6.95788 22.6025 8.23633 21.0159C8.41991 20.7864 8.65156 20.5985 8.90069 20.4477L16.4403 15.8912Z" fill="url(#paint1_linear_281_133)"/>
+<path d="M19.7601 7.55691L7.55689 19.7602C6.31256 21.0045 6.31256 23.022 7.55689 24.2663C8.80121 25.5106 10.8187 25.5106 12.063 24.2663L24.2663 12.063C25.5106 10.8187 25.5106 8.80124 24.2663 7.55692C23.0219 6.31259 21.0045 6.31259 19.7601 7.55691Z" fill="white"/>
+<defs>
+<linearGradient id="paint0_linear_281_133" x1="7.96315" y1="4.67793" x2="22.225" y2="13.3277" gradientUnits="userSpaceOnUse">
+<stop stop-color="white"/>
+<stop offset="0.17" stop-color="white" stop-opacity="0.78"/>
+<stop offset="0.4" stop-color="white" stop-opacity="0.5"/>
+<stop offset="0.6" stop-color="white" stop-opacity="0.29"/>
+<stop offset="0.78" stop-color="white" stop-opacity="0.13"/>
+<stop offset="0.92" stop-color="white" stop-opacity="0.04"/>
+<stop offset="1" stop-color="white" stop-opacity="0"/>
+</linearGradient>
+<linearGradient id="paint1_linear_281_133" x1="23.8597" y1="27.1459" x2="9.59783" y2="18.494" gradientUnits="userSpaceOnUse">
+<stop stop-color="white"/>
+<stop offset="0.17" stop-color="white" stop-opacity="0.78"/>
+<stop offset="0.4" stop-color="white" stop-opacity="0.5"/>
+<stop offset="0.6" stop-color="white" stop-opacity="0.29"/>
+<stop offset="0.78" stop-color="white" stop-opacity="0.13"/>
+<stop offset="0.92" stop-color="white" stop-opacity="0.04"/>
+<stop offset="1" stop-color="white" stop-opacity="0"/>
+</linearGradient>
+</defs>
+</svg>

package/dist/mockServiceWorker.js

@@ -0,0 +1,349 @@
+/* eslint-disable */
+/* tslint:disable */
+
+/**
+ * Mock Service Worker.
+ * @see https://github.com/mswjs/msw
+ * - Please do NOT modify this file.
+ */
+
+const PACKAGE_VERSION = '2.14.3'
+const INTEGRITY_CHECKSUM = '4db4a41e972cec1b64cc569c66952d82'
+const IS_MOCKED_RESPONSE = Symbol('isMockedResponse')
+const activeClientIds = new Set()
+
+addEventListener('install', function () {
+  self.skipWaiting()
+})
+
+addEventListener('activate', function (event) {
+  event.waitUntil(self.clients.claim())
+})
+
+addEventListener('message', async function (event) {
+  const clientId = Reflect.get(event.source || {}, 'id')
+
+  if (!clientId || !self.clients) {
+    return
+  }
+
+  const client = await self.clients.get(clientId)
+
+  if (!client) {
+    return
+  }
+
+  const allClients = await self.clients.matchAll({
+    type: 'window',
+  })
+
+  switch (event.data) {
+    case 'KEEPALIVE_REQUEST': {
+      sendToClient(client, {
+        type: 'KEEPALIVE_RESPONSE',
+      })
+      break
+    }
+
+    case 'INTEGRITY_CHECK_REQUEST': {
+      sendToClient(client, {
+        type: 'INTEGRITY_CHECK_RESPONSE',
+        payload: {
+          packageVersion: PACKAGE_VERSION,
+          checksum: INTEGRITY_CHECKSUM,
+        },
+      })
+      break
+    }
+
+    case 'MOCK_ACTIVATE': {
+      activeClientIds.add(clientId)
+
+      sendToClient(client, {
+        type: 'MOCKING_ENABLED',
+        payload: {
+          client: {
+            id: client.id,
+            frameType: client.frameType,
+          },
+        },
+      })
+      break
+    }
+
+    case 'CLIENT_CLOSED': {
+      activeClientIds.delete(clientId)
+
+      const remainingClients = allClients.filter((client) => {
+        return client.id !== clientId
+      })
+
+      // Unregister itself when there are no more clients
+      if (remainingClients.length === 0) {
+        self.registration.unregister()
+      }
+
+      break
+    }
+  }
+})
+
+addEventListener('fetch', function (event) {
+  const requestInterceptedAt = Date.now()
+
+  // Bypass navigation requests.
+  if (event.request.mode === 'navigate') {
+    return
+  }
+
+  // Opening the DevTools triggers the "only-if-cached" request
+  // that cannot be handled by the worker. Bypass such requests.
+  if (
+    event.request.cache === 'only-if-cached' &&
+    event.request.mode !== 'same-origin'
+  ) {
+    return
+  }
+
+  // Bypass all requests when there are no active clients.
+  // Prevents the self-unregistered worked from handling requests
+  // after it's been terminated (still remains active until the next reload).
+  if (activeClientIds.size === 0) {
+    return
+  }
+
+  const requestId = crypto.randomUUID()
+  event.respondWith(handleRequest(event, requestId, requestInterceptedAt))
+})
+
+/**
+ * @param {FetchEvent} event
+ * @param {string} requestId
+ * @param {number} requestInterceptedAt
+ */
+async function handleRequest(event, requestId, requestInterceptedAt) {
+  const client = await resolveMainClient(event)
+  const requestCloneForEvents = event.request.clone()
+  const response = await getResponse(
+    event,
+    client,
+    requestId,
+    requestInterceptedAt,
+  )
+
+  // Send back the response clone for the "response:*" life-cycle events.
+  // Ensure MSW is active and ready to handle the message, otherwise
+  // this message will pend indefinitely.
+  if (client && activeClientIds.has(client.id)) {
+    const serializedRequest = await serializeRequest(requestCloneForEvents)
+
+    // Clone the response so both the client and the library could consume it.
+    const responseClone = response.clone()
+
+    sendToClient(
+      client,
+      {
+        type: 'RESPONSE',
+        payload: {
+          isMockedResponse: IS_MOCKED_RESPONSE in response,
+          request: {
+            id: requestId,
+            ...serializedRequest,
+          },
+          response: {
+            type: responseClone.type,
+            status: responseClone.status,
+            statusText: responseClone.statusText,
+            headers: Object.fromEntries(responseClone.headers.entries()),
+            body: responseClone.body,
+          },
+        },
+      },
+      responseClone.body ? [serializedRequest.body, responseClone.body] : [],
+    )
+  }
+
+  return response
+}
+
+/**
+ * Resolve the main client for the given event.
+ * Client that issues a request doesn't necessarily equal the client
+ * that registered the worker. It's with the latter the worker should
+ * communicate with during the response resolving phase.
+ * @param {FetchEvent} event
+ * @returns {Promise<Client | undefined>}
+ */
+async function resolveMainClient(event) {
+  const client = await self.clients.get(event.clientId)
+
+  if (activeClientIds.has(event.clientId)) {
+    return client
+  }
+
+  if (client?.frameType === 'top-level') {
+    return client
+  }
+
+  const allClients = await self.clients.matchAll({
+    type: 'window',
+  })
+
+  return allClients
+    .filter((client) => {
+      // Get only those clients that are currently visible.
+      return client.visibilityState === 'visible'
+    })
+    .find((client) => {
+      // Find the client ID that's recorded in the
+      // set of clients that have registered the worker.
+      return activeClientIds.has(client.id)
+    })
+}
+
+/**
+ * @param {FetchEvent} event
+ * @param {Client | undefined} client
+ * @param {string} requestId
+ * @param {number} requestInterceptedAt
+ * @returns {Promise<Response>}
+ */
+async function getResponse(event, client, requestId, requestInterceptedAt) {
+  // Clone the request because it might've been already used
+  // (i.e. its body has been read and sent to the client).
+  const requestClone = event.request.clone()
+
+  function passthrough() {
+    // Cast the request headers to a new Headers instance
+    // so the headers can be manipulated with.
+    const headers = new Headers(requestClone.headers)
+
+    // Remove the "accept" header value that marked this request as passthrough.
+    // This prevents request alteration and also keeps it compliant with the
+    // user-defined CORS policies.
+    const acceptHeader = headers.get('accept')
+    if (acceptHeader) {
+      const values = acceptHeader.split(',').map((value) => value.trim())
+      const filteredValues = values.filter(
+        (value) => value !== 'msw/passthrough',
+      )
+
+      if (filteredValues.length > 0) {
+        headers.set('accept', filteredValues.join(', '))
+      } else {
+        headers.delete('accept')
+      }
+    }
+
+    return fetch(requestClone, { headers })
+  }
+
+  // Bypass mocking when the client is not active.
+  if (!client) {
+    return passthrough()
+  }
+
+  // Bypass initial page load requests (i.e. static assets).
+  // The absence of the immediate/parent client in the map of the active clients
+  // means that MSW hasn't dispatched the "MOCK_ACTIVATE" event yet
+  // and is not ready to handle requests.
+  if (!activeClientIds.has(client.id)) {
+    return passthrough()
+  }
+
+  // Notify the client that a request has been intercepted.
+  const serializedRequest = await serializeRequest(event.request)
+  const clientMessage = await sendToClient(
+    client,
+    {
+      type: 'REQUEST',
+      payload: {
+        id: requestId,
+        interceptedAt: requestInterceptedAt,
+        ...serializedRequest,
+      },
+    },
+    [serializedRequest.body],
+  )
+
+  switch (clientMessage.type) {
+    case 'MOCK_RESPONSE': {
+      return respondWithMock(clientMessage.data)
+    }
+
+    case 'PASSTHROUGH': {
+      return passthrough()
+    }
+  }
+
+  return passthrough()
+}
+
+/**
+ * @param {Client} client
+ * @param {any} message
+ * @param {Array<Transferable>} transferrables
+ * @returns {Promise<any>}
+ */
+function sendToClient(client, message, transferrables = []) {
+  return new Promise((resolve, reject) => {
+    const channel = new MessageChannel()
+
+    channel.port1.onmessage = (event) => {
+      if (event.data && event.data.error) {
+        return reject(event.data.error)
+      }
+
+      resolve(event.data)
+    }
+
+    client.postMessage(message, [
+      channel.port2,
+      ...transferrables.filter(Boolean),
+    ])
+  })
+}
+
+/**
+ * @param {Response} response
+ * @returns {Response}
+ */
+function respondWithMock(response) {
+  // Setting response status code to 0 is a no-op.
+  // However, when responding with a "Response.error()", the produced Response
+  // instance will have status code set to 0. Since it's not possible to create
+  // a Response instance with status code 0, handle that use-case separately.
+  if (response.status === 0) {
+    return Response.error()
+  }
+
+  const mockedResponse = new Response(response.body, response)
+
+  Reflect.defineProperty(mockedResponse, IS_MOCKED_RESPONSE, {
+    value: true,
+    enumerable: true,
+  })
+
+  return mockedResponse
+}
+
+/**
+ * @param {Request} request
+ */
+async function serializeRequest(request) {
+  return {
+    url: request.url,
+    mode: request.mode,
+    method: request.method,
+    headers: Object.fromEntries(request.headers.entries()),
+    cache: request.cache,
+    credentials: request.credentials,
+    destination: request.destination,
+    integrity: request.integrity,
+    redirect: request.redirect,
+    referrer: request.referrer,
+    referrerPolicy: request.referrerPolicy,
+    body: await request.arrayBuffer(),
+    keepalive: request.keepalive,
+  }
+}