@dodopayments/nuxt 0.1.0 → 0.1.2

package/README.md

@@ -1,75 +1,315 @@
-# Nuxt Minimal Starter
+# `@dodopayments/nuxt`
 
-Look at the [Nuxt documentation](https://nuxt.com/docs/getting-started/introduction) to learn more.
+A Nuxt module that provides composables and server routes for integrating Dodo Payments Checkout, Customer Portal, and Webhook functionalities into your Nuxt application.
 
-## Setup
+> **AI Agent Integration Guide:** See the AI Agent Prompt section below for detailed instructions and guidance for AI assistants.
 
-Make sure to install dependencies:
+## Documentation
+
+Detailed documentation can be found at [Dodo Payments Nuxt adaptor](https://docs.dodopayments.com/developer-resources/nuxt-adaptor)
+
+## Installation
+
+You can install this package via npm or any other package manager of your choice:
 
 ```bash
-# npm
-npm install
+npm install @dodopayments/nuxt
+```
+
+## Quick Start
 
-# pnpm
-pnpm install
+### 1. Register the Module
 
-# yarn
-yarn install
+Add `@dodopayments/nuxt` to your `nuxt.config.ts`:
 
-# bun
-bun install
+```ts
+export default defineNuxtConfig({
+  modules: ["@dodopayments/nuxt"],
+  devtools: { enabled: true },
+  compatibilityDate: "2025-02-25",
+  runtimeConfig: {
+    private: {
+      bearerToken: process.env.NUXT_PRIVATE_BEARER_TOKEN,
+      webhookKey: process.env.NUXT_PRIVATE_BEARER_TOKEN,
+      environment: process.env.NUXT_PRIVATE_ENVIRONMENT,
+      returnUrl: process.env.NUXT_PRIVATE_RETURNURL
+    },
+  }
+});
 ```
 
-## Development Server
+### 2. Checkout API Route
 
-Start the development server on `http://localhost:3000`:
+Create a new file at `server/routes/api/checkout.get.ts`:
 
-```bash
-# npm
-npm run dev
+```ts
+export default defineEventHandler((event) => {
+  const {
+    private: { bearerToken, environment, returnUrl },
+  } = useRuntimeConfig();
+  
+  const handler = checkoutHandler({
+    bearerToken: bearerToken,
+    environment: env,
+    returnUrl: returnUrl
+  });
+
+  return handler(event);
+});
+```
+
+- Accepts GET requests with `productId` as a query parameter.
 
-# pnpm
-pnpm dev
 
-# yarn
-yarn dev
+### 3. Customer Portal API Route
 
-# bun
-bun run dev
+Create a new file at `server/routes/api/customer-portal.get.ts`:
+
+```ts
+export default defineEventHandler((event) => {
+  const {
+    private: { bearerToken, environment }
+  } = useRuntimeConfig()
+
+  const handler = customerPortalHandler({
+    bearerToken,
+    environment: environment,
+  })
+
+  return handler(event)
+})
 ```
 
-## Production
+- Accepts GET requests with `customer_id` as a query parameter.
+- Returns 400 if `customer_id` is missing.
 
-Build the application for production:
+### 4. Webhook API Route
 
-```bash
-# npm
-npm run build
+Create a new file at `server/routes/api/webhook.post.ts`:
 
-# pnpm
-pnpm build
+```ts
+export default defineEventHandler((event) => {
+    const {
+        private: { webhookKey }
+    } = useRuntimeConfig()
 
-# yarn
-yarn build
+    const handler = Webhooks({
+        webhookKey: webhookKey,
+        onPayload: async (payload: any) => {
+            // Handle here
+        }
+    })
+
+    return handler(event)
+})
 
-# bun
-bun run build
 ```
 
-Locally preview production build:
+- Only POST requests are supported. Signature is verified using `webhookSecret`.
 
-```bash
-# npm
-npm run preview
+## Environment Variable Setup
 
-# pnpm
-pnpm preview
+Set the following environment variables in your Nuxt project's deployment environment:
 
-# yarn
-yarn preview
+```
+NUXT_PRIVATE_BEARER_TOKEN="""
+NUXT_PRIVATE_ENVIRONMENT=""
+NUXT_PRIVATE_WEBHOOK_KEY=""
+NUXT_PRIVATE_RETURN_URL=""
+```
+
+- `NUXT_PRIVATE_BEARER_TOKEN`: Your Dodo Payments API Key (required for Checkout and Customer Portal).
+- `NUXT_PRIVATE_WEBHOOK_KEY`: Your Dodo Payments Webhook Secret (required for Webhook handler).
+- `NUXT_PRIVATE_ENVIRONMENT`
+- `NUXT_PRIVATE_RETURN_URL`: (Optional) The URL to redirect to after a successful checkout.
+
+**Important:** Never commit sensitive environment variables to version control.
+
+---
+
+
+## Prompt for LLM
 
-# bun
-bun run preview
 ```
+You are an expert Nuxt developer assistant. Your task is to guide a user through integrating the @dodopayments/nuxt module into their existing Nuxt project.
+
+The @dodopayments/nuxt module provides API route handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed for Nuxt 3 server routes.
+
+First, install the necessary package:
+
+npm install @dodopayments/nuxt
+
+Second, add the configuration to nuxt.config.ts
+
+export default defineNuxtConfig({
+  modules: ["@dodopayments/nuxt"],
+  devtools: { enabled: true },
+  compatibilityDate: "2025-02-25",
+  runtimeConfig: {
+    private: {
+      bearerToken: process.env.NUXT_PRIVATE_BEARER_TOKEN,
+      webhookKey: process.env.NUXT_PRIVATE_BEARER_TOKEN,
+      environment: process.env.NUXT_PRIVATE_ENVIRONMENT,
+      returnUrl: process.env.NUXT_PRIVATE_RETURNURL
+    },
+  }
+});
+
+
+Here's how you should structure your response:
+
+    Ask the user which functionalities they want to integrate.
+
+"Which parts of the @dodopayments/nuxt module would you like to integrate into your project? You can choose one or more of the following:
+
+    Checkout API Route (for handling product checkouts)
+    Customer Portal API Route (for managing customer subscriptions/details)
+    Webhook API Route (for receiving Dodo Payments webhook events)
+    All (integrate all three)"
+
+    Based on the user's selection, provide detailed integration steps for each chosen functionality.
+
+If Checkout API Route is selected:
+
+Purpose: This route redirects users to the Dodo Payments checkout page.
+File Creation: Create a new file at server/routes/api/checkout.get.ts in your Nuxt project.
+
+Code Snippet:
+
+// server/routes/api/checkout.get.ts
+
+export default defineEventHandler((event) => {
+  const {
+    private: { bearerToken, environment, returnUrl },
+  } = useRuntimeConfig();
+
+  const handler = checkoutHandler({
+    bearerToken: bearerToken,
+    environment: environment,
+    returnUrl: returnUrl,
+  });
+
+  return handler(event);
+});
+
+Configuration & Usage:
+- bearerToken: Your Dodo Payments API key. Set via the NUXT_PRIVATE_BEARER_TOKEN environment variable.
+- returnUrl: (Optional) The URL to redirect the user to after a successful checkout.
+- environment: (Optional) Set to your environment (e.g., "test_mode" or "live_mode").
+
+Static Checkout (GET) Query Parameters:
+- productId (required): Product identifier (e.g., ?productId=pdt_nZuwz45WAs64n3l07zpQR)
+- quantity (optional): Quantity of the product
+- Customer Fields (optional): fullName, firstName, lastName, email, country, addressLine, city, state, zipCode
+- Disable Flags (optional, set to true to disable): disableFullName, disableFirstName, disableLastName, disableEmail, disableCountry, disableAddressLine, disableCity, disableState, disableZipCode
+- Advanced Controls (optional): paymentCurrency, showCurrencySelector, paymentAmount, showDiscounts
+- Metadata (optional): Any query parameter starting with metadata_ (e.g., ?metadata_userId=abc123)
+
+Dynamic Checkout (POST): Parameters are sent as a JSON body. Supports both one-time and recurring payments. For a complete list of supported POST body fields, refer to:
+- Docs - One Time Payment Product: https://docs.dodopayments.com/api-reference/payments/post-payments
+- Docs - Subscription Product: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions
+
+Error Handling: If productId is missing or other query parameters are invalid, the handler will return a 400 response.
+
+If Customer Portal API Route is selected:
+
+Purpose: This route allows customers to access their Dodo Payments customer portal.
+File Creation: Create a new file at server/routes/api/customer-portal.get.ts in your Nuxt project.
+
+Code Snippet:
+
+// server/routes/api/customer-portal.get.ts
+
+export default defineEventHandler((event) => {
+  const {
+    private: { bearerToken, environment },
+  } = useRuntimeConfig();
+
+  const handler = customerPortalHandler({
+    bearerToken,
+    environment: environment,
+  });
+
+  return handler(event);
+});
+
+Query Parameters:
+- customer_id (required): The customer ID for the portal session (e.g., ?customer_id=cus_123)
+- send_email (optional, boolean): If set to true, sends an email to the customer with the portal link.
+- Returns 400 if customer_id is missing.
+
+If Webhook API Route is selected:
+
+Purpose: This route processes incoming webhook events from Dodo Payments, allowing your application to react to events like successful payments, refunds, or subscription changes.
+File Creation: Create a new file at server/routes/api/webhook.post.ts in your Nuxt project.
+
+Code Snippet:
+
+// server/routes/api/webhook.post.ts
+
+export default defineEventHandler((event) => {
+  const {
+    private: { webhookKey },
+  } = useRuntimeConfig();
+
+  const handler = Webhooks({
+    webhookKey: webhookKey,
+    onPayload: async (payload) => {
+      // handle the payload
+    },
+    // ... other event handlers for granular control
+  });
+
+  return handler(event);
+});
+
+Handler Details:
+- Method: Only POST requests are supported. Other methods return 405.
+- Signature Verification: The handler verifies the webhook signature using webhookKey and returns 401 if verification fails.
+- Payload Validation: The payload is validated with Zod. Returns 400 for invalid payloads.
+
+Error Handling:
+- 401: Invalid signature
+- 400: Invalid payload
+- 500: Internal error during verification
+
+Event Routing: Calls the appropriate event handler based on the payload type. Supported event handlers include:
+- onPayload?: (payload: WebhookPayload) => Promise<void>
+- onPaymentSucceeded?: (payload: WebhookPayload) => Promise<void>
+- onPaymentFailed?: (payload: WebhookPayload) => Promise<void>
+- onPaymentProcessing?: (payload: WebhookPayload) => Promise<void>
+- onPaymentCancelled?: (payload: WebhookPayload) => Promise<void>
+- onRefundSucceeded?: (payload: WebhookPayload) => Promise<void>
+- onRefundFailed?: (payload: WebhookPayload) => Promise<void>
+- onDisputeOpened?: (payload: WebhookPayload) => Promise<void>
+- onDisputeExpired?: (payload: WebhookPayload) => Promise<void>
+- onDisputeAccepted?: (payload: WebhookPayload) => Promise<void>
+- onDisputeCancelled?: (payload: WebhookPayload) => Promise<void>
+- onDisputeChallenged?: (payload: WebhookPayload) => Promise<void>
+- onDisputeWon?: (payload: WebhookPayload) => Promise<void>
+- onDisputeLost?: (payload: WebhookPayload) => Promise<void>
+- onSubscriptionActive?: (payload: WebhookPayload) => Promise<void>
+- onSubscriptionOnHold?: (payload: WebhookPayload) => Promise<void>
+- onSubscriptionRenewed?: (payload: WebhookPayload) => Promise<void>
+- onSubscriptionPaused?: (payload: WebhookPayload) => Promise<void>
+- onSubscriptionPlanChanged?: (payload: WebhookPayload) => Promise<void>
+- onSubscriptionCancelled?: (payload: WebhookPayload) => Promise<void>
+- onSubscriptionFailed?: (payload: WebhookPayload) => Promise<void>
+- onSubscriptionExpired?: (payload: WebhookPayload) => Promise<void>
+- onLicenseKeyCreated?: (payload: WebhookPayload) => Promise<void>
+
+Environment Variable Setup:
+To ensure the module functions correctly, set up the following environment variables in your Nuxt project's deployment environment (e.g., Vercel, Netlify, AWS, etc.):
+- NUXT_PRIVATE_BEARER_TOKEN: Your Dodo Payments API Key (required for Checkout and Customer Portal).
+- NUXT_PRIVATE_WEBHOOK_KEY: Your Dodo Payments Webhook Secret (required for Webhook handler).
+- NUXT_PRIVATE_ENVIRONMENT: (Optional) Set to your environment (e.g., "test_mode" or "live_mode").
+- NUXT_PRIVATE_RETURNURL: (Optional) The URL to redirect to after a successful checkout (for Checkout handler).
+
+Usage in your code:
+bearerToken: useRuntimeConfig().private.bearerToken
+webhookKey: useRuntimeConfig().private.webhookKey
+
+Important: Never commit sensitive environment variables directly into your version control. Use environment variables for all sensitive information.
 
-Check out the [deployment documentation](https://nuxt.com/docs/getting-started/deployment) for more information.
+If the user needs assistance setting up environment variables for their specific deployment environment, ask them what platform they are using (e.g., Vercel, Netlify, AWS, etc.), and provide guidance.
+```

package/dist/module.json

@@ -1,7 +1,7 @@
 {
   "name": "@dodopayments/nuxt",
   "configKey": "dodopayments",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "builder": {
     "@nuxt/module-builder": "1.0.1",
     "unbuild": "3.5.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dodopayments/nuxt",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Dodo Payments Nuxt integration",
   "type": "module",
   "publishConfig": {
@@ -39,7 +39,6 @@
   },
   "keywords": [
     "payments",
-    "dodo",
     "nuxt",
     "webhooks",
     "checkout",