doc: finish refactor of task list for emoji feature

progress/TASK-emojis.md

@@ -7,75 +7,85 @@ Allow people to attach an emoji onto a record. The main entity to which emojis w
 
 ### 1. Data Structure Design
 **Emoji Claim Structure:**
-- [ ] **Type**: `"Comment"` 
+- **Context**: `"@context": "https://endorser.ch"`
-- [ ] **Text**: Contains one emoji - e.g., `"👍"`, `"❤️"`, or `"🚀"`
+- **Type**: `"Emoji"` 
-- [ ] **ParentItem**: Object with `identifier` field containing the handleId of the target action (e.g., GiveAction)
+- **Text**: Contains one emoji - e.g., `"👍"`, `"❤️"`, or `"🚀"`
-- [ ] **Context**: Follow existing claim pattern with `"@context": "https://schema.org"` (optional)
+- **Parent Item**: Object with `lastClaimId` field containing the handleId of the target action (e.g., GiveAction)
-- [x] The issuer is the "agent" attaching the emojis.
+
+- Why not multiple emojis (eg. to optimize bandwidth & storage when using many)?
+  Because there's a possibility of removing an emoji, and then the communication and logic (on both client & server) for determining which is off and which is on becomes more complicated. It's also not a very typical action: people usually attach one at a time. It's possible, so it's an optimization worth considering someday.
 
 ### 2. Database Schema Design
-**New Table: `comment_claim`**
+**New Field on `give_claim`: `emojiCount`**
-- [ ] Standard claim fields: `jwtId`, `handleId`, `issuerDid`, `issuedAt`, `claimType`
+- [ ] map of emoji character key to numeric count of that emoji
-- [ ] Emoji-specific fields: `text`, `parentItemIdentifier`, `parentItemType`, `emojiOnly` (boolean)
+
-- [ ] Indexes on `parentItemIdentifier` for efficient retrieval
+**New Table `emoji_claim`**
-- [ ] Consider emoji count aggregation strategy (computed vs. cached)
+- [ ] Standard claim fields: `jwtId`, `issuerDid`, `issuedAt`
+- [ ] Emoji-specific fields: `text`, `parentItemHandleId`
+
+**Database Migration**
+- [ ] Create new `emoji_claim` table following existing patterns
+- [ ] Add `emojiCount` column to `give_claim` tables
+- [ ] Indexes on `parentItemHandleId` & `issuerDid` for efficient retrieval
 
 ### 3. API Endpoint Design
 **Submission Endpoint:**
 - [ ] `POST /api/v2/claim` (reuse existing claim submission)
-- [ ] Validate Comment claim structure
+- [ ] Validate Emoji contents: text, lastClaimId
-- [ ] Store in `comment_claim` table
+- [ ] Ensure there is no "agent". (The issuer is the "agent" attaching the emojis; it doesn't make sense to attach an emoji on behalf of someone else.)
+- [ ] Store in `emoji_claim` table
+- [ ] Update `give_claim` `emojiCount`
 - [ ] Return standard claim response with `claimId` and `handleId`
-- [ ] Add to emoji count of the parent if `give_claim`, `offer_claim`, or `plan_claim`
+- [ ] Add to emoji count of the parent if `give_claim`
-- [ ] Allow for a removal of a previous emoji: if they sent it before, it gets erased (like in Slack)
+- [ ] Allow for a removal of a previous emoji: if they sent it before, it gets toggled (like in Slack) and entry in `emoji_claim` for this `issuerDid` + `parentHandleId` + `text` is erased
 
-**Retrieval Endpoints:**
+**New Retrieval Endpoints:**
-- [ ] `GET /api/v2/report/comments?parentItemId=<handleId>` - Get all emojis for an item
+- [ ] `GET /api/v2/report/emoji?parentHandleId=<handleId>` gets all active `emoji_claim` records for an item, paged
-  - 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
+- [ ] Update types and API documentation
+
+**API Documentation**
+- [ ] Update Swagger documentation for new endpoints
+- [ ] Document Emoji claim structure
+- [ ] Provide examples of emoji submission and retrieval
+
+**Authentication & Authorization**
+- Emojis require valid JWT authentication (like other claims)
+- Any authenticated user can add emojis to any public GiveAction
+- Users can retrieve all emoji taggers on a particular GiveAction, though DIDs are subject to visibility constraints
+
+### 5. Client-Side
+**Add to UI**
+- [ ] Add the button for adding emojis, and a click sends it
+  - See https://www.npmjs.com/package/emoji-mart-vue-fast
+- [ ] UI should show new emoji quickly
+- [ ] Show the previous emojis with their count, with data from GiveSummaryRecord
+- [ ] Clicking on an emoji already sent from this person removes it
 
-### 5. Client-Side Interface Design
 **New TypeScript Interfaces:**
+- [ ] New type send to server:
 ```typescript
-export interface CommentClaim extends ClaimObject {
+export interface EmojiClaim extends ClaimObject {
-  "@context": "https://schema.org";
+  // the "@context" for this is implicitly "https://endorser.ch"
-  "@type": "Comment";
+  "@type": "Emoji";
+  text: string;
+  lastClaimId: string;
+}
+export interface EmojiSummaryRecord {
+  issuedAt: string; // date
+  issuerDid: string;
+  jwtId: string;
+  parentItemHandleId: string;
   text: string;
-  parentItem: { identifier: string };
 }
 ```
+- [ ] Add `emojiCount` field (map of emoji to count) to `GiveSummaryRecord` interface
 
-### 6. Authentication & Authorization
+### 6. Test
-- [ ] Emojis require valid JWT authentication (like other claims)
+- [ ] Write tests for each case on the back end (multiple emojis, removal, etc)
-- [ ] Any authenticated user can add emojis to any public GiveAction
+- [ ] Write tests for the front end
-- [ ] Users can retrieve all emojis
-
-### 7. Performance Considerations
-**Counting Strategy:**
-- [ ] Real-time COUNT queries (simple, always accurate)
-
-**Indexing:**
-- [ ] Index on `parentItemIdentifier` for emoji retrieval
-- [ ] Consider pagination for items with many emojis
-
-### 8. Database Migration
-- [ ] Create new `comment_claim` table following existing patterns
-- [ ] Add `emojiCount` column to relevant summary tables
-- [ ] Update database service methods
-- [ ] Test migration with existing data
-
-### 9. 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
-
-### 10. Performance Considerations
-- [ ] Cached counts with periodic updates (faster, eventual consistency)
 
 ## Implementation Notes