@framers/agentos-ext-channel-threads 0.1.1 → 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 +121 -0
  2. package/manifest.json +1 -1
  3. package/package.json +3 -2
package/README.md ADDED
@@ -0,0 +1,121 @@
1
+ # Threads channel
2
+
3
+ This pack gives an agent tools to publish Threads posts, replies and quotes, change likes, browse recent posts and read engagement metrics. Its channel adapter calls Meta's Threads Publishing API through `axios`.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @framers/agentos-ext-channel-threads
9
+ ```
10
+
11
+ Peer dependency: `@framers/agentos` at `>=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-threads',
23
+ options: {
24
+ accessToken: process.env.THREADS_ACCESS_TOKEN,
25
+ userId: process.env.THREADS_USER_ID,
26
+ },
27
+ },
28
+ ],
29
+ },
30
+ });
31
+ ```
32
+
33
+ ## Configuration
34
+
35
+ Credentials resolve from direct options, then the selected secrets map, then the environment. The secrets map is `options.secrets` when supplied, otherwise `context.secrets`; the maps are not merged.
36
+
37
+ | Option | Secret id | Environment variable | Required | Default |
38
+ | --- | --- | --- | --- | --- |
39
+ | `accessToken` | `threads.accessToken` | `THREADS_ACCESS_TOKEN`, `META_ACCESS_TOKEN` | yes | Empty string; activation attempts token-store fallback |
40
+ | `userId` | `threads.userId` | `THREADS_USER_ID` | no | Resolved from `/me` during initialization |
41
+ | `secrets` in options or context | `threads.accessToken`, `threads.userId` | None | no | Empty map |
42
+
43
+ ## Tools
44
+
45
+ | Tool | What it does |
46
+ | --- | --- |
47
+ | `threadsPost` | Creates a post with text and optional image, video or carousel items. |
48
+ | `threadsReply` | Replies to a post with text and optional media. |
49
+ | `threadsLike` | Likes or unlikes a post. |
50
+ | `threadsSearch` | Browses recent user posts and optionally filters their text. |
51
+ | `threadsAnalytics` | Gets views, likes, replies, reposts and quotes for a post. |
52
+ | `threadsQuote` | Quotes a post with a comment. |
53
+
54
+ ### `threadsPost`
55
+
56
+ | Parameter | Type | Required | Description |
57
+ | --- | --- | --- | --- |
58
+ | `text` | string | yes | Post text (max `500` characters) |
59
+ | `imageUrl` | string | no | URL of image to attach |
60
+ | `videoUrl` | string | no | URL of video to attach |
61
+ | `carouselItems` | object[] | no | Carousel items (array of image/video objects) |
62
+
63
+ Each object in `carouselItems` has this schema:
64
+
65
+ | Parameter | Type | Required | Description |
66
+ | --- | --- | --- | --- |
67
+ | `type` | string: `IMAGE`, `VIDEO` | yes | Media type |
68
+ | `url` | string | yes | Media URL |
69
+
70
+ ### `threadsReply`
71
+
72
+ | Parameter | Type | Required | Description |
73
+ | --- | --- | --- | --- |
74
+ | `postId` | string | yes | ID of the Threads post to reply to |
75
+ | `text` | string | yes | Reply text |
76
+ | `mediaUrl` | string | no | Optional image or video URL to attach |
77
+
78
+ ### `threadsLike`
79
+
80
+ | Parameter | Type | Required | Description |
81
+ | --- | --- | --- | --- |
82
+ | `postId` | string | yes | ID of the Threads post |
83
+ | `unlike` | boolean | no | Set to true to unlike; defaults to `false` |
84
+
85
+ ### `threadsSearch`
86
+
87
+ | Parameter | Type | Required | Description |
88
+ | --- | --- | --- | --- |
89
+ | `query` | string | no | Optional filter keyword (client-side filtering on returned posts) |
90
+ | `limit` | number | no | Max posts to return (default `25`, max `100`) |
91
+
92
+ ### `threadsAnalytics`
93
+
94
+ | Parameter | Type | Required | Description |
95
+ | --- | --- | --- | --- |
96
+ | `postId` | string | yes | ID of the Threads post to analyze |
97
+
98
+ ### `threadsQuote`
99
+
100
+ | Parameter | Type | Required | Description |
101
+ | --- | --- | --- | --- |
102
+ | `postId` | string | yes | ID of the Threads post to quote |
103
+ | `text` | string | yes | Your quote comment |
104
+
105
+ ## Channel adapter
106
+
107
+ The adapter registers platform `threads`. Initialization creates an authenticated HTTP client and resolves the user id. Sending ignores `conversationId`: it uses `replyToMessageId` for replies, then selects `carousel_item` blocks, video, image or text content for a new post. Each carousel block uses `mediaType` and `url`. Reactions like the specified message regardless of the reaction value. The adapter stores handlers but does not emit inbound events. Typing indicators do nothing.
108
+
109
+ ## Notes
110
+
111
+ Posting, replying and quoting publish content; liking and unliking change account interactions. The exported `ThreadsService.deletePost` deletes a post, but the factory does not register a deletion tool.
112
+
113
+ When the resolved token is empty, activation attempts to load the `threads` token through `FileTokenStore` from `@framers/agentos/auth`. Activation throws if no token is available. An omitted `userId` triggers a profile request.
114
+
115
+ Media publishing creates containers and waits for `FINISHED` before publishing. Image, carousel child and media reply polling allows `20` attempts with a `1000` ms interval. Standalone video polling allows `30` attempts with a `2000` ms interval. An `ERROR` status or exhausted attempts makes publishing fail.
116
+
117
+ `threadsSearch` retrieves the configured user's recent posts and filters the returned text locally, ignoring case. It does not perform a remote keyword search. The post schema describes a `500`-character text limit; the tool does not enforce that limit locally.
118
+
119
+ ## License
120
+
121
+ 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.threads",
4
4
  "name": "Threads Channel Extension",
5
- "version": "0.1.1",
5
+ "version": "0.1.3",
6
6
  "description": "Bidirectional Threads integration — post text, images, videos, carousels, reply, quote, like, search user threads, and track engagement analytics via Meta Threads Publishing API.",
7
7
  "categories": ["channel", "social"],
8
8
  "platforms": ["threads"],
package/package.json CHANGED
@@ -1,7 +1,8 @@
1
1
  {
2
2
  "name": "@framers/agentos-ext-channel-threads",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "description": "Threads channel adapter for AgentOS — post text, images, videos, carousels, replies, quotes, likes, and analytics via Meta Threads API.",
5
+ "license": "Apache-2.0",
5
6
  "main": "dist/index.js",
6
7
  "types": "dist/index.d.ts",
7
8
  "files": [
@@ -18,7 +19,7 @@
18
19
  "@types/node": "^20.0.0",
19
20
  "typescript": "^5.0.0",
20
21
  "vitest": "^3.2.7",
21
- "@framers/agentos": "^0.10.40"
22
+ "@framers/agentos": "^0.13.47"
22
23
  },
23
24
  "repository": {
24
25
  "type": "git",