# SDK JavaScript

> Il client che l'API pubblica su /sdk.js e /sdk.mjs, generato dalla specifica stessa. Come caricarlo nel browser e in Node, i metodi per argomento, come passare parametri e corpo, la gestione degli errori e le opzioni del client.

L'API pubblica un **SDK JavaScript** generato dalla specifica OpenAPI stessa. Copre tutte le operazioni, invia gli header al posto tuo, estrae il contenuto dall'involucro delle risposte e trasforma gli errori in eccezioni.

| File | Uso |
|---|---|
| [`/sdk.js`](https://api.memberfy.net/sdk.js) | UMD: `<script src>` (espone `Memberfy`) oppure `require()` in Node |
| [`/sdk.mjs`](https://api.memberfy.net/sdk.mjs) | ESM: `import { createClient } from '…/sdk.mjs'` |

## Iniziare nel browser

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

**Passa sempre il `baseUrl` con `https://`.**

## Iniziare in Node

Scarica il file nel progetto e importalo in locale (Node 18 o successivo, che ha già `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);
```

Scaricalo di nuovo quando vuoi aggiornarlo.

## Che cosa fa per te

| | |
|---|---|
| **Header** | `Authorization`, `X-CommunityId`, `X-ProfileId` e `Accept-Language`, a partire da `setToken`, `setCommunity`, `setProfile` e `setLanguage` |
| **Involucro** | Restituisce direttamente `data`; gli elenchi restituiscono `{ data, pagination }` |
| **Errori** | Lancia `MemberfyError`, con `.status`, `.body` ed `.errors` |
| **Sessione** | `onUnauthorized` viene chiamato a un `401`, così puoi rifare il login |

## I metodi

I metodi sono raggruppati per argomento (lo stesso del [riferimento](/api/referencia)): `api.auth`, `api.products`, `api.subscriptions`, `api.coupons`, `api.sectionsSpaces`, `api.events`… Il nome del metodo deriva dall'`operationId` dell'operazione: `api.products.postCommunitiesByCommunityIdProducts`, `api.profiles.getList`, `api.auth.login`.

Alcuni nomi portano ancora `CommunitiesByCommunityId` da quando la rotta aveva la community nel percorso. Dal 6 ottobre 2026 nessuna rotta porta la community nel percorso, ma i nomi sono rimasti, perché nel tuo codice non si rompa nulla. La community va sempre con `setCommunity`. Vedi [X-CommunityId](/api/x-community-id#i-percorsi-cambiati).

Nella pagina di ogni endpoint del riferimento compare l'`operationId`.

## Parametri e corpo

I parametri di percorso e di query si passano per nome; **tutto il resto diventa il corpo**:

```js
api.setCommunity(communityId); // the community goes in the X-CommunityId header

await api.products.putCommunitiesByCommunityIdProductsById({
  id: productId,               // goes to the path
  type: 'SUBSCRIPTION',        // body
  title: 'Studente · Mensile', // body
  price: 49,                   // body
  billingInterval: 'MONTHLY',  // body
  allowedPaymentMethods: ['PIX', 'CREDIT_CARD', 'BOLETO'],
});
```

Puoi anche separarli: `{ id, body: { … } }`. **Non passare `communityId` negli argomenti**: non essendo più un parametro di percorso, finirebbe nel corpo. Altre opzioni per chiamata: `headers` (header aggiuntivi), `query` (parametri di query in più) e `signal` (un `AbortController`).

Per qualsiasi rotta c'è `api.request({ httpMethod, path, pathParams, queryParams, hasBody }, args)`.

## Gestire gli errori

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

## Opzioni del client

| Opzione | A cosa serve |
|---|---|
| `baseUrl` | L'indirizzo dell'API. Usa `https://api.memberfy.net` |
| `token`, `communityId`, `profileId`, `language` | Valori iniziali degli header |
| `raw: true` | Restituisce il corpo grezzo, con l'involucro |
| `onUnauthorized` | Funzione chiamata a un `401` |
| `fetch` | Un'implementazione di `fetch`, per ambienti che non hanno quella nativa |

## Sempre aggiornato

L'SDK viene generato ogni volta che viene servito, a partire dalle rotte dell'API. Scaricarlo di nuovo significa aggiornarlo.

## Per l'IA

Perché un assistente generi chiamate corrette, forniscigli anche il [`/docs.txt`](https://api.memberfy.net/docs.txt): l'SDK dice **come** chiamare; il `/docs.txt` dice **che cosa** inviare.

## Correlati

- [Autenticazione](/api/autenticacao)
- [Risposte ed errori](/api/respostas-e-erros)
- [Riferimento API](/api/referencia)