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`):
```typescript
// ❌ 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`):
```typescript
// ✅ 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`

```diff
{
  "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

```bash
# 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:
```bash
# 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:
```typescript
// 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

```bash
pnpm test
```

Verify that all tests pass and functionality works correctly.

#### Step 5: Update Type Checking

```bash
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`:
```bash
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:
   ```bash
   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](https://github.com/transquinnftw/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