@clivly/auth-workos 0.7.2 → 0.7.4

package/README.md

@@ -1,37 +1,79 @@
 # @clivly/auth-workos
 
-WorkOS implementation of Clivly's `ClivlyAuthAdapter`. It reads the host app's
-AuthKit session cookie, authenticates it through WorkOS, and maps the user into
-Clivly's auth shape.
+[WorkOS](https://workos.com) implementation of Clivly's `ClivlyAuthAdapter`.
+Unseals the host app's AuthKit session cookie to resolve a CRM end-user's
+identity.
 
-## Install
+It answers **"who is this person?"** only. CRM authorization lives separately in
+Clivly's `crm_members` layer.
+
+> **Preview-quality surface.** The user mapper, cookie reader, 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** |
+| `@workos-inc/node` | **≥ 7** — a peer dependency you install yourself |
+| WorkOS credentials | API key, client ID, and the AuthKit cookie password |
+
+## 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 @workos-inc/node
+# → import from "clivly/auth/workos"
+
+# Or standalone
 npm install @clivly/auth-workos @workos-inc/node
+# → import from "@clivly/auth-workos"
 ```
 
-This adapter is a Tier 2 surface in
-[STABILITY.md](https://github.com/amani-joseph/clivly.com/blob/master/STABILITY.md).
-
-## Usage
+## Quick start
 
 ```ts
-import { createWorkOSAuthAdapter } from "@clivly/auth-workos";
+import { createWorkOSAuthAdapter } from "clivly/auth/workos";
 
 const authAdapter = createWorkOSAuthAdapter({
   apiKey: process.env.WORKOS_API_KEY!,
   clientId: process.env.WORKOS_CLIENT_ID!,
   cookiePassword: process.env.WORKOS_COOKIE_PASSWORD!,
-  // optional:
-  // cookieName: "wos-session",
 });
 
-const user = await authAdapter.getUser(request);
-// { id, email, name } | null
+const user = await authAdapter.getUser(request); // { id, email, name } | null
 ```
 
-Returns `null` when there is no session cookie or the WorkOS session does not
-authenticate.
+## Options
+
+| Option | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `apiKey` | `string` | Yes | WorkOS API key (`sk_…`) |
+| `clientId` | `string` | Yes | WorkOS client ID (`client_…`) |
+| `cookiePassword` | `string` | Yes | Password used to unseal the AuthKit session cookie |
+| `cookieName` | `string` | No | Session cookie name. Defaults to `wos-session` |
+
+## Behaviour
+
+- Reads the sealed AuthKit session cookie from the incoming request and unseals
+  it with `cookiePassword`.
+- Returns `null` when the cookie is absent, cannot be unsealed, or the session
+  user has no email address (Clivly requires one).
+- `workosUserToClivlyUser` is exported separately if you already hold a WorkOS
+  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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clivly/auth-workos",
-  "version": "0.7.2",
+  "version": "0.7.4",
   "private": false,
   "type": "module",
   "description": "WorkOS implementation of Clivly's ClivlyAuthAdapter.",
@@ -25,7 +25,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@clivly/core": "0.7.2"
+    "@clivly/core": "0.7.4"
   },
   "peerDependencies": {
     "@workos-inc/node": ">=7"