vitrin 0.2.0__tar.gz → 0.2.2__tar.gz

vitrin-0.2.2/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog — vitrin
+
+## 0.2.2 — 2026-08-26
+
+### Corrigido
+- **Retry em timeout deixa de duplicar cobrança.** O client retentava em
+  timeout e erro de rede em qualquer método, apesar de a documentação
+  prometer "429 e 5xx". Timeout é justamente o caso em que o servidor
+  recebeu e processou o pedido — só a resposta se perdeu —, então cada
+  retry de um `POST /charges/` criava uma cobrança nova. Sem
+  `idempotency_key`, um clique podia virar até 4 débitos.
+
+  Agora só retentamos quando é seguro: métodos idempotentes por HTTP
+  (GET/HEAD/PUT/DELETE) sempre, e POST/PATCH apenas com `idempotency_key`
+  — aí o servidor reconhece a repetição e devolve a mesma resposta.
+
+  **Passe `idempotency_key` nas chamadas que criam cobrança.** Sem ela,
+  uma falha de rede agora vira erro em vez de cobrança duplicada, que é o
+  comportamento correto mas significa que o retry passa a ser seu.
+
+## 0.2.1 — 2026-06-29
+
+### Documentação
+- README: seção "Organizações LLC (US)" — USD, cartão + PIX cross-border,
+  liquidação `auto_payout`, onboarding/KYC. O SDK é passthrough (retorna
+  `dict`), então os campos LLC (`currency`, `client_secret`,
+  `presentment_*`) já vêm nas respostas sem mudança de código.
+
+## 0.2.0 — 2026-05-16
+
+### Adicionado
+- `customers.save_card()` / `saved_card()` / `delete_saved_card()` —
+  tokenização + persistência de cartão preferido (one-click buy).
+  Requer `consent` com `accepted_at` + `ip` (LGPD).
+- `customers.saved_card_management_link()` — gera URL com JWT 24h pro
+  cliente final ver/remover o próprio cartão.
+- `charges.create_with_saved_card()` — cobrança one-click server-side
+  (sem CVV) usando o token salvo.
+- `customers.one_click_link()` — gera link assinado de recompra (JWT
+  15min, uso único) pra o cliente final confirmar a compra com 1 clique
+  numa página hospedada pela Vitrin. Aceita `coupon_code` e `bump_ids`
+  (só produto).
+
+## 0.1.0 — Release inicial

{vitrin-0.2.0 → vitrin-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vitrin
-Version: 0.2.0
+Version: 0.2.2
 Summary: SDK oficial Python para a API da Vitrin Digital
 Project-URL: Homepage, https://vitrin.digital
 Project-URL: Documentation, https://vitrin.digital/docs/integracao
@@ -53,6 +53,17 @@ vitrin = Vitrin(
 
 Use `vd_test_*` em desenvolvimento, `vd_live_*` em produção.
 
+## Organizações LLC (US)
+
+Se a org é uma **US LLC** (`entity_type == "llc"`), os valores são em **USD**
+(campo `currency` nas transações); os métodos default são **cartão** e **Pix
+cross-border** (o cliente paga em BRL, a LLC recebe em USD). A liquidação é
+**automática**: os endpoints de saldo/recebíveis/transferências retornam
+`{ "auto_payout": true }` em vez de saldo retido (não há saque/antecipação
+manual; o cronograma "PIX D+1 / Boleto D+2 / Cartão Nx D+30" abaixo é só para
+CNPJ). O onboarding inclui verificação de identidade (KYC). Veja
+`docs/api/onboarding-llc.md` e `docs/api/differences-cnpj-llc.md`.
+
 ## Recursos
 
 ### Clientes
@@ -164,6 +175,10 @@ Retry automático em **429** e **5xx** com backoff exponencial (default: 3 tenta
 
 Inclua `idempotency_key` em POSTs sensíveis. Se o request chegar duas vezes (retry de rede, deploy etc), a Vitrin reconhece pela chave e devolve a mesma resposta — sem cobrar duas vezes.
 
+Vale em `charges.create()` e `charges.create_with_saved_card()`. A chave é escopada por organização (a sua nunca colide com a de outro lojista) e aceita até 128 caracteres.
+
+Use um identificador **seu** e estável — número do pedido, id do carrinho. A proteção vem de a chave se repetir no retry; um UUID novo a cada tentativa não protege de nada.
+
 ```python
 vitrin.charges.create(
     customer_id="cus_1",

{vitrin-0.2.0 → vitrin-0.2.2}/README.md

@@ -25,6 +25,17 @@ vitrin = Vitrin(
 
 Use `vd_test_*` em desenvolvimento, `vd_live_*` em produção.
 
+## Organizações LLC (US)
+
+Se a org é uma **US LLC** (`entity_type == "llc"`), os valores são em **USD**
+(campo `currency` nas transações); os métodos default são **cartão** e **Pix
+cross-border** (o cliente paga em BRL, a LLC recebe em USD). A liquidação é
+**automática**: os endpoints de saldo/recebíveis/transferências retornam
+`{ "auto_payout": true }` em vez de saldo retido (não há saque/antecipação
+manual; o cronograma "PIX D+1 / Boleto D+2 / Cartão Nx D+30" abaixo é só para
+CNPJ). O onboarding inclui verificação de identidade (KYC). Veja
+`docs/api/onboarding-llc.md` e `docs/api/differences-cnpj-llc.md`.
+
 ## Recursos
 
 ### Clientes
@@ -136,6 +147,10 @@ Retry automático em **429** e **5xx** com backoff exponencial (default: 3 tenta
 
 Inclua `idempotency_key` em POSTs sensíveis. Se o request chegar duas vezes (retry de rede, deploy etc), a Vitrin reconhece pela chave e devolve a mesma resposta — sem cobrar duas vezes.
 
+Vale em `charges.create()` e `charges.create_with_saved_card()`. A chave é escopada por organização (a sua nunca colide com a de outro lojista) e aceita até 128 caracteres.
+
+Use um identificador **seu** e estável — número do pedido, id do carrinho. A proteção vem de a chave se repetir no retry; um UUID novo a cada tentativa não protege de nada.
+
 ```python
 vitrin.charges.create(
     customer_id="cus_1",

{vitrin-0.2.0 → vitrin-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "vitrin"
-version = "0.2.0"
+version = "0.2.2"
 description = "SDK oficial Python para a API da Vitrin Digital"
 readme = "README.md"
 requires-python = ">=3.10"

{vitrin-0.2.0 → vitrin-0.2.2}/src/vitrin/_client.py

@@ -4,6 +4,10 @@ Wrapper sobre `requests.Session` com:
 - Headers padrão (Authorization, User-Agent, Content-Type)
 - Mapeamento de status HTTP → :class:`vitrin.errors.VitrinError`
 - Retry automático em 429/5xx com backoff exponencial e jitter
+- Retry em timeout/erro de rede SÓ quando é seguro: método idempotente
+  (GET/HEAD/PUT/DELETE) ou POST/PATCH com ``idempotency_key``. Sem isso o
+  retry de um POST cria uma segunda cobrança — o timeout não diz que o
+  servidor deixou de processar, só que a resposta se perdeu.
 - Idempotency-Key opcional pra POSTs
 """
 
@@ -77,13 +81,13 @@ class Client:
                 )
             except requests.exceptions.Timeout as e:
                 last_exc = VitrinNetworkError(f'Timeout após {self.timeout}s')
-                if attempt < self.max_retries:
+                if attempt < self.max_retries and _pode_retentar(method, idempotency_key):
                     time.sleep(_backoff(attempt))
                     continue
                 raise last_exc from e
             except requests.exceptions.RequestException as e:
                 last_exc = VitrinNetworkError(str(e))
-                if attempt < self.max_retries:
+                if attempt < self.max_retries and _pode_retentar(method, idempotency_key):
                     time.sleep(_backoff(attempt))
                     continue
                 raise last_exc from e
@@ -186,6 +190,23 @@ def _parse_retry_after(value: str | None) -> float | None:
         return None
 
 
+
+_METODOS_IDEMPOTENTES = frozenset({'GET', 'HEAD', 'PUT', 'DELETE', 'OPTIONS'})
+
+
+def _pode_retentar(method: str, idempotency_key: str | None) -> bool:
+    """Se é seguro repetir a chamada depois de timeout ou falha de rede.
+
+    Diferente de um 5xx, que garante que o servidor NÃO concluiu, um timeout
+    não diz nada: o pedido pode ter sido processado e só a resposta ter se
+    perdido. Repetir um POST nesse estado duplica o efeito — em cobrança,
+    duplica o débito. Com `idempotency_key` o servidor reconhece a repetição e
+    devolve a mesma resposta, então aí é seguro.
+    """
+    if method.upper() in _METODOS_IDEMPOTENTES:
+        return True
+    return bool(idempotency_key)
+
 def _backoff(attempt: int) -> float:
     base = 0.25 * (2 ** attempt)
     return base + random.uniform(0, base * 0.5)

{vitrin-0.2.0 → vitrin-0.2.2}/tests/test_client.py

@@ -1,11 +1,13 @@
 """Testes do client HTTP (mocked com responses)."""
 
 import pytest
+import requests
 import responses
 
 from vitrin import (
     Vitrin,
     VitrinAuthError,
+    VitrinNetworkError,
     VitrinNotFoundError,
     VitrinRateLimitError,
     VitrinServerError,
@@ -134,3 +136,62 @@ def test_customers_namespaces_exposed():
                   json={'id': 'cus_x', 'name': 'Maria'}, status=200)
     v = Vitrin(api_key='k')
     assert v.customers.retrieve('cus_x')['name'] == 'Maria'
+
+
+# ── Retry em timeout / erro de rede ───────────────────────────────────
+#
+# Timeout é o caso em que o servidor MUITO PROVAVELMENTE recebeu e processou o
+# pedido — o que não chegou foi a resposta. Retentar um POST assim cria uma
+# segunda cobrança. Medido na produção da Vitrin em 26/08/2026: o POST
+# /charges/ tem p50 de 2,3s e cauda até 16,9s, e integrador com timeout curto
+# gerava cobrança duplicada exatamente por esse caminho.
+#
+# Regra: GET/HEAD/PUT/DELETE são idempotentes por HTTP e podem ser retentados.
+# POST e PATCH só com `idempotency_key`, que faz o servidor devolver a mesma
+# resposta em vez de agir duas vezes.
+
+
+@responses.activate
+def test_post_sem_chave_nao_retenta_em_timeout():
+    responses.add(
+        responses.POST, f'{BASE}/charges/',
+        body=requests.exceptions.Timeout('estourou'),
+    )
+    with pytest.raises(VitrinNetworkError):
+        Vitrin(api_key='k', max_retries=3).request('/charges/', method='POST', body={})
+    assert len(responses.calls) == 1
+
+
+@responses.activate
+def test_post_com_chave_retenta_em_timeout():
+    responses.add(
+        responses.POST, f'{BASE}/charges/',
+        body=requests.exceptions.Timeout('estourou'),
+    )
+    with pytest.raises(VitrinNetworkError):
+        Vitrin(api_key='k', max_retries=2).request(
+            '/charges/', method='POST', body={}, idempotency_key='pedido-1',
+        )
+    assert len(responses.calls) == 3  # 1 inicial + 2 retries
+
+
+@responses.activate
+def test_get_retenta_em_timeout():
+    responses.add(
+        responses.GET, f'{BASE}/transactions/',
+        body=requests.exceptions.Timeout('estourou'),
+    )
+    with pytest.raises(VitrinNetworkError):
+        Vitrin(api_key='k', max_retries=2).request('/transactions/')
+    assert len(responses.calls) == 3
+
+
+@responses.activate
+def test_post_sem_chave_nao_retenta_em_erro_de_rede():
+    responses.add(
+        responses.POST, f'{BASE}/charges/',
+        body=requests.exceptions.ConnectionError('conexão caiu'),
+    )
+    with pytest.raises(VitrinNetworkError):
+        Vitrin(api_key='k', max_retries=3).request('/charges/', method='POST', body={})
+    assert len(responses.calls) == 1

vitrin-0.2.0/CHANGELOG.md

@@ -1,18 +0,0 @@
-# Changelog — vitrin
-
-## 0.2.0 — 2026-05-16
-
-### Adicionado
-- `customers.save_card()` / `saved_card()` / `delete_saved_card()` —
-  tokenização + persistência de cartão preferido (one-click buy).
-  Requer `consent` com `accepted_at` + `ip` (LGPD).
-- `customers.saved_card_management_link()` — gera URL com JWT 24h pro
-  cliente final ver/remover o próprio cartão.
-- `charges.create_with_saved_card()` — cobrança one-click server-side
-  (sem CVV) usando o token salvo.
-- `customers.one_click_link()` — gera link assinado de recompra (JWT
-  15min, uso único) pra o cliente final confirmar a compra com 1 clique
-  numa página hospedada pela Vitrin. Aceita `coupon_code` e `bump_ids`
-  (só produto).
-
-## 0.1.0 — Release inicial