@dodopayments/opencode-plugin 0.3.3 → 0.4.0

package/skills/product-catalog-management/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: product-catalog-management
+description: Guide for creating and managing products, pricing, add-ons, product collections, images, and digital product delivery
+---
+
+# Product Catalog Management
+
+This skill covers the full product lifecycle: creating products with pricing models, managing add-ons and collections, uploading product images, and delivering digital files to customers.
+
+## When to use this skill
+
+- You need to create or update products with one-time, recurring, or usage-based pricing.
+- You're building a product collection or storefront.
+- You need to upload product images or deliver digital files to customers.
+- You're managing add-ons or product variants.
+- You need to understand why a product update failed or why pricing can't be changed.
+
+## Core concepts
+
+**Product model:** Every product has exactly one pricing model selected at creation. The three models are:
+
+- `one_time_price`: charge once per purchase.
+- `recurring_price`: charge on a configurable payment frequency and subscription period.
+- `usage_based_price`: charge per unit consumed (see `usage-based-billing` skill for meter setup).
+
+Pricing is nested inside the product object. There is no separate top-level Price resource.
+
+**Pricing structure:** Each price object contains:
+
+- `type`: one of the three models above.
+- `currency`: ISO 4217 code (e.g., `USD`, `AED`, `INR`).
+- `price`: amount in the smallest currency unit (cents for USD).
+- `discount`: optional discount amount in the same unit.
+
+**Tax category:** Required at product creation. Dodo uses this to calculate and collect sales tax. Supported values are `digital_products`, `saas`, `e_book`, and `edtech`.
+
+**Lifecycle:** Products support `list`, `retrieve`, `update`, and `archive`/`unarchive`. There is no delete endpoint. Archived products remain in your history but don't appear in new checkouts.
+
+**Images:** Presigned upload URLs expire after 60 seconds. Download the URL immediately after requesting it.
+
+**Digital delivery:** Entitlements grant customers access to files. Download URLs expire after roughly 15 minutes.
+
+## Creating a product
+
+All products require a name, a pricing model, and a tax category.
+
+```typescript
+import DodoPayments from 'dodopayments';
+
+const client = new DodoPayments({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  environment: 'test_mode',
+});
+
+// One-time purchase
+const product = await client.products.create({
+  name: 'Pro Bundle',
+  tax_category: 'digital_products',
+  price: {
+    type: 'one_time_price',
+    currency: 'USD',
+    price: 9900, // $99.00
+    discount: 0,
+    purchasing_power_parity: false,
+  },
+});
+
+console.log(product.product_id); // pdt_...
+```
+
+For recurring products, specify the billing cycle:
+
+```typescript
+const subscription = await client.products.create({
+  name: 'Premium Plan',
+  tax_category: 'saas',
+  price: {
+    type: 'recurring_price',
+    currency: 'USD',
+    price: 2999, // $29.99/month
+    discount: 0,
+    payment_frequency_count: 1,
+    payment_frequency_interval: 'Month',
+    subscription_period_count: 1,
+    subscription_period_interval: 'Month',
+    purchasing_power_parity: false,
+  },
+});
+```
+
+This skill is the canonical source for product creation request shapes. For a usage-based product, create the meter as described in the `usage-based-billing` skill, then attach it through the singular `price.meters` array:
+
+```typescript
+const metered = await client.products.create({
+  name: 'API Calls',
+  tax_category: 'saas',
+  price: {
+    type: 'usage_based_price',
+    currency: 'USD',
+    discount: 0,
+    fixed_price: 0, // No fixed monthly charge; amounts use the smallest currency unit
+    payment_frequency_count: 1,
+    payment_frequency_interval: 'Month',
+    subscription_period_count: 1,
+    subscription_period_interval: 'Month',
+    purchasing_power_parity: false,
+    meters: [
+      {
+        meter_id: 'mtr_api_calls',
+        price_per_unit: '0.01',
+        free_threshold: 1000,
+      },
+    ],
+  },
+});
+```
+
+`price_per_unit` is a decimal string in the configured currency's smallest unit. The optional `free_threshold` excludes that many aggregated units before per-unit charging begins.
+
+## Listing and retrieving products
+
+```typescript
+// List all products
+const products = await client.products.list();
+
+// Retrieve a single product
+const product = await client.products.retrieve('pdt_pro_bundle');
+```
+
+## Updating a product
+
+You can update the name, description, and metadata. You cannot change the pricing model or price of a live product. Create a new product instead.
+
+```typescript
+await client.products.update('pdt_pro_bundle', {
+  name: 'Pro Bundle (Updated)',
+  description: 'Includes all pro features',
+  metadata: {
+    category: 'software',
+    tier: 'premium',
+  },
+});
+```
+
+## Archiving and unarchiving
+
+Archive a product to hide it from new checkouts without deleting it:
+
+```typescript
+await client.products.archive('pdt_pro_bundle');
+
+// Restore it later
+await client.products.unarchive('pdt_pro_bundle');
+```
+
+## Product images
+
+Upload a product image via presigned URL. The URL is valid for 60 seconds.
+
+```typescript
+import fs from 'node:fs';
+
+// Request a presigned upload URL
+const uploadUrl = await client.products.images.update('pdt_pro_bundle', {
+  force_update: true,
+});
+
+// Upload immediately (within 60 seconds)
+const response = await fetch(uploadUrl.url, {
+  method: 'PUT',
+  body: fs.readFileSync('./product.png'),
+  headers: { 'Content-Type': 'image/png' },
+});
+
+if (!response.ok) {
+  throw new Error('Image upload failed');
+}
+```
+
+## Add-ons
+
+Add-ons are optional extras customers can purchase alongside a product. Create them independently, then reference them in checkout.
+
+```typescript
+// Create an add-on
+const addon = await client.addons.create({
+  name: 'Priority Support',
+  tax_category: 'saas',
+  currency: 'USD',
+  price: 4900, // $49.00
+});
+
+// Upload an image for the add-on
+const addonImageUrl = await client.addons.updateImages(addon.id);
+
+// List add-ons
+const addons = await client.addons.list();
+```
+
+## Product collections
+
+Group products into collections for themed checkouts. Collections have nested groups and items.
+
+```typescript
+// Create a collection
+const collection = await client.productCollections.create({
+  name: 'Starter Bundle',
+  description: 'Everything you need to get started',
+  groups: [
+    {
+      group_name: 'Core Tools',
+      products: [
+        { product_id: 'pdt_tool_a' },
+        { product_id: 'pdt_tool_b' },
+      ],
+    },
+  ],
+});
+
+// Add another group later
+await client.productCollections.groups.create(collection.id, {
+  group_name: 'Optional Tools',
+  products: [
+    { product_id: 'pdt_tool_c' },
+    { product_id: 'pdt_tool_d' },
+  ],
+});
+
+// Checkout with a collection
+const session = await client.checkoutSessions.create({
+  product_collection_id: collection.id,
+  product_cart: [], // Required: pass an empty array for collection checkout
+  return_url: 'https://yoursite.com/return',
+});
+
+window.location.href = session.checkout_url;
+```
+
+## Digital product delivery
+
+Entitlements grant customers access to downloadable files. Create an entitlement, upload files, and generate download links.
+
+```typescript
+// Create an entitlement
+const entitlement = await client.entitlements.create({
+  name: 'Pro Bundle Files',
+  integration_type: 'digital_files',
+  integration_config: {
+    digital_file_ids: [],
+  },
+});
+
+// Upload and attach a file; the response identifies the attached file
+const { file_id } = await client.entitlements.files.upload(entitlement.id);
+
+// Attach the entitlement to a product
+await client.products.update('pdt_pro_bundle', {
+  entitlements: [{ entitlement_id: entitlement.id }],
+});
+
+// A grant is produced by fulfillment when the customer purchases the product.
+// Grants can be listed, revoked, or fulfilled with a manually managed license key;
+// they cannot be created directly through the SDK.
+
+// List grants for a customer
+const grants = await client.customers.listEntitlementGrants('cus_customer_123');
+
+// Generate a download URL (valid for roughly 15 minutes)
+const grant = grants.items[0];
+const downloadUrl = grant?.digital_product_delivery?.files[0]?.download_url;
+```
+
+## Short links
+
+Create short, shareable links to products:
+
+```typescript
+const shortLink = await client.products.shortLinks.create('pdt_pro_bundle', {
+  slug: 'pro-bundle-deal',
+});
+
+console.log(shortLink.short_url); // https://dodo.link/pro-bundle-deal
+```
+
+## Localized pricing
+
+For country or currency-specific pricing, use the `localized-pricing` skill. Do not hardcode prices in the client.
+
+## Common mistakes
+
+**Expecting a delete endpoint:** Products don't have a delete method. Archive them instead. Archived products remain in your history for reconciliation.
+
+**Trying to change the pricing model:** Once a product is created with `one_time_price`, you can't change it to `recurring_price`. Create a new product and migrate customers to it.
+
+**Hardcoding prices in the client:** Always fetch the product catalog from the API. Prices change, and your client code will become stale. Read `client.products.retrieve(id)` to get the current price.
+
+**Forgetting the tax category:** Every product requires a `tax_category`. Dodo uses this to calculate and remit sales tax. Omitting it will cause the create request to fail.
+
+**Uploading images after the 60-second window:** Request the presigned URL and upload immediately. If the URL expires, request a new one.
+
+**Passing a non-empty product_cart for collection checkout:** Collection checkout requires `product_cart: []`. The collection itself defines what's in the cart.
+
+**Confusing purchasing_power_parity with localized pricing:** The OpenAPI schema includes a `purchasing_power_parity` field in examples, but it's marked unavailable. Use the `localized-pricing` skill for country and currency pricing instead.
+
+## Resources
+
+- [Products](https://docs.dodopayments.com/features/products)
+- [Create product API](https://docs.dodopayments.com/api-reference/products/post-products)
+- [Product Collections](https://docs.dodopayments.com/features/product-collections)
+- [Digital Product Delivery](https://docs.dodopayments.com/features/digital-product-delivery)
+- [Add-ons](https://docs.dodopayments.com/features/addons)

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

@@ -0,0 +1,333 @@
+---
+name: refunds-and-disputes
+description: Guide for issuing refunds, handling disputes and chargebacks, and reconciling customer access with Dodo Payments
+---
+
+# Refunds and Disputes
+
+This skill covers issuing refunds (full and partial), handling the dispute lifecycle, and managing customer access during payment reversals. Disputes are inbound-only; Dodo handles the card-network process as Merchant of Record while you control application access and evidence gathering.
+
+## When to use this skill
+
+- You need to issue a refund (full or partial) for a payment
+- A customer disputes a charge and you need to respond with evidence
+- You're building access-revocation logic tied to refund or dispute status
+- You need to reconcile customer entitlements after a payment reversal
+- You're handling refund or dispute webhooks in production
+
+## Core concepts
+
+**Refunds** are initiated by you via the API. Each refund has a status that tells you whether the money has actually left your account. Partial refunds target specific line items in the original payment.
+
+**Disputes** are initiated by the customer's card network. You cannot create them; you only list and retrieve them. The dispute lifecycle spans seven events, each requiring different application actions.
+
+**Amounts** are always in the smallest currency unit (cents for USD, paise for INR, etc.).
+
+**Access revocation** means removing the customer's ability to use the product or service. On a dispute, you typically revoke access while it's open. Restore it only on `dispute.won`; all other outcomes keep access revoked until you reconcile them separately.
+
+## Refunds
+
+### Create a refund
+
+```typescript
+import DodoPayments from 'dodopayments';
+
+const client = new DodoPayments({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  environment: 'test_mode',
+});
+
+// Full refund
+const refund = await client.refunds.create({
+  payment_id: 'pay_abc123',
+});
+
+console.log(refund.refund_id);
+console.log(refund.status); // 'pending', 'succeeded', 'review', or 'failed'
+```
+
+### Partial refund by item
+
+To refund only specific items from a payment, pass the `items` array with each item ID and the amount to refund in the smallest currency unit. Omit `amount` to refund the whole item:
+
+```typescript
+const partialRefund = await client.refunds.create({
+  payment_id: 'pay_abc123',
+  items: [
+    { item_id: 'item_1', amount: 1000 },
+    { item_id: 'item_2', amount: 2500 },
+  ],
+});
+```
+
+### Refund statuses
+
+Each refund has one of four statuses:
+
+| Status | Meaning | Your action |
+|---|---|---|
+| `pending` | Refund is processing; money hasn't left your account yet | Wait for a webhook or poll the refund status |
+| `succeeded` | Money has been returned to the customer | Revoke access if the product is non-refundable; update your records |
+| `review` | Refund is under review (rare) | Contact support; do not assume it will succeed |
+| `failed` | Refund failed; money remains in your account | Investigate the failure; consider retrying or contacting the customer |
+
+### List and retrieve refunds
+
+```typescript
+// List all refunds
+const refunds = await client.refunds.list();
+
+// Retrieve a specific refund
+const refund = await client.refunds.retrieve('ref_xyz789');
+console.log(refund.status);
+```
+
+### Handle refund webhooks
+
+Webhook signature verification is covered in the `webhook-integration` skill. Always verify the signature before processing.
+
+```typescript
+import DodoPayments from 'dodopayments';
+import express from 'express';
+
+const app = express();
+app.use(express.raw({ type: 'application/json' }));
+
+// `environment` is a narrow union, but env vars are `string | undefined`.
+// Narrow explicitly rather than casting, and default to test mode so a missing
+// variable can never accidentally hit live.
+const environment = process.env.DODO_PAYMENTS_ENVIRONMENT === 'live_mode' ? 'live_mode' : 'test_mode';
+
+const client = new DodoPayments({
+  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+  environment,
+  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
+});
+
+app.post('/webhook', async (req, res) => {
+  try {
+    const event = client.webhooks.unwrap(req.body.toString(), {
+      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 === 'refund.succeeded') {
+      const refund = event.data;
+      // Refund succeeded; revoke access if needed
+      await revokeCustomerAccess(refund.customer.customer_id);
+      await updateRefundRecord(refund.refund_id, 'succeeded');
+    }
+
+    if (event.type === 'refund.failed') {
+      const refund = event.data;
+      // Refund failed; keep access active, alert support
+      await logRefundFailure(refund.refund_id, refund.reason);
+    }
+
+    res.json({ received: true });
+  } catch (error) {
+    res.status(401).json({ error: 'Invalid signature' });
+  }
+});
+```
+
+## Disputes
+
+### Retrieve disputes
+
+Disputes are inbound-only. You cannot create them; you can only list and retrieve them.
+
+```typescript
+// List all disputes
+const disputes = await client.disputes.list();
+
+// Retrieve a specific dispute
+const dispute = await client.disputes.retrieve('dis_abc123');
+console.log(dispute.dispute_status);
+console.log(dispute.amount); // in smallest currency unit
+```
+
+### Dispute lifecycle
+
+A dispute moves through seven events. Each event requires a different action from your application:
+
+| Event | Meaning | Your action |
+|---|---|---|
+| `dispute.opened` | Customer initiated a chargeback | Record the dispute; consider revoking access immediately; gather evidence from your logs |
+| `dispute.challenged` | You submitted evidence | Wait for the card network to review |
+| `dispute.accepted` | You accepted (conceded) the dispute; funds go to the cardholder | Keep access revoked; mark the dispute as accepted in your records |
+| `dispute.cancelled` | Customer or system cancelled the dispute | Keep access revoked; reconcile the payment separately |
+| `dispute.expired` | Dispute window closed without resolution | Treat as lost; keep access revoked |
+| `dispute.won` | You won the dispute | Funds are retained; restore access; update customer records |
+| `dispute.lost` | You lost the dispute | Funds returned to cardholder; keep access revoked; reconcile your records |
+
+### Handle dispute webhooks
+
+Webhook dispute payloads intentionally contain no customer field. Resolve the customer with an extra `disputes.retrieve()` call: the webhook's `dispute_id` identifies the dispute, and the returned `GetDispute` includes `customer`. Without this lookup, access-control handlers would receive `undefined`.
+
+```typescript
+async function resolveDisputeCustomerId(disputeId: string) {
+  const dispute = await client.disputes.retrieve(disputeId);
+  return dispute.customer.customer_id;
+}
+
+app.post('/webhook', async (req, res) => {
+  try {
+    const event = client.webhooks.unwrap(req.body.toString(), {
+      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 === 'dispute.opened') {
+      const dispute = event.data;
+      // Record the dispute and revoke access
+      await recordDispute(dispute.dispute_id, dispute.payment_id, dispute.amount);
+      const customerId = await resolveDisputeCustomerId(dispute.dispute_id);
+      await revokeCustomerAccess(customerId);
+      // Gather evidence from your system and submit via dashboard
+      // (no evidence-submission API exists; use the Dodo dashboard)
+    }
+
+    if (event.type === 'dispute.won') {
+      const dispute = event.data;
+      // Funds retained; restore normal state
+      await markDisputeResolved(dispute.dispute_id, 'won');
+      const customerId = await resolveDisputeCustomerId(dispute.dispute_id);
+      await restoreCustomerAccess(customerId);
+    }
+
+    if (event.type === 'dispute.lost') {
+      const dispute = event.data;
+      // Funds returned to cardholder; keep access revoked
+      await markDisputeResolved(dispute.dispute_id, 'lost');
+      // Do NOT restore access
+    }
+
+    if (event.type === 'dispute.accepted') {
+      const dispute = event.data;
+      // Merchant conceded; funds go to the cardholder and access stays revoked
+      await markDisputeResolved(dispute.dispute_id, 'accepted');
+      // Do NOT restore access
+    }
+
+    if (event.type === 'dispute.cancelled') {
+      const dispute = event.data;
+      // Cancellation is not a win; keep access revoked and reconcile separately
+      await markDisputeResolved(dispute.dispute_id, 'cancelled');
+    }
+
+    res.json({ received: true });
+  } catch (error) {
+    res.status(401).json({ error: 'Invalid signature' });
+  }
+});
+```
+
+### Evidence submission
+
+Dodo handles the card-network dispute process as Merchant of Record. You submit evidence through the Dodo dashboard, not via API. No evidence-submission API exists.
+
+When a dispute opens, gather your evidence (order confirmation, delivery proof, customer communication, etc.) and upload it to the dashboard within the dispute window (typically 4 days). The card network reviews your evidence and makes a final decision.
+
+## Access revocation pattern
+
+A common pattern for managing access during disputes:
+
+```typescript
+async function handleDisputeLifecycle(
+  dispute: Awaited<ReturnType<typeof client.disputes.retrieve>>,
+) {
+  const customerId = dispute.customer.customer_id;
+
+  switch (dispute.dispute_status) {
+    case 'dispute_opened':
+      // Revoke access immediately
+      await revokeCustomerAccess(customerId);
+      break;
+
+    case 'dispute_won':
+      // You won; restore access
+      await restoreCustomerAccess(customerId);
+      break;
+
+    case 'dispute_lost':
+      // You lost; keep access revoked
+      // (do nothing)
+      break;
+
+    case 'dispute_accepted':
+      // You conceded; funds go to the cardholder and access stays revoked
+      break;
+
+    case 'dispute_cancelled':
+      // Cancellation is not a win; reconcile separately and keep access revoked
+      break;
+
+    case 'dispute_expired':
+      // Treat as lost; keep access revoked
+      break;
+
+    case 'dispute_challenged':
+      // Evidence is under review; keep access revoked
+      break;
+  }
+}
+```
+
+## Reconciling entitlements after refund
+
+When a refund succeeds, you must reconcile the customer's access. If the product is non-refundable (e.g., a digital download or subscription already used), revoke access. If it's refundable (e.g., a subscription not yet started), you may restore access or leave it revoked depending on your policy.
+
+```typescript
+async function reconcileRefund(refund) {
+  if (refund.status !== 'succeeded') {
+    return; // Not yet final
+  }
+
+  const payment = await client.payments.retrieve(refund.payment_id);
+  const customer = payment.customer;
+
+  // Revoke access for non-refundable products
+  const includesNonRefundableProduct = payment.product_cart?.some(({ product_id }) =>
+    isNonRefundable(product_id),
+  );
+
+  if (includesNonRefundableProduct) {
+    await revokeCustomerAccess(customer.customer_id);
+  }
+
+  // Update your entitlement records
+  await updateEntitlementRecord(customer.customer_id, {
+    refund_id: refund.refund_id,
+    refund_amount: refund.amount,
+    refund_date: new Date(),
+  });
+}
+```
+
+## Common mistakes
+
+**Auto-refunding without revoking access.** A refund webhook means money is leaving your account. If the product is non-refundable, revoke access immediately. Don't wait for the customer to ask.
+
+**Treating `dispute.opened` as final.** A dispute is not lost until the card network says so. Keep access revoked while it's open, but don't delete customer data or close their account.
+
+**Ignoring partial refunds when computing entitlements.** If a customer refunds only one item from a multi-item purchase, their entitlement to the other items remains valid. Track refunds by item, not just by payment.
+
+**Restoring access on any outcome except `dispute.won`.** `dispute.accepted` means you conceded and the cardholder receives the funds. A cancelled dispute is also not a win. Keep access revoked and reconcile separately unless you receive `dispute.won`.
+
+**Submitting evidence after the dispute window closes.** The card network typically gives you 4 days to respond. Set a calendar reminder and gather evidence immediately when a dispute opens.
+
+**Assuming Dodo will handle access revocation.** Dodo handles the card-network process; you handle application access. Dodo won't revoke your customer's subscription or file access automatically.
+
+## Resources
+
+- [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