@sub-zero/cocoa 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+# Cocoa
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A circular Cocoa portrait button that opens support chat at the bottom right of any web application. Cocoa connects visitors
+to your SubZero chatbot and puts conversations in **Agents → Chatbots**, where your
+team can view, reply, approve agent drafts, and take over.
+
+Zero runtime dependencies. Works with vanilla JavaScript, React, Vue, Angular,
+and other browser frameworks. Styles live in a Shadow DOM so host styles do not
+change the widget.
+
+## Set up your chatbot
+
+1. In SubZero, configure hosted Cocoa under **Agents → Cocoa**, or connect your
+   own agent. Hosted Cocoa is a $20/month add-on using your server-stored provider
+   key; your provider charges separately. Installing this UI does not start a
+   subscription or include a hosted agent.
+2. Under **Agents → Chatbots**, create a chatbot for your project and agent.
+3. Add your website's exact origin, including scheme and development port
+   (for example `https://app.example.com` or `http://localhost:3000`), and enable it.
+4. Copy the chatbot ID from Settings & installation into the example below.
+
+Only the **public chatbot ID** belongs in this widget. Never embed a model API
+key, SubZero agent token, staff login token, or private RDK credential.
+
+## Install with npm
+
+```sh
+npm install @sub-zero/cocoa
+```
+
+```js
+import { createCocoa } from '@sub-zero/cocoa';
+
+const cocoa = createCocoa({
+  chatbotId: 'YOUR_CHATBOT_UUID',
+});
+```
+
+Call `createCocoa` after the document body exists. The bubble appears immediately;
+no conversation is created until the visitor sends a message. The default API is
+`https://api.sub-zero.dev`.
+
+### React / Next.js
+
+Mount once in a client component or application layout. Importing the package is
+safe on the server; mounting it requires a browser.
+
+```jsx
+'use client';
+import { useEffect } from 'react';
+import { createCocoa } from '@sub-zero/cocoa';
+
+export function CocoaSupport() {
+  useEffect(() => {
+    const cocoa = createCocoa({ chatbotId: 'YOUR_CHATBOT_UUID' });
+    return () => cocoa.destroy();
+  }, []);
+  return null;
+}
+```
+
+For Vue, mount in `onMounted` and destroy in `onUnmounted`. For Angular, mount in
+`ngAfterViewInit` in the browser and destroy in `ngOnDestroy`. In an SPA, mount in
+the application shell rather than on each route. For the same API/chatbot pair,
+repeated calls return the existing instance; the first caller's options apply.
+
+### Plain HTML
+
+Copy `node_modules/@sub-zero/cocoa/dist/cocoa.js` to your public assets:
+
+```html
+<script defer src="/cocoa.js" data-chatbot="YOUR_CHATBOT_UUID"></script>
+```
+
+Optional attributes: `data-api`, `data-title`, `data-launcher-label`, and
+`data-accent-color`. To initialize manually, load the script without
+`data-chatbot` and call `window.Cocoa.createCocoa(options)`. Automatic initialization
+exposes the handle as `window.Cocoa.widget`.
+
+SubZero's dashboard-hosted `/subzero-chat.js` uses the same implementation and
+continues to accept existing `data-api` and `data-chatbot` installation snippets.
+For a reproducible release, self-host the file from a pinned npm version.
+
+## Options and controls
+
+```js
+const cocoa = createCocoa({
+  chatbotId: 'YOUR_CHATBOT_UUID',
+  apiUrl: 'https://api.sub-zero.dev',
+  title: 'Acme support',
+  launcherLabel: 'Need help?',
+  welcomeMessage: 'Hi! How can we help?',
+  accentColor: '#385b50',
+  visitorLabel: 'Alex', // display name only; not a verified identity
+  persistSession: true,
+  zIndex: 2147483000,
+  pollInterval: 2500,
+  // nonce: yourCspNonce,
+  onError(error) { console.warn(error.message); },
+});
+
+cocoa.open();
+cocoa.close();
+cocoa.toggle();
+cocoa.reset();   // forget this tab's conversation; does not delete server history
+cocoa.destroy(); // remove UI, stop timers, abort requests; keep session for remount
+```
+
+`reset()` aborts in-flight requests and clears local conversation state. A message
+already accepted by the server cannot be recalled. Call it on application logout or
+account switch to avoid resuming a previous visitor's conversation in that tab.
+Use `persistSession: false` to keep credentials in memory only. With the default
+setting, the visitor credential and any unacknowledged message retry are held in
+sessionStorage. Blocked storage falls back to memory; private-browser reloads may
+therefore start a new conversation. This package does not collect the current
+page URL, app state, or account information.
+
+The widget supports Escape to close, labeled form controls, polite announcement
+of new messages, reduced motion, and narrow screens. It is a nonmodal dialog:
+visitors can continue interacting with the host page. Replies are rendered as
+plain text, never executable HTML or Markdown.
+
+Polling runs only while the chat is open and the page is visible. Errors back off
+up to 30 seconds; requests time out after 20 seconds. Message retries reuse an
+idempotency key, including after reload when sessionStorage is available. Closing
+or pausing a conversation disables sending; expired sessions offer a fresh start.
+There is no substitute AI when the assigned agent is offline. Human replies
+still arrive through the same conversation.
+
+## Security and hosting
+
+Use HTTPS for the API. HTTP is supported only for loopback development hosts.
+Visitor tokens are sent only to the configured API, with cookies omitted and
+redirects rejected. An allowed website origin controls embedding; it does not
+verify the visitor's identity. Do not provide account-specific private data
+based only on a name typed into chat.
+
+For Content Security Policy, allow `data:` under `img-src` for the bundled Cocoa portrait, the API under `connect-src`, the script source
+under `script-src`, and supply a valid nonce through the `nonce` option (or script
+nonce attribute) for the widget stylesheet. The widget uses DOM APIs and is
+compatible with Trusted Types enforcement. The supplied Cocoa portrait is bundled in the widget, so it needs no external image host. No remote fonts, images,
+iframes, analytics, model SDKs, or third-party styles are loaded.
+
+Existing SubZero chat webhooks and human approval policies apply unchanged. RDK
+knowledge and provider credentials are handled by the assigned agent and backend,
+never by this package.
+
+## Maintainers
+
+From the frontend repository:
+
+```sh
+npm run build:cocoa
+npm run test:cocoa
+cd packages/cocoa
+npm pack --dry-run
+npm publish --access public
+```
+
+The package build uses only Node built-ins. Browser tests use the frontend's
+Playwright development dependency and installed Chromium. The published tarball
+contains only `dist`, this README, and package metadata. Do not publish the private
+Angular application root. Review the version and `npm pack --dry-run` output before
+publishing. No open-source license is granted (`UNLICENSED`); the source repository
+may be private.