@checodo/better-auth-referral 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @checodo/better-auth-referral
+
+## 0.1.0
+
+### Minor Changes
+
+- 5f427b0: First release: referral codes, sign-up attribution, and reward steps.

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clas Heinemeyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @checodo/better-auth-referral
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Referral codes for [better-auth](https://better-auth.com): codes per user, attribution for every sign-up method, and steps such as a first purchase before a referral earns a reward.
+
+A community plugin, not made by the better-auth team. It looks and works
+like better-auth's own plugins: a server plugin, a typed client plugin,
+error codes, and database tables.
+
+## Install
+
+```bash
+npm install @checodo/better-auth-referral
+```
+
+Requires `better-auth` and `@better-auth/core` 1.7.20 or a later 1.x
+release (peer dependencies). ESM only.
+
+## Usage
+
+```ts
+// auth.ts
+import { betterAuth } from "better-auth";
+import { referral } from "@checodo/better-auth-referral";
+
+export const auth = betterAuth({
+  plugins: [
+    referral({
+      steps: ["email-verified"],
+      onReferralCompleted: async ({ referrerUserId }) => {
+        // reward the referrer
+      },
+    }),
+  ],
+});
+```
+
+```ts
+// auth-client.ts
+import { createAuthClient } from "better-auth/client";
+import { referralClient } from "@checodo/better-auth-referral/client";
+
+export const authClient = createAuthClient({ plugins: [referralClient()] });
+```
+
+Create the plugin's tables with the better-auth CLI:
+
+```bash
+npx auth@latest migrate
+```
+
+## Documentation
+
+Every option, endpoint, error code, and table:
+[docs](https://github.com/checodo/better-auth-plugins/blob/main/apps/docs/content/docs/referral.mdx).

package/dist/client.d.ts

@@ -0,0 +1,41 @@
+import { i as REFERRAL_ERROR_CODES, t as ReferralPlugin } from "./index-HDtManYT.js";
+/**
+ * Client companion to `referral()`. Adds `authClient.referral.getCode`,
+ * `createCode`, `regenerateCode`, `checkCode`, `listReferrals`, and
+ * `listAllReferrals` (admins), typed from the server plugin. Pass the code
+ * at sign-up in the `x-referral-code` header, or as
+ * `additionalData.referralCode` of a social sign-in.
+ *
+ * @example
+ * ```ts
+ * import { createAuthClient } from "better-auth/client";
+ * import { referralClient } from "@checodo/better-auth-referral/client";
+ *
+ * export const authClient = createAuthClient({
+ *   plugins: [referralClient()],
+ * });
+ *
+ * const { data } = await authClient.referral.createCode();
+ * ```
+ */
+export declare const referralClient: () => {
+  id: "referral";
+  $InferServerPlugin: ReferralPlugin;
+  pathMethods: {
+    "/referral/get-code": "GET";
+    "/referral/create-code": "POST";
+    "/referral/regenerate-code": "POST";
+    "/referral/check-code": "GET";
+    "/referral/list-referrals": "GET";
+    "/referral/list-all-referrals": "GET";
+  };
+  $ERROR_CODES: {
+    INVALID_REFERRAL_CODE: import("better-auth").RawError<"INVALID_REFERRAL_CODE">;
+    UNKNOWN_REFERRAL_STEP: import("better-auth").RawError<"UNKNOWN_REFERRAL_STEP">;
+    CODE_GENERATION_FAILED: import("better-auth").RawError<"CODE_GENERATION_FAILED">;
+    METADATA_TOO_LARGE: import("better-auth").RawError<"METADATA_TOO_LARGE">;
+    YOU_ARE_NOT_ALLOWED_TO_LIST_REFERRALS: import("better-auth").RawError<"YOU_ARE_NOT_ALLOWED_TO_LIST_REFERRALS">;
+  };
+};
+export { REFERRAL_ERROR_CODES };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","names":[],"sources":["../src/client.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;qBAuBa;;EAGiB,oBAAA"}

package/dist/client.js

@@ -0,0 +1,39 @@
+import { t as REFERRAL_ERROR_CODES } from "./error-codes-Bw554PRu.js";
+// src/client.ts
+/**
+* Client companion to `referral()`. Adds `authClient.referral.getCode`,
+* `createCode`, `regenerateCode`, `checkCode`, `listReferrals`, and
+* `listAllReferrals` (admins), typed from the server plugin. Pass the code
+* at sign-up in the `x-referral-code` header, or as
+* `additionalData.referralCode` of a social sign-in.
+*
+* @example
+* ```ts
+* import { createAuthClient } from "better-auth/client";
+* import { referralClient } from "@checodo/better-auth-referral/client";
+*
+* export const authClient = createAuthClient({
+*   plugins: [referralClient()],
+* });
+*
+* const { data } = await authClient.referral.createCode();
+* ```
+*/
+const referralClient = () => {
+	return {
+		id: "referral",
+		$InferServerPlugin: {},
+		pathMethods: {
+			"/referral/get-code": "GET",
+			"/referral/create-code": "POST",
+			"/referral/regenerate-code": "POST",
+			"/referral/check-code": "GET",
+			"/referral/list-referrals": "GET",
+			"/referral/list-all-referrals": "GET"
+		},
+		$ERROR_CODES: REFERRAL_ERROR_CODES
+	};
+};
+export { REFERRAL_ERROR_CODES, referralClient };
+
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","names":[],"sources":["../src/client.ts"],"sourcesContent":["import type { BetterAuthClientPlugin } from \"better-auth/client\";\nimport { REFERRAL_ERROR_CODES } from \"./error-codes\";\nimport type { ReferralPlugin } from \"./index\";\n\n/**\n * Client companion to `referral()`. Adds `authClient.referral.getCode`,\n * `createCode`, `regenerateCode`, `checkCode`, `listReferrals`, and\n * `listAllReferrals` (admins), typed from the server plugin. Pass the code\n * at sign-up in the `x-referral-code` header, or as\n * `additionalData.referralCode` of a social sign-in.\n *\n * @example\n * ```ts\n * import { createAuthClient } from \"better-auth/client\";\n * import { referralClient } from \"@checodo/better-auth-referral/client\";\n *\n * export const authClient = createAuthClient({\n *   plugins: [referralClient()],\n * });\n *\n * const { data } = await authClient.referral.createCode();\n * ```\n */\nexport const referralClient = () => {\n  return {\n    id: \"referral\",\n    $InferServerPlugin: {} as ReferralPlugin,\n    pathMethods: {\n      \"/referral/get-code\": \"GET\",\n      \"/referral/create-code\": \"POST\",\n      \"/referral/regenerate-code\": \"POST\",\n      \"/referral/check-code\": \"GET\",\n      \"/referral/list-referrals\": \"GET\",\n      \"/referral/list-all-referrals\": \"GET\",\n    },\n    $ERROR_CODES: REFERRAL_ERROR_CODES,\n  } satisfies BetterAuthClientPlugin;\n};\n\nexport { REFERRAL_ERROR_CODES } from \"./error-codes\";\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAuBA,MAAa,uBAAuB;CAClC,OAAO;EACL,IAAI;EACJ,oBAAoB,CAAC;EACrB,aAAa;GACX,sBAAsB;GACtB,yBAAyB;GACzB,6BAA6B;GAC7B,wBAAwB;GACxB,4BAA4B;GAC5B,gCAAgC;EAClC;EACA,cAAc;CAChB;AACF"}

package/dist/error-codes-Bw554PRu.js

@@ -0,0 +1,12 @@
+import { defineErrorCodes } from "@better-auth/core/utils/error-codes";
+// src/error-codes.ts
+const REFERRAL_ERROR_CODES = defineErrorCodes({
+	INVALID_REFERRAL_CODE: "This referral code is invalid",
+	UNKNOWN_REFERRAL_STEP: "This referral step is not configured",
+	CODE_GENERATION_FAILED: "Could not generate a unique referral code",
+	METADATA_TOO_LARGE: "The metadata is too large",
+	YOU_ARE_NOT_ALLOWED_TO_LIST_REFERRALS: "You are not allowed to list all referrals"
+});
+export { REFERRAL_ERROR_CODES as t };
+
+//# sourceMappingURL=error-codes-Bw554PRu.js.map

package/dist/error-codes-Bw554PRu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-codes-Bw554PRu.js","names":[],"sources":["../src/error-codes.ts"],"sourcesContent":["import { defineErrorCodes } from \"@better-auth/core/utils/error-codes\";\n\nexport const REFERRAL_ERROR_CODES = defineErrorCodes({\n  INVALID_REFERRAL_CODE: \"This referral code is invalid\",\n  UNKNOWN_REFERRAL_STEP: \"This referral step is not configured\",\n  CODE_GENERATION_FAILED: \"Could not generate a unique referral code\",\n  METADATA_TOO_LARGE: \"The metadata is too large\",\n  YOU_ARE_NOT_ALLOWED_TO_LIST_REFERRALS: \"You are not allowed to list all referrals\",\n});\n\nexport type ReferralErrorCode = keyof typeof REFERRAL_ERROR_CODES;\n"],"mappings":";;AAEA,MAAa,uBAAuB,iBAAiB;CACnD,uBAAuB;CACvB,uBAAuB;CACvB,wBAAwB;CACxB,oBAAoB;CACpB,uCAAuC;AACzC,CAAC"}