# SDK JavaScript

> O cliente que a API publica em /sdk.js e /sdk.mjs, gerado da própria especificação. Como carregar no navegador e no Node, os métodos por assunto, como passar parâmetros e corpo, o tratamento de erro e as opções do cliente.

A API publica um **SDK JavaScript** gerado da própria especificação OpenAPI. Ele cobre todas as operações, envia os headers por você, desembrulha o envelope das respostas e transforma erro em exceção.

| Arquivo | Uso |
|---|---|
| [`/sdk.js`](https://api.memberfy.net/sdk.js) | UMD: `<script src>` (expõe `Memberfy`) ou `require()` no Node |
| [`/sdk.mjs`](https://api.memberfy.net/sdk.mjs) | ESM: `import { createClient } from '…/sdk.mjs'` |

## Começar no navegador

```html
<script src="https://api.memberfy.net/sdk.js"></script>
<script>
  const api = Memberfy.createClient({ baseUrl: 'https://api.memberfy.net' });

  const session = await api.auth.login({ email, password });
  api.setToken(session.token).setCommunity(communityId);

  const me = await api.auth.getMe();
</script>
```

**Passe sempre o `baseUrl` com `https://`.**

## Começar no Node

Baixe o arquivo para o projeto e importe localmente (Node 18 ou mais novo, que já tem `fetch`):

```bash
curl -s https://api.memberfy.net/sdk.mjs -o memberfy-sdk.mjs
```

```js
import { createClient } from './memberfy-sdk.mjs';

const api = createClient({ baseUrl: 'https://api.memberfy.net' });
const session = await api.auth.login({ email: process.env.MEMBERFY_EMAIL, password: process.env.MEMBERFY_PASSWORD });
api.setToken(session.token).setCommunity(process.env.MEMBERFY_COMMUNITY_ID);
```

Baixe de novo quando quiser atualizar.

## O que ele faz por você

| | |
|---|---|
| **Headers** | `Authorization`, `X-CommunityId`, `X-ProfileId` e `Accept-Language`, a partir de `setToken`, `setCommunity`, `setProfile` e `setLanguage` |
| **Envelope** | Devolve o `data` direto; listagens devolvem `{ data, pagination }` |
| **Erros** | Lança `MemberfyError`, com `.status`, `.body` e `.errors` |
| **Sessão** | `onUnauthorized` é chamado num `401`, para você refazer o login |

## Os métodos

Os métodos ficam agrupados por assunto (o mesmo da [referência](/api/referencia)): `api.auth`, `api.products`, `api.subscriptions`, `api.coupons`, `api.sectionsSpaces`, `api.events`… O nome do método vem do `operationId` da operação: `api.products.postCommunitiesByCommunityIdProducts`, `api.profiles.getList`, `api.auth.login`.

Alguns nomes ainda carregam `CommunitiesByCommunityId` de quando a rota tinha a comunidade no caminho. Desde 6 de outubro de 2026 nenhuma rota leva a comunidade no caminho, mas os nomes ficaram, para nada quebrar no seu código. A comunidade vai sempre pelo `setCommunity`. Ver [X-CommunityId](/api/x-community-id#os-caminhos-que-mudaram).

Na página de cada endpoint da referência aparece o `operationId`.

## Parâmetros e corpo

Parâmetros de caminho e de query vão pelo nome; **o resto vira o corpo**:

```js
api.setCommunity(communityId); // a comunidade vai no header X-CommunityId

await api.products.putCommunitiesByCommunityIdProductsById({
  id: productId,               // vai para o caminho
  type: 'SUBSCRIPTION',        // corpo
  title: 'Aluno · Mensal',     // corpo
  price: 49,                   // corpo
  billingInterval: 'MONTHLY',  // corpo
  allowedPaymentMethods: ['PIX', 'CREDIT_CARD', 'BOLETO'],
});
```

Também dá para separar: `{ id, body: { … } }`. **Não passe `communityId` nos argumentos**: como ele não é mais parâmetro de caminho, iria para o corpo. Outras opções por chamada: `headers` (headers extras), `query` (parâmetros de query a mais) e `signal` (um `AbortController`).

Para qualquer rota, há `api.request({ httpMethod, path, pathParams, queryParams, hasBody }, args)`.

## Tratar erro

```js
try {
  await api.coupons.postCommunitiesByCommunityIdCouponsValidate({ code: 'LANCAMENTO20' });
} catch (error) {
  if (error.name === 'MemberfyError') {
    console.log(error.status);  // 400
    console.log(error.errors);  // [{ param: 'code', message: 'Cupom expirado' }]
  }
}
```

## Opções do cliente

| Opção | Para quê |
|---|---|
| `baseUrl` | O endereço da API. Use `https://api.memberfy.net` |
| `token`, `communityId`, `profileId`, `language` | Valores iniciais dos headers |
| `raw: true` | Devolve o corpo cru, com o envelope |
| `onUnauthorized` | Função chamada num `401` |
| `fetch` | Uma implementação de `fetch`, para ambientes sem a nativa |

## Sempre atual

O SDK é gerado a cada vez que é servido, a partir das rotas da API. Baixar de novo é atualizar.

## Para IA

Para um assistente gerar chamadas certas, entregue também o [`/docs.txt`](https://api.memberfy.net/docs.txt): o SDK diz **como** chamar; o `/docs.txt` diz **o que** enviar.

## Relacionados

- [Autenticação](/api/autenticacao)
- [Respostas e erros](/api/respostas-e-erros)
- [Referência da API](/api/referencia)