<p align="center">
<a href="https://social-sdk.dev"><img alt="Social SDK: one typed call, every platform. Bluesky, Instagram, LinkedIn, Threads, TikTok, X, and YouTube wired to one client." src=".github/assets/readme-banner.png" width="100%" /></a>
</p>
<p align="center">
<a href="https://github.com/opencoredev/social-sdk/stargazers"><img alt="GitHub stars" src="https://shieldcn.dev/github/opencoredev/social-sdk/stars.svg?variant=branded&mode=dark" /></a>
<a href="https://x.com/leodev"><img alt="Follow @leodev on X" src="https://shieldcn.dev/x/follow/leodev.svg?variant=branded&mode=dark" /></a>
</p>
Social SDK is an open-source TypeScript toolkit for solo founders and small teams adding social features to their apps. Publish, read, and access analytics or comments where available across X, Threads, Bluesky, YouTube, TikTok, Instagram, and LinkedIn through a typed interface.
Choose direct platform access or a managed backend: Zernio, Post for Me, PostFast, Postiz, or Buffer.
[Start with the quickstart](https://social-sdk.dev/docs/getting-started/mock-quickstart) · [Install from npm](https://social-sdk.dev/docs/getting-started/installation)
- Direct adapters for Bluesky, Instagram, LinkedIn, Threads, TikTok, X, and YouTube
- Optional managed backends for Zernio, Post for Me, PostFast, Postiz, and Buffer
- Typed capability manifests and platform-native operations behind explicit subpath imports
- Independent per-destination outcomes for complete, processing, uncertain, and failed work
- A deterministic mock backend for local development and contract tests
- A CLI for adapter discovery, capability checks, diagnostics, and request validation that never contacts a social platform
## Install
Social SDK runs in trusted server-side code on Node.js 22.12+ or Bun. Keep platform tokens, managed-provider keys, OAuth secrets, and webhook secrets out of browser bundles.
```bash
npm install @opencoredev/social-sdk
# or
bun add @opencoredev/social-sdk
```
For application setup and integration options, see the [installation guide](https://social-sdk.dev/docs/getting-started/installation).
## Usage
Start with the mock backend to verify an integration without credentials, platform calls, or billable provider requests:
```ts
import { createSocial, connectedAccountRef } from "@opencoredev/social-sdk";
import { mockBackend } from "@opencoredev/social-sdk/testing";
const social = createSocial({
backend: mockBackend({ scenario: "immediate-text-success" }),
});
const result = await social.posts.publish({
targets: [
{
account: connectedAccountRef({
backend: "default",
platform: "x",
accountId: "mock-account-1",
}),
},
],
content: { text: "Hello from Social SDK" },
idempotencyKey: "quickstart-1",
});
console.log(result.status, result.outcomes[0]?.state);
// complete published
```
The same client shape works with a direct platform adapter or a managed backend. Import only the adapter you use from its documented subpath.
## Platforms and backends
Direct platform adapters cover Bluesky, Instagram, LinkedIn, Threads, TikTok, X, and YouTube. Hosted execution routes are available through the [Zernio](https://social-sdk.dev/docs/backends/zernio), [Post for Me](https://social-sdk.dev/docs/backends/post-for-me), [PostFast](https://social-sdk.dev/docs/backends/postfast), [Postiz](https://social-sdk.dev/docs/backends/postiz), and [Buffer](https://social-sdk.dev/docs/backends/buffer) adapters. Managed services are optional; a direct integration does not require a Social SDK account.
Read the [platform capability matrix](https://social-sdk.dev/docs/reference/capabilities) before choosing an adapter. It describes the normalized operations implemented by each integration and does not replace provider permissions, account eligibility, or live verification.
## CLI
The `social-sdk` CLI never contacts a social platform. It does not authenticate accounts, upload media, or publish content. It sends one anonymous usage event per command (command, adapter, SDK version, runtime and OS) after a one-time notice; turn that off with `social-sdk telemetry disable`, `SOCIAL_SDK_TELEMETRY_DISABLED=1` or `DO_NOT_TRACK=1`. It is always off in CI. See [CLI telemetry](https://social-sdk.dev/docs/reference/telemetry). The SDK library sends no telemetry.
The package installs the binary into your project's `node_modules/.bin`, which is not on your shell `PATH`. After installing `@opencoredev/social-sdk`, run it from that project directory with `npm exec`, or replace `npm exec --` with `bun run` under Bun:
```bash
npm exec -- social-sdk adapters --json
npm exec -- social-sdk capabilities --adapter youtube --json
npm exec -- social-sdk doctor --adapter zernio --json
npm exec -- social-sdk examples --json
npm exec -- social-sdk validate --adapter mock --file request.json --json
```
See the [CLI reference](https://social-sdk.dev/docs/reference/cli) for command output, validation limits, and exit codes.
## Documentation
Full documentation lives at **[social-sdk.dev/docs](https://social-sdk.dev/docs)**. Good places to start:
- [Installation](https://social-sdk.dev/docs/getting-started/installation)
- [Mock quickstart](https://social-sdk.dev/docs/getting-started/mock-quickstart)
- [Choose an integration](https://social-sdk.dev/docs/getting-started/choose-an-integration)
- [Publish content](https://social-sdk.dev/docs/publishing)
- [Handle outcomes and reconciliation](https://social-sdk.dev/docs/concepts/references-and-outcomes)
## Guides
[Guides](https://social-sdk.dev/guides) on how each platform's API works, with sources and tested TypeScript examples:
- [Facebook Page access tokens, explained](https://social-sdk.dev/guides/facebook-page-access-token)
- [Ayrshare alternatives for developers](https://social-sdk.dev/guides/ayrshare-alternatives)
- [The YouTube upload API, explained](https://social-sdk.dev/guides/youtube-upload-api)
- [The LinkedIn Posts API, explained](https://social-sdk.dev/guides/linkedin-posts-api)
- [Social media APIs for developers](https://social-sdk.dev/guides/social-media-apis)
- [The Buffer API, explained](https://social-sdk.dev/guides/buffer-api)
- [X API pricing, explained](https://social-sdk.dev/guides/x-api-pricing)
- [The Bluesky API, explained](https://social-sdk.dev/guides/bluesky-api)
- [The Threads API, explained](https://social-sdk.dev/guides/threads-api)
## Sponsors
Social SDK is supported by companies that help keep platform integrations practical and maintained. Want your logo here? **[Become a sponsor →](https://github.com/sponsors/opencoredev)**
- [PostFast](https://postfa.st/docs?utm_source=social-sdk&utm_medium=sponsor&utm_campaign=hosted-backend), social media scheduling with a public API
- [Postiz](https://postiz.com/?utm_source=socialsdk), open-source social media scheduling, hosted or self-hosted
<p align="center">
<a href="https://github.com/sponsors/opencoredev">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="https://shieldcn.dev/sponsors/opencoredev.svg?title=false&mode=dark&preset=surface" />
<source media="(prefers-color-scheme: light)" srcset="https://shieldcn.dev/sponsors/opencoredev.svg?title=false&mode=light&preset=surface" />
<img alt="Social SDK sponsors" src="https://shieldcn.dev/sponsors/opencoredev.svg?title=false&mode=dark&preset=surface" width="820" />
</picture>
</a>
</p>
<p align="center"><sub><a href="./LICENSE">MIT License</a> · Built by <a href="https://x.com/leodev">@leodev</a></sub></p>