Better Auth StreamPay Plugin

1.0.0 · active · verified Wed Apr 22

better-auth-streampay is a community-developed plugin designed to seamlessly integrate StreamPay payment and subscription functionalities into applications utilizing the `better-auth` authentication framework. Currently at version 1.0.0, this package provides robust features such as checkout integration with lazy consumer creation, a comprehensive customer portal for managing subscriptions and invoices, and secure handling of StreamPay webhooks with HMAC-SHA256 signature verification. It also allows for optional eager consumer provisioning upon user signup and ensures consumer data synchronization on user updates or deletions. The plugin differentiates itself by offering a tightly coupled solution specifically for StreamPay users within the Better Auth ecosystem, providing distinct sub-plugins for various functionalities like `checkout`, `portal`, `subscriptions`, and `webhooks` for modular integration. While there's no fixed release cadence, being a v1.0.0 community plugin, updates are typically driven by feature development and bug fixes.

Common errors

```
Error: Missing required environment variable: STREAMPAY_API_KEY
```
cause The `STREAMPAY_API_KEY` environment variable, which holds the Base64-encoded StreamPay API key, is not set.

fix Add `STREAMPAY_API_KEY=your_base64_encoded_api_key` to your `.env` file or environment variables.
```
TypeError: Cannot read properties of undefined (reading 'init') at StreamSDK
```
cause The `@streamsdk/typescript` peer dependency is either not installed or improperly imported/configured.

fix Ensure `@streamsdk/typescript` is installed via `pnpm add @streamsdk/typescript` and imported correctly as `import StreamSDK from '@streamsdk/typescript';`.
```
TypeError: streampay.use is not a function
```
cause The sub-plugins (e.g., `checkout`, `portal`) are not being passed as an array to the `use` property of the `streampay` plugin factory.

fix Ensure sub-plugins are correctly composed within the `use` array: `streampay({ client: streamPayClient, use: [checkout(...), portal()] })`.
```
Error: HMAC-SHA256 signature verification failed for StreamPay webhook
```
cause The `STREAMPAY_WEBHOOK_SECRET` environment variable is either missing, incorrect, or the webhook payload has been tampered with.

fix Verify that `STREAMPAY_WEBHOOK_SECRET` in your environment exactly matches the webhook secret configured in your StreamPay dashboard.

Warnings

gotcha This is a community-developed plugin and is NOT officially affiliated with Stream or StreamPay. For plugin-specific bugs or feature requests, use the GitHub issue tracker for this repository. Direct StreamPay support channels will not handle issues related to this plugin.
Fix: Be aware of the support channel distinction. For core StreamPay service issues, contact StreamPay support. For plugin integration issues, open an issue on the plugin's GitHub repository.
breaking The plugin has strict peer dependency requirements for `@streamsdk/typescript`, `better-auth`, and `zod`. Failing to install these or using incompatible versions will lead to runtime errors or build failures.
Fix: Ensure all peer dependencies are installed correctly and meet the specified version ranges, e.g., `pnpm add better-auth-streampay @streamsdk/typescript better-auth zod`.
breaking Critical environment variables must be configured for the plugin to function. `STREAMPAY_API_KEY` (a Base64-encoded `apiKey:apiSecret` pair), `BETTER_AUTH_SECRET`, and `BETTER_AUTH_URL` are generally required, with `STREAMPAY_WEBHOOK_SECRET` being necessary for webhook functionality.
Fix: Define all required environment variables in your `.env` file or deployment configuration, ensuring `STREAMPAY_API_KEY` is correctly Base64-encoded.
breaking The plugin adds a `streampayConsumerId` column to the `user` table. A database migration MUST be run after installing this plugin, regardless of whether you are using Drizzle, Prisma, or the Better Auth CLI for migrations.
Fix: Execute the appropriate database migration command for your ORM/CLI after installation (e.g., `npx @better-auth/cli migrate`, `npx drizzle-kit generate && npx drizzle-kit migrate`, or `npx prisma migrate dev`).

Install

npm install better-auth-streampay npm
yarn add better-auth-streampay yarn
pnpm add better-auth-streampay pnpm

Imports

streampay
wrong:
```
const streampay = require('better-auth-streampay');
```
correct:
```
import { streampay } from 'better-auth-streampay';
```
The primary server-side plugin factory, used within `betterAuth` configuration. ESM-only due to Better Auth's modern tooling.
checkout
wrong:
```
import checkout from 'better-auth-streampay/checkout';
```
correct:
```
import { checkout } from 'better-auth-streampay';
```
Named import for a sub-plugin used to compose functionality within `streampay`. Other sub-plugins like `portal`, `subscriptions`, and `webhooks` are imported similarly.
streampayClient
wrong:
```
import { streampayClient } from 'better-auth-streampay';
```
correct:
```
import { streampayClient } from 'better-auth-streampay/client';
```
The client-side counterpart plugin for `better-auth/react`, imported from a dedicated client entry point.

Quickstart

This quickstart demonstrates the server-side setup of the `better-auth-streampay` plugin, configuring the core `streampay` plugin with its sub-plugins: `checkout`, `portal`, `subscriptions`, and `webhooks`. It initializes the StreamPay SDK client and integrates webhook handlers for payment success and subscription cancellation events.

import { betterAuth } from "better-auth";
import StreamSDK from "@streamsdk/typescript";
import {
  streampay,
  checkout,
  portal,
  subscriptions,
  webhooks,
} from "better-auth-streampay";

// Ensure these environment variables are set in your .env file
// STREAMPAY_API_KEY=your_base64_encoded_api_key:api_secret
// STREAMPAY_WEBHOOK_SECRET=your_webhook_secret (if using webhooks)
// BETTER_AUTH_SECRET=your_session_signing_secret (min 32 chars)
// BETTER_AUTH_URL=your_app_public_url (required in prod)

const streamPayClient = StreamSDK.init(process.env.STREAMPAY_API_KEY ?? '');

const auth = betterAuth({
  plugins: [
    streampay({
      client: streamPayClient,
      // createConsumerOnSignUp defaults to false; set to `true` to provision
      // a StreamPay consumer at signup instead of lazily on first payment.
      use: [
        checkout({
          products: [
            { productId: "aaaa-bbbb-cccc-dddd", slug: "pro" }
          ],
          successUrl: "/dashboard?checkout=success",
          failureUrl: "/dashboard?checkout=failure",
          authenticatedUsersOnly: true,
        }),
        portal(),
        subscriptions(),
        webhooks({
          secret: process.env.STREAMPAY_WEBHOOK_SECRET ?? '',
          onPaymentSucceeded: async (payload) => {
            console.log('Payment Succeeded:', payload);
            // Implement logic to provision user access or update status
          },
          onSubscriptionCanceled: async (payload) => {
            console.log('Subscription Canceled:', payload);
            // Implement logic to revoke user access or update status
          },
        }),
      ],
    }),
  ],
});

console.log('Better Auth with StreamPay plugin initialized successfully.');

view raw JSON →