@clivly/auth-clerk 0.8.0 → 0.9.1

package/README.md

@@ -1,24 +1,82 @@
 # @clivly/auth-clerk
 
-[Clerk](https://clerk.com) implementation of Clivly's `ClivlyAuthAdapter`. Resolves a CRM end-user's identity from the host app's Clerk session.
+[Clerk](https://clerk.com) implementation of Clivly's `ClivlyAuthAdapter`.
+Resolves a CRM end-user's identity from the host app's Clerk session on each
+request.
 
-> **Preview-quality surface.** Install with `npm install @clivly/auth-clerk`.
-> The email mapper and session resolution are unit-tested; broader host-app
-> compatibility coverage is still growing.
+It answers **"who is this person?"** only. CRM authorization lives separately in
+Clivly's `crm_members` layer.
 
-`@clerk/backend` is a peer dependency.
+> **Preview-quality surface.** The email mapper and session resolution are
+> unit-tested; broader host-app compatibility coverage is still growing.
+
+> **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** |
+| `@clerk/backend` | **≥ 1** — a peer dependency you install yourself |
+| Clerk secret key | `sk_…` from your Clerk dashboard |
+
+## 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)
+npm install @clerk/backend
+# → import from "clivly/auth/clerk"
+
+# Or standalone
+npm install @clivly/auth-clerk @clerk/backend
+# → import from "@clivly/auth-clerk"
+```
+
+## Quick start
 
 ```ts
-import { createClerkAuthAdapter } from "@clivly/auth-clerk";
+import { createClerkAuthAdapter } from "clivly/auth/clerk";
 
 const authAdapter = createClerkAuthAdapter({
   secretKey: process.env.CLERK_SECRET_KEY!,
-  publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
 });
 
 const user = await authAdapter.getUser(request); // { id, email, name } | null
 ```
 
+## Options
+
+| Option | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `secretKey` | `string` | Yes | Clerk secret key (`sk_…`) |
+| `publishableKey` | `string` | No | Clerk publishable key (`pk_…`). Improves handshake reliability |
+| `authorizedParties` | `string[]` | No | Origins allowed to make authenticated requests (CSRF protection) |
+
+```ts
+const authAdapter = createClerkAuthAdapter({
+  secretKey: process.env.CLERK_SECRET_KEY!,
+  publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+  authorizedParties: ["https://app.example.com"],
+});
+```
+
+## Behaviour
+
+- Returns `null` when there is no authenticated session, or when the session
+  user has no email address (Clivly requires one).
+- `clerkUserToClivlyUser` is exported separately if you already hold a Clerk
+  user object and only need the mapping.
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/auth-clerk",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "private": false,
   "type": "module",
   "description": "Clerk implementation of Clivly's ClivlyAuthAdapter.",
@@ -25,7 +25,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@clivly/core": "0.8.0"
+    "@clivly/core": "0.9.1"
   },
   "peerDependencies": {
     "@clerk/backend": ">=1"