Skip to content

fix: alinha SDK Java com a API por chave e publica no Maven Central (2.0.0) - #5

Merged
micaelmrq merged 13 commits into
mainfrom
fix/align-api-2026-09
Sep 25, 2026
Merged

micaelmrq merged 13 commits into
mainfrom
fix/align-api-2026-09

Conversation

@micaelmrq

@micaelmrq micaelmrq commented Sep 24, 2026 •

Copy link
Copy Markdown
Member

Alinha o SDK Java com a API real por chave de API (contrato de ararahq-api origin/main @ 35451b75) e passa a publicar no Maven Central. Versão 1.8.1 → 2.0.0 (tem remoções).

P0

  • Idempotência: messages.send, messages.sendBatch e campaigns.create sempre mandam Idempotency-Key. Se quem chama não passa chave, o SDK gera um UUID v4 e usa a mesma chave em todos os retries. Há também uma sobrecarga send(request, key) / create(request, key). O RetryInterceptor nunca repete POST/PATCH sem a chave. Antes disso, um timeout ou 5xx virava envio duplicado e cobrado.
  • Templates por id: getById, getStatus, delete e analytics recebem o UUID. Não existe getByName: o README manda usar list(name, ...).
  • Paginação: PaginatedResponse<T> (data + pagination) em templates.list e smartLinks.list, que antes quebravam sempre na desserialização. CampaignPage (content/totalPages/totalElements) em campaigns.list. Wallet já seguia esse formato.
  • Removidos: UserService (/users/me → 403 por chave) e ApiKeyService (403 RESOURCE_FORBIDDEN), com UpdateUserRequest e GeneratedApiKey. Entrou AuthService.me() → GET /auth/me. O Java não tinha webhook de organização.
  • Receiver flexível: aceita whatsapp:+55..., +55... e só dígitos, com a mesma regra da API (tira whatsapp:, 7 a 15 dígitos).
  • Erros: AraraApiException expõe getCode(), getDetails() e getRetryAfter(). 403 PLAN_FEATURE_LOCKED vira PlanFeatureLockedException (feature, currentPlan, upgradeTo). 401, e 403 sem código, viram AraraAuthException, e isso inclui o corpo padrão do Spring que o filtro de chave devolve. 403 com código de negócio vira AraraApiException com o código.

P1 e higiene

  • messages.sendBatch (limite de 1000 conferido no cliente), messages.listByBatch, campaigns.list/cancel, templates.analytics (global e por id), OptOutService (/v1/opt-outs), CampaignRequest.scheduledAt, CreateTemplateRequest.headerType, MessageResponse.reason.
  • Query e telefone no path agora saem codificados na URL (QueryString). Antes, q com &, # ou + corrompia a query.
  • O README documenta quais recursos pedem chave ADMIN (auth.me, contacts, conversations, wallet, optOuts, organizations). CHANGELOG.md criado.
  • Testes: os testes de serviço que mockavam o próprio client (e confirmavam os bugs) foram reescritos contra MockWebServer. Cada um confere método, path com query, Authorization, Idempotency-Key, body JSON e parse real da resposta.

Publicação

  • Plugin com.vanniktech.maven.publish 0.34.0 → Sonatype Central Portal, com assinatura GPG em memória. O POM tem scm, licenses, developers, sources e javadoc.
  • O workflow maven-publish.yml roda em push na main e em workflow_dispatch (PR só faz build). Ele faz build, checa se repo1.maven.org/.../arara-java-sdk/<versão>/*.pom existe e, se a versão for nova, faz publishAndReleaseToMavenCentral, depois GitHub Packages, depois a tag vX.Y.Z e gh release create --generate-notes. Versão já publicada: pula.

O que o founder precisa cadastrar antes do merge

  1. Conta em https://central.sonatype.com (login com o GitHub da ararahq serve).
  2. Namespace com.ararahq verificado: Namespaces → Add e depois o registro TXT que o Portal mostrar no DNS de ararahq.com. io.github.ararahq seria verificado pelo GitHub, mas mudaria o groupId, então fica o DNS.
  3. Account → Generate User Token: usuário e senha do token viram os secrets MAVEN_CENTRAL_USERNAME e MAVEN_CENTRAL_PASSWORD do repo.
  4. Chave GPG: gpg --quick-gen-key "Arara HQ <suporte@ararahq.com>" rsa4096 sign 2y, depois gpg --keyserver keyserver.ubuntu.com --send-keys <ID> e gpg --armor --export-secret-keys <ID>. A saída ASCII inteira vai no secret GPG_PRIVATE_KEY e a senha em GPG_PASSPHRASE.
  5. Sem esses secrets, o merge na main falha no passo de publicação, com o build verde.

Pendente

  • Não publicado ainda (depende dos itens acima). O 1.8.1 continua só no GitHub Packages.
  • Fora do escopo desta rodada: templates.usage/recreate/sync/library, campaigns.estimate, contacts segments/export/lgpd, wallet.calculate/receipt, saldo (/dashboard/wallet/balance), números reactivatable/reactivate, media/upload e, em SendMessageRequest, type/replyTo/interactive/location/reaction.
  • Sem prova contra a API real. Tudo foi validado com servidor fake montado a partir do contrato.

Prova

$ ./gradlew build
> Task :test            119 testes, 0 falhas, 0 ignorados (após correções da revisão)
> Task :jacocoTestCoverageVerification   (mínimo 80%)
BUILD SUCCESSFUL
Cobertura: linhas 94,5%, branches 84,1%, instruções 93,2%
$ ./gradlew publishToMavenLocal   (sem assinatura) -> jar, sources, javadoc, module e pom com scm/licenses/developers gerados

Correções da revisão (16 itens)

CampaignListItem/CampaignResponse com scheduledAt/createdAt; getById → CampaignDetail; chave de idempotência em branco recusada e com trim; Retry-After acima de 30 s não espera; teste de retry de POST após queda de conexão (mesma chave e body); 403 vazio em GET /v1/messages/{id} → NOT_FOUND; error plano só vira code se casar ^[A-Z][A-Z0-9_]+$; api key em branco recusada; workflow checa Central, Packages, tag e release separados, falha se faltar secret e publica numa invocação única; jars reproduzíveis; artifactId lido do settings.gradle; getters corretos no README/CHANGELOG; smart-link valida e codifica id; item nulo em lote/campanha falha com índice.

@micaelmrq
micaelmrq merged commit c42ec6b into main Sep 25, 2026
2 checks passed
@micaelmrq
micaelmrq deleted the fix/align-api-2026-09 branch September 25, 2026 01:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant