Merge branch 'main' into feat/acp

Author: celesteanglm

plugins/twitter/README.md

@@ -1,99 +1,115 @@
 # Twitter Plugin for GAME SDK
 
-The Twitter plugin is a lightweight wrapper over commonly-used twitter API calls. It can be used as a executable on its own or by combining multiple of these into an executable.
+The **Twitter Plugin** provides a lightweight interface for integrating Twitter (X) functionality into your GAME SDK agents. Built on top of [`virtuals_tweepy`](https://pypi.org/project/virtuals-tweepy/) by the Virtuals team — a maintained fork of [`Tweepy`](https://pypi.org/project/tweepy/)) — this plugin lets you easily post tweets, fetch data, and execute workflows through agent logic.
+
+## 📜 GAME X API Usage Terms & Rules
+By using our GAME API, you agree to the [Terms of Use](https://virtualsprotocol.notion.site/Terms-of-Use-2152d2a429e980f09a74c85c0a5974c4?source=copy_link) and [GAME X API Terms](https://virtualsprotocol.notion.site/Agents-on-X-Rulebook-1972d2a429e980ddaa85da3c903afade?pvs=74).
+
+## 🚀 API Access Tiers
+Virtuals sponsors the community with a **Twitter Enterprise API access plan**, using OAuth 2.0 with PKCE. This provides:
+
+## 🚀 API Access Tiers
+### Tier 1 — Default
+- Higher rate limits: **50 calls / 5 minutes**
+- Smoother onboarding
+- Free usage via your `GAME_API_KEY`
+
+### Tier 2 — Elevated
+- Even higher rate limits
+- Requires approval from the Virtuals team. Request access via Discord → @virtualsio
+
+---
+Use it standalone or compose multiple Twitter actions as part of a larger agent job.
 
 ## Installation
 
-From this directory (`twitter`), run the installation:
+You can install the plugin using either `poetry` or `pip`:
 
 ```bash
+# Using Poetry (from the plugin directory)
 poetry install
 ```
+or
+```bash
+# Using pip (recommended for integration projects)
+pip install twitter_plugin_gamesdk
+```
 
-## Usage
+---
 
-The Twitter plugin can be initialized in one of two ways:
+## Authentication Methods
+Virtuals sponsors the community with a **Twitter Enterprise API access plan**, using OAuth 2.0 with PKCE. This provides:
 
-1. Using GAME's X enterprise API credentials (higher rate limits)
+- Higher rate limits: **35 calls / 5 minutes**
+- Smoother onboarding
+- Free usage via your `GAME_API_KEY`
 
-   - To get the access token for this option, run the following command:
+#### 1. Get Your Access Token
 
-     ```bash
-     poetry run twitter-plugin-gamesdk auth -k <GAME_API_KEY>
-     ```
+Run the following command to authenticate using your `GAME_API_KEY`:
 
-     You will see the following output:
+```bash
+poetry run twitter-plugin-gamesdk auth -k <GAME_API_KEY>
+```
 
-     ```bash
-     Waiting for authentication...
+This will prompt:
 
-     Visit the following URL to authenticate:
-     https://x.com/i/oauth2/authorize?response_type=code&client_id=VVdyZ0t4WFFRMjBlMzVaczZyMzU6MTpjaQ&redirect_uri=http%3A%2F%2Flocalhost%3A8714%2Fcallback&state=866c82c0-e3f6-444e-a2de-e58bcc95f08b&code_challenge=K47t-0Mcl8B99ufyqmwJYZFB56fiXiZf7f3euQ4H2_0&code_challenge_method=s256&scope=tweet.read%20tweet.write%20users.read%20offline.access
-     ```
+```bash
+Waiting for authentication...
 
-     After authenticating, you will receive the following message:
+Visit the following URL to authenticate:
+https://x.com/i/oauth2/authorize?...
 
-     ```bash
-     Authenticated! Here's your access token:
-     apx-<xxx>
-     ```
+Authenticated! Here's your access token:
+apx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
+
+#### 2. Store Your Access Token
 
-   - Set the access token as an environment variable called `GAME_TWITTER_ACCESS_TOKEN` (e.g. using a `.bashrc` or a `.zshrc` file).
-   - Import and initialize the plugin to use in your worker:
+We recommend storing environment variables in a `.env` file:
 
-     ```python
-     import os
-     from twitter_plugin_gamesdk.twitter_plugin import TwitterPlugin
+```
+# .env
+
+GAME_TWITTER_ACCESS_TOKEN=apx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+```
 
-     # Define your options with the necessary credentials
-     options = {
-         "credentials": {
-             "gameTwitterAccessToken": os.environ.get("GAME_TWITTER_ACCESS_TOKEN")
-         },
-     }
-     # Initialize the TwitterPlugin with your options
-     twitter_plugin = TwitterPlugin(options)
+Then, use `load_dotenv()` to load them:
 
-     # Post a tweet
-     post_tweet_fn = twitter_plugin.get_function('post_tweet')
-     post_tweet_fn("Hello world!")
-     ```
+```python
+import os
+from dotenv import load_dotenv
+from twitter_plugin_gamesdk.twitter_plugin import TwitterPlugin
 
-2. Using your own X API credentials
+load_dotenv()
+
+options = {
+    "credentials": {
+        "game_twitter_access_token": os.environ.get("GAME_TWITTER_ACCESS_TOKEN")
+    }
+}
+
+twitter_plugin = TwitterPlugin(options)
+client = twitter_plugin.twitter_client
+
+client.create_tweet(text="Tweeting with GAME Access Token!")
+```
+---
 
-   - If you don't already have one, create a X (twitter) account and navigate to the [developer portal](https://developer.x.com/en/portal/dashboard).
-   - Create a project app, generate the following credentials and set them as environment variables (e.g. using a `.bashrc` or a `.zshrc` file):
-     - `TWITTER_BEARER_TOKEN`
-     - `TWITTER_API_KEY`
-     - `TWITTER_API_SECRET_KEY`
-     - `TWITTER_ACCESS_TOKEN`
-     - `TWITTER_ACCESS_TOKEN_SECRET`
-   - Import and initialize the plugin to use in your worker:
+## Examples
 
-     ```python
-     import os
-     from twitter_plugin_gamesdk.twitter_plugin import TwitterPlugin
+Explore the [`examples/`](./examples) directory for sample scripts demonstrating how to:
 
-     # Define your options with the necessary credentials
-     options = {
-         "credentials": {
-             "bearerToken": os.environ.get("TWITTER_BEARER_TOKEN"),
-             "apiKey": os.environ.get("TWITTER_API_KEY"),
-             "apiSecretKey": os.environ.get("TWITTER_API_SECRET_KEY"),
-             "accessToken": os.environ.get("TWITTER_ACCESS_TOKEN"),
-             "accessTokenSecret": os.environ.get("TWITTER_ACCESS_TOKEN_SECRET"),
-         },
-     }
-     # Initialize the TwitterPlugin with your options
-     twitter_plugin = TwitterPlugin(options)
+- Post tweets
+- Reply to mentions
+- Quote tweets
+- Fetch user timelines
+- And more!
 
-     # Post a tweet
-     post_tweet_fn = twitter_plugin.twitter_client.create_tweet
-     post_tweet_fn(text="Hello world! This is a test tweet from the Twitter Plugin!")
-     ```
+---
 
-For detailed documentation on each function's parameters and usage, please refer to the [Tweepy Client Documentation](https://docs.tweepy.org/en/stable/client.html).
+## API Reference
 
-Example usage:
+This plugin wraps [`virtuals_tweepy`](https://pypi.org/project/virtuals-tweepy/), which is API-compatible with [Tweepy’s client interface](https://docs.tweepy.org/en/stable/client.html). Refer to their docs for supported methods and parameters.
 
-You can refer to the example files in the `examples` directory for more examples on how to call the twitter functions.
+---