@codybrom/denim 1.3.6 → 2.0.0

package/src/api/debugToken.ts

@@ -0,0 +1,35 @@
+import { THREADS_API_BASE_URL } from "../constants.ts";
+import type { DebugTokenInfo } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Retrieves debug information about an access token.
+ *
+ * @param accessToken - The access token for authentication
+ * @param inputToken - The token to debug
+ * @returns A Promise that resolves to the DebugTokenInfo
+ * @throws Will throw an error if the API request fails
+ */
+export async function debugToken(
+	accessToken: string,
+	inputToken: string,
+): Promise<DebugTokenInfo> {
+	const api = getAPI();
+	if (api) {
+		return api.debugToken(accessToken, inputToken);
+	}
+
+	const url = new URL(`${THREADS_API_BASE_URL}/debug_token`);
+	url.searchParams.append("input_token", inputToken);
+	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 debug token (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/deleteThread.ts

@@ -0,0 +1,36 @@
+import { THREADS_API_BASE_URL } from "../constants.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Deletes a Threads post.
+ *
+ * @param mediaId - The ID of the Threads media to delete
+ * @param accessToken - The access token for authentication
+ * @returns A Promise that resolves to an object indicating success
+ * @throws Will throw an error if the API request fails
+ */
+export async function deleteThread(
+	mediaId: string,
+	accessToken: string,
+): Promise<{ success: boolean; deleted_id?: string }> {
+	const api = getAPI();
+	if (api) {
+		return api.deleteThread(mediaId, accessToken);
+	}
+
+	const url = new URL(`${THREADS_API_BASE_URL}/${mediaId}`);
+	url.searchParams.append("access_token", accessToken);
+
+	const response = await fetch(url.toString(), {
+		method: "DELETE",
+	});
+
+	if (!response.ok) {
+		const responseText = await response.text();
+		throw new Error(
+			`Failed to delete thread (${response.status}): ${responseText}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/exchangeCodeForToken.ts

@@ -0,0 +1,50 @@
+import { THREADS_OAUTH_BASE_URL } from "../constants.ts";
+import type { AuthCodeResponse } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Exchanges an OAuth authorization code for a short-lived access token.
+ * This is the first step in the OAuth flow after the user authorizes your app.
+ *
+ * @param clientId - Your Threads App ID
+ * @param clientSecret - Your Threads App Secret
+ * @param code - The authorization code received from the redirect
+ * @param redirectUri - The redirect URI used in the authorization request
+ * @returns A Promise that resolves to the access token and user ID
+ * @throws Will throw an error if the API request fails
+ */
+export async function exchangeCodeForToken(
+	clientId: string,
+	clientSecret: string,
+	code: string,
+	redirectUri: string,
+): Promise<AuthCodeResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.exchangeCodeForToken(clientId, clientSecret, code, redirectUri);
+	}
+
+	const url = `${THREADS_OAUTH_BASE_URL}/oauth/access_token`;
+	const body = new URLSearchParams({
+		client_id: clientId,
+		client_secret: clientSecret,
+		code: code,
+		grant_type: "authorization_code",
+		redirect_uri: redirectUri,
+	});
+
+	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 exchange authorization code: ${responseText}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/exchangeToken.ts

@@ -0,0 +1,36 @@
+import { THREADS_OAUTH_BASE_URL } from "../constants.ts";
+import type { TokenResponse } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Exchanges a short-lived access token for a long-lived one.
+ *
+ * @param clientSecret - The app's client secret
+ * @param accessToken - The short-lived access token to exchange
+ * @returns A Promise that resolves to the TokenResponse with the long-lived token
+ * @throws Will throw an error if the API request fails
+ */
+export async function exchangeToken(
+	clientSecret: string,
+	accessToken: string,
+): Promise<TokenResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.exchangeToken(clientSecret, accessToken);
+	}
+
+	const url = new URL(`${THREADS_OAUTH_BASE_URL}/access_token`);
+	url.searchParams.append("grant_type", "th_exchange_token");
+	url.searchParams.append("client_secret", clientSecret);
+	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 exchange token (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/getAppAccessToken.ts

@@ -0,0 +1,35 @@
+import { THREADS_OAUTH_BASE_URL } from "../constants.ts";
+import type { TokenResponse } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Gets an app-level access token using client credentials.
+ * App tokens are used for server-to-server requests that don't act on behalf of a user.
+ *
+ * @param clientId - Your Threads App ID
+ * @param clientSecret - Your Threads App Secret
+ * @returns A Promise that resolves to the app access token
+ * @throws Will throw an error if the API request fails
+ */
+export async function getAppAccessToken(
+	clientId: string,
+	clientSecret: string,
+): Promise<TokenResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.getAppAccessToken(clientId, clientSecret);
+	}
+
+	const url = new URL(`${THREADS_OAUTH_BASE_URL}/oauth/access_token`);
+	url.searchParams.append("grant_type", "client_credentials");
+	url.searchParams.append("client_id", clientId);
+	url.searchParams.append("client_secret", clientSecret);
+
+	const response = await fetch(url.toString());
+	if (!response.ok) {
+		const responseText = await response.text();
+		throw new Error(`Failed to get app access token: ${responseText}`);
+	}
+
+	return await response.json();
+}

package/src/api/getConversation.ts

@@ -0,0 +1,51 @@
+import { REPLY_FIELDS, THREADS_API_BASE_URL } from "../constants.ts";
+import type { CursorPaginationOptions, ThreadsListResponse } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Retrieves the full conversation thread for a Threads media object.
+ *
+ * @param mediaId - The ID of the root 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)
+ * @returns A Promise that resolves to the ThreadsListResponse
+ * @throws Will throw an error if the API request fails
+ */
+export async function getConversation(
+	mediaId: string,
+	accessToken: string,
+	options?: CursorPaginationOptions,
+	fields?: string[],
+	reverse?: boolean,
+): Promise<ThreadsListResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.getConversation(mediaId, accessToken, options, fields, reverse);
+	}
+
+	const fieldList = (fields ?? REPLY_FIELDS).join(",");
+	const url = new URL(`${THREADS_API_BASE_URL}/${mediaId}/conversation`);
+	url.searchParams.append("fields", fieldList);
+	url.searchParams.append("access_token", accessToken);
+
+	if (reverse !== undefined) {
+		url.searchParams.append("reverse", String(reverse));
+	}
+
+	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 conversation (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/getGhostPosts.ts

@@ -0,0 +1,50 @@
+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 ghost posts 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 getGhostPosts(
+	userId: string,
+	accessToken: string,
+	options?: PaginationOptions,
+	fields?: string[],
+): Promise<ThreadsListResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.getGhostPosts(userId, accessToken, options, fields);
+	}
+
+	const fieldList = (fields ?? USER_THREADS_FIELDS).join(",");
+	const url = new URL(`${THREADS_API_BASE_URL}/${userId}/ghost_posts`);
+	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 ghost posts (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/getLocation.ts

@@ -0,0 +1,38 @@
+import { LOCATION_FIELDS, THREADS_API_BASE_URL } from "../constants.ts";
+import type { ThreadsLocation } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Retrieves information about a specific location.
+ *
+ * @param locationId - The ID of the location
+ * @param accessToken - The access token for authentication
+ * @param fields - Optional array of fields to return
+ * @returns A Promise that resolves to the ThreadsLocation object
+ * @throws Will throw an error if the API request fails
+ */
+export async function getLocation(
+	locationId: string,
+	accessToken: string,
+	fields?: string[],
+): Promise<ThreadsLocation> {
+	const api = getAPI();
+	if (api) {
+		return api.getLocation(locationId, accessToken, fields);
+	}
+
+	const fieldList = (fields ?? LOCATION_FIELDS).join(",");
+	const url = new URL(`${THREADS_API_BASE_URL}/${locationId}`);
+	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 get location (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/getMediaInsights.ts

@@ -0,0 +1,39 @@
+import { THREADS_API_BASE_URL } from "../constants.ts";
+import type { MediaInsightsResponse } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Retrieves insight metrics for a specific Threads media object.
+ *
+ * Available metrics: views, likes, replies, reposts, quotes, shares
+ *
+ * @param mediaId - The ID of the Threads media object
+ * @param accessToken - The access token for authentication
+ * @param metrics - Array of metric names to retrieve
+ * @returns A Promise that resolves to the MediaInsightsResponse
+ * @throws Will throw an error if the API request fails
+ */
+export async function getMediaInsights(
+	mediaId: string,
+	accessToken: string,
+	metrics: string[],
+): Promise<MediaInsightsResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.getMediaInsights(mediaId, accessToken, metrics);
+	}
+
+	const url = new URL(`${THREADS_API_BASE_URL}/${mediaId}/insights`);
+	url.searchParams.append("metric", metrics.join(","));
+	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 get media insights (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/getMentions.ts

@@ -0,0 +1,57 @@
+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,
+	"alt_text",
+	"link_attachment_url",
+	"poll_attachment",
+];
+
+/**
+ * Retrieves a list of posts where the user is mentioned.
+ *
+ * @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 getMentions(
+	userId: string,
+	accessToken: string,
+	options?: PaginationOptions,
+	fields?: string[],
+): Promise<ThreadsListResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.getMentions(userId, accessToken, options, fields);
+	}
+
+	const fieldList = (fields ?? DEFAULT_FIELDS).join(",");
+	const url = new URL(`${THREADS_API_BASE_URL}/${userId}/mentions`);
+	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 mentions (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/getOEmbed.ts

@@ -0,0 +1,41 @@
+import { THREADS_API_BASE_URL } from "../constants.ts";
+import type { OEmbedResponse } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Retrieves oEmbed HTML for a Threads post.
+ *
+ * @param accessToken - The access token for authentication
+ * @param postUrl - The URL of the Threads post to embed
+ * @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,
+	maxWidth?: number,
+): Promise<OEmbedResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.getOEmbed(accessToken, postUrl, maxWidth);
+	}
+
+	const url = new URL(`${THREADS_API_BASE_URL}/oembed`);
+	url.searchParams.append("url", postUrl);
+	url.searchParams.append("access_token", accessToken);
+
+	if (maxWidth !== undefined) {
+		url.searchParams.append("maxwidth", maxWidth.toString());
+	}
+
+	const response = await fetch(url.toString());
+	if (!response.ok) {
+		const errorBody = await response.text();
+		throw new Error(
+			`Failed to get oEmbed (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/getProfile.ts

@@ -0,0 +1,46 @@
+import { THREADS_API_BASE_URL } from "../constants.ts";
+import type { ThreadsProfile } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+const DEFAULT_FIELDS = [
+	"id",
+	"username",
+	"name",
+	"threads_profile_picture_url",
+	"threads_biography",
+	"is_verified",
+	"recently_searched_keywords",
+];
+
+/**
+ * Retrieves profile information for a Threads user.
+ *
+ * @param userId - The user ID (or "me" for the authenticated user)
+ * @param accessToken - The access token for authentication
+ * @param fields - Optional array of fields to return
+ * @returns A Promise that resolves to the ThreadsProfile object
+ * @throws Will throw an error if the API request fails
+ */
+export async function getProfile(
+	userId: string,
+	accessToken: string,
+	fields?: string[],
+): Promise<ThreadsProfile> {
+	const api = getAPI();
+	if (api) {
+		return api.getProfile(userId, accessToken, fields);
+	}
+
+	const fieldList = (fields ?? DEFAULT_FIELDS).join(",");
+	const url = new URL(`${THREADS_API_BASE_URL}/${userId}`);
+	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 get profile (${response.status}): ${errorBody}`);
+	}
+
+	return await response.json();
+}

package/src/api/getProfilePosts.ts

@@ -0,0 +1,53 @@
+import { THREADS_API_BASE_URL, USER_THREADS_FIELDS } from "../constants.ts";
+import type { PaginationOptions, ThreadsListResponse } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+const DEFAULT_FIELDS = USER_THREADS_FIELDS.filter((f) => f !== "owner");
+
+/**
+ * Retrieves posts from a public Threads profile by username.
+ *
+ * @param accessToken - The access token for authentication
+ * @param username - The exact username whose posts to retrieve
+ * @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 getProfilePosts(
+	accessToken: string,
+	username: string,
+	options?: PaginationOptions,
+	fields?: string[],
+): Promise<ThreadsListResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.getProfilePosts(accessToken, username, options, fields);
+	}
+
+	const fieldList = (fields ?? DEFAULT_FIELDS).join(",");
+	const url = new URL(`${THREADS_API_BASE_URL}/profile_posts`);
+	url.searchParams.append("username", username);
+	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 profile posts (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}

package/src/api/getPublishingLimit.ts

@@ -0,0 +1,59 @@
+import { THREADS_API_BASE_URL } from "../constants.ts";
+import type { PublishingLimit } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+const DEFAULT_FIELDS = [
+	"quota_usage",
+	"config",
+	"reply_quota_usage",
+	"reply_config",
+	"delete_quota_usage",
+	"delete_config",
+	"location_search_quota_usage",
+	"location_search_config",
+];
+
+/**
+ * Retrieves the current publishing rate limit usage for a user.
+ *
+ * @param userId - The user ID of the Threads account
+ * @param accessToken - The access token for authentication
+ * @param fields - Optional array of fields to return (defaults to all quota fields)
+ * @returns A Promise that resolves to the rate limit usage information
+ * @throws Will throw an error if the API request fails
+ * @example
+ * ```typescript
+ * const rateLimit = await getPublishingLimit("123456", "your_access_token");
+ * console.log(`Current usage: ${rateLimit.quota_usage}`);
+ * ```
+ */
+export async function getPublishingLimit(
+	userId: string,
+	accessToken: string,
+	fields?: string[],
+): Promise<PublishingLimit> {
+	const api = getAPI();
+	if (api) {
+		return api.getPublishingLimit(userId, accessToken, fields);
+	}
+	const fieldList = (fields ?? DEFAULT_FIELDS).join(",");
+	const url = new URL(
+		`${THREADS_API_BASE_URL}/${userId}/threads_publishing_limit`,
+	);
+	url.searchParams.append("access_token", accessToken);
+	url.searchParams.append("fields", fieldList);
+
+	const response = await fetch(url.toString());
+	if (!response.ok) {
+		const errorBody = await response.text();
+		throw new Error(
+			`Failed to get publishing limit (${response.status}): ${errorBody}`,
+		);
+	}
+
+	const data = await response.json();
+	if (!data.data?.[0]) {
+		throw new Error("No publishing limit data returned");
+	}
+	return data.data[0];
+}

package/src/api/getReplies.ts

@@ -0,0 +1,51 @@
+import { REPLY_FIELDS, THREADS_API_BASE_URL } from "../constants.ts";
+import type { CursorPaginationOptions, ThreadsListResponse } from "../types.ts";
+import { getAPI } from "../utils/getAPI.ts";
+
+/**
+ * Retrieves replies to a specific Threads media object.
+ *
+ * @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)
+ * @returns A Promise that resolves to the ThreadsListResponse
+ * @throws Will throw an error if the API request fails
+ */
+export async function getReplies(
+	mediaId: string,
+	accessToken: string,
+	options?: CursorPaginationOptions,
+	fields?: string[],
+	reverse?: boolean,
+): Promise<ThreadsListResponse> {
+	const api = getAPI();
+	if (api) {
+		return api.getReplies(mediaId, accessToken, options, fields, reverse);
+	}
+
+	const fieldList = (fields ?? REPLY_FIELDS).join(",");
+	const url = new URL(`${THREADS_API_BASE_URL}/${mediaId}/replies`);
+	url.searchParams.append("fields", fieldList);
+	url.searchParams.append("access_token", accessToken);
+
+	if (reverse !== undefined) {
+		url.searchParams.append("reverse", String(reverse));
+	}
+
+	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 replies (${response.status}): ${errorBody}`,
+		);
+	}
+
+	return await response.json();
+}