Affiliate Better Auth

Common errors

• Error: Cannot find module 'affiliate-better-auth' or 'better-auth'

  cause One or both packages are not installed or are not resolvable in the module path. This can happen with incorrect `pnpm`, `npm`, or `yarn` commands.
  fix Run `pnpm add affiliate-better-auth better-auth` (or `npm i` / `yarn add`) in your project root to ensure both the plugin and its peer dependency are correctly installed.

• TypeError: auth.plugins.affiliate.generateLink is not a function

  cause The `affiliatePlugin` was not correctly initialized or the `auth` instance does not have the expected `affiliate` property on its `plugins` object.
  fix Ensure `affiliatePlugin()` is included in the `plugins` array when configuring `betterAuth` on the server: `betterAuth({ plugins: [affiliatePlugin()] })`.

• Error: Peer dependency 'better-auth@^1.3.0' not installed or incompatible.

  cause Your installed version of `better-auth` does not match the required peer dependency range for `affiliate-better-auth`.
  fix Install a compatible version of `better-auth`. For example, `npm install better-auth@^1.3.0` or update your `package.json` and run `npm install`.

Warnings

• breaking This package is tightly coupled with `better-auth`. Major version upgrades of `better-auth` (e.g., from 1.x to 2.x) may introduce breaking changes requiring updates to `affiliate-better-auth` or its configuration.
  Fix: Always check the release notes for both `affiliate-better-auth` and `better-auth` when upgrading major versions. Ensure your `better-auth` peer dependency range is compatible.
• gotcha Referral tracking relies on an `affiliate` cookie being set. Users blocking cookies or using incognito modes may not be accurately tracked, or the referral link logic might not function as expected without manual handling.
  Fix: Communicate cookie usage clearly to users. For critical referral flows, consider fallback mechanisms or alternative tracking methods alongside cookie-based tracking. Ensure your frontend properly calls `POST /affiliate/issue-cookie`.
• gotcha The package automatically creates minimal schema for `affiliate_code` and `affiliate` models via the Better Auth adapter. If you have existing tables or a different schema preference, this might lead to conflicts or require manual migration/adjustments.
  Fix: Review the automatically generated schema. If conflicts arise, you may need to manually adjust your database schema or fork the plugin to customize schema generation if allowed by Better Auth's plugin API.
• gotcha While recent `affiliate-better-auth` versions show `0.6.x`, the provided changelog consistently refers to `0.1.0`. This discrepancy might indicate a versioning inconsistency or a misaligned changelog, which can make tracking specific changes or breaking points difficult.
  Fix: Rely on the npm package version for compatibility and feature tracking (e.g., `0.6.6`). For detailed change information, consult the GitHub repository directly if the README/changelog is ambiguous.

Install

• npm install affiliate-better-auth npm
• yarn add affiliate-better-auth yarn
• pnpm add affiliate-better-auth pnpm

Imports

• affiliatePlugin
  wrong:

  const { affiliatePlugin } = require('affiliate-better-auth');

  correct:

  import { affiliatePlugin } from 'affiliate-better-auth';

  Used for server-side integration with Better Auth. The package is primarily ESM.
• affiliateClientPlugin
  wrong:

  const { affiliateClientPlugin } = require('affiliate-better-auth');

  correct:

  import { affiliateClientPlugin } from 'affiliate-better-auth';

  Used for client-side integration, primarily to pass the plugin to createAuthClient. The package is primarily ESM.
• betterAuth
  wrong:

  import betterAuth from 'better-auth';

  correct:

  import { betterAuth } from 'better-auth';

  The core server-side Better Auth instance into which affiliatePlugin is loaded.
• createAuthClient
  wrong:

  import { createAuthClient } from 'better-auth';

  correct:

  import { createAuthClient } from 'better-auth/client';

  The client-side factory function for Better Auth; affiliateClientPlugin integrates here.

Quickstart

Demonstrates server-side initialization of `affiliate-better-auth` by integrating `affiliatePlugin` into the `betterAuth` instance, enabling referral tracking functionalities and automatic schema generation.

import { betterAuth } from 'better-auth';
import { affiliatePlugin } from 'affiliate-better-auth';

// Configure Better Auth with the affiliate plugin
export const auth = betterAuth({
	plugins: [
		// Initialize the affiliate plugin on the server
		affiliatePlugin()
	]
});

// Example of accessing an affiliate endpoint (conceptual, not runnable directly without a server setup)
// (You would typically expose these via your API routes)
// auth.get('/affiliate/generate-link', (req, res) => {
//   if (!req.session) return res.status(401).send('Unauthorized');
//   const link = auth.plugins.affiliate.generateLink(req.session.userId);
//   res.json({ link });
// });

// Client-side example (requires a separate client-side bundle)
// import { createAuthClient } from 'better-auth/client';
// import { affiliateClientPlugin } from 'affiliate-better-auth';
// export const clientAuth = createAuthClient({
// 	plugins: [
// 		affiliateClientPlugin()
// 	]
// });
// // To issue a cookie from the client after receiving a referral code, for example from a URL query parameter
// // clientAuth.plugins.affiliate.issueCookie(codeFromQueryParams);