@venturekit-pro/chat

Real-time chat for VentureKit — 1-1, group, and channel rooms with message history, presence, and read receipts.

Pre-release — API may change before 1.0.

Scope

This package implements chat only:

• 1-1, group, and channel rooms with participant roles (owner / admin / member / guest)
• Message types: text, image, file, system
• Edit / soft-delete + read receipts
• Typing indicators + presence (online / away / offline)
• Pluggable ChatStore interface — Phase 1 ships the in-memory adapter; bring your own DynamoDB / Postgres / Redis adapter for production.

Transactional notifications (email / WhatsApp / SMS / push) used to live alongside this package; they now have their own home in @venturekit/notify on the free tier. See the migration note at the bottom for what changed.

Quick start

import { createChatManager, type ChatStore } from '@venturekit-pro/chat';

const store: ChatStore = /* your storage adapter */;

const chat = createChatManager(store);

// Direct (1-1) room
const room = await chat.createDirectRoom('user-1', 'user-2');

// Send + read
await chat.sendMessage({ roomId: room.id, senderId: 'user-1', content: 'Hello!' });
const messages = await chat.getMessages(room.id, { limit: 50 });
await chat.markRead(room.id, 'user-2', messages[0].id);

API surface

| Symbol | Role | | --- | --- | | createChatManager(store) | Builds the chat manager bound to a store. | | ChatStore | Adapter interface — implement to plug Postgres/Dynamo/etc. | | RoomType, ParticipantRole, ChatMessageType | Discriminated unions for rooms / participants / messages. | | ChatRoom, Participant, ChatMessage, UnreadCount | Public read shapes returned by the manager. | | TypingEvent, UserPresence, PresenceStatus | Live state primitives — propagated by the consumer's transport. |

Storage

The package is transport-agnostic. The ChatStore interface declares 12 methods covering rooms, messages, and read receipts. Implement it against:

• DynamoDB — single-table layout, recommended for serverless apps already on the Lambda + DynamoDB stack.
• Postgres — reuse the project's existing DB; pair with pg_listen for fan-out.
• In-memory — useful for tests + the local dev path; we may ship a built-in test adapter in a future release.

There is intentionally no real-time transport baked in — pair with WebSocket (API Gateway WS), Server-Sent Events, or any pub-sub the consumer already runs.

Migration from @venturekit-pro/comms (v0.x)

The 0.1 cut of @venturekit-pro/comms bundled email, push, SMS, WhatsApp, broadcast, templates, preferences, and chat. That surface area has now split:

| Old import (@venturekit-pro/comms) | New home | | --- | --- | | createChatManager, ChatStore, ChatRoom, … | @venturekit-pro/chat (this package) | | createEmailProvider, createPushProvider, createSmsProvider | @venturekit/notify | | createCommsClient, BroadcastRequest, … | @venturekit/notify (createNotifyClient) | | createTemplateRegistry, MessageTemplate | @venturekit/notify (NotifyTemplate + createTemplateRegistry) | | NotificationPreference, isQuietHours, … | @venturekit/notify (NotificationPreferenceRow + admin helpers) |

Update both packages with one pnpm add @venturekit-pro/chat @venturekit/notify and adjust imports. The chat API is unchanged; the notify API is intent-driven (declare in vk.config.ts, get auto-provisioned SES + outbox + dispatcher).

License

Apache-2.0