SDK TypeScript/Node.js oficial da Mupay. A ideia e deixar pagamento tao facil quanto criar um cliente, chamar gateway.charges.create(...) e seguir com o produto.

Ele foi desenhado para parecer uma biblioteca escrita por pessoa: nomes curtos, erros uteis, retries seguros e idempotencia automatica. Sem cliente HTTP pesado, sem codigo gerado vazando para sua aplicacao.

Install

npm install mupay-sdk

Quickstart em menos de 1 minuto

import Gateway from 'mupay-sdk';

const gateway = new Gateway({
  apiKey: process.env.MUPAY_API_KEY!,
  env: 'test'
});

const charge = await gateway.charges.create({
  amount_cents: 9990,
  payment_method: 'pix',
  customer: { id: 'cus_123' }
});

console.log(charge.charge_id);

Pronto: o SDK escolhe a URL do sandbox, envia Authorization, gera Idempotency-Key, serializa JSON e faz retry seguro quando a API responde 429 ou 5xx.

Por que integrar com a SDK e nao montar HTTP na mao?

gateway.charges.create(...) e legivel por quem acabou de chegar no codigo.
Todo POST financeiro recebe idempotencia automaticamente.
Erros vem tipados com code, suggestion, documentationUrl e requestId.
Webhooks validam HMAC-SHA256, timestamp e payload bruto.
Bundle minificado+gzip fica abaixo de 50KB; hoje esta em torno de 1.7KB gzip.

Examples

PIX charge

const charge = await gateway.charges.create({
  amount_cents: 9990,
  payment_method: 'pix',
  customer: { id: 'cus_123' },
  description: 'Plano Pro mensal'
});

Card charge

const charge = await gateway.charges.create({
  amount_cents: 14990,
  payment_method: 'credit_card',
  customer: { id: 'cus_123' },
  card_token_id: '11111111-1111-1111-1111-111111111111',
  installments: 3,
  metadata: { cart_id: 'cart_789' }
});

Cancel subscription

const subscription = await gateway.subscriptions.cancel('sub_123', {
  mode: 'immediate',
  reason: 'customer_request'
});

Refund

const refund = await gateway.refunds.create('ch_123', {
  amount_cents: 9990,
  reason: 'requested_by_customer'
});

Webhook validation

const event = await gateway.webhooks.constructEvent(
  rawPayload,
  request.headers.get('mupay-signature')!,
  process.env.MUPAY_WEBHOOK_SECRET!
);

if (event.type === 'charge.paid') {
  console.log(event.data);
}

Errors

Erros da API preservam os campos DX-first do Problem Details:

import { ValidationError } from 'mupay-sdk';

try {
  await gateway.charges.create({
    amount_cents: 0,
    payment_method: 'pix',
    customer: { id: 'cus_123' }
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(error.code);
    console.log(error.suggestion);
    console.log(error.documentationUrl);
    console.log(error.requestId);
  }
}

Runtime support

Node.js 18+
Bun
Deno
Cloudflare Workers
Vercel Edge

O SDK usa fetch, AbortController, crypto.subtle e TextEncoder, sem axios ou got.

Como publicar no npm

O pacote e publico e sem escopo: mupay-sdk. Pacotes npm sem escopo sao publicados no registry publico pelo proprio nome, desde que o nome esteja disponivel.

Fluxo recomendado:

Crie/acesse uma conta em npmjs.com.
Garanta que voce tem permissao para publicar mupay-sdk.
Rode checks locais:

npm ci
npm run check
npm pack --dry-run

Publique manualmente:

npm publish --provenance

Se a conta npm ainda nao estiver pronta para provenance, use npm publish e habilite provenance depois. O repositorio nao publica a SDK automaticamente pela pipeline do GitHub.

Segundo a documentacao do npm, pacotes sem escopo sao publicos por natureza; para pacotes com escopo seria necessario npm publish --access public.