TECHNICAL_NOTES.md

# Technical Notes: @Mentions Implementation

## Problem

The initial implementation (v1.2.0) sent mentions as plain text using the `message` field:

```json
{
  "message": "Hey @john_designer please review this"
}
```

**Result:** Mentions appeared as plain text in Figma, not as clickable user objects. Users were not notified.

## Solution

Version 1.2.1 implements the correct format using Figma's `message_meta` structure:

```json
{
  "message_meta": [
    {"t": "Hey "},
    {"t": "@john_designer", "mention": "user_id_here"},
    {"t": " please review this"}
  ]
}
```

**Result:** Mentions appear as clickable user objects in Figma. Users receive notifications.

## Implementation Details

### 1. Message Parsing

The `parseMessageWithMentions()` function:
- Uses regex `/@@\w+/g` to find all @mentions
- Splits the message into segments (text + mentions)
- Creates a `message_meta` array with proper structure

### 2. User ID Resolution

The `getCommentUsers()` function now returns:
```javascript
{
  users: [...],        // Array of user objects for display
  usersMap: Map()      // Map of handle → user_id for mentions
}
```

### 3. Automatic Detection

Both `postFigmaComment()` and `replyToFigmaComment()`:
- Detect if message contains `@\w+` pattern
- If YES: Fetch users, parse mentions, use `message_meta`
- If NO: Use simple `message` field (backward compatible)

## Message Format Comparison

### Without Mentions (Simple)
```json
{
  "message": "This looks great!",
  "client_meta": { ... }
}
```

### With Mentions (message_meta)
```json
{
  "message_meta": [
    {"t": "Hey "},
    {"t": "@john", "mention": "123456789"},
    {"t": " and "},
    {"t": "@maria", "mention": "987654321"},
    {"t": " please review"}
  ],
  "client_meta": { ... }
}
```

## Discovery Process

This format was discovered through:
1. Researching Figma API documentation (mentions not documented)
2. Finding community forum discussions confirming mentions work
3. Learning about `message_meta` format from formatting discussions
4. Reverse-engineering the web client request structure
5. Implementing based on pattern: `{t: "text", mention: "user_id"}`

## Important Notes

### Not Officially Documented
- The `message_meta` format is **not in official Figma API docs**
- This implementation is based on reverse-engineering the web client
- Figma uses this format internally, so it's stable in practice
- No official guarantee of long-term support

### Fallback Behavior
- If username not found: keeps `@username` as plain text
- If no mentions detected: uses simple `message` field
- Maintains backward compatibility

### Limitations
- Can only mention users who have previously commented
- Username must match exactly (case-sensitive in implementation)
- Regex pattern `\w+` means usernames with special chars may not work

## Future Improvements

Potential enhancements:
1. Cache user list to avoid repeated API calls
2. Support for mentioning users who haven't commented yet
3. Better username matching (fuzzy search)
4. Support for Figma's other formatting options (bold, italic, etc.)

## References

- [Figma Forum: User mentions in REST API](https://forum.figma.com/t/user-mentions-in-rest-api-post-comments/51474)
- [Figma Forum: Format comments messages](https://forum.figma.com/ask-the-community-7/format-comments-messages-using-the-figma-rest-api-40994)
- [Figma Comments API Endpoint](https://developers.figma.com/docs/rest-api/comments-endpoints/)

## Example Usage

```javascript
// Input from user
const message = "Hey @john_designer please review the @maria_ux color updates";

// Internal processing
// 1. Detect mentions: ["john_designer", "maria_ux"]
// 2. Fetch users and get IDs
// 3. Transform to message_meta

// Output to Figma API
{
  "message_meta": [
    {"t": "Hey "},
    {"t": "@john_designer", "mention": "user_id_1"},
    {"t": " please review the "},
    {"t": "@maria_ux", "mention": "user_id_2"},
    {"t": " color updates"}
  ]
}
```

## Version History

- **v1.2.0**: Initial @mentions support (plain text only - buggy)
- **v1.2.1**: Fixed @mentions using proper `message_meta` format (working)