If you are integrating Social Fetch from TypeScript, you should not have to choose between typed code and the same boring API semantics we document everywhere else. The official @socialfetch/sdk package gives you method names that map back to public routes, typed responses, and one failure model you can branch on without parsing raw HTTP by hand.

Install it, create a client, and make the same platform calls you would make over REST:

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

Why use the SDK?

The SDK is for teams that want the documented Social Fetch API, but with TypeScript doing more of the remembering:

• Route-aligned methods — client.tiktok.getProfile({ handle }), client.instagram.getPost({ url }), client.auth.whoami(), and the rest of the current SDK surface map back to documented HTTP routes.
• Typed Result handling — expected API and runtime failures return { ok: false, error }, so your code can branch without every integration becoming a try/catch maze.
• The same envelope — successful calls still return data and meta, including requestId, creditsCharged where relevant, and version.
• No client-side secrets — keep using it from your backend, worker, or server process. API keys still belong outside browser bundles.

That last point matters. The SDK is not a new product surface with different rules. It is a TypeScript-shaped path through the same API.

Result first, data second

SDK methods return a Result, not a thrown exception, for expected failures:

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

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

console.log(tweets.value.data.tweets);

This keeps the failure path close to the call site. You can log requestId, branch on error.code, and decide whether the job should retry, skip, or surface a support-friendly message.

Prefer exceptions? Use unwrap()

Some codebases prefer exception-style control flow. For that, import unwrap():

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.profile);
} catch (error) {
  if (error instanceof SocialFetchUnwrapError) {
    console.error(error.error.code, error.error.requestId);
    return;
  }

  throw error;
}

Use whichever style fits your app. The important part is that SDK failures still carry normalized Social Fetch error details.

HTTP status is not the whole story

The SDK preserves API semantics. Some lookups can succeed at the transport level and still tell you the thing was not_found, private, or otherwise unavailable in data.lookupStatus.

That means the normal shape is:

1. Check result.ok for SDK/API failure.
2. Inspect result.value.data for the route outcome.
3. Log result.value.meta.requestId when something needs debugging.

For example, a profile lookup can return a successful response where your next branch is still about lookupStatus. Treat that as domain data, not an SDK exception.

Where to go next

Start with the TypeScript SDK guide for installation, Result, and unwrap(). Keep the SDK reference open when you need the exact method inventory, and use the API reference when you want the route-level schema behind a method.

If you are wiring Social Fetch for the first time, use Quickstart for auth and the first request, Errors for retry and outcome semantics, and Pricing when you estimate volume.

Typed client, same envelope, fewer surprises.