@dodopayments/fastify 0.1.1

package/README.md

@@ -0,0 +1,262 @@
+# `@dodopayments/fastify`
+
+A typescript library that exports Handlers for Checkout, Customer Portal, and Webhook routes for easy integration with your Fastify app.
+
+> **AI Agent Integration Guide:** See the AI Agent Prompt section below for detailed instructions and guidance for AI assistants.
+
+## Documentation
+
+Detailed documentation can be found at [Dodo Payments Fastify adaptor](https://docs.dodopayments.com/developer-resources/fastify-adaptor)
+
+## Installation
+
+You can install this package via npm or any other package manager of your choice:
+
+```bash
+npm install @dodopayments/fastify
+```
+
+## Quick Start
+
+
+### 1. Checkout
+
+```typescript
+import { Checkout } from '@dodopayments/fastify';
+
+const fastify = Fastify({})
+const checkoutGet = Checkout({
+    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
+    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
+    type: 'static'
+});
+
+fastify.get('/api/checkout', checkoutGet.getHandler);
+```
+
+---
+
+### 2. Customer Portal Route Handler
+
+```typescript
+import { CustomerPortal } from "@dodopayments/fastify";
+
+const fastify = Fastify({})
+const customerPortalHandler = CustomerPortal({
+    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+    environment: process.env.DODO_PAYMENTS_ENVIRONMENT
+});
+fastify.get('/api/customer-portal', customerPortalHandler);
+
+```
+
+#### 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.
+
+---
+
+### 3. Webhook Route Handler
+
+```typescript
+
+import Fastify from 'fastify'
+import { Webhooks } from '@dodopayments/fastify'
+
+const fastify = Fastify({})
+fastify.addContentTypeParser('application/json', { parseAs: 'string' }, function (req, body, done) {
+    done(null, body)
+})
+fastify.post('/api/webhooks', Webhooks({
+  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
+  onPayload: async (payload) => {
+    // Handle Payload Here
+    console.log(payload)
+  }
+}));
+
+```
+
+---
+
+## Prompt for LLM
+
+```
+You are an expert Fastify developer assistant. Your task is to guide a user through integrating the @dodopayments/fastify adapter into their existing Fastify project.
+
+The @dodopayments/fastify adapter provides route handlers for Dodo Payments' Checkout, Customer Portal, and Webhook functionalities, designed to plug directly into an Fastify app.
+
+First, install the necessary package. Use the package manager appropriate for the user's project (npm, yarn, or bun):
+
+npm install @dodopayments/fastify
+
+---
+
+Here's how you should structure your response:
+
+1. Ask the user which functionalities they want to integrate.
+
+"Which parts of the @dodopayments/fastify adapter would you like to integrate into your project? You can choose one or more of the following:
+
+- Checkout Route Handler (for handling product checkouts)
+- Customer Portal Route Handler (for managing customer subscriptions/details)
+- Webhook Route Handler (for receiving Dodo Payments webhook events)
+- All (integrate all three)"
+
+---
+
+2. Based on the user's selection, provide detailed integration steps for each chosen functionality.
+
+---
+
+**If Checkout Route Handler is selected:**
+
+**Purpose**: This handler redirects users to the Dodo Payments checkout page.
+
+**Integration**:
+Create two routes in your Fastify app — one for static (GET) and one for dynamic (POST) checkout.
+
+
+import { Checkout } from '@dodopayments/fastify';
+import Fastify from 'fastify'
+
+const fastify = Fastify({})
+const checkoutGet = Checkout({
+    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
+    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
+    type: 'static'
+});
+
+const checkoutPost = Checkout({
+    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+    environment: process.env.DODO_PAYMENTS_ENVIRONMENT,
+    returnUrl: process.env.DODO_PAYMENTS_RETURN_URL,
+    type: 'dynamic'
+});
+
+fastify.get('/api/checkout', checkoutGet.getHandler);
+fastify.post('/api/checkout', checkoutGet.postHandler);
+
+
+Config Options:
+
+    bearerToken: Your Dodo Payments API key (recommended to be stored in DODO_PAYMENTS_API_KEY env variable).
+
+    returnUrl (optional): URL to redirect the user after successful checkout.
+
+    environment: "test_mode" or "live_mode"
+
+    type: "static" (GET) or "dynamic" (POST)
+
+GET (static checkout) expects query parameters:
+
+    productId (required)
+
+    quantity, customer fields (fullName, email, etc.), and metadata (metadata_*) are optional.
+
+POST (dynamic checkout) expects a JSON body with payment details (one-time or subscription). Reference the docs for the full POST schema:
+
+    One-time payments: https://docs.dodopayments.com/api-reference/payments/post-payments
+
+    Subscriptions: https://docs.dodopayments.com/api-reference/subscriptions/post-subscriptions
+
+If Customer Portal Route Handler is selected:
+
+Purpose: This route allows customers to manage their subscriptions via the Dodo Payments portal.
+
+Integration:
+
+import { CustomerPortal } from "@dodopayments/fastify";
+import Fastify from 'fastify'
+
+const fastify = Fastify({})
+const customerPortalHandler = CustomerPortal({
+    bearerToken: process.env.DODO_PAYMENTS_API_KEY,
+    environment: process.env.DODO_PAYMENTS_ENVIRONMENT
+});
+fastify.get('/api/customer-portal', customerPortalHandler);
+
+Query Parameters:
+
+    customer_id (required): e.g., ?customer_id=cus_123
+
+    send_email (optional): if true, customer is emailed the portal link
+
+Returns 400 if customer_id is missing.
+
+If Webhook Route Handler is selected:
+
+Purpose: Processes incoming webhook events from Dodo Payments to trigger events in your app.
+
+Integration:
+
+import Fastify from 'fastify'
+import { Webhooks } from '@dodopayments/fastify'
+
+const fastify = Fastify({})
+fastify.addContentTypeParser('application/json', { parseAs: 'string' }, function (req, body, done) {
+    done(null, body)
+})
+
+fastify.post('/api/webhooks', Webhooks({
+  webhookKey: process.env.DODO_PAYMENTS_WEBHOOK_KEY,
+  onPayload: async (payload) => {
+    // Handle Payload Here
+    console.log(payload)
+  }
+}));
+
+Features:
+
+    Only POST method is allowed — others return 405
+
+    Signature verification is performed using webhookKey. Returns 401 if invalid.
+
+    Zod-based payload validation. Returns 400 if invalid schema.
+
+    All handlers are async functions.
+
+Supported Webhook Event Handlers:
+
+You may pass in any of the following handlers:
+
+    onPayload
+
+    onPaymentSucceeded
+
+    onPaymentFailed
+
+    onPaymentProcessing
+
+    onPaymentCancelled
+
+    onRefundSucceeded
+
+    onRefundFailed
+
+    onDisputeOpened, onDisputeExpired, onDisputeAccepted, onDisputeCancelled, onDisputeChallenged, onDisputeWon, onDisputeLost
+
+    onSubscriptionActive, onSubscriptionOnHold, onSubscriptionRenewed, onSubscriptionPaused, onSubscriptionPlanChanged, onSubscriptionCancelled, onSubscriptionFailed, onSubscriptionExpired
+
+    onLicenseKeyCreated
+
+Environment Variable Setup:
+
+Make sure to define these environment variables in your project:
+
+DODO_PAYMENTS_API_KEY=your-api-key
+DODO_PAYMENTS_RETURN_URL=https://yourapp.com/success
+DODO_PAYMENTS_WEBHOOK_KEY=your-webhook-secret
+DODO_PAYMENTS_ENVIRONMENT="test"or"live"
+
+Use these inside your code as:
+
+process.env.DODO_PAYMENTS_API_KEY
+process.env.DODO_PAYMENTS_WEBHOOK_KEY
+
+Security Note: Do NOT commit secrets to version control. Use .env files locally and secrets managers in deployment environments (e.g., AWS, Vercel, Heroku, etc.).

package/dist/checkout/checkout.d.ts

@@ -0,0 +1,7 @@
+import { FastifyRequest, FastifyReply } from "fastify";
+import { CheckoutHandlerConfig } from "@dodopayments/core/checkout";
+export declare const Checkout: (config: CheckoutHandlerConfig) => {
+    getHandler: (request: FastifyRequest, reply: FastifyReply) => Promise<never>;
+    postHandler: (request: FastifyRequest, reply: FastifyReply) => Promise<never>;
+};
+//# sourceMappingURL=checkout.d.ts.map

package/dist/checkout/checkout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../../src/checkout/checkout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,EAEL,qBAAqB,EAGtB,MAAM,6BAA6B,CAAC;AAErC,eAAO,MAAM,QAAQ,GAAI,QAAQ,qBAAqB;0BAEjB,cAAc,SAAS,YAAY;2BA4BlC,cAAc,SAAS,YAAY;CAuBxE,CAAC"}

package/dist/customer-portal/customer-portal.d.ts

@@ -0,0 +1,5 @@
+import { FastifyRequest, FastifyReply } from "fastify";
+import { ClientOptions } from "dodopayments";
+export type CustomerPortalConfig = Pick<ClientOptions, "environment" | "bearerToken">;
+export declare const CustomerPortal: ({ bearerToken, environment, }: CustomerPortalConfig) => (request: FastifyRequest, reply: FastifyReply) => Promise<never>;
+//# sourceMappingURL=customer-portal.d.ts.map

package/dist/customer-portal/customer-portal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"customer-portal.d.ts","sourceRoot":"","sources":["../../src/customer-portal/customer-portal.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvD,OAAqB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE3D,MAAM,MAAM,oBAAoB,GAAG,IAAI,CACrC,aAAa,EACb,aAAa,GAAG,aAAa,CAC9B,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,+BAG5B,oBAAoB,eACc,cAAc,SAAS,YAAY,mBAoCvE,CAAC"}