SDK Overview - Social media studio

@social-media-scheduler/sdk is the server-side TypeScript SDK for platforms that want to offer social account connection and post scheduling to their own customers. Social media studio hosts the OAuth flow and publishing infrastructure while your application keeps ownership of its customer experience.

Partner keys can access every end user in their project. Use the SDK only in trusted server code. Never include a pk_test_ or pk_live_ key in browser, mobile, desktop, or other customer-distributed code.

The Embedded Platform is currently in limited availability, and hosted account connection currently supports Threads. Contact Social media studio to have a partner project and API key provisioned.

SDK versus CLI

Package	Intended user	Credentials	Typical use
`@social-media-scheduler/sdk`	Application developers serving many end users	Partner key (`pk_test_` or `pk_live_`)	Embed connections and scheduling in a product
`@social-media-scheduler/cli`	A direct Social media studio customer	Personal API key (`sk_live_`)	Manage your own organization from a terminal or CI

The packages are independent. Installing the SDK does not install the so-me command, and the CLI does not expose the partner SDK.

Requirements

Node.js 20 or newer
A Social media studio partner project
A test or live partner API key
Every application origin that may receive an OAuth return, registered on the partner project

Install

npm install @social-media-scheduler/sdk

pnpm add @social-media-scheduler/sdk

yarn add @social-media-scheduler/sdk

The SDK ships ESM and CommonJS builds, includes TypeScript declarations, and has no runtime dependencies.

Initialize the client

import { SoMePlatformClient } from "@social-media-scheduler/sdk";

export const soMe = new SoMePlatformClient({
  apiKey: process.env.SOME_PARTNER_API_KEY!,
});

The production API URL defaults to https://api.so-me.studio. You can provide baseUrl for a self-hosted or local environment and customize the 30-second request timeout:

const soMe = new SoMePlatformClient({
  apiKey: process.env.SOME_PARTNER_API_KEY!,
  baseUrl: "http://localhost:8000",
  timeoutMs: 15_000,
});

End-to-end flow

Upsert an end user using the stable customer ID from your database.
Create a short-lived connect session and send its connectUrl to the customer’s browser.
After OAuth completes, retrieve the session or list the customer’s social connections.
Create an immediate or scheduled post using a returned connection ID.
Receive publishing results through signed webhooks.

const customer = await soMe.endUsers.upsert({
  externalId: "customer_123",
  displayName: "Acme",
});

const session = await soMe.connectSessions.create({
  endUserId: customer.id,
  platform: "THREADS",
  returnUrl: "https://app.example.com/settings/social",
});

// Redirect the customer's browser to session.connectUrl.

Connect accounts

Create end users and run the hosted OAuth flow.

Publish posts

Publish immediately, schedule posts, and upload media.

Receive webhooks

Verify signed delivery payloads and handle retries safely.

Secure the integration

Protect partner keys and handle API failures.

​SDK versus CLI

​Requirements

​Install

​Initialize the client

​End-to-end flow

Connect accounts

Publish posts

Receive webhooks

Secure the integration

SDK versus CLI

Requirements

Install

Initialize the client

End-to-end flow