@dodopayments/opencode-plugin 0.6.1 → 0.6.3

package/skills/refunds-and-disputes/SKILL.md

@@ -350,4 +350,4 @@ async function reconcileRefund(refund) {
 - [Refunds API](https://docs.dodopayments.com/api-reference/refunds/post-refunds)
 - [Refunds feature guide](https://docs.dodopayments.com/features/transactions/refunds)
 - [Dispute webhooks](https://docs.dodopayments.com/developer-resources/webhooks/intents/dispute)
-- [Webhook integration skill](../webhook-integration/) for signature verification
+- The `webhook-integration` skill for signature verification

package/skills/subscription-integration/SKILL.md

@@ -347,85 +347,11 @@ For full customer management (creating, updating, listing), see the `customer-ma
 
 ## 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
+Full guide: [references/webhook-events.md](references/webhook-events.md).
 
-```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 });
-}
-```
+Covers:
 
----
+- Example Handler
 
 ## Credit Entitlements
 

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/usage-based-billing/SKILL.md

@@ -235,122 +235,13 @@ 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,
-      // 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
-```
-
----
+- Track API Calls
+- Track AI Token Usage
+- Track Storage Usage
 
 ## Querying Usage for Display
 

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
+```
+
+---