@dodopayments/opencode-plugin 0.6.0 → 0.6.2

package/skills/license-keys/references/cli-tool.md

@@ -0,0 +1,143 @@
+# Dodo Payments License Keys: CLI Tool Integration
+
+
+### Node.js CLI example
+
+```typescript
+// src/license.ts
+import Conf from 'conf';
+import DodoPayments from 'dodopayments';
+import { machineIdSync } from 'node-machine-id';
+
+interface StoredLicense {
+  key: string;
+  instanceId: string;
+  machineId: string;
+}
+
+interface CliStore {
+  license?: StoredLicense;
+}
+
+// Typing the store keeps `config.get('license')` strongly typed at every call site.
+const config = new Conf<CliStore>({ projectName: 'your-cli' });
+const client = new DodoPayments({ bearerToken: 'public', environment: 'test_mode' }); // public endpoints: placeholder token; use 'live_mode' in production
+
+export async function activate(licenseKey: string): Promise<void> {
+  const machineId = machineIdSync();
+  const deviceName = `CLI - ${process.platform} - ${machineId.substring(0, 8)}`;
+
+  try {
+    const response = await client.licenses.activate({
+      license_key: licenseKey,
+      name: deviceName,
+    });
+
+    config.set('license', {
+      key: licenseKey,
+      instanceId: response.id,
+      machineId,
+    });
+
+    console.log('License activated successfully!');
+  } catch (error: any) {
+    if (error.status === 422) {
+      console.error('Activation limit reached. Deactivate another device first.');
+    } else {
+      console.error('Activation failed:', error.message);
+    }
+    process.exit(1);
+  }
+}
+
+export async function checkLicense(): Promise<boolean> {
+  const license = config.get('license');
+
+  if (!license) {
+    return false;
+  }
+
+  try {
+    const response = await client.licenses.validate({
+      license_key: license.key,
+      license_key_instance_id: license.instanceId,
+    });
+
+    return response.valid;
+  } catch {
+    return false;
+  }
+}
+
+export async function deactivate(): Promise<void> {
+  const license = config.get('license');
+
+  if (!license) {
+    console.log('No active license found.');
+    return;
+  }
+
+  try {
+    await client.licenses.deactivate({
+      license_key: license.key,
+      license_key_instance_id: license.instanceId,
+    });
+
+    config.delete('license');
+    console.log('License deactivated.');
+  } catch (error: any) {
+    console.error('Deactivation failed:', error.message);
+  }
+}
+
+export function requireLicense() {
+  return async () => {
+    const valid = await checkLicense();
+    if (!valid) {
+      console.error('This command requires a valid license.');
+      console.error('Run: your-cli activate <license-key>');
+      process.exit(1);
+    }
+  };
+}
+```
+
+### CLI commands
+
+```typescript
+// src/cli.ts
+import { Command } from 'commander';
+import { activate, deactivate, checkLicense, requireLicense } from './license';
+
+const program = new Command();
+
+program
+  .command('activate <license-key>')
+  .description('Activate your license')
+  .action(activate);
+
+program
+  .command('deactivate')
+  .description('Deactivate license on this device')
+  .action(deactivate);
+
+program
+  .command('status')
+  .description('Check license status')
+  .action(async () => {
+    const valid = await checkLicense();
+    console.log(valid ? 'License: Active' : 'License: Not activated');
+  });
+
+program
+  .command('generate')
+  .description('Generate something (requires license)')
+  .hook('preAction', requireLicense())
+  .action(async () => {
+    // Premium feature
+  });
+
+program.parse();
+```
+
+---

package/skills/license-keys/references/desktop-app.md

@@ -0,0 +1,170 @@
+# Dodo Payments License Keys: Desktop App Integration
+
+
+### Electron app example
+
+```typescript
+// main/license.ts
+import Store from 'electron-store';
+import DodoPayments from 'dodopayments';
+import os from 'os';
+
+const store = new Store();
+const client = new DodoPayments({ bearerToken: 'public', environment: 'test_mode' }); // public endpoints: placeholder token; use 'live_mode' in production
+
+interface LicenseInfo {
+  key: string;
+  instanceId: string;
+  activatedAt: string;
+  lastValidatedAt?: string; // last time the server confirmed the license (absent on records saved before it was added)
+}
+
+export async function activateLicense(licenseKey: string): Promise<boolean> {
+  try {
+    const deviceName = `${os.hostname()} - ${os.platform()}`;
+
+    const response = await client.licenses.activate({
+      license_key: licenseKey,
+      name: deviceName,
+    });
+
+    const now = new Date().toISOString();
+    const licenseInfo: LicenseInfo = {
+      key: licenseKey,
+      instanceId: response.id,
+      activatedAt: now,
+      lastValidatedAt: now,
+    };
+
+    store.set('license', licenseInfo);
+    return true;
+  } catch (error) {
+    console.error('Activation failed:', error);
+    return false;
+  }
+}
+
+export async function checkLicense(): Promise<boolean> {
+  const license = store.get('license') as LicenseInfo | undefined;
+
+  if (!license) {
+    return false;
+  }
+
+  try {
+    const response = await client.licenses.validate({
+      license_key: license.key,
+      license_key_instance_id: license.instanceId,
+    });
+
+    if (!response.valid) {
+      // An explicit "invalid" from the server (revoked key, deactivated
+      // instance) ends the license: drop the cache so a later offline start
+      // cannot fall back to the grace period.
+      store.delete('license');
+      return false;
+    }
+    store.set('license', { ...license, lastValidatedAt: new Date().toISOString() });
+    return true;
+  } catch (error) {
+    // Only a connection failure (offline, DNS, timeout) earns the grace period.
+    // Any other API error - a revoked key, a deactivated instance - is a real
+    // answer from the server, so fail closed.
+    if (!(error instanceof DodoPayments.APIConnectionError)) {
+      return false;
+    }
+
+    // Trust the cached result only within a grace period measured from the
+    // LAST SUCCESSFUL validation, not from activation - otherwise a key revoked
+    // yesterday keeps working offline for 30 days after activation, and an old
+    // activation gets no grace at all.
+    // Records saved before lastValidatedAt existed fall back to activatedAt
+    // until their first successful validation.
+    const lastValidated = new Date(license.lastValidatedAt ?? license.activatedAt);
+    const daysSinceValidation = (Date.now() - lastValidated.getTime()) / (1000 * 60 * 60 * 24);
+
+    // Allow 30-day offline grace period
+    return daysSinceValidation < 30;
+  }
+}
+
+export async function deactivateLicense(): Promise<boolean> {
+  const license = store.get('license') as LicenseInfo | undefined;
+
+  if (!license) {
+    return true;
+  }
+
+  try {
+    await client.licenses.deactivate({
+      license_key: license.key,
+      license_key_instance_id: license.instanceId,
+    });
+
+    store.delete('license');
+    return true;
+  } catch (error) {
+    console.error('Deactivation failed:', error);
+    return false;
+  }
+}
+```
+
+### React component for license input
+
+```tsx
+// components/LicenseActivation.tsx
+import { useState } from 'react';
+
+interface Props {
+  onActivated: () => void;
+}
+
+export function LicenseActivation({ onActivated }: Props) {
+  const [licenseKey, setLicenseKey] = useState('');
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const handleActivate = async () => {
+    setLoading(true);
+    setError(null);
+
+    try {
+      const success = await window.electronAPI.activateLicense(licenseKey);
+
+      if (success) {
+        onActivated();
+      } else {
+        setError('Invalid license key. Please check and try again.');
+      }
+    } catch (err) {
+      setError('Activation failed. Please try again.');
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <div className="license-form">
+      <h2>Activate Your License</h2>
+      <p>Enter your license key to unlock all features.</p>
+
+      <input
+        type="text"
+        value={licenseKey}
+        onChange={(e) => setLicenseKey(e.target.value)}
+        placeholder="XXXX-XXXX-XXXX-XXXX"
+        disabled={loading}
+      />
+
+      {error && <p className="error">{error}</p>}
+
+      <button onClick={handleActivate} disabled={loading || !licenseKey}>
+        {loading ? 'Activating...' : 'Activate License'}
+      </button>
+    </div>
+  );
+}
+```
+
+---

package/skills/localized-pricing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: localized-pricing
-description: Guide for implementing localized pricing, adaptive currency, and purchasing power parity with Dodo Payments
+description: Dodo Payments multi-currency pricing, covering fixed localized prices per country or currency, Adaptive Currency live FX conversion at checkout, and purchasing power parity (PPP) percentages. Use when pricing in INR, EUR, or other local currencies, offering regional or PPP discounts, or resolving billing country and currency fallback.
 ---
 
 # Localized Pricing, Adaptive Currency, and PPP
@@ -23,9 +23,9 @@ This skill covers three distinct mechanisms for pricing in multiple countries an
 |---|---|---|---|
 | **Localized Pricing** | Developer sets fixed prices per country/currency | You (via API) | Only when you update them |
 | **Adaptive Currency** | Live FX conversion at checkout time | Dodo (live rates) | Every transaction, based on current rates |
-| **PPP Discounts** | Third-party tools generate discount codes for low-income regions | ParityDeals, Evendeals, or similar | Per tool's schedule |
+| **Purchasing Power Parity (PPP)** | Charges a per-country percentage of the base price | You (business-wide country percentages in the dashboard, per-product opt-in) | Only when you change the percentages |
 
-**Key distinction:** Localized prices are static. Adaptive currency is dynamic. PPP is a discount mechanism, not a pricing mode.
+**Key distinction:** Localized prices are static. Adaptive currency is dynamic. PPP is a native per-country percentage applied to the base price before Adaptive Currency converts it.
 
 ### Localized Pricing
 
@@ -41,9 +41,23 @@ Use adaptive currency when you want to offer checkout in any currency without ma
 
 ### PPP (Purchasing Power Parity)
 
-Third-party services like ParityDeals or Evendeals generate discount codes for customers in low-income countries. These are not a native Dodo API feature. You integrate them by accepting the discount codes they generate and passing them to Dodo at checkout.
+PPP is native ([docs](https://docs.dodopayments.com/features/purchasing-power-parity)). Dodo keeps one business-wide percentage per country (30 to 100, managed in the dashboard only), and the customer pays that share of your list price based on their billing country. Each product opts in with `price.purchasing_power_parity: true` (default `false`).
 
-Use PPP when you want to offer affordability-based discounts without building your own detection logic.
+PPP requires Adaptive Currency: enable it under **Settings → Business** first, or product opt-in is rejected. A matching localized price always wins over PPP, and discount codes apply to the PPP-reduced price.
+
+```typescript
+await client.products.create({
+  name: 'Starter Plan',
+  tax_category: 'saas',
+  price: {
+    type: 'one_time_price',
+    currency: 'USD',
+    price: 2000, // $20.00; a customer in India at 30% pays $6.00
+    discount: 0,
+    purchasing_power_parity: true,
+  },
+});
+```
 
 ## Product pricing mode
 
@@ -125,24 +139,40 @@ Archived prices are soft-deleted. They no longer apply to new checkouts but rema
 
 ## Adaptive Currency at checkout
 
-Enable adaptive currency by passing `billing_currency` to a checkout session. Dodo converts the base product price using live rates.
+Enable Adaptive Currency in the dashboard under **Settings → Business** ([docs](https://docs.dodopayments.com/features/adaptive-currency)). Dodo then converts the base product price at live rates. Passing `billing_currency` and `billing_address.country` on a checkout session only pins the currency you charge in; if you omit them, Adaptive Currency picks the currency and country from the customer's IP address.
 
 ```typescript
-const session = await client.checkoutSessions.create({
-  product_cart: [
-    {
-      product_id: 'pdt_premium_plan',
-      quantity: 1,
-    },
-  ],
-  billing_currency: 'AED', // Customer sees price in AED
-  return_url: 'https://example.com/return',
-});
+// Server route (e.g. POST /api/checkout): create the session and return its URL
+export async function POST() {
+  const session = await client.checkoutSessions.create({
+    product_cart: [
+      {
+        product_id: 'pdt_premium_plan',
+        quantity: 1,
+      },
+    ],
+    billing_currency: 'AED', // Pin the charge currency (requires Adaptive Currency)
+    billing_address: { country: 'AE' },
+    return_url: 'https://example.com/return',
+  });
+
+  return Response.json({ checkout_url: session.checkout_url });
+}
+```
+
+Never call the SDK or expose the API key in browser code. The browser only receives the URL and redirects:
 
-// Redirect customer to checkout
-window.location.href = session.checkout_url;
+```typescript
+// Browser
+const res = await fetch('/api/checkout', { method: 'POST' });
+const { checkout_url } = (await res.json()) as { checkout_url: string };
+window.location.href = checkout_url;
 ```
 
+**Fees:** Adaptive Currency adds a tiered conversion fee (4% under $500, 3% from $500 to $1,500, 2% above $1,500) on top of the displayed price by default. Turn on **Fees Inclusive** in **Settings → Business** to absorb the fee from your settlement instead. When a localized price matches, the transaction is always treated as fees-inclusive.
+
+**Charm Pricing:** With Adaptive Currency on, [Charm Pricing](https://docs.dodopayments.com/features/charm-pricing) can round the converted price to a clean ending such as 49.99. It requires Adaptive Currency.
+
 Adaptive currency is also available on subscription creation and plan changes. Check the API reference for `billing_currency` support on the specific endpoint you're using.
 
 ## Billing country and currency resolution
@@ -195,7 +225,7 @@ A customer in India using a USD card will match `by_currency: USD` but not `by_c
 
 ### Mistake 3: Forgetting a fallback price
 
-If you set `pricing_mode: by_country` but don't create a localized price for a customer's country, Dodo falls back to the base price in the base currency. This is usually not what you want.
+If you set `pricing_mode: by_country` but don't create a localized price for a customer's country, Dodo falls back to the base price: charged directly if the customer is already in your base currency, or converted through Adaptive Currency when that is enabled ([docs](https://docs.dodopayments.com/features/localized-pricing)). Without Adaptive Currency, that is the base price in the base currency, which is usually not what you want.
 
 Always create localized prices for your target markets before enabling the mode.
 
@@ -205,17 +235,9 @@ You can use both on the same product, but they serve different purposes. Localiz
 
 If you set a localized price for India and also enable adaptive currency, the localized price takes precedence for customers in India.
 
-### Mistake 5: Expecting PPP to be a native Dodo API
-
-PPP discounts are generated by third-party services like ParityDeals or Evendeals. Dodo does not have a built-in PPP API. You integrate PPP by accepting discount codes from these services and passing them to Dodo at checkout.
+### Mistake 5: Reaching for a third-party tool for PPP
 
-```typescript
-const session = await client.checkoutSessions.create({
-  product_cart: [{ product_id: 'pdt_premium_plan', quantity: 1 }],
-  discount_codes: ['PPP_DISCOUNT_CODE_FROM_PARITY_DEALS'],
-  return_url: 'https://example.com/return',
-});
-```
+PPP is native: opt products in with `price.purchasing_power_parity: true` and set country percentages in the dashboard (Adaptive Currency must be on). Third-party tools like ParityDeals are only an alternative if you want their site banners; their codes are passed as ordinary `discount_codes` at checkout.
 
 ### Mistake 6: Not handling missing localized prices in production