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

# Visão geral do SDK

> Incorpore conexões de contas sociais e o agendamento de posts do Social media studio ao seu aplicativo

`@social-media-scheduler/sdk` é o SDK TypeScript do lado do servidor para plataformas
que querem oferecer conexão de contas sociais e agendamento de posts aos seus próprios
clientes. O Social media studio hospeda o fluxo OAuth e a infraestrutura de publicação, enquanto o seu
aplicativo mantém o controle da experiência do cliente.

> [!WARNING]
>
> As chaves de parceiro podem acessar todos os usuários finais do projeto. Use o SDK somente em
> código de servidor confiável. Nunca inclua uma chave `pk_test_` ou `pk_live_` em código de navegador,
> mobile, desktop ou qualquer outro código distribuído aos clientes.

> [!NOTE]
>
> A Plataforma Embedded está atualmente em disponibilidade limitada, e a conexão de contas
> hospedada atualmente oferece suporte ao Threads. Entre em contato com o Social media studio para que um projeto de parceiro
> e uma chave de API sejam provisionados.

## SDK versus CLI

| Pacote | Usuário-alvo | Credenciais | Uso típico |
| - | - | - | - |
| `@social-media-scheduler/sdk` | Desenvolvedores de aplicativos que atendem muitos usuários finais | Chave de parceiro (`pk_test_` ou `pk_live_`) | Incorporar conexões e agendamento em um produto |
| `@social-media-scheduler/cli` | Um cliente direto do Social media studio | Chave de API pessoal (`sk_live_`) | Gerenciar a sua própria organização pelo terminal ou em CI |

Os pacotes são independentes. Instalar o SDK não instala o comando `so-me`,
e a CLI não expõe o SDK de parceiros.

## Requisitos

* Node.js 20 ou mais recente
* Um projeto de parceiro do Social media studio
* Uma chave de API de parceiro de teste ou de produção
* Toda origem do aplicativo que possa receber um retorno do OAuth, registrada no
  projeto de parceiro

## Instalação

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

O SDK inclui builds ESM e CommonJS, traz declarações TypeScript e não tem
dependências em tempo de execução.

## Inicializar o cliente

```ts theme={null}
import { SoMePlatformClient } from "@social-media-scheduler/sdk";

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

A URL da API de produção é `https://api.so-me.studio` por padrão. Você pode informar
`baseUrl` para um ambiente auto-hospedado ou local e personalizar o tempo limite de
requisição de 30 segundos:

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

## Fluxo completo

1. Faça o upsert de um usuário final usando o ID de cliente estável do seu banco de dados.
2. Crie uma sessão de conexão de curta duração e envie a `connectUrl` dela para o
   navegador do cliente.
3. Depois que o OAuth for concluído, busque a sessão ou liste as conexões sociais
   do cliente.
4. Crie um post imediato ou agendado usando um ID de conexão retornado.
5. Receba os resultados da publicação por meio de webhooks assinados.

```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",
});

// Redirecione o navegador do cliente para session.connectUrl.
```

> **[Conectar contas](/pt-BR/sdk/connect-accounts.md)**
>
> Crie usuários finais e execute o fluxo OAuth hospedado.

> **[Publicar posts](/pt-BR/sdk/posts-and-media.md)**
>
> Publique imediatamente, agende posts e envie mídia.

> **[Receber webhooks](/pt-BR/sdk/webhooks.md)**
>
> Verifique payloads de entrega assinados e trate novas tentativas com segurança.

> **[Proteger a integração](/pt-BR/sdk/security-and-errors.md)**
>
> Proteja as chaves de parceiro e trate falhas da API.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.