@adityanair98/api-oracle 0.5.0

package/src/entries/messaging/vonage.json

@@ -0,0 +1,89 @@
+{
+  "name": "Vonage",
+  "slug": "vonage",
+  "category": "messaging",
+  "subcategory": "sms-voice",
+  "website": "https://www.vonage.com/communications-apis",
+  "description": "Vonage (formerly Nexmo) is a cloud communications platform offering SMS, voice, video, and authentication APIs. It is Twilio's primary competitor with strong European coverage and a more developer-friendly pricing model, especially for international SMS.",
+  "useCases": [
+    {
+      "task": "Send SMS messages globally with competitive international rates",
+      "fit": "perfect"
+    },
+    {
+      "task": "Implement SMS-based two-factor authentication",
+      "fit": "perfect"
+    },
+    {
+      "task": "Make and receive programmatic voice calls",
+      "fit": "good"
+    },
+    {
+      "task": "Verify phone numbers with OTP",
+      "fit": "perfect"
+    }
+  ],
+  "auth": {
+    "method": "api_key",
+    "setupSteps": [
+      "Sign up at vonage.com",
+      "Go to your Dashboard to find your API Key and API Secret",
+      "Purchase a virtual number if needed for two-way SMS",
+      "Set VONAGE_API_KEY and VONAGE_API_SECRET environment variables"
+    ],
+    "envVarName": "VONAGE_API_SECRET",
+    "codeSnippet": "import Vonage from '@vonage/server-sdk';\nconst vonage = new Vonage({\n  apiKey: process.env.VONAGE_API_KEY!,\n  apiSecret: process.env.VONAGE_API_SECRET!,\n});"
+  },
+  "pricing": {
+    "model": "usage_based",
+    "freeTier": "€2 free credit on signup",
+    "startingPrice": "$0.0062 per SMS (US outbound)",
+    "costPer": "Varies by country; €0.0062/SMS outbound US; Voice from $0.013/min",
+    "pricingUrl": "https://www.vonage.com/communications-apis/sms/pricing"
+  },
+  "rateLimits": {
+    "tier": "default",
+    "limit": "30 messages/second (default); can be increased on request",
+    "notes": "Default throughput is higher than Twilio long codes. Rate limits can be increased for high-volume use cases.",
+    "retryStrategy": "Retry with exponential backoff on 429 responses; Vonage returns message-status in response for each sent message"
+  },
+  "sdk": {
+    "primaryLanguage": "typescript",
+    "installCommand": "npm install --save-exact @vonage/server-sdk",
+    "importStatement": "import Vonage from '@vonage/server-sdk';",
+    "otherLanguages": ["python", "java", "ruby", "php", "dotnet"]
+  },
+  "codeExamples": [
+    {
+      "title": "Send an SMS",
+      "language": "typescript",
+      "code": "import Vonage from '@vonage/server-sdk';\n\nconst vonage = new Vonage({\n  apiKey: process.env.VONAGE_API_KEY!,\n  apiSecret: process.env.VONAGE_API_SECRET!,\n});\n\nconst response = await vonage.sms.send({\n  to: '14155551234',\n  from: 'YourBrand', // Alphanumeric sender ID (not available in all countries)\n  text: 'Your verification code is 382910. Expires in 10 minutes.',\n});\n\nconst result = response.messages[0];\nif (result?.status === '0') {\n  console.log('SMS sent successfully, ID:', result['message-id']);\n} else {\n  console.error('Failed to send SMS:', result?.['error-text']);\n}",
+      "notes": "Alphanumeric sender IDs (like 'YourBrand') are not supported in all countries, including the US. In the US, you must use a virtual number."
+    },
+    {
+      "title": "Phone number verification with Verify API",
+      "language": "typescript",
+      "code": "import Vonage from '@vonage/server-sdk';\n\nconst vonage = new Vonage({\n  apiKey: process.env.VONAGE_API_KEY!,\n  apiSecret: process.env.VONAGE_API_SECRET!,\n});\n\n// Start verification\nconst verifyResponse = await vonage.verify.start({\n  number: '14155551234',\n  brand: 'MyApp',\n});\nconst requestId = verifyResponse.request_id;\nconsole.log('Verification started, request ID:', requestId);\n\n// Later — check the code user entered\nconst checkResponse = await vonage.verify.check(requestId, '1234');\nif (checkResponse.status === '0') {\n  console.log('Phone number verified successfully!');\n}",
+      "notes": "The Verify API handles the entire OTP flow — it sends the code, manages retries, and handles timeouts. Much simpler than building your own verification flow."
+    }
+  ],
+  "gotchas": [
+    "Vonage response objects use string status codes ('0' for success) not HTTP-style integers. Always check message.status === '0' rather than truthy checks, as error codes are also non-zero strings.",
+    "Alphanumeric sender IDs are banned in the US and several other countries. If you need to send from a recognizable name, you'll need to implement this per-country or use a short code.",
+    "The Vonage SDK has had significant breaking changes between major versions. Pin to the exact version you test against and review the changelog before upgrading.",
+    "International SMS prices vary wildly. A message that costs $0.006 in the US can cost $0.15+ in some countries. Always check country-specific pricing before rolling out globally."
+  ],
+  "reliability": {
+    "uptimeGuarantee": "99.999% uptime commitment on enterprise plans",
+    "statusPageUrl": "https://vonageapiservicestatus.com",
+    "notes": "Vonage has global carrier connections and data centers in multiple regions. Strong European infrastructure makes it a good choice for EU-focused applications."
+  },
+  "qualityScore": 7,
+  "qualityJustification": "Solid Twilio alternative with competitive international pricing and good European coverage. The TypeScript SDK is functional but not as polished as Twilio's. Verify API is genuinely excellent for OTP flows. Less community resources and documentation depth than Twilio.",
+  "alternatives": ["twilio"],
+  "complementary": ["resend", "clerk", "stripe"],
+  "bestFor": "SMS and voice communications with competitive international rates, especially for European markets or OTP verification flows",
+  "lastVerified": "2026-02-25",
+  "entryVersion": 1,
+  "addedBy": "claude-code-session-2"
+}

package/src/entries/notifications/knock.json

@@ -0,0 +1,84 @@
+{
+  "name": "Knock",
+  "slug": "knock",
+  "category": "notifications",
+  "subcategory": "notification-infrastructure",
+  "website": "https://knock.app",
+  "description": "Knock is a notification infrastructure platform that manages the entire notification workflow: routing users to the right channels (email, push, SMS, in-app), managing user preferences, handling notification templates, and tracking delivery — all in one place. It is built for product engineers who want to offload notification complexity.",
+  "useCases": [
+    {
+      "task": "Build a multi-channel notification system (email + push + in-app + SMS)",
+      "fit": "perfect"
+    },
+    {
+      "task": "Let users manage their own notification preferences",
+      "fit": "perfect"
+    },
+    {
+      "task": "Trigger notifications from workflows and digests",
+      "fit": "perfect"
+    },
+    {
+      "task": "Add an in-app notification feed to a web application",
+      "fit": "perfect"
+    }
+  ],
+  "auth": {
+    "method": "api_key",
+    "setupSteps": [
+      "Sign up at knock.app",
+      "Create a new environment (development and production are separate)",
+      "Go to Settings > API Keys to get your API key",
+      "Create users (Knock stores user preferences and notification history)",
+      "Set KNOCK_API_KEY environment variable"
+    ],
+    "envVarName": "KNOCK_API_KEY",
+    "codeSnippet": "import Knock from '@knocklabs/node';\nconst knock = new Knock(process.env.KNOCK_API_KEY!);"
+  },
+  "pricing": {
+    "model": "freemium",
+    "freeTier": "Up to 10,000 monthly notifications, 1 environment",
+    "startingPrice": "$100/month (Starter plan) for 100,000 notifications, 3 environments",
+    "costPer": "$1 per 1,000 notifications above plan limit",
+    "pricingUrl": "https://knock.app/pricing"
+  },
+  "rateLimits": {
+    "tier": "all tiers",
+    "limit": "500 requests/minute for the Workflows API (default)",
+    "notes": "Rate limits are per API key. Bulk workflow triggers and batch operations available. Contact support for higher limits.",
+    "retryStrategy": "Knock handles delivery retries internally per channel. Implement application-level retry with backoff for 429 API responses."
+  },
+  "sdk": {
+    "primaryLanguage": "typescript",
+    "installCommand": "npm install --save-exact @knocklabs/node",
+    "importStatement": "import Knock from '@knocklabs/node';",
+    "otherLanguages": ["python", "ruby", "go", "java", "elixir"]
+  },
+  "codeExamples": [
+    {
+      "title": "Trigger a notification workflow",
+      "language": "typescript",
+      "code": "import Knock from '@knocklabs/node';\n\nconst knock = new Knock(process.env.KNOCK_API_KEY!);\n\n// Identify the recipient (creates or updates the user in Knock)\nawait knock.users.identify('user-123', {\n  name: 'Jane Smith',\n  email: 'jane@example.com',\n  phone_number: '+14155551234',\n});\n\n// Trigger a workflow\nconst result = await knock.workflows.trigger('new-comment', {\n  recipients: ['user-123'],\n  data: {\n    commenter_name: 'Bob',\n    post_title: 'My awesome post',\n    comment_text: 'Great post, Jane!',\n    post_url: 'https://app.com/posts/456',\n  },\n  actor: 'user-456', // Who triggered the action\n});\n\nconsole.log('Workflow triggered:', result.workflow_run_id);",
+      "notes": "Workflows are defined in the Knock dashboard with channel routing logic. The 'new-comment' key matches the workflow key you created. Data fields map to template variables in your notification templates."
+    }
+  ],
+  "gotchas": [
+    "Knock requires you to 'identify' users before triggering notifications. If you trigger a workflow for an unidentified user, the notification is silently dropped. Always call users.identify() when users sign up in your app.",
+    "Knock's pricing scales by notifications sent, not users. If your app sends frequent notifications (e.g., a busy collaboration tool), costs can grow quickly. The 10k/month free tier is limiting for high-activity apps.",
+    "Knock manages notification preferences, but your app still needs to register push tokens (APNs/FCM). You send the token to Knock, which stores it per user — but you still need to implement the mobile push registration flow.",
+    "Environments in Knock are completely isolated. Workflows, templates, and configurations in Development don't carry over to Production — you must recreate them. Use the dashboard export/import to migrate."
+  ],
+  "reliability": {
+    "uptimeGuarantee": "99.9% uptime on paid plans",
+    "statusPageUrl": "https://status.knock.app",
+    "notes": "Knock is a younger platform but has strong reliability track record. Used by Vercel, Linear, and other developer-focused companies."
+  },
+  "qualityScore": 8,
+  "qualityJustification": "Best developer experience for building complex notification systems. The workflow model, user preference management, and in-app feed components are genuinely excellent. Pricing is the main constraint — $100/month minimum for production use is steep for indie developers. Excellent TypeScript SDK.",
+  "alternatives": ["novu", "onesignal"],
+  "complementary": ["resend", "twilio", "clerk"],
+  "bestFor": "Multi-channel notification infrastructure with workflow routing, user preferences, and in-app notification feeds for SaaS products",
+  "lastVerified": "2026-02-25",
+  "entryVersion": 1,
+  "addedBy": "claude-code-session-2"
+}

package/src/entries/notifications/novu.json

@@ -0,0 +1,84 @@
+{
+  "name": "Novu",
+  "slug": "novu",
+  "category": "notifications",
+  "subcategory": "notification-infrastructure",
+  "website": "https://novu.co",
+  "description": "Novu is an open-source notification infrastructure platform supporting email, SMS, push, in-app, and chat notifications from a single API. As an open-source alternative to Knock and Courier, it can be self-hosted for full data control, or used as a managed cloud service with a generous free tier.",
+  "useCases": [
+    {
+      "task": "Build a multi-channel notification system with open-source flexibility",
+      "fit": "perfect"
+    },
+    {
+      "task": "Self-host notification infrastructure for data control",
+      "fit": "perfect"
+    },
+    {
+      "task": "Add an in-app notification bell/feed to a web app",
+      "fit": "perfect"
+    },
+    {
+      "task": "Send notifications via multiple providers with fallback logic",
+      "fit": "good"
+    }
+  ],
+  "auth": {
+    "method": "api_key",
+    "setupSteps": [
+      "Sign up at novu.co (or self-host via Docker)",
+      "Go to Settings > API Keys in the Novu dashboard",
+      "Copy your API Key",
+      "Set NOVU_API_KEY environment variable",
+      "Create notification workflows (called 'workflows' or 'notifications') in the dashboard"
+    ],
+    "envVarName": "NOVU_API_KEY",
+    "codeSnippet": "import { Novu } from '@novu/node';\nconst novu = new Novu(process.env.NOVU_API_KEY!);"
+  },
+  "pricing": {
+    "model": "freemium",
+    "freeTier": "30,000 events/month, unlimited subscribers (cloud)",
+    "startingPrice": "$250/month (Business plan) for 250,000 events/month",
+    "costPer": "Cloud: $0.01 per event above free tier; self-hosted is free",
+    "pricingUrl": "https://novu.co/pricing"
+  },
+  "rateLimits": {
+    "tier": "free tier (cloud)",
+    "limit": "30,000 events/month, 60 requests/minute API rate limit",
+    "notes": "Self-hosted has no limits beyond your infrastructure capacity. Cloud rate limits scale with paid plans.",
+    "retryStrategy": "Implement standard exponential backoff for 429 responses. Novu handles per-channel delivery retries automatically."
+  },
+  "sdk": {
+    "primaryLanguage": "typescript",
+    "installCommand": "npm install --save-exact @novu/node",
+    "importStatement": "import { Novu } from '@novu/node';",
+    "otherLanguages": ["python", "php", "ruby", "java", "go", "dotnet"]
+  },
+  "codeExamples": [
+    {
+      "title": "Trigger a notification",
+      "language": "typescript",
+      "code": "import { Novu } from '@novu/node';\n\nconst novu = new Novu(process.env.NOVU_API_KEY!);\n\n// Identify subscriber (creates if not exists)\nawait novu.subscribers.identify('user-123', {\n  firstName: 'Jane',\n  lastName: 'Smith',\n  email: 'jane@example.com',\n  phone: '+14155551234',\n});\n\n// Trigger workflow\nconst result = await novu.trigger('order-shipped', {\n  to: { subscriberId: 'user-123' },\n  payload: {\n    orderId: 'order_456',\n    trackingUrl: 'https://track.example.com/order_456',\n    estimatedDelivery: 'Feb 28, 2026',\n  },\n});\n\nconsole.log('Triggered:', result.data?.transactionId);",
+      "notes": "Workflows are defined in the Novu dashboard. The first argument to trigger() is the workflow trigger ID. Subscribers are automatically created if they don't exist."
+    }
+  ],
+  "gotchas": [
+    "Novu's open-source status means the self-hosted version can lag behind the cloud version in features. Check the GitHub releases before choosing self-hosting for production.",
+    "The jump from free tier (30k events) to paid ($250/month Business) is steep with no intermediate tier. For apps between 30k-250k events, consider whether the cost is justified versus simpler alternatives.",
+    "Novu's workflow builder in the dashboard is a visual editor — complex workflows with branching logic are harder to version-control than code-based approaches like Knock.",
+    "Subscriber management is separate from your user database. You must sync users to Novu (via identify()) on signup and keep them in sync. A missed identify call means notifications get dropped silently."
+  ],
+  "reliability": {
+    "uptimeGuarantee": "99.5% uptime on cloud; self-hosted depends on your infrastructure",
+    "statusPageUrl": "https://novustatus.com",
+    "notes": "Novu cloud is improving reliability. Self-hosted on your own infrastructure gives full control. The project is actively maintained with a large open-source community."
+  },
+  "qualityScore": 7,
+  "qualityJustification": "Best option if open-source and self-hosting are important. The 30k/month free cloud tier is the most generous in the notification infrastructure category. Dashboard UX is improving. Less polished than Knock for complex workflows, but the self-hosting option is a genuine differentiator.",
+  "alternatives": ["knock", "onesignal"],
+  "complementary": ["resend", "twilio", "supabase"],
+  "bestFor": "Multi-channel notification infrastructure with open-source flexibility and self-hosting option for data control",
+  "lastVerified": "2026-02-25",
+  "entryVersion": 1,
+  "addedBy": "claude-code-session-2"
+}

package/src/entries/notifications/onesignal.json

@@ -0,0 +1,84 @@
+{
+  "name": "OneSignal",
+  "slug": "onesignal",
+  "category": "notifications",
+  "subcategory": "push-notifications",
+  "website": "https://onesignal.com",
+  "description": "OneSignal is the most widely used push notification service, supporting web push, iOS, Android, email, and SMS from a single platform. It provides a free tier that is genuinely production-grade, making it the default choice for apps needing multi-channel notification delivery without infrastructure complexity.",
+  "useCases": [
+    {
+      "task": "Send push notifications to mobile app users (iOS and Android)",
+      "fit": "perfect"
+    },
+    {
+      "task": "Send web push notifications to browser users",
+      "fit": "perfect"
+    },
+    {
+      "task": "Send multi-channel notifications (push + email + SMS)",
+      "fit": "perfect"
+    },
+    {
+      "task": "Send targeted notifications based on user segments",
+      "fit": "perfect"
+    }
+  ],
+  "auth": {
+    "method": "api_key",
+    "setupSteps": [
+      "Sign up at onesignal.com",
+      "Create a new app in the dashboard",
+      "Configure your platforms (iOS/Android/Web) with your APNs/FCM credentials",
+      "Go to Settings > Keys & IDs to find your App ID and REST API Key",
+      "Set ONESIGNAL_APP_ID and ONESIGNAL_API_KEY environment variables"
+    ],
+    "envVarName": "ONESIGNAL_API_KEY",
+    "codeSnippet": "// Server-side notification sending\nconst response = await fetch('https://onesignal.com/api/v1/notifications', {\n  method: 'POST',\n  headers: {\n    'Content-Type': 'application/json',\n    'Authorization': `Basic ${process.env.ONESIGNAL_API_KEY}`,\n  },\n  body: JSON.stringify(notification),\n});"
+  },
+  "pricing": {
+    "model": "freemium",
+    "freeTier": "Unlimited subscribers, unlimited notifications, unlimited apps (free plan)",
+    "startingPrice": "$9/month for Growth plan with advanced features",
+    "costPer": "Free plan covers core push notifications; paid plans add segmentation, analytics, A/B testing",
+    "pricingUrl": "https://onesignal.com/pricing"
+  },
+  "rateLimits": {
+    "tier": "free tier",
+    "limit": "No documented notification rate limit; API requests: 2,500 per hour",
+    "notes": "OneSignal batches notifications internally. For large sends, use segments rather than individual API calls.",
+    "retryStrategy": "Implement exponential backoff for 429 and 5xx API responses. OneSignal handles delivery retries internally."
+  },
+  "sdk": {
+    "primaryLanguage": "typescript",
+    "installCommand": "npm install --save-exact @onesignal/node-onesignal",
+    "importStatement": "import * as OneSignal from '@onesignal/node-onesignal';",
+    "otherLanguages": ["python", "ruby", "java", "php", "csharp", "swift", "android"]
+  },
+  "codeExamples": [
+    {
+      "title": "Send a push notification to specific users",
+      "language": "typescript",
+      "code": "import * as OneSignal from '@onesignal/node-onesignal';\n\nconst configuration = OneSignal.createConfiguration({\n  restApiKey: process.env.ONESIGNAL_API_KEY!,\n});\nconst client = new OneSignal.DefaultApi(configuration);\n\nconst notification = new OneSignal.Notification();\nnotification.app_id = process.env.ONESIGNAL_APP_ID!;\nnotification.contents = { en: 'Your order has shipped! Track it now.' };\nnotification.headings = { en: 'Order Update' };\n\n// Send to specific users by external ID\nnotification.include_aliases = {\n  external_id: ['user-123', 'user-456'],\n};\nnotification.target_channel = 'push';\n\nconst response = await client.createNotification(notification);\nconsole.log('Notification ID:', response.id);\nconsole.log('Recipients:', response.recipients);",
+      "notes": "Use external_id to identify users by your own user ID (set when registering devices). This avoids managing OneSignal's player_id internally."
+    }
+  ],
+  "gotchas": [
+    "Setting up push notifications requires configuring APNs certificates (iOS) and FCM keys (Android) in the OneSignal dashboard. This is the most time-consuming part of setup and requires Apple Developer account access.",
+    "Web push notifications require HTTPS. You cannot test web push on localhost — use ngrok, Vercel preview deployments, or a staging environment with HTTPS.",
+    "OneSignal's free plan stores only 90 days of notification history. If you need longer retention for analytics or audit logs, export data regularly or upgrade to a paid plan.",
+    "Device tokens (player IDs) can become stale if users uninstall and reinstall the app. Clean up invalid tokens from your database using OneSignal's device deletion API."
+  ],
+  "reliability": {
+    "uptimeGuarantee": "99.9% uptime SLA on paid plans",
+    "statusPageUrl": "https://status.onesignal.com",
+    "notes": "OneSignal processes billions of notifications per day. Very high reliability with global infrastructure."
+  },
+  "qualityScore": 8,
+  "qualityJustification": "Best push notification service with the most generous free tier in the category — truly unlimited subscribers and notifications at no cost. Multi-channel support (push + email + SMS) from one platform is convenient. Setup complexity for mobile (APNs/FCM) is unavoidable industry-wide.",
+  "alternatives": ["knock", "novu"],
+  "complementary": ["twilio", "resend", "clerk"],
+  "bestFor": "Mobile and web push notifications with an unlimited free tier — ideal for apps that need multi-channel (push + email + SMS) from a single platform",
+  "lastVerified": "2026-02-25",
+  "entryVersion": 1,
+  "addedBy": "claude-code-session-2"
+}

package/src/entries/payments/lemonsqueezy.json

@@ -0,0 +1,91 @@
+{
+  "name": "Lemon Squeezy",
+  "slug": "lemonsqueezy",
+  "category": "payments",
+  "subcategory": "merchant-of-record",
+  "website": "https://lemonsqueezy.com",
+  "description": "Lemon Squeezy is a Merchant of Record platform for selling digital products, software licenses, and SaaS subscriptions. Like Paddle, it handles all tax compliance globally. Designed with a developer-first API and a clean merchant dashboard. Particularly strong for selling one-time digital products (ebooks, templates, plugins) in addition to subscriptions.",
+  "useCases": [
+    {
+      "task": "Sell digital products (ebooks, templates, plugins) with instant delivery",
+      "fit": "perfect"
+    },
+    {
+      "task": "Accept SaaS subscription payments with global tax handling",
+      "fit": "perfect"
+    },
+    {
+      "task": "Generate and manage software license keys",
+      "fit": "good"
+    },
+    {
+      "task": "Set up a simple checkout page without building a custom payment UI",
+      "fit": "good"
+    }
+  ],
+  "auth": {
+    "method": "api_key",
+    "setupSteps": [
+      "Create a Lemon Squeezy account at lemonsqueezy.com",
+      "Verify your account and complete store setup",
+      "Add your store and configure store details",
+      "Create products in your store dashboard",
+      "Go to Settings > API and generate an API key",
+      "Set up webhooks in Settings > Webhooks and copy the signing secret"
+    ],
+    "envVarName": "LEMONSQUEEZY_API_KEY",
+    "codeSnippet": "import { lemonSqueezySetup } from '@lemonsqueezy/lemonsqueezy.js';\n\nlemonSqueezySetup({\n  apiKey: process.env.LEMONSQUEEZY_API_KEY!,\n  onError: (error) => console.error('Lemon Squeezy error:', error),\n});"
+  },
+  "pricing": {
+    "model": "usage_based",
+    "freeTier": null,
+    "startingPrice": "5% + $0.50 per transaction (Starter)",
+    "costPer": "5% + $0.50 per transaction; Enterprise plans negotiated for high volume",
+    "pricingUrl": "https://www.lemonsqueezy.com/pricing"
+  },
+  "rateLimits": {
+    "tier": "standard",
+    "limit": "120 API requests/minute",
+    "notes": "Webhooks delivered at least once with retry on failure. Event IDs should be used for idempotency.",
+    "retryStrategy": "Use the event_id from webhook payload as idempotency key. Return HTTP 200 immediately and process async."
+  },
+  "sdk": {
+    "primaryLanguage": "typescript",
+    "installCommand": "npm install --save-exact @lemonsqueezy/lemonsqueezy.js",
+    "importStatement": "import { lemonSqueezySetup, getProducts, createCheckout } from '@lemonsqueezy/lemonsqueezy.js';",
+    "otherLanguages": ["php", "python"]
+  },
+  "codeExamples": [
+    {
+      "title": "Create a checkout session",
+      "language": "typescript",
+      "code": "import { lemonSqueezySetup, createCheckout } from '@lemonsqueezy/lemonsqueezy.js';\n\nlemonSqueezySetup({\n  apiKey: process.env.LEMONSQUEEZY_API_KEY!,\n});\n\n// Create a checkout for a specific variant\nconst { data, error } = await createCheckout(\n  process.env.LEMONSQUEEZY_STORE_ID!, // Your store ID\n  process.env.LEMONSQUEEZY_VARIANT_ID!, // The product variant ID\n  {\n    checkoutOptions: {\n      embed: false,\n      media: true,\n      logo: true,\n    },\n    checkoutData: {\n      email: 'customer@example.com', // Pre-fill customer email\n      custom: {\n        userId: 'user_123', // Pass through to webhooks\n      },\n    },\n    productOptions: {\n      redirectUrl: 'https://yourapp.com/success',\n      receiptButtonText: 'Go to Dashboard',\n      receiptThankYouNote: 'Thank you for subscribing!',\n    },\n  }\n);\n\nif (error) {\n  console.error('Failed to create checkout:', error);\n  throw new Error(error.title);\n}\n\nconst checkoutUrl = data?.data.attributes.url;\nconsole.log('Checkout URL:', checkoutUrl);\n// Redirect user to checkoutUrl",
+      "notes": "Lemon Squeezy checkout URLs are single-use and expire after 24 hours. Always generate a fresh checkout URL per customer session. Pass custom data (like userId) in checkoutData.custom — it will be available in webhook payloads."
+    },
+    {
+      "title": "Verify and handle webhook",
+      "language": "typescript",
+      "code": "import crypto from 'crypto';\nimport type { Request, Response } from 'express';\n\ninterface LemonSqueezyWebhookPayload {\n  meta: {\n    event_name: string;\n    custom_data?: Record<string, string>;\n  };\n  data: {\n    id: string;\n    attributes: Record<string, unknown>;\n  };\n}\n\nexport async function handleLemonSqueezyWebhook(req: Request, res: Response) {\n  const rawBody = req.body as string; // Must be raw string before JSON parse\n  const signature = req.headers['x-signature'] as string;\n\n  // Verify HMAC-SHA256 signature\n  const hmac = crypto.createHmac('sha256', process.env.LEMONSQUEEZY_WEBHOOK_SECRET!);\n  const digest = hmac.update(rawBody).digest('hex');\n\n  if (!crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature))) {\n    console.error('Invalid webhook signature');\n    return res.status(401).send('Invalid signature');\n  }\n\n  const payload = JSON.parse(rawBody) as LemonSqueezyWebhookPayload;\n  const eventName = payload.meta.event_name;\n  const eventId = payload.data.id; // Use as idempotency key\n  const customData = payload.meta.custom_data;\n\n  switch (eventName) {\n    case 'order_created': {\n      const order = payload.data.attributes;\n      console.log('New order:', eventId, 'status:', order['status']);\n      // Deliver digital product or provision access\n      if (order['status'] === 'paid') {\n        await deliverProduct(customData?.userId, eventId);\n      }\n      break;\n    }\n    case 'subscription_created': {\n      const subscription = payload.data.attributes;\n      console.log('New subscription:', eventId, 'status:', subscription['status']);\n      await provisionSubscription(customData?.userId, payload.data.id);\n      break;\n    }\n    case 'subscription_cancelled': {\n      console.log('Subscription cancelled:', eventId);\n      await scheduleAccessRevocation(customData?.userId);\n      break;\n    }\n    default:\n      console.log('Unhandled event:', eventName);\n  }\n\n  return res.status(200).json({ received: true, eventId });\n}\n\nasync function deliverProduct(userId: string | undefined, orderId: string) {\n  // Your product delivery logic here\n}\n\nasync function provisionSubscription(userId: string | undefined, subscriptionId: string) {\n  // Your subscription provisioning logic here\n}\n\nasync function scheduleAccessRevocation(userId: string | undefined) {\n  // Your access revocation logic here\n}",
+      "notes": "Lemon Squeezy uses HMAC-SHA256 for webhook signature verification — use crypto.timingSafeEqual() to prevent timing attacks. The raw body must be used for signature verification before parsing as JSON. Use payload.data.id as an idempotency key."
+    }
+  ],
+  "gotchas": [
+    "Lemon Squeezy is newer and smaller than Paddle or Stripe. In 2024, Stripe acquired Lemon Squeezy. While this is broadly positive for stability, the roadmap may change and some features may eventually be consolidated into Stripe's MoR offerings.",
+    "Like Paddle, Lemon Squeezy is the Merchant of Record — your company name does NOT appear on bank statements. Some B2B customers require invoices from the actual vendor and may push back on the MoR model for procurement.",
+    "Lemon Squeezy's API rate limit (120 requests/minute) is lower than Paddle's. If you have bulk operations (syncing subscribers, updating prices across many products), implement request queuing and exponential backoff.",
+    "License key generation is a powerful feature but must be explicitly enabled per product and configured with a key pattern. Keys are not automatically generated for subscriptions — only for products with license keys enabled."
+  ],
+  "reliability": {
+    "uptimeGuarantee": "99.9% uptime (no published SLA)",
+    "statusPageUrl": "https://lemonsqueezy.statuspage.io",
+    "notes": "Stripe-backed infrastructure after 2024 acquisition. Handles PCI DSS compliance and tax remittance as Merchant of Record globally."
+  },
+  "qualityScore": 7,
+  "qualityJustification": "Excellent developer experience for selling digital products and licenses. Cleaner UI than Paddle, good API documentation. Acquisition by Stripe in 2024 provides stability but also introduces uncertainty about long-term direction. Scores below Paddle for market maturity and enterprise readiness.",
+  "alternatives": ["paddle", "stripe"],
+  "complementary": ["resend", "clerk", "supabase"],
+  "bestFor": "Selling digital products, software licenses, and SaaS subscriptions without managing tax compliance — particularly strong for individual creators and small teams",
+  "lastVerified": "2026-02-25",
+  "entryVersion": 1,
+  "addedBy": "claude-code-session-4"
+}

package/src/entries/payments/paddle.json

@@ -0,0 +1,90 @@
+{
+  "name": "Paddle",
+  "slug": "paddle",
+  "category": "payments",
+  "subcategory": "merchant-of-record",
+  "website": "https://paddle.com",
+  "description": "Paddle is a Merchant of Record (MoR) that handles payments, subscriptions, global tax compliance (VAT, GST, sales tax), and fraud detection for SaaS businesses. You sell through Paddle — they handle the tax liability, meaning you never have to register for VAT in individual countries. Ideal for indie developers and SaaS companies selling globally without a dedicated finance team.",
+  "useCases": [
+    {
+      "task": "Accept SaaS subscription payments globally without handling tax compliance",
+      "fit": "perfect"
+    },
+    {
+      "task": "Sell a software product to international customers with automatic VAT/GST",
+      "fit": "perfect"
+    },
+    {
+      "task": "Manage subscription upgrades, downgrades, and trials",
+      "fit": "good"
+    },
+    {
+      "task": "Process one-time payments for digital products",
+      "fit": "good"
+    }
+  ],
+  "auth": {
+    "method": "api_key",
+    "setupSteps": [
+      "Register a Paddle account at paddle.com",
+      "Verify your business details and get approved as a Paddle seller",
+      "Add your products and prices in the Paddle Dashboard",
+      "Go to Developer Tools > Authentication and generate your API key",
+      "Configure webhooks in Developer Tools > Notifications and copy the webhook secret"
+    ],
+    "envVarName": "PADDLE_API_KEY",
+    "codeSnippet": "import { Paddle, Environment } from '@paddle/paddle-node-sdk';\n\nconst paddle = new Paddle(process.env.PADDLE_API_KEY!, {\n  environment: Environment.Sandbox, // Use Environment.Production for live\n});"
+  },
+  "pricing": {
+    "model": "usage_based",
+    "freeTier": null,
+    "startingPrice": "5% + $0.50 per transaction (Starter)",
+    "costPer": "5% + $0.50/transaction up to $10K MRR; custom rates above $50K MRR",
+    "pricingUrl": "https://paddle.com/pricing/"
+  },
+  "rateLimits": {
+    "tier": "standard",
+    "limit": "200 API requests/minute",
+    "notes": "Webhook events are delivered at least once — implement idempotency keys to handle duplicates. Paddle retries failed webhooks for up to 72 hours.",
+    "retryStrategy": "Implement webhook idempotency using the event ID. Return 200 quickly; process async."
+  },
+  "sdk": {
+    "primaryLanguage": "typescript",
+    "installCommand": "npm install --save-exact @paddle/paddle-node-sdk",
+    "importStatement": "import { Paddle, Environment } from '@paddle/paddle-node-sdk';",
+    "otherLanguages": ["python", "php", "ruby"]
+  },
+  "codeExamples": [
+    {
+      "title": "Create a subscription checkout link",
+      "language": "typescript",
+      "code": "import { Paddle, Environment } from '@paddle/paddle-node-sdk';\n\nconst paddle = new Paddle(process.env.PADDLE_API_KEY!, {\n  environment: Environment.Sandbox,\n});\n\n// Create a transaction (checkout) for a subscription price\nconst transaction = await paddle.transactions.create({\n  items: [\n    {\n      priceId: 'pri_01h1234abcde', // Your Paddle price ID\n      quantity: 1,\n    },\n  ],\n  customData: {\n    userId: 'user_123',\n    planName: 'pro',\n  },\n  checkoutSettings: {\n    successUrl: 'https://yourapp.com/success',\n  },\n});\n\n// Redirect user to checkout\nconst checkoutUrl = transaction.checkout?.url;\nconsole.log('Checkout URL:', checkoutUrl);",
+      "notes": "Paddle generates a hosted checkout page — redirect the user to transaction.checkout.url. You do not need to build your own payment form. Paddle's overlay checkout can also be embedded on your page using Paddle.js."
+    },
+    {
+      "title": "Handle Paddle webhook events",
+      "language": "typescript",
+      "code": "import { Paddle, Environment } from '@paddle/paddle-node-sdk';\nimport type { Request, Response } from 'express';\n\nconst paddle = new Paddle(process.env.PADDLE_API_KEY!, {\n  environment: Environment.Sandbox,\n});\n\nexport async function handlePaddleWebhook(req: Request, res: Response) {\n  const signature = req.headers['paddle-signature'] as string;\n  const rawBody = req.body as string; // Must be raw string, not parsed JSON\n\n  let event;\n  try {\n    event = paddle.webhooks.unmarshal(\n      rawBody,\n      process.env.PADDLE_WEBHOOK_SECRET!,\n      signature\n    );\n  } catch (err) {\n    console.error('Webhook signature verification failed:', err);\n    return res.status(400).send('Invalid signature');\n  }\n\n  // Use event.eventId as idempotency key to avoid double-processing\n  const eventId = event.eventId;\n\n  switch (event.eventType) {\n    case 'subscription.created': {\n      const subscription = event.data;\n      console.log('New subscription:', subscription.id, 'customer:', subscription.customerId);\n      // Provision access for the customer\n      await provisionSubscription(subscription.customerId, subscription.id);\n      break;\n    }\n    case 'transaction.completed': {\n      const transaction = event.data;\n      console.log('Payment succeeded:', transaction.id, 'total:', transaction.details?.totals?.total);\n      // Update payment records\n      await recordPayment(transaction.id, transaction.customerId);\n      break;\n    }\n    case 'subscription.canceled': {\n      const subscription = event.data;\n      console.log('Subscription canceled:', subscription.id);\n      // Revoke access at period end\n      await scheduleAccessRevocation(subscription.customerId, subscription.scheduledChange?.effectiveAt);\n      break;\n    }\n    default:\n      console.log('Unhandled event type:', event.eventType);\n  }\n\n  // Always return 200 immediately\n  return res.status(200).json({ received: true, eventId });\n}\n\nasync function provisionSubscription(customerId: string, subscriptionId: string) {\n  // Your provisioning logic here\n}\n\nasync function recordPayment(transactionId: string, customerId: string) {\n  // Your payment recording logic here\n}\n\nasync function scheduleAccessRevocation(customerId: string, effectiveAt?: string) {\n  // Your access revocation logic here\n}",
+      "notes": "Paddle webhooks must be verified using paddle.webhooks.unmarshal(). Pass the raw request body as a string — do not parse it as JSON before verification. Use the eventId as an idempotency key to safely handle Paddle's at-least-once delivery."
+    }
+  ],
+  "gotchas": [
+    "Paddle is the Merchant of Record — customers see 'Paddle' on their bank statement, not your company name. Some customers may be confused by this and initiate chargebacks thinking it's a fraudulent charge. Add a note to your receipt emails explaining this.",
+    "Paddle's Merchant of Record model means you CANNOT easily migrate your subscriber base to another payment processor. All subscription data (customer, payment method, billing history) is locked in Paddle. Plan your stack accordingly before onboarding thousands of subscribers.",
+    "Paddle's 5% fee applies to every transaction including renewals. At scale, this becomes expensive compared to Stripe (2.9% + $0.30) — especially for low-ticket, high-volume subscriptions. Calculate the break-even point for your price point.",
+    "Paddle's sandbox environment uses different API keys than production. Test mode and live mode are completely separate — you cannot transfer products, prices, or customer data between them."
+  ],
+  "reliability": {
+    "uptimeGuarantee": "99.9% uptime SLA",
+    "statusPageUrl": "https://paddle.statuspage.io",
+    "notes": "Globally distributed payment infrastructure with automatic failover. Paddle handles PCI DSS compliance on your behalf as Merchant of Record."
+  },
+  "qualityScore": 8,
+  "qualityJustification": "Best choice for indie hackers and small SaaS teams that want to sell globally without a finance/legal team. Handles VAT, GST, and sales tax automatically as Merchant of Record. SDK quality is good; dashboard is polished. Transaction fee (5%) is higher than Stripe but includes tax handling that would otherwise require a separate service like TaxJar.",
+  "alternatives": ["lemonsqueezy", "stripe"],
+  "complementary": ["stripe", "resend", "clerk", "supabase"],
+  "bestFor": "Selling SaaS subscriptions and digital products globally without managing tax compliance — Paddle acts as the legal seller in each country",
+  "lastVerified": "2026-02-25",
+  "entryVersion": 1,
+  "addedBy": "claude-code-session-4"
+}