@polar-sh/better-auth 0.1.2 → 1.0.0

package/README.md

@@ -6,8 +6,10 @@ A [Better Auth](https://github.com/better-auth/better-auth) plugin for integrati
 
 - Checkout Integration
 - Customer Portal
-- Webhook handling
 - Automatic Customer creation on signup
+- Event Ingestion & Customer Meters for flexible Usage Based Billing
+- Handle Polar Webhooks securely with signature verification
+- Reference System to associate purchases with organizations
 
 ## Installation
 
@@ -15,7 +17,7 @@ A [Better Auth](https://github.com/better-auth/better-auth) plugin for integrati
 pnpm add better-auth @polar-sh/better-auth @polar-sh/sdk
 ```
 
-### Preparation
+## Preparation
 
 Go to your Polar Organization Settings, and create an Organization Access Token. Add it to your environment.
 
@@ -24,52 +26,108 @@ Go to your Polar Organization Settings, and create an Organization Access Token.
 POLAR_ACCESS_TOKEN=...
 ```
 
+### Configuring BetterAuth Server
+
+The Polar plugin comes with a handful additional plugins which adds functionality to your stack.
+
+- Checkout - Enables a seamless checkout integration
+- Portal - Makes it possible for your customers to manage their orders, subscriptions & granted benefits
+- Usage - Simple extension for listing customer meters & ingesting events for Usage Based Billing
+- Webhooks - Listen for relevant Polar webhooks
+
 ```typescript
 import { betterAuth } from "better-auth";
-import { polar } from "@polar-sh/better-auth";
+import { polar, checkout, portal, usage, webhooks } from "@polar-sh/better-auth";
 import { Polar } from "@polar-sh/sdk";
 
-const client = new Polar({
+const polarClient = new Polar({
     accessToken: process.env.POLAR_ACCESS_TOKEN,
     // Use 'sandbox' if you're using the Polar Sandbox environment
     // Remember that access tokens, products, etc. are completely separated between environments.
     // Access tokens obtained in Production are for instance not usable in the Sandbox environment.
-    server: 'production'
+    server: 'sandbox'
 });
 
 const auth = betterAuth({
     // ... Better Auth config
     plugins: [
         polar({
-            client,
-            // Enable automatic Polar Customer creation on signup
+            client: polarClient,
             createCustomerOnSignUp: true,
-            // Enable customer portal
-            enableCustomerPortal: true, // Deployed under /portal for authenticated users
-            // Configure checkout
-            checkout: {
-                enabled: true,
-                products: [
-                    {
-                        productId: "123-456-789", // ID of Product from Polar Dashboard
-                        slug: "pro" // Custom slug for easy reference in Checkout URL, e.g. /checkout/pro
-                    }
-                ],
-                successUrl: "/success?checkout_id={CHECKOUT_ID}",
-                authenticatedUsersOnly: true
-            },
-            // Incoming Webhooks handler will be installed at /polar/webhooks
-            webhooks: {
-                secret: process.env.POLAR_WEBHOOK_SECRET,
-                onPayload: ...,
-            }
+            use: [
+                checkout({
+                    products: [
+                        {
+                            productId: "123-456-789", // ID of Product from Polar Dashboard
+                            slug: "pro" // Custom slug for easy reference in Checkout URL, e.g. /checkout/pro
+                        }
+                    ],
+                    successUrl: "/success?checkout_id={CHECKOUT_ID}",
+                    authenticatedUsersOnly: true
+                }),
+                portal(),
+                usage(),
+                webhooks({
+                    secret: process.env.POLAR_WEBHOOK_SECRET,
+                    onCustomerStateChanged: (payload) => // Triggered when anything regarding a customer changes
+                    onOrderPaid: (payload) => // Triggered when an order was paid (purchase, subscription renewal, etc.)
+                    ...  // Over 25 granular webhook handlers
+                    onPayload: (payload) => // Catch-all for all events
+                })
+            ],
         })
     ]
 });
 ```
 
+### Configuring BetterAuth Client
+
+You will be using the BetterAuth Client to interact with the Polar functionalities.
+
+```typescript
+import { createAuthClient } from "better-auth/react";
+import { polarClient } from "@polar-sh/better-auth";
+import { organizationClient } from "better-auth/client/plugins";
+
+// This is all that is needed
+// All Polar plugins, etc. should be attached to the server-side BetterAuth config
+export const authClient = createAuthClient({
+  plugins: [polarClient()],
+});
+```
+
 ## Configuration Options
 
+```typescript
+import { betterAuth } from "better-auth";
+import { polar, checkout, portal, usage, webhooks } from "@polar-sh/better-auth";
+import { Polar } from "@polar-sh/sdk";
+
+const polarClient = new Polar({
+    accessToken: process.env.POLAR_ACCESS_TOKEN,
+    // Use 'sandbox' if you're using the Polar Sandbox environment
+    // Remember that access tokens, products, etc. are completely separated between environments.
+    // Access tokens obtained in Production are for instance not usable in the Sandbox environment.
+    server: 'sandbox'
+});
+
+const auth = betterAuth({
+    // ... Better Auth config
+    plugins: [
+        polar({
+            client: polarClient,
+            createCustomerOnSignUp: true,
+            getCustomerCreateParams?: ({ user, session }, request) => ({
+                myCustomProperty: 123
+            }),
+            use: [
+                // This is where you add Polar plugins
+            ]
+        })
+    ]
+})
+```
+
 ### Required Options
 
 - `client`: Polar SDK client instance
@@ -77,14 +135,282 @@ const auth = betterAuth({
 ### Optional Options
 
 - `createCustomerOnSignUp`: Automatically create a Polar customer when a user signs up
-- `getCustomerCreateParams`: Custom function to provide additional customer creation parameters
-- `enableCustomerPortal`: Enable the customer portal functionality. Deployed as GET endpoint at /portal
-- `checkout.enabled`: Enable checkout functionality. Deployed as GET endpoint at /checkout
-- `checkout.products`: Array of products or function returning products. Slug passed will then be passable as route param.
-- `checkout.successUrl`: URL to redirect to after successful checkout
-- `checkout.authenticatedUsersOnly`: Only allow authenticated users to access the checkout
+- `getCustomerCreateParams`: Custom function to provide additional customer creation metadata
+
+### Customers
+
+When `createCustomerOnSignUp` is enabled, a new Polar Customer is automatically created when a new User is added in the Better-Auth Database.
+
+All new customers are created with an associated `externalId`, which is the ID of your User in the Database. This allows us to skip any Polar <-> User mapping in your Database.
+
+## Checkout Plugin
+
+To support checkouts in your app, simply pass the Checkout plugin to the use-property.
+
+```typescript
+import { polar, checkout } from "@polar-sh/better-auth";
+
+const auth = betterAuth({
+    // ... Better Auth config
+    plugins: [
+        polar({
+            ...
+            use: [
+                checkout({
+                    // Optional field - will make it possible to pass a slug to checkout instead of Product ID
+                    products: [ { productId: "123-456-789", slug: "pro" } ],
+                    // Relative URL to return to when checkout is successfully completed
+                    successUrl: "/success?checkout_id={CHECKOUT_ID}",
+                    // Wheather you want to allow unauthenticated checkout sessions or not
+                    authenticatedUsersOnly: true
+                })
+            ],
+        })
+    ]
+});
+```
+
+When checkouts are enabled, you're able to initialize Checkout Sessions using the checkout-method on the BetterAuth Client. This will redirect the user to the Product Checkout.
+
+```typescript
+await authClient.checkout({
+  // Any Polar Product ID can be passed here
+  products: ["e651f46d-ac20-4f26-b769-ad088b123df2"],
+  // Or, if you setup "products" in the Checkout Config, you can pass the slug
+  slug: "pro",
+});
+```
+
+Checkouts will automatically carry the authenticated User as the customer to the checkout. Email-address will be "locked-in".
+
+If `authenticatedUsersOnly` is `false` - then it will be possible to trigger checkout sessions without any associated customer.
+
+### Organization Support
+
+This plugin supports the Organization plugin. If you pass the organization ID to the Checkout referenceId, you will be able to keep track of purchases made from organization members.
+
+```typescript
+const organizationId = (await authClient.organization.list())?.data?.[0]?.id,
+
+await authClient.checkout({
+    // Any Polar Product ID can be passed here
+    products: ["e651f46d-ac20-4f26-b769-ad088b123df2"],
+    // Or, if you setup "products" in the Checkout Config, you can pass the slug
+    slug: 'my-pro-product',
+    // Reference ID will be saved as `referenceId` in the metadata of the checkout, order & subscription object
+    referenceId: organizationId
+});
+```
+
+## Portal Plugin
+
+A plugin which enables customer management of their purchases, orders and subscriptions.
+
+```typescript
+import { polar, checkout, portal } from "@polar-sh/better-auth";
+
+const auth = betterAuth({
+    // ... Better Auth config
+    plugins: [
+        polar({
+            ...
+            use: [
+                checkout(...),
+                portal()
+            ],
+        })
+    ]
+});
+```
+
+The portal-plugin gives the BetterAuth Client a set of customer management methods, scoped under `authClient.customer`.
+
+### Customer Portal Management
+
+The following method will redirect the user to the Polar Customer Portal, where they can see orders, purchases, subscriptions, benefits, etc.
+
+```typescript
+await authClient.customer.portal();
+```
+
+### Customer State
+
+The portal plugin also adds a convenient state-method for retrieving the general Customer State.
+
+```typescript
+const { data: customerState } = await authClient.customer.state();
+```
+
+The customer state object contains:
+
+- All the data about the customer.
+- The list of their active subscriptions
+  - Note: This does not include subscriptions done by a parent organization. See the subscription list-method below for more information.
+- The list of their granted benefits.
+- The list of their active meters, with their current balance.
+
+Thus, with that single object, you have all the required information to check if you should provision access to your service or not.
+
+[You can learn more about the Polar Customer State in the Polar Docs](https://docs.polar.sh/integrate/customer-state).
 
-### Webhook Handlers
+### Benefits, Orders & Subscriptions
+
+The portal plugin adds 3 convenient methods for listing benefits, orders & subscriptions relevant to the authenticated user/customer.
+
+[All of these methods use the Polar CustomerPortal APIs](https://docs.polar.sh/api-reference/customer-portal)
+
+#### Benefits
+
+This method only lists granted benefits for the authenticated user/customer.
+
+```typescript
+const { data: benefits } = await authClient.customer.benefits.list({
+  query: {
+    page: 1,
+    limit: 10,
+  },
+});
+```
+
+#### Orders
+
+This method lists orders like purchases and subscription renewals for the authenticated user/customer.
+
+```typescript
+const { data: orders } = await authClient.customer.orders.list({
+  query: {
+    page: 1,
+    limit: 10,
+    productBillingType: "one_time", // or 'recurring'
+  },
+});
+```
+
+#### Subscriptions
+
+This method lists the subscriptions associated with authenticated user/customer.
+
+```typescript
+const { data: subscriptions } = await authClient.customer.orders.list({
+  query: {
+    page: 1,
+    limit: 10,
+    active: true,
+  },
+});
+```
+
+**Important** - Organization Support
+
+This will **not** return subscriptions made by a parent organization to the authenticated user.
+
+However, you can pass a `referenceId` to this method. This will return all subscriptions associated with that referenceId instead of subscriptions associated with the user.
+
+So in order to figure out if a user should have access, pass the user's organization ID to see if there is an active subscription for that organization.
+
+```typescript
+const organizationId = (await authClient.organization.list())?.data?.[0]?.id,
+
+const { data: subscriptions } = await authClient.customer.orders.list({
+    query: {
+	    page: 1,
+		limit: 10,
+		active: true,
+        referenceId: organizationId
+    },
+});
+
+const userShouldHaveAccess = subscriptions.some(
+    sub => // Your logic to check subscription product or whatever.
+)
+```
+
+## Usage Plugin
+
+A simple plugin for Usage Based Billing.
+
+```typescript
+import { polar, checkout, portal, usage } from "@polar-sh/better-auth";
+
+const auth = betterAuth({
+    // ... Better Auth config
+    plugins: [
+        polar({
+            ...
+            use: [
+                checkout(...),
+                portal(),
+                usage()
+            ],
+        })
+    ]
+});
+```
+
+### Event Ingestion
+
+Polar's Usage Based Billing builds entirely on event ingestion. Ingest events from your application, create Meters to represent that usage, and add metered prices to Products to charge for it.
+
+[Learn more about Usage Based Billing in the Polar Docs.](https://docs.polar.sh/features/usage-based-billing/introduction)
+
+```typescript
+const { data: ingested } = await authClient.usage.ingest({
+  event: "file-uploads",
+  metadata: {
+    uploadedFiles: 12,
+  },
+});
+```
+
+The authenticated user is automatically associated with the ingested event.
+
+### Customer Meters
+
+A simple method for listing the authenticated user's Usage Meters, or as we call them, Customer Meters.
+
+Customer Meter's contains all information about their consumtion on your defined meters.
+
+- Customer Information
+- Meter Information
+- Customer Meter Information
+  - Consumed Units
+  - Credited Units
+  - Balance
+
+```typescript
+const { data: customerMeters } = await authClient.usage.meters.list({
+  query: {
+    page: 1,
+    limit: 10,
+  },
+});
+```
+
+## Webhooks Plugin
+
+The Webhooks plugin can be used to capture incoming events from your Polar organization.
+
+```typescript
+import { polar, webhooks } from "@polar-sh/better-auth";
+
+const auth = betterAuth({
+    // ... Better Auth config
+    plugins: [
+        polar({
+            ...
+            use: [
+                webhooks({
+                    secret: process.env.POLAR_WEBHOOK_SECRET,
+                    onCustomerStateChanged: (payload) => // Triggered when anything regarding a customer changes
+                    onOrderPaid: (payload) => // Triggered when an order was paid (purchase, subscription renewal, etc.)
+                    ...  // Over 25 granular webhook handlers
+                    onPayload: (payload) => // Catch-all for all events
+                })
+            ],
+        })
+    ]
+});
+```
 
 Configure a Webhook endpoint in your Polar Organization Settings page. Webhook endpoint is configured at /polar/webhooks.
 
@@ -123,34 +449,3 @@ The plugin supports handlers for all Polar webhook events:
 - `onCustomerUpdated` - Triggered when a customer is updated
 - `onCustomerDeleted` - Triggered when a customer is deleted
 - `onCustomerStateChanged` - Triggered when a customer is created
-
-## API Routes
-
-The plugin adds the following API routes:
-
-- `GET /checkout/:slug` - Redirect to Polar checkout
-- `GET /state` - Customer state (Customer Data, Active Subscriptions, Entitlements, etc.) for the authenticated user
-- `GET /portal` - Redirects to Polar Customer Portal for authenticated user
-- `POST /polar/webhooks` - Incoming webhooks are automatically parsed & validated
-
-## Customers
-
-When `createCustomerOnSignUp` is enabled, a new Polar Customer is automatically created when a new User is added in the Better-Auth Database.
-
-All new customers are created with an associated `externalId`, which is the ID of your User in the Database. This allows us to skip any Polar <-> User mapping in your Database.
-
-## Checkouts
-
-When checkouts are enabled, you're able to initialize Checkout Sessions on the `/checkout/:slug` route.
-
-### Checkouts with slug
-
-If you pass an array of products to the configuration, you're able to use the slug as a reference instead of using the product id.
-
-### Checkouts with products
-
-All your organization products are eligible for checkouts, even if they're not passed to the products-configuration.
-
-You can initialize a checkout session like following - `/checkout?products=123-456-789`
-
-You can pass multiple products like - `/checkout?products=123-456-789&products=987-654-321`