@sinnu-dev/sdk 0.0.0-stage → 0.2.0

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.
+
+```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

package/dist/index.cjs

@@ -0,0 +1,446 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Checkout: () => Checkout,
+  DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  DEFAULT_CHECKOUT_BASE_URL: () => DEFAULT_CHECKOUT_BASE_URL,
+  SINNU_SIGNATURE_HEADER: () => SINNU_SIGNATURE_HEADER,
+  Sinnu: () => Sinnu,
+  SinnuAuthError: () => SinnuAuthError,
+  SinnuError: () => SinnuError,
+  SinnuNotFoundError: () => SinnuNotFoundError,
+  SinnuRateLimitError: () => SinnuRateLimitError,
+  SinnuValidationError: () => SinnuValidationError,
+  SinnuWebhookSignatureError: () => SinnuWebhookSignatureError,
+  collectAll: () => collectAll,
+  computeSignature: () => computeSignature,
+  constructEvent: () => constructEvent,
+  createTypedClient: () => createTypedClient,
+  default: () => index_default,
+  paginate: () => paginate,
+  unwrap: () => unwrap,
+  verifySignature: () => verifySignature,
+  webhooks: () => webhooks
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/client.ts
+var import_openapi_fetch = __toESM(require("openapi-fetch"), 1);
+
+// src/errors.ts
+var SinnuError = class extends Error {
+  constructor(message, statusCode, body, response) {
+    super(message);
+    this.name = "SinnuError";
+    this.statusCode = statusCode;
+    this.body = body;
+    this.response = response;
+  }
+};
+var SinnuAuthError = class extends SinnuError {
+  constructor(message, statusCode = 401, body, response) {
+    super(message, statusCode, body, response);
+    this.name = "SinnuAuthError";
+  }
+};
+var SinnuNotFoundError = class extends SinnuError {
+  constructor(message, body, response) {
+    super(message, 404, body, response);
+    this.name = "SinnuNotFoundError";
+  }
+};
+var SinnuValidationError = class extends SinnuError {
+  constructor(message, statusCode, body, response) {
+    super(message, statusCode, body, response);
+    this.name = "SinnuValidationError";
+  }
+};
+var SinnuRateLimitError = class extends SinnuError {
+  constructor(message, body, response) {
+    super(message, 429, body, response);
+    this.name = "SinnuRateLimitError";
+  }
+};
+function toSinnuError(statusCode, body, response) {
+  const message = body?.message ?? `Requisi\xE7\xE3o falhou com status ${statusCode}`;
+  switch (statusCode) {
+    case 401:
+    case 403:
+      return new SinnuAuthError(message, statusCode, body, response);
+    case 404:
+      return new SinnuNotFoundError(message, body, response);
+    case 400:
+    case 422:
+      return new SinnuValidationError(message, statusCode, body, response);
+    case 429:
+      return new SinnuRateLimitError(message, body, response);
+    default:
+      return new SinnuError(message, statusCode, body, response);
+  }
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.sinnu.com.br";
+var API_KEY_PREFIXES = ["sk_live_"];
+function assertApiKey(apiKey) {
+  if (!apiKey || typeof apiKey !== "string") {
+    throw new Error(
+      "[@sinnu-dev/sdk] apiKey \xE9 obrigat\xF3ria. Gere uma chave secreta no painel sinnu (Integra\xE7\xF5es)."
+    );
+  }
+  if (!API_KEY_PREFIXES.some((p) => apiKey.startsWith(p))) {
+    console.warn(
+      "[@sinnu-dev/sdk] apiKey n\xE3o come\xE7a com 'sk_live_'. Use a chave secreta no backend, nunca uma chave no cliente."
+    );
+  }
+}
+function createTypedClient(options) {
+  assertApiKey(options.apiKey);
+  return (0, import_openapi_fetch.default)({
+    baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+    fetch: options.fetch,
+    headers: {
+      Authorization: `Bearer ${options.apiKey}`,
+      "Content-Type": "application/json",
+      ...options.headers
+    }
+  });
+}
+async function unwrap(p) {
+  const { data, error, response } = await p;
+  if (error || !response.ok) {
+    throw toSinnuError(
+      response.status,
+      error ?? void 0,
+      response
+    );
+  }
+  if (data === void 0 || data === null) {
+    throw toSinnuError(response.status, { message: "Resposta sem corpo" }, response);
+  }
+  return data;
+}
+var RawHttp = class {
+  constructor(baseUrl, apiKey, extraHeaders, fetchImpl) {
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.extraHeaders = extraHeaders;
+    this.fetchImpl = fetchImpl;
+  }
+  async request(path, options = {}) {
+    const url = new URL(path.replace(/^\//, ""), ensureTrailingSlash(this.baseUrl));
+    if (options.query) {
+      for (const [key, value] of Object.entries(options.query)) {
+        if (value !== void 0) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    const response = await this.fetchImpl(url.toString(), {
+      method: options.method ?? "GET",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        ...this.extraHeaders
+      },
+      body: options.body !== void 0 ? JSON.stringify(options.body) : void 0
+    });
+    const text = await response.text();
+    const parsed = text ? safeJsonParse(text) : void 0;
+    if (!response.ok) {
+      throw toSinnuError(response.status, parsed, response);
+    }
+    return parsed;
+  }
+};
+function ensureTrailingSlash(url) {
+  return url.endsWith("/") ? url : `${url}/`;
+}
+function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+// src/resources/checkout.ts
+var DEFAULT_CHECKOUT_BASE_URL = "https://pay.sinnu.com.br";
+var Checkout = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  /**
+   * Monta a URL pública do checkout hosted para um `slug` (8 chars) gerado
+   * ao criar um link (`sinnu.links.create(...).url` já vem pronto; este
+   * helper é útil quando você só tem o slug).
+   *
+   * @example
+   * const url = sinnu.checkout.url("abcd1234", { reference: "pedido-123" });
+   * // => "https://pay.sinnu.com.br/abcd1234?ref=pedido-123"
+   */
+  url(slug, options = {}) {
+    if (!slug || typeof slug !== "string") {
+      throw new Error("[@sinnu-dev/sdk] slug do checkout \xE9 obrigat\xF3rio.");
+    }
+    const base = options.checkoutBaseUrl ?? this.options.checkoutBaseUrl ?? DEFAULT_CHECKOUT_BASE_URL;
+    const url = new URL(encodeURIComponent(slug), ensureTrailingSlash2(base));
+    const query = { ...this.options.query, ...options.query };
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== void 0) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+    if (options.reference !== void 0) {
+      if (options.reference.length > 255) {
+        throw new Error("[@sinnu-dev/sdk] reference tem no m\xE1ximo 255 caracteres.");
+      }
+      url.searchParams.set("ref", options.reference);
+    }
+    return url.toString();
+  }
+};
+function ensureTrailingSlash2(url) {
+  return url.endsWith("/") ? url : `${url}/`;
+}
+
+// src/pagination.ts
+async function* paginate(fetchPage) {
+  let page = 1;
+  let seen = 0;
+  while (true) {
+    const result = await fetchPage(page);
+    for (const item of result.data) {
+      yield item;
+    }
+    seen += result.data.length;
+    const pageSize = result.pageSize || result.data.length;
+    if (result.data.length === 0 || seen >= result.total || pageSize === 0) {
+      return;
+    }
+    page += 1;
+  }
+}
+async function collectAll(fetchPage) {
+  const out = [];
+  for await (const item of paginate(fetchPage)) {
+    out.push(item);
+  }
+  return out;
+}
+
+// src/resources/links.ts
+var Links = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Cria um link de pagamento (valor em centavos). */
+  async create(body) {
+    return this.http.request("/api/payment-links", {
+      method: "POST",
+      body
+    });
+  }
+  /** Busca um link de pagamento pelo id. */
+  async get(id) {
+    return this.http.request(`/api/payment-links/${encodeURIComponent(id)}`);
+  }
+  /** Atualiza parcialmente um link de pagamento. */
+  async update(id, body) {
+    return this.http.request(`/api/payment-links/${encodeURIComponent(id)}`, {
+      method: "PATCH",
+      body
+    });
+  }
+  /** Arquiva um link de pagamento. */
+  async archive(id) {
+    await this.http.request(`/api/payment-links/${encodeURIComponent(id)}`, {
+      method: "DELETE"
+    });
+  }
+  /** Lista links de pagamento (paginado). */
+  async list(params = {}) {
+    return this.http.request("/api/payment-links", {
+      query: { page: params.page, pageSize: params.pageSize }
+    });
+  }
+  /** Lista transações de um link de pagamento (paginado). */
+  async transactions(id, params = {}) {
+    return this.http.request(
+      `/api/payment-links/${encodeURIComponent(id)}/transactions`,
+      { query: { page: params.page, pageSize: params.pageSize } }
+    );
+  }
+  /** Itera todos os links de pagamento, página a página. */
+  listAll(params = {}) {
+    return paginate((page) => this.list({ ...params, page }));
+  }
+};
+
+// src/resources/transactions.ts
+var Transactions = class {
+  constructor(http) {
+    this.http = http;
+  }
+  /** Lista transações (paginado, com filtro opcional por status). */
+  async list(params = {}) {
+    return this.http.request("/api/transactions/", {
+      query: {
+        status: params.status,
+        search: params.search,
+        customer: params.customer,
+        page: params.page,
+        pageSize: params.pageSize
+      }
+    });
+  }
+  /** Busca uma transação pelo id. */
+  async get(id) {
+    return this.http.request(`/api/transactions/${encodeURIComponent(id)}/`);
+  }
+  /** Estorna (refund) uma transação. */
+  async refund(id, body = {}) {
+    return this.http.request(
+      `/api/transactions/${encodeURIComponent(id)}/refund/`,
+      { method: "POST", body }
+    );
+  }
+  /** Itera todas as transações, página a página. */
+  listAll(params = {}) {
+    return paginate((page) => this.list({ ...params, page }));
+  }
+};
+
+// src/webhooks.ts
+var import_node_crypto = require("crypto");
+var SINNU_SIGNATURE_HEADER = "x-sinnu-signature";
+var SinnuWebhookSignatureError = class extends SinnuError {
+  constructor(message) {
+    super(message, 0);
+    this.name = "SinnuWebhookSignatureError";
+  }
+};
+function normalizeSignature(signature) {
+  if (signature === void 0) {
+    throw new SinnuWebhookSignatureError(
+      "[@sinnu-dev/sdk] header de assinatura ausente. Esperado 'X-Sinnu-Signature'."
+    );
+  }
+  const value = Array.isArray(signature) ? signature[0] : signature;
+  if (!value) {
+    throw new SinnuWebhookSignatureError("[@sinnu-dev/sdk] header de assinatura vazio.");
+  }
+  return value.startsWith("sha256=") ? value.slice("sha256=".length) : value;
+}
+function toBuffer(payload) {
+  return typeof payload === "string" ? Buffer.from(payload, "utf8") : payload;
+}
+function computeSignature(payload, secret) {
+  return (0, import_node_crypto.createHmac)("sha256", secret).update(toBuffer(payload)).digest("hex");
+}
+function verifySignature(options) {
+  const { payload, signature, secret } = options;
+  if (!secret) {
+    throw new SinnuWebhookSignatureError(
+      "[@sinnu-dev/sdk] webhook secret \xE9 obrigat\xF3rio para verificar a assinatura."
+    );
+  }
+  const provided = normalizeSignature(signature);
+  const expected = computeSignature(payload, secret);
+  const providedBuf = Buffer.from(provided, "hex");
+  const expectedBuf = Buffer.from(expected, "hex");
+  if (providedBuf.length !== expectedBuf.length) {
+    return false;
+  }
+  return (0, import_node_crypto.timingSafeEqual)(providedBuf, expectedBuf);
+}
+function constructEvent(options) {
+  if (!verifySignature(options)) {
+    throw new SinnuWebhookSignatureError(
+      "[@sinnu-dev/sdk] assinatura de webhook inv\xE1lida. Requisi\xE7\xE3o rejeitada."
+    );
+  }
+  const text = typeof options.payload === "string" ? options.payload : options.payload.toString("utf8");
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new SinnuWebhookSignatureError("[@sinnu-dev/sdk] corpo do webhook n\xE3o \xE9 um JSON v\xE1lido.");
+  }
+}
+var webhooks = {
+  signatureHeader: SINNU_SIGNATURE_HEADER,
+  computeSignature,
+  verifySignature,
+  constructEvent
+};
+
+// src/index.ts
+var Sinnu = class {
+  constructor(options) {
+    /** Verificação de webhooks (HMAC SHA-256): não faz requisições. */
+    this.webhooks = webhooks;
+    this.http = createTypedClient(options);
+    const raw = new RawHttp(
+      options.baseUrl ?? DEFAULT_BASE_URL,
+      options.apiKey,
+      options.headers ?? {},
+      options.fetch ?? fetch
+    );
+    this.links = new Links(raw);
+    this.transactions = new Transactions(raw);
+    this.checkout = new Checkout({ checkoutBaseUrl: options.checkoutBaseUrl });
+  }
+};
+var index_default = Sinnu;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Checkout,
+  DEFAULT_BASE_URL,
+  DEFAULT_CHECKOUT_BASE_URL,
+  SINNU_SIGNATURE_HEADER,
+  Sinnu,
+  SinnuAuthError,
+  SinnuError,
+  SinnuNotFoundError,
+  SinnuRateLimitError,
+  SinnuValidationError,
+  SinnuWebhookSignatureError,
+  collectAll,
+  computeSignature,
+  constructEvent,
+  createTypedClient,
+  paginate,
+  unwrap,
+  verifySignature,
+  webhooks
+});