@dodopayments/opencode-plugin 0.6.0 → 0.6.2

package/skills/subscription-integration/references/webhook-events.md

@@ -0,0 +1,82 @@
+# Dodo Payments Subscription Integration: Webhook Events
+
+
+| Event | When | Action |
+|-------|------|--------|
+| `subscription.active` | Subscription becomes active, including a trial start or recovery | Grant access |
+| `subscription.updated` | Any subscription field changes | Sync your stored copy (status, dates, metadata) |
+| `subscription.renewed` | Successful renewal | Log renewal, send receipt |
+| `subscription.past_due` | Renewal failed and the grace period opened (payload has `past_due_ends_at`) | Keep access, prompt for payment before the deadline |
+| `subscription.on_hold` | Renewal/plan-change payment failed | Notify customer, offer recovery |
+| `subscription.paused` | Subscription paused | Revoke access while paused |
+| `subscription.unpaused` | Paused subscription resumed | Restore access |
+| `subscription.plan_changed` | Plan upgraded/downgraded or add-ons changed | Update entitlements |
+| `subscription.update_payment_method` | Payment method updated | Update stored payment details |
+| `subscription.cancelled` | Customer cancels | Schedule access revocation per `cancel_at_next_billing_date` |
+| `subscription.failed` | Initial creation failed (mandate creation) | Notify customer, offer a new subscription |
+| `subscription.expired` | Subscription term ended | Revoke access |
+
+Webhook signature verification, raw-body handling, durable processing, and idempotency are covered in the `webhook-integration` skill.
+
+### Example Handler
+
+```typescript
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(req: NextRequest) {
+  const raw = await req.text();
+  const headers = Object.fromEntries(req.headers.entries());
+  const event = await client.webhooks.unwrap(raw, { headers });
+  const webhookId = req.headers.get('webhook-id');
+
+  if (!webhookId) {
+    return NextResponse.json({ error: 'Missing webhook-id' }, { status: 400 });
+  }
+
+  // Implement this as an atomic insert backed by a UNIQUE constraint.
+  // Keep the claim and entitlement changes in the same database transaction.
+  const claimed = await claimWebhookId(webhookId);
+  if (!claimed) {
+    return NextResponse.json({ received: true });
+  }
+
+  switch (event.type) {
+    case 'subscription.active':
+      await grantAccess(event.data.customer.customer_id, event.data.product_id);
+      break;
+    case 'subscription.on_hold':
+      await notifyPaymentFailed(event.data.customer.customer_id);
+      break;
+    case 'subscription.paused':
+    case 'subscription.unpaused': {
+      // Pause and resume can happen in quick succession, and handlers for
+      // different events can finish in any order. Don't trust the event type:
+      // re-read the subscription and apply its CURRENT status, scoped to this
+      // subscription (the customer may hold other active ones). Run this under
+      // a per-subscription lock if your handlers execute concurrently.
+      const current = await client.subscriptions.retrieve(event.data.subscription_id);
+      if (current.status === 'paused') {
+        await suspendSubscriptionAccess(current.subscription_id);
+      } else if (current.status === 'active' || current.status === 'past_due') {
+        // past_due keeps access during the payment grace period
+        await restoreSubscriptionAccess(current.subscription_id);
+      }
+      break;
+    }
+    case 'subscription.cancelled':
+      if (event.data.cancel_at_next_billing_date) {
+        await scheduleAccessRevocation(event.data.subscription_id, new Date(event.data.next_billing_date));
+      } else {
+        await revokeAccessImmediately(event.data.subscription_id);
+      }
+      break;
+    case 'subscription.expired':
+      await revokeAccess(event.data.customer.customer_id);
+      break;
+  }
+
+  return NextResponse.json({ received: true });
+}
+```
+
+---

package/skills/testing-and-go-live/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: testing-and-go-live
-description: Guide for test-mode payment scenarios, renewal simulation, local webhook delivery tests, test and live catalog migration, and production launch checks.
+description: Dodo Payments test mode and production launch, covering test cards and payment methods, success and decline scenarios, renewal simulation, local webhook testing with the CLI, copying products from test to live, and a go-live checklist. Use when verifying payment flows, switching from test_mode to live_mode, or preparing to launch.
 ---
 
 # Testing and Go-Live
@@ -44,6 +44,8 @@ const client = new DodoPayments({
 ```
 
 ```python
+import os
+
 from dodopayments import DodoPayments
 
 client = DodoPayments(
@@ -67,31 +69,34 @@ Get your test API key from the Dodo dashboard. Test keys are prefixed `dodo_test
 
 ### Card success and decline scenarios
 
-Use these card numbers in test mode. The expiry can be any future date; the CVC can be any three digits.
+Use these card numbers in test mode with expiry **06/32** (or **12/34**) and CVV **123**.
 
 | Scenario | Card Number | Result |
 |---|---|---|
 | Success | `4242 4242 4242 4242` | Payment succeeds |
 | Decline | `4000 0000 0000 0002` | Payment declined |
 | Decline (insufficient funds) | `4000 0000 0000 9995` | Insufficient funds error |
-| Decline (lost card) | `4000 0000 0000 9987` | Lost card error |
+
+Only use cards listed on the [Testing Process](https://docs.dodopayments.com/miscellaneous/testing-process) page; other Stripe-style test numbers (for example "lost card" variants) are not documented for Dodo.
 
 ### Subscription renewal failure
 
 To test subscription renewal failures, use this card:
 
-| Card Number | Behavior |
-|---|---|
-| `4000 0000 0000 0069` | Renewal fails on next billing date |
+| Card Number | Expiry | CVV | Behavior |
+|---|---|---|---|
+| `4000 0000 0000 0341` | 12/34 | 123 | Declined at the subscription's next charge (renewal, upgrade, or downgrade) |
+
+Create the subscription with a success card first, then switch its payment method to this card in the Customer Portal.
 
 ### UPI (India)
 
-Test UPI success and failure with these VPAs:
+Test UPI success and failure with these VPAs. The billing country must be `IN` and the currency `INR` (non-Indian merchants also need Adaptive Currency enabled):
 
 | VPA | Result |
 |---|---|
-| `success@okhdfcbank` | Payment succeeds |
-| `failure@okhdfcbank` | Payment fails |
+| `success@upi` | Payment succeeds |
+| `failure@upi` | Payment fails |
 
 ### BNPL, wallets, and regional methods
 
@@ -162,7 +167,9 @@ dodo wh trigger payment.success http://localhost:3000/webhook
 
 Sends a realistic mock payload for a chosen event. It runs offline and works even while logged out — which is the tell for the part that matters: **these payloads are unsigned.** `unwrap()` rejects them because there is no valid signature to verify.
 
-Use `unsafeUnwrap()` for triggered events only, and never on an endpoint that also receives real traffic. Event names are `<category>.<event>`, for example `payment.success`, `subscription.active`, or `dispute.opened`.
+Use `unsafeUnwrap()` for triggered events only, and never on an endpoint that also receives real traffic. Trigger names are `<category>.<event>`, for example `payment.success`, `subscription.active`, or `dispute.opened`.
+
+**Trigger names are not always the payload `type`.** `payment.success` delivers `type: "payment.succeeded"`, `refund.success` delivers `refund.succeeded`, and `licence.created` delivers `license_key.created`. Switch on the payload types in your handler; a `case 'payment.success'` never matches.
 
 As with `listen`, both arguments are required in direct mode; `/wh trigger` inside the TUI opens a wizard instead.
 
@@ -184,19 +191,19 @@ Products are environment-specific. You cannot reuse a test product ID in product
 
 **Programmatic approach:**
 
-Fetch the product from test mode, extract its configuration, and create it in live mode:
+Fetch the product from test mode, extract its configuration, and create it in live mode. API keys are per mode — a test key does not authenticate against live mode and vice versa — so this needs two distinct keys:
 
 ```typescript
 // In test mode
 const testClient = new DodoPayments({
-  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  bearerToken: process.env.DODO_PAYMENTS_TEST_API_KEY,
   environment: 'test_mode',
 });
 const testProduct = await testClient.products.retrieve('pdt_test_123');
 
 // In live mode
 const liveClient = new DodoPayments({
-  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  bearerToken: process.env.DODO_PAYMENTS_LIVE_API_KEY,
   environment: 'live_mode',
 });
 const liveProduct = await liveClient.products.create({
@@ -331,5 +338,5 @@ Test keys (prefixed `dodo_test_`) only work with `https://test.dodopayments.com`
 
 - [Testing Process](https://docs.dodopayments.com/miscellaneous/testing-process)
 - [Test vs. Live Mode](https://docs.dodopayments.com/miscellaneous/test-mode-vs-live-mode)
-- [Webhook Integration](https://docs.dodopayments.com/developer-resources/webhooks/intents/introduction)
-- [Dodo CLI](https://docs.dodopayments.com/developer-resources/cli)
+- [Webhook Integration](https://docs.dodopayments.com/developer-resources/webhooks)
+- [Dodo CLI](https://docs.dodopayments.com/developer-resources/sdks/cli)

package/skills/usage-based-billing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: usage-based-billing
-description: Guide for charging directly per measured API call, token, storage unit, or other consumption using meters, stable usage events, aggregation, free thresholds, and metered subscriptions.
+description: Dodo Payments usage-based billing that charges per measured unit, covering meters, usage event ingestion by event_name, aggregation, free thresholds, price_per_unit, and metered subscriptions. Use when billing per API call, AI token, storage, or bandwidth, sending usage events, or adding metered pricing to a plan; use credit-based-billing for prepaid credit pools.
 ---
 
 # Dodo Payments Usage-Based Billing
@@ -181,7 +181,7 @@ async function trackBatchUsage(
     customerId: string;
     eventName: string;
     occurredAt: string;
-    metadata: Record<string, string>;
+    metadata: Record<string, string | number | boolean>;
   }>
 ) {
   const formattedEvents = events.map((event) => ({
@@ -235,135 +235,29 @@ The `product-catalog-management` skill is the canonical source for the complete
 
 ## Instrumenting Your Application
 
-### Track API Calls
+Full guide: [references/instrumentation.md](references/instrumentation.md).
 
-Persist the event before reporting the operation as complete, then ingest it from a retrying worker. The outbox or queue implementation must durably store the payload before `persist` resolves.
+Covers:
 
-```typescript
-type PersistedUsageEvent = {
-  event_id: string;
-  customer_id: string;
-  event_name: string;
-  timestamp: string;
-  metadata: Record<string, string | number | boolean>;
-};
-
-interface UsageOutbox {
-  persist(event: PersistedUsageEvent): Promise<void>;
-  nextBatch(limit: number): Promise<PersistedUsageEvent[]>;
-  markIngested(eventIds: string[]): Promise<void>;
-}
-
-async function completeApiOperation(
-  outbox: UsageOutbox,
-  operationId: string,
-  customerId: string,
-  occurredAt: string,
-): Promise<void> {
-  await outbox.persist({
-    event_id: `api-call:${operationId}`,
-    customer_id: customerId,
-    event_name: 'api.call',
-    timestamp: occurredAt,
-    metadata: { endpoint: '/v1/users', method: 'GET', status: 200 },
-  });
-}
-
-async function ingestUsageOutbox(outbox: UsageOutbox): Promise<void> {
-  const events = await outbox.nextBatch(1000);
-  if (events.length === 0) return;
-
-  await client.usageEvents.ingest({ events });
-  await outbox.markIngested(events.map((event) => event.event_id));
-}
-```
-
-If the worker crashes after Dodo accepts the batch but before `markIngested`, retry the same persisted events with the same IDs. Dodo ignores the already-ingested IDs.
-
-### Track AI Token Usage
-
-```typescript
-async function callAI(
-  customerId: string,
-  generationId: string,
-  prompt: string,
-  completedAt: string,
-) {
-  const response = await openai.chat.completions.create({
-    model: 'gpt-4',
-    messages: [{ role: 'user', content: prompt }],
-  });
-
-  // Track tokens after completion
-  await client.usageEvents.ingest({
-    events: [{
-      event_id: `generation:${generationId}`,
-      customer_id: customerId,
-      event_name: 'ai.tokens',
-      timestamp: completedAt,
-      metadata: {
-        tokens: response.usage.total_tokens.toString(),
-        prompt_tokens: response.usage.prompt_tokens.toString(),
-        completion_tokens: response.usage.completion_tokens.toString(),
-        model: 'gpt-4',
-      }
-    }]
-  });
-
-  return response;
-}
-```
-
-### Track Storage Usage
-
-For snapshot-based metrics (current state), use the `last` aggregation:
-
-```typescript
-async function updateStorageUsage(
-  customerId: string,
-  snapshotId: string,
-  bytesUsed: number,
-  capturedAt: string,
-) {
-  await client.usageEvents.ingest({
-    events: [{
-      event_id: `storage-snapshot:${snapshotId}`,
-      customer_id: customerId,
-      event_name: 'storage.snapshot',
-      timestamp: capturedAt,
-      metadata: {
-        bytes: bytesUsed.toString(),
-        gb: (bytesUsed / 1024 / 1024 / 1024).toFixed(2),
-      }
-    }]
-  });
-}
-
-// Call periodically or after storage changes
-await updateStorageUsage(
-  'cus_abc',
-  'snapshot_01K1M4D2K9',
-  5368709120,
-  '2026-08-01T10:30:00Z',
-); // 5GB
-```
-
----
+- Track API Calls
+- Track AI Token Usage
+- Track Storage Usage
 
 ## Querying Usage for Display
 
 ### Retrieve Usage History
 
 ```typescript
-const usage = await client.subscriptions.retrieveUsageHistory(
-  'sub_abc123',
-  { page_size: 100 }
-);
-
-console.log(usage.items); // Array of billing-period usage records
+// Auto-paginates across ALL billing periods; narrow with start_date/end_date/meter_id.
+for await (const period of client.subscriptions.retrieveUsageHistory('sub_abc123', {
+  start_date: '2025-01-01T00:00:00Z',
+  page_size: 20,
+})) {
+  console.log(period); // one record per billing period, with per-meter usage
+}
 ```
 
-This returns aggregated usage per meter for the subscription's current billing period.
+This is paginated usage history organized by billing period, across the subscription's lifetime - not just the current period. Filter with `start_date`, `end_date`, and `meter_id`, and iterate pages (or `for await`) rather than reading only the first page.
 
 ---
 
@@ -378,7 +272,7 @@ To link a meter to credits:
 3. On the meter, enable **Bill usage in Credits**.
 4. Set `credit_entitlement_id` and `meter_units_per_credit` (e.g., 1,000 tokens = 1 credit).
 
-Usage under the free threshold is excluded. Approximately every minute, a background worker aggregates new usage, converts it using the meter-to-credit ratio, and consumes the oldest non-expired credit grants (FIFO). When credits run out, configured overage behavior applies.
+The free threshold does **not** apply to credit-billed meters: every unit counts toward credit deduction (it only applies when the meter bills in money). Approximately every minute, a background worker aggregates new usage, converts it using the meter-to-credit ratio, and deducts from non-expired grants, earliest-expiring grants consumed first. When credits run out, configured overage behavior applies.
 
 ---
 

package/skills/usage-based-billing/references/instrumentation.md

@@ -0,0 +1,119 @@
+# Dodo Payments Usage-Based Billing: Instrumenting Your Application
+
+
+### Track API Calls
+
+Persist the event before reporting the operation as complete, then ingest it from a retrying worker. The outbox or queue implementation must durably store the payload before `persist` resolves.
+
+```typescript
+type PersistedUsageEvent = {
+  event_id: string;
+  customer_id: string;
+  event_name: string;
+  timestamp: string;
+  metadata: Record<string, string | number | boolean>;
+};
+
+interface UsageOutbox {
+  persist(event: PersistedUsageEvent): Promise<void>;
+  nextBatch(limit: number): Promise<PersistedUsageEvent[]>;
+  markIngested(eventIds: string[]): Promise<void>;
+}
+
+async function completeApiOperation(
+  outbox: UsageOutbox,
+  operationId: string,
+  customerId: string,
+  occurredAt: string,
+): Promise<void> {
+  await outbox.persist({
+    event_id: `api-call:${operationId}`,
+    customer_id: customerId,
+    event_name: 'api.call',
+    timestamp: occurredAt,
+    metadata: { endpoint: '/v1/users', method: 'GET', status: 200 },
+  });
+}
+
+async function ingestUsageOutbox(outbox: UsageOutbox): Promise<void> {
+  const events = await outbox.nextBatch(1000);
+  if (events.length === 0) return;
+
+  await client.usageEvents.ingest({ events });
+  await outbox.markIngested(events.map((event) => event.event_id));
+}
+```
+
+If the worker crashes after Dodo accepts the batch but before `markIngested`, retry the same persisted events with the same IDs. Dodo ignores the already-ingested IDs.
+
+### Track AI Token Usage
+
+```typescript
+async function callAI(
+  customerId: string,
+  generationId: string,
+  prompt: string,
+  completedAt: string,
+) {
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: prompt }],
+  });
+
+  // Track tokens after completion
+  await client.usageEvents.ingest({
+    events: [{
+      event_id: `generation:${generationId}`,
+      customer_id: customerId,
+      event_name: 'ai.tokens',
+      timestamp: completedAt,
+      // Aggregated properties (Sum/Max/Last) must be numbers, not strings.
+      metadata: {
+        tokens: response.usage.total_tokens,
+        prompt_tokens: response.usage.prompt_tokens,
+        completion_tokens: response.usage.completion_tokens,
+        model: 'gpt-4',
+      }
+    }]
+  });
+
+  return response;
+}
+```
+
+### Track Storage Usage
+
+For snapshot-based metrics (current state), use the `last` aggregation:
+
+```typescript
+async function updateStorageUsage(
+  customerId: string,
+  snapshotId: string,
+  bytesUsed: number,
+  capturedAt: string,
+) {
+  await client.usageEvents.ingest({
+    events: [{
+      event_id: `storage-snapshot:${snapshotId}`,
+      customer_id: customerId,
+      event_name: 'storage.snapshot',
+      timestamp: capturedAt,
+      // Numeric values: a string property does not aggregate.
+      metadata: {
+        bytes: bytesUsed,
+        gb: Number((bytesUsed / 1024 / 1024 / 1024).toFixed(2)),
+      }
+    }]
+  });
+}
+
+// Call periodically or after storage changes
+await updateStorageUsage(
+  'cus_abc',
+  'snapshot_01K1M4D2K9',
+  5368709120,
+  '2026-08-01T10:30:00Z',
+); // 5GB
+```
+
+---