@dodopayments/opencode-plugin 0.5.1 → 0.6.1

package/skills/framework-adapters/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: framework-adapters
-description: Guide for mounting official @dodopayments/* checkout, portal, and verified-webhook route handlers in supported web frameworks; use domain skills for payment and lifecycle logic.
+description: Official @dodopayments/* framework adapters that mount Checkout, CustomerPortal, and Webhooks route handlers. Use when integrating Dodo Payments into Next.js, Express, Fastify, Hono, Astro, Remix, SvelteKit, Nuxt, TanStack, Bun, or Convex, such as @dodopayments/nextjs; use domain skills for payment and subscription logic.
 ---
 
 # Framework Adapters
@@ -21,10 +21,12 @@ Dodo publishes `@dodopayments/*` packages that wrap the core SDK with framework-
 
 Each adapter exposes three handler families:
 
-- **Checkout:** static (GET only), dynamic (POST with cart), or session (POST with pre-built session).
+- **Checkout:** static (GET only), dynamic (POST, creates a payment or subscription via the deprecated `POST /payments` / `POST /subscriptions` endpoints - existing integrations only), or session (POST with a checkout session payload - use this for new integrations).
 - **CustomerPortal:** generates a time-bound portal session link.
 - **Webhooks:** verifies webhook signatures and dispatches typed events.
 
+> **Security - CustomerPortal does not authenticate.** Every `CustomerPortal` handler opens the portal for whatever `?customer_id=` it receives. Mounted as-is, any visitor can open any customer's portal by guessing or enumerating IDs. Put the route behind your own authentication and resolve the customer ID **server-side from the signed-in session**; never accept it from the client. The portal examples below do this.
+
 **Export names are not uniform across adapters.** Most export `Checkout` / `CustomerPortal` / `Webhooks`, but two differ, and the return shapes differ as well. Check this table before writing imports:
 
 | Adapter | Checkout export | Portal export | Handler shape |
@@ -34,7 +36,7 @@ Each adapter exposes three handler families:
 | `fastify` | `Checkout` | `CustomerPortal` | returns `{ getHandler, postHandler }` |
 | `sveltekit` | `Checkout` | `CustomerPortal` | returns `{ GET, POST }` / `{ GET }` |
 | `nuxt` | `checkoutHandler` (auto-imported) | `customerPortalHandler` | no import statement |
-| `convex` | `DodoPayments` component | — | `createDodoWebhookHandler` |
+| `convex` | `checkout` (from `dodo.api()`) | `customerPortal` (from `dodo.api()`, uses `identify`) | `createDodoWebhookHandler` |
 
 The adapters handle raw body preservation for webhook verification, environment variable mapping, and framework-specific request/response shapes. Checkout payload design belongs to the `checkout-integration` skill; webhook business logic belongs to `webhook-integration`; portal behavior belongs to `customer-management`.
 
@@ -71,7 +73,7 @@ DODO_PAYMENTS_RETURN_URL=https://yourdomain.com/checkout/success
 NUXT_PRIVATE_BEARER_TOKEN=dodo_test_...
 NUXT_PRIVATE_WEBHOOK_KEY=your-webhook-secret
 NUXT_PRIVATE_ENVIRONMENT=test_mode
-NUXT_PRIVATE_RETURNURL=https://yourdomain.com/checkout/success
+NUXT_PRIVATE_RETURN_URL=https://yourdomain.com/checkout/success
 ```
 
 **Convex** uses dashboard environment variables (not local `.env`):
@@ -108,6 +110,7 @@ Defaulting to `test_mode` is deliberate: a missing or misspelled variable must n
 ```typescript
 // app/api/checkout/route.ts
 import { Checkout } from "@dodopayments/nextjs";
+import { dodoEnvironment } from "@/lib/dodo-env";
 
 export const GET = Checkout({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
@@ -128,12 +131,26 @@ export const POST = Checkout({
 
 ```typescript
 // app/api/customer-portal/route.ts
+import { NextRequest } from "next/server";
 import { CustomerPortal } from "@dodopayments/nextjs";
+import { dodoEnvironment } from "@/lib/dodo-env";
+// your auth helper
+import { getSessionUser } from "@/lib/auth";
 
-export const GET = CustomerPortal({
+const portal = CustomerPortal({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
   environment: dodoEnvironment,
 });
+
+export async function GET(req: NextRequest) {
+  const user = await getSessionUser(req);
+  if (!user?.dodoCustomerId) return new Response("Unauthorized", { status: 401 });
+
+  // Overwrite any client-supplied ?customer_id= with the signed-in user's ID.
+  const url = new URL(req.url);
+  url.searchParams.set("customer_id", user.dodoCustomerId);
+  return portal(new NextRequest(url, req));
+}
 ```
 
 ### Webhooks
@@ -164,6 +181,8 @@ import { checkoutHandler } from "@dodopayments/express";
 import { dodoEnvironment } from "./lib/dodo-env";
 
 const app = express();
+// Required before the POST route: the session/dynamic handlers read req.body.
+app.use(express.json());
 
 app.get("/api/checkout", checkoutHandler({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
@@ -182,13 +201,24 @@ app.post("/api/checkout", checkoutHandler({
 
 ### Customer Portal
 
+The adapter's `CustomerPortal` reads `customer_id` from `req.query`, which you cannot safely rewrite in Express 5. Behind your auth middleware, call the SDK directly with the session's customer ID instead:
+
 ```typescript
-import { CustomerPortal } from "@dodopayments/express";
+import DodoPayments from "dodopayments";
+import { dodoEnvironment } from "./lib/dodo-env";
 
-app.get("/api/customer-portal", CustomerPortal({
+const client = new DodoPayments({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
   environment: dodoEnvironment,
-}));
+});
+
+// requireAuth = your session middleware; it must set req.user.
+app.get("/api/customer-portal", requireAuth, async (req, res) => {
+  const customerId = req.user?.dodoCustomerId; // from the session, never from req.query
+  if (!customerId) return res.status(401).send("Unauthorized");
+  const session = await client.customers.customerPortal.create(customerId);
+  res.redirect(session.link);
+});
 ```
 
 ### Webhooks
@@ -196,7 +226,10 @@ app.get("/api/customer-portal", CustomerPortal({
 ```typescript
 import { Webhooks } from "@dodopayments/express";
 
-app.use(express.raw({ type: "application/json" }));
+// The Express handler verifies the signature against the PARSED req.body, so it
+// needs express.json() (skip this line if already registered). Do NOT use express.raw() here - the
+// handler would see a Buffer and reject every request.
+app.use(express.json());
 
 app.post("/api/webhook", Webhooks({
   webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
@@ -269,6 +302,7 @@ fastify.post("/api/webhook", Webhooks({
 ```typescript
 import { Hono } from "hono";
 import { Checkout } from "@dodopayments/hono";
+import { dodoEnvironment } from "./lib/dodo-env";
 
 const app = new Hono();
 
@@ -289,13 +323,24 @@ app.post("/api/checkout", Checkout({
 
 ### Customer Portal
 
+The adapter's `CustomerPortal` reads `c.req.query("customer_id")`. Behind your auth middleware, call the SDK directly with the session's customer ID instead:
+
 ```typescript
-import { CustomerPortal } from "@dodopayments/hono";
+import DodoPayments from "dodopayments";
+import { dodoEnvironment } from "./lib/dodo-env";
 
-app.get("/api/customer-portal", CustomerPortal({
+const client = new DodoPayments({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
   environment: dodoEnvironment,
-}));
+});
+
+// Assumes your auth middleware ran first and stored the user on the context.
+app.get("/api/customer-portal", async (c) => {
+  const customerId = c.get("user")?.dodoCustomerId; // from the session, never from the query
+  if (!customerId) return c.text("Unauthorized", 401);
+  const session = await client.customers.customerPortal.create(customerId);
+  return c.redirect(session.link);
+});
 ```
 
 ### Webhooks
@@ -373,6 +418,7 @@ export const POST = Webhooks({
 // app/routes/api.checkout.tsx
 import { Checkout } from "@dodopayments/remix";
 import type { LoaderFunctionArgs, ActionFunctionArgs } from "@remix-run/node";
+import { dodoEnvironment } from "~/lib/dodo-env";
 
 const checkoutHandler = Checkout({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
@@ -391,13 +437,24 @@ export const action = ({ request }: ActionFunctionArgs) => checkoutHandler(reque
 // app/routes/api.customer-portal.tsx
 import { CustomerPortal } from "@dodopayments/remix";
 import type { LoaderFunctionArgs } from "@remix-run/node";
+import { dodoEnvironment } from "~/lib/dodo-env";
+// your auth helper
+import { getSessionUser } from "~/lib/auth.server";
 
 const portalHandler = CustomerPortal({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
   environment: dodoEnvironment,
 });
 
-export const loader = ({ request }: LoaderFunctionArgs) => portalHandler(request);
+export const loader = async ({ request }: LoaderFunctionArgs) => {
+  const user = await getSessionUser(request);
+  if (!user?.dodoCustomerId) return new Response("Unauthorized", { status: 401 });
+
+  // Overwrite any client-supplied ?customer_id= with the signed-in user's ID.
+  const url = new URL(request.url);
+  url.searchParams.set("customer_id", user.dodoCustomerId);
+  return portalHandler(new Request(url, request));
+};
 ```
 
 ### Webhooks
@@ -428,15 +485,26 @@ export const action = ({ request }: ActionFunctionArgs) =>
 import { Checkout } from "@dodopayments/sveltekit";
 import { DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_RETURN_URL, DODO_PAYMENTS_ENVIRONMENT } from "$env/static/private";
 
-const checkoutHandler = Checkout({
+const dodoEnvironment = DODO_PAYMENTS_ENVIRONMENT === "live_mode" ? "live_mode" : "test_mode";
+
+// Checkout() returns { GET, POST }, not a handler. Export GET from a "static"
+// handler - the GET of a "session"/"dynamic" handler returns 400.
+const staticCheckout = Checkout({
+  bearerToken: DODO_PAYMENTS_API_KEY,
+  returnUrl: DODO_PAYMENTS_RETURN_URL,
+  environment: dodoEnvironment,
+  type: "static",
+});
+
+const sessionCheckout = Checkout({
   bearerToken: DODO_PAYMENTS_API_KEY,
   returnUrl: DODO_PAYMENTS_RETURN_URL,
-  environment: DODO_PAYMENTS_ENVIRONMENT,
+  environment: dodoEnvironment,
   type: "session",
 });
 
-export const GET = checkoutHandler;
-export const POST = checkoutHandler;
+export const GET = staticCheckout.GET;
+export const POST = sessionCheckout.POST;
 ```
 
 ### Webhooks
@@ -469,7 +537,7 @@ export default defineNuxtConfig({
       bearerToken: process.env.NUXT_PRIVATE_BEARER_TOKEN,
       webhookKey: process.env.NUXT_PRIVATE_WEBHOOK_KEY,
       environment: process.env.NUXT_PRIVATE_ENVIRONMENT,
-      returnUrl: process.env.NUXT_PRIVATE_RETURNURL,
+      returnUrl: process.env.NUXT_PRIVATE_RETURN_URL,
     },
   },
 });
@@ -518,7 +586,8 @@ export default Webhooks({
 ```typescript
 // src/routes/api/checkout.ts
 import { Checkout } from "@dodopayments/tanstack";
-import { dodoEnvironment } from "./lib/dodo-env";
+// src/lib/dodo-env.ts
+import { dodoEnvironment } from "../../lib/dodo-env";
 
 export const GET = Checkout({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
@@ -545,6 +614,9 @@ TanStack Start's server-route definition API has changed across releases (`creat
 
 ```typescript
 import { Checkout, CustomerPortal } from "@dodopayments/bun";
+import { dodoEnvironment } from "./lib/dodo-env";
+// your auth helper
+import { getSessionUser } from "./lib/auth";
 
 const checkoutHandler = Checkout({
   bearerToken: process.env.DODO_PAYMENTS_API_KEY,
@@ -560,14 +632,18 @@ const portalHandler = CustomerPortal({
 
 Bun.serve({
   port: 3000,
-  fetch(request) {
+  async fetch(request) {
     const url = new URL(request.url);
 
     if (url.pathname === "/api/checkout") {
       return checkoutHandler(request);
     }
     if (url.pathname === "/api/customer-portal" && request.method === "GET") {
-      return portalHandler(request);
+      const user = await getSessionUser(request);
+      if (!user?.dodoCustomerId) return new Response("Unauthorized", { status: 401 });
+      // Overwrite any client-supplied ?customer_id= with the signed-in user's ID.
+      url.searchParams.set("customer_id", user.dodoCustomerId);
+      return portalHandler(new Request(url, request));
     }
 
     return new Response("Not Found", { status: 404 });
@@ -591,20 +667,74 @@ app.use(dodopayments);
 export default app;
 ```
 
-Then use the component in your actions and HTTP routes:
+Run `npx convex dev` once to generate `components.dodopayments`. `identify` needs an app-owned lookup from the signed-in user to their Dodo customer ID. This assumes a `customers` table with `authId` and `dodoCustomerId` fields and a `by_auth_id` index; adapt it to your schema:
+
+```typescript
+// convex/customers.ts
+import { internalQuery } from "./_generated/server";
+import { v } from "convex/values";
+
+export const getByAuthId = internalQuery({
+  args: { authId: v.string() },
+  handler: async (ctx, { authId }) =>
+    ctx.db
+      .query("customers")
+      .withIndex("by_auth_id", (q) => q.eq("authId", authId))
+      .unique(),
+});
+```
+
+Then create a `DodoPayments` client in a local module and export its API methods:
 
 ```typescript
-// convex/checkout.ts
-import { mutation } from "./_generated/server";
-import { components } from "./_generated/server";
-
-export const createCheckoutSession = mutation({
-  args: { customerId: v.string() },
-  handler: async (ctx, args) => {
-    const dodo = components.dodopayments;
-    return dodo.checkout.createSession(ctx, {
-      customerId: args.customerId,
-      // ... checkout params
+// convex/dodo.ts
+import { DodoPayments } from "@dodopayments/convex";
+import { components, internal } from "./_generated/api";
+
+const apiKey = process.env.DODO_PAYMENTS_API_KEY;
+if (!apiKey) throw new Error("DODO_PAYMENTS_API_KEY is not set");
+
+export const dodo = new DodoPayments(components.dodopayments, {
+  // Maps the signed-in Convex user to a Dodo customer; used by customerPortal.
+  identify: async (ctx) => {
+    const identity = await ctx.auth.getUserIdentity();
+    if (!identity) return null;
+    const customer = await ctx.runQuery(internal.customers.getByAuthId, {
+      authId: identity.subject,
+    });
+    return customer ? { dodoCustomerId: customer.dodoCustomerId } : null;
+  },
+  apiKey,
+  environment: process.env.DODO_PAYMENTS_ENVIRONMENT === "live_mode" ? "live_mode" : "test_mode",
+});
+
+export const { checkout, customerPortal } = dodo.api();
+```
+
+Call `checkout` from an **action** (mutations cannot make network calls), passing the checkout session fields in `payload`. The client sends a plan slug; the server maps it to a product ID and owns the return URL, so a caller cannot pick an arbitrary product or redirect target:
+
+```typescript
+// convex/payments.ts
+import { action } from "./_generated/server";
+import { v } from "convex/values";
+import { checkout } from "./dodo";
+
+// Public plan slug -> Dodo product ID. Never accept a product_id from the client.
+const PRODUCT_IDS: Readonly<Record<string, string>> = {
+  starter: "pdt_starter_monthly",
+  pro: "pdt_pro_monthly",
+};
+
+export const createCheckout = action({
+  args: { plan: v.string() },
+  handler: async (ctx, { plan }) => {
+    if (!Object.hasOwn(PRODUCT_IDS, plan)) throw new Error(`Unknown plan: ${plan}`);
+    // Returns { checkout_url }
+    return await checkout(ctx, {
+      payload: {
+        product_cart: [{ product_id: PRODUCT_IDS[plan], quantity: 1 }],
+        return_url: process.env.DODO_PAYMENTS_RETURN_URL,
+      },
     });
   },
 });
@@ -618,7 +748,7 @@ Convex only supports session checkout, not static or dynamic modes.
 
 2. **Wrong webhook variable name:** Check whether your adapter uses `DODO_PAYMENTS_WEBHOOK_KEY` or `DODO_PAYMENTS_WEBHOOK_SECRET`. The docs are inconsistent; use the name your adapter actually references.
 
-3. **Forgetting raw body preservation:** Webhook handlers must receive the raw request body, not a re-parsed JSON object. Fastify requires an explicit string body parser; Express needs `express.raw()`; other frameworks handle this automatically. Webhook signature verification is covered in the `webhook-integration` skill.
+3. **Forgetting raw body preservation:** Webhook handlers must receive the raw request body, not a re-parsed JSON object. Fastify requires an explicit string body parser; other frameworks handle this automatically. **Express is the exception:** its `Webhooks` handler verifies against the parsed `req.body`, so register `express.json()` before the route and do not use `express.raw()`, which makes every verification fail. Webhook signature verification is covered in the `webhook-integration` skill.
 
 4. **Mixing framework conventions:** Each framework has its own request/response shape. Don't try to use a Next.js handler in Express or vice versa. Use the adapter for your framework.
 
@@ -626,7 +756,9 @@ Convex only supports session checkout, not static or dynamic modes.
 
 6. **Skipping environment setup:** The adapters won't work without `DODO_PAYMENTS_API_KEY` and `DODO_PAYMENTS_ENVIRONMENT`. Set these before testing.
 
-7. **Using `@dodopayments/core` directly:** The core package is an internal dependency, not a documented public entry point. Use the framework adapter for your stack.
+7. **Exposing CustomerPortal unauthenticated:** The portal handlers trust `?customer_id=` from the request. Resolve the ID from the signed-in session on the server, as in the examples above, or anyone can open any customer's portal.
+
+8. **Using `@dodopayments/core` directly:** The core package is an internal dependency, not a documented public entry point. Use the framework adapter for your stack.
 
 ## Resources