obi-sdk 0.19.51 → 0.19.52

package/README.md

@@ -78,6 +78,212 @@ Key features of session persistence:
 
 No additional configuration is required to enable this feature.
 
+## Command API
+
+The Obi SDK provides a programmatic command API for controlling sessions and interactions. While most users should use the [obi-loader](https://www.npmjs.com/package/obi-loader) package which provides a convenient wrapper, advanced users can access the SDK instance directly via `window.obi`.
+
+### Using window.ObiSDK() (Recommended)
+
+For most use cases, use the global `window.ObiSDK()` function provided by the obi-loader:
+
+```typescript
+// Start a session
+window.ObiSDK("startSession", { planUuid: "plan-uuid", withMicrophone: true })
+
+// Send a message
+window.ObiSDK("say", "Help me with this feature")
+
+// Stop a session
+window.ObiSDK("stopSession")
+
+// Update configuration
+window.ObiSDK("update", { showMenu: true })
+```
+
+For detailed documentation and examples of all commands, see the [obi-loader README](https://www.npmjs.com/package/obi-loader#programmatic-commands).
+
+### Advanced: Direct SDK Instance Usage
+
+Advanced users can access the SDK instance directly for more control:
+
+```typescript
+// Access the SDK instance
+const sdk = window.obi
+
+// Start a session
+await sdk.startSession({ withMicrophone: true })
+
+// Send a message
+await sdk.say("I need help with this feature")
+
+// Stop the session
+sdk.client?.stopSession()
+
+// Update configuration
+sdk.updateConfig({ showMenu: true, isActive: true })
+```
+
+### Available Commands
+
+| Command        | Description                                    | Parameters                                              |
+| -------------- | ---------------------------------------------- | ------------------------------------------------------- |
+| `update`       | Update widget configuration                    | `config: Partial<Config>` - Configuration object        |
+| `startSession` | Start an onboarding session                    | `options?: { planUuid?: string, withMicrophone?: boolean }` |
+| `say`          | Send a text message to the agent               | `message: string` - Message to send                     |
+| `stopSession`  | Stop the current session                       | None                                                    |
+
+**Note**: For comprehensive documentation, usage examples, and best practices, refer to the [obi-loader package documentation](https://www.npmjs.com/package/obi-loader).
+
+## Event API
+
+The Obi SDK extends `EventEmitter` and provides events for monitoring SDK state and responding to changes. Access the SDK instance via `window.obi` to subscribe to events.
+
+### Available Events
+
+```typescript
+// Listen for SDK initialization
+window.obi.on("initialised", () => {
+  console.log("Obi SDK is ready")
+  // Perform actions after SDK is initialized
+})
+
+// Handle errors
+window.obi.on("error", (error: Error) => {
+  console.error("Obi SDK error:", error)
+  // Report to error tracking service
+  errorTracker.captureException(error)
+})
+
+// Monitor menu visibility changes
+window.obi.on("showMenu", (isVisible: boolean) => {
+  console.log(`Menu is now ${isVisible ? "visible" : "hidden"}`)
+  // Track analytics
+  analytics.track("obi_menu_toggled", { visible: isVisible })
+})
+
+// Track configuration updates
+window.obi.on("configUpdated", () => {
+  console.log("Obi configuration has been updated")
+  // Sync with your application state
+})
+
+// Handle transient messages
+window.obi.on("showMessage", ({ text, autoCloseMs }) => {
+  console.log(`Message: ${text} (auto-close in ${autoCloseMs}ms)`)
+  // Display in custom UI if needed
+})
+```
+
+### Event Reference
+
+| Event            | Parameters                                | Description                                                    |
+| ---------------- | ----------------------------------------- | -------------------------------------------------------------- |
+| `initialised`    | None                                      | Fired when SDK initialization is complete                      |
+| `error`          | `error: Error`                            | Fired when an error occurs in the SDK                          |
+| `showMenu`       | `isVisible: boolean`                      | Fired when the widget menu visibility changes                  |
+| `configUpdated`  | None                                      | Fired when the SDK configuration is updated                    |
+| `showMessage`    | `{ text: string, autoCloseMs?: number }`  | Fired when a transient message should be displayed to the user |
+
+### Use Cases
+
+**Error Tracking Integration:**
+
+```typescript
+window.obi.on("error", (error) => {
+  // Send to Sentry, Bugsnag, or other error tracking service
+  Sentry.captureException(error, {
+    tags: { source: "obi-sdk" },
+  })
+})
+```
+
+**Analytics Integration:**
+
+```typescript
+window.obi.on("initialised", () => {
+  analytics.track("obi_sdk_loaded")
+})
+
+window.obi.on("showMenu", (isVisible) => {
+  analytics.track("obi_menu_interaction", {
+    action: isVisible ? "opened" : "closed",
+    timestamp: new Date().toISOString(),
+  })
+})
+```
+
+**UI Synchronization:**
+
+```typescript
+// Sync menu state with your application UI
+window.obi.on("showMenu", (isVisible) => {
+  document.getElementById("obi-menu-indicator")?.classList.toggle("active", isVisible)
+})
+
+// Display custom notifications
+window.obi.on("showMessage", ({ text, autoCloseMs }) => {
+  showCustomToast(text, autoCloseMs || 5000)
+})
+```
+
+**State Management Integration:**
+
+```typescript
+// Redux example
+window.obi.on("configUpdated", () => {
+  store.dispatch(obiConfigUpdated())
+})
+
+window.obi.on("error", (error) => {
+  store.dispatch(obiError(error.message))
+})
+
+// React state example
+function useObiEvents() {
+  const [isMenuVisible, setIsMenuVisible] = useState(false)
+  const [isInitialized, setIsInitialized] = useState(false)
+
+  useEffect(() => {
+    const sdk = window.obi
+
+    sdk.on("initialised", () => setIsInitialized(true))
+    sdk.on("showMenu", setIsMenuVisible)
+
+    return () => {
+      sdk.off("initialised")
+      sdk.off("showMenu")
+    }
+  }, [])
+
+  return { isMenuVisible, isInitialized }
+}
+```
+
+### TypeScript Support
+
+The SDK provides full TypeScript support for events:
+
+```typescript
+import type { ObiSDK, ObiSDKEvents } from "@obi/obi-sdk"
+
+// Event handlers are fully typed
+window.obi.on("initialised", () => {
+  // No parameters
+})
+
+window.obi.on("error", (error: Error) => {
+  // error is typed as Error
+})
+
+window.obi.on("showMenu", (isVisible: boolean) => {
+  // isVisible is typed as boolean
+})
+
+window.obi.on("showMessage", ({ text, autoCloseMs }) => {
+  // Parameters are typed correctly
+})
+```
+
 ## Engagement Sessions
 
 The SDK also tracks lightweight engagement sessions per product + onboardee for analytics. A new engagement session starts after 30 minutes of inactivity and is stored in `localStorage`. You can subscribe to the `engagementSessionStarted` event and read current values via `getEngagementInfo()` on the SDK instance (available as `window.obi` when using the loader).