Skip to main content

​
SDKs de Código Aberto

A Arara acredita que a melhor experiência do desenvolvedor vem de SDKs bem construídos e mantidos pela comunidade. Por isso, incentivamos e suportamos a criação de SDKs de código aberto para diferentes linguagens e frameworks.

​
Por Que SDKs?

SDKs facilitam a integração, reduzem erros comuns, fornecem autocomplete e documentação inline, e tornam a experiência de desenvolvimento muito mais agradável. Eles são essenciais para uma excelente DX (Developer Experience).

​
SDKs Disponíveis e Planejados

Node.js/TypeScript

SDK oficial para Node.js e TypeScript

Python

SDK oficial para Python

Java

SDK oficial para Java

PHP

SDK oficial para PHP

Go

SDK oficial para Go
Não encontrou um SDK para sua linguagem favorita? Siga o guia abaixo para criar o seu próprio! SDKs da comunidade são muito bem-vindos e podem se tornar oficiais com o tempo.

​
Criando um Novo SDK

Se você quer criar um SDK para uma linguagem que ainda não tem suporte, siga este guia para garantir consistência e qualidade.

​
Regras e Diretrizes

Antes de começar, certifique-se de seguir estas regras:

​
1. Estrutura do Repositório

  • Nome: Use o padrão arara-{linguagem}-sdk (ex: arara-python-sdk, arara-java-sdk)
  • Organização: Crie o repositório na organização ararahq no GitHub (Caso não consiga, contate o suporte)
  • Licença: Use a licença MIT
  • README: Deve incluir:
    • Instalação
    • Exemplo básico de uso
    • Link para documentação completa
    • Badges (build status, version, license)

​
2. Funcionalidades Mínimas

Todo SDK deve implementar pelo menos:
  • Autenticação: Suporte a API Key via header Authorization
  • Envio de Mensagens: Método para POST /v1/messages
  • Tratamento de Erros: Classes/exceções específicas para cada tipo de erro HTTP
  • Validação: Validação básica de parâmetros antes de enviar
  • Type Safety: Tipos fortes quando a linguagem suporta (TypeScript, Java, etc.)

​
3. Padrões de Código

  • Nomenclatura: Siga as convenções da linguagem
  • Documentação: Documente todas as funções públicas
  • Testes: Inclua testes unitários e de integração
  • Exemplos: Forneça exemplos práticos no README e na documentação

​
4. Gerenciamento de Versões

  • Use Semantic Versioning (MAJOR.MINOR.PATCH)
  • Mantenha um CHANGELOG.md atualizado
  • Tag releases no GitHub

​
Passo a Passo: Criando um SDK

1

1. Planejamento

Antes de começar a codificar:
  1. Verifique se já existe: Consulte a lista de SDKs acima e o GitHub da Arara
  2. Abra uma Issue: Crie uma issue no repositório principal da Arara anunciando sua intenção
  3. Planeje a estrutura: Decida sobre:
    • Gerenciador de pacotes (npm, pip, maven, etc.)
    • Biblioteca HTTP (fetch, requests, okhttp, etc.)
    • Estrutura de pastas
    • Sistema de testes
Consulte SDKs existentes de outras APIs populares (Stripe, Twilio) na mesma linguagem para inspiração na estrutura.
2

2. Configuração Inicial

Configure o projeto básico:
  • Crie o repositório no GitHub
  • Configure o gerenciador de pacotes
  • Configure ferramentas de build/test
  • Adicione arquivos essenciais (README, LICENSE, .gitignore)
  • Configure CI/CD básico (GitHub Actions, etc.)
# Estrutura sugerida
arara-js/
├── src/
│   ├── client.ts
│   ├── resources/
│   │   └── messages.ts
│   └── types.ts
├── tests/
├── package.json
├── tsconfig.json
└── README.md
3

3. Implementação do Cliente Base

Crie a classe/função principal do cliente:
  • Inicialização: Recebe a API Key
  • Configuração HTTP: Base URL, headers padrão, timeout
  • Tratamento de Erros: Mapeamento de códigos HTTP para exceções
  • Método genérico de requisição: Para fazer chamadas HTTP
export class AraraClient {
  private apiKey: string;
  private baseURL: string = 'https://api.ararahq.com';
  
  constructor(apiKey: string) {
    if (!apiKey) {
      throw new Error('API Key is required');
    }
    this.apiKey = apiKey;
  }
  
  private async request(
    method: string,
    path: string,
    body?: any
  ): Promise<any> {
    const response = await fetch(`${this.baseURL}${path}`, {
      method,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: body ? JSON.stringify(body) : undefined,
    });
    
    if (!response.ok) {
      throw new AraraError(response.status, await response.json());
    }
    
    return response.json();
  }
}
4

4. Implementação do Recurso de Mensagens

Crie a classe/função para enviar mensagens:
  • Método send: Recebe receiver, templateName, variables
  • Validação: Valida formato do número e parâmetros obrigatórios
  • Retorno tipado: Retorna um objeto com os dados da mensagem
export interface SendMessageParams {
  receiver: string;
  templateName: string;
  variables?: string[];
}

export interface Message {
  id: string;
  receiver: string;
  templateName: string;
  status: string;
  createdAt: string;
}

export class Messages {
  constructor(private client: AraraClient) {}
  
  async send(params: SendMessageParams): Promise<Message> {
    // Validação
    if (!params.receiver.startsWith('whatsapp:+')) {
      throw new Error('Receiver must be in format whatsapp:+5583991768778');
    }
    
    return this.client.request('POST', '/v1/messages', {
      receiver: params.receiver,
      templateName: params.templateName,
      variables: params.variables || [],
    });
  }
}
5

5. Tratamento de Erros

Implemente classes de erro específicas:
  • AraraError/AraraException: Classe base
  • Erros específicos: 400, 401, 404, 422, 500
  • Mensagens claras: Erros devem ter mensagens descritivas
export class AraraError extends Error {
  constructor(
    public statusCode: number,
    public response: any
  ) {
    super(response?.message || `HTTP ${statusCode}`);
    this.name = 'AraraError';
  }
}

export class AraraAuthenticationError extends AraraError {
  constructor(response: any) {
    super(401, response);
    this.name = 'AraraAuthenticationError';
  }
}
6

6. Testes

Crie testes abrangentes:
  • Testes unitários: Para cada método
  • Testes de integração: Com a API real (use API Key de teste)
  • Testes de erro: Para cada tipo de erro HTTP
  • Cobertura: Almeje pelo menos 80% de cobertura
Use mocks para testes unitários e uma API Key de teste para testes de integração. Nunca commite API Keys reais!
7

7. Documentação e Exemplos

Documente tudo:
  • README completo: Com instalação, uso básico e exemplos
  • Documentação de API: Use ferramentas como JSDoc, Sphinx, JavaDoc
  • Exemplos práticos: Casos de uso comuns
  • CHANGELOG: Mantenha um changelog atualizado
Exemplo de README mínimo deve incluir:
  • Título e descrição do SDK
  • Seção de instalação com comandos específicos
  • Exemplo básico de uso
  • Link para documentação completa
  • Instruções de contribuição
Estrutura sugerida:
# Arara SDK para [Linguagem]

SDK oficial da Arara para [linguagem].

## Instalação
[comandos de instalação]

## Uso Básico
[exemplo de código]

## Documentação
[link para documentação completa]

## Contribuindo
[instruções de contribuição]
8

8. Publicação e Manutenção

Publique e mantenha:
  1. Publique no gerenciador de pacotes:
    • npm (Node.js)
    • PyPI (Python)
    • Maven Central (Java)
    • etc.
  2. Configure CI/CD:
    • Testes automáticos
    • Publicação automática de releases
  3. Mantenha atualizado:
    • Monitore mudanças na API
    • Atualize quando necessário
    • Responda a issues e PRs
Antes de publicar, certifique-se de que o SDK está completo, testado e documentado. Primeiras impressões são importantes!

​
Contribuindo com SDKs Existentes

Se você quer contribuir com um SDK existente:
  1. Fork o repositório do SDK
  2. Crie uma branch para sua feature/correção
  3. Siga as diretrizes de contribuição do repositório
  4. Escreva testes para suas mudanças
  5. Abra um Pull Request com descrição clara
Contribuições são sempre bem-vindas! Mesmo pequenas melhorias como correções de documentação, exemplos adicionais ou melhorias de performance são valiosas.

​
SDKs da Comunidade

SDKs criados pela comunidade também são bem-vindos! Se você criou um SDK que não está na lista oficial:
  1. Adicione na documentação: Abra um PR adicionando seu SDK na lista acima
  2. Mantenha atualizado: Certifique-se de manter o SDK compatível com a API
  3. Siga as diretrizes: Use as mesmas regras e padrões dos SDKs oficiais

​
Recursos Úteis

​
Contribuições

SDKs de código aberto são fundamentais para o sucesso da Arara. Cada contribuição, grande ou pequena, faz a diferença e ajuda a melhorar a experiência de desenvolvimento para toda a comunidade.