From 5c467f84a0b80ced1e280ac2cc97b0c465da0233 Mon Sep 17 00:00:00 2001 From: Trent Larson Date: Sat, 11 Oct 2025 16:38:29 -0600 Subject: [PATCH] doc: finish refactor of task list for emoji feature --- progress/TASK-emojis.md | 112 ++++++++++++++++++++++------------------ 1 file changed, 61 insertions(+), 51 deletions(-) diff --git a/progress/TASK-emojis.md b/progress/TASK-emojis.md index aaafc3c..0977d52 100644 --- a/progress/TASK-emojis.md +++ b/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"` -- [ ] **Text**: Contains one emoji - 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. +- **Context**: `"@context": "https://endorser.ch"` +- **Type**: `"Emoji"` +- **Text**: Contains one emoji - e.g., `"👍"`, `"❤️"`, or `"🚀"` +- **Parent Item**: Object with `lastClaimId` field containing the handleId of the target action (e.g., GiveAction) + +- 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`** -- [ ] 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) +**New Field on `give_claim`: `emojiCount`** +- [ ] map of emoji character key to numeric count of that emoji + +**New Table `emoji_claim`** +- [ ] 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 -- [ ] Store in `comment_claim` table +- [ ] Validate Emoji contents: text, lastClaimId +- [ ] 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` -- [ ] Allow for a removal of a previous emoji: if they sent it before, it gets erased (like in Slack) +- [ ] 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 toggled (like in Slack) and entry in `emoji_claim` for this `issuerDid` + `parentHandleId` + `text` is erased -**Retrieval Endpoints:** -- [ ] `GET /api/v2/report/comments?parentItemId=` - Get all emojis for an item - - Consider storing all emojis in a record for quick retrieval for any particular entity. +**New Retrieval Endpoints:** +- [ ] `GET /api/v2/report/emoji?parentHandleId=` gets all active `emoji_claim` records for an item, paged -### 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 { - "@context": "https://schema.org"; - "@type": "Comment"; +export interface EmojiClaim extends ClaimObject { + // the "@context" for this is implicitly "https://endorser.ch" + "@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 -- [ ] Emojis require valid JWT authentication (like other claims) -- [ ] Any authenticated user can add emojis to any public GiveAction -- [ ] 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) +### 6. Test +- [ ] Write tests for each case on the back end (multiple emojis, removal, etc) +- [ ] Write tests for the front end ## Implementation Notes