wyzecash 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Mudanças
+
+## 0.2.0
+
+**Mudanças que pedem ajuste no seu código:**
+
+- Saem `pix.send`, `pix.list` e `pix.retrieve`: enviar Pix e sacar são o mesmo Pix que sai, então use `withdrawals.create` (com `destination` ou `copyPaste`). A rota antiga `/v1/pix/payments` continua respondendo por enquanto, mas vai ser removida.
+- Sai `meds.downloadAttachment`: as provas do MED são internas da WyzeCash e não se baixam pela API (a rota já recusava).
+
+**Novidades:**
+
+- `meds.respond(id, { defense, evidence })`: responde um MED com a defesa e até 5 provas (em base64), num pedido só. Precisa da permissão `/meds/respond` na chave.
+- O endereço padrão passa a ser `https://api.wyzecash.com.br`. O antigo continua funcionando, e quem passa `baseUrl` não muda nada.
+- `payments.retrieve` e `withdrawals.retrieve` explicam no editor que, para saber quando a cobrança é paga ou o saque conclui, o caminho é o webhook (ou o WebSocket), não a consulta em sequência, que gasta o limite de 100 pedidos por minuto da conta. O README ganhou a seção "Saber quando foi pago".
+
+## 0.1.0
+
+Primeira versão.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 WyzeCash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,162 @@
-# Temporary Holding Version
+# wyzecash
 
-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 [WyzeCash](https://docs.wyzecash.com.br) para Node.js 20+, Bun e Deno: cobranças por Pix, cartão e cripto, links de pagamento, saldo e extrato, saques, estornos, MED, subcontas e webhooks. Sem dependências.
+
+```bash
+npm install wyzecash
+```
+
+## Começar
+
+```ts
+import WyzeCash from "wyzecash";
+
+const wyzecash = new WyzeCash(process.env.WYZECASH_API_KEY);
+
+const cobranca = await wyzecash.payments.create({
+  amount: 15000, // R$ 150,00, sempre em centavos
+  description: "Pedido #1052",
+});
+
+console.log(cobranca.copyPaste); // Pix Copia e Cola
+```
+
+A chave de API (`bk_live_…`) é criada no painel, em Integrações e API, com uma permissão por rota. Sem passar a chave, o SDK lê a variável `WYZECASH_API_KEY`.
+
+Não existe ambiente de testes: todo pedido é de verdade. Para testar, faça uma cobrança pequena.
+
+## Recursos
+
+| Recurso | Métodos |
+|---|---|
+| `payments` | `create`, `methods`, `list`, `retrieve` |
+| `paymentLinks` | `create`, `list`, `retrieve`, `update`, `delete`, `listPayments` |
+| `customers` | `create`, `list`, `retrieve`, `update`, `delete` |
+| `balance` | `retrieve` |
+| `fees` | `list`, `preview` |
+| `statement` | `list` |
+| `transactions` | `list`, `retrieve` |
+| `search` | `query` |
+| `receipts` | `retrieve` |
+| `meds` | `list`, `retrieve`, `respond` |
+| `withdrawals` | `create`, `list`, `retrieve` |
+| `refunds` | `create`, `list`, `retrieve` |
+| `subaccounts` | `create`, `list`, `retrieve`, `update`, `delete`, `retrieveSettings`, `updateSettings`, `previewSettings`, `listEntries`, `fund`, `transfer`, `returnToAccount`, `withdraw` |
+
+Todos os campos e respostas têm tipos e a descrição em português (o editor mostra ao passar o mouse).
+
+## Listas
+
+`await` traz a primeira página; `for await` passa por todas, buscando a próxima só quando precisa.
+
+```ts
+const pagina = await wyzecash.payments.list({ status: "paid", limit: 50 });
+
+for await (const cobranca of wyzecash.payments.list({ status: "paid" })) {
+  console.log(cobranca.id, cobranca.amount);
+}
+```
+
+## Idempotency-Key
+
+Criar cobrança, saque, Pix enviado, estorno e os envios das subcontas pedem a `Idempotency-Key`. Passe o código do pedido no seu sistema: repetir a mesma chave devolve o mesmo resultado, sem fazer de novo.
+
+```ts
+await wyzecash.withdrawals.create(
+  { amount: 10000, destination: { keyType: "email", key: "financeiro@exemplo.com" } },
+  { idempotencyKey: "saque-1052" },
+);
+```
+
+Sem ela, o SDK cria uma chave por chamada.
+
+## Erros e novas tentativas
+
+```ts
+import WyzeCash, { WyzeCashError } from "wyzecash";
+
+try {
+  await wyzecash.payments.create({ amount: 15000 });
+} catch (erro) {
+  if (erro instanceof WyzeCashError) console.log(erro.status, erro.code, erro.message, erro.requestId);
+}
+```
+
+- O `code` é estável (`VALIDATION`, `INSUFFICIENT_FUNDS`, `RATE_LIMITED`...) e a `message` está em português.
+- `429` (passou de 100 pedidos por minuto) volta a tentar sozinho, esperando o `Retry-After`.
+- Erro de rede e `5xx` voltam a tentar só nas consultas e na criação de cobrança.
+- O que tira dinheiro (saque, Pix enviado, estorno, envios das subcontas) **nunca** é repetido sozinho: se a rede cair, confira pela consulta ou pelo webhook antes de pedir de novo.
+
+Opções do cliente: `new WyzeCash(chave, { maxRetries: 2, timeout: 60000, baseUrl, fetch })`.
+
+## Saber quando foi pago
+
+**Use os webhooks ou o tempo real (WebSocket), não `payments.retrieve` em sequência.**
+
+Chamar a consulta da cobrança em sequência para ver se ela foi paga gasta o limite de **100 pedidos por minuto da conta** (somando todas as rotas e todas as chaves). Uma tela consultando a cada 2 segundos gasta 30 por minuto; com quatro abertas, **todo** pedido da conta, até criar cobrança, volta `429 RATE_LIMITED` até liberar. Os avisos do webhook e do WebSocket não contam no limite.
+
+- O seu sistema tem um endereço HTTPS: use os [webhooks](#webhooks) (`payment.paid`, `payment.expired`, `withdrawal.completed`...).
+- Não tem (bot de Discord ou Telegram, programa num VPS): use o [tempo real](#tempo-real-websocket), de todas as cobranças ou só de uma (`ws.subscribePayment("BKY-…")`).
+- A tela de "aguardando pagamento" pergunta ao **seu** servidor (que o webhook ou o WebSocket atualizou), nunca direto à WyzeCash: a chave de API não vai para o navegador nem para o app.
+- `payments.retrieve` só para conferir uma vez (o webhook não chegou em alguns minutos). Sem webhook nem WebSocket, consulte no máximo a cada 5 segundos e pare na primeira situação final (`paid`, `expired` ou `refunded`).
+
+## Webhooks
+
+Cada aviso chega com o cabeçalho `X-Bukio-Signature`. Confira sempre com o corpo cru, como chegou:
+
+```ts
+import { verifyWebhook } from "wyzecash";
+
+const evento = await verifyWebhook(corpoCru, request.headers["x-bukio-signature"], process.env.WYZECASH_WEBHOOK_SECRET);
+if (evento.type === "payment.paid") {
+  // marque o pedido como pago (use evento.id para não processar duas vezes)
+}
+```
+
+Aviso com assinatura errada, sem assinatura ou assinado há mais de 5 minutos lança `WyzeCashWebhookError`.
+
+### Fastify
+
+```ts
+import Fastify from "fastify";
+import { wyzecashWebhooks } from "wyzecash/fastify";
+
+const app = Fastify({ logger: true });
+
+await app.register(wyzecashWebhooks, {
+  path: "/webhooks/wyzecash",
+  secret: process.env.WYZECASH_WEBHOOK_SECRET,
+  async onEvent(evento) {
+    if (evento.type === "payment.paid") {
+      // marque o pedido como pago
+    }
+  },
+});
+
+await app.listen({ port: 3000 });
+```
+
+O plugin lê o corpo cru só na rota dele (o resto da aplicação continua lendo JSON como sempre) e responde `200` quando deu certo, `400` quando o aviso não é da WyzeCash e `500` quando o `onEvent` falha (a WyzeCash manda de novo mais tarde).
+
+## Tempo real (WebSocket)
+
+Os mesmos eventos dos webhooks, na hora, sem precisar de um endereço HTTPS seu. Use só no servidor (a chave de API vai junto):
+
+```ts
+const ws = wyzecash.realtime({ events: ["payment.*"] });
+
+ws.on("payment.paid", (evento) => {
+  // marque o pedido como pago (use evento.id para não processar duas vezes)
+});
+ws.on("error", (erro) => console.error(erro.code, erro.message));
+```
+
+- `events`: `*`, `payment.*`, `withdrawal.*`, `pix.*`, `transfer.*`, `subaccount.*` ou um evento só (`payment.paid`). A chave só recebe o que ela pode consultar; sem permissão chega o erro `FORBIDDEN`.
+- `payments: ["BKY-…"]` ou `ws.subscribePayment("BKY-…")`: só os eventos de uma cobrança, por 30 minutos ou até ela ser paga ou vencer.
+- Caiu? Conecta de novo sozinho e pede o que perdeu desde o último evento (`ws.lastEventId`, até 24 horas). Guarde esse código e passe em `since` quando o seu sistema reiniciar.
+- Chave apagada ou inválida fecha a conexão (código 1008) e não reconecta. `ws.close()` fecha de vez.
+- No Node 20, que não tem WebSocket, passe o do pacote `ws`: `wyzecash.realtime({ WebSocket })` com `import WebSocket from "ws"`.
+
+## Documentação
+
+Referência completa da API: https://docs.wyzecash.com.br

package/dist/client.d.ts

@@ -0,0 +1,42 @@
+import type { Requester, RequestOptions } from "./core.js";
+import { type OperationId, Resources } from "./generated.js";
+import { ListPromise } from "./pagination.js";
+import { RealtimeConnection, type RealtimeOptions } from "./realtime.js";
+import { Webhooks } from "./webhooks.js";
+export declare const DEFAULT_BASE_URL = "https://api.wyzecash.com.br";
+export interface ClientOptions {
+    /** A chave de API (`bk_live_…`). Sem ela, vale a variável de ambiente `WYZECASH_API_KEY`. */
+    apiKey?: string;
+    /** Endereço da API (padrão: o de produção). */
+    baseUrl?: string;
+    /** Quantas vezes tentar de novo (padrão 2). */
+    maxRetries?: number;
+    /** Tempo máximo de cada pedido, em milissegundos (padrão 60 000). */
+    timeout?: number;
+    /** Outro fetch (para testes ou proxy). */
+    fetch?: typeof fetch;
+}
+export declare class WyzeCash extends Resources implements Requester {
+    /** Conferir a assinatura dos webhooks. */
+    static readonly webhooks: Webhooks;
+    readonly webhooks: Webhooks;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly maxRetries;
+    private readonly timeout;
+    private readonly fetchImpl;
+    constructor(apiKeyOrOptions?: string | ClientOptions, maybeOptions?: ClientOptions);
+    /**
+     * Eventos na hora pelo WebSocket (os mesmos dos webhooks), sem endereço HTTPS seu. Só no servidor.
+     *
+     *   const ws = wyzecash.realtime({ events: ["payment.*"] });
+     *   ws.on("payment.paid", (e) => liberarPedido(e.data));
+     */
+    realtime(options?: RealtimeOptions): RealtimeConnection;
+    request<T>(id: OperationId, pathArgs: string[], params: object | undefined, options?: RequestOptions): Promise<T>;
+    list<P extends {
+        items: unknown[];
+        nextCursor?: string | null;
+    }, T>(id: OperationId, pathArgs: string[], params: object | undefined, options?: RequestOptions): ListPromise<P, T>;
+    private send;
+}

package/dist/client.js

@@ -0,0 +1,143 @@
+// O cliente da API da WyzeCash: `new WyzeCash(chave)` e os recursos (`wyzecash.payments.create(...)`).
+// Sem dependências: usa o fetch do Node 20+, Bun, Deno e servidores na borda.
+//
+// Novas tentativas: 429 (passou do limite) sempre volta a tentar, esperando o `Retry-After`, porque
+// a API não fez nada. Erro de rede, tempo esgotado e 5xx só voltam a tentar nas consultas e na
+// criação de cobrança (com a mesma Idempotency-Key); o que tira dinheiro (saque, Pix enviado,
+// estorno, envios das subcontas) nunca é repetido sozinho: confira pela consulta ou pelo webhook.
+import { WyzeCashConnectionError, WyzeCashError } from "./errors.js";
+import { OPERATIONS, Resources } from "./generated.js";
+import { ListPromise } from "./pagination.js";
+import { RealtimeConnection } from "./realtime.js";
+import { VERSION } from "./version.js";
+import { Webhooks } from "./webhooks.js";
+export const DEFAULT_BASE_URL = "https://api.wyzecash.com.br";
+const env = (name) => globalThis.process?.env?.[name];
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+export class WyzeCash extends Resources {
+    /** Conferir a assinatura dos webhooks. */
+    static webhooks = new Webhooks();
+    webhooks = WyzeCash.webhooks;
+    apiKey;
+    baseUrl;
+    maxRetries;
+    timeout;
+    fetchImpl;
+    constructor(apiKeyOrOptions, maybeOptions = {}) {
+        super();
+        const options = typeof apiKeyOrOptions === "string" ? { ...maybeOptions, apiKey: apiKeyOrOptions } : (apiKeyOrOptions ?? {});
+        const apiKey = options.apiKey ?? env("WYZECASH_API_KEY");
+        if (!apiKey)
+            throw new Error("Passe a chave de API: new WyzeCash(process.env.WYZECASH_API_KEY).");
+        this.apiKey = apiKey;
+        this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.maxRetries = options.maxRetries ?? 2;
+        this.timeout = options.timeout ?? 60_000;
+        this.fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    /**
+     * Eventos na hora pelo WebSocket (os mesmos dos webhooks), sem endereço HTTPS seu. Só no servidor.
+     *
+     *   const ws = wyzecash.realtime({ events: ["payment.*"] });
+     *   ws.on("payment.paid", (e) => liberarPedido(e.data));
+     */
+    realtime(options = {}) {
+        return new RealtimeConnection(`${this.baseUrl.replace(/^http/, "ws")}/v1/ws`, this.apiKey, options);
+    }
+    request(id, pathArgs, params, options = {}) {
+        return this.send(id, pathArgs, params, options);
+    }
+    list(id, pathArgs, params, options = {}) {
+        const base = { ...(params ?? {}) };
+        const start = typeof base.cursor === "string" ? base.cursor : undefined;
+        delete base.cursor;
+        return new ListPromise((cursor) => this.send(id, pathArgs, cursor ? { ...base, cursor } : base, options), start);
+    }
+    async send(id, pathArgs, params, options) {
+        const op = OPERATIONS[id];
+        let path = op.path;
+        for (const arg of pathArgs) {
+            if (!arg)
+                throw new Error(`Faltou o código na rota ${op.path}.`);
+            path = path.replace(/\{[A-Za-z]+\}/, encodeURIComponent(arg));
+        }
+        const url = new URL(this.baseUrl + path);
+        const body = {};
+        for (const [name, value] of Object.entries(params ?? {})) {
+            if (value === undefined)
+                continue;
+            if (op.query.includes(name)) {
+                if (value !== null)
+                    url.searchParams.set(name, String(value));
+            }
+            else
+                body[name] = value;
+        }
+        const headers = {
+            authorization: `Bearer ${this.apiKey}`,
+            accept: op.binary ? "*/*" : "application/json",
+            "user-agent": `wyzecash-node/${VERSION}`,
+        };
+        if (op.idempotent)
+            headers["idempotency-key"] = options.idempotencyKey ?? globalThis.crypto.randomUUID();
+        const payload = op.body ? JSON.stringify(body) : undefined;
+        if (payload !== undefined)
+            headers["content-type"] = "application/json";
+        const safeToRepeat = op.method === "GET" || op.method === "DELETE" || (op.idempotent && !op.moneyOut);
+        const maxRetries = options.maxRetries ?? this.maxRetries;
+        for (let attempt = 0;; attempt++) {
+            let response;
+            const controller = new AbortController();
+            const onAbort = () => controller.abort(options.signal?.reason);
+            options.signal?.addEventListener("abort", onAbort, { once: true });
+            const timer = setTimeout(() => controller.abort(new WyzeCashConnectionError("A API não respondeu a tempo.", "TIMEOUT")), options.timeout ?? this.timeout);
+            try {
+                response = await this.fetchImpl(url, { method: op.method, headers, body: payload, signal: controller.signal });
+            }
+            catch (error) {
+                clearTimeout(timer);
+                options.signal?.removeEventListener("abort", onAbort);
+                if (options.signal?.aborted)
+                    throw error;
+                const failure = error instanceof WyzeCashConnectionError ? error : new WyzeCashConnectionError(`Não deu para falar com a API: ${error?.message ?? error}`);
+                if (safeToRepeat && attempt < maxRetries) {
+                    await wait(backoff(attempt));
+                    continue;
+                }
+                throw failure;
+            }
+            clearTimeout(timer);
+            options.signal?.removeEventListener("abort", onAbort);
+            if (response.ok) {
+                if (op.binary)
+                    return (await response.arrayBuffer());
+                const text = await response.text();
+                return (text ? JSON.parse(text) : null);
+            }
+            const retryable = response.status === 429 || (response.status >= 500 && safeToRepeat);
+            if (retryable && attempt < maxRetries) {
+                const after = Number(response.headers.get("retry-after"));
+                await wait(Number.isFinite(after) && after > 0 ? Math.min(after, 60) * 1000 : backoff(attempt));
+                continue;
+            }
+            throw await toError(response);
+        }
+    }
+}
+const backoff = (attempt) => Math.min(8000, 500 * 2 ** attempt) * (0.75 + Math.random() * 0.5);
+async function toError(response) {
+    let json = null;
+    try {
+        json = await response.json();
+    }
+    catch {
+        json = null;
+    }
+    return new WyzeCashError({
+        status: response.status,
+        code: json?.error?.code ?? `HTTP_${response.status}`,
+        message: json?.error?.message ?? `A API respondeu ${response.status}.`,
+        requestId: json?.requestId ?? response.headers.get("x-request-id"),
+        details: json?.error?.details ?? null,
+    });
+}

package/dist/core.d.ts

@@ -0,0 +1,22 @@
+import type { OperationId } from "./generated.js";
+import type { ListPromise } from "./pagination.js";
+export interface RequestOptions {
+    /**
+     * Chave do pedido nas rotas que pedem `Idempotency-Key` (criar cobrança, saque, Pix enviado,
+     * estorno e os envios das subcontas). Use o código do pedido no seu sistema: repetir a mesma
+     * chave devolve o mesmo resultado. Sem ela, o SDK cria uma por chamada.
+     */
+    idempotencyKey?: string;
+    /** Tempo máximo do pedido, em milissegundos. */
+    timeout?: number;
+    /** Quantas vezes tentar de novo (vale por cima do padrão do cliente). */
+    maxRetries?: number;
+    signal?: AbortSignal;
+}
+export interface Requester {
+    request<T>(op: OperationId, pathArgs: string[], params: object | undefined, options?: RequestOptions): Promise<T>;
+    list<P extends {
+        items: unknown[];
+        nextCursor?: string | null;
+    }, T>(op: OperationId, pathArgs: string[], params: object | undefined, options?: RequestOptions): ListPromise<P, T>;
+}

package/dist/core.js

@@ -0,0 +1,2 @@
+// O que os recursos gerados (generated.ts) pedem ao cliente.
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,24 @@
+export declare class WyzeCashError extends Error {
+    /** Situação HTTP (0 quando o pedido nem chegou à API). */
+    readonly status: number;
+    /** Código estável do erro (ex.: `VALIDATION`, `INSUFFICIENT_FUNDS`, `RATE_LIMITED`). */
+    readonly code: string;
+    /** Código do pedido: mande para o suporte quando precisar de ajuda. */
+    readonly requestId: string | null;
+    readonly details: Record<string, unknown> | null;
+    constructor(input: {
+        status: number;
+        code: string;
+        message: string;
+        requestId?: string | null;
+        details?: Record<string, unknown> | null;
+    });
+}
+/** O pedido não chegou à API ou a resposta não voltou (rede, tempo esgotado). */
+export declare class WyzeCashConnectionError extends WyzeCashError {
+    constructor(message: string, code?: "CONNECTION_ERROR" | "TIMEOUT");
+}
+/** O aviso (webhook) não passou na conferência da assinatura. */
+export declare class WyzeCashWebhookError extends WyzeCashError {
+    constructor(message: string, code: "MISSING_SIGNATURE" | "INVALID_SIGNATURE" | "TIMESTAMP_OUT_OF_RANGE" | "INVALID_PAYLOAD");
+}

package/dist/errors.js

@@ -0,0 +1,33 @@
+// Erros do SDK. A API responde `{ "error": { "code", "message", "details" }, "requestId" }`: o
+// `code` é estável (use no seu sistema) e a `message` está em português.
+export class WyzeCashError extends Error {
+    /** Situação HTTP (0 quando o pedido nem chegou à API). */
+    status;
+    /** Código estável do erro (ex.: `VALIDATION`, `INSUFFICIENT_FUNDS`, `RATE_LIMITED`). */
+    code;
+    /** Código do pedido: mande para o suporte quando precisar de ajuda. */
+    requestId;
+    details;
+    constructor(input) {
+        super(input.message);
+        this.name = "WyzeCashError";
+        this.status = input.status;
+        this.code = input.code;
+        this.requestId = input.requestId ?? null;
+        this.details = input.details ?? null;
+    }
+}
+/** O pedido não chegou à API ou a resposta não voltou (rede, tempo esgotado). */
+export class WyzeCashConnectionError extends WyzeCashError {
+    constructor(message, code = "CONNECTION_ERROR") {
+        super({ status: 0, code, message });
+        this.name = "WyzeCashConnectionError";
+    }
+}
+/** O aviso (webhook) não passou na conferência da assinatura. */
+export class WyzeCashWebhookError extends WyzeCashError {
+    constructor(message, code) {
+        super({ status: 400, code, message });
+        this.name = "WyzeCashWebhookError";
+    }
+}

package/dist/fastify.d.ts

@@ -0,0 +1,14 @@
+import type { FastifyInstance, FastifyRequest } from "fastify";
+import { type WebhookEvent } from "./webhooks.js";
+export interface WyzeCashWebhooksOptions {
+    /** Caminho da rota (padrão `/webhooks/wyzecash`). */
+    path?: string;
+    /** Segredo do webhook. Sem ele, vale a variável de ambiente `WYZECASH_WEBHOOK_SECRET`. */
+    secret?: string;
+    /** Quantos segundos o aviso vale depois de assinado (padrão 300). */
+    tolerance?: number;
+    /** Chamado com cada aviso conferido. Use `evento.id` para não processar o mesmo duas vezes. */
+    onEvent: (event: WebhookEvent, request: FastifyRequest) => unknown | Promise<unknown>;
+}
+export declare function wyzecashWebhooks(fastify: FastifyInstance, options: WyzeCashWebhooksOptions): Promise<void>;
+export default wyzecashWebhooks;

package/dist/fastify.js

@@ -0,0 +1,50 @@
+// Plugin do Fastify para receber os webhooks da WyzeCash:
+//
+//   import { wyzecashWebhooks } from "wyzecash/fastify";
+//   await app.register(wyzecashWebhooks, {
+//     path: "/webhooks/wyzecash",
+//     secret: process.env.WYZECASH_WEBHOOK_SECRET,
+//     async onEvent(evento) { if (evento.type === "payment.paid") ... },
+//   });
+//
+// A rota lê o corpo cru (a assinatura é conferida nos bytes como chegaram). O plugin não é
+// "fastify-plugin" de propósito: a troca do leitor de JSON fica só dentro dele e o resto da sua
+// aplicação continua lendo JSON como sempre. Responde 200 quando deu certo, 400 quando o aviso não
+// é da WyzeCash e 500 quando o seu onEvent falha (aí a WyzeCash manda de novo mais tarde).
+import { WyzeCashWebhookError } from "./errors.js";
+import { SIGNATURE_HEADER, verifyWebhook } from "./webhooks.js";
+const env = (name) => globalThis.process?.env?.[name];
+export async function wyzecashWebhooks(fastify, options) {
+    const secret = options.secret ?? env("WYZECASH_WEBHOOK_SECRET");
+    if (!secret)
+        throw new Error("wyzecashWebhooks: passe o `secret` (ou a variável WYZECASH_WEBHOOK_SECRET).");
+    if (typeof options.onEvent !== "function")
+        throw new Error("wyzecashWebhooks: passe a função `onEvent`.");
+    fastify.removeContentTypeParser(["application/json"]);
+    fastify.addContentTypeParser("application/json", { parseAs: "buffer" }, (_request, body, done) => done(null, body));
+    fastify.post(options.path ?? "/webhooks/wyzecash", async (request, reply) => {
+        const raw = request.body;
+        if (!(raw instanceof Uint8Array))
+            return reply.code(400).send({ error: "Corpo do aviso vazio ou fora do JSON." });
+        let event;
+        try {
+            event = await verifyWebhook(raw, request.headers[SIGNATURE_HEADER], secret, { tolerance: options.tolerance });
+        }
+        catch (error) {
+            if (error instanceof WyzeCashWebhookError) {
+                request.log.warn({ code: error.code }, "WyzeCash: aviso recusado");
+                return reply.code(400).send({ error: error.message });
+            }
+            throw error;
+        }
+        try {
+            await options.onEvent(event, request);
+        }
+        catch (error) {
+            request.log.error({ err: error, event: event.id, type: event.type }, "WyzeCash: o onEvent falhou");
+            return reply.code(500).send({ error: "Não deu para processar o aviso agora." });
+        }
+        return reply.code(200).send({ received: true });
+    });
+}
+export default wyzecashWebhooks;