@venturialstd/conversations

Venturial conversations package — a product-agnostic NestJS + TypeORM library for in-app messaging (direct chats today; schema supports groups, channels, and richer message features). It is not related to vendor “Conversations” products such as Twilio Conversations; in code review and docs, refer to this package explicitly as the Venturial conversations module to avoid confusion.

Install

npm install @venturialstd/conversations

Peer dependencies (your app must provide compatible versions):

• @nestjs/common ^10 or ^11
• @nestjs/typeorm ^10 or ^11
• typeorm ^0.3

Registering the module

Import your host TypeOrmModule.forRoot(...) (or equivalent) before registering this feature module.

import { Module } from '@nestjs/common';
import { TypeOrmModule } from '@nestjs/typeorm';
import { ConversationsModule } from '@venturialstd/conversations';

@Module({
  imports: [
    TypeOrmModule.forRoot({
      /* host config: Postgres recommended (entities use timestamptz, jsonb) */
    }),
    ConversationsModule.forRoot(),
  ],
})
export class AppModule {}

ConversationsModule.forRoot() accepts optional ConversationsModuleOptions for future extension; today it registers TypeOrmModule.forFeature for the package entities and exports ConversationsService and ConversationsGroupService.

Migrations (host-owned)

This package does not ship SQL migrations. The host application owns the database and should generate and run migrations when upgrading:

1. Ensure TypeORM sees the package entities (via forFeature or entities glob including node_modules/@venturialstd/conversations/dist/**/*.entity.js if needed).
2. After a semver upgrade, diff schema changes (e.g. clientMessageId on conv_message; participantType on conv_participant; replyRootMessageId on conv_message — nullable uuid FK to thread root, VL-255) and add a migration in your repo.
3. Run migrations in your usual deploy pipeline.

Patch/minor releases may add columns or indexes; always read the release notes when bumping.

Semver

• Patch: bug fixes, internal refactors without schema changes.
• Minor: backward-compatible API or optional schema additions (with host migration).
• Major: breaking changes to public types or required schema.

Public surface (high level)

Ticket-oriented names:

• Direct chat: getOrCreateDirectConversation → ConversationSummary
• Listing: listConversationsForUser (includes participants with ParticipantType), listMessages ({ items, nextCursor }, cursor = older-than message id)
• Messages: sendTextMessage (body or text, optional clientMessageId), editMessage, softDeleteMessage, markConversationRead (readUpTo = message id)

Legacy aliases (still supported): paginateMessages (messages / nextBeforeMessageId), markReadUpTo.

• Reactions: addReaction, removeReaction
• Groups/channels: ConversationsGroupService

Errors are package-specific (ConversationForbiddenError, ConversationNotFoundError, ConversationsError, etc.); map them to HTTP in your controllers.

Adopting in a second Nest application

Create a new Nest API (or use an existing one) with TypeORM pointed at its own database. Install this package, register TypeOrmModule.forRoot with the same database flavor you use in production (Postgres is recommended), then import ConversationsModule.forRoot(). Expose HTTP routes in the host app that extract actorUserId from your auth layer (JWT, session, etc.) and call ConversationsService methods — do not add Auth0 or product-specific user modules inside this package. Generate and run migrations in the second app so its schema matches the entities. After that, both apps can share the same conversation rules while keeping auth and routing separate.

Development

npm run build
npm test

Tests use pg-mem (in-memory PostgreSQL) for fast checks of idempotency and authorization behavior.