TypeScript SDK

Install and use the official TypeScript SDK — Result handling, unwrap, and route mapping

Install

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.

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 };

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

Quickstart — env setup, first request, response envelope.
This page — Result handling and unwrap().
API reference — params and schemas.
Errors and Credits — runtime behavior.

Quickstart

Authenticate, make a first platform request, and choose between raw HTTP and SDK paths.

API reference

See the exact routes, parameters, and response schemas behind SDK methods.

Errors

HTTP error handling, outcome semantics, and retry guidance still apply to SDK users.

npm package

Published package metadata and install source on npm.

Quickstart

API reference

Errors

npm package

On this page