@dodopayments/convex 0.1.0 → 0.2.0

package/README.md

@@ -1,10 +1,16 @@
-# `@dodopayments/convex`
+# Dodo Payments Convex Component
 
-A TypeScript library that provides a Convex component for seamless integration of Dodo Payments into your Convex applications.
+[![npm version](https://badge.fury.io/js/@dodopayments%2Fconvex.svg)](https://badge.fury.io/js/@dodopayments%2Fconvex.svg)
 
-> **AI Agent Integration Guide:** See the AI Agent Prompt section below for detailed instructions and guidance for AI assistants.
+This component is the official way to integrate the Dodo Payments in your Convex project.
 
-## Documentation
+Features:
+
+- Checkout Session: Integrate Dodo Payments Checkout with a couple of lines code.
+
+- Customer Portal: Allow customers to manage subscriptions and details
+
+- Webhooks: Handle webhooks efficiently. Just write your business logic and handle the events you want. Webhook verification is taken care by us
 
 Detailed documentation can be found at [Dodo Payments Convex Component](https://docs.dodopayments.com/developer-resources/convex-component)
 
@@ -16,6 +22,7 @@ npm install @dodopayments/convex
 
 ## Quick Start
 
+
 ### 1. Add Component to Convex Config
 
 ```typescript
@@ -30,8 +37,15 @@ export default app;
 
 ### 2. Set Up Environment Variables
 
+Create a [Dodo Payments](https://dodopayments.com) account and get the API_KEY and WEBHOOK_SECRET
+
 Add your environment variables in the Convex dashboard (**Settings** → **Environment Variables**). You can open the dashboard by running:
 
+```env
+DODO_PAYMENTS_API_KEY=your-dodo-payments-api-key
+DODO_PAYMENTS_ENVIRONMENT=test_mode
+DODO_PAYMENTS_WEBHOOK_SECRET=your-webhook-secret (if using webhooks)
+```
 ```sh
 npx convex dashboard
 ```
@@ -44,37 +58,57 @@ Set the following variables:
 
 > **Note:** Convex backend functions only read environment variables set in the Convex dashboard. `.env` files are ignored. Always set secrets in the Convex dashboard for both production and development.
 
-### 3. Create Payment Functions
+### 3. Create Internal Query
+
+First, create an internal query to fetch users from your database. This will be used in the payment functions to identify customers.
+
+```typescript
+// convex/users.ts
+import { internalQuery } from "./_generated/server";
+import { v } from "convex/values";
+
+// Internal query to fetch user by auth ID
+export const getByAuthId = internalQuery({
+  args: { authId: v.string() },
+  handler: async (ctx, { authId }) => {
+    return await ctx.db
+      .query("users")
+      .withIndex("by_auth_id", (q) => q.eq("authId", authId))
+      .first();
+  },
+});
+```
+
+### 4. Create Payment Functions
 
 ```typescript
 // convex/dodo.ts
 import { DodoPayments } from "@dodopayments/convex";
 import { components } from "./_generated/api";
+import { internal } from "./_generated/api";
 
 export const dodo = new DodoPayments(components.dodopayments, {
   // This function maps your Convex user to a Dodo Payments customer
-  // Customize it based on your authentication provider and/or user database
+  // Customize it based on your authentication provider and user database
+
   identify: async (ctx) => {
     const identity = await ctx.auth.getUserIdentity();
     if (!identity) {
       return null; // User is not logged in
     }
     
-    // Lookup user from your database
-    const user = await ctx.db.query("users")
-       .withIndex("by_auth_id", (q) => q.eq("authId", identity.subject))
-       .first();
-     if (!user) {
-       return null; // User not found in database
-     }
-     
-     return {
-       dodoCustomerId: user.dodoCustomerId, // Use stored dodoCustomerId
-       customerData: {
-         name: user.name,
-         email: user.email,
-       },
-     };
+    // Use ctx.runQuery() to lookup user from your database
+    const user = await ctx.runQuery(internal.users.getByAuthId, {
+      authId: identity.subject,
+    });
+    
+    if (!user) {
+      return null; // User not found in database
+    }
+    
+    return {
+      dodoCustomerId: user.dodoCustomerId, // Replace user.dodoCustomerId with your field storing Dodo Payments customer ID
+    };
   },
   apiKey: process.env.DODO_PAYMENTS_API_KEY!,
   environment: process.env.DODO_PAYMENTS_ENVIRONMENT as "test_mode" | "live_mode",
@@ -84,7 +118,7 @@ export const dodo = new DodoPayments(components.dodopayments, {
 export const { checkout, customerPortal } = dodo.api();
 ```
 
-### 4. Set Up Webhooks (Optional)
+### 5. Set Up Webhooks (Optional)
 
 For handling Dodo Payments webhooks, create a file `convex/http.ts`:
 
@@ -92,6 +126,7 @@ For handling Dodo Payments webhooks, create a file `convex/http.ts`:
 // convex/http.ts
 import { httpRouter } from "convex/server";
 import { createDodoWebhookHandler } from "@dodopayments/convex";
+import { internal } from "./_generated/api";
 
 const http = httpRouter();
 
@@ -99,13 +134,24 @@ http.route({
   path: "/dodopayments-webhook",
   method: "POST",
   handler: createDodoWebhookHandler({
-    onPaymentSucceeded: async (payload) => {
-      console.log("Payment succeeded:", payload.data.payment_id);
-      // Add your logic here to handle the successful payment
+    onPaymentSucceeded: async (ctx, payload) => {
+      console.log("Payment succeeded:", payload.data.payment_id);  
+      // Update order status in your database
+      await ctx.runMutation(internal.orders.markAsPaid, {
+        orderId: payload.data.metadata.orderId,
+        paymentId: payload.data.payment_id,
+        amount: payload.data.amount,
+      });
     },
-    onSubscriptionActive: async (payload) => {
+    
+    onSubscriptionActive: async (ctx, payload) => {
       console.log("Subscription activated:", payload.data.subscription_id);
-      // Add your logic here
+      // Create or update subscription record in your database
+      await ctx.runMutation(internal.subscriptions.createOrUpdate, {
+        subscriptionId: payload.data.subscription_id,
+        customerId: payload.data.customer_id,
+        status: "active",
+      });
     },
     // Add other event handlers as needed
   }),
@@ -114,11 +160,13 @@ http.route({
 export default http;
 ```
 
+**Important:** All webhook handlers receive the Convex `ActionCtx` as the first parameter, allowing you to use `ctx.runQuery()` and `ctx.runMutation()` to interact with your database.
+
 Add your webhook secret in the Convex dashboard (**Settings** → **Environment Variables**):
 
 - `DODO_PAYMENTS_WEBHOOK_SECRET=your-webhook-secret`
 
-### 5. Define Payment Actions
+### 6. Define Payment Actions
 
 ```typescript
 // convex/payments.ts
@@ -149,7 +197,7 @@ export const createCheckout = action({
 });
 ```
 
-### 6. Frontend Usage
+### 7. Frontend Usage
 
 ```tsx
 import { useAction } from "convex/react";
@@ -220,44 +268,51 @@ Then add the required environment variables (e.g., DODO_PAYMENTS_API_KEY, DODO_P
 DODO_PAYMENTS_API_KEY=your-api-key
 DODO_PAYMENTS_ENVIRONMENT=test_mode
 
-Step 3: Create your payment functions file.
+Step 3: Create an internal query to fetch users from your database.
+
+// convex/users.ts
+import { internalQuery } from "./_generated/server";
+import { v } from "convex/values";
+
+// Internal query to fetch user by auth ID
+export const getByAuthId = internalQuery({
+  args: { authId: v.string() },
+  handler: async (ctx, { authId }) => {
+    return await ctx.db
+      .query("users")
+      .withIndex("by_auth_id", (q) => q.eq("authId", authId))
+      .first();
+  },
+});
+
+Step 4: Create your payment functions file.
 
 // convex/dodo.ts
 import { DodoPayments } from "@dodopayments/convex";
 import { components } from "./_generated/api";
+import { internal } from "./_generated/api";
 
 export const dodo = new DodoPayments(components.dodopayments, {
   // This function maps your Convex user to a Dodo Payments customer
-  // Customize it based on your authentication provider
+  // Customize it based on your authentication provider and user database
+
   identify: async (ctx) => {
     const identity = await ctx.auth.getUserIdentity();
     if (!identity) {
       return null; // User is not logged in
     }
     
-    // Option 1: Use identity data directly
-    return {
-      dodoCustomerId: identity.subject, // Use a stable identifier for the customer ID
-      customerData: { // Optional: additional customer information
-        name: identity.name,
-        email: identity.email,
-      },
-    };
+    // Use ctx.runQuery() to lookup user from your database
+    const user = await ctx.runQuery(internal.users.getByAuthId, {
+      authId: identity.subject,
+    });
     
-    // Lookup user from your database
-    const user = await ctx.db.query("users")
-      .withIndex("by_auth_id", (q) => q.eq("authId", identity.subject))
-      .first();
     if (!user) {
       return null; // User not found in database
     }
-
+    
     return {
-      dodoCustomerId: user.dodoCustomerId, // Use stored dodoCustomerId
-      customerData: {
-        name: user.name,
-        email: user.email,
-      },
+      dodoCustomerId: user.dodoCustomerId, // Replace user.dodoCustomerId with your field storing Dodo Payments customer ID
     };
   },
   apiKey: process.env.DODO_PAYMENTS_API_KEY!,
@@ -267,7 +322,7 @@ export const dodo = new DodoPayments(components.dodopayments, {
 // Export the API methods for use in your app
 export const { checkout, customerPortal } = dodo.api();
 
-Step 4: Create actions that use the checkout function.
+Step 5: Create actions that use the checkout function.
 
 // convex/payments.ts
 import { action } from "./_generated/server";
@@ -297,7 +352,7 @@ export const createCheckout = action({
   },
 });
 
-Step 5: Use in your frontend.
+Step 6: Use in your frontend.
 
 // Your frontend component
 import { useAction } from "convex/react";
@@ -332,9 +387,9 @@ Purpose: This function allows customers to manage their subscriptions and paymen
 
 Integration Steps:
 
-Follow Steps 1-3 from the Checkout Function section, then:
+Follow Steps 1-4 from the Checkout Function section, then:
 
-Step 4: Create a customer portal action.
+Step 5: Create a customer portal action.
 
 // convex/payments.ts (add to existing file)
 import { action } from "./_generated/server";
@@ -350,7 +405,7 @@ export const getCustomerPortal = action({
   },
 });
 
-Step 5: Use in your frontend.
+Step 6: Use in your frontend.
 
 // Your frontend component
 import { useAction } from "convex/react";
@@ -394,6 +449,7 @@ Step 2: Create a file `convex/http.ts`:
 // convex/http.ts
 import { httpRouter } from "convex/server";
 import { createDodoWebhookHandler } from "@dodopayments/convex";
+import { internal } from "./_generated/api";
 
 const http = httpRouter();
 
@@ -401,13 +457,22 @@ http.route({
   path: "/dodopayments-webhook",
   method: "POST",
   handler: createDodoWebhookHandler({
-    onPaymentSucceeded: async (payload) => {
+    onPaymentSucceeded: async (ctx, payload) => {
       console.log("Payment succeeded:", payload.data.payment_id);
-      // Add your logic here to handle the successful payment
+      // Update order status in your database
+      await ctx.runMutation(internal.orders.markAsPaid, {
+        orderId: payload.data.metadata.orderId,
+        paymentId: payload.data.payment_id,
+      });
     },
-    onSubscriptionActive: async (payload) => {
+    
+    onSubscriptionActive: async (ctx, payload) => {
       console.log("Subscription activated:", payload.data.subscription_id);
-      // Add your logic here
+      // Use ctx to create or update subscription records
+      await ctx.runMutation(internal.subscriptions.createOrUpdate, {
+        subscriptionId: payload.data.subscription_id,
+        customerId: payload.data.customer_id,
+      });
     },
     // Add other event handlers as needed
   }),

package/dist/client/index.d.ts

@@ -12,7 +12,6 @@ export interface DodoPaymentsComponent {
 export type DodoPaymentsClientConfig = {
     identify: (ctx: GenericActionCtx<any>) => Promise<{
         dodoCustomerId: string;
-        customerData?: any;
     } | null>;
     apiKey: string;
     environment: "test_mode" | "live_mode";