@dodopayments/opencode-plugin 0.6.1 → 0.6.3

package/skills/framework-adapters/SKILL.md

@@ -169,578 +169,89 @@ export const POST = Webhooks({
 
 ## Express
 
-**Package:** `@dodopayments/express`
+Full guide: [references/express.md](references/express.md).
 
-### Checkout
+Covers:
 
-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);
-  },
-}));
-```
+- Checkout
+- Customer Portal
+- Webhooks
 
 ## 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";
+Full guide: [references/fastify.md](references/fastify.md).
 
-fastify.addContentTypeParser(
-  "application/json",
-  { parseAs: "string" },
-  (req, body, done) => done(null, body)
-);
+Covers:
 
-fastify.post("/api/webhook", Webhooks({
-  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
-  onPayload: async (payload) => {
-    console.log("Webhook:", payload.type);
-  },
-}));
-```
+- Checkout
+- Webhooks
 
 ## Hono
 
-**Package:** `@dodopayments/hono`
+Full guide: [references/hono.md](references/hono.md).
 
-### Checkout
+Covers:
 
-```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);
-  },
-}));
-```
+- Checkout
+- Customer Portal
+- Webhooks
 
 ## Astro
 
-**Package:** `@dodopayments/astro`  
-**Route placement:** `src/pages/api/checkout.ts`, `src/pages/api/customer-portal.ts`, `src/pages/api/webhook.ts`
-
-Disable prerendering for checkout routes.
-
-### Checkout
+Full guide: [references/astro.md](references/astro.md).
 
-```typescript
-// src/pages/api/checkout.ts
-import { Checkout } from "@dodopayments/astro";
-
-export const prerender = false;
+Covers:
 
-// Astro reads env from import.meta.env, which is typed as string - so it needs
-// the same narrowing as process.env. Define this alongside the other helper in
-// lib/dodo-env.ts if you use both.
-const dodoEnvironment =
-  import.meta.env.DODO_PAYMENTS_ENVIRONMENT === "live_mode" ? "live_mode" : "test_mode";
-
-export const GET = Checkout({
-  bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
-  returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
-  environment: dodoEnvironment,
-  type: "static",
-});
-
-export const POST = Checkout({
-  bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
-  returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
-  environment: dodoEnvironment,
-  type: "session",
-});
-```
-
-### Webhooks
-
-```typescript
-// src/pages/api/webhook.ts
-import { Webhooks } from "@dodopayments/astro";
-
-export const prerender = false;
-
-export const POST = Webhooks({
-  webhookKey: import.meta.env.DODO_PAYMENTS_WEBHOOK_KEY,
-  onPayload: async (payload) => {
-    console.log("Webhook:", payload.type);
-  },
-});
-```
+- Checkout
+- Webhooks
 
 ## Remix
 
-**Package:** `@dodopayments/remix`
+Full guide: [references/remix.md](references/remix.md).
 
-### Checkout
+Covers:
 
-```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);
-```
+- Checkout
+- Customer Portal
+- Webhooks
 
 ## 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";
+Full guide: [references/sveltekit.md](references/sveltekit.md).
 
-const dodoEnvironment = DODO_PAYMENTS_ENVIRONMENT === "live_mode" ? "live_mode" : "test_mode";
+Covers:
 
-// 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);
-  },
-});
-```
+- Checkout
+- Webhooks
 
 ## 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
+Full guide: [references/nuxt.md](references/nuxt.md).
 
-```typescript
-// server/routes/api/webhook.ts
-// Webhooks and useRuntimeConfig are auto-imported by the module.
-const config = useRuntimeConfig();
+Covers:
 
-export default Webhooks({
-  webhookKey: config.private.webhookKey,
-  onPayload: async (payload) => {
-    console.log("Webhook:", payload.type);
-  },
-});
-```
+- Checkout
+- Webhooks
 
 ## 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",
-});
+Full guide: [references/tanstack-start.md](references/tanstack-start.md).
 
-export const POST = Checkout({
-  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
-  returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
-  environment: dodoEnvironment,
-  type: "session",
-});
-```
+Covers:
 
-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.
+- Checkout
 
 ## Bun
 
-**Package:** `@dodopayments/bun`
-
-### Checkout and Portal
+Full guide: [references/bun.md](references/bun.md).
 
-```typescript
-import { Checkout, CustomerPortal } from "@dodopayments/bun";
-import { dodoEnvironment } from "./lib/dodo-env";
-// your auth helper
-import { getSessionUser } from "./lib/auth";
+Covers:
 
-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 });
-  },
-});
-```
+- Checkout and Portal
 
 ## 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.
+Full guide: [references/convex.md](references/convex.md).
 
 ## Common mistakes
 

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

@@ -0,0 +1,52 @@
+# Framework Adapters: Astro
+
+
+**Package:** `@dodopayments/astro`  
+**Route placement:** `src/pages/api/checkout.ts`, `src/pages/api/customer-portal.ts`, `src/pages/api/webhook.ts`
+
+Disable prerendering for checkout routes.
+
+### Checkout
+
+```typescript
+// src/pages/api/checkout.ts
+import { Checkout } from "@dodopayments/astro";
+
+export const prerender = false;
+
+// Astro reads env from import.meta.env, which is typed as string - so it needs
+// the same narrowing as process.env. Define this alongside the other helper in
+// lib/dodo-env.ts if you use both.
+const dodoEnvironment =
+  import.meta.env.DODO_PAYMENTS_ENVIRONMENT === "live_mode" ? "live_mode" : "test_mode";
+
+export const GET = Checkout({
+  bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
+  returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
+  environment: dodoEnvironment,
+  type: "static",
+});
+
+export const POST = Checkout({
+  bearerToken: import.meta.env.DODO_PAYMENTS_API_KEY,
+  returnUrl: import.meta.env.DODO_PAYMENTS_RETURN_URL,
+  environment: dodoEnvironment,
+  type: "session",
+});
+```
+
+### Webhooks
+
+```typescript
+// src/pages/api/webhook.ts
+import { Webhooks } from "@dodopayments/astro";
+
+export const prerender = false;
+
+export const POST = Webhooks({
+  webhookKey: import.meta.env.DODO_PAYMENTS_WEBHOOK_KEY,
+  onPayload: async (payload) => {
+    console.log("Webhook:", payload.type);
+  },
+});
+```