@dodopayments/convex 0.1.1 → 0.2.1

package/README.md

@@ -22,7 +22,6 @@ npm install @dodopayments/convex
 
 ## Quick Start
 
-
 ### 1. Add Component to Convex Config
 
 ```typescript
@@ -46,6 +45,7 @@ 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
 ```
@@ -58,55 +58,75 @@ 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",
 });
 
-export const { checkout, customerPortal } = dodo.api();
 // Export the API methods for use in your app
 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`:
 
 ```typescript
 // convex/http.ts
-import { httpRouter } from "convex/server";
 import { createDodoWebhookHandler } from "@dodopayments/convex";
+import { httpRouter } from "convex/server";
+import { internal } from "./_generated/api";
 
 const http = httpRouter();
 
@@ -114,13 +134,32 @@ 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
+    // Handle successful payments
+    onPaymentSucceeded: async (ctx, payload) => {
+      console.log("🎉 Payment Succeeded!");
+      // Use Convex context to persist payment data
+      await ctx.runMutation(internal.webhooks.createPayment, {
+        paymentId: payload.data.payment_id,
+        businessId: payload.business_id,
+        customerEmail: payload.data.customer.email,
+        amount: payload.data.total_amount,
+        currency: payload.data.currency,
+        status: payload.data.status,
+        webhookPayload: JSON.stringify(payload),
+      });
     },
-    onSubscriptionActive: async (payload) => {
-      console.log("Subscription activated:", payload.data.subscription_id);
-      // Add your logic here
+
+    // Handle subscription activation
+    onSubscriptionActive: async (ctx, payload) => {
+      console.log("🎉 Subscription Activated!");
+      // Use Convex context to persist subscription data
+      await ctx.runMutation(internal.webhooks.createSubscription, {
+        subscriptionId: payload.data.subscription_id,
+        businessId: payload.business_id,
+        customerEmail: payload.data.customer.email,
+        status: payload.data.status,
+        webhookPayload: JSON.stringify(payload),
+      });
     },
     // Add other event handlers as needed
   }),
@@ -129,11 +168,15 @@ http.route({
 export default http;
 ```
 
+**Important:** Make sure to define the corresponding database mutations in your Convex backend for each webhook event you want to handle. For example, create a `createPayment` mutation to record successful payments or a `createSubscription` mutation to manage subscription state.
+
+**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
@@ -164,7 +207,7 @@ export const createCheckout = action({
 });
 ```
 
-### 6. Frontend Usage
+### 7. Frontend Usage
 
 ```tsx
 import { useAction } from "convex/react";
@@ -235,44 +278,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!,
@@ -282,7 +332,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";
@@ -312,7 +362,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";
@@ -347,9 +397,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";
@@ -365,7 +415,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";
@@ -407,8 +457,9 @@ Do not use .env files for backend functions; always set secrets in the Convex da
 Step 2: Create a file `convex/http.ts`:
 
 // convex/http.ts
-import { httpRouter } from "convex/server";
 import { createDodoWebhookHandler } from "@dodopayments/convex";
+import { httpRouter } from "convex/server";
+import { internal } from "./_generated/api";
 
 const http = httpRouter();
 
@@ -416,13 +467,32 @@ 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
+    // Handle successful payments
+    onPaymentSucceeded: async (ctx, payload) => {
+      console.log("🎉 Payment Succeeded!");
+      // Use Convex context to persist payment data
+      await ctx.runMutation(internal.webhooks.createPayment, {
+        paymentId: payload.data.payment_id,
+        businessId: payload.business_id,
+        customerEmail: payload.data.customer.email,
+        amount: payload.data.total_amount,
+        currency: payload.data.currency,
+        status: payload.data.status,
+        webhookPayload: JSON.stringify(payload),
+      });
     },
-    onSubscriptionActive: async (payload) => {
-      console.log("Subscription activated:", payload.data.subscription_id);
-      // Add your logic here
+
+    // Handle subscription activation
+    onSubscriptionActive: async (ctx, payload) => {
+      console.log("🎉 Subscription Activated!");
+      // Use Convex context to persist subscription data
+      await ctx.runMutation(internal.webhooks.createSubscription, {
+        subscriptionId: payload.data.subscription_id,
+        businessId: payload.business_id,
+        customerEmail: payload.data.customer.email,
+        status: payload.data.status,
+        webhookPayload: JSON.stringify(payload),
+      });
     },
     // Add other event handlers as needed
   }),
@@ -430,6 +500,8 @@ http.route({
 
 export default http;
 
+Note: Make sure to define the corresponding database mutations in your Convex backend for each webhook event you want to handle. For example, create a `createPayment` mutation to record successful payments or a `createSubscription` mutation to manage subscription state.
+
 Now, you can set the webhook endpoint URL in your Dodo Payments dashboard to `https://<your-convex-deployment-url>/dodopayments-webhook`.
 
 Environment Variable Setup:
@@ -455,4 +527,3 @@ If the user needs assistance setting up environment variables or deployment, ask
 
 Run `npx convex dev` after setting up the component to generate the necessary types.
 ```
-

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";