# Firehose Event Handlers Implementation Guide - Reusing Existing Use Cases

## Overview

This implementation reuses existing use cases as much as possible for handling firehose events. The key insight is that firehose events represent already-published records, so we need to skip the publishing step and use the provided AT URI + CID as the published record ID.

## Architecture Approach

1. **Reuse existing use cases** - Leverage existing business logic in use cases
2. **Skip publishing for firehose events** - Add optional `publishedRecordId` parameter to use cases
3. **Use AT URI resolution** - Convert AT URIs from firehose events to domain entities
4. **Minimal changes** - Keep modifications as simple as possible

## Implementation Strategy

### Core Pattern

Each firehose processor will:

1. Parse the AT URI and extract relevant data from the record
2. Use `IAtUriResolutionService` to resolve AT URIs to domain entities
3. Call existing use cases with an optional `publishedRecordId` parameter
4. When `publishedRecordId` is provided, skip publishing and use that ID for marking as published

### Use Case Modifications

Add optional `publishedRecordId?: PublishedRecordId` parameter to these use cases:

- `AddUrlToLibraryUseCase`
- `CreateCollectionUseCase`
- `UpdateCollectionUseCase`
- `DeleteCollectionUseCase`
- `RemoveCardFromLibraryUseCase`

For `UpdateUrlCardAssociationsUseCase`, we'll need a more complex approach since it handles multiple operations. We'll add optional parameters for collection link published record IDs.

## Event Handling Implementation

### URL Card Events

#### Create

- Extract URL and curator DID from record
- Call `AddUrlToLibraryUseCase` with `publishedRecordId` from event

#### Update

- Skip for now (URL cards don't typically update)

#### Delete

- Resolve AT URI to card ID
- Call `RemoveCardFromLibraryUseCase` with `publishedRecordId` to skip unpublishing

### Note Card Events

#### Create/Update

- Extract parent card AT URI, note text, and curator DID
- Resolve parent card AT URI to card ID
- Call `UpdateUrlCardAssociationsUseCase` with note and `publishedRecordId`

#### Delete

- Resolve AT URI to card ID
- Verify it's a note card
- Call `RemoveCardFromLibraryUseCase` with `publishedRecordId`

### Collection Events

#### Create

- Extract name, description, curator DID from record
- Call `CreateCollectionUseCase` with `publishedRecordId` from event

#### Update

- Resolve AT URI to collection ID
- Extract updated fields from record
- Call `UpdateCollectionUseCase` with `publishedRecordId`

#### Delete

- Resolve AT URI to collection ID
- Call `DeleteCollectionUseCase` with `publishedRecordId` to skip unpublishing

### Collection Link Events

#### Create

- Extract collection and card strong refs from record
- Resolve AT URIs to collection ID and card ID
- Call `UpdateUrlCardAssociationsUseCase` with `addToCollections` and link `publishedRecordId`

#### Delete

- Extract collection and card strong refs from record
- Resolve AT URIs to collection ID and card ID
- Call `UpdateUrlCardAssociationsUseCase` with `removeFromCollections` and link `publishedRecordId`

## Key Benefits

1. **Reuses existing business logic** - No duplication of validation and domain rules
2. **Minimal code changes** - Just add optional parameters to existing use cases
3. **Consistent behavior** - Same validation and error handling as normal operations
4. **Simple to test** - Can test firehose handling by calling existing use cases with mock data

## Files to Modify

### Use Cases (add optional publishedRecordId parameter):

- `AddUrlToLibraryUseCase.ts`
- `CreateCollectionUseCase.ts`
- `UpdateCollectionUseCase.ts`
- `DeleteCollectionUseCase.ts`
- `RemoveCardFromLibraryUseCase.ts`
- `UpdateUrlCardAssociationsUseCase.ts` (more complex - add collection link published record IDs)

### Firehose Processors (simplify to call existing use cases):

- `ProcessCardFirehoseEventUseCase.ts`
- `ProcessCollectionFirehoseEventUseCase.ts`
- `ProcessCollectionLinkFirehoseEventUseCase.ts`

### Services (add mapping storage methods):

- `IAtUriResolutionService.ts` (already has the methods we need)

This approach maintains clean separation of concerns while maximizing code reuse and minimizing the complexity of firehose event handling.