Denim

A Deno/TypeScript wrapper for the Threads API. Covers posting, retrieval, replies, profiles, insights, search, locations, tokens, and oEmbed.

You'll need a Threads app with an access token from Meta's developer portal. See the Threads API docs for setup.

deno add @codybrom/denim

Publishing

Threads publishing is two steps: create a container, then publish it.

import {
	createThreadsContainer,
	publishThreadsContainer,
} from "@codybrom/denim";

const containerId = await createThreadsContainer({
	userId: "YOUR_USER_ID",
	accessToken: "YOUR_ACCESS_TOKEN",
	mediaType: "TEXT",
	text: "Hello from Denim!",
});

await publishThreadsContainer("YOUR_USER_ID", "YOUR_ACCESS_TOKEN", containerId);

createThreadsContainer(request) takes a ThreadsPostRequest and returns the container ID string. The request requires userId, accessToken, mediaType, and usually text. Optional fields control the post type:

| Field | Type | Purpose | | ------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------- | | imageUrl | string | Image URL (for IMAGE or CAROUSEL items) | | videoUrl | string | Video URL (for VIDEO or CAROUSEL items) | | altText | string | Alt text for images and videos | | linkAttachment | string | URL to attach to a TEXT post | | replyControl | string | "everyone", "accounts_you_follow", "mentioned_only", "parent_post_author_only", or "followers_only" | | allowlistedCountryCodes | string[] | ISO country codes to restrict post visibility | | replyToId | string | Post ID to reply to | | quotePostId | string | Post ID to quote | | pollAttachment | object | { option_a, option_b, option_c?, option_d? } | | topicTag | string | Topic tag for the post | | isGhostPost | boolean | Make a ghost post (text only, expires in 24h) | | isSpoilerMedia | boolean | Hide media behind a spoiler overlay | | textEntities | array | Text spoiler ranges: [{ entity_type, offset, length }] | | textAttachment | object | Long-form text: { plaintext, link_attachment_url? } | | gifAttachment | object | GIF: { gif_id, provider } | | locationId | string | Location ID from searchLocations | | children | string[] | Carousel item IDs from createCarouselItem | | autoPublishText | boolean | Skip the publish step for text posts |

publishThreadsContainer(userId, accessToken, containerId, getPermalink?) publishes a container. Pass true for getPermalink to get { id, permalink } instead of just the ID string.

createCarouselItem(request) creates individual items for a carousel post. Takes the same request shape but mediaType must be "IMAGE" or "VIDEO".

repost(mediaId, accessToken) reposts an existing thread. Returns { id }.

deleteThread(mediaId, accessToken) deletes a thread. Returns { success: boolean, deleted_id?: string }.

Retrieval

All retrieval functions accept an optional fields string array to request specific fields, and an optional PaginationOptions object ({ since?, until?, limit?, before?, after? }).

getThreadsList(userId, accessToken, options?, fields?) returns a user's threads as { data: ThreadsPost[], paging }.

getSingleThread(mediaId, accessToken, fields?) returns a single ThreadsPost.

getGhostPosts(userId, accessToken, options?, fields?) returns a user's ghost posts.

Profiles

getProfile(userId, accessToken, fields?) returns the authenticated user's ThreadsProfile (username, name, bio, profile picture, verification status).

lookupProfile(accessToken, username, fields?) looks up any public profile by username. Returns a PublicProfile with follower counts and engagement stats. Requires threads_profile_discovery permission.

getProfilePosts(accessToken, username, options?, fields?) returns a public profile's posts.

Replies

getReplies(mediaId, accessToken, options?, fields?, reverse?) returns direct replies to a post. Pass reverse: false for chronological order (default is reverse chronological).

getConversation(mediaId, accessToken, options?, fields?, reverse?) returns the full conversation thread (replies and nested replies). Pass reverse: false for chronological order.

getUserReplies(userId, accessToken, options?, fields?) returns all replies made by a user.

manageReply(replyId, accessToken, hide) hides or unhides a reply. Pass true to hide, false to unhide.

Insights

getMediaInsights(mediaId, accessToken, metrics) returns metrics for a post. Pass metric names as a string array: "views", "likes", "replies", "reposts", "quotes", "shares".

const insights = await getMediaInsights(postId, token, ["views", "likes"]);
// insights.data[0].values[0].value => 42

getUserInsights(userId, accessToken, metrics, options?) returns user-level metrics. Accepts an options object with since/until timestamps and breakdown for demographics.

Search & Locations

searchKeyword(accessToken, options, fields?) searches posts by keyword or topic tag. Options: { q, search_type?, search_mode?, media_type?, author_username?, ...pagination }. Requires threads_keyword_search permission for searching beyond your own posts.

searchLocations(accessToken, options, fields?) searches for locations by name or coordinates. Options: { query?, latitude?, longitude? }. Returns location objects with IDs you can pass to createThreadsContainer as locationId.

getLocation(locationId, accessToken, fields?) returns details for a location (name, address, city, country, coordinates).

Tokens

exchangeCodeForToken(clientId, clientSecret, code, redirectUri) exchanges an OAuth authorization code for a short-lived access token. Returns { access_token, user_id }.

getAppAccessToken(clientId, clientSecret) gets an app-level access token via client credentials. Returns { access_token, token_type }.

exchangeToken(clientSecret, accessToken) exchanges a short-lived token for a long-lived one (60 days). Returns { access_token, token_type, expires_in }.

refreshToken(accessToken) refreshes a long-lived token before it expires. Same return shape.

debugToken(accessToken, inputToken) returns metadata about a token: app ID, scopes, expiry, validity.

Other

getPublishingLimit(userId, accessToken, fields?) returns rate limit info: post quota, reply quota, and remaining usage.

getMentions(userId, accessToken, options?, fields?) returns posts that mention the authenticated user.

getOEmbed(accessToken, url, maxWidth?) returns embeddable HTML for a Threads post URL. Returns { html, provider_name, type, version, width }.

Utilities

validateRequest(request) checks a ThreadsPostRequest for invalid combinations (wrong media type for polls, too many text entities, etc.) and throws descriptive errors. Called automatically by createThreadsContainer.

checkContainerStatus(containerId, accessToken) polls a container's publishing status. Returns { status, error_message? } where status is "FINISHED", "IN_PROGRESS", "EXPIRED", "ERROR", or "PUBLISHED".

Testing

Denim ships a MockThreadsAPI interface for testing without network requests. Set an implementation on globalThis.threadsAPI and all functions route through it instead of calling the Threads API:

import { MockThreadsAPIImpl } from "@codybrom/denim";

const mock = new MockThreadsAPIImpl();
(globalThis as any).threadsAPI = mock;

// Now all denim functions use the mock
const container = await createThreadsContainer({ ... });

// Enable error mode to test failure paths
mock.setErrorMode(true);

See mod_test.ts for more examples.

deno task test

License

MIT