TypeScript SDK

Install and use the official TypeScript SDK for Social Fetch with a concrete method inventory, route mapping, unwrap guidance, and parity with documented public routes

Install

The package is published on npm as @socialfetch/sdk.

$npm install @socialfetch/sdk

Requirements

Node.js 18+
A Social Fetch API key (sfk_...) — API Keys

Quick start

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

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

const result = await client.tiktok.getProfile({ handle: "charlidamelio" });

if (!result.ok) {
  console.error(result.error.code, result.error.requestId);
  return;
}

console.log(result.value.data.profile);

Client configuration

Most integrations only need apiKey:

apiKey — required, sent as the x-api-key header

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

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

Advanced options like baseUrl and fetch exist for tests and custom environments, but most integrations only need apiKey.

Result handling

SDK methods return a Result instead of throwing for expected API failures:

type Result<T, E> =
  | { ok: true; value: T }
  | { ok: false; error: E };

That means your normal flow can branch on result.ok:

const result = await client.tiktok.getProfile({ handle: "charlidamelio" });

if (!result.ok) {
  console.error(result.error.code, result.error.requestId);
} else {
  console.log(result.value.data.profile);
}

`unwrap()` and thrown failures

If you prefer exception-style control flow, import unwrap():

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

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

try {
  const tweets = unwrap(
    await client.twitter.getProfileTweets({ handle: "elonmusk" })
  );

  console.log(tweets.data.tweets);
} catch (error) {
  if (error instanceof SocialFetchUnwrapError) {
    console.error(error.error.code, error.error.requestId);
  } else {
    throw error;
  }
}

unwrap() returns result.value on success and throws SocialFetchUnwrapError on SDK/API failures.

Error handling

The SDK uses SocialFetchSdkError, which has two categories:

kind: "api" — normalized public API errors such as unauthorized, insufficient_credits, or temporarily_unavailable
kind: "client" — local/runtime failures such as network_error, parse_error, or invalid_response

You can also import:

PUBLIC_API_ERROR_CODES
isSocialFetchSdkError()

Important

The SDK keeps the same API semantics. A route can return HTTP 200 and still resolve to not_found or private, so check fields like lookupStatus when the route provides them.

After `result.ok`

Handle SDK/API errors first, then inspect result.value.data:

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

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

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

if (!profile.ok) {
  // 401, 402, 503, parse errors, etc.
  console.error(profile.error.code, profile.error.requestId);
  return;
}

switch (profile.value.data.lookupStatus) {
  case "found":
    // use profile.value.data.profile / metrics
    break;
  case "private":
  case "not_found":
    // still HTTP 200 from the API — handle without treating as SDK failure
    break;
}

Some list routes omit lookupStatus and can return empty arrays for more than one reason. See Errors.

Recommended workflow

Start with Quickstart for environment setup, your first request, and the response-envelope basics.
Use this page for Result handling and unwrap().
Use the API reference for exact params and schemas.
Use Errors and Credits for runtime behavior.

Install

Requirements

Quick start

Client configuration

Result handling

`unwrap()` and thrown failures

Error handling

After `result.ok`

Recommended workflow

Quickstart

API reference

Errors

npm package

On this page