# Social SDK

> Typed social platform integrations for TypeScript applications, with direct routes, optional managed backends, and deterministic testing.

## When to use Social SDK

Use Social SDK when server-side TypeScript or JavaScript code (Node.js 22.12+ or Bun) needs to:

- Publish text, images, or video to Bluesky, Instagram, LinkedIn, Threads, TikTok, X, or YouTube through one typed client.
- Read posts, post metrics, search results, the social graph, notifications, or analytics reports from those platforms.
- Handle comments, direct messages, and verified platform webhooks.
- Send the same calls through the Zernio or Post for Me managed backends instead of each platform's API.
- Build and test a social feature offline with a deterministic mock backend, without credentials or billable calls.

It is not the right tool for browser-only code (credentials must stay on a server), for a hosted scheduler or dashboard (Social SDK is a library with no hosted service), or for accounts your application is not authorized to act for.

## How an agent should use it

1. Install the package: `npm install @opencoredev/social-sdk` or `bun add @opencoredev/social-sdk`.
2. Start with `mockBackend` from `@opencoredev/social-sdk/testing`, following the [Quickstart](https://social-sdk.dev/docs/getting-started/mock-quickstart).
3. Import only the adapters you need from their subpaths, such as `@opencoredev/social-sdk/x` or `@opencoredev/social-sdk/cloud/zernio`. Check an operation against the [capability matrix](https://social-sdk.dev/docs/reference/capabilities) before calling it.
4. Treat each target's outcome separately. A processing or uncertain outcome is not a published post.
5. Use the offline CLI to discover adapters and validate requests without network calls: `npx @opencoredev/social-sdk adapters --json` or `npx @opencoredev/social-sdk validate --adapter mock --file request.json --json`. See the [CLI reference](https://social-sdk.dev/docs/reference/cli).
6. Follow [Integrate with an agent](https://social-sdk.dev/docs/agents/integrate-social-sdk) and the [integration checklist](https://social-sdk.dev/docs/agents/integration-checklist) for connections, tenant authorization, and webhooks.

## Packages and source

- [npm package](https://www.npmjs.com/package/@opencoredev/social-sdk): `@opencoredev/social-sdk`, including the `social-sdk` CLI.
- [Source on GitHub](https://github.com/opencoredev/social-sdk): MIT-licensed source, issues, and changelog.

## Docs

- [Overview](https://social-sdk.dev/docs): Add typed social platform features to a TypeScript application through direct integrations or optional managed backends.
- [Installation](https://social-sdk.dev/docs/getting-started/installation): Install Social SDK, keep credentials server-side, and select only the integration modules your application uses.
- [Quickstart](https://social-sdk.dev/docs/getting-started/mock-quickstart): Build and verify your first Social SDK flow without credentials, platform calls, or billable provider requests.
- [Choose an integration](https://social-sdk.dev/docs/getting-started/choose-an-integration): Decide between direct integrations, managed backends, and an explicit mixed-backend setup for your application.

## Platforms

- [Platforms](https://social-sdk.dev/docs/platforms): Compare the social operations, content formats, permissions, and evidence available through each direct platform adapter.
- [X](https://social-sdk.dev/docs/platforms/x): Publish and read X posts with existing user authorization, explicit media limits, native references, and uncertain-write reconciliation.
- [Threads](https://social-sdk.dev/docs/platforms/threads): Publish Threads containers, carousels, and media while preserving processing outcomes for explicit reconciliation.
- [Bluesky](https://social-sdk.dev/docs/platforms/bluesky): Connect Bluesky accounts with AT Protocol OAuth, publish records, and use typed AT Protocol operations with explicit reconciliation.
- [YouTube](https://social-sdk.dev/docs/platforms/youtube): Upload a video to a selected YouTube channel with explicit audience, visibility, media processing, and reconciliation fields.
- [TikTok](https://social-sdk.dev/docs/platforms/tiktok): Prepare TikTok creator choices and publish verified media URLs with Social SDK, covering consent, privacy settings, drafts, and processing checks.
- [Instagram](https://social-sdk.dev/docs/platforms/instagram): Publish Instagram professional-account media and use typed native Reels, Stories, hashtag, limit, and mention operations.
- [LinkedIn](https://social-sdk.dev/docs/platforms/linkedin): Publish as an explicit LinkedIn author while preserving native URNs, permissions, image, video, and document processing states, comments, and metrics.

### Hosted platforms

- [Hosted platforms](https://social-sdk.dev/docs/backends): Compare Zernio and Post for Me as hosted execution routes, including supported operations, platform coverage, webhooks, and pricing.
- [Zernio](https://social-sdk.dev/docs/backends/zernio): Configure the Zernio managed backend with server credentials, explicit accounts, outcomes, and HMAC webhook verification.
- [Post for Me](https://social-sdk.dev/docs/backends/post-for-me): Configure Post for Me with server credentials, account-scoped publishing, feed analytics, and shared-secret webhooks.

## Integrations

- [Integrations](https://social-sdk.dev/docs/integrations): Use Social SDK with web frameworks, databases, and job runners such as Next.js, Hono, Supabase, SurrealDB, and Inngest.

### Frameworks

- [Next.js](https://social-sdk.dev/docs/integrations/nextjs): Publish to social platforms from Next.js App Router route handlers and server actions with Social SDK, with raw-body webhook verification.
- [TanStack Start](https://social-sdk.dev/docs/integrations/tanstack-start): Publish to social platforms from TanStack Start server functions and API routes with Social SDK, keeping credentials in server-only code.
- [Express](https://social-sdk.dev/docs/integrations/express): Publish to social platforms from Express routes and verify webhooks against the raw request body with Social SDK.
- [Hono](https://social-sdk.dev/docs/integrations/hono): Publish to social platforms from Hono routes on Node or Bun using web-standard Request and Response with Social SDK.
- [Elysia](https://social-sdk.dev/docs/integrations/elysia): Publish to social platforms from Elysia routes on Bun or Node using web-standard Request and Response with Social SDK.
- [NestJS](https://social-sdk.dev/docs/integrations/nestjs): Provide the Social SDK client through NestJS dependency injection, publish from services, and verify webhooks with a raw-body controller.

### Databases

- [Convex](https://social-sdk.dev/docs/integrations/convex): Publish to social platforms from Convex actions and store connections, deliveries, and webhook events in Convex tables.
- [Supabase](https://social-sdk.dev/docs/integrations/supabase): Store Social SDK connections, delivery outcomes, and webhook events in Supabase Postgres with row-level security.
- [Neon](https://social-sdk.dev/docs/integrations/neon): Run Social SDK inside a Neon Function next to Neon Postgres, and reconcile deliveries on a scheduled Function Trigger.
- [SurrealDB](https://social-sdk.dev/docs/integrations/surrealdb): Keep connected accounts, deliveries, and publish state in SurrealDB, and stream delivery updates to your app with live queries.

### Job runners

- [Trigger.dev](https://social-sdk.dev/docs/integrations/trigger-dev): Run scheduled social publishing and delivery reconciliation as durable Trigger.dev tasks with Social SDK idempotency keys and explicit outcomes.
- [Inngest](https://social-sdk.dev/docs/integrations/inngest): Drive event-based social publishing flows with durable Inngest steps, retries, and Social SDK idempotency keys.
- [Restate](https://social-sdk.dev/docs/integrations/restate): Run each social post as a Restate Virtual Object that journals Social SDK calls, schedules its own reconciliation, and serializes duplicate requests.

## Guides

- [Connect accounts](https://social-sdk.dev/docs/authentication): Separate application credentials, user grants, callbacks, token storage, reconnects, and tenant authorization.
- [Publish content](https://social-sdk.dev/docs/publishing): Prepare text and media, fan out to explicit account targets, and preserve independent destination outcomes through retries and reconciliation.
- [Read posts and analytics](https://social-sdk.dev/docs/reads): Read feeds, single posts, likes, and current post metrics through the normalized API, with platform tabs covering scopes, limits, and native reads.
- [Search posts and actors](https://social-sdk.dev/docs/reads/search): Search posts and actors across provider indexes, with platform-specific scopes, query limits, result fields, and cursor pagination for each supported platform.
- [Social graph](https://social-sdk.dev/docs/reads/graph): Read profiles, followers, and following lists, then follow, block, or mute accounts through the normalized graph API or each platform's native module.
- [Notifications and mentions](https://social-sdk.dev/docs/reads/notifications): Read Bluesky and LinkedIn organization notifications, plus native mention timelines on X, Instagram, and Threads, with cursors and scopes.
- [Analytics reports](https://social-sdk.dev/docs/reads/reports): Read account metrics and native analytics reports for YouTube, X, Bluesky, Threads, Instagram, LinkedIn, and TikTok, with the scopes and limits each one needs.
- [Handle comments and messages](https://social-sdk.dev/docs/comments): List, reply to, and moderate comments, and read and send direct messages, with per-platform examples for X, Bluesky, Threads, YouTube, and more.
- [Process webhooks](https://social-sdk.dev/docs/events): Verify raw webhooks from managed backends and direct platforms, quarantine unmapped tenants, deduplicate events, and process them durably.
- [Mount in your framework](https://social-sdk.dev/docs/getting-started/framework-recipes): Mount the example Request/Response handler in Node, Bun, Next.js App Router, and Hono fetch-based servers with server-side authorization.
- [Integrate the Social SDK](https://social-sdk.dev/docs/agents/integrate-social-sdk): A mock-first integration path for authorized account connections, durable publishing, per-target outcomes, and verified webhook processing.
- [Integration checklist](https://social-sdk.dev/docs/agents/integration-checklist): A safe, mock-first sequence for coding agents that add Social SDK to an existing application and verify the result.

## Concepts

- [Model](https://social-sdk.dev/docs/concepts/integration-model): Understand the four independent concepts that define Social SDK behavior and keep platform routing explicit for every call.
- [Architecture](https://social-sdk.dev/docs/concepts/architecture): Trace backend routing, account grants, per-target publication outcomes, and durable webhook acceptance in one flow.
- [Accounts](https://social-sdk.dev/docs/concepts/accounts): Understand connected accounts in Social SDK, how discovery works, what account references contain, and why ownership mapping stays application data.
- [Authorization](https://social-sdk.dev/docs/concepts/tenant-authorization): Enforce account ownership and server-only credential boundaries when multiple tenants use one application server.
- [Outcomes](https://social-sdk.dev/docs/concepts/references-and-outcomes): Keep account, publication, delivery, native post, schedule, and media identifiers distinct in application code.
- [Capabilities](https://social-sdk.dev/docs/concepts/capabilities): Understand how declared capabilities, content formats, availability states, and evidence levels describe what each Social SDK integration can do.
- [Content](https://social-sdk.dev/docs/concepts/content): Understand shared content, per-target platform options, declared formats, and strict local preparation in Social SDK publish requests.
- [Media](https://social-sdk.dev/docs/concepts/media): Attach images, video, and documents through URLs, blobs, streams, and uploaded references with bounded memory and explicit processing states.
- [Idempotency](https://social-sdk.dev/docs/concepts/idempotency): Use idempotency keys, content fingerprints, and bounded retry budgets so at-least-once schedulers and retries never double-post to a platform.
- [Native access](https://social-sdk.dev/docs/concepts/native-access): Reach platform-specific operations through typed native modules while your application keeps tenant authorization and reconciliation explicit.

## Reference

- [Reference](https://social-sdk.dev/docs/reference): Find the public client, account, publication, delivery outcome, capability, error, and adapter contracts for implementation work.
- [Capability matrix](https://social-sdk.dev/docs/reference/capabilities): Read generated operation declarations for installed Social SDK adapters, including formats, backend routes, and scope guidance.
- [Pagination and iteration](https://social-sdk.dev/docs/reference/pagination): Traverse authorized account pages with query-bound cursors, lazy iteration, cancellation, and explicit page and item limits.
- [Diagnostic CLI](https://social-sdk.dev/docs/reference/cli): Check selected adapter configuration and validate a publish request locally without making network requests or mutating social accounts.
- [Errors](https://social-sdk.dev/docs/reference/errors): Handle every SocialError code with its retry disposition, carried context fields, preparation issues, and redacted JSON serialization.
- [Security](https://social-sdk.dev/docs/reference/security): Credential boundaries, tenant authorization, webhook verification, and redaction rules for Social SDK applications.
- [Operations](https://social-sdk.dev/docs/operations): Configure timeouts, retries, concurrency, rate limits, provider charges, diagnostics, and safe server boundaries.
- [Evidence levels](https://social-sdk.dev/docs/testing/evidence-levels): Read support claims by implementation, contract, live account, approval, and release evidence for each capability.
- [Contributing](https://social-sdk.dev/docs/contributing): Add a social adapter with typed capabilities, contract fixtures, source evidence, and honest verification states.
- [FAQ](https://social-sdk.dev/docs/reference/faq): Common questions about Social SDK hosting, pricing, runtimes, scheduling, live verification, and platform support.

## Agent resources

- [llms-full.txt](https://social-sdk.dev/llms-full.txt): The full Markdown of every page in one file.
- [Page Markdown](https://social-sdk.dev/index.md): Append `.md` to any page URL to fetch that page as raw Markdown.
- [JSON API](https://social-sdk.dev/api/docs/pages.json): Page index of the JSON docs API; each entry links the page's JSON and Markdown forms. Described by the OpenAPI document at https://social-sdk.dev/openapi.json.
- [API catalog](https://social-sdk.dev/.well-known/api-catalog): RFC 9727 linkset of the APIs documented here.
- [agent-readability.json](https://social-sdk.dev/agent-readability.json): Manifest of every agent-facing artifact on this site.
- [Sitemap](https://social-sdk.dev/sitemap.xml): Every indexable page URL with its last-modified date.

## Site

- [Social SDK home](https://social-sdk.dev/): The landing page for the typed social platform toolkit.
- [About](https://social-sdk.dev/about): What Social SDK is, what it is not, and who maintains it.
- [Contact](https://social-sdk.dev/contact): Where to report bugs, ask questions, and raise security issues.
- [Privacy](https://social-sdk.dev/privacy): What the website records and what the SDK never collects.