Add automatic pix

[lucasmiranda-stark]

Summary

Adds support for the Pix Automático (Automatic Pix) feature: recurring debit authorizations and the per-cycle pulls that draw on them.

New resources

• pixPullSubscription — recurring debit authorization. Full CRUD: create (batch), get, query, page, update, cancel. Plus log sub-resource with get/query/page.
• pixPullRequest — single pull cycle against an active subscription. Full CRUD + log sub-resource (same shape).

Wiring

• Webhook event dispatch registered for subscription strings pix-pull-subscription and pix-pull-request-log.
• README usage sections + CHANGELOG entry under [Unreleased] → Added.

Test plan

All mocha integration tests run end-to-end against the sandbox:

• testPixPullSubscription.js + testPixPullSubscriptionLog.js — CRUD round-trip, subscriptionIds plural filter, Event.parse dispatch, M8 datetime empty-string normalization.
• testPixPullRequest.js + testPixPullRequestLog.js — CRUD, requestIds plural filter, M12 no parse method on resource.

Notes

• Parse tests compare error type via e.constructor.name === "InvalidSignatureError" rather than instanceof — the starkcore and sdk/error.js modules define separate InvalidSignatureError classes with different constructor identities; both carry the same .name string.
• DateTime fields normalize server-side empty strings to null before parsing.
• A couple of integration tests use permissive try/catch guards where the sandbox enforces business rules outside the SDK's contract (state-transition restrictions, receiver-only roles).

🤖 Generated with Claude Code

[raphaelvalerio-stark]

Review — pontos a endereçar antes do merge

🔴 Blockers

1. Exports de classe top-level faltando em index.js

Os módulos estão expostos (starkinfra.pixPullSubscription, starkinfra.pixPullRequest), mas as classes não — todo o resto do SDK (PixDispute, PixRequest, PixReversal, PixInfraction…) expõe ambos. Hoje new starkinfra.PixPullSubscription({...}) quebra, e os próprios exemplos do README acabam tendo que usar o caminho longo new starkinfra.pixPullSubscription.PixPullSubscription({...}).

Adicionar logo após a linha do PixInfraction em index.js:84:

exports.PixPullSubscription = exports.pixPullSubscription.PixPullSubscription;
exports.PixPullRequest = exports.pixPullRequest.PixPullRequest;

E ajustar os exemplos do README pra usar new starkinfra.PixPullSubscription({...}).

---

2. Testes ausentes de update e cancel em ambos os recursos

Métodos públicos sem cobertura nenhuma:

• tests/testPixPullSubscription.js — não testa update(id, {status: 'confirmed', senderCityCode}) nem cancel(id, reason). A regra documentada em sdk/pixPullSubscription/pixPullSubscription.js:205 ("status='confirmed' exige senderCityCode") é justamente o tipo de invariante que precisa de teste de regressão.
• tests/testPixPullRequest.js — mesmo gap. update aceita status ∈ {scheduled, denied} (sdk/pixPullRequest/pixPullRequest.js:135-145) e cancel também não é exercitado.

Padrão de referência: tests/testPixInfraction.js:96-103 usa um helper (getPixInfractionToPatch) que puxa uma entidade real do sandbox e faz o round-trip.

---

🟡 Should-fix

3. Normalização de datetime inconsistente entre os dois recursos

• sdk/pixPullSubscription/pixPullSubscription.js:76-77 normaliza "" → null em due e installmentEnd.
• sdk/pixPullRequest/pixPullRequest.js:57 não normaliza due — usa check.datetime(due) direto.

Se o servidor pode retornar string vazia no due do PixPullRequest (provável, dado que o webhook de subscription já faz isso), o parse vai estourar. Confirmar o comportamento com o backend e padronizar — ou aplica em ambos, ou remove de ambos.

---

4. Asserção do "no parse on PixPullRequest" está implícita

A descrição do PR diz que PixPullRequest intencionalmente não tem parse, mas nenhum teste falha se alguém adicionar um por engano no futuro. Duas opções razoáveis:

• adicionar assert.strictEqual(starkinfra.pixPullRequest.parse, undefined) em tests/testPixPullRequest.js; ou
• deixar um comentário curto em sdk/pixPullRequest/index.js explicando que a omissão é intencional (com o motivo).

---

5. Caminho de sucesso do parse não testado

tests/testPixPullSubscription.js:121-150 cobre só assinaturas inválidas e malformadas. Falta um test_success que confirme:

• payload válido → objeto parseado correto;
• "due": "" e "installmentEnd": "" viram null no objeto retornado (essa é a única coisa que prova a normalização do item 3 — hoje o código existe mas não há asserção que quebre se for removido).

tests/testEvent.js:7-18 serve de template.

---

🤖 Este comentário foi escrito por Claude (Opus 4.7) via Claude Code.