npm package: @nhvbeauty/integration-gateway
Description: TypeScript SDK for Integration Gateway
Latest version: 0.8.0

# @nhvbeauty/integration-gateway

SDK TypeScript para o Integration Gateway. Centraliza o acesso a **Bling**, **TPL** e **Shopify** usando uma unica API key.

## Características

- **Inicialização explícita** – `initialize()` carrega dados do gateway e cria os clientes
- **Clientes tipados** – Reutiliza `Bling` e `Tpl` de `@nhvbeauty/bling` e `@nhvbeauty/tpl`; Shopify via `@shopify/admin-api-client`
- **Rate limiting e tokens** – Gerenciados pelo Integration Gateway; não é necessário implementar retry/backoff no SDK

## Instalação

```bash
bun add @nhvbeauty/integration-gateway
```

## Uso rápido

```typescript
import { IntegrationGatewaySDK } from '@nhvbeauty/integration-gateway'

const sdk = new IntegrationGatewaySDK({
  // opcional: se omitido, usa INTEGRATION_GATEWAY_BASE_URL
  // e depois fallback para https://ig.nhv.digital/api/v1
  baseURL: 'https://api.seudominio.com',
  // opcional: se omitido, usa INTEGRATION_GATEWAY_API_KEY
  apiKey: process.env.INTEGRATION_GATEWAY_API_KEY!,
})

await sdk.initialize()

const bling = sdk.getBlingByCompanyId('77c6d8af7481552f823f729b91f8dcca')
const tpl = sdk.getTplByAccountId('xyz789')
const shopify = sdk.getShopifyByShopDomain('minha-loja')

// Bling
const orders = await bling.getOrders({ limite: 50, pagina: 1 })

// TPL
const orderDetail = await tpl.getOrderDetailByNumber('PED-001')

// Shopify (GraphQL)
const result = await shopify.request(`#graphql
  query {
    shop { name }
  }
`)
```

## API do SDK

| Método | Retorno | Descrição |
|--------|---------|-----------|
| `initialize()` | `Promise<void>` | Uma chamada a `/integration-access/bootstrap` carrega credenciais e cria os clientes. **Obrigatório** antes de usar os getters. |
| `getBlingByCompanyId(companyId)` | `Bling` | Cliente Bling para o companyId. Lança se o companyId não for encontrado. |
| `getTplByAccountId(accountId)` | `Tpl` | Cliente TPL para o accountId. Lança se o accountId não for encontrado. |
| `getShopifyByShopDomain(shopDomain)` | `AdminApiClient` | Cliente oficial Shopify Admin API buscando pelo shop domain. Aceita com ou sem `.myshopify.com`. |

Configuração do construtor:

```typescript
interface IntegrationGatewaySDKConfig {
  baseURL?: string // 1) construtor, 2) INTEGRATION_GATEWAY_BASE_URL, 3) https://ig.nhv.digital/api/v1
  apiKey?: string  // 1) construtor, 2) INTEGRATION_GATEWAY_API_KEY
}
```

Também é válido instanciar sem parâmetros:

```typescript
const sdk = new IntegrationGatewaySDK()
```

Nesse caso:
- `baseURL` usa `INTEGRATION_GATEWAY_BASE_URL` ou, se ausente, `https://ig.nhv.digital/api/v1`
- `apiKey` deve vir de `INTEGRATION_GATEWAY_API_KEY`

## Exemplos por integração

### Bling (pedidos, contatos, notas fiscais)

Os métodos disponíveis são os do cliente [@nhvbeauty/bling](https://www.npmjs.com/package/@nhvbeauty/bling). Exemplos:

```typescript
const bling = sdk.getBlingByCompanyId('77c6d8af7481552f823f729b91f8dcca')

const orders = await bling.getOrders({
  limite: 100,
  pagina: 1,
  dataInicial: '2024-01-01',
  dataFinal: '2024-12-31',
})

const order = await bling.getOrderById(12345678)
const invoices = await bling.getInvoices({ limite: 100, situacao: 1 })
const contact = await bling.getContactById(12345678)

await bling.updateOrderStatus(12345678, 9)
await bling.updateOrder(12345678, { observacoes: 'Atualizado via API' })
await bling.updateContact(12345678, { nome: 'João', email: 'joao@exemplo.com' })
```

### TPL (pedidos, rastreio)

Os métodos disponíveis são os do cliente [@nhvbeauty/tpl](https://www.npmjs.com/package/@nhvbeauty/tpl). Exemplos:

```typescript
const tpl = sdk.getTplByAccountId('xyz789')

const result = await tpl.createOrder({
  number: 'PED-001',
  date: '01/01/2024',
  deliveryTo: { name: 'João', identification: '12345678901', phone: '11987654321', mail: 'joao@exemplo.com', address: { street: 'Rua X', number: '1', neighborhood: 'Centro', city: 'São Paulo', state: 'SP', zipCode: '01234567' } },
  items: [{ sku: 'PROD-001', name: 'Produto', amount: 2, unitWeight: 500 }],
})

const order = await tpl.getOrderDetail('12345')
const byNumber = await tpl.getOrderDetailByNumber('PED-001')
await tpl.deleteOrder('12345')
```

### Shopify (Admin API)

O retorno de `getShopifyByShopDomain` é um [AdminApiClient](https://github.com/Shopify/shopify-api-js) oficial. Use GraphQL:

```typescript
const shopify = sdk.getShopifyByShopDomain('minha-loja')
// ou
const shopify = sdk.getShopifyByShopDomain('minha-loja.myshopify.com')

const result = await shopify.request(`#graphql
  query {
    products(first: 10) {
      edges {
        node {
          id
          title
        }
      }
    }
  }
`)
```

## Tratamento de erros

- **Configuração ausente (construtor/env):**
  - `Integration Gateway baseURL is required. Provide it via constructor or INTEGRATION_GATEWAY_BASE_URL.`
  - `Integration Gateway apiKey is required. Provide it via constructor or INTEGRATION_GATEWAY_API_KEY.`
- **Não inicializado:** `IntegrationGatewaySDK not initialized. Call initialize() first.`
- **Sem acesso ao companyId/accountId/domain:** `No Bling access for companyId <id>`, `No TPL access for accountId <id>`, `No Shopify access for shop domain <domain>`
- **Falha na inicialização:** `Failed to initialize Integration Gateway SDK: <motivo>`

Erros HTTP (401, 429, etc.) vêm das chamadas internas (axios); trate no seu fluxo conforme a resposta.

## Documentação para agentes/LLMs

- **llms.txt** – Guia curto para descoberta por agentes/LLMs.
- **llms-full.txt** – Referência técnica detalhada do SDK.

## Tipos exportados

O pacote exporta:

- `IntegrationGatewaySDK` (classe)
- `IIntegrationGatewaySDK` (interface)
- `Bling`, `BlingOAuth` (re-export de `@nhvbeauty/bling`)
- `Tpl` (re-export de `@nhvbeauty/tpl`)

Tipos de pedidos, contatos, notas fiscais etc. vêm dos pacotes `@nhvbeauty/bling` e `@nhvbeauty/tpl`; importe de lá quando precisar de tipos específicos.

## Segurança

- Não commite API keys no código; use variáveis de ambiente.
- Use sempre HTTPS para o `baseURL`.
- Mantenha as API keys restritas ao ambiente (dev/staging/prod).

## Desenvolvimento

```bash
bun install
bun run build
bun test
```

## Licença

Apache-2.0 com restrição **Commons Clause**: o software não pode ser utilizado para fins comerciais. Ver [LICENSE](LICENSE) no repositório.