@flostack/chat

Real-time, event-driven, plugin-based chat system built on Supabase.

Install

npm install @flostack/chat

Quick Start

import { createFlostackChat, PluginRegistry, createPlugin } from '@flostack/chat'
import { createClient } from '@supabase/supabase-js'

// 1. Create Supabase client
const supabase = createClient(SUPABASE_URL, SUPABASE_KEY)

// 2. Create chat instance
const chat = createFlostackChat(supabase)
const registry = new PluginRegistry(chat)

// 3. Define your plugin
const myPlugin = createPlugin({
  name: 'my-app',
  version: '1.0.0',
  systemMessages: [
    {
      id: 'myapp:item-created',
      name: 'Item Created',
      content: (meta) => `Created: ${meta?.name}`,
      icon: '✨',
    },
  ],
  eventTriggers: [
    {
      id: 'myapp:item-created',
      name: 'Item Created',
      systemMessageTemplateId: 'myapp:item-created',
      sendNotification: true,
    },
  ],
  initialize: async (chat) => {
    chat.registerEventHandler('myapp:item-created', async (payload) => {
      console.log('Item created:', payload)
    })
  },
})

// 4. Register and go
await registry.register(myPlugin)

Sub-path imports

// Core (chat engine, plugins, types)
import { createFlostackChat, createPlugin } from '@flostack/chat'

// React components
import { MessageItem } from '@flostack/chat/components'

// React hooks (require Supabase client)
import { useConversationMessages, useSendMessage } from '@flostack/chat/hooks'

// Database helpers
import { verifySchema, TABLES } from '@flostack/chat/db'

Database Setup

Run schema.sql in your Supabase SQL Editor. You can find it in the package:

import { getSchemaPath } from '@flostack/chat/db'
console.log(getSchemaPath()) // absolute path to schema.sql

Or copy it directly from node_modules/@flostack/chat/schema.sql.

React Hooks

import { useConversationMessages, useSendMessage } from '@flostack/chat/hooks'

function Chat({ conversationId, supabase, userId }) {
  const { messages, loading, addLocalMessage } = useConversationMessages(conversationId, supabase)
  const { sendMessage, sending } = useSendMessage(supabase)

  const handleSend = (text) => {
    sendMessage(conversationId, text, userId, 'staff')
  }

  return (
    <div>
      {messages.map(msg => <MessageItem key={msg.id} message={msg} currentUserId={userId} />)}
    </div>
  )
}

Publishing (for maintainers)

The package publishes automatically via GitHub Actions when you create a release. To publish manually:

npm run build
npm publish --access public

Bump the version in package.json before each publish. The GitHub Actions workflow requires an NPM_TOKEN secret — generate one at npmjs.com/settings/tokens and add it to your repo's Settings > Secrets.

License

MIT