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 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"]}