# 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:**
- **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 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 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`
- [ ] 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

**New Retrieval Endpoints:**
- [ ] `GET /api/v2/report/emoji?parentHandleId=<handleId>` gets all active `emoji_claim` records for an item, paged

**Modify existing endpoints:**
- [ ] 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

**New TypeScript Interfaces:**
- [ ] New type send to server:
```typescript
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;
}
```
- [ ] Add `emojiCount` field (map of emoji to count) to `GiveSummaryRecord` interface

### 6. Test
- [ ] Write tests for each case on the back end (multiple emojis, removal, etc)
- [ ] Write tests for the front end

## 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