Docs update from nexus-sdk

tools/social-twitter/README.md

@@ -813,6 +813,72 @@ The undo retweet operation failed.
 
 ---
 
+# `xyz.taluslabs.social.twitter.follow-user@1`
+
+Standard Nexus Tool that allows a user to follow another user on Twitter.
+Twitter api [reference](https://docs.x.com/x-api/users/follow)
+
+## Input
+
+**Authentication Parameters**
+
+The following authentication parameters are provided as part of the TwitterAuth structure:
+
+- **`consumer_key`: [`String`]** - Twitter API application's Consumer Key
+- **`consumer_secret_key`: [`String`]** - Twitter API application's Consumer Secret Key
+- **`access_token`: [`String`]** - Access Token for user's Twitter account
+- **`access_token_secret`: [`String`]** - Access Token Secret for user's Twitter account
+
+**Additional Parameters**
+
+**`user_id`: [`String`]**
+
+The ID of the authenticated user who will follow another user.
+
+**`target_user_id`: [`String`]**
+
+The ID of the user to follow.
+
+## Output Variants & Ports
+
+**`followed`**
+
+The user was successfully followed.
+
+- **`followed.result`: [`bool`]** - Confirmation that the user was followed (true)
+
+**`pending`**
+
+The follow request is pending (e.g., when following a protected account).
+
+- **`pending.result`: [`bool`]** - Confirmation that the follow request is pending (true)
+
+**`err`**
+
+The follow operation failed.
+
+- **`err.reason`: [`String`]** - A detailed error message describing what went wrong
+- **`err.kind`: [`TwitterErrorKind`]** - The type of error that occurred. Possible values:
+  - `network` - A network-related error occurred when connecting to Twitter
+  - `connection` - Could not establish a connection to Twitter
+  - `timeout` - The request to Twitter timed out
+  - `parse` - Failed to parse Twitter's response
+  - `auth` - Authentication or authorization error
+  - `not_found` - The requested user was not found
+  - `rate_limit` - Twitter's rate limit was exceeded
+  - `server` - An error occurred on Twitter's servers
+  - `forbidden` - The request was forbidden
+  - `api` - An API-specific error occurred
+  - `unknown` - An unexpected error occurred
+- **`err.status_code`: [`Option<u16>`]** - The HTTP status code returned by Twitter, if available. Common codes include:
+  - `401` - Unauthorized (authentication error)
+  - `403` - Forbidden
+  - `404` - Not Found
+  - `429` - Too Many Requests (rate limit exceeded)
+  - `5xx` - Server errors
+
+---
+
 # `xyz.taluslabs.social.twitter.get-user-by-id@1`
 
 Standard Nexus Tool that retrieves a user from the Twitter API by their ID. Twitter api [reference](https://developer.twitter.com/en/docs/twitter-api/users/lookup/api-reference/get-users-id)
@@ -2101,6 +2167,256 @@ The direct messages were not retrieved due to an error.
 
 ---
 
+# `xyz.taluslabs.social.twitter.get-conversation-messages-by-id@1`
+
+Standard Nexus Tool that retrieves direct messages from a conversation by ID.
+Twitter api [reference](https://developer.twitter.com/en/docs/twitter-api/direct-messages/lookup/api-reference/get-dm_conversations-dm_conversation_id-dm_events)
+
+## Input
+
+**Authentication Parameters**
+
+The following authentication parameters are provided as part of the TwitterAuth structure:
+
+- **`consumer_key`: [`String`]** - Twitter API application's Consumer Key
+- **`consumer_secret_key`: [`String`]** - Twitter API application's Consumer Secret Key
+- **`access_token`: [`String`]** - Access Token for user's Twitter account
+- **`access_token_secret`: [`String`]** - Access Token Secret for user's Twitter account
+
+**Additional Parameters**
+
+**`conversation_id`: [`String`]**
+
+The ID of the DM Conversation (e.g. "123123123-456456456").
+
+_opt_ **`max_results`: [`Option<i32>`]** _default_: [`None`]
+
+The maximum number of results to return (1-100, default: 100).
+
+_opt_ **`pagination_token`: [`Option<String>`]** _default_: [`None`]
+
+This parameter is used to get a specified 'page' of results.
+
+_opt_ **`event_types`: [`Option<Vec<String>>`]** _default_: [`None`]
+
+The set of event_types to include in the results.
+
+_opt_ **`dm_event_fields`: [`Option<Vec<DmEventField>>`]** _default_: [`None`]
+
+A comma separated list of DM Event fields to display.
+
+_opt_ **`expansions`: [`Option<Vec<ExpansionField>>`]** _default_: [`None`]
+
+A comma separated list of fields to expand.
+
+_opt_ **`media_fields`: [`Option<Vec<MediaField>>`]** _default_: [`None`]
+
+A comma separated list of Media fields to display.
+
+_opt_ **`user_fields`: [`Option<Vec<UserField>>`]** _default_: [`None`]
+
+A comma separated list of User fields to display.
+
+_opt_ **`tweet_fields`: [`Option<Vec<TweetField>>`]** _default_: [`None`]
+
+A comma separated list of Tweet fields to display.
+
+## Output Variants & Ports
+
+**`ok`**
+
+The conversation messages were retrieved successfully.
+
+- **`ok.data`: [`Option<Vec<DmEvent>>`]** - The list of DM events in the conversation
+- **`ok.includes`: [`Option<Includes>`]** - Additional information related to the events
+- **`ok.meta`: [`Option<Meta>`]** - Pagination metadata
+
+**`err`**
+
+The conversation messages were not retrieved due to an error.
+
+- **`err.reason`: [`String`]** - A detailed error message describing what went wrong
+- **`err.kind`: [`TwitterErrorKind`]** - The type of error that occurred. Possible values:
+
+  - `network` - A network-related error occurred when connecting to Twitter
+  - `connection` - Could not establish a connection to Twitter
+  - `timeout` - The request to Twitter timed out
+  - `parse` - Failed to parse Twitter's response
+  - `auth` - Authentication or authorization error
+  - `not_found` - The requested conversation or resource was not found
+  - `rate_limit` - Twitter's rate limit was exceeded
+  - `server` - An error occurred on Twitter's servers
+  - `forbidden` - The request was forbidden
+  - `api` - An API-specific error occurred
+  - `unknown` - An unexpected error occurred
+
+- **`err.status_code`: [`Option<u16>`]** - The HTTP status code returned by Twitter, if available. Common codes include:
+  - `401` - Unauthorized (authentication error)
+  - `403` - Forbidden
+  - `404` - Not Found (conversation not found)
+  - `429` - Too Many Requests (rate limit exceeded)
+  - `5xx` - Server errors
+
+---
+
+# `xyz.taluslabs.social.twitter.create-group-conversation@1`
+
+Standard Nexus Tool that creates a group DM conversation on Twitter.
+Twitter api [reference](https://developer.twitter.com/en/docs/twitter-api/direct-messages/manage/api-reference/post-dm_conversations)
+
+## Input
+
+**Authentication Parameters**
+
+The following authentication parameters are provided as part of the TwitterAuth structure:
+
+- **`consumer_key`: [`String`]** - Twitter API application's Consumer Key
+- **`consumer_secret_key`: [`String`]** - Twitter API application's Consumer Secret Key
+- **`access_token`: [`String`]** - Access Token for user's Twitter account
+- **`access_token_secret`: [`String`]** - Access Token Secret for user's Twitter account
+
+**Additional Parameters**
+
+**`conversation_type`: [`ConversationType`]**
+
+The type of conversation to create. Currently only supports `Group`.
+
+**`message`: [`Message`]**
+
+The initial message to send in the conversation, containing:
+
+- **`text`: [`Option<String>`]** - The text content of the message
+- **`media_ids`: [`Option<MediaIdsBag>`]** - Media IDs to attach to the message. Can be either a single ID or multiple IDs:
+  - `One(String)` - A single media ID
+  - `Many(Vec<String>)` - Multiple media IDs
+
+**`participant_ids`: [`Vec<String>`]**
+
+List of user IDs who will participate in the group conversation.
+
+## Output Variants & Ports
+
+**`ok`**
+
+The group conversation was created successfully.
+
+- **`ok.dm_conversation_id`: [`String`]** - The unique identifier of the DM conversation
+- **`ok.dm_event_id`: [`String`]** - The unique identifier of the DM event
+
+**`err`**
+
+The group conversation creation failed.
+
+- **`err.reason`: [`String`]** - A detailed error message describing what went wrong
+- **`err.kind`: [`TwitterErrorKind`]** - The type of error that occurred. Possible values:
+  - `network` - A network-related error occurred when connecting to Twitter
+  - `connection` - Could not establish a connection to Twitter
+  - `timeout` - The request to Twitter timed out
+  - `parse` - Failed to parse Twitter's response
+  - `auth` - Authentication or authorization error
+  - `not_found` - The requested conversation or resource was not found
+  - `rate_limit` - Twitter's rate limit was exceeded
+  - `server` - An error occurred on Twitter's servers
+  - `forbidden` - The request was forbidden
+  - `api` - An API-specific error occurred
+  - `validation` - Input validation error (e.g., empty message text or media_ids)
+  - `unknown` - An unexpected error occurred
+- **`err.status_code`: [`Option<u16>`]** - The HTTP status code returned by Twitter, if available. Common codes include:
+  - `401` - Unauthorized (authentication error)
+  - `403` - Forbidden
+  - `404` - Not Found
+  - `429` - Too Many Requests (rate limit exceeded)
+  - `5xx` - Server errors
+
+## Validation Rules
+
+The message must follow these validation rules:
+
+1. Either `text` or `media_ids` must be provided and non-empty
+2. If `media_ids` is provided, it must not be empty (for `Many` variant)
+
+---
+
+# `xyz.taluslabs.social.twitter.send-message-to-group-conversation@1`
+
+Standard Nexus Tool that sends a message to a group conversation on Twitter.
+Twitter api [reference](https://developer.twitter.com/en/docs/twitter-api/direct-messages/manage/api-reference/post-dm_conversations-dm_conversation_id-messages)
+
+## Input
+
+**Authentication Parameters**
+
+The following authentication parameters are provided as part of the TwitterAuth structure:
+
+- **`consumer_key`: [`String`]** - Twitter API application's Consumer Key
+- **`consumer_secret_key`: [`String`]** - Twitter API application's Consumer Secret Key
+- **`access_token`: [`String`]** - Access Token for user's Twitter account
+- **`access_token_secret`: [`String`]** - Access Token Secret for user's Twitter account
+
+**Additional Parameters**
+
+**`dm_conversation_id`: [`String`]**
+
+The DM Conversation ID to send the message to.
+
+**`message`: [`Message`]**
+
+The message to send, containing:
+
+- **`text`: [`Option<String>`]** - The text content of the message
+- **`media_ids`: [`Option<Vec<String>>`]** - List of media IDs to attach to the message
+
+## Output Variants & Ports
+
+**`ok`**
+
+The message was sent successfully.
+
+- **`ok.dm_conversation_id`: [`String`]** - The ID of the conversation the message was sent to
+- **`ok.dm_event_id`: [`String`]** - The ID of the sent message event
+
+**`err`**
+
+The message sending failed.
+
+- **`err.reason`: [`String`]** - A detailed error message describing what went wrong
+- **`err.kind`: [`TwitterErrorKind`]** - The type of error that occurred. Possible values:
+  - `network` - A network-related error occurred when connecting to Twitter
+  - `connection` - Could not establish a connection to Twitter
+  - `timeout` - The request to Twitter timed out
+  - `parse` - Failed to parse Twitter's response
+  - `auth` - Authentication or authorization error
+  - `not_found` - The requested conversation was not found
+  - `rate_limit` - Twitter's rate limit was exceeded
+  - `server` - An error occurred on Twitter's servers
+  - `forbidden` - The request was forbidden
+  - `api` - An API-specific error occurred
+  - `validation` - Input validation error (e.g., empty text or media_ids)
+  - `unknown` - An unexpected error occurred
+- **`err.status_code`: [`Option<u16>`]** - The HTTP status code returned by Twitter, if available. Common codes include:
+  - `401` - Unauthorized (authentication error)
+  - `403` - Forbidden
+  - `404` - Not Found
+  - `429` - Too Many Requests (rate limit exceeded)
+  - `5xx` - Server errors
+
+## Validation Rules
+
+The message must follow these validation rules:
+
+1. Either `text` or `media_ids` must be provided and non-empty
+2. If `media_ids` is provided, it must not be empty (for `Many` variant)
+
+## Example Error Messages
+
+- "Either text or media_ids must be provided"
+- "Text must not be empty"
+- "Media IDs must not be empty"
+- "Unauthorized" (when authentication fails)
+- "Response parsing error" (when Twitter's response cannot be parsed)
+
+---
+
 # Error Handling
 
 The Twitter SDK includes a centralized error handling system that provides consistent error responses across all modules. This system includes: