@codybrom/denim 1.3.5 → 2.0.0

package/src/api/getSingleThread.ts

@@ -0,0 +1,37 @@
+import { SINGLE_THREAD_FIELDS, THREADS_API_BASE_URL } from "../constants.ts";
+import type { ThreadsPost } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Retrieves a single Threads media object.
+ *
+ * @param mediaId - The ID of the Threads media object
+ * @param accessToken - The access token for authentication
+ * @param fields - Optional array of fields to return (defaults to all available fields)
+ * @returns A Promise that resolves to the ThreadsPost object
+ * @throws Will throw an error if the API request fails
+ */
+export async function getSingleThread(
+	mediaId: string,
+	accessToken: string,
+	fields?: string[],
+): Promise<ThreadsPost> {
+	const api = getAPI();
+	if (api) {
+		return api.getSingleThread(mediaId, accessToken, fields);
+	}
+	const fieldList = (fields ?? SINGLE_THREAD_FIELDS).join(",");
+	const url = new URL(`${THREADS_API_BASE_URL}/${mediaId}`);
+	url.searchParams.append("fields", fieldList);
+	url.searchParams.append("access_token", accessToken);
+
+	const response = await fetch(url.toString());
+	if (!response.ok) {
+		const errorBody = await response.text();
+		throw new Error(
+			`Failed to retrieve thread (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/getThreadsList.ts

@@ -0,0 +1,49 @@
+import { THREADS_API_BASE_URL, USER_THREADS_FIELDS } from "../constants.ts";
+import type { PaginationOptions, ThreadsListResponse } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Retrieves a list of all threads created by a user.
+ *
+ * @param userId - The user ID of the Threads account
+ * @param accessToken - The access token for authentication
+ * @param options - Optional parameters for pagination and date range
+ * @param fields - Optional array of fields to return (defaults to all available fields)
+ * @returns A Promise that resolves to the ThreadsListResponse
+ * @throws Will throw an error if the API request fails
+ */
+export async function getThreadsList(
+	userId: string,
+	accessToken: string,
+	options?: PaginationOptions,
+	fields?: string[],
+): Promise<ThreadsListResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.getThreadsList(userId, accessToken, options, fields);
+	}
+	const fieldList = (fields ?? USER_THREADS_FIELDS).join(",");
+	const url = new URL(`${THREADS_API_BASE_URL}/${userId}/threads`);
+	url.searchParams.append("fields", fieldList);
+	url.searchParams.append("access_token", accessToken);
+
+	if (options) {
+		if (options.since) url.searchParams.append("since", String(options.since));
+		if (options.until) url.searchParams.append("until", String(options.until));
+		if (options.limit) {
+			url.searchParams.append("limit", options.limit.toString());
+		}
+		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 retrieve threads list (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/getUserInsights.ts

@@ -0,0 +1,54 @@
+import { THREADS_API_BASE_URL } from "../constants.ts";
+import type { UserInsightsOptions, UserInsightsResponse } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Retrieves insight metrics for a Threads user.
+ *
+ * Available metrics: views, likes, replies, reposts, quotes, clicks,
+ * followers_count, follower_demographics
+ *
+ * @param userId - The user ID of the Threads account
+ * @param accessToken - The access token for authentication
+ * @param metrics - Array of metric names to retrieve
+ * @param options - Optional parameters for time range and breakdown
+ * @returns A Promise that resolves to the UserInsightsResponse
+ * @throws Will throw an error if the API request fails
+ */
+export async function getUserInsights(
+	userId: string,
+	accessToken: string,
+	metrics: string[],
+	options?: UserInsightsOptions,
+): Promise<UserInsightsResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.getUserInsights(userId, accessToken, metrics, options);
+	}
+
+	const url = new URL(`${THREADS_API_BASE_URL}/${userId}/threads_insights`);
+	url.searchParams.append("metric", metrics.join(","));
+	url.searchParams.append("access_token", accessToken);
+
+	if (options) {
+		if (options.since !== undefined) {
+			url.searchParams.append("since", options.since.toString());
+		}
+		if (options.until !== undefined) {
+			url.searchParams.append("until", options.until.toString());
+		}
+		if (options.breakdown) {
+			url.searchParams.append("breakdown", options.breakdown);
+		}
+	}
+
+	const response = await fetch(url.toString());
+	if (!response.ok) {
+		const errorBody = await response.text();
+		throw new Error(
+			`Failed to get user insights (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/getUserReplies.ts

@@ -0,0 +1,54 @@
+import { REPLY_FIELDS, THREADS_API_BASE_URL } from "../constants.ts";
+import type { PaginationOptions, ThreadsListResponse } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+const DEFAULT_FIELDS = REPLY_FIELDS.filter(
+	(f) => f !== "hide_status" && f !== "topic_tag",
+);
+
+/**
+ * Retrieves a list of all replies created by a user.
+ *
+ * @param userId - The user ID of the Threads account
+ * @param accessToken - The access token for authentication
+ * @param options - Optional pagination parameters
+ * @param fields - Optional array of fields to return
+ * @returns A Promise that resolves to the ThreadsListResponse
+ * @throws Will throw an error if the API request fails
+ */
+export async function getUserReplies(
+	userId: string,
+	accessToken: string,
+	options?: PaginationOptions,
+	fields?: string[],
+): Promise<ThreadsListResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.getUserReplies(userId, accessToken, options, fields);
+	}
+
+	const fieldList = (fields ?? DEFAULT_FIELDS).join(",");
+	const url = new URL(`${THREADS_API_BASE_URL}/${userId}/replies`);
+	url.searchParams.append("fields", fieldList);
+	url.searchParams.append("access_token", accessToken);
+
+	if (options) {
+		if (options.since) url.searchParams.append("since", String(options.since));
+		if (options.until) url.searchParams.append("until", String(options.until));
+		if (options.limit) {
+			url.searchParams.append("limit", options.limit.toString());
+		}
+		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 user replies (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/lookupProfile.ts

@@ -0,0 +1,53 @@
+import { THREADS_API_BASE_URL } from "../constants.ts";
+import type { PublicProfile } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+const DEFAULT_FIELDS = [
+	"username",
+	"name",
+	"profile_picture_url",
+	"biography",
+	"is_verified",
+	"follower_count",
+	"likes_count",
+	"quotes_count",
+	"replies_count",
+	"reposts_count",
+	"views_count",
+];
+
+/**
+ * Looks up a public Threads profile by username.
+ *
+ * @param accessToken - The access token for authentication
+ * @param username - The exact username to look up
+ * @param fields - Optional array of fields to return
+ * @returns A Promise that resolves to the PublicProfile object
+ * @throws Will throw an error if the API request fails
+ */
+export async function lookupProfile(
+	accessToken: string,
+	username: string,
+	fields?: string[],
+): Promise<PublicProfile> {
+	const api = getAPI();
+	if (api) {
+		return api.lookupProfile(accessToken, username, fields);
+	}
+
+	const fieldList = (fields ?? DEFAULT_FIELDS).join(",");
+	const url = new URL(`${THREADS_API_BASE_URL}/profile_lookup`);
+	url.searchParams.append("username", username);
+	url.searchParams.append("fields", fieldList);
+	url.searchParams.append("access_token", accessToken);
+
+	const response = await fetch(url.toString());
+	if (!response.ok) {
+		const errorBody = await response.text();
+		throw new Error(
+			`Failed to look up profile (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/manageReply.ts

@@ -0,0 +1,41 @@
+import { THREADS_API_BASE_URL } from "../constants.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Hides or unhides a reply on a Threads post.
+ *
+ * @param replyId - The ID of the reply to manage
+ * @param accessToken - The access token for authentication
+ * @param hide - Whether to hide (true) or unhide (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 manageReply(
+	replyId: string,
+	accessToken: string,
+	hide: boolean,
+): Promise<{ success: boolean }> {
+	const api = getAPI();
+	if (api) {
+		return api.manageReply(replyId, accessToken, hide);
+	}
+
+	const url = `${THREADS_API_BASE_URL}/${replyId}/manage_reply`;
+	const body = new URLSearchParams({
+		access_token: accessToken,
+		hide: String(hide),
+	});
+
+	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 reply: ${responseText}`);
+	}
+
+	return await response.json();
+}

package/src/api/publishThreadsContainer.ts

@@ -0,0 +1,107 @@
+import { THREADS_API_BASE_URL } from "../constants.ts";
+import { checkContainerStatus } from "../utils/checkContainerStatus.ts";
+import { getAPI } from "../utils/getAPI.ts";
+import { getSingleThread } from "./getSingleThread.ts";
+/**
+ * Publishes a Threads media container.
+ *
+ * @param userId - The user ID of the Threads account
+ * @param accessToken - The access token for authentication
+ * @param containerId - The ID of the container to publish
+ * @returns A Promise that resolves to the published container ID
+ * @throws Will throw an error if the API request fails or if publishing times out
+ *
+ * @example
+ * ```typescript
+ * const publishedId = await publishThreadsContainer("123456", "your_access_token", "container_id");
+ * ```
+ */
+export async function publishThreadsContainer(
+	userId: string,
+	accessToken: string,
+	containerId: string,
+	getPermalink: boolean = false,
+): Promise<string | { id: string; permalink: string }> {
+	const api = getAPI();
+	if (api) {
+		return api.publishThreadsContainer(
+			userId,
+			accessToken,
+			containerId,
+			getPermalink,
+		);
+	}
+	try {
+		// Wait 30 seconds before first status check (per API docs recommendation)
+		await new Promise((resolve) => setTimeout(resolve, 30_000));
+
+		// Poll container status once per minute, for up to 5 minutes (per API docs)
+		let result = await checkContainerStatus(containerId, accessToken);
+		let attempts = 0;
+		const maxAttempts = 5;
+		const pollInterval = 60_000; // 1 minute
+
+		while (
+			result.status !== "FINISHED" &&
+			attempts < maxAttempts
+		) {
+			if (result.status === "ERROR" || result.status === "EXPIRED") {
+				throw new Error(
+					`Container cannot be published. Status: ${result.status}${
+						result.error_message ? ` - ${result.error_message}` : ""
+					}`,
+				);
+			}
+			await new Promise((resolve) => setTimeout(resolve, pollInterval));
+			result = await checkContainerStatus(containerId, accessToken);
+			attempts++;
+		}
+
+		if (result.status !== "FINISHED") {
+			throw new Error(
+				`Container not ready after ${maxAttempts} attempts. Current status: ${result.status}`,
+			);
+		}
+
+		// Publish the container
+		const publishUrl = `${THREADS_API_BASE_URL}/${userId}/threads_publish`;
+		const publishBody = new URLSearchParams({
+			access_token: accessToken,
+			creation_id: containerId,
+		});
+
+		const publishResponse = await fetch(publishUrl, {
+			method: "POST",
+			body: publishBody,
+			headers: {
+				"Content-Type": "application/x-www-form-urlencoded",
+			},
+		});
+
+		if (!publishResponse.ok) {
+			const errorBody = await publishResponse.text();
+			throw new Error(
+				`Failed to publish Threads container (${publishResponse.status}): ${errorBody}`,
+			);
+		}
+
+		const publishData = await publishResponse.json();
+
+		if (getPermalink) {
+			const threadData = await getSingleThread(publishData.id, accessToken);
+			return {
+				id: publishData.id,
+				permalink: threadData.permalink || "",
+			};
+		}
+
+		return publishData.id;
+	} catch (error) {
+		if (error instanceof Error) {
+			throw error;
+		}
+		throw new Error(
+			`Failed to publish Threads container: ${String(error)}`,
+		);
+	}
+}

package/src/api/refreshToken.ts

@@ -0,0 +1,33 @@
+import { THREADS_OAUTH_BASE_URL } from "../constants.ts";
+import type { TokenResponse } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Refreshes a long-lived access token.
+ *
+ * @param accessToken - The long-lived access token to refresh
+ * @returns A Promise that resolves to the TokenResponse with the refreshed token
+ * @throws Will throw an error if the API request fails
+ */
+export async function refreshToken(
+	accessToken: string,
+): Promise<TokenResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.refreshToken(accessToken);
+	}
+
+	const url = new URL(`${THREADS_OAUTH_BASE_URL}/refresh_access_token`);
+	url.searchParams.append("grant_type", "th_refresh_token");
+	url.searchParams.append("access_token", accessToken);
+
+	const response = await fetch(url.toString());
+	if (!response.ok) {
+		const errorBody = await response.text();
+		throw new Error(
+			`Failed to refresh token (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/repost.ts

@@ -0,0 +1,38 @@
+import { THREADS_API_BASE_URL } from "../constants.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Reposts a previously published Threads post.
+ *
+ * @param mediaId - The ID of the Threads media to repost
+ * @param accessToken - The access token for authentication
+ * @returns A Promise that resolves to an object with the repost ID
+ * @throws Will throw an error if the API request fails
+ */
+export async function repost(
+	mediaId: string,
+	accessToken: string,
+): Promise<{ id: string }> {
+	const api = getAPI();
+	if (api) {
+		return api.repost(mediaId, accessToken);
+	}
+
+	const url = `${THREADS_API_BASE_URL}/${mediaId}/repost`;
+	const body = new URLSearchParams({
+		access_token: accessToken,
+	});
+
+	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 repost: ${responseText}`);
+	}
+
+	return await response.json();
+}

package/src/api/searchKeyword.ts

@@ -0,0 +1,86 @@
+import { THREADS_API_BASE_URL } from "../constants.ts";
+import type { KeywordSearchOptions, ThreadsListResponse } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+const DEFAULT_FIELDS = [
+	"id",
+	"media_product_type",
+	"media_type",
+	"media_url",
+	"permalink",
+	"username",
+	"text",
+	"timestamp",
+	"shortcode",
+	"thumbnail_url",
+	"children",
+	"is_quote_post",
+	"alt_text",
+	"link_attachment_url",
+	"has_replies",
+	"is_reply",
+	"root_post",
+	"replied_to",
+	"reply_audience",
+	"quoted_post",
+	"reposted_post",
+	"gif_url",
+	"poll_attachment",
+	"topic_tag",
+];
+
+/**
+ * Searches for Threads posts by keyword or topic tag.
+ *
+ * @param accessToken - The access token for authentication
+ * @param options - Search options including query string and filters
+ * @param fields - Optional array of fields to return
+ * @returns A Promise that resolves to the ThreadsListResponse
+ * @throws Will throw an error if the API request fails
+ */
+export async function searchKeyword(
+	accessToken: string,
+	options: KeywordSearchOptions,
+	fields?: string[],
+): Promise<ThreadsListResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.searchKeyword(accessToken, options, fields);
+	}
+
+	const fieldList = (fields ?? DEFAULT_FIELDS).join(",");
+	const url = new URL(`${THREADS_API_BASE_URL}/keyword_search`);
+	url.searchParams.append("q", options.q);
+	url.searchParams.append("fields", fieldList);
+	url.searchParams.append("access_token", accessToken);
+
+	if (options.search_type) {
+		url.searchParams.append("search_type", options.search_type);
+	}
+	if (options.search_mode) {
+		url.searchParams.append("search_mode", options.search_mode);
+	}
+	if (options.media_type) {
+		url.searchParams.append("media_type", options.media_type);
+	}
+	if (options.author_username) {
+		url.searchParams.append("author_username", options.author_username);
+	}
+	if (options.since) url.searchParams.append("since", String(options.since));
+	if (options.until) url.searchParams.append("until", String(options.until));
+	if (options.limit) {
+		url.searchParams.append("limit", options.limit.toString());
+	}
+	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 search keywords (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/searchLocations.ts

@@ -0,0 +1,46 @@
+import { LOCATION_FIELDS, THREADS_API_BASE_URL } from "../constants.ts";
+import type { LocationSearchOptions, ThreadsLocation } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Searches for locations on Threads.
+ *
+ * @param accessToken - The access token for authentication
+ * @param options - Search options including query and coordinates
+ * @param fields - Optional array of fields to return
+ * @returns A Promise that resolves to an array of locations
+ * @throws Will throw an error if the API request fails
+ */
+export async function searchLocations(
+	accessToken: string,
+	options: LocationSearchOptions,
+	fields?: string[],
+): Promise<{ data: ThreadsLocation[] }> {
+	const api = getAPI();
+	if (api) {
+		return api.searchLocations(accessToken, options, fields);
+	}
+
+	const fieldList = (fields ?? LOCATION_FIELDS).join(",");
+	const url = new URL(`${THREADS_API_BASE_URL}/location_search`);
+	url.searchParams.append("access_token", accessToken);
+	url.searchParams.append("fields", fieldList);
+
+	if (options.query) url.searchParams.append("query", options.query);
+	if (options.latitude !== undefined) {
+		url.searchParams.append("latitude", options.latitude.toString());
+	}
+	if (options.longitude !== undefined) {
+		url.searchParams.append("longitude", options.longitude.toString());
+	}
+
+	const response = await fetch(url.toString());
+	if (!response.ok) {
+		const errorBody = await response.text();
+		throw new Error(
+			`Failed to search locations (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/constants.ts

@@ -0,0 +1,80 @@
+/** The base URL for the Threads API */
+export const THREADS_API_BASE_URL = "https://graph.threads.net/v1.0";
+
+/** The base URL for OAuth/token endpoints (no version prefix) */
+export const THREADS_OAUTH_BASE_URL = "https://graph.threads.net";
+
+/** Fields common to all media post endpoints */
+const MEDIA_BASE_FIELDS = [
+	"id",
+	"media_product_type",
+	"media_type",
+	"media_url",
+	"permalink",
+	"username",
+	"text",
+	"timestamp",
+	"shortcode",
+	"thumbnail_url",
+	"children",
+	"is_quote_post",
+	"has_replies",
+	"is_verified",
+	"profile_picture_url",
+] as const;
+
+/** Fields for own-post retrieval (GET /{user-id}/threads) */
+export const USER_THREADS_FIELDS = [
+	...MEDIA_BASE_FIELDS,
+	"owner",
+	"alt_text",
+	"link_attachment_url",
+	"reply_audience",
+	"quoted_post",
+	"reposted_post",
+	"gif_url",
+	"poll_attachment",
+	"topic_tag",
+	"is_spoiler_media",
+	"text_entities",
+	"text_attachment",
+	"ghost_post_status",
+	"ghost_post_expiration_timestamp",
+] as const;
+
+/** Fields for single thread retrieval (GET /{media-id}) */
+export const SINGLE_THREAD_FIELDS = [
+	...USER_THREADS_FIELDS,
+	"is_reply",
+	"is_reply_owned_by_me",
+	"root_post",
+	"replied_to",
+	"hide_status",
+] as const;
+
+/** Fields for reply/conversation endpoints */
+export const REPLY_FIELDS = [
+	...MEDIA_BASE_FIELDS,
+	"root_post",
+	"replied_to",
+	"is_reply",
+	"is_reply_owned_by_me",
+	"hide_status",
+	"reply_audience",
+	"quoted_post",
+	"reposted_post",
+	"gif_url",
+	"topic_tag",
+] as const;
+
+/** Fields for location endpoints */
+export const LOCATION_FIELDS = [
+	"id",
+	"name",
+	"address",
+	"city",
+	"country",
+	"latitude",
+	"longitude",
+	"postal_code",
+] as const;