npm install threads-sdk-js

threads-sdk-js wraps the documented Threads Graph API endpoints with a small TypeScript client, token-safe errors, cursor pagination helpers, and a registry-generated API reference. It is intended for server-side Node.js apps that publish Threads posts, retrieve posts and replies, read insights, use oEmbed, and work with token/debug utilities without hand-building every request.

Install

npm install threads-sdk-js

Node.js 20 or newer is required. The SDK uses native fetch by default and lets you inject a custom fetch implementation for tests or instrumentation.

Quickstart

import { ThreadsClient } from "threads-sdk-js";

const client = new ThreadsClient({
  accessToken: process.env.THREADS_ACCESS_TOKEN
});

const container = await client.posts.createContainer(process.env.THREADS_USER_ID!, {
  media_type: "TEXT",
  text: "Hello from the Threads API"
});

const post = await client.posts.publishContainer(process.env.THREADS_USER_ID!, {
  creation_id: container.id
});

console.log(post.id);

Endpoint Status

This table is generated from src/registry/endpoints.ts.

| ID | Category | Method | Path | Kind | Status | SDK helper | |---|---|---:|---|---|---|---| | posts.createContainer | Posts and publishing | POST | /{threads_user_id}/threads | graph_endpoint | supported | client.posts.createContainer() | | posts.publishContainer | Posts and publishing | POST | /{threads_user_id}/threads_publish | graph_endpoint | supported | client.posts.publishContainer() | | posts.repost | Posts and publishing | POST | /{threads_media_id}/repost | graph_endpoint | supported | client.posts.repost() | | posts.getContainerStatus | Posts and publishing | GET | /{threads_container_id} | graph_endpoint | supported | client.posts.getContainerStatus() | | posts.getMedia | Posts and retrieval | GET | /{threads_media_id} | graph_endpoint | supported | client.posts.get() | | posts.listUserThreads | Posts and retrieval | GET | /{threads_user_id}/threads | graph_endpoint | supported | client.posts.listUserThreads() | | posts.deleteMedia | Posts and publishing | DELETE | /{threads_media_id} | graph_endpoint | supported | client.posts.delete() | | posts.getReplies | Replies | GET | /{threads_media_id}/replies | graph_endpoint | supported | client.posts.getReplies() | | posts.getConversation | Replies | GET | /{threads_media_id}/conversation | graph_endpoint | supported | client.posts.getConversation() | | posts.getMentions | Posts and retrieval | GET | /{threads_user_id}/mentions | graph_endpoint | supported | client.posts.getMentions() | | replies.manageReply | Replies | POST | /{threads_reply_id}/manage_reply | graph_endpoint | supported | client.replies.manage() | | replies.getPendingReplies | Replies | GET | /{threads_media_id}/pending_replies | graph_endpoint | supported | client.replies.getPending() | | replies.managePendingReply | Replies | POST | /{threads_reply_id}/manage_pending_reply | graph_endpoint | supported | client.replies.managePending() | | profiles.getMe | Profiles | GET | /me | graph_endpoint | supported | client.profiles.getMe() | | profiles.getUser | Profiles | GET | /{threads_user_id} | graph_endpoint | supported | client.profiles.get() | | profiles.lookup | Profiles | GET | /profile_lookup | graph_endpoint | supported | client.profiles.lookup() | | profiles.listPublicPosts | Profiles | GET | /profile_posts | graph_endpoint | supported | client.profiles.listPublicPosts() | | profiles.getPublishingLimit | Profiles | GET | /{threads_user_id}/threads_publishing_limit | graph_endpoint | supported | client.profiles.getPublishingLimit() | | profiles.listReplies | Profiles | GET | /{threads_user_id}/replies | graph_endpoint | supported | client.profiles.listReplies() | | insights.getMediaInsights | Insights | GET | /{threads_media_id}/insights | graph_endpoint | supported | client.insights.getMedia() | | insights.getUserInsights | Insights | GET | /{threads_user_id}/threads_insights | graph_endpoint | supported | client.insights.getUser() | | search.keywordSearch | Search and discovery | GET | /keyword_search | graph_endpoint | supported | client.search.keyword() | | locations.get | Locations | GET | /{location_id} | graph_endpoint | supported | client.locations.get() | | location.search | Locations | GET | /location_search | graph_endpoint | supported | client.search.location() | | tokens.exchangeAuthorizationCode | Auth and debug | POST | /oauth/access_token | graph_endpoint | supported | client.utilities.exchangeAuthorizationCode() | | tokens.exchangeLongLived | Auth and debug | GET | /access_token | graph_endpoint | supported | client.utilities.exchangeLongLivedToken() | | tokens.refreshLongLived | Auth and debug | GET | /refresh_access_token | graph_endpoint | supported | client.utilities.refreshLongLivedToken() | | tokens.getAppAccessToken | Auth and debug | GET | /oauth/access_token | graph_endpoint | supported | client.utilities.getAppAccessToken() | | debug.debugToken | Auth and debug | GET | /debug_token | graph_endpoint | supported | client.utilities.debugToken() | | embed.oEmbed | Embeds | GET | /oembed | graph_endpoint | supported | client.utilities.oEmbed() | | webhooks.setup | Webhooks | - | - | dashboard_setup | dashboard_only | Documented capability; no Graph helper | | webhooks.payload | Webhooks | - | - | webhook_payload | helper_only | verifyWebhookChallenge() and exported webhook types |

Main API

const client = new ThreadsClient({
  accessToken: process.env.THREADS_ACCESS_TOKEN,
  apiVersion: "v23.0",
  timeoutMs: 30_000
});

Available helper groups:

• client.posts: create containers, publish containers, repost posts, check container status, retrieve media, list user posts, delete posts, replies, conversations, and mentions.
• client.replies: hide or unhide replies, list pending replies, and approve or ignore pending replies.
• client.profiles: retrieve app-scoped profiles, public profiles/posts, publishing limits, and user replies.
• client.insights: retrieve media and user insight metrics.
• client.locations: retrieve location objects by ID.
• client.search: keyword and location search helpers where Meta grants access.
• client.utilities: long-lived token exchange/refresh, token debug, and Threads oEmbed.
• client.request: low-level escape hatch for newly documented fields or endpoints.

Pagination

List helpers return one page by default and expose cursors explicitly:

const page = await client.posts.listUserThreads("123", {
  fields: ["id", "text", "timestamp"],
  limit: 25
});

console.log(page.data, page.nextCursor, page.previousCursor);

For caller-controlled lazy iteration:

for await (const page of client.iteratePages({
  path: "/123/threads",
  query: { fields: ["id", "text"], limit: 25 },
  limit: 3
})) {
  console.log(page.data);
}

Errors And Token Safety

The SDK throws ThreadsApiError for Graph API and network failures and ThreadsTimeoutError for timeout or abort cases. Error details redact access_token, Authorization, token-like values, and secrets before exposing request or raw payload data.

POST and DELETE calls are never retried automatically. You can opt into retries for safe GET calls:

const client = new ThreadsClient({
  accessToken: process.env.THREADS_ACCESS_TOKEN,
  retry: ({ status, attempt }) => ({
    retry: status === 429 && attempt < 2,
    delayMs: 500
  })
});

Webhooks

Webhook subscription setup is dashboard-driven in Meta developer tools. This package exports helper types and verifyWebhookChallenge() for callback verification, but it does not pretend dashboard setup is a callable Threads Graph endpoint.

Development

npm install
npm run docs:generate
npm run test
npm run test:coverage
npm run typecheck
npm run lint
npm run build
npm pack --dry-run

Tests use mocked fetch calls and do not require real Threads credentials.

Publishing

First manual publish:

npm whoami
npm view threads-sdk-js name version --json
npm run docs:check
npm run typecheck
npm run lint
npm test
npm run build
npm pack --dry-run
npm publish --access public

If npm view threads-sdk-js name version --json returns E404, the name is still available to your npm account. Before publishing, make sure package.json has the intended version and that CHANGELOG.md describes the release.

Automated releases:

1. Configure npm trusted publishing for GitHub Actions.
2. Set the trusted publisher workflow filename to release.yml.
3. Set the trusted publisher environment name to npm.
4. Merge the release commit to main.
5. Create and push a matching version tag, for example v0.1.0.

When the tag is pushed, .github/workflows/release.yml runs npm ci, npm run prepack, upgrades npm to a trusted-publishing-capable CLI, and runs npm publish through OIDC. No npm automation token is required.

Version And Support Policy

This package follows the official Meta Threads docs as source of truth. New Meta fields can be used immediately through client.request() and then promoted into typed helpers by updating the endpoint registry, generated docs, and tests.