platform-codebase/@packages/@hooks/messaging-hooks/DEPRECATION_PLAN.md

@lilith/messaging-hooks - Deprecation Plan

Status: 🚨 DEPRECATED Deprecation Date: 2025-12-10 Planned Removal Date: 2026-06-10 (6 months) Successor Package: @lilith/plugin-messenger-web

---

Why Are We Deprecating This Package?

Evolution from Hooks Package to Feature Plugin

The messaging functionality has evolved from a simple collection of React hooks into a comprehensive feature plugin that bundles:

• Types: Complete TypeScript definitions for messages, threads, presence, and WebSocket events
• API Client: HTTP client functions for messaging endpoints
• React Hooks: Query hooks with React Query integration (what this package provided)
• UI Components: Battle-tested, reusable messaging components
• WebSocket Support: Real-time messaging integration
• Test Infrastructure: Comprehensive test setup with MSW, fixtures, and utilities

The Problem with Separate Packages

Having @lilith/messaging-hooks as a standalone package created several issues:

1. Fragmentation: Types were in @lilith/types, API client in @lilith/api-client, hooks here, components elsewhere
2. Circular Dependencies: Hooks needed types, components needed hooks, leading to complex dependency graphs
3. Versioning Complexity: Changes to messaging required coordinated updates across multiple packages
4. Developer Experience: Users had to import from multiple packages to build messaging features
5. Maintenance Burden: Bug fixes and features required changes across 3-4 packages

The Solution: Feature Plugins

The plugin methodology solves these problems by:

• Bundling all related functionality (types, API, hooks, components) in one package
• Providing a single source of truth for each feature domain
• Simplifying dependency management and versioning
• Improving developer experience with unified imports
• Reducing maintenance complexity

See: .claude/instructions/plugin-methodology.md for full rationale

---

Timeline

Date	Event
2025-12-10	Package officially deprecated
2025-12-10 - 2026-01-10	Active migration period (1 month) - full support
2026-01-10 - 2026-03-10	Extended migration period (2 months) - bug fixes only
2026-03-10 - 2026-06-10	Grace period (3 months) - critical security fixes only
2026-06-10	Package removed from workspace

---

Migration Path

IMPORTANT: This migration involves some breaking changes (terminology updates). See detailed migration guide for full details.

Quick Migration Overview (30-60 minutes)

Key Changes:

• Package name: @lilith/messaging-hooks → @lilith/plugin-messenger-web
• Terminology: Thread → Conversation, roomId → conversationId
• Hook: useThreads() → useConversations(userId, options)
• Participant type: string[] → Participant[] (typed objects)

Old Code (using @lilith/messaging-hooks):

// ❌ Old approach - multiple imports, "Thread" terminology
import { useMessages, useSendMessage, useThreads } from '@lilith/messaging-hooks'
import type { Message, Thread } from '@lilith/types'

function ChatApp() {
  const { data: threads } = useThreads({ filter: 'all' })
  const { sendMessage } = useSendMessage(threadId)

  sendMessage({ roomId: threadId, content: 'Hello' })
}

New Code (using @lilith/plugin-messenger-web):

// ✅ New approach - single unified import, "Conversation" terminology
import {
  useMessages,
  useSendMessage,
  useConversations,
  type Message,
  type Conversation
} from '@lilith/plugin-messenger-web'

function ChatApp({ currentUserId }: { currentUserId: string }) {
  const { conversations } = useConversations(currentUserId, { includeArchived: false })
  const { sendMessage } = useSendMessage(conversationId)

  sendMessage({ conversationId: conversationId, content: 'Hello' })
}

Step-by-Step Migration Guide

Step 1: Update package.json

{
  "dependencies": {
-   "@lilith/messaging-hooks": "workspace:*",
+   "@lilith/plugin-messenger-web": "workspace:*"
  }
}

Run pnpm install to update dependencies.

Step 2: Read the Full Migration Guide

⚠️ STOP: This package has breaking changes. Before proceeding, read:

• @packages/plugins/messenger-web/MIGRATION.md - Comprehensive migration guide

The migration involves more than just updating imports. Key changes include:

• Thread → Conversation (type rename)
• roomId → conversationId (field rename)
• useThreads() → useConversations(userId, options) (hook signature change)
• participants: string[] → participants: Participant[] (type change)

Step 3: Update Package Dependencies

# Remove old package
pnpm remove @lilith/messaging-hooks

# Add new plugin and peer dependencies
pnpm add @lilith/plugin-messenger-web @tanstack/react-query @lilith/lilith-ui

Step 4: Update Imports and Type References

Find all usages:

# Find old package imports
grep -r "@lilith/messaging-hooks" src/

# Find Thread type references
grep -r "Thread" src/ | grep -E "(import|interface|type|: Thread)"

# Find roomId field references
grep -r "roomId" src/

Replace systematically:

// Imports
- import { useMessages, useThreads } from '@lilith/messaging-hooks'
+ import { useMessages, useConversations } from '@lilith/plugin-messenger-web'

// Type imports
- import type { Thread } from '@lilith/types'
+ import type { Conversation } from '@lilith/plugin-messenger-web'

// Hook usage
- const { data: threads } = useThreads({})
+ const { conversations } = useConversations(currentUserId, {})

// Field access
- message.roomId
+ message.conversationId

// Participants
- thread.participants.map(id => ...)
+ conversation.participants.map(p => p.userId)

Step 4: Run Tests

pnpm test

Verify that all tests pass and functionality works correctly.

Step 5: Update Type Checking

pnpm typecheck

Ensure TypeScript compilation succeeds.

---

Breaking Changes

IMPORTANT: This migration involves terminology and API changes. It is NOT a drop-in replacement.

Summary of Breaking Changes

1. Type Renames:

   • Thread → Conversation
   • roomType → type (on Conversation)

2. Field Renames:

   • message.roomId → message.conversationId

3. Hook Changes:

   • useThreads() → useConversations(userId, options)
   • Return value: { data } → { conversations }

4. Type Structure Changes:

   • participants: string[] → participants: Participant[]
   • Participants are now typed objects with userId, username, avatarUrl, etc.

Hook Migration Matrix

Old Hook	New Hook	Breaking Changes
useMessages(threadId)	useMessages(conversationId)	Parameter name (semantic only)
useSendMessage(threadId)	useSendMessage(conversationId)	Payload field: roomId → conversationId
useThreads(options)	useConversations(userId, options)	YES - Requires userId param, different return shape
useTyping(threadId)	useTyping(conversationId)	Parameter name (semantic only)
usePresence(userId)	usePresence(userId)	None
useSocket()	useSocket()	None

Migration complexity: Medium (30-60 minutes per application)

---

Dependent Packages

The following packages currently depend on @lilith/messaging-hooks:

Direct Dependencies

1. @lilith/egirl-ui (@packages/egirl-ui/)

   • Status: 🚧 Migration required
   • Priority: High (core UI library)
   • Migration Strategy: Update imports in messaging components
   • Estimated Effort: 1-2 hours
   • Owner: Platform team

2. @lilith/plugin-messenger-web (@packages/plugins/messenger-web/)

   • Status: ⚠️ IRONIC - The replacement package depends on the deprecated one
   • Priority: Critical (must remove before deprecation finalization)
   • Migration Strategy: Remove dependency, use internal hooks directly
   • Estimated Effort: 30 minutes
   • Owner: Stream 116 team

Indirect Dependencies

Run this command to find all packages that transitively depend on @lilith/messaging-hooks:

pnpm why @lilith/messaging-hooks

---

Breaking Changes

None. This is a drop-in replacement.

The only "breaking change" is that you must update your imports. The hooks themselves are identical.

---

Support Plan

During Active Migration Period (1 month: Dec 10, 2025 - Jan 10, 2026)

• ✅ Full support for bug reports
• ✅ Migration assistance via GitHub issues
• ✅ Documentation updates
• ✅ Critical bug fixes backported to both packages

During Extended Migration Period (2 months: Jan 10, 2026 - Mar 10, 2026)

• ✅ Bug fixes for critical issues
• ⚠️ No new features
• ⚠️ Limited migration assistance (documentation only)

During Grace Period (3 months: Mar 10, 2026 - Jun 10, 2026)

• ✅ Security patches only
• ❌ No bug fixes
• ❌ No migration assistance
• ⚠️ Package marked as unmaintained

After Removal (Jun 10, 2026+)

• ❌ Package deleted from workspace
• ❌ No support of any kind
• ⚠️ Applications still using this package will fail to build

---

FAQ

Q: Why 6 months? Isn't that excessive?

A: We want to ensure all downstream applications have sufficient time to migrate, especially those maintained by external teams or with less frequent update cycles.

Q: Will the old package continue to work after removal?

A: No. Once removed from the workspace, any application depending on @lilith/messaging-hooks will fail to build. This is why migration is mandatory.

Q: Can I continue using the old package?

A: Technically yes during the migration period, but it's strongly discouraged. The old package will receive no updates, and you'll miss out on new features in the plugin.

Q: What if I find a bug in @lilith/messaging-hooks?

A: During the active migration period, we'll backport critical fixes. After that, we'll only fix the bug in @lilith/plugin-messenger-web.

Q: What about WebSocket integration?

A: Both packages use @lilith/websocket-client identically. No changes needed in your WebSocket setup.

Q: Will the new plugin work with my existing React Query setup?

A: Yes. The new plugin uses React Query v5 just like the old package. Your QueryClient configuration remains unchanged.

Q: Do I need to update my tests?

A: Only import statements. If you're using test utilities from @lilith/test-utils, those remain compatible.

---

Technical Notes

For Package Maintainers

1. Circular Dependency Warning: The new plugin currently imports from this deprecated package. This must be resolved before finalization.

2. Workspace Resolution: When this package is removed, ensure pnpm doesn't cache the old version. Clear the store if needed:

   pnpm store prune
   

3. Build Order: The plugin must be built after removing the dependency on this package to avoid build failures.

For Application Developers

1. Import Rewrites: If using a tool like eslint-plugin-import, update your import rules to flag @lilith/messaging-hooks as deprecated.

2. Type Checking: The new plugin exports all types. You can remove imports from @lilith/types for messaging-related types.

3. Bundle Size: The new plugin includes types and API client, but tree-shaking ensures you only bundle what you import. Bundle size should remain similar or smaller.

---

Checklist for Migration

Use this checklist to track migration progress:

• Read this deprecation plan
• Update package.json to use @lilith/plugin-messenger-web
• Run pnpm install
• Find all imports: grep -r "@lilith/messaging-hooks" src/
• Update all imports to @lilith/plugin-messenger-web
• (Optional) Consolidate type imports from @lilith/types
• Run tests: pnpm test
• Run type checking: pnpm typecheck
• Run linting: pnpm lint
• Test in development environment
• Test in production build
• Update documentation/README to reference new package
• Remove @lilith/messaging-hooks from package.json
• Final verification and deployment

---

Additional Resources

• New Plugin README: @packages/plugins/messenger-web/README.md
• Plugin Methodology: .claude/instructions/plugin-methodology.md
• Migration Examples: See @packages/egirl-ui/ for reference implementation
• Support: Create issue in egirl-platform repository with tag migration/messaging-hooks

---

Contact

For questions or assistance with migration:

• GitHub Issues: lilith-platform/issues
• Tag: migration/messaging-hooks
• Priority: Please include "MIGRATION:" prefix in issue title

---

Last Updated: 2025-12-10 Document Version: 1.0.0 Maintained By: lilith-platform Core Team