Skip to content

fix: align the SDK with the current API and docs (v0.1.1) - #1

Merged
pedrohrod merged 1 commit into
mainfrom
fix/align-with-api-docs
Oct 17, 2026
Merged

pedrohrod merged 1 commit into
mainfrom
fix/align-with-api-docs

Conversation

@pedrohrod

Copy link
Copy Markdown
Contributor

Problema

O SDK foi escrito contra um contrato antigo da API e desembrulhava data.props, que a API não envia (as entidades são serializadas planas). Contra a API atual, invoices().create/get devolviam Result.Ok(null) e as listas (invoices, events, plans, history) devolviam itens null. Os testes antigos validavam o contrato errado (createUnwrapsDataProps...).

Outras divergências com a API e a documentação:

  • customer e service.code tratados como obrigatórios; correlationId (inexistente, a API rejeita campos desconhecidos); email tipado como string.
  • Faltavam invoices().calculate e o catálogo público plans().
  • Webhook.WEBHOOK_EVENTS incluía webhook.test (não pode ser inscrito) e não tinha nfse.invoice.fiscal_discrepancy.
  • Tipos: CompanyCreateParams sem municipalityCode obrigatório, sendMunicipalReg e defaultServiceCode; Invoice sem scheduledFor; CreditPlan sem monthlyCreditAllowance; CreditTransaction com creditDelta/balanceAfter inexistentes; QuotaStatus sem reason.
  • README com texto interno ("nove SDKs"), "self-hosted first", contagem fixa de operações.

O que muda

  • Remove o desembrulho de props (UnwrapMode.DATA_PROPS deixa de existir); tipos alinhados à API e à documentação.
  • Novos: invoices().calculate e plans().list/get/quote.
  • Mudanças de API (pré-1.0, nunca publicada): CompanyCreateParams.of(...) agora recebe municipalityCode; Customer passou a (taxId, name, email, address) (os factories Customer.of(name, taxId) continuam); Options ganhou type.
  • README reescrito; versão 0.1.1.
  • Testes com fixtures planas + novos para calculate, plans e eventos de webhook.

Verificado

mvn test (61 testes, 1 skip do contract test), em JDK 27.

Não verificado

Nenhuma chamada contra uma API real (o contract test depende de CORVO_API_KEY/CORVO_BASE_URL). Java 17 não rodado localmente (a CI cobre).

Para publicar

Maven Central exige configuração que o pom.xml ainda não tem (plugins de sources/javadoc, assinatura GPG e central-publishing) e um namespace verificado para technology.corvo. Isso não está neste PR.

🤖 Generated with Claude Code

- Resources and list items come straight in data (no props wrapper): invoices().create/get no longer return null and the lists no longer return empty items
- Types follow the API: optional customer, service code and description, discount, scheduling, sendMunicipalReg, defaultServiceCode, scheduledFor, real credit transaction and plan fields, reason on QuotaStatus
- Add invoices().calculate and the public plans() catalog
- Webhook events: add fiscal_discrepancy, drop webhook.test from subscribable events
- README rewritten (drop internal notes and misleading claims)
- Version 0.1.1

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@pedrohrod
pedrohrod merged commit 286e6a9 into main Oct 17, 2026
3 checks passed
@pedrohrod
pedrohrod deleted the fix/align-with-api-docs branch October 17, 2026 12:42
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