@magnetcustomer/sdk 1.0.1 → 2.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Magnet Customer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,148 +1,158 @@
 # @magnetcustomer/sdk
 
-Official Node.js SDK for the [MagnetCustomer CRM API](https://developers.magnetcustomer.com).
+SDK oficial da API da [Magnet Customer](https://magnetcustomer.com) para Node.js, com tipos TypeScript.
 
-Auto-generated from the OpenAPI 3.1 specification. Supports TypeScript and JavaScript (CommonJS + ESM).
+Ele autentica com um Service Account, renova o token sozinho e expõe um objeto por recurso da API.
 
-## Installation
+- Documentação: <https://magnetcustomer.com/developers>
+- Referência da API: <https://magnetcustomer.com/developers/api-reference>
+
+## Instalação
 
 ```bash
 npm install @magnetcustomer/sdk
 ```
 
-## Quick Start
+Requer Node.js 18 ou superior.
 
-```typescript
-import { Configuration, ContactsApi } from '@magnetcustomer/sdk';
+## Antes de começar
 
-const config = new Configuration({
-  basePath: 'https://platform-api.your-tenant.magnetcustomer.com',
-  accessToken: 'your-oauth2-token',
-});
+Crie um Service Account no CRM, em **Configurações › Service Accounts** (apenas administradores), e copie o **Client ID** e o **Client Secret**. Dê a ele só as permissões de que a integração precisa.
 
-const contacts = new ContactsApi(config);
-const response = await contacts.apiContactsGet({ page: 1, limit: 25 });
-console.log(response.data);
-```
+Guarde o secret no servidor, em variável de ambiente. Nunca o coloque em navegador ou aplicativo móvel.
 
-## Authentication
+## Uso
 
-The SDK uses OAuth2 Bearer tokens. Obtain a token via the Client Credentials flow:
+```ts
+import { MagnetCustomer } from '@magnetcustomer/sdk';
 
-```bash
-curl -X POST https://magnetcustomer.net/realms/platform/protocol/openid-connect/token \
-  -d "grant_type=client_credentials" \
-  -d "client_id=YOUR_CLIENT_ID" \
-  -d "client_secret=YOUR_CLIENT_SECRET" \
-  -d "scope=openid"
-```
-
-Then pass the `access_token` from the response to the `Configuration`:
+const crm = new MagnetCustomer({
+  account: 'sua-conta', // o subdomínio que você usa para abrir o CRM
+  clientId: process.env.MAGNET_CLIENT_ID!,
+  clientSecret: process.env.MAGNET_CLIENT_SECRET!,
+});
 
-```typescript
-const config = new Configuration({
-  basePath: 'https://platform-api.your-tenant.magnetcustomer.com',
-  accessToken: tokenResponse.access_token,
+// Listar: envie sempre `page`
+const { data } = await crm.deals.listDeals({ page: 1, limit: 25 });
+console.log(data.total, data.docs);
+
+// Criar
+const created = await crm.contacts.createContact({
+  contactInput: {
+    fullname: 'Maria Santos',
+    email: 'maria@cliente.com',
+    phones: [{ number: '11987654321', ddi: '+55', typePhone: 'cellphone' }],
+  },
 });
+
+// Atualizar e mover de etapa
+await crm.deals.updateDeal({ id: dealId, dealInput: { amount: 90000 } });
+await crm.deals.moveDealStage({ id: dealId, moveDealStageRequest: { stageId } });
 ```
 
-## Available APIs
-
-The SDK covers 60+ API groups:
-
-| API Class | Description |
-|-----------|-------------|
-| `ActionsApi` | Campaign actions (enable/disable) |
-| `ActivitiesApi` | Meetings, observations, todos |
-| `AuthenticationApi` | OAuth2 token management |
-| `ContactsApi` | CRM contacts CRUD |
-| `DealsApi` | Deal management |
-| `PipelinesApi` | Sales pipelines |
-| `TasksApi` | Task management |
-| `TicketsApi` | Support tickets |
-| `WebhooksApi` | Webhook configuration |
-| `DashboardsApi` | Analytics dashboards |
-| `CampaignsApi` | Marketing campaigns |
-| `SegmentationApi` | Contact segmentation |
-| `StaffsApi` | Team members |
-| `TeamsApi` | Team management |
-| `WorkspacesApi` | Workspace/BU management |
-| `ProcessAutomationApi` | Workflow automation |
-| `IntegrationsApi` | Third-party integrations |
-| `ReportsApi` | Reporting and analytics |
-
-...and 40+ more.
-
-## Examples
-
-### Create a Contact
-
-```typescript
-import { Configuration, ContactsApi } from '@magnetcustomer/sdk';
-
-const api = new ContactsApi(new Configuration({
-  basePath: 'https://platform-api.your-tenant.magnetcustomer.com',
-  accessToken: 'your-token',
-}));
-
-const result = await api.apiContactsPost({
-  body: { name: 'John Doe', email: 'john@example.com' },
-});
-console.log(result.data);
+Cada método devolve a resposta do [axios](https://axios-http.com): o corpo está em `data` e o status em `status`.
+
+## Recursos
+
+| Propriedade | Recurso |
+|---|---|
+| `crm.contacts` | Contatos |
+| `crm.leads`, `crm.prospects`, `crm.customers` | Contatos por fase |
+| `crm.organizations` | Empresas |
+| `crm.deals` | Oportunidades |
+| `crm.pipelines` | Pipelines, etapas e motivos de perda |
+| `crm.journeys` | Jornadas (leitura) |
+| `crm.meetings` | Reuniões, tipos e salas |
+| `crm.tasks`, `crm.taskTypes` | Tarefas e tipos de tarefa |
+| `crm.observations` | Observações |
+| `crm.tickets` | Tickets, situações e mensagens |
+| `crm.treatments` | Atendimentos e tipos |
+| `crm.staffs` | Usuários |
+| `crm.customFields` | Campos personalizados |
+| `crm.teams` | Equipes e áreas de trabalho |
+| `crm.webhooks` | Eventos de webhook disponíveis |
+
+Os parâmetros, o corpo aceito e a resposta de cada operação estão na [referência da API](https://magnetcustomer.com/developers/api-reference). Os nomes dos métodos são os `operationId` de lá.
+
+## Paginação
+
+Envie sempre `page`. A resposta traz `docs`, `total`, `pages`, `page` e `limit` (no máximo 100 por página).
+
+```ts
+async function* allDeals() {
+  for (let page = 1; ; page++) {
+    const { data } = await crm.deals.listDeals({ page, limit: 100 });
+    yield* data.docs ?? [];
+    if (page >= (data.pages ?? 0)) return;
+  }
+}
 ```
 
-### List Deals with Pagination
+## Filtros com vários valores
 
-```typescript
-import { Configuration, DealsApi } from '@magnetcustomer/sdk';
+Passe uma lista; o SDK envia no formato que a API espera (`staffs[]=...`), inclusive com um valor só:
 
-const api = new DealsApi(new Configuration({
-  basePath: 'https://platform-api.your-tenant.magnetcustomer.com',
-  accessToken: 'your-token',
-}));
+```ts
+await crm.contacts.listContacts({ page: 1, staffs: [staffId] });
+```
+
+## Webhooks
+
+Os webhooks são criados por um administrador no CRM, em **Integrações › Webhooks**. O SDK lista os eventos disponíveis com `crm.webhooks.listWebhookTriggers()`.
+
+## Erros
+
+Uma resposta fora de 2xx lança o erro do axios, com o status e o corpo da API:
 
-const result = await api.apiDealsGet({ page: 1, limit: 25 });
-console.log(result.data);
+```ts
+try {
+  await crm.deals.getDeal({ id });
+} catch (error) {
+  if (error.response?.status === 404) {
+    // registro não encontrado
+  }
+  console.error(error.response?.status, error.response?.data);
+}
 ```
 
-### Using a Custom Axios Instance
+| Status | Quando |
+|---|---|
+| `400` | Corpo ou parâmetros inválidos. `data.errors` ou `data.fields` dizem o que faltou |
+| `401` | Credencial inválida. O SDK pede um token novo e repete a chamada uma vez |
+| `403` | O Service Account não tem a permissão da rota. `data.requiredPermission` diz qual |
+| `404` | Registro não encontrado |
+| `429` | Limite de requisições. Espere o tempo do cabeçalho `Retry-After` |
 
-```typescript
-import axios from 'axios';
-import { Configuration, ContactsApi } from '@magnetcustomer/sdk';
+## Token
 
-const axiosInstance = axios.create({
-  timeout: 10000,
-  headers: { 'X-Custom-Header': 'value' },
-});
+O token vale 15 minutos. O SDK guarda o token, pede outro um minuto antes de vencer e compartilha o pedido entre chamadas simultâneas. Você não precisa fazer nada.
 
-const config = new Configuration({
-  basePath: 'https://platform-api.your-tenant.magnetcustomer.com',
-  accessToken: 'your-token',
-});
+Para usar o token em outro cliente HTTP:
 
-const api = new ContactsApi(config, undefined, axiosInstance);
+```ts
+const token = await crm.tokens.getAccessToken();
 ```
 
-## Module Formats
+## Vindo da versão 1.x
 
-| Format | Entry Point |
-|--------|-------------|
-| CommonJS | `dist/index.js` |
-| ESM | `dist/esm/index.js` |
-| TypeScript types | `dist/index.d.ts` |
+A 2.0 foi refeita a partir da referência atual da API e muda a interface:
 
-## Documentation
+- Um cliente só (`new MagnetCustomer({ account, clientId, clientSecret })`) no lugar de `Configuration` + uma classe por API.
+- O token é obtido e renovado pelo SDK.
+- Os métodos têm os nomes da referência (`listDeals`, `createContact`...) e recebem um objeto de parâmetros.
+- A 2.x cobre os recursos da tabela acima, os mesmos da referência pública. Para uma rota fora dela, use o token de `crm.tokens.getAccessToken()` no seu cliente HTTP.
 
-- [Developer Portal](https://developers.magnetcustomer.com)
-- [API Reference](https://developers.magnetcustomer.com/api-reference)
-- [Getting Started](https://developers.magnetcustomer.com/getting-started/quick-start)
+## Desenvolvimento
 
-## Requirements
+```bash
+npm ci
+npm test         # testes
+npm run build    # compila para dist/
+npm run generate # regenera src/generated a partir de openapi.yaml (requer Java e Python com PyYAML)
+```
 
-- Node.js 14+
-- `axios` ^1.0 (peer dependency — installed automatically)
+`openapi.yaml` é a cópia da referência pública. `src/generated` é código gerado: não edite à mão.
 
-## License
+## Licença
 
-MIT — see [LICENSE](LICENSE).
+MIT

package/dist/auth.d.ts

@@ -0,0 +1,25 @@
+import { AxiosInstance } from 'axios';
+export declare const DEFAULT_TOKEN_URL = "https://magnetcustomer.net/realms/platform/protocol/openid-connect/token";
+export interface ServiceAccountCredentials {
+    clientId: string;
+    clientSecret: string;
+    /** Endereço do token. Só mude em ambientes de teste. */
+    tokenUrl?: string;
+}
+/**
+ * Obtém e renova o token de um Service Account (OAuth 2.0 client_credentials).
+ * O fluxo não tem refresh token: quando o token está perto de vencer, um novo é pedido.
+ */
+export declare class TokenManager {
+    private readonly credentials;
+    private readonly http;
+    private readonly now;
+    private cached;
+    private pending;
+    constructor(credentials: ServiceAccountCredentials, http?: AxiosInstance, now?: () => number);
+    /** Devolve um token válido, pedindo um novo só quando necessário. */
+    getAccessToken(): Promise<string>;
+    /** Descarta o token guardado. Use ao receber 401. */
+    invalidate(): void;
+    private requestToken;
+}

package/dist/auth.js

@@ -0,0 +1,61 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenManager = exports.DEFAULT_TOKEN_URL = void 0;
+const axios_1 = __importDefault(require("axios"));
+exports.DEFAULT_TOKEN_URL = 'https://magnetcustomer.net/realms/platform/protocol/openid-connect/token';
+/** Folga, em segundos, para renovar o token antes de ele vencer. */
+const RENEWAL_MARGIN_SECONDS = 60;
+/**
+ * Obtém e renova o token de um Service Account (OAuth 2.0 client_credentials).
+ * O fluxo não tem refresh token: quando o token está perto de vencer, um novo é pedido.
+ */
+class TokenManager {
+    constructor(credentials, http = axios_1.default.create(), now = Date.now) {
+        this.credentials = credentials;
+        this.http = http;
+        this.now = now;
+        this.cached = null;
+        this.pending = null;
+        if (!credentials.clientId || !credentials.clientSecret) {
+            throw new Error('clientId e clientSecret são obrigatórios.');
+        }
+    }
+    /** Devolve um token válido, pedindo um novo só quando necessário. */
+    async getAccessToken() {
+        if (this.cached && this.cached.expiresAt > this.now()) {
+            return this.cached.accessToken;
+        }
+        // Chamadas simultâneas compartilham o mesmo pedido de token.
+        if (!this.pending) {
+            this.pending = this.requestToken().finally(() => {
+                this.pending = null;
+            });
+        }
+        return this.pending;
+    }
+    /** Descarta o token guardado. Use ao receber 401. */
+    invalidate() {
+        this.cached = null;
+    }
+    async requestToken() {
+        const body = new URLSearchParams({
+            grant_type: 'client_credentials',
+            client_id: this.credentials.clientId,
+            client_secret: this.credentials.clientSecret,
+        });
+        const response = await this.http.post(this.credentials.tokenUrl ?? exports.DEFAULT_TOKEN_URL, body.toString(), {
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        });
+        const { access_token: accessToken, expires_in: expiresIn } = response.data ?? {};
+        if (!accessToken) {
+            throw new Error('A resposta do pedido de token não trouxe access_token.');
+        }
+        const lifetimeSeconds = Math.max((Number(expiresIn) || 0) - RENEWAL_MARGIN_SECONDS, 0);
+        this.cached = { accessToken, expiresAt: this.now() + lifetimeSeconds * 1000 };
+        return accessToken;
+    }
+}
+exports.TokenManager = TokenManager;

package/dist/client.d.ts

@@ -0,0 +1,39 @@
+import { AxiosInstance } from 'axios';
+import { ServiceAccountCredentials, TokenManager } from './auth';
+import { ContactsApi, CustomFieldsApi, CustomersApi, DealsApi, JourneysApi, LeadsApi, MeetingsApi, ObservationsApi, OrganizationsApi, PipelinesApi, ProspectsApi, StaffsApi, TaskTypesApi, TasksApi, TeamsApi, TicketsApi, TreatmentsApi, WebhooksApi } from './generated/api';
+export interface MagnetCustomerOptions extends ServiceAccountCredentials {
+    /** Subdomínio da conta: o mesmo usado para abrir o CRM (`acme` em `acme.magnetcustomer.com`). */
+    account: string;
+    /** Endereço da API. Por padrão é montado a partir de `account`. */
+    baseUrl?: string;
+}
+/** Monta o endereço da API de uma conta. */
+export declare function buildBaseUrl(account: string): string;
+/**
+ * Cliente da API da Magnet Customer.
+ *
+ * Autentica com um Service Account, renova o token sozinho e expõe um objeto por recurso.
+ */
+export declare class MagnetCustomer {
+    readonly contacts: ContactsApi;
+    readonly leads: LeadsApi;
+    readonly prospects: ProspectsApi;
+    readonly customers: CustomersApi;
+    readonly organizations: OrganizationsApi;
+    readonly deals: DealsApi;
+    readonly pipelines: PipelinesApi;
+    readonly meetings: MeetingsApi;
+    readonly tasks: TasksApi;
+    readonly taskTypes: TaskTypesApi;
+    readonly observations: ObservationsApi;
+    readonly staffs: StaffsApi;
+    readonly customFields: CustomFieldsApi;
+    readonly tickets: TicketsApi;
+    readonly treatments: TreatmentsApi;
+    readonly journeys: JourneysApi;
+    readonly teams: TeamsApi;
+    readonly webhooks: WebhooksApi;
+    readonly tokens: TokenManager;
+    readonly baseUrl: string;
+    constructor(options: MagnetCustomerOptions, http?: AxiosInstance);
+}

package/dist/client.js

@@ -0,0 +1,65 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MagnetCustomer = void 0;
+exports.buildBaseUrl = buildBaseUrl;
+const axios_1 = __importDefault(require("axios"));
+const auth_1 = require("./auth");
+const configuration_1 = require("./generated/configuration");
+const api_1 = require("./generated/api");
+/** Monta o endereço da API de uma conta. */
+function buildBaseUrl(account) {
+    if (!/^[a-z0-9][a-z0-9-]*$/i.test(account)) {
+        throw new Error('account deve ser só o subdomínio da conta, por exemplo "acme".');
+    }
+    return `https://${account}.platform-api.magnetcustomer.com`;
+}
+/**
+ * Cliente da API da Magnet Customer.
+ *
+ * Autentica com um Service Account, renova o token sozinho e expõe um objeto por recurso.
+ */
+class MagnetCustomer {
+    constructor(options, http = axios_1.default.create()) {
+        this.baseUrl = options.baseUrl ?? buildBaseUrl(options.account);
+        this.tokens = new auth_1.TokenManager(options, http);
+        // Um 401 com token guardado quase sempre é token vencido: descarta e tenta uma vez de novo.
+        http.interceptors.response.use(undefined, async (error) => {
+            const request = error?.config;
+            const isApiCall = typeof request?.url === 'string' && request.url.startsWith(this.baseUrl);
+            if (error?.response?.status === 401 && isApiCall && !request.retriedAfterUnauthorized) {
+                this.tokens.invalidate();
+                request.retriedAfterUnauthorized = true;
+                request.headers.Authorization = `Bearer ${await this.tokens.getAccessToken()}`;
+                return http.request(request);
+            }
+            throw error;
+        });
+        const configuration = new configuration_1.Configuration({
+            basePath: this.baseUrl,
+            accessToken: () => this.tokens.getAccessToken(),
+        });
+        const build = (Api) => new Api(configuration, this.baseUrl, http);
+        this.contacts = build(api_1.ContactsApi);
+        this.leads = build(api_1.LeadsApi);
+        this.prospects = build(api_1.ProspectsApi);
+        this.customers = build(api_1.CustomersApi);
+        this.organizations = build(api_1.OrganizationsApi);
+        this.deals = build(api_1.DealsApi);
+        this.pipelines = build(api_1.PipelinesApi);
+        this.meetings = build(api_1.MeetingsApi);
+        this.tasks = build(api_1.TasksApi);
+        this.taskTypes = build(api_1.TaskTypesApi);
+        this.observations = build(api_1.ObservationsApi);
+        this.staffs = build(api_1.StaffsApi);
+        this.customFields = build(api_1.CustomFieldsApi);
+        this.tickets = build(api_1.TicketsApi);
+        this.treatments = build(api_1.TreatmentsApi);
+        this.journeys = build(api_1.JourneysApi);
+        this.teams = build(api_1.TeamsApi);
+        this.webhooks = build(api_1.WebhooksApi);
+    }
+}
+exports.MagnetCustomer = MagnetCustomer;