@dodopayments/opencode-plugin 0.6.0 → 0.6.2

package/skills/checkout-integration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: checkout-integration
-description: Guide for starting hosted Checkout Sessions, payment links, and overlay or inline checkout for one-time and recurring products; use subscription-integration for post-checkout lifecycle management.
+description: Dodo Payments checkout via hosted Checkout Sessions (client.checkoutSessions.create), static payment links, and overlay or inline checkout for one-time and subscription products. Use when building a pay button, checkout page, trial signup, custom fields, discount codes at checkout, or return_url redirects; use subscription-integration for post-checkout lifecycle.
 ---
 
 # Dodo Payments Checkout Integration
@@ -38,7 +38,7 @@ Dodo Payments offers three ways to collect payment:
 
 **Checkout Session:** A single-use session that generates a hosted checkout URL. Expires after 24 hours (or 15 minutes if `confirm=true`).
 
-**Return URL:** Where the customer lands after payment. Query parameters include `status=success` and `session_id`.
+**Return URL:** Where the customer lands after payment. Dodo appends `payment_id` (one-time) or `subscription_id` (subscription), `status`, and when available `license_key` and `email`. It is a UI hint only, never proof of payment.
 
 **Entitlement on webhook:** The browser redirect is not the source of truth. Always verify payment via webhook before granting access. See `webhook-integration` skill for verification.
 
@@ -209,471 +209,31 @@ const session = await client.checkoutSessions.create({
 
 ## Next.js App Router
 
-### API Route
+Full guide: [references/server-examples.md](references/server-examples.md).
 
-```typescript
-// app/api/checkout/route.ts
-import { NextResponse } from 'next/server';
-import DodoPayments from 'dodopayments';
-import { getCurrentUser } from '@/lib/auth';
-
-const client = new DodoPayments({
-  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
-  environment: process.env.NODE_ENV === 'production' ? 'live_mode' : 'test_mode'
-});
-
-type PlanId = 'starter' | 'pro';
-
-const PRODUCT_IDS: Record<PlanId, string> = {
-  starter: 'pdt_starter_monthly',
-  pro: 'pdt_pro_monthly'
-};
-
-function productIdForPlan(value: unknown): string | null {
-  if (typeof value !== 'string') return null;
-  return PRODUCT_IDS[value as PlanId] ?? null;
-}
-
-export async function POST(request: Request) {
-  const user = await getCurrentUser();
-  if (!user) {
-    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
-  }
-
-  let body: unknown;
-  try {
-    body = await request.json();
-  } catch {
-    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
-  }
-
-  if (!body || typeof body !== 'object') {
-    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
-  }
-
-  const input = body as { planId?: unknown; quantity?: unknown };
-  const productId = productIdForPlan(input.planId);
-  const quantity = input.quantity ?? 1;
-
-  if (!productId) {
-    return NextResponse.json({ error: 'Unknown plan' }, { status: 400 });
-  }
-
-  if (!Number.isInteger(quantity) || (quantity as number) < 1) {
-    return NextResponse.json(
-      { error: 'Quantity must be a positive integer' },
-      { status: 400 }
-    );
-  }
-
-  try {
-    const session = await client.checkoutSessions.create({
-      product_cart: [{ product_id: productId, quantity: quantity as number }],
-      customer: { email: user.email, name: user.name },
-      metadata: { app_user_id: user.id },
-      return_url: `${process.env.NEXT_PUBLIC_APP_URL}/checkout/success`
-    });
-
-    return NextResponse.json({
-      checkoutUrl: session.checkout_url,
-      sessionId: session.session_id
-    });
-  } catch (error) {
-    console.error('Checkout error:', error);
-    return NextResponse.json(
-      { error: 'Failed to create checkout' },
-      { status: 500 }
-    );
-  }
-}
-```
-
-### Client Component
-
-```typescript
-// components/CheckoutButton.tsx
-'use client';
-
-import { useState } from 'react';
-
-interface CheckoutButtonProps {
-  planId: 'starter' | 'pro';
-  quantity?: number;
-  children: React.ReactNode;
-}
-
-export function CheckoutButton({ planId, quantity = 1, children }: CheckoutButtonProps) {
-  const [loading, setLoading] = useState(false);
-
-  const handleCheckout = async () => {
-    setLoading(true);
-    try {
-      const response = await fetch('/api/checkout', {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ planId, quantity })
-      });
-
-      if (!response.ok) {
-        throw new Error('Failed to create checkout');
-      }
-
-      const data = (await response.json()) as { checkoutUrl?: string };
-      if (!data.checkoutUrl) throw new Error('Checkout URL was not returned');
-      window.location.href = data.checkoutUrl;
-    } catch (error) {
-      console.error('Checkout error:', error);
-      alert('Failed to start checkout. Please try again.');
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return (
-    <button onClick={handleCheckout} disabled={loading}>
-      {loading ? 'Loading...' : children}
-    </button>
-  );
-}
-```
-
-### Success Page
+Covers:
 
-```typescript
-// app/checkout/success/page.tsx
-import { Suspense } from 'react';
-
-function SuccessContent() {
-  return (
-    <div className="text-center py-20">
-      <h1 className="text-3xl font-bold">Payment Successful</h1>
-      <p className="mt-4 text-gray-600">
-        Thank you for your purchase. Check your email for a confirmation.
-      </p>
-      <a href="/" className="mt-8 inline-block text-blue-600 hover:underline">
-        Return to Home
-      </a>
-    </div>
-  );
-}
-
-export default function SuccessPage() {
-  return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <SuccessContent />
-    </Suspense>
-  );
-}
-```
-
----
+- API Route
+- Client Component
+- Success Page
 
 ## Express.js
 
-```typescript
-import express from 'express';
-import DodoPayments from 'dodopayments';
-import { getCurrentUser } from './auth';
-import { fulfillOneTimePurchase, grantSubscriptionAccess } from './entitlements';
-
-const app = express();
-
-const client = new DodoPayments({
-  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
-  environment: process.env.NODE_ENV === 'production' ? 'live_mode' : 'test_mode'
-});
-
-// Mount the webhook before express.json() so verification receives signed bytes.
-app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
-  try {
-    const event = client.webhooks.unwrap(req.body.toString('utf8'), {
-      headers: {
-        'webhook-id': req.headers['webhook-id'] as string,
-        'webhook-signature': req.headers['webhook-signature'] as string,
-        'webhook-timestamp': req.headers['webhook-timestamp'] as string
-      }
-    });
-
-    if (event.type === 'payment.succeeded') {
-      // This branch fulfills one-time purchases only.
-      await fulfillOneTimePurchase(event.data.customer.customer_id);
-    } else if (event.type === 'subscription.active') {
-      // Subscription access starts only after this verified event.
-      await grantSubscriptionAccess(event.data);
-    }
-
-    res.json({ received: true });
-  } catch (error) {
-    console.error('Webhook verification failed:', error);
-    res.status(401).json({ error: 'Invalid signature' });
-  }
-});
-
-app.use(express.json());
-
-type PlanId = 'starter' | 'pro';
-
-const PRODUCT_IDS: Record<PlanId, string> = {
-  starter: 'pdt_starter_monthly',
-  pro: 'pdt_pro_monthly'
-};
-
-function productIdForPlan(value: unknown): string | null {
-  if (typeof value !== 'string') return null;
-  return PRODUCT_IDS[value as PlanId] ?? null;
-}
-
-app.post('/api/checkout', async (req, res) => {
-  const user = await getCurrentUser(req);
-  if (!user) {
-    res.status(401).json({ error: 'Not authenticated' });
-    return;
-  }
-
-  const { planId, quantity = 1 } = req.body as {
-    planId?: unknown;
-    quantity?: unknown;
-  };
-  const productId = productIdForPlan(planId);
-
-  if (!productId) {
-    res.status(400).json({ error: 'Unknown plan' });
-    return;
-  }
-
-  if (!Number.isInteger(quantity) || (quantity as number) < 1) {
-    res.status(400).json({ error: 'Quantity must be a positive integer' });
-    return;
-  }
-
-  try {
-    const session = await client.checkoutSessions.create({
-      product_cart: [{ product_id: productId, quantity: quantity as number }],
-      customer: { email: user.email, name: user.name },
-      metadata: { app_user_id: user.id },
-      return_url: `${process.env.APP_URL}/success`
-    });
-
-    res.json({ checkoutUrl: session.checkout_url });
-  } catch (error) {
-    console.error('Checkout error:', error);
-    res.status(500).json({ error: 'Failed to create checkout' });
-  }
-});
-
-app.get('/success', (req, res) => {
-  res.send('Payment successful!');
-});
-```
-
----
+Full guide: [references/server-examples.md](references/server-examples.md).
 
 ## Python (FastAPI)
 
-```python
-import logging
-import os
-from typing import Annotated, Literal
-
-from dodopayments import DodoPayments
-from fastapi import Depends, FastAPI, HTTPException
-from pydantic import BaseModel, Field
-
-from app.auth import User, get_current_user
-
-app = FastAPI()
-logger = logging.getLogger(__name__)
-client = DodoPayments(
-    bearer_token=os.environ["DODO_PAYMENTS_API_KEY"],
-    environment="test_mode"
-)
-
-PRODUCT_IDS = {
-    "starter": "pdt_starter_monthly",
-    "pro": "pdt_pro_monthly",
-}
-
-class CheckoutRequest(BaseModel):
-    plan_id: Literal["starter", "pro"]
-    quantity: int = Field(default=1, gt=0)
-
-@app.post("/api/checkout")
-async def create_checkout(
-    request: CheckoutRequest,
-    user: Annotated[User, Depends(get_current_user)],
-):
-    try:
-        session = client.checkout_sessions.create(
-            product_cart=[{
-                "product_id": PRODUCT_IDS[request.plan_id],
-                "quantity": request.quantity
-            }],
-            customer={
-                "email": user.email,
-                "name": user.name
-            },
-            metadata={"app_user_id": user.id},
-            return_url=f"{os.environ['APP_URL']}/success"
-        )
-        return {"checkout_url": session.checkout_url}
-    except Exception as error:
-        logger.exception("Checkout session creation failed")
-        raise HTTPException(status_code=500, detail="Failed to create checkout") from error
-```
-
----
+Full guide: [references/server-examples.md](references/server-examples.md).
 
 ## Overlay Checkout
 
-Use the `dodopayments-checkout` package for overlay or inline checkout that stays on your site.
-
-### Installation
-
-```bash
-npm install dodopayments-checkout
-```
-
-### Server Route
-
-Create the Checkout Session on the server. The browser sends a public plan slug, while the server derives
-the customer from the authenticated user and maps the slug to an allowlisted product id.
-
-```typescript
-// app/api/overlay-checkout/route.ts
-import { NextResponse } from 'next/server';
-import DodoPayments from 'dodopayments';
-import { getCurrentUser } from '@/lib/auth';
-
-const client = new DodoPayments({
-  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
-  environment: process.env.NODE_ENV === 'production' ? 'live_mode' : 'test_mode'
-});
-
-type PlanId = 'starter' | 'pro';
-
-const PRODUCT_IDS: Record<PlanId, string> = {
-  starter: 'pdt_starter_monthly',
-  pro: 'pdt_pro_monthly'
-};
-
-export async function POST(request: Request) {
-  const user = await getCurrentUser();
-  if (!user) {
-    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
-  }
-
-  let body: unknown;
-  try {
-    body = await request.json();
-  } catch {
-    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
-  }
-
-  if (!body || typeof body !== 'object') {
-    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
-  }
-
-  const { planId, quantity = 1 } = body as {
-    planId?: unknown;
-    quantity?: unknown;
-  };
-  const productId = typeof planId === 'string'
-    ? PRODUCT_IDS[planId as PlanId]
-    : undefined;
-
-  if (!productId) {
-    return NextResponse.json({ error: 'Unknown plan' }, { status: 400 });
-  }
-
-  if (!Number.isInteger(quantity) || (quantity as number) < 1) {
-    return NextResponse.json(
-      { error: 'Quantity must be a positive integer' },
-      { status: 400 }
-    );
-  }
-
-  try {
-    const session = await client.checkoutSessions.create({
-      product_cart: [{ product_id: productId, quantity: quantity as number }],
-      customer: { email: user.email, name: user.name },
-      metadata: { app_user_id: user.id },
-      return_url: `${process.env.NEXT_PUBLIC_APP_URL}/checkout/success`
-    });
-
-    if (!session.checkout_url) {
-      return NextResponse.json({ error: 'Checkout URL was not returned' }, { status: 502 });
-    }
-
-    return NextResponse.json({ checkoutUrl: session.checkout_url });
-  } catch (error) {
-    console.error('Overlay checkout error:', error);
-    return NextResponse.json({ error: 'Failed to create checkout' }, { status: 500 });
-  }
-}
-```
-
-### Browser Overlay and Inline Modes
-
-Browser code calls the server route and receives only the checkout URL. The Dodo Payments API bearer token
-stays in the server route and is never sent to the browser.
-
-```typescript
-// lib/open-checkout.ts
-import { DodoPayments } from 'dodopayments-checkout';
-
-type PlanId = 'starter' | 'pro';
-
-async function createCheckoutUrl(planId: PlanId, quantity = 1): Promise<string> {
-  const response = await fetch('/api/overlay-checkout', {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ planId, quantity })
-  });
-
-  if (!response.ok) throw new Error('Failed to create checkout');
-
-  const data = (await response.json()) as { checkoutUrl?: string };
-  if (!data.checkoutUrl) throw new Error('Checkout URL was not returned');
-  return data.checkoutUrl;
-}
+Full guide: [references/overlay-checkout.md](references/overlay-checkout.md).
 
-export async function openOverlayCheckout(planId: PlanId): Promise<void> {
-  const checkoutUrl = await createCheckoutUrl(planId);
+Covers:
 
-  DodoPayments.Initialize({
-    mode: 'test', // or 'live'
-    displayType: 'overlay',
-    onEvent: (event) => {
-      console.log('Checkout event:', event);
-    }
-  });
-
-  DodoPayments.Checkout.open({ checkoutUrl });
-}
-
-export async function openInlineCheckout(planId: PlanId): Promise<void> {
-  const checkoutUrl = await createCheckoutUrl(planId);
-
-  DodoPayments.Initialize({
-    mode: 'test', // or 'live'
-    displayType: 'inline',
-    onEvent: (event) => {
-      console.log('Checkout event:', event);
-    }
-  });
-
-  DodoPayments.Checkout.open({
-    checkoutUrl,
-    elementId: 'dodo-inline-checkout'
-  });
-}
-```
-
-```html
-<div id="dodo-inline-checkout"></div>
-```
-
----
+- Installation
+- Server Route
+- Browser Overlay and Inline Modes
 
 ## Static Payment Links
 
@@ -685,6 +245,8 @@ No-code shareable links. No server-side API call needed.
 https://checkout.dodopayments.com/buy/{productid}
 ```
 
+In test mode the host is `test.checkout.dodopayments.com` (for example `https://test.checkout.dodopayments.com/buy/{productid}`); a test-mode product does not exist on the live host.
+
 Example:
 ```text
 https://checkout.dodopayments.com/buy/pdt_example
@@ -789,16 +351,25 @@ const session = await client.checkoutSessions.create({
 After payment, the customer is redirected to your `return_url` with query parameters:
 
 ```text
-https://yoursite.com/success?status=success&session_id=cks_123
+# One-time payment
+https://yoursite.com/success?payment_id=pay_xxx&status=succeeded&email=customer%40example.com
+
+# Subscription (with license keys)
+https://yoursite.com/success?subscription_id=sub_xxx&status=active&license_key=LK-001,LK-002&email=customer%40example.com
 ```
 
 Query parameters:
-- `status`: `success` or `failed`
-- `session_id`: Checkout session ID
+- `payment_id` (one-time payments) or `subscription_id` (subscriptions)
+- `status`: `succeeded` (one-time) or `active` (subscription) on success; `failed` if declined; `processing` (or a `requires_*` value) if it settles later; `expired` if the session expired
+- `license_key`: present when the product issues license keys (comma-separated if several)
+- `email`: present when the customer has an email on record
+
+There is no `session_id` parameter. Treat `processing`/missing status as "unknown" and wait for the webhook.
 
 ### Verify Payment Server-Side
 
-Do not trust the browser redirect. Use the Express webhook route above: it receives the raw signed body
+Do not trust the browser redirect. Use the Express webhook route in
+[references/server-examples.md](references/server-examples.md#expressjs): it receives the raw signed body
 before `express.json()`, fulfills one-time purchases on verified `payment.succeeded` using
 `event.data.customer.customer_id`, and grants subscription access only on verified `subscription.active`.
 
@@ -818,8 +389,8 @@ Do not use `client.payments.create()` or `client.subscriptions.create()` for new
 **3. Forgetting the `environment` flag**
 The default is `live_mode`. Always set `environment: 'test_mode'` during development to avoid charging real cards.
 
-**4. Assuming only one discount-code form is valid**
-Both `discount_code` (a string) and `discount_codes` (an array) are valid Checkout Session parameters.
+**4. Using the deprecated `discount_code`**
+Use `discount_codes` (an array). The singular `discount_code` string is deprecated (still accepted for backward compatibility) and cannot be combined with `discount_codes` in the same request.
 
 **5. Amounts in wrong unit**
 All amounts are in the smallest currency unit (cents for USD). $10 is `1000`, not `10`.

package/skills/checkout-integration/references/overlay-checkout.md

@@ -0,0 +1,148 @@
+# Dodo Payments Checkout Integration: Overlay Checkout
+
+
+Use the `dodopayments-checkout` package for overlay or inline checkout that stays on your site.
+
+### Installation
+
+```bash
+npm install dodopayments-checkout
+```
+
+### Server Route
+
+Create the Checkout Session on the server. The browser sends a public plan slug, while the server derives
+the customer from the authenticated user and maps the slug to an allowlisted product id.
+
+```typescript
+// app/api/overlay-checkout/route.ts
+import { NextResponse } from 'next/server';
+import DodoPayments from 'dodopayments';
+import { getCurrentUser } from '@/lib/auth';
+
+const client = new DodoPayments({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY!,
+  environment: process.env.NODE_ENV === 'production' ? 'live_mode' : 'test_mode'
+});
+
+type PlanId = 'starter' | 'pro';
+
+const PRODUCT_IDS: Record<PlanId, string> = {
+  starter: 'pdt_starter_monthly',
+  pro: 'pdt_pro_monthly'
+};
+
+export async function POST(request: Request) {
+  const user = await getCurrentUser();
+  if (!user) {
+    return NextResponse.json({ error: 'Not authenticated' }, { status: 401 });
+  }
+
+  let body: unknown;
+  try {
+    body = await request.json();
+  } catch {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  if (!body || typeof body !== 'object') {
+    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
+  }
+
+  const { planId, quantity = 1 } = body as {
+    planId?: unknown;
+    quantity?: unknown;
+  };
+  const productId = typeof planId === 'string'
+    ? PRODUCT_IDS[planId as PlanId]
+    : undefined;
+
+  if (!productId) {
+    return NextResponse.json({ error: 'Unknown plan' }, { status: 400 });
+  }
+
+  if (!Number.isInteger(quantity) || (quantity as number) < 1) {
+    return NextResponse.json(
+      { error: 'Quantity must be a positive integer' },
+      { status: 400 }
+    );
+  }
+
+  try {
+    const session = await client.checkoutSessions.create({
+      product_cart: [{ product_id: productId, quantity: quantity as number }],
+      customer: { email: user.email, name: user.name },
+      metadata: { app_user_id: user.id },
+      return_url: `${process.env.NEXT_PUBLIC_APP_URL}/checkout/success`
+    });
+
+    if (!session.checkout_url) {
+      return NextResponse.json({ error: 'Checkout URL was not returned' }, { status: 502 });
+    }
+
+    return NextResponse.json({ checkoutUrl: session.checkout_url });
+  } catch (error) {
+    console.error('Overlay checkout error:', error);
+    return NextResponse.json({ error: 'Failed to create checkout' }, { status: 500 });
+  }
+}
+```
+
+### Browser Overlay and Inline Modes
+
+Browser code calls the server route and receives only the checkout URL. The Dodo Payments API bearer token
+stays in the server route and is never sent to the browser.
+
+```typescript
+// lib/open-checkout.ts
+import { DodoPayments } from 'dodopayments-checkout';
+
+type PlanId = 'starter' | 'pro';
+
+async function createCheckoutUrl(planId: PlanId, quantity = 1): Promise<string> {
+  const response = await fetch('/api/overlay-checkout', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ planId, quantity })
+  });
+
+  if (!response.ok) throw new Error('Failed to create checkout');
+
+  const data = (await response.json()) as { checkoutUrl?: string };
+  if (!data.checkoutUrl) throw new Error('Checkout URL was not returned');
+  return data.checkoutUrl;
+}
+
+// Call ONCE when the app loads (e.g. in your root component or entry point),
+// not before every checkout. Pick the display type your page uses.
+export function initCheckout(displayType: 'overlay' | 'inline'): void {
+  DodoPayments.Initialize({
+    mode: 'test', // or 'live'
+    displayType,
+    onEvent: (event) => {
+      console.log('Checkout event:', event);
+    }
+  });
+}
+
+// Requires initCheckout('overlay') to have run at app load.
+export async function openOverlayCheckout(planId: PlanId): Promise<void> {
+  const checkoutUrl = await createCheckoutUrl(planId);
+  DodoPayments.Checkout.open({ checkoutUrl });
+}
+
+// Requires initCheckout('inline') to have run at app load.
+export async function openInlineCheckout(planId: PlanId): Promise<void> {
+  const checkoutUrl = await createCheckoutUrl(planId);
+  DodoPayments.Checkout.open({
+    checkoutUrl,
+    elementId: 'dodo-inline-checkout'
+  });
+}
+```
+
+```html
+<div id="dodo-inline-checkout"></div>
+```
+
+---