If you are integrating a social media API from a modern Node.js or edge environment, you should not have to choose between strongly typed code and the boring, reliable API semantics we document everywhere else.

The official @socialfetch/sdk package gives you method names that map directly back to our public REST routes, fully typed response objects, and a unified failure model you can branch on without writing raw HTTP fetch wrappers by hand.

Install the package, instantiate the client, and make the same platform calls you normally would:

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) {
  // Gracefully handle expected SDK or API failures
  console.error(result.error.code, result.error.requestId);
  return;
}

// Fully typed autocomplete for the profile payload
console.log(result.value.data.profile);

Why Use a TypeScript SDK for Social Data?

The SDK is designed for engineering teams that want the reliability of the documented Social Fetch API, but with TypeScript doing the heavy lifting of remembering payload shapes and query parameters:

• Route-Aligned Methods — client.tiktok.getProfile({ handle }), client.instagram.getPost({ url }), and the rest of the SDK surface cleanly map back to the documented HTTP routes.
• Typed Result Pattern — Expected API and runtime failures return { ok: false, error }. This means your application code can branch cleanly without every API integration degrading into a massive, nested try/catch maze.
• Consistent Envelopes — Successful calls still return data and meta, preserving access to the crucial requestId, creditsCharged, and version fields for debugging and billing.
• Secure Server-Side Usage — Keep using it from your backend, Cloudflare Worker, or cron job. API keys still belong strictly outside of client browser bundles.

That last point is critical. The SDK is not a fundamentally new product surface with hidden rules; it is simply a TypeScript-native path through our exact same infrastructure.

Result-Based Error Handling

SDK methods return a Result type, rather than throwing exceptions for expected API failures. This keeps the failure path explicitly close to the call site:

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

if (!tweets.ok) {
  // Log the requestId immediately for faster debugging
  console.error("Twitter fetch failed:", tweets.error.code, tweets.error.requestId);
  return;
}

// Safely access the data array
console.log(tweets.value.data.tweets);

By returning a Result, you can log the requestId, branch logically on error.code, and cleanly decide whether your background job should retry, skip the record, or surface a user-friendly message to the frontend.

Prefer Exceptions? Use Unwrap

We know that some codebases are built entirely around exception-style control flow. If you prefer to try/catch everything, import the unwrap() helper:

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) {
    // Still retains the crucial API metadata
    console.error("API Error:", error.error.code, error.error.requestId);
    return;
  }

  // Handle standard JS errors (network failure, etc.)
  throw error;
}

Use whichever style fits your application architecture. The important part is that SDK failures never swallow the normalized Social Fetch error details you need for debugging.

Domain Outcomes vs SDK Exceptions

The TypeScript SDK preserves our core API semantics. Some lookups can succeed perfectly at the transport level, but the domain data tells you the profile was not_found, private, or otherwise unavailable. This is surfaced in data.lookupStatus.

That means the standard consumption pattern is:

1. Check result.ok to catch SDK, network, or strict API failures (like a 401 Unauthorized).
2. Inspect result.value.data.lookupStatus for the actual route outcome (e.g., was the account private?).
3. Log result.value.meta.requestId whenever something needs debugging in the future.

For example, an Instagram profile lookup can return a successful API response where your next logic branch handles the lookupStatus. Treat that as valid domain data, not an SDK exception.

Getting Started with the TypeScript SDK

Ready to drop the SDK into your project?

Start with the TypeScript SDK Guide for installation instructions, Result documentation, and unwrap() details. Keep the SDK Reference open when you need the exact method inventory, and lean on the API Reference when you want to understand the exact route-level schema behind any given method.

If you are wiring up Social Fetch for the very first time, check out the Quickstart for authentication basics, the Errors guide for retry semantics, and Pricing to estimate your monthly volume.

Typed client, same boring envelope, fewer surprises.