Connections: Define/persist connection metadata (implement for Reddit)

[devin-ai-integration]

Scope

• Establish a metadata structure for external connections (provider-specific fields)
• Implement metadata collection/storage for Reddit connection

Acceptance criteria

• Connection model supports metadata blob (validated)
• Reddit connection populates metadata at creation time (e.g., username, verified/email, karma)
• Expose relevant metadata safely in API responses where appropriate

Code references

• Reddit metadata TODO: https://github.com/erkinalp/anticensor/blob/master/src/connections/Reddit/index.ts#L144-L146

[traycerai]

Plan

Observations

I analyzed the codebase and found that the infrastructure for connection metadata is already in place. The ConnectedAccount entity has metadata_ and metadata_visibility fields, and the API already exposes these fields through the ConnectedAccountDTO. However, the Reddit connection implementation has a TODO comment and doesn't populate the metadata field. The Reddit API provides rich user information including username, verification status, karma, and other relevant data that should be stored as metadata.

Approach

I'll implement connection metadata support by:

1. Define metadata structure: Create a TypeScript interface for Reddit-specific metadata to ensure type safety and validation
2. Implement metadata collection: Update the Reddit connection to populate metadata during account creation using the existing Reddit API response
3. Add metadata validation: Create a validation schema to ensure metadata integrity
4. Update API exposure: Ensure metadata is properly exposed in API responses with appropriate visibility controls
5. Add comprehensive documentation: Document the metadata structure and usage patterns for future connection implementations

Reasoning

I explored the codebase structure and found the connections directory with various OAuth providers. I examined the Reddit connection implementation and discovered the TODO comment for metadata. I then analyzed the ConnectedAccount entity, ConnectedAccountDTO, and API routes to understand how metadata is currently handled. I also checked other connection implementations like GitHub to understand existing patterns.

Proposed File Changes

📄 src/util/interfaces/ConnectedAccount.ts ^(MODIFY) 🔗

Add Reddit-specific metadata interface to define the structure of metadata that will be stored for Reddit connections. This interface will include fields like username, verified status, email verification, karma, account creation date, and moderator status. This provides type safety and clear documentation of what metadata is available for Reddit connections.

📄 src/util/schemas/index.ts ^(MODIFY) 🔗

References

• 📄 src/util/schemas/RedditMetadataSchema.ts ^(NEW)

Export the new Reddit metadata validation schema to make it available throughout the application. This ensures the schema can be imported and used for validating Reddit connection metadata.

📄 src/util/schemas/RedditMetadataSchema.ts ^(NEW) 🔗

References

• 📄 src/util/schemas/Validator.ts

Create a validation schema for Reddit connection metadata using a validation library (likely Joi or similar based on the existing schema patterns in src/util/schemas/). This schema will validate the structure and types of Reddit metadata fields including username (string), verified status (boolean), email verification (boolean), karma (number), account creation timestamps, and moderator status. The schema ensures data integrity when storing Reddit metadata.

📄 src/connections/Reddit/index.ts ^(MODIFY) 🔗

References

• 📄 src/util/interfaces/ConnectedAccount.ts ^(MODIFY)
• 📄 src/util/schemas/RedditMetadataSchema.ts ^(NEW)

Implement metadata collection in the Reddit connection's handleCallback method. Replace the TODO comment (lines 144-145) with code that creates a metadata object from the Reddit API response (userInfo). The metadata will include username, verified status, email verification, total karma, account creation date, and moderator status. Add the metadata to the createConnection call using the metadata_ field. Import the Reddit metadata interface and validation schema to ensure type safety and data validation.

📄 src/api/routes/users/@me/connections/index.ts ^(MODIFY) 🔗

References

• 📄 src/util/dtos/ConnectedAccountDTO.ts ^(MODIFY)

Update the database query to include metadata_ and metadata_visibility fields in the select statement (lines 30-42). This ensures that metadata is retrieved from the database and available for the DTO transformation. The metadata will be properly exposed through the existing ConnectedAccountDTO which already handles these fields.

📄 src/util/dtos/ConnectedAccountDTO.ts ^(MODIFY) 🔗

References

• 📄 src/util/entities/ConnectedAccount.ts

Enhance the DTO constructor to implement proper metadata visibility controls. Add logic to check the metadata_visibility setting and the relationship between viewerUserId and targetUserId to determine whether metadata should be included in the response. If metadata should not be visible to the current viewer, set metadata_ to undefined or a filtered version. This ensures that sensitive metadata is only exposed to authorized users according to the user's privacy settings.

Diagram

sequenceDiagram
    participant User
    participant API
    participant RedditConnection
    participant RedditAPI
    participant Database
    participant DTO

    User->>API: POST /connections/reddit/callback
    API->>RedditConnection: handleCallback(params)
    RedditConnection->>RedditAPI: exchangeCode(state, code)
    RedditAPI-->>RedditConnection: access_token
    RedditConnection->>RedditAPI: getUser(access_token)
    RedditAPI-->>RedditConnection: userInfo (username, karma, verified, etc.)
    RedditConnection->>RedditConnection: createMetadata(userInfo)
    RedditConnection->>Database: createConnection(data + metadata)
    Database-->>RedditConnection: ConnectedAccount
    RedditConnection-->>API: ConnectedAccount
    
    Note over User,DTO: Later API calls
    User->>API: GET /users/@me/connections
    API->>Database: find ConnectedAccounts (including metadata)
    Database-->>API: ConnectedAccount[]
    API->>DTO: new ConnectedAccountDTO(account, with_token, viewerId)
    DTO->>DTO: applyMetadataVisibility()
    DTO-->>API: filtered DTO
    API-->>User: connections with appropriate metadata

Loading

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end.

### Observations

I analyzed the codebase and found that the infrastructure for connection metadata is already in place. The `ConnectedAccount` entity has `metadata_` and `metadata_visibility` fields, and the API already exposes these fields through the `ConnectedAccountDTO`. However, the Reddit connection implementation has a TODO comment and doesn't populate the metadata field. The Reddit API provides rich user information including username, verification status, karma, and other relevant data that should be stored as metadata.

### Approach

I'll implement connection metadata support by:

1. **Define metadata structure**: Create a TypeScript interface for Reddit-specific metadata to ensure type safety and validation
2. **Implement metadata collection**: Update the Reddit connection to populate metadata during account creation using the existing Reddit API response
3. **Add metadata validation**: Create a validation schema to ensure metadata integrity
4. **Update API exposure**: Ensure metadata is properly exposed in API responses with appropriate visibility controls
5. **Add comprehensive documentation**: Document the metadata structure and usage patterns for future connection implementations

### Reasoning

I explored the codebase structure and found the connections directory with various OAuth providers. I examined the Reddit connection implementation and discovered the TODO comment for metadata. I then analyzed the `ConnectedAccount` entity, `ConnectedAccountDTO`, and API routes to understand how metadata is currently handled. I also checked other connection implementations like GitHub to understand existing patterns.

## Mermaid Diagram

sequenceDiagram
    participant User
    participant API
    participant RedditConnection
    participant RedditAPI
    participant Database
    participant DTO

    User->>API: POST /connections/reddit/callback
    API->>RedditConnection: handleCallback(params)
    RedditConnection->>RedditAPI: exchangeCode(state, code)
    RedditAPI-->>RedditConnection: access_token
    RedditConnection->>RedditAPI: getUser(access_token)
    RedditAPI-->>RedditConnection: userInfo (username, karma, verified, etc.)
    RedditConnection->>RedditConnection: createMetadata(userInfo)
    RedditConnection->>Database: createConnection(data + metadata)
    Database-->>RedditConnection: ConnectedAccount
    RedditConnection-->>API: ConnectedAccount
    
    Note over User,DTO: Later API calls
    User->>API: GET /users/@me/connections
    API->>Database: find ConnectedAccounts (including metadata)
    Database-->>API: ConnectedAccount[]
    API->>DTO: new ConnectedAccountDTO(account, with_token, viewerId)
    DTO->>DTO: applyMetadataVisibility()
    DTO-->>API: filtered DTO
    API-->>User: connections with appropriate metadata

## Proposed File Changes

### src/util/interfaces/ConnectedAccount.ts(MODIFY)

Add Reddit-specific metadata interface to define the structure of metadata that will be stored for Reddit connections. This interface will include fields like username, verified status, email verification, karma, account creation date, and moderator status. This provides type safety and clear documentation of what metadata is available for Reddit connections.

### src/util/schemas/index.ts(MODIFY)

References: 

- src/util/schemas/RedditMetadataSchema.ts(NEW)

Export the new Reddit metadata validation schema to make it available throughout the application. This ensures the schema can be imported and used for validating Reddit connection metadata.

### src/util/schemas/RedditMetadataSchema.ts(NEW)

References: 

- src/util/schemas/Validator.ts

Create a validation schema for Reddit connection metadata using a validation library (likely Joi or similar based on the existing schema patterns in `src/util/schemas/`). This schema will validate the structure and types of Reddit metadata fields including username (string), verified status (boolean), email verification (boolean), karma (number), account creation timestamps, and moderator status. The schema ensures data integrity when storing Reddit metadata.

### src/connections/Reddit/index.ts(MODIFY)

References: 

- src/util/interfaces/ConnectedAccount.ts(MODIFY)
- src/util/schemas/RedditMetadataSchema.ts(NEW)

Implement metadata collection in the Reddit connection's `handleCallback` method. Replace the TODO comment (lines 144-145) with code that creates a metadata object from the Reddit API response (`userInfo`). The metadata will include username, verified status, email verification, total karma, account creation date, and moderator status. Add the metadata to the `createConnection` call using the `metadata_` field. Import the Reddit metadata interface and validation schema to ensure type safety and data validation.

### src/api/routes/users/@me/connections/index.ts(MODIFY)

References: 

- src/util/dtos/ConnectedAccountDTO.ts(MODIFY)

Update the database query to include `metadata_` and `metadata_visibility` fields in the select statement (lines 30-42). This ensures that metadata is retrieved from the database and available for the DTO transformation. The metadata will be properly exposed through the existing `ConnectedAccountDTO` which already handles these fields.

### src/util/dtos/ConnectedAccountDTO.ts(MODIFY)

References: 

- src/util/entities/ConnectedAccount.ts

Enhance the DTO constructor to implement proper metadata visibility controls. Add logic to check the `metadata_visibility` setting and the relationship between `viewerUserId` and `targetUserId` to determine whether metadata should be included in the response. If metadata should not be visible to the current viewer, set `metadata_` to undefined or a filtered version. This ensures that sensitive metadata is only exposed to authorized users according to the user's privacy settings.

---

Developer Humor

🔗 Why did the Reddit connection finally get metadata?
Because it was tired of being just another
anonymous account in the database!
Now it can show off its karma points
and verified status with pride! ✨
📊 From TODO to TA-DA! 🎉

---

Execution Information

Branch: master
Commit: 0442d70

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.