@clivly/auth-better-auth 0.8.0 → 0.9.1

package/README.md

@@ -1,11 +1,43 @@
 # @clivly/auth-better-auth
 
-[better-auth](https://better-auth.com) implementation of Clivly's `ClivlyAuthAdapter`. Resolves a CRM end-user's identity from the host app's better-auth session via `auth.api.getSession`.
+[better-auth](https://better-auth.com) implementation of Clivly's
+`ClivlyAuthAdapter`. Resolves a CRM end-user's identity from the host app's
+better-auth session via `auth.api.getSession`.
 
-Zero runtime dependencies — you pass your own `betterAuth({...})` instance, so there's no `better-auth` version to keep in lockstep.
+It answers **"who is this person?"** only. CRM authorization lives separately in
+Clivly's `crm_members` layer.
+
+> **Optional.** You do not need an auth adapter to sync data into Clivly. Only
+> reach for one when a Clivly surface must resolve which of *your* users is
+> making a request.
+
+## Prerequisites
+
+| Requirement | Version / note |
+| --- | --- |
+| Node.js | **≥ 22** |
+| A `betterAuth({...})` instance | You pass your own — there is **no peer dependency** and no `better-auth` version to keep in lockstep |
+
+## Installation
+
+Two equivalent import paths — pick whichever matches how you installed Clivly:
+
+```bash
+# If you already installed `clivly` (recommended — this is what `clivly init` does)
+# nothing extra to install
+# → import from "clivly/auth/better-auth"
+
+# Or standalone
+npm install @clivly/auth-better-auth
+# → import from "@clivly/auth-better-auth"
+```
+
+Zero runtime dependencies.
+
+## Quick start
 
 ```ts
-import { createBetterAuthAdapter } from "@clivly/auth-better-auth";
+import { createBetterAuthAdapter } from "clivly/auth/better-auth";
 import { auth } from "./auth"; // your betterAuth({ ... }) instance
 
 const authAdapter = createBetterAuthAdapter({ auth });
@@ -13,7 +45,28 @@ const authAdapter = createBetterAuthAdapter({ auth });
 const user = await authAdapter.getUser(request); // { id, email, name } | null
 ```
 
-Returns `null` when there's no session or the session user has no email (Clivly requires one). The adapter answers "who is this person?" only — CRM authorization lives in Clivly's separate `crm_members` layer.
+## Options
+
+| Option | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `auth` | `BetterAuthLike` | Yes | Anything exposing `api.getSession({ headers })` — your `betterAuth({...})` instance satisfies this structurally |
+
+## Behaviour
+
+- Returns `null` when there is no session, or when the session user has no
+  email address (Clivly requires one).
+- `betterAuthUserToClivlyUser` is exported separately if you already hold a
+  better-auth user object and only need the mapping.
+
+`clivly init` detects a better-auth instance in your project and wires it into
+the scaffolded auth-verify route. Pass `--auth-import <specifier>` when it lives
+across a package boundary the on-disk probe cannot see.
+
+## Related documentation
+
+- **[Connecting to Clivly Cloud](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md#auth-adapters-optional)** — where auth adapters fit in the setup
+- [`@clivly/core` README](https://github.com/amani-joseph/clivly.com/blob/master/packages/core/README.md) — the `ClivlyAuthAdapter` contract
+- [`clivly` CLI README](https://github.com/amani-joseph/clivly.com/blob/master/packages/cli/README.md)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/auth-better-auth",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "private": false,
   "type": "module",
   "description": "better-auth implementation of Clivly's ClivlyAuthAdapter.",
@@ -25,7 +25,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@clivly/core": "0.8.0"
+    "@clivly/core": "0.9.1"
   },
   "devDependencies": {
     "tsdown": "^0.22.14",