@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

bun add @nhvbeauty/integration-gateway

Uso rápido

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:

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:

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. Exemplos:

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: '[email protected]' })

TPL (pedidos, rastreio)

Os métodos disponíveis são os do cliente @nhvbeauty/tpl. Exemplos:

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: '[email protected]', 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 oficial. Use GraphQL:

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

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 no repositório.