Skip to content

fix(sdk): align with api contract and publish on main (2.0.0) - #6

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 ararahq-sdk ao contrato real da API por chave (origin/main @ 35451b75) e passa a publicar no PyPI a cada push na main. Versão 1.8.1 → 2.0.0 (tem quebras, ver CHANGELOG.md).

P0

  • Idempotência: messages.send, messages.send_batch e campaigns.create sempre mandam Idempotency-Key (a do caller via idempotency_key=, ou um UUID v4 por chamada). A chave vai no header da chamada, então todo retry dela reaproveita a mesma. O http client só repete POST/PATCH que levam a chave; GET/PUT/DELETE continuam repetindo livremente.
  • Template por id: get/get_status/delete/analytics recebem o UUID. Busca por nome = templates.list(name=...) (documentado).
  • Paginação: templates.list e smart_links.list devolvem Page (data + pagination) com page/size (e name/status em templates). Antes lançavam sempre. Campanhas usam {content,totalPages,totalElements}.
  • Removidos: payments, brain, organizations, users, api_keys (403/404 por chave). Entrou auth.me() → GET /auth/me.
  • Erros: todo erro traz status_code/code/message/details/retry_after. 403 PLAN_FEATURE_LOCKED → AraraPlanFeatureLockedError (feature, current_plan, upgrade_to); 403 com outro código → AraraApiError; 403 sem envelope (corpo Spring/vazio: chave sem permissão, fora da allowlist) → AraraForbiddenError; 401 → AraraAuthError; 422 → AraraUnprocessableError. Chave de idempotência em branco conta como ausente.
  • Específicos: CreateTemplateRequest manda body (+ header/headerType/footer/buttons/samples/variableExamples/carouselCards); structureJson saiu. MessageResponse.cost opcional e com reason.

P1 feito

  • messages.send_batch (≤1000, validado local) e messages.list_by_batch.
  • campaigns.list/get/cancel; CampaignRequest com scheduled_at e ab_test.
  • templates.analytics.
  • opt_outs (list/create/get/delete, telefone URL-encoded).
  • README diz que contacts, conversations, wallet e auth.me exigem chave ADMIN.

Higiene

  • Configuração e modelos sem class Config / Field(env=...) (pytest agora sai sem warning de depreciação).
  • Resposta 200 sem corpo (cancelar campanha) devolve None em vez de quebrar no parse.
  • README sem emoji e reescrito para a superfície nova; CHANGELOG.md; .DS_Store no .gitignore.
  • Novo ci.yml (PR na main: ruff + pytest + build em 3.9 e 3.12).

Pendente

  • Não cobertos nesta rodada: campaigns.estimate, templates.recreate/library/sync/usage, contacts segments/export, wallet/calculate, organizations/me/plan, media/upload.
  • opt_outs e templates.analytics devolvem dict: a API responde Map/Any e o shape não foi fixado no contrato.
  • Timeout padrão continua 30s (mudar para ~10s é mudança de comportamento, fica para decisão).
  • dist/ e htmlcov/ locais antigos não são versionados (já estavam no .gitignore).

Pro founder cadastrar antes do merge (senão o publish falha)

  1. PyPI → projeto ararahq-sdk → Manage → Publishing → Add a new publisher (GitHub):
    • Owner: ararahq
    • Repository: arara-python-sdk
    • Workflow: pypi-publish.yml
    • Environment: pypi
  2. GitHub → Settings → Environments → criar pypi (se ainda não existe).
    O job publish tem só id-token: write + contents: read; tag e release rodam num job release separado com contents: write. O gate publica só com 404 do PyPI, pula com 200 e falha com qualquer outro status. Depois do merge, o workflow roda na main, vê que 2.0.0 não existe no PyPI, publica, cria a tag v2.0.0 e o release com os artefatos.

Prova (local, Python 3.12)

$ python -m pytest
71 passed in 4.87s
Required test coverage of 80.0% reached. Total coverage: 89.02%

$ ruff check arara_api_sdk
All checks passed!

$ python -m build
Successfully built ararahq_sdk-2.0.0.tar.gz and ararahq_sdk-2.0.0-py3-none-any.whl

@micaelmrq
micaelmrq merged commit 1ca9b8e 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