@sinnu-dev/sdk 0.0.0-stage → 0.2.1

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# Sinnu SDK para Node.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SDK oficial da [Sinnu](https://sinnu.com.br) para receber com **Pix** e **cartão de crédito**
+direto do seu sistema.
+
+Feito para **agências**, **prestadores de serviço**, **SaaS** e qualquer negócio que
+cobra clientes pela internet: gere um link de pagamento, mande para o cliente e saiba na
+hora quando o dinheiro entrou.
+
+📘 **Documentação completa:** [docs.sinnu.com.br](https://docs.sinnu.com.br)
+
+## O que dá para fazer
+
+- **Cobrar** com links de pagamento: Pix e cartão em até 12x, no checkout hospedado da Sinnu.
+- **Acompanhar** as transações: status, valor bruto, taxas e valor líquido.
+- **Estornar** uma venda pelo próprio sistema.
+- **Ser avisado** de cada pagamento por webhook, com assinatura verificada.
+
+## Instalação
+
+```bash
+npm install @sinnu-dev/sdk
+```
+
+Requer Node.js 18 ou mais recente. Funciona com TypeScript e JavaScript (ESM e CommonJS).
+
+## Primeiros passos
+
+Gere sua **chave secreta** (`sk_live_...`) no painel da Sinnu, em **Chave de API**, e guarde
+em uma variável de ambiente do servidor.
+
+> A chave secreta dá acesso à sua conta. Use só no backend: nunca no navegador nem no app.
+
+```ts
+import { Sinnu } from "@sinnu-dev/sdk";
+
+const sinnu = new Sinnu({ apiKey: process.env.SINNU_API_KEY! });
+
+const link = await sinnu.links.create({
+  title: "Consultoria inicial",
+  amountCents: 9900, // R$ 99,00
+  methods: ["pix", "credit_card"],
+  maxInstallments: 12,
+});
+
+// Envie esta URL para o seu cliente pagar.
+console.log(sinnu.checkout.url(link.slug));
+```
+
+Valores são sempre em **centavos**: `9900` é R$ 99,00.
+
+## Cobrar pedidos do seu sistema
+
+O link é o produto e pode ser vendido muitas vezes. Para saber qual pedido cada venda
+pagou, abra o checkout com a referência do pedido:
+
+```ts
+const link = await sinnu.links.create({
+  title: "Consultoria inicial",
+  amountCents: 9900,
+  externalReference: "CONSULTORIA-1H", // código do produto no seu sistema
+  redirectUrl: "https://sualoja.com.br/obrigado", // ou o deep link do app: meuapp://pedido
+});
+
+// Um checkout por pedido: a referência volta na transação e no webhook.
+const url = sinnu.checkout.url(link.slug, { reference: "pedido-123" });
+```
+
+Depois do pagamento confirmado, o comprador volta para o `redirectUrl` (liberado por empresa:
+confirme com a Sinnu se já está ativo para a sua) com
+`transactionId`, `reference` e `status=approved` na query. Use esses parâmetros só para
+mostrar a tela certa: libere o pedido pelo webhook ou por `transactions.get(transactionId)`.
+
+## Acompanhar transações
+
+```ts
+const page = await sinnu.transactions.list({ status: "approved" });
+console.log(`${page.total} vendas aprovadas`);
+
+// Ou percorra todas as páginas:
+for await (const tx of sinnu.transactions.listAll({ status: "approved" })) {
+  console.log(tx.id, tx.method, tx.amount, tx.net);
+}
+```
+
+## Estornar uma venda
+
+O estorno é sempre do valor total da transação. A chave precisa do escopo `transactions:refund`; sem ele, a API responde `403`.
+
+```ts
+const tx = await sinnu.transactions.refund("ID_DA_TRANSACAO", {
+  reason: "Pedido cancelado pelo cliente",
+});
+```
+
+## Receber webhooks
+
+A Sinnu avisa seu sistema a cada evento de pagamento. Verifique a assinatura com o
+**corpo cru** da requisição antes de processar:
+
+```ts
+import { constructEvent, SinnuWebhookSignatureError } from "@sinnu-dev/sdk";
+
+try {
+  const event = constructEvent({
+    payload: rawBody,
+    signature: req.headers["x-sinnu-signature"],
+    secret: process.env.SINNU_WEBHOOK_SECRET!,
+  });
+
+  if (event.type === "transaction.approved") {
+    // event.data.reference é o pedido do seu sistema (o ?ref= do checkout):
+    // libere o pedido, envie o acesso, emita a nota...
+  }
+} catch (err) {
+  if (err instanceof SinnuWebhookSignatureError) {
+    // assinatura inválida: responda 400 e descarte
+  }
+}
+```
+
+## Tratamento de erros
+
+Toda falha da API vira um `SinnuError` (ou uma subclasse), com o status HTTP em
+`statusCode`:
+
+```ts
+import { SinnuAuthError, SinnuError, SinnuValidationError } from "@sinnu-dev/sdk";
+
+try {
+  await sinnu.links.create({ title: "Teste", amountCents: 500 });
+} catch (err) {
+  if (err instanceof SinnuAuthError) console.error("Chave de API inválida");
+  else if (err instanceof SinnuValidationError) console.error(err.body);
+  else if (err instanceof SinnuError) console.error(err.statusCode, err.message);
+}
+```
+
+Também existem `SinnuNotFoundError` e `SinnuRateLimitError`.
+
+## Recursos
+
+| Recurso | Métodos |
+|---|---|
+| `sinnu.links` | `create`, `get`, `update`, `archive`, `list`, `listAll`, `transactions` |
+| `sinnu.transactions` | `list`, `listAll`, `get`, `refund` |
+| `sinnu.checkout` | `url` |
+| `sinnu.webhooks` | `constructEvent`, `verifySignature`, `computeSignature` |
+
+Para chamar direto qualquer rota da API pública com tipos, use `sinnu.http`.
+
+## Links úteis
+
+- [Guia do SDK](https://docs.sinnu.com.br/sdk)
+- [Início rápido](https://docs.sinnu.com.br/guias/inicio-rapido)
+- [Autenticação](https://docs.sinnu.com.br/guias/autenticacao)
+- [Webhooks](https://docs.sinnu.com.br/guias/webhooks)
+- [Referência da API](https://docs.sinnu.com.br/api-reference)
+
+## Licença
+
+MIT