better-auth-mp 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +65 -0
- package/DISCLAIMER.md +51 -0
- package/LICENSE +21 -0
- package/README.es.md +233 -0
- package/README.md +233 -0
- package/dist/client-plugin.cjs +13 -0
- package/dist/client-plugin.cjs.map +1 -0
- package/dist/client-plugin.d.cts +15 -0
- package/dist/client-plugin.d.ts +15 -0
- package/dist/client-plugin.js +10 -0
- package/dist/client-plugin.js.map +1 -0
- package/dist/index.cjs +1403 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +574 -0
- package/dist/index.d.ts +574 -0
- package/dist/index.js +1396 -0
- package/dist/index.js.map +1 -0
- package/dist/schemas.cjs +121 -0
- package/dist/schemas.cjs.map +1 -0
- package/dist/schemas.d.cts +428 -0
- package/dist/schemas.d.ts +428 -0
- package/dist/schemas.js +108 -0
- package/dist/schemas.js.map +1 -0
- package/dist/types.cjs +195 -0
- package/dist/types.cjs.map +1 -0
- package/dist/types.d.cts +485 -0
- package/dist/types.d.ts +485 -0
- package/dist/types.js +190 -0
- package/dist/types.js.map +1 -0
- package/package.json +77 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
## [Unreleased]
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- Initial release of `better-auth-mp` plugin
|
|
15
|
+
- MercadoPago integration for Better Auth
|
|
16
|
+
- Subscription management support
|
|
17
|
+
- Webhook handling with signature verification
|
|
18
|
+
- Type-safe Zod schemas
|
|
19
|
+
- Client plugin for React
|
|
20
|
+
|
|
21
|
+
### Features
|
|
22
|
+
|
|
23
|
+
- 🔐 Authentication-first payments — Payments tied to authenticated Better Auth users
|
|
24
|
+
- 💳 Subscription management — Create and manage recurring subscriptions with MercadoPago
|
|
25
|
+
- 🔔 Webhook handling — Built-in webhook verification and event processing
|
|
26
|
+
- 📦 Type-safe — Full TypeScript support with Zod validation
|
|
27
|
+
- 🔌 Pluggable — Drop-in Better Auth plugin with minimal configuration
|
|
28
|
+
- 🌎 LATAM-ready — Built specifically for MercadoPago's Latin American market
|
|
29
|
+
|
|
30
|
+
### Documentation
|
|
31
|
+
|
|
32
|
+
- Bilingual documentation (English & Spanish)
|
|
33
|
+
- Quick start guide
|
|
34
|
+
- Configuration reference
|
|
35
|
+
- Contributing guidelines
|
|
36
|
+
- Legal disclaimer
|
|
37
|
+
|
|
38
|
+
---
|
|
39
|
+
|
|
40
|
+
## Migration Guides
|
|
41
|
+
|
|
42
|
+
### From version 0.1.0
|
|
43
|
+
|
|
44
|
+
This is the initial release. No migration needed.
|
|
45
|
+
|
|
46
|
+
---
|
|
47
|
+
|
|
48
|
+
## Upcoming Features
|
|
49
|
+
|
|
50
|
+
See our [public roadmap](https://github.com/IvanTsxx/better-auth-mp/issues) for planned features:
|
|
51
|
+
|
|
52
|
+
- One-click checkout via Brick
|
|
53
|
+
- Subscription plan management UI
|
|
54
|
+
- Refund management
|
|
55
|
+
- Payment analytics endpoints
|
|
56
|
+
- Multi-currency support
|
|
57
|
+
- Installment (cuotas) support
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## Support
|
|
62
|
+
|
|
63
|
+
- 📖 [Documentation](https://better-auth-mp.vercel.app)
|
|
64
|
+
- 🐛 [Issue Tracker](https://github.com/IvanTsxx/better-auth-mp/issues)
|
|
65
|
+
- 💬 [Discussions](https://github.com/IvanTsxx/better-auth-mp/discussions)
|
package/DISCLAIMER.md
ADDED
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# Disclaimer / Descargo de Responsabilidad
|
|
2
|
+
|
|
3
|
+
## English
|
|
4
|
+
|
|
5
|
+
**`better-auth-mp` is an independent, community-maintained plugin and is NOT officially affiliated with, endorsed by, or supported by MercadoPago, Mercado Libre, Better Auth, or any of their respective companies, employees, or subsidiaries.**
|
|
6
|
+
|
|
7
|
+
### No Warranty
|
|
8
|
+
|
|
9
|
+
This software is provided **"as is"** without warranty of any kind, either express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. The authors and contributors of this project make no guarantees that this software will meet your requirements or that its operation will be uninterrupted or error-free.
|
|
10
|
+
|
|
11
|
+
### Financial and Legal Responsibility
|
|
12
|
+
|
|
13
|
+
This plugin facilitates the integration of payment processing features into your applications. The authors and contributors:
|
|
14
|
+
|
|
15
|
+
- **Are not responsible** for any financial losses, failed transactions, security breaches, compliance failures, or any other damages that may arise from the use or misuse of this plugin.
|
|
16
|
+
- **Do not guarantee** compliance with any specific jurisdiction's financial regulations, PCI-DSS standards, or any other legal or regulatory requirements.
|
|
17
|
+
- **Strongly recommend** that you review and comply with [MercadoPago's official terms of service](https://www.mercadopago.com.ar/developers/es/docs/checkout-api/legal/terms-and-conditions) and applicable local laws before deploying this plugin in production.
|
|
18
|
+
|
|
19
|
+
### Third-Party Services
|
|
20
|
+
|
|
21
|
+
By using this plugin, you agree to comply with the terms of service of MercadoPago and any other third-party services that this plugin integrates with. The authors are not responsible for changes in third-party APIs that may break the functionality of this plugin.
|
|
22
|
+
|
|
23
|
+
### Limitation of Liability
|
|
24
|
+
|
|
25
|
+
To the fullest extent permitted by applicable law, in no event shall the authors, contributors, 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.
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## Español
|
|
30
|
+
|
|
31
|
+
**`better-auth-mp` es un plugin independiente mantenido por la comunidad y NO está oficialmente afiliado, respaldado ni soportado por MercadoPago, Mercado Libre, Better Auth, ni ninguna de sus respectivas empresas, empleados o subsidiarias.**
|
|
32
|
+
|
|
33
|
+
### Sin Garantía
|
|
34
|
+
|
|
35
|
+
Este software se proporciona **"tal cual"** sin garantía de ningún tipo, ya sea expresa o implícita, incluyendo pero no limitado a las garantías de comerciabilidad, idoneidad para un propósito particular y no infracción. Los autores y colaboradores de este proyecto no garantizan que este software cumpla con sus requisitos o que su funcionamiento sea ininterrumpido o libre de errores.
|
|
36
|
+
|
|
37
|
+
### Responsabilidad Financiera y Legal
|
|
38
|
+
|
|
39
|
+
Este plugin facilita la integración de funcionalidades de procesamiento de pagos en sus aplicaciones. Los autores y colaboradores:
|
|
40
|
+
|
|
41
|
+
- **No son responsables** de ninguna pérdida financiera, transacciones fallidas, infracciones de seguridad, incumplimientos de cumplimiento normativo, ni ningún otro daño que pueda surgir del uso o mal uso de este plugin.
|
|
42
|
+
- **No garantizan** el cumplimiento con las regulaciones financieras de ninguna jurisdicción específica, los estándares PCI-DSS, ni ningún otro requisito legal o regulatorio.
|
|
43
|
+
- **Recomiendan encarecidamente** que revise y cumpla con los [términos de servicio oficiales de MercadoPago](https://www.mercadopago.com.ar/developers/es/docs/checkout-api/legal/terms-and-conditions) y las leyes locales aplicables antes de implementar este plugin en producción.
|
|
44
|
+
|
|
45
|
+
### Servicios de Terceros
|
|
46
|
+
|
|
47
|
+
Al usar este plugin, usted acepta cumplir con los términos de servicio de MercadoPago y cualquier otro servicio de terceros con el que este plugin se integre. Los autores no son responsables de los cambios en las APIs de terceros que puedan afectar la funcionalidad de este plugin.
|
|
48
|
+
|
|
49
|
+
### Limitación de Responsabilidad
|
|
50
|
+
|
|
51
|
+
En la máxima medida permitida por la ley aplicable, en ningún caso los autores, colaboradores o titulares de derechos de autor serán responsables de ninguna reclamación, daño u otra responsabilidad, ya sea en una acción de contrato, agravio u otro tipo, que surja de, fuera de o en relación con el software o el uso u otras operaciones en el software.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 better-auth-mp contributors
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.es.md
ADDED
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<img src="https://better-auth-mp.vercel.app/logo.png" alt="better-auth-mp logo" width="120" />
|
|
3
|
+
|
|
4
|
+
<h1>better-auth-mp</h1>
|
|
5
|
+
|
|
6
|
+
<p>
|
|
7
|
+
Plugin de MercadoPago para <a href="https://better-auth.com">Better Auth</a> — suscripciones, pagos y webhooks listos para usar.
|
|
8
|
+
</p>
|
|
9
|
+
|
|
10
|
+
<p>
|
|
11
|
+
<a href="https://www.npmjs.com/package/better-auth-mp">
|
|
12
|
+
<img src="https://img.shields.io/npm/v/better-auth-mp?style=flat-square&colorA=18181b&colorB=00BCFF" alt="versión npm" />
|
|
13
|
+
</a>
|
|
14
|
+
<a href="https://www.npmjs.com/package/better-auth-mp">
|
|
15
|
+
<img src="https://img.shields.io/npm/dm/better-auth-mp?style=flat-square&colorA=18181b&colorB=00BCFF" alt="descargas npm" />
|
|
16
|
+
</a>
|
|
17
|
+
<a href="https://github.com/IvanTsxx/better-auth-mp/blob/main/packages/plugin/LICENSE">
|
|
18
|
+
<img src="https://img.shields.io/npm/l/better-auth-mp?style=flat-square&colorA=18181b&colorB=00BCFF" alt="licencia" />
|
|
19
|
+
</a>
|
|
20
|
+
<a href="https://github.com/IvanTsxx/better-auth-mp/actions/workflows/release.yml">
|
|
21
|
+
<img src="https://img.shields.io/github/actions/workflow/status/IvanTsxx/better-auth-mp/release.yml?style=flat-square&colorA=18181b&colorB=00BCFF&label=release" alt="estado del release" />
|
|
22
|
+
</a>
|
|
23
|
+
</p>
|
|
24
|
+
|
|
25
|
+
<p>
|
|
26
|
+
<a href="./README.md">🇺🇸 Read in English</a>
|
|
27
|
+
</p>
|
|
28
|
+
</div>
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
> ⚠️ **Descargo de responsabilidad:** Este plugin es mantenido por la comunidad y no está oficialmente afiliado a MercadoPago ni a Better Auth. Consultá el [DISCLAIMER.md](./DISCLAIMER.md) para más detalles.
|
|
33
|
+
|
|
34
|
+
## Tabla de Contenidos
|
|
35
|
+
|
|
36
|
+
- [Características](#características)
|
|
37
|
+
- [Instalación](#instalación)
|
|
38
|
+
- [Inicio rápido](#inicio-rápido)
|
|
39
|
+
- [Configuración del servidor](#configuración-del-servidor)
|
|
40
|
+
- [Configuración del cliente](#configuración-del-cliente)
|
|
41
|
+
- [Configuración](#configuración)
|
|
42
|
+
- [Integraciones](#integraciones)
|
|
43
|
+
- [Roadmap](#roadmap)
|
|
44
|
+
- [Contribuir](#contribuir)
|
|
45
|
+
- [Licencia](#licencia)
|
|
46
|
+
|
|
47
|
+
## Características
|
|
48
|
+
|
|
49
|
+
- 🔐 **Pagos vinculados a autenticación** — Los pagos quedan asociados a usuarios autenticados de Better Auth
|
|
50
|
+
- 💳 **Gestión de suscripciones** — Creá y gestioná suscripciones recurrentes con MercadoPago
|
|
51
|
+
- 🔔 **Manejo de webhooks** — Verificación de webhooks y procesamiento de eventos incorporado
|
|
52
|
+
- 📦 **Type-safe** — Soporte completo de TypeScript con validación Zod
|
|
53
|
+
- 🔌 **Pluggable** — Plugin de Better Auth que se integra con configuración mínima
|
|
54
|
+
- 🌎 **Hecho para LATAM** — Construido específicamente para el mercado latinoamericano de MercadoPago
|
|
55
|
+
|
|
56
|
+
## Instalación
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
# npm
|
|
60
|
+
npm install better-auth-mp
|
|
61
|
+
|
|
62
|
+
# yarn
|
|
63
|
+
yarn add better-auth-mp
|
|
64
|
+
|
|
65
|
+
# pnpm
|
|
66
|
+
pnpm add better-auth-mp
|
|
67
|
+
|
|
68
|
+
# bun
|
|
69
|
+
bun add better-auth-mp
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Dependencias de pares (peer dependencies)
|
|
73
|
+
|
|
74
|
+
Asegurate de tener instaladas las peer dependencies requeridas:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
bun add better-auth @prisma/client
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Inicio rápido
|
|
81
|
+
|
|
82
|
+
### Configuración del servidor
|
|
83
|
+
|
|
84
|
+
Agregá el plugin a tu configuración de Better Auth:
|
|
85
|
+
|
|
86
|
+
```typescript
|
|
87
|
+
// auth.ts (servidor)
|
|
88
|
+
import { betterAuth } from "better-auth";
|
|
89
|
+
import { prismaAdapter } from "better-auth/adapters/prisma";
|
|
90
|
+
import { mercadopago } from "better-auth-mp";
|
|
91
|
+
import { PrismaClient } from "@prisma/client";
|
|
92
|
+
|
|
93
|
+
const prisma = new PrismaClient();
|
|
94
|
+
|
|
95
|
+
export const auth = betterAuth({
|
|
96
|
+
database: prismaAdapter(prisma, {
|
|
97
|
+
provider: "postgresql",
|
|
98
|
+
}),
|
|
99
|
+
plugins: [
|
|
100
|
+
mercadopago({
|
|
101
|
+
accessToken: process.env.MP_ACCESS_TOKEN!,
|
|
102
|
+
webhookSecret: process.env.MP_WEBHOOK_SECRET!,
|
|
103
|
+
}),
|
|
104
|
+
],
|
|
105
|
+
});
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Configuración del cliente
|
|
109
|
+
|
|
110
|
+
Agregá el plugin al cliente de Better Auth:
|
|
111
|
+
|
|
112
|
+
```typescript
|
|
113
|
+
// auth-client.ts (cliente)
|
|
114
|
+
import { createAuthClient } from "better-auth/react";
|
|
115
|
+
import { mercadopagoClient } from "better-auth-mp/client";
|
|
116
|
+
|
|
117
|
+
export const authClient = createAuthClient({
|
|
118
|
+
plugins: [mercadopagoClient()],
|
|
119
|
+
});
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Variables de entorno
|
|
123
|
+
|
|
124
|
+
```env
|
|
125
|
+
# Credenciales de MercadoPago
|
|
126
|
+
MP_ACCESS_TOKEN=APP_USR-xxxxxxxxxxxxxxxxxxxx
|
|
127
|
+
MP_WEBHOOK_SECRET=tu-secreto-de-webhook
|
|
128
|
+
|
|
129
|
+
# Better Auth
|
|
130
|
+
BETTER_AUTH_SECRET=tu-secreto-de-auth
|
|
131
|
+
BETTER_AUTH_URL=http://localhost:3000
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Configuración
|
|
135
|
+
|
|
136
|
+
### Opciones del plugin
|
|
137
|
+
|
|
138
|
+
| Opción | Tipo | Requerido | Descripción |
|
|
139
|
+
|--------|------|-----------|-------------|
|
|
140
|
+
| `accessToken` | `string` | ✅ | Access Token de MercadoPago (producción o sandbox) |
|
|
141
|
+
| `webhookSecret` | `string` | ✅ | Secreto para verificación de firma de webhooks |
|
|
142
|
+
| `sandbox` | `boolean` | ❌ | Activa el modo sandbox (por defecto: `false`) |
|
|
143
|
+
| `notificationUrl` | `string` | ❌ | URL personalizada para webhooks (por defecto: se detecta automáticamente desde `BETTER_AUTH_URL`) |
|
|
144
|
+
|
|
145
|
+
```typescript
|
|
146
|
+
mercadopago({
|
|
147
|
+
accessToken: process.env.MP_ACCESS_TOKEN!,
|
|
148
|
+
webhookSecret: process.env.MP_WEBHOOK_SECRET!,
|
|
149
|
+
sandbox: process.env.NODE_ENV !== "production",
|
|
150
|
+
notificationUrl: "https://tudominio.com/api/auth/mercadopago/webhook",
|
|
151
|
+
})
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Schema de base de datos (agnóstico al ORM)
|
|
155
|
+
|
|
156
|
+
Este plugin es **completamente agnóstico al ORM** — funciona con Prisma, Drizzle, o cualquier otro ORM/base de datos compatible con Better Auth.
|
|
157
|
+
|
|
158
|
+
El schema requerido se genera automáticamente usando el **CLI de Better Auth**. Ejecutalo una vez después de configurar el plugin:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
# bun
|
|
162
|
+
bunx @better-auth/cli generate
|
|
163
|
+
|
|
164
|
+
# npm
|
|
165
|
+
npx @better-auth/cli@latest generate
|
|
166
|
+
|
|
167
|
+
# pnpm
|
|
168
|
+
pnpm dlx @better-auth/cli@latest generate
|
|
169
|
+
|
|
170
|
+
# yarn
|
|
171
|
+
yarn dlx @better-auth/cli@latest generate
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
El CLI lee tu configuración de `auth.ts` y genera automáticamente los modelos/migraciones necesarios para el ORM y base de datos que tengas configurado.
|
|
175
|
+
|
|
176
|
+
## Integraciones
|
|
177
|
+
|
|
178
|
+
### Next.js App Router
|
|
179
|
+
|
|
180
|
+
Creá el route handler para los webhooks:
|
|
181
|
+
|
|
182
|
+
```typescript
|
|
183
|
+
// app/api/auth/[...betterauth]/route.ts
|
|
184
|
+
import { auth } from "@/lib/auth";
|
|
185
|
+
import { toNextJsHandler } from "better-auth/next-js";
|
|
186
|
+
|
|
187
|
+
export const { POST, GET } = toNextJsHandler(auth);
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
El plugin registra automáticamente el endpoint de webhook en `/api/auth/mercadopago/webhook`.
|
|
191
|
+
|
|
192
|
+
### Eventos de Webhook
|
|
193
|
+
|
|
194
|
+
El plugin maneja los siguientes eventos de webhook de MercadoPago:
|
|
195
|
+
|
|
196
|
+
| Evento | Descripción |
|
|
197
|
+
|--------|-------------|
|
|
198
|
+
| `subscription_preapproval` | Suscripción creada o actualizada |
|
|
199
|
+
| `payment` | Pago recibido, reembolsado o fallido |
|
|
200
|
+
|
|
201
|
+
### Hooks del cliente (React)
|
|
202
|
+
|
|
203
|
+
```typescript
|
|
204
|
+
import { authClient } from "@/lib/auth-client";
|
|
205
|
+
|
|
206
|
+
// En tu componente
|
|
207
|
+
const { data: session } = authClient.useSession();
|
|
208
|
+
const subscription = authClient.mercadopago.useSubscription();
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
## Roadmap
|
|
212
|
+
|
|
213
|
+
| Funcionalidad | Estado |
|
|
214
|
+
|---------------|--------|
|
|
215
|
+
| ✅ Webhooks de pagos básicos | Publicado |
|
|
216
|
+
| ✅ Gestión de suscripciones | Publicado |
|
|
217
|
+
| ✅ Verificación de firma de webhooks | Publicado |
|
|
218
|
+
| 🔄 Checkout con un click via Brick | En desarrollo |
|
|
219
|
+
| 🔄 UI para gestión de planes de suscripción | En desarrollo |
|
|
220
|
+
| 📋 Gestión de reembolsos | Planeado |
|
|
221
|
+
| 📋 Endpoints de analytics de pagos | Planeado |
|
|
222
|
+
| 📋 Soporte multi-moneda | Planeado |
|
|
223
|
+
| 📋 Soporte de cuotas | Planeado |
|
|
224
|
+
|
|
225
|
+
## Contribuir
|
|
226
|
+
|
|
227
|
+
¡Las contribuciones son bienvenidas! Leé nuestra guía [CONTRIBUTING.es.md](./CONTRIBUTING.es.md) antes de enviar un PR.
|
|
228
|
+
|
|
229
|
+
## Licencia
|
|
230
|
+
|
|
231
|
+
[MIT](./LICENSE) — Copyright © 2025 better-auth-mp contributors.
|
|
232
|
+
|
|
233
|
+
Consultá [DISCLAIMER.md](./DISCLAIMER.md) para información legal importante.
|
package/README.md
ADDED
|
@@ -0,0 +1,233 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
<img src="https://better-auth-mp.vercel.app/logo.png" alt="better-auth-mp logo" width="120" />
|
|
3
|
+
|
|
4
|
+
<h1>better-auth-mp</h1>
|
|
5
|
+
|
|
6
|
+
<p>
|
|
7
|
+
MercadoPago plugin for <a href="https://better-auth.com">Better Auth</a> — subscriptions, payments & webhooks out of the box.
|
|
8
|
+
</p>
|
|
9
|
+
|
|
10
|
+
<p>
|
|
11
|
+
<a href="https://www.npmjs.com/package/better-auth-mp">
|
|
12
|
+
<img src="https://img.shields.io/npm/v/better-auth-mp?style=flat-square&colorA=18181b&colorB=00BCFF" alt="npm version" />
|
|
13
|
+
</a>
|
|
14
|
+
<a href="https://www.npmjs.com/package/better-auth-mp">
|
|
15
|
+
<img src="https://img.shields.io/npm/dm/better-auth-mp?style=flat-square&colorA=18181b&colorB=00BCFF" alt="npm downloads" />
|
|
16
|
+
</a>
|
|
17
|
+
<a href="https://github.com/IvanTsxx/better-auth-mp/blob/main/packages/plugin/LICENSE">
|
|
18
|
+
<img src="https://img.shields.io/npm/l/better-auth-mp?style=flat-square&colorA=18181b&colorB=00BCFF" alt="license" />
|
|
19
|
+
</a>
|
|
20
|
+
<a href="https://github.com/IvanTsxx/better-auth-mp/actions/workflows/release.yml">
|
|
21
|
+
<img src="https://img.shields.io/github/actions/workflow/status/IvanTsxx/better-auth-mp/release.yml?style=flat-square&colorA=18181b&colorB=00BCFF&label=release" alt="release status" />
|
|
22
|
+
</a>
|
|
23
|
+
</p>
|
|
24
|
+
|
|
25
|
+
<p>
|
|
26
|
+
<a href="./README.es.md">🇦🇷 Leer en Español</a>
|
|
27
|
+
</p>
|
|
28
|
+
</div>
|
|
29
|
+
|
|
30
|
+
---
|
|
31
|
+
|
|
32
|
+
> ⚠️ **Disclaimer:** This plugin is community-maintained and is not officially affiliated with MercadoPago or Better Auth. See [DISCLAIMER.md](./DISCLAIMER.md) for full details.
|
|
33
|
+
|
|
34
|
+
## Table of Contents
|
|
35
|
+
|
|
36
|
+
- [Features](#features)
|
|
37
|
+
- [Installation](#installation)
|
|
38
|
+
- [Quick Start](#quick-start)
|
|
39
|
+
- [Server Setup](#server-setup)
|
|
40
|
+
- [Client Setup](#client-setup)
|
|
41
|
+
- [Configuration](#configuration)
|
|
42
|
+
- [Integrations](#integrations)
|
|
43
|
+
- [Roadmap](#roadmap)
|
|
44
|
+
- [Contributing](#contributing)
|
|
45
|
+
- [License](#license)
|
|
46
|
+
|
|
47
|
+
## Features
|
|
48
|
+
|
|
49
|
+
- 🔐 **Authentication-first payments** — Payments tied to authenticated Better Auth users
|
|
50
|
+
- 💳 **Subscription management** — Create and manage recurring subscriptions with MercadoPago
|
|
51
|
+
- 🔔 **Webhook handling** — Built-in webhook verification and event processing
|
|
52
|
+
- 📦 **Type-safe** — Full TypeScript support with Zod validation
|
|
53
|
+
- 🔌 **Pluggable** — Drop-in Better Auth plugin with minimal configuration
|
|
54
|
+
- 🌎 **LATAM-ready** — Built specifically for MercadoPago's Latin American market
|
|
55
|
+
|
|
56
|
+
## Installation
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
# npm
|
|
60
|
+
npm install better-auth-mp
|
|
61
|
+
|
|
62
|
+
# yarn
|
|
63
|
+
yarn add better-auth-mp
|
|
64
|
+
|
|
65
|
+
# pnpm
|
|
66
|
+
pnpm add better-auth-mp
|
|
67
|
+
|
|
68
|
+
# bun
|
|
69
|
+
bun add better-auth-mp
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Peer Dependencies
|
|
73
|
+
|
|
74
|
+
Make sure you have the required peer dependencies installed:
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
bun add better-auth @prisma/client
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Quick Start
|
|
81
|
+
|
|
82
|
+
### Server Setup
|
|
83
|
+
|
|
84
|
+
Add the plugin to your Better Auth configuration:
|
|
85
|
+
|
|
86
|
+
```typescript
|
|
87
|
+
// auth.ts (server)
|
|
88
|
+
import { betterAuth } from "better-auth";
|
|
89
|
+
import { prismaAdapter } from "better-auth/adapters/prisma";
|
|
90
|
+
import { mercadopago } from "better-auth-mp";
|
|
91
|
+
import { PrismaClient } from "@prisma/client";
|
|
92
|
+
|
|
93
|
+
const prisma = new PrismaClient();
|
|
94
|
+
|
|
95
|
+
export const auth = betterAuth({
|
|
96
|
+
database: prismaAdapter(prisma, {
|
|
97
|
+
provider: "postgresql",
|
|
98
|
+
}),
|
|
99
|
+
plugins: [
|
|
100
|
+
mercadopago({
|
|
101
|
+
accessToken: process.env.MP_ACCESS_TOKEN!,
|
|
102
|
+
webhookSecret: process.env.MP_WEBHOOK_SECRET!,
|
|
103
|
+
}),
|
|
104
|
+
],
|
|
105
|
+
});
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
### Client Setup
|
|
109
|
+
|
|
110
|
+
Add the client plugin to your Better Auth client:
|
|
111
|
+
|
|
112
|
+
```typescript
|
|
113
|
+
// auth-client.ts (client)
|
|
114
|
+
import { createAuthClient } from "better-auth/react";
|
|
115
|
+
import { mercadopagoClient } from "better-auth-mp/client";
|
|
116
|
+
|
|
117
|
+
export const authClient = createAuthClient({
|
|
118
|
+
plugins: [mercadopagoClient()],
|
|
119
|
+
});
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### Environment Variables
|
|
123
|
+
|
|
124
|
+
```env
|
|
125
|
+
# MercadoPago credentials
|
|
126
|
+
MP_ACCESS_TOKEN=APP_USR-xxxxxxxxxxxxxxxxxxxx
|
|
127
|
+
MP_WEBHOOK_SECRET=your-webhook-secret
|
|
128
|
+
|
|
129
|
+
# Better Auth
|
|
130
|
+
BETTER_AUTH_SECRET=your-auth-secret
|
|
131
|
+
BETTER_AUTH_URL=http://localhost:3000
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
## Configuration
|
|
135
|
+
|
|
136
|
+
### Plugin Options
|
|
137
|
+
|
|
138
|
+
| Option | Type | Required | Description |
|
|
139
|
+
|--------|------|----------|-------------|
|
|
140
|
+
| `accessToken` | `string` | ✅ | MercadoPago Access Token (production or sandbox) |
|
|
141
|
+
| `webhookSecret` | `string` | ✅ | Secret for webhook signature verification |
|
|
142
|
+
| `sandbox` | `boolean` | ❌ | Enable sandbox mode (default: `false`) |
|
|
143
|
+
| `notificationUrl` | `string` | ❌ | Override webhook URL (default: auto-detected from `BETTER_AUTH_URL`) |
|
|
144
|
+
|
|
145
|
+
```typescript
|
|
146
|
+
mercadopago({
|
|
147
|
+
accessToken: process.env.MP_ACCESS_TOKEN!,
|
|
148
|
+
webhookSecret: process.env.MP_WEBHOOK_SECRET!,
|
|
149
|
+
sandbox: process.env.NODE_ENV !== "production",
|
|
150
|
+
notificationUrl: "https://yourdomain.com/api/auth/mercadopago/webhook",
|
|
151
|
+
})
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Database Schema (ORM-agnostic)
|
|
155
|
+
|
|
156
|
+
This plugin is **fully ORM-agnostic** — it works with Prisma, Drizzle, or any other ORM/database supported by Better Auth.
|
|
157
|
+
|
|
158
|
+
The required schema is generated automatically using the **Better Auth CLI**. Run it once after configuring the plugin:
|
|
159
|
+
|
|
160
|
+
```bash
|
|
161
|
+
# bun
|
|
162
|
+
bunx @better-auth/cli generate
|
|
163
|
+
|
|
164
|
+
# npm
|
|
165
|
+
npx @better-auth/cli@latest generate
|
|
166
|
+
|
|
167
|
+
# pnpm
|
|
168
|
+
pnpm dlx @better-auth/cli@latest generate
|
|
169
|
+
|
|
170
|
+
# yarn
|
|
171
|
+
yarn dlx @better-auth/cli@latest generate
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
The CLI reads your `auth.ts` configuration and generates the necessary models/migrations for your configured ORM and database automatically.
|
|
175
|
+
|
|
176
|
+
## Integrations
|
|
177
|
+
|
|
178
|
+
### Next.js App Router
|
|
179
|
+
|
|
180
|
+
Create the webhook route handler:
|
|
181
|
+
|
|
182
|
+
```typescript
|
|
183
|
+
// app/api/auth/[...betterauth]/route.ts
|
|
184
|
+
import { auth } from "@/lib/auth";
|
|
185
|
+
import { toNextJsHandler } from "better-auth/next-js";
|
|
186
|
+
|
|
187
|
+
export const { POST, GET } = toNextJsHandler(auth);
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
The plugin automatically registers the webhook endpoint at `/api/auth/mercadopago/webhook`.
|
|
191
|
+
|
|
192
|
+
### Webhook Events
|
|
193
|
+
|
|
194
|
+
The plugin handles the following MercadoPago webhook events:
|
|
195
|
+
|
|
196
|
+
| Event | Description |
|
|
197
|
+
|-------|-------------|
|
|
198
|
+
| `subscription_preapproval` | Subscription created or updated |
|
|
199
|
+
| `payment` | Payment received, refunded, or failed |
|
|
200
|
+
|
|
201
|
+
### Client Hooks (React)
|
|
202
|
+
|
|
203
|
+
```typescript
|
|
204
|
+
import { authClient } from "@/lib/auth-client";
|
|
205
|
+
|
|
206
|
+
// In your component
|
|
207
|
+
const { data: session } = authClient.useSession();
|
|
208
|
+
const subscription = authClient.mercadopago.useSubscription();
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
## Roadmap
|
|
212
|
+
|
|
213
|
+
| Feature | Status |
|
|
214
|
+
|---------|--------|
|
|
215
|
+
| ✅ Basic payment webhooks | Released |
|
|
216
|
+
| ✅ Subscription management | Released |
|
|
217
|
+
| ✅ Webhook signature verification | Released |
|
|
218
|
+
| 🔄 One-click checkout via Brick | In progress |
|
|
219
|
+
| 🔄 Subscription plan management UI | In progress |
|
|
220
|
+
| 📋 Refund management | Planned |
|
|
221
|
+
| 📋 Payment analytics endpoints | Planned |
|
|
222
|
+
| 📋 Multi-currency support | Planned |
|
|
223
|
+
| 📋 Installment (cuotas) support | Planned |
|
|
224
|
+
|
|
225
|
+
## Contributing
|
|
226
|
+
|
|
227
|
+
We welcome contributions! Please read our [CONTRIBUTING.md](./CONTRIBUTING.md) guide before submitting a PR.
|
|
228
|
+
|
|
229
|
+
## License
|
|
230
|
+
|
|
231
|
+
[MIT](./LICENSE) — Copyright © 2025 better-auth-mp contributors.
|
|
232
|
+
|
|
233
|
+
See [DISCLAIMER.md](./DISCLAIMER.md) for important legal information.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// src/client-plugin.ts
|
|
4
|
+
var mercadopagoClient = () => ({
|
|
5
|
+
$InferServerPlugin: {},
|
|
6
|
+
id: "mercadopago"
|
|
7
|
+
});
|
|
8
|
+
var mercadopagoPluginClient = mercadopagoClient;
|
|
9
|
+
|
|
10
|
+
exports.mercadopagoClient = mercadopagoClient;
|
|
11
|
+
exports.mercadopagoPluginClient = mercadopagoPluginClient;
|
|
12
|
+
//# sourceMappingURL=client-plugin.cjs.map
|
|
13
|
+
//# sourceMappingURL=client-plugin.cjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/client-plugin.ts"],"names":[],"mappings":";;;AAIO,IAAM,oBAAoB,OAC9B;AAAA,EACC,oBAAoB,EAAC;AAAA,EAErB,EAAA,EAAI;AACN,CAAA;AAGK,IAAM,uBAAA,GAA0B","file":"client-plugin.cjs","sourcesContent":["import type { BetterAuthClientPlugin } from \"better-auth/client\";\n\nimport type { mercadoPagoPlugin } from \"./index\";\n\nexport const mercadopagoClient = () =>\n ({\n $InferServerPlugin: {} as ReturnType<typeof mercadoPagoPlugin>,\n\n id: \"mercadopago\",\n }) satisfies BetterAuthClientPlugin;\n\n// Export the client plugin\nexport const mercadopagoPluginClient = mercadopagoClient;\n"]}
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { mercadoPagoPlugin } from './index.cjs';
|
|
2
|
+
import './types.cjs';
|
|
3
|
+
import 'better-auth';
|
|
4
|
+
import 'zod';
|
|
5
|
+
|
|
6
|
+
declare const mercadopagoClient: () => {
|
|
7
|
+
$InferServerPlugin: ReturnType<typeof mercadoPagoPlugin>;
|
|
8
|
+
id: "mercadopago";
|
|
9
|
+
};
|
|
10
|
+
declare const mercadopagoPluginClient: () => {
|
|
11
|
+
$InferServerPlugin: ReturnType<typeof mercadoPagoPlugin>;
|
|
12
|
+
id: "mercadopago";
|
|
13
|
+
};
|
|
14
|
+
|
|
15
|
+
export { mercadopagoClient, mercadopagoPluginClient };
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import { mercadoPagoPlugin } from './index.js';
|
|
2
|
+
import './types.js';
|
|
3
|
+
import 'better-auth';
|
|
4
|
+
import 'zod';
|
|
5
|
+
|
|
6
|
+
declare const mercadopagoClient: () => {
|
|
7
|
+
$InferServerPlugin: ReturnType<typeof mercadoPagoPlugin>;
|
|
8
|
+
id: "mercadopago";
|
|
9
|
+
};
|
|
10
|
+
declare const mercadopagoPluginClient: () => {
|
|
11
|
+
$InferServerPlugin: ReturnType<typeof mercadoPagoPlugin>;
|
|
12
|
+
id: "mercadopago";
|
|
13
|
+
};
|
|
14
|
+
|
|
15
|
+
export { mercadopagoClient, mercadopagoPluginClient };
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
// src/client-plugin.ts
|
|
2
|
+
var mercadopagoClient = () => ({
|
|
3
|
+
$InferServerPlugin: {},
|
|
4
|
+
id: "mercadopago"
|
|
5
|
+
});
|
|
6
|
+
var mercadopagoPluginClient = mercadopagoClient;
|
|
7
|
+
|
|
8
|
+
export { mercadopagoClient, mercadopagoPluginClient };
|
|
9
|
+
//# sourceMappingURL=client-plugin.js.map
|
|
10
|
+
//# sourceMappingURL=client-plugin.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/client-plugin.ts"],"names":[],"mappings":";AAIO,IAAM,oBAAoB,OAC9B;AAAA,EACC,oBAAoB,EAAC;AAAA,EAErB,EAAA,EAAI;AACN,CAAA;AAGK,IAAM,uBAAA,GAA0B","file":"client-plugin.js","sourcesContent":["import type { BetterAuthClientPlugin } from \"better-auth/client\";\n\nimport type { mercadoPagoPlugin } from \"./index\";\n\nexport const mercadopagoClient = () =>\n ({\n $InferServerPlugin: {} as ReturnType<typeof mercadoPagoPlugin>,\n\n id: \"mercadopago\",\n }) satisfies BetterAuthClientPlugin;\n\n// Export the client plugin\nexport const mercadopagoPluginClient = mercadopagoClient;\n"]}
|