@clivly/auth-workos 0.8.0 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +61 -6
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,15 +1,46 @@
|
|
|
1
1
|
# @clivly/auth-workos
|
|
2
2
|
|
|
3
|
-
[WorkOS](https://workos.com) implementation of Clivly's `ClivlyAuthAdapter`.
|
|
3
|
+
[WorkOS](https://workos.com) implementation of Clivly's `ClivlyAuthAdapter`.
|
|
4
|
+
Unseals the host app's AuthKit session cookie to resolve a CRM end-user's
|
|
5
|
+
identity.
|
|
4
6
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
> broader host-app compatibility coverage is still growing.
|
|
7
|
+
It answers **"who is this person?"** only. CRM authorization lives separately in
|
|
8
|
+
Clivly's `crm_members` layer.
|
|
8
9
|
|
|
9
|
-
|
|
10
|
+
> **Preview-quality surface.** The user mapper, cookie reader, and session
|
|
11
|
+
> resolution are unit-tested; broader host-app compatibility coverage is still
|
|
12
|
+
> growing.
|
|
13
|
+
|
|
14
|
+
> **Optional.** You do not need an auth adapter to sync data into Clivly. Only
|
|
15
|
+
> reach for one when a Clivly surface must resolve which of *your* users is
|
|
16
|
+
> making a request.
|
|
17
|
+
|
|
18
|
+
## Prerequisites
|
|
19
|
+
|
|
20
|
+
| Requirement | Version / note |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| Node.js | **≥ 22** |
|
|
23
|
+
| `@workos-inc/node` | **≥ 7** — a peer dependency you install yourself |
|
|
24
|
+
| WorkOS credentials | API key, client ID, and the AuthKit cookie password |
|
|
25
|
+
|
|
26
|
+
## Installation
|
|
27
|
+
|
|
28
|
+
Two equivalent import paths — pick whichever matches how you installed Clivly:
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
# If you already installed `clivly` (recommended — this is what `clivly init` does)
|
|
32
|
+
npm install @workos-inc/node
|
|
33
|
+
# → import from "clivly/auth/workos"
|
|
34
|
+
|
|
35
|
+
# Or standalone
|
|
36
|
+
npm install @clivly/auth-workos @workos-inc/node
|
|
37
|
+
# → import from "@clivly/auth-workos"
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Quick start
|
|
10
41
|
|
|
11
42
|
```ts
|
|
12
|
-
import { createWorkOSAuthAdapter } from "
|
|
43
|
+
import { createWorkOSAuthAdapter } from "clivly/auth/workos";
|
|
13
44
|
|
|
14
45
|
const authAdapter = createWorkOSAuthAdapter({
|
|
15
46
|
apiKey: process.env.WORKOS_API_KEY!,
|
|
@@ -20,6 +51,30 @@ const authAdapter = createWorkOSAuthAdapter({
|
|
|
20
51
|
const user = await authAdapter.getUser(request); // { id, email, name } | null
|
|
21
52
|
```
|
|
22
53
|
|
|
54
|
+
## Options
|
|
55
|
+
|
|
56
|
+
| Option | Type | Required | Notes |
|
|
57
|
+
| --- | --- | --- | --- |
|
|
58
|
+
| `apiKey` | `string` | Yes | WorkOS API key (`sk_…`) |
|
|
59
|
+
| `clientId` | `string` | Yes | WorkOS client ID (`client_…`) |
|
|
60
|
+
| `cookiePassword` | `string` | Yes | Password used to unseal the AuthKit session cookie |
|
|
61
|
+
| `cookieName` | `string` | No | Session cookie name. Defaults to `wos-session` |
|
|
62
|
+
|
|
63
|
+
## Behaviour
|
|
64
|
+
|
|
65
|
+
- Reads the sealed AuthKit session cookie from the incoming request and unseals
|
|
66
|
+
it with `cookiePassword`.
|
|
67
|
+
- Returns `null` when the cookie is absent, cannot be unsealed, or the session
|
|
68
|
+
user has no email address (Clivly requires one).
|
|
69
|
+
- `workosUserToClivlyUser` is exported separately if you already hold a WorkOS
|
|
70
|
+
user object and only need the mapping.
|
|
71
|
+
|
|
72
|
+
## Related documentation
|
|
73
|
+
|
|
74
|
+
- **[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
|
|
75
|
+
- [`@clivly/core` README](https://github.com/amani-joseph/clivly.com/blob/master/packages/core/README.md) — the `ClivlyAuthAdapter` contract
|
|
76
|
+
- [`clivly` CLI README](https://github.com/amani-joseph/clivly.com/blob/master/packages/cli/README.md)
|
|
77
|
+
|
|
23
78
|
## License
|
|
24
79
|
|
|
25
80
|
MIT
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@clivly/auth-workos",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "WorkOS implementation of Clivly's ClivlyAuthAdapter.",
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
"access": "public"
|
|
26
26
|
},
|
|
27
27
|
"dependencies": {
|
|
28
|
-
"@clivly/core": "0.
|
|
28
|
+
"@clivly/core": "0.9.0"
|
|
29
29
|
},
|
|
30
30
|
"peerDependencies": {
|
|
31
31
|
"@workos-inc/node": ">=7"
|