К основному содержанию
скилл CX Codex

better-auth-integration — скилл для Claude Code: установка

Скилл better-auth-integration для Claude Code связывает Better Auth с Dodo Payments: синхронизирует клиентов, запускает checkout и принимает проверенные вебхуки.

MIT 192 установок ★ 14 обновлён 2026-10-20

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add dodopayments/skills --skill better-auth-integration -a claude-code
Открыть на GitHub

Что делает better-auth-integration

Скилл показывает, как подключить @dodopayments/better-auth к Better Auth. Он охватывает создание клиента при регистрации, checkout для вошедших пользователей, клиентский портал, списки подписок и платежей, передачу usage-событий и обработку подписанных вебхуков.

В серверной конфигурации используются dodopayments, checkout, portal, usage и webhooks, а в браузере — dodopaymentsClient. Для работы нужны @dodopayments/better-auth, dodopayments, better-auth и zod; Better Auth должен быть версии 1.4 или более новой версии ветки 1.x. После подключения плагина схему базы обновляют командами npx auth generate или npx auth migrate.

В checkout slug должен совпадать с настроенным продуктом. Доступ к порталу, спискам и usage требует аутентифицированного пользователя, а часть операций — подтверждённый email. Для вебхуков нужен DODO_PAYMENTS_WEBHOOK_KEY, для API — DODO_PAYMENTS_API_KEY. Без включённой нужной функции её маршрут вернёт 404.

Какие задачи решает

  • синхронизировать Better Auth пользователя с клиентом Dodo Payments
  • запустить checkout для вошедшего пользователя
  • открыть клиентский портал и историю платежей
  • передать событие измеряемого usage
  • проверить подпись входящего вебхука

Примеры запросов агенту

  • Подключи @dodopayments/better-auth к этому проекту на Better Auth и настрой создание клиента при регистрации.
  • Добавь checkout для продукта со slug premium-plan, доступный только авторизованным пользователям.
  • Настрой webhooks с DODO_PAYMENTS_WEBHOOK_KEY и обработчиком проверенного payload.

Как установить better-auth-integration

1Через Skills CLI (Vercel)

npx skills add dodopayments/skills --skill better-auth-integration -a claude-code

2Вручную: положить файлы

~/.claude/skills/better-auth-integration/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/better-auth-integration/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о better-auth-integration

Как установить better-auth-integration в Claude Code?

Выполните npx skills add dodopayments/skills --skill better-auth-integration -a claude-code. Затем проверьте файл ~/.claude/skills/better-auth-integration/SKILL.md.

Что делает better-auth-integration?

Скилл помогает подключить Better Auth к Dodo Payments: создавать клиентов при регистрации, запускать checkout, открывать портал, передавать usage и принимать проверенные вебхуки.

Что нужно для работы с better-auth-integration?

Нужны Better Auth 1.4 или более новая версия ветки 1.x, пакеты @dodopayments/better-auth, dodopayments, better-auth и zod. Для API и вебхуков также используются DODO_PAYMENTS_API_KEY и DODO_PAYMENTS_WEBHOOK_KEY.

Исходный текст

SKILL.md · MIT
---
name: better-auth-integration
description: Dodo Payments plugin for Better Auth (@dodopayments/better-auth) covering customer sync on signup, authenticated checkout, customer portal, usage ingestion, and verified webhooks. Use when an app uses Better Auth and needs the dodopayments, dodopaymentsClient, checkout, portal, usage, or webhooks plugins; for other auth stacks use framework-adapters.
---

# Better Auth Integration

Use `@dodopayments/better-auth` to synchronize Better Auth users with Dodo Payments and expose authenticated checkout, customer portal, subscription, payment, usage, and webhook endpoints.

## When to use this skill

- Create a Dodo customer automatically when a Better Auth user signs up.
- Start checkout for a signed-in user without exposing a Dodo API key.
- Let users open their customer portal or list their subscriptions and payments.
- Submit metered usage for the signed-in customer.
- Receive signature-verified Dodo webhooks through Better Auth.

## Install

```bash
npm install @dodopayments/better-auth dodopayments better-auth zod
```

Requires Better Auth 1.4 or a later 1.x release.

The package exports the lowercase server functions `dodopayments`, `checkout`, `portal`, `usage`, and `webhooks`. Its client entry point exports `dodopaymentsClient`.

## Server setup

Every endpoint is registered by a feature in `use`. Include every feature that the application calls; omitting one makes its route return 404.

```typescript
import { betterAuth } from "better-auth";
import DodoPayments from "dodopayments";
import { checkout, dodopayments, portal, usage, webhooks } from "@dodopayments/better-auth";

const dodoPayments = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: "test_mode",
});

export const auth = betterAuth({
  database: {
    // your database config
  },
  plugins: [
    dodopayments({
      client: dodoPayments,
      createCustomerOnSignUp: true,
      // `user` here is Better Auth's base user: id, name, email, emailVerified,
      // image, createdAt, updatedAt. Anything else (phone number, company, plan)
      // must first be declared via `user.additionalFields` in your Better Auth
      // config, otherwise it does not exist on the type and will be undefined.
      getCustomerParams: (user) => ({
        metadata: { better_auth_user_id: user.id },
      }),
      use: [
        checkout({
          products: [
            { productId: "pdt_premium", slug: "premium-plan" },
          ],
          successUrl: "https://app.example.com/billing/success",
          authenticatedUsersOnly: true,
        }),
        portal(),
        usage(),
        webhooks({
          webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
          onPayload: async (payload) => {
            console.log("Verified Dodo webhook:", payload.type);
          },
        }),
      ],
    }),
  ],
});
```

`products` maps an application slug to a Dodo product ID. `authenticatedUsersOnly: true` requires a Better Auth session for checkout. `getCustomerParams` adds application metadata when customer synchronization runs.

The plugin adds a `dodoCustomerId` field to the Better Auth `user` table. After adding the plugin, update your database schema with the [Better Auth CLI](https://www.better-auth.com/docs/concepts/cli):

```bash
npx auth generate   # generate the ORM schema or SQL migration, then apply it yourself
npx auth migrate    # or apply it directly (built-in Kysely adapter only)
```

## Browser client setup

```typescript
import { createAuthClient } from "better-auth/react";
import { dodopaymentsClient } from "@dodopayments/better-auth/client";

export const authClient = createAuthClient({
  plugins: [dodopaymentsClient()],
});
```

These are browser methods. They send the Better Auth session cookie automatically; do not pass `request.headers` to them.

## Create a checkout session

```typescript
import { authClient } from "@/lib/auth-client";

async function startCheckout() {
  const { data: session, error } = await authClient.dodopayments.checkoutSession({
    slug: "premium-plan",
    referenceId: "order_123",
  });

  if (error) {
    console.error("Checkout error:", error);
    return;
  }

  if (session) {
    window.location.href = session.url;
  }
}
```

`slug` must match a product configured in `checkout({ products: [...] })`. `referenceId` is optional reconciliation metadata.

## Open the customer portal

```typescript
const { data: portalSession, error } =
  await authClient.dodopayments.customer.portal();

if (error) {
  console.error("Portal error:", error);
} else if (portalSession?.redirect) {
  window.location.href = portalSession.url;
}
```

The portal endpoint requires a signed-in, verified user and resolves that user's synchronized Dodo customer.

## List subscriptions and payments

```typescript
const { data: subscriptions, error: subscriptionsError } =
  await authClient.dodopayments.customer.subscriptions.list({
    query: { page: 1, limit: 10, status: "active" },
  });

const { data: payments, error: paymentsError } =
  await authClient.dodopayments.customer.payments.list({
    query: { page: 1, limit: 10, status: "succeeded" },
  });

if (subscriptionsError || paymentsError) {
  console.error("Could not load billing history");
} else {
  console.log("Subscriptions:", subscriptions?.items);
  console.log("Payments:", payments?.items);
}
```

Both list responses use an `items` envelope. Subscription filters accept `page`, `limit`, and `status`; payment filters use the same pagination fields and payment statuses.

## Ingest metered usage

Enable `usage()` on the server, then submit an event for the signed-in customer:

```typescript
const { data, error } = await authClient.dodopayments.usage.ingest({
  event_id: "evt_usage_123",
  event_name: "api_calls",
  metadata: { requests: 100 },
  timestamp: new Date(),
});

if (error) {
  console.error("Usage ingestion failed:", error);
} else {
  console.log("Ingested events:", data?.ingested_count);
}
```

Both `usage.ingest` and `usage.meters.list` require a signed-in user with a verified email address. The plugin derives `customer_id` from the authenticated session. `event_id` is the event's idempotency key; reuse it when retrying the same event.

## Webhook endpoint

`webhooks({ webhookKey, onPayload })` verifies and handles the request itself. With Better Auth's default `/api/auth` base path, configure this URL in the Dodo dashboard:

```text
https://app.example.com/api/auth/dodopayments/webhooks
```

Do not create a second route and do not call `auth.api.dodopayments.verifyWebhook()`; that method does not exist. The plugin reads the raw request, verifies the Standard Webhooks signature with `webhookKey`, and invokes `onPayload` plus any configured event-specific callback.

## Registered endpoints

- `POST /dodopayments/checkout`
- `POST /dodopayments/checkout-session`
- `GET /dodopayments/customer/portal`
- `GET /dodopayments/customer/subscriptions/list`
- `GET /dodopayments/customer/payments/list`
- `POST /dodopayments/usage/ingest`
- `GET /dodopayments/usage/meters/list`
- `POST /dodopayments/webhooks`

Better Auth prefixes these plugin paths with its configured API base path.

## Common mistakes

**Enabling only `portal()`.** Checkout, usage, and webhook routes do not exist unless `checkout()`, `usage()`, and `webhooks()` are also present in `use`.

**Mixing browser and server APIs.** Call `authClient.dodopayments...` in browser code without a `headers` option. Use Better Auth's server API separately when handling server requests.

**Creating duplicate customers.** When `createCustomerOnSignUp` is enabled, do not also call `client.customers.create()` for the same user.

**Granting access from browser state.** Treat verified webhook events or a server-side Dodo lookup as the source of truth for entitlements.

**Adding a custom webhook verifier.** The plugin owns `/dodopayments/webhooks`, signature verification, and callback dispatch.

## Resources

- [Better Auth Adapter](https://docs.dodopayments.com/developer-resources/better-auth-adaptor)
- [Dodo Payments Better Auth package](https://www.npmjs.com/package/@dodopayments/better-auth)
- [Dodo Payments SDK](https://github.com/dodopayments/dodopayments-typescript)

© dodopayments · MIT · dodopayments/skills

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
better-auth-security-best-practices better-auth Скилл better-auth-security-best-practices настраивает защиту Better Auth: ограничивает частоту запросов, проверяет происхождение, шифрует токены и защищает пользовательские сессии. CX Codex +1 52 200установок better-auth giuseppe-trisciuoglio Скилл с готовыми шаблонами Better Auth: подключение к NestJS, Drizzle ORM и PostgreSQL, вход через соцсети и плагины вроде 2FA и passkey. CX Codex +1 3 800установок nuxt-better-auth onmax Скилл nuxt-better-auth помогает настраивать аутентификацию в Nuxt через @nuxtjs/better-auth, защищать маршруты и работать с сессиями. Пригодится при внедрении Better Auth. CX Codex +1 2 100установок safe-action-better-auth next-safe-action Скилл safe-action-better-auth для Claude Code помогает добавить аутентификацию и проверку доступа к safe actions через Better Auth. Он включается при настройке middleware, сессии и отказа в доступе. CX Codex +1 499установок better-auth-authentication bobmatnyc Скилл better-auth-authentication для TypeScript-приложений: помогает настроить вход по email и паролю, социальные провайдеры и проверку почты. CX Codex +1 406установок better-auth-core bobmatnyc Скилл better-auth-core для Claude Code и других агентов: настраивает Better Auth в TypeScript — инстанс, БД, обработчики, клиент и сессии. CX Codex +1 376установок

Из того же набора17

Весь набор →
testing-and-go-live Скилл testing-and-go-live проводит платёжную интеграцию Dodo Payments через тестовый режим: карты, отказы, продления, вебхуки. И доводит до боевого запуска по чек-листу. CX Codex +1 219установок framework-adapters Скилл framework-adapters подключает официальные адаптеры Dodo Payments в Next.js, Express, Hono или Nuxt. Настраивает маршруты для чекаута, портала клиента и вебхуков. CX Codex +1 209установок refunds-and-disputes Скилл refunds-and-disputes обучает агента управлять возвратами и спорами в Dodo Payments. Помогает настроить вебхуки, частичные выплаты по позициям заказа и отзыв доступа у клиентов. CX Codex +1 208установок product-catalog-management Скилл product-catalog-management управляет каталогом Dodo Payments: создание разовых и регулярных тарифов, работа с аддонами и загрузка изображений. CX Codex +1 208установок customer-management Скилл customer-management для Claude Code управляет клиентами Dodo Payments: создаёт записи, настраивает портал и способы оплаты, ведёт кошельки и связывает пользователей приложения с ID клиентов для биллинга. CX Codex +1 202установок discounts-and-promotions Скилл discounts-and-promotions помогает настроить промокоды Dodo Payments: создать скидку, проверить её ограничения и разобраться, почему код не применяется. CX Codex +1 199установок localized-pricing Скилл localized-pricing помогает настроить мультивалютные расчёты в Dodo Payments: фиксированные региональные цены, конвертацию Adaptive Currency и скидки паритета покупательской способности (PPP). CX Codex +1 198установок mobile-checkout Скилл mobile-checkout помогает встроить оплату Dodo Payments в мобильные приложения на React Native, Flutter, iOS и Android через системный браузер. CX Codex +1 192установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой