From 04c86ff87f2d3e7f89ec8f43bc2665aa0aa3d476 Mon Sep 17 00:00:00 2001 From: afarukcali <28007392+afarukcali@users.noreply.github.com> Date: Tue, 20 May 2025 14:08:35 +0000 Subject: [PATCH] Update docs from nexus-sdk (commit: caa5f3157667f5c62bca1c1a01bdd7f6ee444039) --- tools/social-twitter/README.md | 316 +++++++++++++++++++++++++++++++++ 1 file changed, 316 insertions(+) diff --git a/tools/social-twitter/README.md b/tools/social-twitter/README.md index 3dfbbdb..043286e 100644 --- a/tools/social-twitter/README.md +++ b/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`]** - 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`]** _default_: [`None`] + +The maximum number of results to return (1-100, default: 100). + +_opt_ **`pagination_token`: [`Option`]** _default_: [`None`] + +This parameter is used to get a specified 'page' of results. + +_opt_ **`event_types`: [`Option>`]** _default_: [`None`] + +The set of event_types to include in the results. + +_opt_ **`dm_event_fields`: [`Option>`]** _default_: [`None`] + +A comma separated list of DM Event fields to display. + +_opt_ **`expansions`: [`Option>`]** _default_: [`None`] + +A comma separated list of fields to expand. + +_opt_ **`media_fields`: [`Option>`]** _default_: [`None`] + +A comma separated list of Media fields to display. + +_opt_ **`user_fields`: [`Option>`]** _default_: [`None`] + +A comma separated list of User fields to display. + +_opt_ **`tweet_fields`: [`Option>`]** _default_: [`None`] + +A comma separated list of Tweet fields to display. + +## Output Variants & Ports + +**`ok`** + +The conversation messages were retrieved successfully. + +- **`ok.data`: [`Option>`]** - The list of DM events in the conversation +- **`ok.includes`: [`Option`]** - Additional information related to the events +- **`ok.meta`: [`Option`]** - 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`]** - 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`]** - The text content of the message +- **`media_ids`: [`Option`]** - Media IDs to attach to the message. Can be either a single ID or multiple IDs: + - `One(String)` - A single media ID + - `Many(Vec)` - Multiple media IDs + +**`participant_ids`: [`Vec`]** + +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`]** - 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`]** - The text content of the message +- **`media_ids`: [`Option>`]** - 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`]** - 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: