TTC Chat Widget

Embeddable chat widget for TentaclesAI applications.

Installation

npm install ttc-chat-widget
# or
yarn add ttc-chat-widget
# or
pnpm add ttc-chat-widget

Quick Start

ES Modules (Recommended)

import { createChatWidget } from 'ttc-chat-widget'
// Import styles for full widget styling (optional - core positioning works without it)
import 'ttc-chat-widget/style.css'

const widget = createChatWidget({
  appId: 'your-app-id'
})

Note: The widget injects critical positioning styles automatically. Importing the CSS file adds visual polish (colors, shadows, animations) but is not required for basic functionality.

Script Tag (CDN)

<!-- Include the CSS (optional but recommended for full styling) -->
<link rel="stylesheet" href="https://unpkg.com/ttc-chat-widget/dist/ttc-chat-widget.css">

<!-- Include Vue 3 (required peer dependency) -->
<script src="https://unpkg.com/vue@3/dist/vue.global.prod.js"></script>

<!-- Include the widget -->
<script src="https://unpkg.com/ttc-chat-widget/dist/ttc-chat-widget.iife.js"></script>

<script>
  const widget = TTCChatWidget.createChatWidget({
    appId: 'your-app-id'
  })
</script>

Configuration Options

interface ChatWidgetOptions {
  // Required: Your TentaclesAI App ID
  appId: string
  
  // Optional: Container element or selector (defaults to document.body)
  container?: string | HTMLElement
  
  // Optional: Start with panel open (default: false)
  open?: boolean
  
  // Optional: Theme mode (default: 'light')
  theme?: 'light' | 'dark' | 'auto'
  
  // Optional: Custom positioning
  position?: {
    bottom?: number
    right?: number
    left?: number
    top?: number
  }
  
  // Optional: Z-index (default: 9999)
  zIndex?: number
  
  // Optional: TTC modules (classes with @ttc.describe decorated methods)
  modules?: any[]
  
  // Optional: Callbacks
  onAuthenticated?: (token: string) => void
  onLogout?: () => void
  onMessageSent?: (message: string) => void
  onMessageReceived?: (message: string) => void
}

API Methods

The createChatWidget function returns a widget instance with the following methods:

const widget = createChatWidget({ appId: 'your-app-id' })

// Open the chat panel
widget.open()

// Close the chat panel
widget.close()

// Toggle the chat panel
widget.toggle()

// Check if user is authenticated
const isLoggedIn = widget.isAuthenticated()

// Programmatically logout
widget.logout()

// Destroy the widget and clean up
widget.destroy()

// Get the Vue app instance (advanced)
const app = widget.getApp()

Examples

Custom Position

const widget = createChatWidget({
  appId: 'your-app-id',
  position: {
    bottom: 100,
    left: 24  // Position on left side instead of right
  }
})

Dark Mode

const widget = createChatWidget({
  appId: 'your-app-id',
  theme: 'dark'  // or 'auto' to follow system preference
})

With Callbacks

const widget = createChatWidget({
  appId: 'your-app-id',
  onAuthenticated: (token) => {
    console.log('User authenticated!')
    // Save token, update UI, etc.
  },
  onLogout: () => {
    console.log('User logged out')
  }
})

Mount in Specific Container

const widget = createChatWidget({
  appId: 'your-app-id',
  container: '#my-chat-container'
})

With Custom Modules

Create a module class with functions the AI can call:

import { createChatWidget, ttc } from 'ttc-chat-widget'
import { z } from 'zod'

class MyModule {
  @ttc.describe({
    doc: "Get the current weather for a city",
    inputSchema: z.object({
      city: z.string()
    }),
    outputSchema: z.object({
      temperature: z.number(),
      condition: z.string()
    })
  })
  async getWeather(city) {
    // Your implementation
    return { temperature: 72, condition: 'sunny' }
  }
}

const widget = createChatWidget({
  appId: 'your-app-id',
  modules: [MyModule]
})

Authentication Flow

1. User clicks the floating button
2. If not authenticated, a "Connect Account" screen appears
3. User clicks "Connect Account" → redirected to TentaclesAI OAuth
4. After authorization, user is redirected back with auth token
5. Widget automatically opens and user can start chatting

License

MIT