@codybrom/denim 2.0.2 → 2.1.0

package/CHANGELOG.md

@@ -6,6 +6,29 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.1.0] - 2026-09-20
+
+### Added
+
+- Reply Approvals (Feb 13, 2026 API): `enableReplyApprovals` on
+  `ThreadsPostRequest`, `getPendingReplies()` (`GET /{media-id}/pending_replies`
+  with `approval_status` filter), `managePendingReply()`
+  (`POST /{reply-id}/manage_pending_reply`), `reply_approval_status` on
+  `ThreadsPost`, and `ApprovalStatus` / `PendingRepliesOptions` types. Ghost
+  posts cannot combine with reply approvals.
+- Share to Instagram Stories (Mar 25, 2026 API): `shareToIgStory` and
+  `shareToIgStoryDarkMode` on `ThreadsPostRequest` (`crossreshare_to_ig` /
+  `crossreshare_to_ig_dark_mode`, requires `threads_share_to_instagram`
+  permission). `publishThreadsContainer` with `getPermalink: true` now also
+  returns `crossreshare_to_ig_status`.
+
+### Changed
+
+- `getOEmbed()` no longer requires an access token (Mar 3, 2026 API). Preferred
+  order is now `getOEmbed(postUrl, accessToken?, maxWidth?)`; legacy
+  `getOEmbed(accessToken, postUrl, maxWidth?)` still works.
+- `AuthCodeResponse` now includes optional `token_type` (Aug 12, 2026 API).
+
 ## [2.0.2] - 2026-07-11
 
 ### Fixed

package/deno.json

@@ -1,6 +1,6 @@
 {
 	"name": "@codybrom/denim",
-	"version": "2.0.2",
+	"version": "2.1.0",
 	"description": "A Deno/TypeScript library for the Threads API",
 	"exports": {
 		".": "./mod.ts"

package/mod.ts

@@ -8,6 +8,7 @@
 
 // ─── Types ───────────────────────────────────────────────────────────────────
 import type {
+	ApprovalStatus,
 	AuthCodeResponse,
 	CursorPaginationOptions,
 	DebugTokenInfo,
@@ -21,10 +22,12 @@ import type {
 	MockThreadsAPI,
 	OEmbedResponse,
 	PaginationOptions,
+	PendingRepliesOptions,
 	PollAttachment,
 	PollAttachmentInput,
 	PublicProfile,
 	PublishingLimit,
+	PublishResult,
 	QuotaConfig,
 	ReplyControl,
 	ResponseMediaType,
@@ -49,6 +52,7 @@ import type {
 } from "./src/types.ts";
 
 export type {
+	ApprovalStatus,
 	AuthCodeResponse,
 	CursorPaginationOptions,
 	DebugTokenInfo,
@@ -62,10 +66,12 @@ export type {
 	MockThreadsAPI,
 	OEmbedResponse,
 	PaginationOptions,
+	PendingRepliesOptions,
 	PollAttachment,
 	PollAttachmentInput,
 	PublicProfile,
 	PublishingLimit,
+	PublishResult,
 	QuotaConfig,
 	ReplyControl,
 	ResponseMediaType,
@@ -108,8 +114,10 @@ export { lookupProfile } from "./src/api/lookupProfile.ts";
 
 // ─── Replies ─────────────────────────────────────────────────────────────────
 export { getConversation } from "./src/api/getConversation.ts";
+export { getPendingReplies } from "./src/api/getPendingReplies.ts";
 export { getReplies } from "./src/api/getReplies.ts";
 export { getUserReplies } from "./src/api/getUserReplies.ts";
+export { managePendingReply } from "./src/api/managePendingReply.ts";
 export { manageReply } from "./src/api/manageReply.ts";
 
 // ─── Mentions ────────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@codybrom/denim",
-	"version": "2.0.2",
+	"version": "2.1.0",
 	"description": "A Deno/TypeScript library for the Threads API",
 	"main": "mod.ts",
 	"directories": {

package/readme.md

@@ -115,6 +115,15 @@ made by a user.
 `manageReply(replyId, accessToken, hide)` hides or unhides a reply. Pass `true`
 to hide, `false` to unhide.
 
+`getPendingReplies(mediaId, accessToken, options?, fields?, reverse?,
+approvalStatus?)`
+returns replies awaiting approval on posts created with
+`enableReplyApprovals: true`. Filter with `"pending"` or `"ignored"` (default
+returns both).
+
+`managePendingReply(replyId, accessToken, approve)` approves (`true`) or ignores
+(`false`) a pending reply. Ignored replies can still be approved later.
+
 ## Insights
 
 `getMediaInsights(mediaId, accessToken, metrics)` returns metrics for a post.
@@ -150,7 +159,7 @@ objects with IDs you can pass to `createThreadsContainer` as `locationId`.
 
 `exchangeCodeForToken(clientId, clientSecret, code, redirectUri)` exchanges an
 OAuth authorization code for a short-lived access token. Returns
-`{ access_token, user_id }`.
+`{ access_token, user_id, token_type? }` (`token_type` present since Aug 2026).
 
 `getAppAccessToken(clientId, clientSecret)` gets an app-level access token via
 client credentials. Returns `{ access_token, token_type }`.
@@ -172,8 +181,17 @@ 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 }`.
+`getOEmbed(postUrl, accessToken?, maxWidth?)` returns embeddable HTML for a
+Threads post URL. No access token required since Mar 2026. Legacy
+`getOEmbed(accessToken, url, maxWidth?)` order still works. Returns
+`{ html, provider_name, type, version, width }`.
+
+`createThreadsContainer` accepts `enableReplyApprovals?: boolean` (cannot be
+combined with `isGhostPost`), plus `shareToIgStory?: boolean` and
+`shareToIgStoryDarkMode?: boolean` for cross-sharing to the linked Instagram
+account as a Story (requires `threads_share_to_instagram` permission).
+`publishThreadsContainer(..., getPermalink=true)` may also return
+`crossreshare_to_ig_status: "SUCCESS" | "FAILED"`.
 
 ## Utilities
 

package/src/api/createThreadsContainer.ts

@@ -68,6 +68,21 @@ export async function createThreadsContainer(
 		if (request.isSpoilerMedia !== undefined) {
 			body.append("is_spoiler_media", String(request.isSpoilerMedia));
 		}
+		if (request.enableReplyApprovals !== undefined) {
+			body.append(
+				"enable_reply_approvals",
+				String(request.enableReplyApprovals),
+			);
+		}
+		if (request.shareToIgStory !== undefined) {
+			body.append("crossreshare_to_ig", String(request.shareToIgStory));
+		}
+		if (request.shareToIgStoryDarkMode !== undefined) {
+			body.append(
+				"crossreshare_to_ig_dark_mode",
+				String(request.shareToIgStoryDarkMode),
+			);
+		}
 
 		// JSON-serialized parameters
 		if (request.pollAttachment) {

package/src/api/getOEmbed.ts

@@ -2,31 +2,66 @@ import { THREADS_API_BASE_URL } from "../constants.ts";
 import type { OEmbedResponse } from "../types.ts";
 import { getAPI } from "../utils/getAPI.ts";
 
+function isUrl(value: string): boolean {
+	return /^https?:\/\//i.test(value);
+}
+
 /**
  * Retrieves oEmbed HTML for a Threads post.
+ * Since March 3, 2026 the oEmbed endpoint works without an access token.
  *
- * @param accessToken - The access token for authentication
- * @param postUrl - The URL of the Threads post to embed
+ * Supports both call orders for backwards compatibility:
+ * - `getOEmbed(accessToken, postUrl, maxWidth?)` (legacy)
+ * - `getOEmbed(postUrl, accessToken?, maxWidth?)` (preferred)
+ * - `getOEmbed(postUrl, maxWidth?)` — no token; pass maxWidth as second arg
+ *   only via the 3-arg form `getOEmbed(postUrl, undefined, maxWidth)`
+ *
+ * @param accessTokenOrUrl - Legacy access token OR the post URL
+ * @param urlOrAccessTokenOrMaxWidth - Post URL, optional access token, or maxWidth
  * @param maxWidth - Optional maximum width of the embed in pixels
  * @returns A Promise that resolves to the OEmbedResponse
  * @throws Will throw an error if the API request fails
  */
 export async function getOEmbed(
-	accessToken: string,
-	postUrl: string,
+	accessTokenOrUrl: string,
+	urlOrAccessTokenOrMaxWidth?: string | number,
 	maxWidth?: number,
 ): Promise<OEmbedResponse> {
+	let accessToken: string | undefined;
+	let postUrl: string;
+	let resolvedMaxWidth = maxWidth;
+
+	if (typeof urlOrAccessTokenOrMaxWidth === "number") {
+		// getOEmbed(postUrl, maxWidth)
+		postUrl = accessTokenOrUrl;
+		resolvedMaxWidth = urlOrAccessTokenOrMaxWidth;
+	} else if (urlOrAccessTokenOrMaxWidth === undefined) {
+		// Single-arg: must be the post URL (no token)
+		postUrl = accessTokenOrUrl;
+	} else if (isUrl(accessTokenOrUrl) && !isUrl(urlOrAccessTokenOrMaxWidth)) {
+		// New order: getOEmbed(postUrl, accessToken?, maxWidth?)
+		postUrl = accessTokenOrUrl;
+		accessToken = urlOrAccessTokenOrMaxWidth || undefined;
+	} else {
+		// Legacy order: getOEmbed(accessToken, postUrl, maxWidth?)
+		accessToken = accessTokenOrUrl || undefined;
+		postUrl = urlOrAccessTokenOrMaxWidth;
+	}
+
 	const api = getAPI();
 	if (api) {
-		return api.getOEmbed(accessToken, postUrl, maxWidth);
+		// Mock preserves legacy (token, url) ordering
+		return api.getOEmbed(accessToken ?? "", postUrl, resolvedMaxWidth);
 	}
 
 	const url = new URL(`${THREADS_API_BASE_URL}/oembed`);
 	url.searchParams.append("url", postUrl);
-	url.searchParams.append("access_token", accessToken);
+	if (accessToken) {
+		url.searchParams.append("access_token", accessToken);
+	}
 
-	if (maxWidth !== undefined) {
-		url.searchParams.append("maxwidth", maxWidth.toString());
+	if (resolvedMaxWidth !== undefined) {
+		url.searchParams.append("maxwidth", resolvedMaxWidth.toString());
 	}
 
 	const response = await fetch(url.toString());

package/src/api/getPendingReplies.ts

@@ -0,0 +1,69 @@
+import { PENDING_REPLY_FIELDS, THREADS_API_BASE_URL } from "../constants.ts";
+import type {
+	ApprovalStatus,
+	CursorPaginationOptions,
+	ThreadsListResponse,
+} from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Retrieves pending replies awaiting approval on a Threads post.
+ * Only applicable to posts created with reply approvals enabled.
+ *
+ * @param mediaId - The ID of the Threads media object
+ * @param accessToken - The access token for authentication
+ * @param options - Optional pagination parameters
+ * @param fields - Optional array of fields to return
+ * @param reverse - Optional boolean to sort in reverse chronological order (default: true)
+ * @param approvalStatus - Optional filter: `pending` or `ignored` (default returns both)
+ * @returns A Promise that resolves to the ThreadsListResponse
+ * @throws Will throw an error if the API request fails
+ */
+export async function getPendingReplies(
+	mediaId: string,
+	accessToken: string,
+	options?: CursorPaginationOptions,
+	fields?: string[],
+	reverse?: boolean,
+	approvalStatus?: ApprovalStatus,
+): Promise<ThreadsListResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.getPendingReplies(
+			mediaId,
+			accessToken,
+			options,
+			fields,
+			reverse,
+			approvalStatus,
+		);
+	}
+
+	const fieldList = (fields ?? PENDING_REPLY_FIELDS).join(",");
+	const url = new URL(`${THREADS_API_BASE_URL}/${mediaId}/pending_replies`);
+	url.searchParams.append("fields", fieldList);
+	url.searchParams.append("access_token", accessToken);
+
+	if (reverse !== undefined) {
+		url.searchParams.append("reverse", String(reverse));
+	}
+
+	if (approvalStatus !== undefined) {
+		url.searchParams.append("approval_status", approvalStatus);
+	}
+
+	if (options) {
+		if (options.after) url.searchParams.append("after", options.after);
+		if (options.before) url.searchParams.append("before", options.before);
+	}
+
+	const response = await fetch(url.toString());
+	if (!response.ok) {
+		const errorBody = await response.text();
+		throw new Error(
+			`Failed to get pending replies (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/managePendingReply.ts

@@ -0,0 +1,42 @@
+import { THREADS_API_BASE_URL } from "../constants.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Approves or ignores a pending reply on a Threads post with reply approvals enabled.
+ * Ignored replies can still be approved later.
+ *
+ * @param replyId - The ID of the pending reply to manage
+ * @param accessToken - The access token for authentication
+ * @param approve - Whether to approve (true) or ignore (false) the reply
+ * @returns A Promise that resolves to an object indicating success
+ * @throws Will throw an error if the API request fails
+ */
+export async function managePendingReply(
+	replyId: string,
+	accessToken: string,
+	approve: boolean,
+): Promise<{ success: boolean }> {
+	const api = getAPI();
+	if (api) {
+		return api.managePendingReply(replyId, accessToken, approve);
+	}
+
+	const url = `${THREADS_API_BASE_URL}/${replyId}/manage_pending_reply`;
+	const body = new URLSearchParams({
+		access_token: accessToken,
+		approve: String(approve),
+	});
+
+	const response = await fetch(url, {
+		method: "POST",
+		body: body,
+		headers: { "Content-Type": "application/x-www-form-urlencoded" },
+	});
+
+	if (!response.ok) {
+		const responseText = await response.text();
+		throw new Error(`Failed to manage pending reply: ${responseText}`);
+	}
+
+	return await response.json();
+}

package/src/api/publishThreadsContainer.ts

@@ -92,6 +92,11 @@ export async function publishThreadsContainer(
 			return {
 				id: publishData.id,
 				permalink: threadData.permalink || "",
+				...(publishData.crossreshare_to_ig_status
+					? {
+						crossreshare_to_ig_status: publishData.crossreshare_to_ig_status,
+					}
+					: {}),
 			};
 		}
 

package/src/constants.ts

@@ -65,6 +65,12 @@ export const REPLY_FIELDS = [
 	"reposted_post",
 	"gif_url",
 	"topic_tag",
+	"reply_approval_status",
+] as const;
+
+/** Fields for pending replies endpoint (same as replies, includes approval status) */
+export const PENDING_REPLY_FIELDS = [
+	...REPLY_FIELDS,
 ] as const;
 
 /** Fields for location endpoints */

package/src/types.ts

@@ -136,6 +136,12 @@ export interface ThreadsPostRequest {
 	isGhostPost?: boolean;
 	/** Location ID to tag (optional) */
 	locationId?: string;
+	/** Enable reply approvals — replies must be approved before publishing (optional, cannot be used with isGhostPost) */
+	enableReplyApprovals?: boolean;
+	/** Cross-share the post to the linked Instagram account as a Story (optional, any media type, requires `threads_share_to_instagram` permission) */
+	shareToIgStory?: boolean;
+	/** Cross-share the post to the linked Instagram account as a Story in dark mode (optional, any media type, requires `threads_share_to_instagram` permission) */
+	shareToIgStoryDarkMode?: boolean;
 }
 
 /**
@@ -165,6 +171,33 @@ export interface CursorPaginationOptions {
 	after?: string;
 }
 
+/**
+ * Approval status filter for pending replies.
+ * `pending` shows only pending replies, `ignored` shows only ignored replies.
+ * Default (omitted) returns both.
+ */
+export type ApprovalStatus = "pending" | "ignored";
+
+/**
+ * Options for pending replies retrieval.
+ */
+export interface PendingRepliesOptions extends CursorPaginationOptions {
+	/** Filter by approval status (optional, default returns both) */
+	approval_status?: ApprovalStatus;
+}
+
+/**
+ * Result of publishing a Threads media container.
+ */
+export interface PublishResult {
+	/** The published Threads media ID */
+	id: string;
+	/** Permalink (only populated when requested via `getPermalink`) */
+	permalink?: string;
+	/** Cross-share to Instagram Story status (only when cross-sharing was requested) */
+	crossreshare_to_ig_status?: "SUCCESS" | "FAILED";
+}
+
 // ─── Response Types (snake_case — matching API reality) ──────────────────────
 
 /**
@@ -319,6 +352,8 @@ export interface ThreadsPost {
 	ghost_post_expiration_timestamp?: string;
 	/** List of country codes where the post is visible */
 	allowlisted_country_codes?: string[];
+	/** Approval status of a pending reply (`pending` or `ignored`) */
+	reply_approval_status?: "pending" | "ignored";
 }
 
 /**
@@ -552,12 +587,15 @@ export interface LocationSearchOptions {
 
 /**
  * Response from exchanging an OAuth authorization code for a short-lived token.
+ * Since August 12, 2026 the API also returns `token_type`.
  */
 export interface AuthCodeResponse {
 	/** The short-lived access token */
 	access_token: string;
 	/** The user ID of the authenticated user */
 	user_id: string;
+	/** Token type (e.g., "bearer"). Present since August 12, 2026. */
+	token_type?: string;
 }
 
 /**
@@ -760,7 +798,14 @@ export interface MockThreadsAPI {
 		accessToken: string,
 		containerId: string,
 		getPermalink?: boolean,
-	): Promise<string | { id: string; permalink: string }>;
+	): Promise<
+		| string
+		| {
+			id: string;
+			permalink: string;
+			crossreshare_to_ig_status?: "SUCCESS" | "FAILED";
+		}
+	>;
 
 	createCarouselItem(
 		request: Omit<ThreadsPostRequest, "mediaType"> & {
@@ -853,6 +898,21 @@ export interface MockThreadsAPI {
 		hide: boolean,
 	): Promise<{ success: boolean }>;
 
+	getPendingReplies(
+		mediaId: string,
+		accessToken: string,
+		options?: CursorPaginationOptions,
+		fields?: string[],
+		reverse?: boolean,
+		approvalStatus?: ApprovalStatus,
+	): Promise<ThreadsListResponse>;
+
+	managePendingReply(
+		replyId: string,
+		accessToken: string,
+		approve: boolean,
+	): Promise<{ success: boolean }>;
+
 	getMentions(
 		userId: string,
 		accessToken: string,
@@ -918,8 +978,8 @@ export interface MockThreadsAPI {
 	): Promise<DebugTokenInfo>;
 
 	getOEmbed(
-		accessToken: string,
-		url: string,
+		accessTokenOrUrl: string,
+		urlOrUndefined?: string,
 		maxWidth?: number,
 	): Promise<OEmbedResponse>;
 }

package/src/utils/mock_threads_api.ts

@@ -101,7 +101,13 @@ export class MockThreadsAPIImpl implements MockThreadsAPI {
 		_accessToken: string,
 		containerId: string,
 		getPermalink: boolean = false,
-	): Promise<string | { id: string; permalink: string }> {
+	): Promise<
+		string | {
+			id: string;
+			permalink: string;
+			crossreshare_to_ig_status?: "SUCCESS" | "FAILED";
+		}
+	> {
 		if (this.errorMode) {
 			return Promise.reject(new Error("Failed to publish Threads container"));
 		}
@@ -377,6 +383,36 @@ export class MockThreadsAPIImpl implements MockThreadsAPI {
 		return Promise.resolve({ success: true });
 	}
 
+	getPendingReplies(
+		_mediaId: string,
+		_accessToken: string,
+		_options?: CursorPaginationOptions,
+		_fields?: string[],
+		_reverse?: boolean,
+		_approvalStatus?: "pending" | "ignored",
+	): Promise<ThreadsListResponse> {
+		if (this.errorMode) {
+			return Promise.reject(new Error("Failed to get pending replies"));
+		}
+		return Promise.resolve({
+			data: Array.from(this.posts.values()).slice(0, 25),
+			paging: {
+				cursors: { before: "BEFORE_CURSOR", after: "AFTER_CURSOR" },
+			},
+		});
+	}
+
+	managePendingReply(
+		_replyId: string,
+		_accessToken: string,
+		_approve: boolean,
+	): Promise<{ success: boolean }> {
+		if (this.errorMode) {
+			return Promise.reject(new Error("Failed to manage pending reply"));
+		}
+		return Promise.resolve({ success: true });
+	}
+
 	getMentions(
 		_userId: string,
 		_accessToken: string,
@@ -504,6 +540,7 @@ export class MockThreadsAPIImpl implements MockThreadsAPI {
 		return Promise.resolve({
 			access_token: "short_lived_token_abc123",
 			user_id: "12345",
+			token_type: "bearer",
 		});
 	}
 
@@ -564,8 +601,8 @@ export class MockThreadsAPIImpl implements MockThreadsAPI {
 	}
 
 	getOEmbed(
-		_accessToken: string,
-		_url: string,
+		_accessTokenOrUrl: string,
+		_urlOrUndefined?: string,
 		_maxWidth?: number,
 	): Promise<OEmbedResponse> {
 		if (this.errorMode) {

package/src/utils/validateRequest.ts

@@ -51,6 +51,11 @@ export async function validateRequest(
 		if (request.replyToId) {
 			throw new Error("isGhostPost cannot be used together with replyToId");
 		}
+		if (request.enableReplyApprovals) {
+			throw new Error(
+				"enableReplyApprovals cannot be used together with isGhostPost",
+			);
+		}
 	}
 
 	// Text attachment can only be used with TEXT posts and not with polls