Criar um plugin

pagamentos-plugin-meu-plugin/
├── package.json
├── tsconfig.json
├── src/
│   └── index.ts
├── README.md
└── .npmignore

{
  "name": "pagamentos-plugin-meu-plugin",
  "peerDependencies": {
    "pagamentos": "^0.x"
  },
  "devDependencies": {
    "pagamentos": "file:../pagamentos"
  }
}

export interface PluginNotificacoesOptions {
  webhookUrl: string
  canal?: 'slack' | 'discord' | 'teams'
}

import {
  onCobrancaCreated,
  onWebhookEvent,
  onCobrancaCancelled,
  type LifecycleHook,
  type WebhookHook
} from 'pagamentos'

export interface PluginNotificacoesOptions {
  webhookUrl: string
  canal: 'slack' | 'discord' | 'teams'
}

export function pluginNotificacoes(
  options: PluginNotificacoesOptions
): (LifecycleHook | WebhookHook)[] {
  return [
    // Notifica quando uma cobrança é criada
    onCobrancaCreated(async (evt) => {
      await enviarNotificacao(options, {
        texto: `Nova cobrança criada: R$ ${(evt.input.valor / 100).toFixed(2)}`,
        cor: 'azul'
      })
    }),

    // Notifica quando o pagamento é confirmado
    onWebhookEvent('pagamento.realizado', async (event) => {
      await enviarNotificacao(options, {
        texto: `Pagamento confirmado: R$ ${(event.data.cobranca.valor / 100).toFixed(2)}`,
        cor: 'verde'
      })
    }),

    // Notifica quando a cobrança é cancelada
    onCobrancaCancelled(async (evt) => {
      await enviarNotificacao(options, {
        texto: `Cobrança cancelada: ${evt.output.id}`,
        cor: 'vermelho'
      })
    })
  ]
}

async function enviarNotificacao(
  options: PluginNotificacoesOptions,
  payload: { texto: string; cor: string }
) {
  // Implementação específica para cada canal
  await fetch(options.webhookUrl, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text: payload.texto })
  })
}

import { Pagamentos, mercadopago } from 'pagamentos'
import { pluginNotificacoes } from 'pagamentos-plugin-notificacoes'

const pg = new Pagamentos({
  providers: [mercadopago({ accessToken: '...' })],
  hooks: [
    ...pluginNotificacoes({
      webhookUrl: process.env.SLACK_WEBHOOK_URL!,
      canal: 'slack'
    })
  ]
})

import { onClienteCreated, onCobrancaCancelled } from 'pagamentos'

export function pluginSyncDatabase(db: Database) {
  return [
    onClienteCreated(async (evt) => {
      await db.clientes.upsert({
        id: evt.output.id,
        nome: evt.input.nome
      })
    }),
    onCobrancaCancelled(async (evt) => {
      await db.cobrancas.update(evt.output.id, { status: 'cancelado' })
    })
  ]
}

import { onWebhookEvent } from 'pagamentos'

export function pluginEmailNotificacao(sender: EmailSender) {
  return [
    onWebhookEvent('pagamento.realizado', async (event) => {
      await sender.send({
        to: event.data.cliente?.email,
        template: 'pagamento_confirmado',
        vars: { nome: event.data.cliente?.nome }
      })
    }),
    onWebhookEvent('cobranca.vencida', async (event) => {
      await sender.send({
        to: event.data.cobranca.cliente.email,
        template: 'cobranca_vencida'
      })
    })
  ]
}

import { onCobrancaCreated, onWebhookEvent } from 'pagamentos'

export function pluginAnalytics(tracker: Tracker) {
  return [
    onCobrancaCreated(async (evt) => {
      tracker.track('cobranca_criada', { valor: evt.input.valor })
    }),
    onWebhookEvent('pagamento.realizado', async (event) => {
      tracker.track('pagamento_convertido', {
        cobrancaId: event.data.cobranca.id
      })
    })
  ]
}

onWebhookEvent('pagamento.realizado', async (event) => {
  const jaProcessado = await db.eventos.exists({ id: event.id })
  if (jaProcessado) return
  // ...
})

onCobrancaCreated(async (evt) => {
  try {
    await lógicaExterna()
  } catch (error) {
    console.error('[meu-plugin] Erro:', error)
  }
})

// ✅ Bom
export function plugin(options: { apiKey: string })

// ❌ Evite
export function plugin() { process.env.API_KEY }

## Eventos

- `onCobrancaCreated` — dispara após `pg.cobrancas.create()`
- `onWebhookEvent('pagamento.realizado')` — dispara quando o provedor confirma

export interface PluginMeuPluginOptions {
  apiKey: string
  ambiente?: 'producao' | 'sandbox'
}