# Emojis

Allow people to attach an emoji onto a record. The main entity to which emojis will be attached is the "GiveAction", ie. items that show on the front page (though technically we won't limit attachment entity types).

## Feature Design Checklist

### 1. Data Structure Design
**Emoji Claim Structure:**
- [ ] **Type**: `"Comment"` 
- [ ] **Text**: Contains emoji(s) and only emojis - e.g., `"👍"`, `"❤️🎉"`, or `"🚀"`
- [ ] **ParentItem**: Object with `identifier` field containing the handleId of the target action (e.g., GiveAction)
- [ ] **Context**: Follow existing claim pattern with `"@context": "https://schema.org"` (optional?)
- [x] The issuer is the "agent" attaching the emojis.

### 2. Database Schema Design
**New Table: `comment_claim`**
- [ ] Standard claim fields: `jwtId`, `handleId`, `issuerDid`, `issuedAt`, `claimType`
- [ ] Emoji-specific fields: `text`, `parentItemIdentifier`, `parentItemType`, `emojiOnly` (boolean)
- [ ] Indexes on `parentItemIdentifier` for efficient retrieval
- [ ] Consider emoji count aggregation strategy (computed vs. cached)

### 3. API Endpoint Design
**Submission Endpoint:**
- [ ] `POST /api/v2/claim` (reuse existing claim submission)
- [ ] Validate Comment claim structure
- [ ] Store in `comment_claim` table
- [ ] Return standard claim response with `claimId` and `handleId`
- [ ] Add to emjoi count of the parent if `give_claim`, `offer_claim`, or `plan_claim`

**Retrieval Endpoints:**
- [ ] `GET /api/v2/report/comments?parentItemId=<handleId>` - Get all emojis for an item
  - Consider storing all emojis in a record for quick retrieval for any particular entity.

### 4. GiveAction Enhancement
**Modify existing endpoints:**
- [ ] Add `emojiCount` field to `GiveSummaryRecord` interface
- [ ] Update `dbService.getGives*` methods to include emoji counts

### 5. Client-Side Interface Design
**New TypeScript Interfaces:**
```typescript
export interface CommentClaim extends ClaimObject {
  "@context": "https://schema.org";
  "@type": "Comment";
  text: string;
  parentItem: { identifier: string };
}

### 6. Authentication & Authorization
- [ ] Emojis require valid JWT authentication (like other claims)
- [ ] Any authenticated user can add emojis to any public GiveAction
- [ ] Users can only retrieve emojis they have permission to see (follow existing visibility rules)
- [ ] Consider rate limiting for emoji submissions

### 7. Validation Rules
**Content Validation:**
- [ ] Text length limit (e.g., 280 characters like Twitter)
- [ ] Unicode emoji validation (optional - could allow any text)
- [ ] Prevent empty or whitespace-only submissions
- [ ] Sanitize text input for security

**Business Rules:**
- [ ] One emoji submission per user per item (or allow multiple?)
- [ ] Prevent self-emoji on own GiveActions (optional business rule)
- [ ] Consider moderation capabilities for inappropriate content

### 8. Performance Considerations
**Counting Strategy:**
- [ ] Option A: Real-time COUNT queries (simple, always accurate)
- [ ] Option B: Cached counts with periodic updates (faster, eventual consistency)
- [ ] Option C: Trigger-based count maintenance (complex but efficient)

**Indexing:**
- [ ] Index on `parentItemIdentifier` for emoji retrieval
- [ ] Composite index on `(parentItemIdentifier, issuerDid)` if preventing duplicates
- [ ] Consider pagination for items with many emojis

### 9. Database Migration
- [ ] Create new `comment_claim` table following existing patterns
- [ ] Add `emojiCount` column to relevant summary tables (optional optimization)
- [ ] Update database service methods
- [ ] Test migration with existing data

### 10. API Documentation
- [ ] Update Swagger documentation for new endpoints
- [ ] Document Comment claim structure
- [ ] Provide examples of emoji submission and retrieval
- [ ] Document rate limits and validation rules

## Implementation Notes

This design follows the existing Endorser Server patterns:
- [ ] Reuses the proven JWT claim submission system
- [ ] Follows the established database and API patterns
- [ ] Maintains consistency with existing visibility and authentication rules
- [ ] Supports the distributed/P2P vision by storing emojis as signed claims

The emoji feature will integrate seamlessly with the existing GiveAction display system, showing emoji counts alongside other give information and providing a separate endpoint for detailed emoji retrieval when users want to see who reacted and with what emojis.