@dodopayments/opencode-plugin 0.6.1 → 0.6.2

package/skills/framework-adapters/references/bun.md

@@ -0,0 +1,45 @@
+# Framework Adapters: Bun
+
+
+**Package:** `@dodopayments/bun`
+
+### Checkout and Portal
+
+```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,
+  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
+  environment: dodoEnvironment,
+  type: "session",
+});
+
+const portalHandler = CustomerPortal({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  environment: dodoEnvironment,
+});
+
+Bun.serve({
+  port: 3000,
+  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") {
+      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 });
+  },
+});
+```

package/skills/framework-adapters/references/convex.md

@@ -0,0 +1,91 @@
+# Framework Adapters: Convex
+
+
+**Package:** `@dodopayments/convex`
+
+Convex uses a component-based architecture. Register the component in `convex.config.ts`:
+
+```typescript
+// convex/convex.config.ts
+import { defineApp } from "convex/server";
+import dodopayments from "@dodopayments/convex/convex.config";
+
+const app = defineApp();
+app.use(dodopayments);
+export default app;
+```
+
+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/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,
+      },
+    });
+  },
+});
+```
+
+Convex only supports session checkout, not static or dynamic modes.

package/skills/framework-adapters/references/express.md

@@ -0,0 +1,72 @@
+# Framework Adapters: Express
+
+
+**Package:** `@dodopayments/express`
+
+### Checkout
+
+The Express adapter names its checkout export `checkoutHandler` in lowercase, unlike every other adapter. `import { Checkout } from "@dodopayments/express"` does not resolve.
+
+```typescript
+import express from "express";
+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,
+  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
+  environment: dodoEnvironment,
+  type: "static",
+}));
+
+app.post("/api/checkout", checkoutHandler({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
+  environment: dodoEnvironment,
+  type: "session",
+}));
+```
+
+### 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 DodoPayments from "dodopayments";
+import { dodoEnvironment } from "./lib/dodo-env";
+
+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
+
+```typescript
+import { Webhooks } from "@dodopayments/express";
+
+// 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,
+  onPayload: async (payload) => {
+    console.log("Webhook:", payload.type);
+  },
+}));
+```

package/skills/framework-adapters/references/fastify.md

@@ -0,0 +1,54 @@
+# Framework Adapters: Fastify
+
+
+**Package:** `@dodopayments/fastify`
+
+Fastify requires a string body parser to preserve the raw body for webhook verification.
+
+### Checkout
+
+`Checkout(config)` returns an object with `getHandler` and `postHandler`, not a single callable. Build it once and mount each method, rather than calling the result.
+
+```typescript
+import Fastify from "fastify";
+import { Checkout } from "@dodopayments/fastify";
+import { dodoEnvironment } from "./lib/dodo-env";
+
+const fastify = Fastify();
+
+const staticCheckout = Checkout({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
+  environment: dodoEnvironment,
+  type: "static",
+});
+
+const sessionCheckout = Checkout({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
+  environment: dodoEnvironment,
+  type: "session",
+});
+
+fastify.get("/api/checkout", staticCheckout.getHandler);
+fastify.post("/api/checkout", sessionCheckout.postHandler);
+```
+
+### Webhooks
+
+```typescript
+import { Webhooks } from "@dodopayments/fastify";
+
+fastify.addContentTypeParser(
+  "application/json",
+  { parseAs: "string" },
+  (req, body, done) => done(null, body)
+);
+
+fastify.post("/api/webhook", Webhooks({
+  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
+  onPayload: async (payload) => {
+    console.log("Webhook:", payload.type);
+  },
+}));
+```

package/skills/framework-adapters/references/hono.md

@@ -0,0 +1,63 @@
+# Framework Adapters: Hono
+
+
+**Package:** `@dodopayments/hono`
+
+### Checkout
+
+```typescript
+import { Hono } from "hono";
+import { Checkout } from "@dodopayments/hono";
+import { dodoEnvironment } from "./lib/dodo-env";
+
+const app = new Hono();
+
+app.get("/api/checkout", Checkout({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
+  environment: dodoEnvironment,
+  type: "static",
+}));
+
+app.post("/api/checkout", Checkout({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
+  environment: dodoEnvironment,
+  type: "session",
+}));
+```
+
+### 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 DodoPayments from "dodopayments";
+import { dodoEnvironment } from "./lib/dodo-env";
+
+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
+
+```typescript
+import { Webhooks } from "@dodopayments/hono";
+
+app.post("/api/webhook", Webhooks({
+  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
+  onPayload: async (payload) => {
+    console.log("Webhook:", payload.type);
+  },
+}));
+```

package/skills/framework-adapters/references/nuxt.md

@@ -0,0 +1,53 @@
+# Framework Adapters: Nuxt
+
+
+**Package:** `@dodopayments/nuxt`
+
+Add the module to `nuxt.config.ts` and configure runtime variables:
+
+```typescript
+// nuxt.config.ts
+export default defineNuxtConfig({
+  modules: ["@dodopayments/nuxt"],
+  runtimeConfig: {
+    private: {
+      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_RETURN_URL,
+    },
+  },
+});
+```
+
+### Checkout
+
+The Nuxt module registers its handlers with `addServerImportsDir`, so `checkoutHandler`, `customerPortalHandler`, and `Webhooks` are **auto-imported** inside `server/`. Do not import them from `@dodopayments/nuxt` — that entry point exports only the Nuxt module itself, and a named import from it will not resolve.
+
+```typescript
+// server/routes/api/checkout.ts
+// checkoutHandler and useRuntimeConfig are auto-imported by the module.
+const config = useRuntimeConfig();
+
+export default checkoutHandler({
+  bearerToken: config.private.bearerToken,
+  returnUrl: config.private.returnUrl,
+  environment: config.private.environment,
+  type: "session",
+});
+```
+
+### Webhooks
+
+```typescript
+// server/routes/api/webhook.ts
+// Webhooks and useRuntimeConfig are auto-imported by the module.
+const config = useRuntimeConfig();
+
+export default Webhooks({
+  webhookKey: config.private.webhookKey,
+  onPayload: async (payload) => {
+    console.log("Webhook:", payload.type);
+  },
+});
+```

package/skills/framework-adapters/references/remix.md

@@ -0,0 +1,65 @@
+# Framework Adapters: Remix
+
+
+**Package:** `@dodopayments/remix`
+
+### Checkout
+
+```typescript
+// 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,
+  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
+  environment: dodoEnvironment,
+  type: "session",
+});
+
+export const loader = ({ request }: LoaderFunctionArgs) => checkoutHandler(request);
+export const action = ({ request }: ActionFunctionArgs) => checkoutHandler(request);
+```
+
+### Customer Portal
+
+```typescript
+// 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 = 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
+
+```typescript
+// app/routes/api.webhook.tsx
+import { Webhooks } from "@dodopayments/remix";
+import type { ActionFunctionArgs } from "@remix-run/node";
+
+export const action = ({ request }: ActionFunctionArgs) =>
+  Webhooks({
+    webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
+    onPayload: async (payload) => {
+      console.log("Webhook:", payload.type);
+    },
+  })(request);
+```

package/skills/framework-adapters/references/sveltekit.md

@@ -0,0 +1,49 @@
+# Framework Adapters: SvelteKit
+
+
+**Package:** `@dodopayments/sveltekit`  
+**Route placement:** `src/routes/api/checkout/+server.ts`, `src/routes/api/customer-portal/+server.ts`, `src/routes/api/webhook/+server.ts`
+
+### Checkout
+
+```typescript
+// src/routes/api/checkout/+server.ts
+import { Checkout } from "@dodopayments/sveltekit";
+import { DODO_PAYMENTS_API_KEY, DODO_PAYMENTS_RETURN_URL, DODO_PAYMENTS_ENVIRONMENT } from "$env/static/private";
+
+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: dodoEnvironment,
+  type: "session",
+});
+
+export const GET = staticCheckout.GET;
+export const POST = sessionCheckout.POST;
+```
+
+### Webhooks
+
+```typescript
+// src/routes/api/webhook/+server.ts
+import { Webhooks } from "@dodopayments/sveltekit";
+import { DODO_PAYMENTS_WEBHOOK_KEY } from "$env/static/private";
+
+export const POST = Webhooks({
+  webhookKey: DODO_PAYMENTS_WEBHOOK_KEY,
+  onPayload: async (payload) => {
+    console.log("Webhook:", payload.type);
+  },
+});
+```

package/skills/framework-adapters/references/tanstack-start.md

@@ -0,0 +1,31 @@
+# Framework Adapters: TanStack Start
+
+
+**Package:** `@dodopayments/tanstack`
+
+### Checkout
+
+`Checkout(config)` returns a plain `(request: Request) => Promise<Response>`, so export it directly as the route's method handler. The adapter's own documented usage is `export const GET = Checkout(config)`.
+
+```typescript
+// src/routes/api/checkout.ts
+import { Checkout } from "@dodopayments/tanstack";
+// src/lib/dodo-env.ts
+import { dodoEnvironment } from "../../lib/dodo-env";
+
+export const GET = Checkout({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
+  environment: dodoEnvironment,
+  type: "static",
+});
+
+export const POST = Checkout({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
+  environment: dodoEnvironment,
+  type: "session",
+});
+```
+
+TanStack Start's server-route definition API has changed across releases (`createServerFileRoute` was removed). Wrap these exports in whatever route helper your installed version provides; the adapter handlers themselves are unaffected.