@dodopayments/opencode-plugin 0.6.0 → 0.6.2

package/README.md

@@ -175,6 +175,7 @@ If you prefer the local stdio API server with your own API key instead of the de
 | `dodo-best-practices` | SDK setup, environments, API keys, and the canonical checkout-to-webhook architecture |
 | `framework-adapters` | Official `@dodopayments/*` handlers for Next.js, Express, Hono, Astro, Remix, SvelteKit, Nuxt, Fastify, TanStack, Bun, Convex |
 | `testing-and-go-live` | Test mode, test payment methods, webhook testing, production launch checklist |
+| `dodo-mcp-usage` | When to use the documentation vs API MCP servers, test-mode safety rules, auth, troubleshooting |
 
 **Accepting payments**
 

package/opencode-plugin/README.md

@@ -37,7 +37,7 @@ opencode run "List every skill available to you by name."
 
 ## What you get
 
-Agent skills (auto-loaded when relevant): `dodo-best-practices`, `framework-adapters`, `testing-and-go-live`, `checkout-integration`, `subscription-integration`, `mobile-checkout`, `webhook-integration`, `credit-based-billing`, `usage-based-billing`, `license-keys`, `product-catalog-management`, `discounts-and-promotions`, `localized-pricing`, `customer-management`, `refunds-and-disputes`, `billing-sdk`, `better-auth-integration`.
+Agent skills (auto-loaded when relevant): `dodo-best-practices`, `dodo-mcp-usage`, `framework-adapters`, `testing-and-go-live`, `checkout-integration`, `subscription-integration`, `mobile-checkout`, `webhook-integration`, `credit-based-billing`, `usage-based-billing`, `license-keys`, `product-catalog-management`, `discounts-and-promotions`, `localized-pricing`, `customer-management`, `refunds-and-disputes`, `billing-sdk`, `better-auth-integration`.
 
 Two MCP servers (registered automatically):
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@dodopayments/opencode-plugin",
-    "version": "0.6.0",
+    "version": "0.6.2",
     "description": "Dodo Payments agent skills and MCP servers for OpenCode.",
     "type": "module",
     "main": "opencode-plugin/index.js",

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

@@ -1,6 +1,6 @@
 ---
 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.
+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
@@ -18,9 +18,11 @@ Use `@dodopayments/better-auth` to synchronize Better Auth users with Dodo Payme
 ## Install
 
 ```bash
-npm install @dodopayments/better-auth dodopayments better-auth
+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
@@ -76,6 +78,13 @@ export const auth = betterAuth({
 
 `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
@@ -170,7 +179,7 @@ if (error) {
 }
 ```
 
-The plugin derives `customer_id` from the authenticated session. `event_id` is the event's idempotency key; reuse it when retrying the same event.
+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
 

package/skills/billing-sdk/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: billing-sdk
-description: Guide for building billing UI with BillingSDK - the open-source React component library for pricing tables, subscription management, usage meters, invoice history, and customer portal flows wired to Dodo Payments.
+description: BillingSDK, the open-source React and shadcn component library for Dodo Payments billing UI. Use when building pricing tables, pricing pages, account billing pages, usage meters, credit balances, invoice history, or cancel and upgrade UI in React or Next.js, or running @billingsdk/cli init; keep Dodo API calls server-side.
 ---
 
 # BillingSDK
@@ -75,8 +75,11 @@ From the current official registry, grouped by purpose:
 | Payments | `payment-details`, `payment-details-two`, `payment-method-selector`, `payment-card`, `payment-failure` |
 | Promotion and trials | `banner`, `limited-offer-dialog`, `trial-expiry-card` |
 
-`pricing-table-one` is the only block with an officially published prop example, reproduced below. For
-every other block, run `add` and read the generated file's props type.
+Most blocks have a published usage example and props table on their page at
+[billingsdk.com/docs/components](https://billingsdk.com/docs/components) (for example `subscription-management`
+and `billing-settings`); `pricing-table-one` is reproduced in
+[references/pricing-page.md](references/pricing-page.md). The generated file's props type is still
+authoritative for the version you installed, so read it after running `add`.
 
 ## Server client
 
@@ -101,169 +104,14 @@ are `https://test.dodopayments.com` and `https://live.dodopayments.com`.
 
 ## Pricing page
 
-### 1. Plan catalogue
+Full guide: [references/pricing-page.md](references/pricing-page.md).
 
-Keep the product ids and the display copy in one module. The `price` here is a display number rendered by
-the component — the amount actually charged comes from the Dodo product catalogue, and Dodo API amounts
-are always in the smallest currency unit (cents). Treat this file as a mirror of the dashboard and
-reconcile it when you change a price.
+Covers:
 
-```typescript
-// lib/plans.ts
-export type PlanId = 'starter' | 'pro';
-
-export interface Plan {
-  id: PlanId;
-  title: string;
-  price: number;
-  period: string;
-  features: string[];
-  popular: boolean;
-}
-
-export const PLANS: readonly Plan[] = [
-  {
-    id: 'starter',
-    title: 'Starter',
-    price: 9,
-    period: 'month',
-    features: ['100 requests', 'Basic support', '1 project'],
-    popular: false,
-  },
-  {
-    id: 'pro',
-    title: 'Pro',
-    price: 29,
-    period: 'month',
-    features: ['Unlimited requests', 'Priority support', '10 projects'],
-    popular: true,
-  },
-];
-```
-
-### 2. Product id map — server only
-
-Never let the browser choose an arbitrary `product_id`. Map the public plan slug to a `pdt_` id on the
-server and reject anything else.
-
-```typescript
-// lib/plan-products.server.ts
-import 'server-only';
-import type { PlanId } from './plans';
-
-const PRODUCT_IDS: Record<PlanId, string> = {
-  starter: 'pdt_starter_monthly',
-  pro: 'pdt_pro_monthly',
-};
-
-export function productIdForPlan(value: unknown): string | null {
-  if (typeof value !== 'string') return null;
-  return PRODUCT_IDS[value as PlanId] ?? null;
-}
-```
-
-### 3. Checkout route
-
-```typescript
-// app/api/checkout/route.ts
-import { NextResponse } from 'next/server';
-import { dodo } from '@/lib/dodopayments';
-import { productIdForPlan } from '@/lib/plan-products.server';
-import { getCurrentUser } from '@/lib/auth';
-
-export async function POST(request: Request) {
-  const user = await getCurrentUser();
-  if (!user) {
-    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
-  }
-
-  const body: unknown = await request.json();
-  const planId = (body as { planId?: unknown }).planId;
-  const productId = productIdForPlan(planId);
-
-  if (!productId) {
-    return NextResponse.json({ error: 'Unknown plan' }, { status: 400 });
-  }
-
-  try {
-    const session = await dodo.checkoutSessions.create({
-      product_cart: [{ product_id: productId, quantity: 1 }],
-      customer: { email: user.email, name: user.name },
-      return_url: `${process.env.NEXT_PUBLIC_APP_URL}/billing/return`,
-      cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
-      metadata: { app_user_id: user.id },
-    });
-
-    if (!session.checkout_url) {
-      return NextResponse.json({ error: 'No checkout URL returned' }, { status: 502 });
-    }
-
-    return NextResponse.json({ checkoutUrl: session.checkout_url });
-  } catch (error) {
-    console.error('Checkout session creation failed', error);
-    return NextResponse.json({ error: 'Could not start checkout' }, { status: 500 });
-  }
-}
-```
-
-`checkout_url` is nullable — it is absent when the session is created with `payment_method_id` — so guard
-it rather than redirecting to `undefined`. Checkout URLs are single-use and normally expire after 24 hours.
-
-Use `checkoutSessions.create`. `payments.create` and `subscriptions.create` are deprecated for new
-integrations. Checkout parameters are covered in depth in the `checkout-integration` skill.
-
-### 4. Client component
-
-```tsx
-// components/pricing-plans.tsx
-'use client';
-
-import { useState } from 'react';
-import { PricingTableOne } from '@/components/billingsdk/pricing-table-one';
-import { PLANS } from '@/lib/plans';
-
-export function PricingPlans() {
-  const [error, setError] = useState<string | null>(null);
-
-  async function handlePlanSelect(planId: string) {
-    setError(null);
-    try {
-      const response = await fetch('/api/checkout', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ planId }),
-      });
-
-      if (!response.ok) {
-        setError('Could not start checkout. Please try again.');
-        return;
-      }
-
-      const { checkoutUrl } = (await response.json()) as { checkoutUrl: string };
-      window.location.href = checkoutUrl;
-    } catch {
-      setError('Network error. Please try again.');
-    }
-  }
-
-  return (
-    <>
-      <PricingTableOne
-        plans={PLANS}
-        title="Choose your plan"
-        description="Select the plan that works best for you"
-        onPlanSelect={handlePlanSelect}
-        theme="classic"
-        size="medium"
-      />
-      {error ? <p role="alert">{error}</p> : null}
-    </>
-  );
-}
-```
-
-Render `<PricingPlans />` from `app/pricing/page.tsx`. Nothing secret crosses into the client component:
-it sends a plan slug and receives a URL.
+- Plan catalogue
+- Product id map — server only
+- Checkout route
+- Client component
 
 ## Subscription management and customer portal
 
@@ -458,14 +306,14 @@ signature verification is covered in the `webhook-integration` skill.
 **Accepting a raw `product_id` from the request body.** A caller can then check out against any product in
 your catalogue, including internal or discounted ones. Map an opaque plan slug to a `pdt_` id server-side.
 
-**Hardcoding prices in the client.** `PLANS[].price` is display text. When you change a price in the Dodo
+**Hardcoding prices in the client.** `plans[].monthlyPrice` / `yearlyPrice` are display text. When you change a price in the Dodo
 dashboard, the checkout charges the new amount while the pricing page keeps advertising the old one.
-Reconcile `lib/plans.ts` with the dashboard as part of any pricing change.
+Reconcile `lib/billingsdk-config.ts` with the dashboard as part of any pricing change.
 
 **`npm install billingsdk`.** The root repository package is private. Install through
 `@billingsdk/cli` or the shadcn registry instead.
 
-**Guessing prop names.** `pricing-table-one` is the only block with a published prop example. Open the
+**Guessing prop names.** Check the block's page on billingsdk.com/docs/components, then open the
 generated file under `components/billingsdk/` and read the exported props type before wiring anything else.
 
 **Using `DODO_PAYMENTS_WEBHOOK_SECRET`.** The SDK reads `DODO_PAYMENTS_WEBHOOK_KEY` for the `webhookKey`

package/skills/billing-sdk/references/pricing-page.md

@@ -0,0 +1,197 @@
+# BillingSDK: Pricing page
+
+
+### 1. Plan catalogue
+
+`pricing-table-one` takes BillingSDK's `Plan[]`, not an arbitrary shape. Adding the component generates
+`lib/billingsdk-config.ts`, which exports the `Plan` interface and a sample `plans` array — edit that array
+rather than defining your own type. Prices are display **strings** (`monthlyPrice`, `yearlyPrice`) and
+`features` are objects. The amount actually charged comes from the Dodo product catalogue (always in the
+smallest currency unit), so treat this file as a mirror of the dashboard and reconcile it when you change a
+price.
+
+```typescript
+// lib/billingsdk-config.ts (generated by `add pricing-table-one`; edit the plans)
+export interface Plan {
+  id: string;
+  title: string;
+  description: string;
+  highlight?: boolean;
+  type?: 'monthly' | 'yearly';
+  currency?: string;
+  monthlyPrice: string;
+  yearlyPrice: string;
+  buttonText: string;
+  badge?: string;
+  features: {
+    name: string;
+    icon: string;
+    iconColor?: string;
+  }[];
+}
+
+export const plans: Plan[] = [
+  {
+    id: 'starter',
+    title: 'Starter',
+    description: 'For individuals getting started.',
+    currency: '$',
+    monthlyPrice: '9',
+    yearlyPrice: '90',
+    buttonText: 'Choose Starter',
+    features: [
+      { name: '100 requests', icon: 'check' },
+      { name: 'Basic support', icon: 'check' },
+      { name: '1 project', icon: 'check' },
+    ],
+  },
+  {
+    id: 'pro',
+    title: 'Pro',
+    description: 'For teams running in production.',
+    currency: '$',
+    monthlyPrice: '29',
+    yearlyPrice: '290',
+    buttonText: 'Choose Pro',
+    badge: 'Most popular',
+    highlight: true,
+    features: [
+      { name: 'Unlimited requests', icon: 'check' },
+      { name: 'Priority support', icon: 'check' },
+      { name: '10 projects', icon: 'check' },
+    ],
+  },
+];
+```
+
+The generated file is the contract for your installed version; if its `Plan` differs from the above, follow
+the file. `onPlanSelect` receives only the plan `id`, so the ids here are the slugs the server maps below.
+
+This example sells **monthly plans only**: `yearlyPrice` is required by the `Plan` type and is displayed,
+but the server map below has only monthly products. To sell yearly too, create the yearly products in Dodo,
+track the table's billing-period toggle in your own state (it is not passed to `onPlanSelect`), send it with
+the plan id, and key the server map by plan and period (for example `pro:yearly`).
+
+### 2. Product id map — server only
+
+Never let the browser choose an arbitrary `product_id`. Map the public plan slug to a `pdt_` id on the
+server and reject anything else.
+
+```typescript
+// lib/plan-products.server.ts
+import 'server-only';
+
+// Keys must match the `id`s in lib/billingsdk-config.ts.
+const PRODUCT_IDS: Readonly<Record<string, string>> = {
+  starter: 'pdt_starter_monthly',
+  pro: 'pdt_pro_monthly',
+};
+
+export function productIdForPlan(value: unknown): string | null {
+  if (typeof value !== 'string' || !Object.hasOwn(PRODUCT_IDS, value)) return null;
+  return PRODUCT_IDS[value];
+}
+```
+
+### 3. Checkout route
+
+```typescript
+// app/api/checkout/route.ts
+import { NextResponse } from 'next/server';
+import { dodo } from '@/lib/dodopayments';
+import { productIdForPlan } from '@/lib/plan-products.server';
+import { getCurrentUser } from '@/lib/auth';
+
+export async function POST(request: Request) {
+  const user = await getCurrentUser();
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  const body: unknown = await request.json();
+  const planId = (body as { planId?: unknown }).planId;
+  const productId = productIdForPlan(planId);
+
+  if (!productId) {
+    return NextResponse.json({ error: 'Unknown plan' }, { status: 400 });
+  }
+
+  try {
+    const session = await dodo.checkoutSessions.create({
+      product_cart: [{ product_id: productId, quantity: 1 }],
+      customer: { email: user.email, name: user.name },
+      return_url: `${process.env.NEXT_PUBLIC_APP_URL}/billing/return`,
+      cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/pricing`,
+      metadata: { app_user_id: user.id },
+    });
+
+    if (!session.checkout_url) {
+      return NextResponse.json({ error: 'No checkout URL returned' }, { status: 502 });
+    }
+
+    return NextResponse.json({ checkoutUrl: session.checkout_url });
+  } catch (error) {
+    console.error('Checkout session creation failed', error);
+    return NextResponse.json({ error: 'Could not start checkout' }, { status: 500 });
+  }
+}
+```
+
+`checkout_url` is nullable — it is absent when the session is created with `payment_method_id` — so guard
+it rather than redirecting to `undefined`. Checkout URLs are single-use and normally expire after 24 hours.
+
+Use `checkoutSessions.create`. `payments.create` and `subscriptions.create` are deprecated for new
+integrations. Checkout parameters are covered in depth in the `checkout-integration` skill.
+
+### 4. Client component
+
+```tsx
+// components/pricing-plans.tsx
+'use client';
+
+import { useState } from 'react';
+import { PricingTableOne } from '@/components/billingsdk/pricing-table-one';
+import { plans } from '@/lib/billingsdk-config';
+
+export function PricingPlans() {
+  const [error, setError] = useState<string | null>(null);
+
+  async function handlePlanSelect(planId: string) {
+    setError(null);
+    try {
+      const response = await fetch('/api/checkout', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ planId }),
+      });
+
+      if (!response.ok) {
+        setError('Could not start checkout. Please try again.');
+        return;
+      }
+
+      const { checkoutUrl } = (await response.json()) as { checkoutUrl: string };
+      window.location.href = checkoutUrl;
+    } catch {
+      setError('Network error. Please try again.');
+    }
+  }
+
+  return (
+    <>
+      <PricingTableOne
+        plans={plans}
+        title="Choose your plan"
+        description="Select the plan that works best for you"
+        onPlanSelect={handlePlanSelect}
+        theme="classic"
+        size="medium"
+      />
+      {error ? <p role="alert">{error}</p> : null}
+    </>
+  );
+}
+```
+
+Render `<PricingPlans />` from `app/pricing/page.tsx`. Nothing secret crosses into the client component:
+it sends a plan slug and receives a URL.