@oficialapi/sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OficialAPI
+
+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

@@ -0,0 +1,563 @@
+# OficialAPI SDK
+
+SDK oficial da OficialAPI para integração com WhatsApp, Telegram, Facebook, Instagram e WebChat. Desenvolvido em TypeScript com suporte completo a TypeScript e JavaScript.
+
+## 🚀 Características
+
+- ✅ **100% TypeScript** - Tipos completos e IntelliSense
+- ✅ **Autenticação Automática** - Renovação automática de tokens
+- ✅ **Retry Inteligente** - Retry automático em caso de falhas
+- ✅ **Tratamento de Erros** - Erros formatados e informativos
+- ✅ **Fácil de Usar** - API intuitiva e bem documentada
+- ✅ **Robusto** - Testado e pronto para produção
+- ✅ **Rápido** - Otimizado para performance
+- ✅ **Seguro** - Validação e sanitização de dados
+
+## 📦 Instalação
+
+```bash
+npm install @oficialapi/sdk
+# ou
+yarn add @oficialapi/sdk
+# ou
+pnpm add @oficialapi/sdk
+```
+
+## 🔧 Configuração
+
+```typescript
+import { OficialAPISDK } from '@oficialapi/sdk';
+
+const sdk = new OficialAPISDK({
+  clientId: 'seu-client-id',
+  clientSecret: 'seu-client-secret',
+  timeout: 30000, // opcional, padrão: 30000ms
+  maxRetries: 3, // opcional, padrão: 3
+  retryDelay: 1000, // opcional, padrão: 1000ms
+});
+```
+
+## 📚 Exemplos de Uso
+
+### WhatsApp
+
+#### Enviar Mensagem de Texto
+
+```typescript
+const result = await sdk.whatsapp.sendText({
+  token: 'sk_live_9999999999999999999999999999',
+  sender: '5511999999999',
+  messageText: 'Olá! Como posso ajudar você hoje?'
+});
+
+console.log(result.data.messageId);
+```
+
+#### Enviar Mídia
+
+```typescript
+await sdk.whatsapp.sendMedia({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  fileUrl: 'https://example.com/image.jpg',
+  type: 'image',
+  caption: 'Veja esta imagem!'
+});
+```
+
+#### Enviar Template
+
+```typescript
+await sdk.whatsapp.sendTemplate({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  templateName: 'welcome_message',
+  languageCode: 'pt_BR',
+  components: [
+    {
+      type: 'body',
+      parameters: [
+        { type: 'text', text: 'João' }
+      ]
+    }
+  ]
+});
+```
+
+#### Enviar Botões
+
+```typescript
+await sdk.whatsapp.sendButtons({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  messageText: 'Escolha uma opção:',
+  buttons: [
+    {
+      type: 'reply',
+      reply: {
+        id: 'option1',
+        title: 'Opção 1'
+      }
+    },
+    {
+      type: 'reply',
+      reply: {
+        id: 'option2',
+        title: 'Opção 2'
+      }
+    }
+  ]
+});
+```
+
+#### Enviar Lista Interativa
+
+```typescript
+await sdk.whatsapp.sendList({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  messageText: 'Escolha um produto:',
+  buttonText: 'Ver Produtos',
+  sections: [
+    {
+      title: 'Produtos',
+      rows: [
+        {
+          id: 'product1',
+          title: 'Produto 1',
+          description: 'Descrição do produto 1'
+        },
+        {
+          id: 'product2',
+          title: 'Produto 2',
+          description: 'Descrição do produto 2'
+        }
+      ]
+    }
+  ]
+});
+```
+
+#### Enviar Contato
+
+```typescript
+await sdk.whatsapp.sendContact({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  contacts: [
+    {
+      name: {
+        formatted_name: 'João Silva',
+        first_name: 'João',
+        last_name: 'Silva'
+      },
+      phones: [
+        {
+          phone: '+5511999999999',
+          type: 'Mobile',
+          wa_id: '5511999999999'
+        }
+      ]
+    }
+  ]
+});
+```
+
+#### Enviar Localização
+
+```typescript
+await sdk.whatsapp.sendLocation({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  latitude: -23.5505,
+  longitude: -46.6333,
+  name: 'São Paulo',
+  address: 'São Paulo, SP, Brasil'
+});
+```
+
+#### Enviar Áudio
+
+```typescript
+await sdk.whatsapp.sendAudio({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  audioUrl: 'https://example.com/audio.ogg'
+});
+```
+
+#### Enviar Vídeo
+
+```typescript
+await sdk.whatsapp.sendVideo({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  videoUrl: 'https://example.com/video.mp4',
+  caption: 'Veja este vídeo!'
+});
+```
+
+#### Enviar Documento
+
+```typescript
+await sdk.whatsapp.sendDocument({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  documentUrl: 'https://example.com/document.pdf',
+  filename: 'documento.pdf',
+  caption: 'Aqui está o documento'
+});
+```
+
+#### Enviar Pedido com Opções de Pagamento
+
+```typescript
+await sdk.whatsapp.sendOrderDetails({
+  token: 'sk_live_...',
+  sender: '5511999999999',
+  orderId: 'ORDER123',
+  orderItems: [
+    {
+      item_code: 'ITEM001',
+      description: 'Produto 1',
+      quantity: 2,
+      price: 50.00
+    }
+  ],
+  orderTotal: 100.00,
+  currency: 'BRL',
+  paymentMethods: [
+    {
+      type: 'PIX',
+      name: 'PIX'
+    },
+    {
+      type: 'CREDIT_CARD',
+      name: 'Cartão de Crédito'
+    }
+  ]
+});
+```
+
+#### Gerenciar Templates
+
+```typescript
+// Listar templates
+const templates = await sdk.whatsapp.listTemplates('sk_live_...');
+
+// Obter detalhes de um template
+const template = await sdk.whatsapp.getTemplate('sk_live_...', 'template_id');
+
+// Criar template
+await sdk.whatsapp.createTemplate({
+  token: 'sk_live_...',
+  name: 'welcome_message',
+  language: 'pt_BR',
+  category: 'UTILITY',
+  components: [
+    {
+      type: 'BODY',
+      text: 'Olá {{1}}! Bem-vindo ao nosso serviço.'
+    }
+  ]
+});
+
+// Upload de mídia para template
+const file = new File(['...'], 'image.jpg', { type: 'image/jpeg' });
+await sdk.whatsapp.uploadMedia({
+  token: 'sk_live_...',
+  file: file,
+  filename: 'image.jpg'
+});
+```
+
+### Telegram
+
+#### Enviar Mensagem de Texto
+
+```typescript
+await sdk.telegram.sendMessage({
+  token: 'sk_live_...',
+  chatId: '123456789',
+  text: 'Olá! Como posso ajudar?',
+  parseMode: 'HTML'
+});
+```
+
+#### Enviar Mídia
+
+```typescript
+await sdk.telegram.sendMedia({
+  token: 'sk_live_...',
+  chatId: '123456789',
+  fileUrl: 'https://example.com/image.jpg',
+  type: 'photo',
+  caption: 'Veja esta imagem!'
+});
+```
+
+#### Enviar Botões
+
+```typescript
+await sdk.telegram.sendButtons({
+  token: 'sk_live_...',
+  chatId: '123456789',
+  text: 'Escolha uma opção:',
+  buttons: [
+    [
+      { text: 'Opção 1', callback_data: 'option1' },
+      { text: 'Opção 2', callback_data: 'option2' }
+    ]
+  ]
+});
+```
+
+#### Enviar Localização
+
+```typescript
+await sdk.telegram.sendLocation({
+  token: 'sk_live_...',
+  chatId: '123456789',
+  latitude: -23.5505,
+  longitude: -46.6333
+});
+```
+
+#### Enviar Contato
+
+```typescript
+await sdk.telegram.sendContact({
+  token: 'sk_live_...',
+  chatId: '123456789',
+  phoneNumber: '+5511999999999',
+  firstName: 'João',
+  lastName: 'Silva'
+});
+```
+
+#### Enviar Enquete
+
+```typescript
+await sdk.telegram.sendPoll({
+  token: 'sk_live_...',
+  chatId: '123456789',
+  question: 'Qual sua cor favorita?',
+  options: ['Vermelho', 'Azul', 'Verde'],
+  isAnonymous: false
+});
+```
+
+### WebChat
+
+#### Enviar Mensagem de Texto
+
+```typescript
+await sdk.webchat.sendText({
+  token: 'sk_live_...',
+  sender: 'user123',
+  messageText: 'Olá!'
+});
+```
+
+#### Enviar Card
+
+```typescript
+await sdk.webchat.sendCard({
+  token: 'sk_live_...',
+  sender: 'user123',
+  title: 'Produto',
+  description: 'Descrição do produto',
+  imageUrl: 'https://example.com/image.jpg',
+  buttons: [
+    {
+      type: 'url',
+      title: 'Ver Mais',
+      value: 'https://example.com/product'
+    }
+  ]
+});
+```
+
+#### Enviar Formulário
+
+```typescript
+await sdk.webchat.sendForm({
+  token: 'sk_live_...',
+  sender: 'user123',
+  title: 'Formulário de Contato',
+  fields: [
+    {
+      type: 'text',
+      name: 'name',
+      label: 'Nome',
+      required: true
+    },
+    {
+      type: 'email',
+      name: 'email',
+      label: 'E-mail',
+      required: true
+    }
+  ],
+  submitButtonText: 'Enviar'
+});
+```
+
+### Facebook
+
+#### Listar Posts
+
+```typescript
+const posts = await sdk.facebook.listPosts({
+  token: 'sk_live_...',
+  pageId: 'page_id',
+  limit: 10
+});
+```
+
+#### Criar Post
+
+```typescript
+await sdk.facebook.createPost({
+  token: 'sk_live_...',
+  pageId: 'page_id',
+  message: 'Novo post!',
+  link: 'https://example.com'
+});
+```
+
+#### Enviar Mensagem
+
+```typescript
+await sdk.facebook.sendText({
+  token: 'sk_live_...',
+  recipientId: 'user_id',
+  message: 'Olá!'
+});
+```
+
+### Instagram
+
+#### Enviar Mensagem de Texto
+
+```typescript
+await sdk.instagram.sendText({
+  token: 'sk_live_...',
+  recipientId: 'user_id',
+  message: 'Olá!'
+});
+```
+
+#### Enviar Mídia
+
+```typescript
+await sdk.instagram.sendMedia({
+  token: 'sk_live_...',
+  recipientId: 'user_id',
+  fileUrl: 'https://example.com/image.jpg',
+  type: 'image',
+  caption: 'Veja esta imagem!'
+});
+```
+
+#### Enviar Resposta Privada a Comentário
+
+```typescript
+await sdk.instagram.sendPrivateReply({
+  token: 'sk_live_...',
+  commentId: 'comment_id',
+  message: 'Obrigado pelo comentário!'
+});
+```
+
+### Canais
+
+#### Listar Canais
+
+```typescript
+const channels = await sdk.channels.list();
+console.log(channels);
+```
+
+### Integrações
+
+#### Criar Webhook
+
+```typescript
+const webhook = await sdk.integrations.createWebhook({
+  url: 'https://example.com/webhook',
+  expiresInDays: 365
+});
+```
+
+## 🔐 Autenticação
+
+O SDK gerencia automaticamente a autenticação. Quando você cria uma instância do SDK, ele automaticamente:
+
+1. Obtém um token de acesso usando suas credenciais
+2. Renova o token quando necessário
+3. Adiciona o token em todas as requisições
+
+Se precisar definir um token manualmente (útil para testes):
+
+```typescript
+sdk.setAccessToken('seu-token-aqui', 86400); // expiresIn em segundos
+```
+
+Para limpar o token:
+
+```typescript
+sdk.clearToken();
+```
+
+## 🛠️ Tratamento de Erros
+
+O SDK formata todos os erros de forma consistente:
+
+```typescript
+try {
+  await sdk.whatsapp.sendText({...});
+} catch (error) {
+  console.error('Erro:', error.message);
+  console.error('Status:', error.status);
+  console.error('Detalhes:', error.details);
+}
+```
+
+## 📝 Tipos TypeScript
+
+Todos os tipos estão disponíveis para importação:
+
+```typescript
+import type {
+  SDKConfig,
+  Channel,
+  SendWhatsAppTextParams,
+  ApiResponse,
+  // ... outros tipos
+} from '@oficialapi/sdk';
+```
+
+## 🔄 Retry Automático
+
+O SDK possui retry automático configurável:
+
+- **maxRetries**: Número máximo de tentativas (padrão: 3)
+- **retryDelay**: Delay entre tentativas em ms (padrão: 1000)
+
+O retry é aplicado automaticamente em:
+- Erros de rede
+- Erros 5xx (erros do servidor)
+- Timeouts
+
+## 📖 Documentação Completa
+
+Para mais informações, consulte a [documentação completa da API](https://api.oficialapi.com.br/api/docs).
+
+## 🤝 Suporte
+
+Para suporte, entre em contato através do [painel administrativo](https://access.oficialapi.com.br) ou abra uma issue no repositório.
+
+## 📄 Licença
+
+MIT