@dodopayments/opencode-plugin 0.3.2 → 0.4.0

package/skills/better-auth-integration/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: better-auth-integration
+description: Guide only for applications using @dodopayments/better-auth, covering authenticated customer sync, checkout, portal access, usage ingestion, and verified webhook callbacks.
+---
+
+# 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
+```
+
+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.
+
+## 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);
+}
+```
+
+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)