# @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`.

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.

This adapter does not participate in sync scheduling or presence transport.

## 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 { auth } from "./auth"; // your betterAuth({ ... }) instance

const authAdapter = createBetterAuthAdapter({ auth });

const user = await authAdapter.getUser(request); // { id, email, name } | null
```

## 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, printing `Auth: better-auth (wired)` when it
finds one. The probe covers each framework's conventional locations, including
SvelteKit's `src/lib/server/auth` and Nuxt's `server/utils/auth`.

Pass `--auth-import <specifier>` when your instance lives somewhere the on-disk
probe cannot see, such as a sibling workspace package. It accepts an alias or
subpath import (`$lib/server/auth`, `@/lib/auth`, `#auth`), a package name, or a
project-relative path (`src/lib/server/auth`) — the first two are emitted
unchanged, the last is rebased to the route file's depth.

## 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

MIT