@framers/agentos-ext-channel-twitter 0.1.2 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +170 -0
  2. package/manifest.json +1 -1
  3. package/package.json +2 -2
package/README.md ADDED
@@ -0,0 +1,170 @@
1
+ # Twitter channel
2
+
3
+ This pack gives an agent tweet posting, replies, quotes, threads, engagement, search, trends, direct messages, analytics and scheduling through `twitter-api-v2`.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @framers/agentos-ext-channel-twitter
9
+ ```
10
+
11
+ Peer dependency: `@framers/agentos` `>=0.10.40`.
12
+
13
+ ## Usage
14
+
15
+ ```ts
16
+ import { AgentOS } from '@framers/agentos';
17
+
18
+ const agentos = await AgentOS.create({
19
+ extensionManifest: {
20
+ packs: [
21
+ {
22
+ package: '@framers/agentos-ext-channel-twitter',
23
+ options: {
24
+ bearerToken: process.env.TWITTER_BEARER_TOKEN,
25
+ apiKey: process.env.TWITTER_API_KEY,
26
+ apiSecret: process.env.TWITTER_API_SECRET,
27
+ accessToken: process.env.TWITTER_ACCESS_TOKEN,
28
+ accessSecret: process.env.TWITTER_ACCESS_SECRET,
29
+ },
30
+ },
31
+ ],
32
+ },
33
+ });
34
+ ```
35
+
36
+ ## Configuration
37
+
38
+ | Option | Secret id | Environment variable | Required | Default |
39
+ | --- | --- | --- | --- | --- |
40
+ | `bearerToken` | `twitter.bearerToken` | `TWITTER_BEARER_TOKEN`, `X_BEARER_TOKEN` | Yes, by manifest | None |
41
+ | `apiKey` | `twitter.apiKey` | `TWITTER_API_KEY`, `X_API_KEY`, `X_CONSUMER_KEY`, `TWITTER_CONSUMER_KEY` | No | None |
42
+ | `apiSecret` | `twitter.apiSecret` | `TWITTER_API_SECRET`, `X_API_SECRET`, `X_CONSUMER_SECRET`, `X_CONSUMER_SECRET_KEY`, `TWITTER_CONSUMER_SECRET` | No | None |
43
+ | `accessToken` | `twitter.accessToken` | `TWITTER_ACCESS_TOKEN`, `X_ACCESS_TOKEN` | No | None |
44
+ | `accessSecret` | `twitter.accessSecret` | `TWITTER_ACCESS_SECRET`, `X_ACCESS_SECRET`, `X_ACCESS_TOKEN_SECRET`, `TWITTER_ACCESS_TOKEN_SECRET` | No | None |
45
+ | `secrets` | All credential secret ids above | None | No | `context.secrets`, then `{}` |
46
+
47
+ Credentials resolve from options, then secrets, then the listed environment variables in order. `options.secrets` takes precedence over `context.secrets`. Resolution uses nullish fallback, so an empty string blocks later values.
48
+
49
+ ## Tools
50
+
51
+ | Tool | What it does |
52
+ | --- | --- |
53
+ | `twitterPost` | Post a tweet with optional media and a poll. |
54
+ | `twitterReply` | Reply to an existing tweet. |
55
+ | `twitterQuote` | Quote an existing tweet with a comment. |
56
+ | `twitterLike` | Like or unlike a tweet. |
57
+ | `twitterRetweet` | Retweet or undo a retweet. |
58
+ | `twitterSearch` | Search tweets with filters and sorting. |
59
+ | `twitterTrending` | Get trending topics for a location, defaulting to worldwide. |
60
+ | `twitterTimeline` | Get the authenticated user's home timeline. |
61
+ | `twitterDm` | Send or list direct messages. |
62
+ | `twitterAnalytics` | Get likes, retweets, replies and impressions for a tweet. |
63
+ | `twitterSchedule` | Schedule a tweet for future posting. |
64
+ | `twitterThread` | Post tweet texts as sequential replies. |
65
+
66
+ ### `twitterPost`
67
+
68
+ | Parameter | Type | Required | Description |
69
+ | --- | --- | --- | --- |
70
+ | `text` | string | Yes | Tweet text (max `280` characters) |
71
+ | `mediaPath` | string | No | Path to media file to attach |
72
+ | `pollOptions` | string[] | No | Poll options (`2` to `4` choices) |
73
+ | `pollDurationMinutes` | number | No | Poll duration in minutes (default `1440`, a day) |
74
+
75
+ ### `twitterReply`
76
+
77
+ | Parameter | Type | Required | Description |
78
+ | --- | --- | --- | --- |
79
+ | `tweetId` | string | Yes | ID of the tweet to reply to |
80
+ | `text` | string | Yes | Reply text |
81
+
82
+ ### `twitterQuote`
83
+
84
+ | Parameter | Type | Required | Description |
85
+ | --- | --- | --- | --- |
86
+ | `tweetId` | string | Yes | ID of the tweet to quote |
87
+ | `text` | string | Yes | Your quote comment |
88
+
89
+ ### `twitterLike`
90
+
91
+ | Parameter | Type | Required | Description |
92
+ | --- | --- | --- | --- |
93
+ | `tweetId` | string | Yes | ID of the tweet |
94
+ | `unlike` | boolean | No | Set to `true` to unlike; default `false` |
95
+
96
+ ### `twitterRetweet`
97
+
98
+ | Parameter | Type | Required | Description |
99
+ | --- | --- | --- | --- |
100
+ | `tweetId` | string | Yes | ID of the tweet to retweet |
101
+ | `undo` | boolean | No | Set to `true` to unretweet; default `false` |
102
+
103
+ ### `twitterSearch`
104
+
105
+ | Parameter | Type | Required | Description |
106
+ | --- | --- | --- | --- |
107
+ | `query` | string | Yes | Search query (supports Twitter search operators) |
108
+ | `maxResults` | number | No | Max tweets to return (default `10`, max `100`) |
109
+ | `sortOrder` | string: `recency`, `relevancy` | No | Sort order |
110
+
111
+ ### `twitterTrending`
112
+
113
+ | Parameter | Type | Required | Description |
114
+ | --- | --- | --- | --- |
115
+ | `woeid` | number | No | Yahoo WOEID for location (`1` = worldwide, `23424977` = US); default `1` |
116
+
117
+ ### `twitterTimeline`
118
+
119
+ | Parameter | Type | Required | Description |
120
+ | --- | --- | --- | --- |
121
+ | `maxResults` | number | No | Max tweets to return (default `20`, max `100`) |
122
+
123
+ ### `twitterDm`
124
+
125
+ | Parameter | Type | Required | Description |
126
+ | --- | --- | --- | --- |
127
+ | `action` | string: `send`, `list` | Yes | Action to perform |
128
+ | `recipientId` | string | No | User ID to send DM to (required for send) |
129
+ | `text` | string | No | Message text (required for send) |
130
+ | `maxResults` | number | No | Max DM events to return (for list); default `20` |
131
+
132
+ ### `twitterAnalytics`
133
+
134
+ | Parameter | Type | Required | Description |
135
+ | --- | --- | --- | --- |
136
+ | `tweetId` | string | Yes | ID of the tweet to analyze |
137
+
138
+ ### `twitterSchedule`
139
+
140
+ | Parameter | Type | Required | Description |
141
+ | --- | --- | --- | --- |
142
+ | `text` | string | Yes | Tweet text |
143
+ | `scheduledAt` | string | Yes | ISO 8601 timestamp for when to post |
144
+ | `mediaPath` | string | No | Optional media file path |
145
+
146
+ ### `twitterThread`
147
+
148
+ | Parameter | Type | Required | Description |
149
+ | --- | --- | --- | --- |
150
+ | `tweets` | string[]; minimum `2` items | Yes | Array of tweet texts (each max `280` characters). Posted as a sequential thread. |
151
+
152
+ ## Channel adapter
153
+
154
+ The adapter registers platform `twitter`. Sending posts the first text block, uploads image and video blocks through the SDK, attaches poll options and converts poll duration from hours to minutes. It reads `replyToMessageId` for replies and ignores `conversationId`. Failed media uploads are skipped. Reactions call the like operation regardless of the supplied reaction.
155
+
156
+ Activation initializes API clients. Connection status follows the service's running state, with initialization errors exposed in connection information. The adapter stores handlers but emits no inbound events. Typing indicators do nothing.
157
+
158
+ ## Notes
159
+
160
+ A bearer token supplies the read client. Posting, engagement, media uploads, home timeline and direct messages require `apiKey`, `apiSecret`, `accessToken` and `accessSecret` together. The service also uses that write client for reads when no bearer token is set, although the manifest declares `twitter.bearerToken` required.
161
+
162
+ If neither `bearerToken` nor `apiKey` is set, activation attempts to load a stored Twitter access token through `FileTokenStore` from `@framers/agentos/auth`. Initialization throws if no read or write client can be created.
163
+
164
+ Write tools publish tweets, send messages or change likes and retweets. Threads post sequentially without rollback. `recipientId` is passed directly to the SDK's `sendDmInConversation` method. Timeline and direct-message listing requests are capped at `100` results; search forwards `maxResults` without a local cap and defaults to `relevancy` sorting.
165
+
166
+ Scheduling stores timers in memory without persistence or cancellation. A past timestamp posts immediately and ignores `mediaPath`. Future scheduled posts upload media at execution time and silently discard failures. Pack deactivation shuts down the service but does not clear scheduled timers.
167
+
168
+ ## License
169
+
170
+ Apache-2.0
package/manifest.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "$schema": "https://agentos.sh/schemas/extension-manifest-v1.json",
3
3
  "id": "com.framers.channels.twitter",
4
4
  "name": "Twitter/X Channel Extension",
5
- "version": "0.1.2",
5
+ "version": "0.1.3",
6
6
  "description": "Bidirectional Twitter/X integration — post tweets, reply, quote, thread, search trends, DM, and track engagement via Twitter API v2.",
7
7
  "categories": ["channel", "social"],
8
8
  "platforms": ["twitter"],
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@framers/agentos-ext-channel-twitter",
3
- "version": "0.1.2",
3
+ "version": "0.1.3",
4
4
  "description": "Twitter/X channel adapter for AgentOS — post tweets, reply, quote, thread, search trends, DMs, and engagement analytics via Twitter API v2.",
5
5
  "license": "Apache-2.0",
6
6
  "main": "dist/index.js",
@@ -19,7 +19,7 @@
19
19
  "@types/node": "^20.0.0",
20
20
  "typescript": "^5.0.0",
21
21
  "vitest": "^3.2.7",
22
- "@framers/agentos": "^0.13.40"
22
+ "@framers/agentos": "^0.13.47"
23
23
  },
24
24
  "repository": {
25
25
  "type": "git",