@socialfetch/sdk

@socialfetch/sdk

Official TypeScript SDK for the Social Fetch public HTTP API. Call /v1 endpoints with typed methods; responses use a lightweight Result (ok / err) so expected API failures are data, not thrown exceptions.

Resources

Resource	Link
Product	socialfetch.dev
Documentation	socialfetch.dev/docs
Dashboard & API keys	app.socialfetch.dev
Issues & support	github.com/social-freak-ltd/socialfetch-sdk

For questions or problems with the API or this package, open an issue or contact support@socialfetch.dev.

Install

npm install @socialfetch/sdk

pnpm add @socialfetch/sdk

yarn add @socialfetch/sdk

Requirements

• Node.js 18+ with a global fetch (the client also accepts a custom fetch implementation).
• ESM-only package. Use import rather than require().

Quick start

Create a client with your API key from the dashboard. The package wraps the documented public routes: top-level health() and ask(), plus auth, billing, facebook, tiktok, twitter, instagram, linkedin, spotify, web, youtube, and other platform resources. Use the documentation and API reference when you need exact route coverage or raw HTTP details.

import { SocialFetchClient, unwrap } from "@socialfetch/sdk";

const client = new SocialFetchClient({
	apiKey: process.env.SOCIALFETCH_API_KEY!,
});

const whoami = await client.auth.whoami();
if (!whoami.ok) {
	console.error(whoami.error.code, whoami.error.requestId);
} else {
	console.log(whoami.value.data.user);
}

// Optional: throw on failure (unexpected errors can still throw)
const profile = unwrap(
	await client.tiktok.getProfile({ handle: "charlidamelio" }),
	await client.github.getProfile({ handle: "torvalds" }),
	await client.github.listProfileRepositories({ handle: "torvalds" }),
	await client.github.getRepository({
		url: "https://github.com/torvalds/linux",
	}),
);

Exported endpoint types

The SDK exports request and response types for the current public methods, so consumers can reuse the official shapes directly from @socialfetch/sdk instead of recreating mirror interfaces in their own code.

Common root exports include auth and billing responses such as WhoamiResponse and BalanceResponse, plus resource-specific aliases such as InstagramProfileResponse, TikTokVideoCommentsResponse, TikTokProfileShowcaseProductsResponse, TikTokShopProductSearchResponse, TikTokShopProductsResponse, ListShopProductsParams, TwitterProfileTweetsResponse, FacebookPostTranscriptResponse, WebSearchResponse, and YouTubeVideoResponse.

For example, if you're working with Instagram profile routes you can import both the params and response types directly from @socialfetch/sdk:

import type {
	GetInstagramProfileParams,
	InstagramProfileResponse,
} from "@socialfetch/sdk";

const params: GetInstagramProfileParams = {
	handle: "instagram",
};

function renderProfile(response: InstagramProfileResponse) {
	return response.data.username;
}

Auth and billing responses are also available from the package root:

import type { BalanceResponse, WhoamiResponse } from "@socialfetch/sdk";

function formatAccountSummary(
	whoami: WhoamiResponse,
	balance: BalanceResponse,
) {
	return {
		userId: whoami.data.user.id,
		remainingCredits: balance.data.balance,
	};
}

This applies across the SDK for other exported endpoint shapes too, including platform-specific request params, response payloads, and shared error/result types.

Useful shared exports include:

• Result<T, E> plus ok() / err() for Result-style control flow.
• ExtractResultValue<R> and ExtractResultError<R> for deriving the success or error side from a result-returning SDK method.
• SocialFetchSdkError for the normalized SDK error shape.
• PublicApiErrorCode and PUBLIC_API_ERROR_CODES for working with stable API error codes.
• isSocialFetchSdkError for narrowing unknown caught values.
• SocialFetchUnwrapError when using unwrap() in try / catch.
• SocialFetchClientConfig and HealthResponse for client setup and health checks.

Result pattern example

If you want to keep expected failures as data instead of throwing, annotate your application helpers with the SDK's exported Result and error types:

import type {
	GetInstagramProfileParams,
	InstagramProfileResponse,
	Result,
	SocialFetchSdkError,
} from "@socialfetch/sdk";
import { SocialFetchClient } from "@socialfetch/sdk";

const client = new SocialFetchClient({
	apiKey: process.env.SOCIALFETCH_API_KEY!,
});

async function loadInstagramProfile(
	params: GetInstagramProfileParams,
): Promise<Result<InstagramProfileResponse, SocialFetchSdkError>> {
	return client.instagram.getProfile(params);
}

Result type extraction example

If you want to derive types from SDK methods directly, use ExtractResultValue<R> and ExtractResultError<R>. They accept the method's ReturnType and handle the async Promise<Result<...>> shape for you:

import type {
	ExtractResultError,
	ExtractResultValue,
	SocialFetchClient,
} from "@socialfetch/sdk";

export type SocialFetchTikTokVideoResponse = ExtractResultValue<
	ReturnType<SocialFetchClient["tiktok"]["getVideo"]>
>;

export type SocialFetchTikTokVideoError = ExtractResultError<
	ReturnType<SocialFetchClient["tiktok"]["getVideo"]>
>;

Error handling example

You can branch on the normalized error shape without inventing your own error interface:

import {
	PUBLIC_API_ERROR_CODES,
	type SocialFetchSdkError,
} from "@socialfetch/sdk";

function getRetryMessage(error: SocialFetchSdkError) {
	if (error.kind === "api") {
		const isKnownCode = (PUBLIC_API_ERROR_CODES as readonly string[]).includes(
			error.code,
		);

		if (isKnownCode && error.code === "temporarily_unavailable") {
			return `The API is temporarily unavailable. Request ID: ${error.requestId}`;
		}
	}

	if (error.kind === "client" && error.code === "network_error") {
		return "Network error. Please try again.";
	}

	return error.message;
}

unwrap() example

If you prefer thrown errors at your application boundary, catch SocialFetchUnwrapError and read the typed detail field:

import {
	SocialFetchClient,
	SocialFetchUnwrapError,
	unwrap,
} from "@socialfetch/sdk";

const client = new SocialFetchClient({
	apiKey: process.env.SOCIALFETCH_API_KEY!,
});

try {
	const profile = unwrap(
		await client.instagram.getProfile({ handle: "instagram" }),
	);

	console.log(profile.data.username);
} catch (error) {
	if (error instanceof SocialFetchUnwrapError) {
		console.error(error.detail.code, error.detail.requestId);
	}
}

Configuration

• apiKey (required) — API key from the dashboard, sent as the x-api-key header.
• baseUrl (optional) — API origin without a trailing path, e.g. https://api.socialfetch.dev. Defaults to production.
• fetch (optional) — Custom fetch implementation for custom Node.js and test environments.

The client sends its package version in the User-Agent header (for example socialfetch-typescript-sdk/0.13.0) so Social Fetch can measure SDK adoption and support compatibility. This is not separate telemetry — it is part of normal API requests.

When your installed SDK is behind the version bundled with the API deployment you are calling, responses may include:

• X-SocialFetch-SDK-Latest — recommended TypeScript SDK version for that API
• X-SocialFetch-SDK-Update: recommended — upgrade when convenient (requests are not blocked)

Compare with SDK_VERSION from @socialfetch/sdk/version, or check npm releases and the SDK changelog.

Errors

On err, the SDK exposes structured fields such as code, requestId, and HTTP metadata where applicable. See the docs for error semantics and retry guidance. You can also import PUBLIC_API_ERROR_CODES and isSocialFetchSdkError for typed handling.