From 1cbd0d80de841185514e3e2a3c961568ac28d376 Mon Sep 17 00:00:00 2001 From: afarukcali <28007392+afarukcali@users.noreply.github.com> Date: Mon, 19 May 2025 12:35:40 +0000 Subject: [PATCH] Update docs from nexus-sdk (commit: 2c62ae5599141cbb3a829b4db807bf6a1f7fa5c9) --- nexus-sdk/cli.md | 52 ++++- nexus-sdk/guides/math-branching-with-chat.md | 2 +- tools/social-twitter/README.md | 193 +++++++++++++++++++ 3 files changed, 245 insertions(+), 2 deletions(-) diff --git a/nexus-sdk/cli.md b/nexus-sdk/cli.md index 162c3f4..620d8f4 100644 --- a/nexus-sdk/cli.md +++ b/nexus-sdk/cli.md @@ -50,12 +50,14 @@ The specific design for onchain tools is still in progress and as a result the i --- -**`nexus tool register --off-chain --invocation-cost [mist] --collateral-coin [object_id]`** +**`nexus tool register --off-chain --invocation-cost [mist] --collateral-coin [object_id] [--batch]`** Command that makes a request to `GET /meta` to fetch the Tool definition and then submits a TX to our Tool Registry. It also locks the collateral and sets the single invocation cost of the Tool which defaults to 0 MIST. This returns 2 OwnerCap object IDs that can be used to manage the Tool and its Gas settlement methods. +If the `--batch` flag is passed, the command will accept a URL of a webserver hosting multiple tools and register all of them at once. `nexus-toolkit` automatically generates a `GET /tools` endpoint that returns a list of URLs of all tools registered on that server. The CLI will then iterate over the list and register each tool. + {% hint style="info" %} This command requires that a wallet is connected to the CLI... {% endhint %} @@ -92,6 +94,20 @@ Owned OwnerCap object must be passed to this command for authorization. This command requires that a wallet is connected to the CLI... {% endhint %} +--- + +**`nexus tool set-invocation-cost --tool-fqn --owner-cap --invocation-cost `** + +Tool owners can change the invocation cost of their Tools specified by the FQN. This operation requires that the `OwnerCap` object is passed to the command and owned by the transaction sender. + + + +{% hint style="info" %} +This command requires that a wallet is connected to the CLI... +{% endhint %} + +--- + **`nexus tool list`** List all Nexus Tools available in the Tool Registry. This reads the dynamic object directly from Sui. @@ -178,6 +194,40 @@ This command requires that a wallet is connected to the CLI... --- +**`nexus gas expiry enable --tool-fqn --owner-cap --cost-per-minute `** + +The tool owners can enable the expiry gas extension for their tools specified by the FQN. This operation requires that the `OwnerCap` object is passed to the command and owned by the transaction sender. This allows users to buy expiry gas tickets that can be used to pay for the tool usage for a limited amount of time. + +Calling this command again with a different `cost-per-minute` value will update the cost of the tickets. + +{% hint style="info" %} +This command requires that a wallet is connected to the CLI... +{% endhint %} + +--- + +**`nexus gas expiry disable --tool-fqn --owner-cap `** + +Disables the expiry gas extension for the tool specified by the FQN. This operation requires that the `OwnerCap` object is passed to the command and owned by the transaction sender. + +{% hint style="info" %} +This command requires that a wallet is connected to the CLI... +{% endhint %} + +--- + +**`nexus gas expiry buy-ticket --tool-fqn --minutes --coin `** + +Buy an expiry gas ticket for the tool specified by the FQN. This ticket can then be used to pay for the tool usage for the specified amount of `minutes` if a DAG is executed from the same address that was used to buy this ticket. The ticket is paid for with the provided `coin` object. + +This transaction fails if the tool does not have the expiry gas extension enabled. + +{% hint style="info" %} +This command requires that a wallet is connected to the CLI... +{% endhint %} + +--- + ### `nexus network` Set of commands for managing Nexus networks. diff --git a/nexus-sdk/guides/math-branching-with-chat.md b/nexus-sdk/guides/math-branching-with-chat.md index dddc283..b4e388a 100644 --- a/nexus-sdk/guides/math-branching-with-chat.md +++ b/nexus-sdk/guides/math-branching-with-chat.md @@ -621,5 +621,5 @@ This extended DAG demonstrates how to combine mathematical computation with natu -[math-branching-entry-guide]: ./math-branching-dag-entry.md +[math-branching-entry-guide]: ./math_branching-dag-entry.md [llm-openai-chat-prep-tool]: ./llm-openai-chat-prep-tool.md diff --git a/tools/social-twitter/README.md b/tools/social-twitter/README.md index b1a20aa..54cccf3 100644 --- a/tools/social-twitter/README.md +++ b/tools/social-twitter/README.md @@ -299,6 +299,63 @@ The tweet posting failed. --- +# `xyz.taluslabs.social.twitter.delete-tweet@1` + +Standard Nexus Tool that deletes a tweet. +Twitter api [reference](https://docs.x.com/x-api/posts/post-delete-by-post-id#post-delete-by-post-id) + +## 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** + +**`tweet_id`: [`String`]** + +The ID of the tweet to delete. + +## Output Variants & Ports + +**`ok`** + +The tweet was successfully deleted. + +- **`ok.deleted`: [`bool`]** - Confirmation that the tweet was deleted (true) + +**`err`** + +The tweets could not be deleted 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 tweet 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 + - `429` - Too Many Requests (rate limit exceeded) + - `5xx` - Server errors + +--- + # `xyz.taluslabs.social.twitter.like-tweet@1` Standard Nexus Tool that allows a user to like a specific tweet. @@ -448,6 +505,141 @@ The tweet mentions retrieval failed. --- +# `xyz.taluslabs.social.twitter.get-tweets@1` + +Standard Nexus Tool that retrieves multiple tweets by their IDs from the Twitter API. Twitter api [reference](https://developer.twitter.com/en/docs/twitter-api/tweets/lookup/api-reference/get-tweets) + +## Input + +**`bearer_token`: [`String`]** + +The bearer token for the user's Twitter account. + +**`ids`: [`Vec`]** + +A list of Tweet IDs to retrieve. Up to 100 are allowed in a single request. + +_opt_ **`tweet_fields`: [`Option>`]** _default_: [`None`] + +A list of Tweet fields to display. + +_opt_ **`expansions`: [`Option>`]** _default_: [`None`] + +A list of fields to expand. + +_opt_ **`media_fields`: [`Option>`]** _default_: [`None`] + +A list of Media fields to display. + +_opt_ **`poll_fields`: [`Option>`]** _default_: [`None`] + +A list of Poll fields to display. + +_opt_ **`user_fields`: [`Option>`]** _default_: [`None`] + +A list of User fields to display. + +_opt_ **`place_fields`: [`Option>`]** _default_: [`None`] + +A list of Place fields to display. + +## Output Variants & Ports + +**`ok`** + +The tweets were retrieved successfully. + +- **`ok.data`: [`Vec`]** - The collection of retrieved tweets. +- **`ok.includes`: [`Option`]** - Additional data included in the response (users, media, polls, etc.) +- **`ok.meta`: [`Option`]** - Metadata about the response. + +**`err`** + +The tweets could not be retrieved due to an error. + +- **`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 tweet 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.reason`: [`String`]** - The reason for the error. This could be: + + - Twitter API error (e.g., "Twitter API returned errors: Not Found Error: Could not find tweet with id: [1346889436626259969].") + - Network error (e.g., "Network error: network error: Connection refused") + - Response parsing error (e.g., "Response parsing error: expected value at line 1 column 1") + - Status code error (e.g., "Twitter API status error: 429 Too Many Requests") + - "No tweet data or errors found in the response" when the API response is empty + - Unauthorized error (e.g., "Unauthorized") + - Other error types handled by the centralized error handling mechanism + +- **`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.undo-retweet-tweet@1` + +Standard Nexus Tool that undoes a retweet. +Twitter api [reference](https://docs.x.com/x-api/posts/causes-the-user-in-the-path-to-unretweet-the-specified-post) + +## 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 undo the retweet. + +**`tweet_id`: [`String`]** + +The ID of the tweet to undo retweet. + +## Output Variants & Ports + +**`ok`** + +The retweet was successfully undone. + +- **`ok.retweeted`: [`bool`]** - Confirmation that the retweet was undone (false) + +**`err`** + +The undo retweet operation failed. + +- **`err.reason`: [`String`]** - The reason for the error. This could be: + - Twitter API error status (Code/Message format) + - Twitter API error details (Detail/Status/Title format) + - Unauthorized error + - Invalid JSON response + - Failed to read Twitter API response + - Failed to send undo retweet request to Twitter API + - Unexpected response format from Twitter API + - Twitter API indicated the tweet was already retweeted + +--- + # `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) @@ -981,6 +1173,7 @@ The ID of the user to add to the list. The user was successfully added to the list. +- \*\*`ok.is_member` - **`ok.is_member`** - Confirmation that the user is a member of the list (true). **`err`**