README-first/progress/TASK-emojis.md

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?)
• 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:

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.