> ## Documentation Index
> Fetch the complete documentation index at: https://docs.so-me.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Overview

> Embed Social media studio social account connections and post scheduling in your application

`@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.

<Warning>
  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.
</Warning>

<Note>
  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.
</Note>

## 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

<CodeGroup>
  ```bash npm theme={null}
  npm install @social-media-scheduler/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @social-media-scheduler/sdk
  ```

  ```bash yarn theme={null}
  yarn add @social-media-scheduler/sdk
  ```
</CodeGroup>

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

## Initialize the client

```ts theme={null}
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:

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

## End-to-end flow

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

```ts theme={null}
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.
```

<CardGroup cols={2}>
  <Card title="Connect accounts" icon="link" href="/sdk/connect-accounts">
    Create end users and run the hosted OAuth flow.
  </Card>

  <Card title="Publish posts" icon="paper-plane" href="/sdk/posts-and-media">
    Publish immediately, schedule posts, and upload media.
  </Card>

  <Card title="Receive webhooks" icon="webhook" href="/sdk/webhooks">
    Verify signed delivery payloads and handle retries safely.
  </Card>

  <Card title="Secure the integration" icon="shield" href="/sdk/security-and-errors">
    Protect partner keys and handle API failures.
  </Card>
</CardGroup>