clivly 0.7.1 → 0.7.2

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.
Files changed (2) hide show
  1. package/README.md +103 -159
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,34 +1,40 @@
1
1
  # clivly
2
2
 
3
- Configure and integrate [Clivly](https://clivly.com) — the CRM that lives inside
4
- your app.
3
+ Clivly's consolidated public package.
5
4
 
6
- For the full integration path, including when to use `start()` versus
7
- `runScheduled()` / `createClivlyHandler()`, see the
8
- [connecting to Clivly Cloud guide](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md).
5
+ It serves two roles:
9
6
 
10
- ## Usage
7
+ - the CLI you run as `npx clivly ...`
8
+ - the package that exposes the stable runtime subpaths such as `clivly/sdk`
9
+
10
+ ## Install
11
11
 
12
12
  ```bash
13
13
  npm install clivly
14
+ ```
15
+
16
+ Stable releases publish on npm's `latest` tag. Use `@next` only when you are
17
+ intentionally testing a prerelease build.
14
18
 
15
- npx clivly init # scaffold config, routes and .env, then pair this machine
16
- npx clivly login # pair this machine and write your credentials to .env
19
+ This package requires Node `>=22`.
20
+
21
+ ## CLI commands
22
+
23
+ ```bash
24
+ npx clivly init # scaffold config, route files, and .env placeholders
25
+ npx clivly add widget # scaffold the chat-session route for the widget
26
+ npx clivly login # pair this machine and write credentials to .env
17
27
  npx clivly status # check your setup, step by step
18
28
  npx clivly dev # tunnel localhost so remote sync can reach you
19
29
  npx clivly push-schema # report your schema to Clivly without deploying
20
30
  ```
21
31
 
22
- `ping` and `doctor` remain as aliases that run subsets of the `status` ladder.
32
+ `ping` and `doctor` remain available as focused aliases around parts of the
33
+ `status` ladder.
23
34
 
24
- Clivly's stable packages publish on npm's `latest` tag. Once installed, the
25
- `npx clivly …` commands above use your local copy. Use `@next` only when you
26
- are intentionally testing a prerelease cut.
35
+ ## Runtime imports
27
36
 
28
- ## Imports
29
-
30
- `clivly` is the consolidated public package. The CLI remains available as
31
- `npx clivly`, while application code imports from typed subpaths:
37
+ Application code should import from subpaths, not from the package root:
32
38
 
33
39
  ```ts
34
40
  import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
@@ -39,71 +45,43 @@ import { createWorkOSAuthAdapter } from "clivly/auth/workos";
39
45
  import { createBetterAuthAdapter } from "clivly/auth/better-auth";
40
46
  ```
41
47
 
42
- Provider and framework integrations use optional peer dependencies.
43
- **Supported auth providers: Clerk, WorkOS, and BetterAuth.** Install only
48
+ Do **not** import application code from `clivly` (the package root). The root
49
+ entry is the CLI.
50
+
51
+ Provider and framework integrations use optional peer dependencies. Install only
44
52
  what your app actually uses, such as `drizzle-orm`, `vite`, `@clerk/backend`,
45
53
  `@workos-inc/node`, or `better-auth`.
46
54
 
47
- `clivly init` detects your framework from `package.json`, locates your Drizzle
48
- schema, and generates a `clivly.config.ts` that maps likely contact and company
49
- tables. The init command currently generates config for Drizzle only; Prisma and
50
- Kysely projects should use a hand-written `fetchPage` source for now.
51
-
52
- Use `--schema` when your Drizzle schema is not in a common location or in
53
- `drizzle.config.ts`. Re-run with `--force` to overwrite an existing config.
54
-
55
- ### Monorepos
55
+ ## `clivly init`
56
56
 
57
- In a workspace, `init` reads your `pnpm-workspace.yaml` (or `workspaces` array)
58
- and imports anything owned by a *sibling* package by **package name** rather than
59
- by a relative path that climbs out of your app:
60
-
61
- ```ts
62
- import * as schema from "@acme/database"; // not "../../packages/database/src/index"
63
- ```
57
+ `clivly init` detects your framework from `package.json`, locates your Drizzle
58
+ schema, and writes:
64
59
 
65
- `--schema` accepts a package specifier as well as a path, so all of these work:
60
+ - `clivly.config.ts`
61
+ - the supported Clivly route files for your framework
62
+ - missing `.env` placeholders
66
63
 
67
- ```bash
68
- clivly init --schema @acme/database # the package entry
69
- clivly init --schema @acme/database/src/schema.ts # a subpath inside it
70
- clivly init --schema ./src/db/schema.ts # a plain path (unchanged)
71
- ```
64
+ It currently targets Drizzle-backed integrations. Prisma and Kysely projects
65
+ can still integrate, but should provide hand-written `fetchPage` sources rather
66
+ than relying on the generated Drizzle path.
72
67
 
73
- A real file always wins over a same-named package, so existing relative paths
74
- keep their meaning.
68
+ Useful flags:
75
69
 
76
70
  | Flag | Purpose |
77
71
  | --- | --- |
78
- | `--schema <path\|package>` | Where your Drizzle tables live. |
79
- | `--db-import <specifier>` | Where the Drizzle instance lives, when it isn't beside the schema. Accepts `@acme/database#database` to name the export. |
80
- | `--auth-import <specifier>` | Where your better-auth instance lives. Same `#exportName` form. Overrides on-disk probing, which cannot see across a package boundary. |
81
- | `--contact-table <name>` | Use this table as the contact entity, skipping the naming heuristics. |
82
- | `--company-table <name>` | Same for companies. |
83
-
84
- `--contact-table` and `--company-table` accept either the SQL table name or the
85
- name it is exported under in your schema module — whichever you have in front of
86
- you.
87
-
88
- ### When no contact entity can be found
72
+ | `--schema <path\|package>` | Where your Drizzle schema lives |
73
+ | `--db-import <specifier>` | Where the Drizzle client lives when it is not beside the schema |
74
+ | `--auth-import <specifier>` | Where your auth instance lives |
75
+ | `--contact-table <name>` | Force the contact entity table |
76
+ | `--company-table <name>` | Force the company entity table |
77
+ | `--force` | Overwrite generated files / `.env` values |
78
+ | `--no-login` | Skip the browser pairing step |
79
+ | `--no-browser` | Print the approval URL instead of opening it |
89
80
 
90
- `init` **writes nothing** rather than scaffolding a config that cannot compile.
91
- Clivly needs one entity before a config will load, and it will not invent one:
92
-
93
- ```
94
- No usable contact entity
81
+ If no usable contact entity can be found, `init` writes nothing rather than
82
+ generating a broken config.
95
83
 
96
- Tables in @acme/database:
97
- widgets
98
- invoices
99
-
100
- Pick the one that holds your people and re-run:
101
- clivly init --schema @acme/database --contact-table widgets
102
-
103
- Nothing was written — Clivly needs one entity before a config can load.
104
- ```
105
-
106
- First-class route scaffolding currently exists for:
84
+ Supported first-class route scaffolding today:
107
85
 
108
86
  - Next.js
109
87
  - TanStack Start
@@ -111,81 +89,50 @@ First-class route scaffolding currently exists for:
111
89
  - Remix
112
90
  - Nuxt
113
91
 
114
- Vue.js apps can still integrate Clivly, but they usually need a manual server
115
- layer for the tick route unless they are using Nuxt.
116
-
117
- When `init` finishes and `CLIVLY_SECRET_KEY` is still empty, it hands you straight
118
- into `clivly login` so you don't end up staring at a blank `.env`. That step is
119
- interactive, so it is skipped automatically when there is no TTY or when `CI` is
120
- set — and you can always turn it off yourself:
92
+ ## `clivly add widget`
121
93
 
122
94
  ```bash
123
- npx clivly init --no-login # scaffold only; pair later with `clivly login`
124
- npx clivly init --no-browser # pair, but print the URL instead of opening it
95
+ npx clivly add widget
125
96
  ```
126
97
 
98
+ Scaffolds the host-side widget session route that mounts
99
+ `createChatSessionHandler()` from `clivly/sdk`. It is idempotent and supports
100
+ `--dry-run` and `--force`.
101
+
127
102
  ## `clivly login`
128
103
 
129
104
  ```bash
130
105
  npx clivly login [--force] [--rotate] [--api-url <url>] [--no-browser]
131
106
  ```
132
107
 
133
- Pairs this machine with a Clivly workspace and writes `CLIVLY_SECRET_KEY` and
134
- `CLIVLY_SYNC_TRIGGER_SECRET` into your project's `.env`. It creates a pairing
135
- session, prints (and by default opens) an approval link, and waits while you
136
- approve it in a signed-in browser. The approval link is always printed, so an
137
- SSH or headless session can be approved by opening the link elsewhere.
138
-
139
- - `--no-browser` — print the approval URL without opening a browser.
140
- - `--force` — overwrite `.env` values that already have a real value. Without
141
- it, existing values are kept and reported as skipped; an empty placeholder
142
- (`CLIVLY_SECRET_KEY=`) is always filled in.
143
- - `--rotate` — rotate the workspace's remote-sync trigger secret instead of
144
- revealing the current one. Your already-deployed host app will stop receiving
145
- sync triggers until you redeploy it with the new secret.
146
-
147
- Before anything is written, the CLI prints which workspace approved the pairing
148
- and asks you to confirm. Declining writes nothing and exits non-zero. In a
149
- non-interactive run (no TTY, or `CI` set) the workspace is still printed but
150
- you are not prompted, so scripted pairing cannot hang.
151
-
152
- The pairing endpoints are feature-flagged server-side
153
- (`CLIVLY_CLI_PAIRING_ENABLED`); if the backend you point at has not enabled
154
- them, `clivly login` says so and exits non-zero.
155
-
156
- **Clivly Cloud has pairing enabled**, so `clivly login` is the normal path there.
157
- The flag defaults to `false`, so a self-hosted backend must opt in.
158
-
159
- ### Manual credential path
160
-
161
- If pairing is unavailable — a self-hosted backend with the flag off, or a
162
- restricted environment — every credential can be set by hand. Nothing about the
163
- CLI requires pairing.
164
-
165
- | Value | Where to get it | Notes |
166
- | --- | --- | --- |
167
- | `CLIVLY_SECRET_KEY` | Dashboard → **Settings → API keys** → Create | **Shown once.** Copy it immediately; you cannot retrieve it later, only regenerate. Regenerating **revokes the previous key**, so redeploy after rotating. The legacy name `CLIVLY_API_KEY` is still accepted as a fallback. |
168
- | `CLIVLY_SYNC_TRIGGER_SECRET` | Dashboard → **Integrations → Remote sync** | Must match the value in your app's env exactly. A mismatch surfaces as a `401` on the signed trigger. |
169
- | `CLIVLY_SYNC_TRIGGER_URL` | Your own deployment | The public URL of your mounted tick route, e.g. `https://app.example.com/api/clivly/tick`. Optional until you deploy — push-only setups can leave it unset. |
170
-
171
- Write them into the `.env` of the package that imports `clivly`, then re-run
172
- `clivly status` to confirm each rung goes green.
173
-
174
- > **Running your own Clivly backend?** `CLIVLY_TRIGGER_SECRET_WRAPPING_KEY` (a
175
- > 32-byte hex key) is a **hard production prerequisite** for pairing. The
176
- > trigger secret is stored encrypted with it, so without the key set on the
177
- > server, `clivly login` fails with a 500 at the moment it would hand over
178
- > credentials. Set it before enabling `CLIVLY_CLI_PAIRING_ENABLED`.
108
+ Pairs this machine with a Clivly workspace and writes:
109
+
110
+ - `CLIVLY_SECRET_KEY`
111
+ - `CLIVLY_SYNC_TRIGGER_SECRET`
112
+
113
+ into your project's `.env`.
114
+
115
+ The approval URL is always printed, so headless or SSH sessions can still be
116
+ approved in another browser.
117
+
118
+ Notes:
119
+
120
+ - `--force` overwrites existing real values
121
+ - `--rotate` rotates the remote-sync trigger secret instead of revealing the
122
+ current one
123
+ - pairing is feature-flagged server-side with `CLIVLY_CLI_PAIRING_ENABLED`
124
+
125
+ If pairing is unavailable, you can still set credentials manually and then run
126
+ `clivly status`.
179
127
 
180
128
  ## `clivly status`
181
129
 
182
130
  ```bash
183
- npx clivly status [--verbose] [--config <path>]
131
+ npx clivly status [--verbose] [--config <path>] [--env-file <path>]
184
132
  ```
185
133
 
186
- Walks your setup one rung at a time — credentials, config, schema, sources,
187
- connectivity — and stops at the first thing that isn't ready, telling you what
188
- to do about it. This is the command to reach for when something isn't working.
134
+ Walks the setup one rung at a time: credentials, config, schema, sources, and
135
+ connectivity. This is the main diagnostic command for integration issues.
189
136
 
190
137
  ## `clivly dev`
191
138
 
@@ -194,52 +141,49 @@ npx clivly dev [--port <n>] [--api-url <url>] [--route-path <path>] [-- <cmd>]
194
141
  ```
195
142
 
196
143
  Opens a `cloudflared` tunnel to your local app and registers it with Clivly for
197
- the length of the session, so remote sync can reach `localhost` while you
198
- develop. Your dev server is detected from `package.json` scripts, or pass it
199
- explicitly after `--`. Needs `cloudflared` on `PATH` and `CLIVLY_SECRET_KEY` set.
200
- The override is cleared when the process exits; remote sync is otherwise
201
- deploy-only.
144
+ the lifetime of the session, so remote sync can reach `localhost` during local
145
+ development. The override is cleared on exit.
202
146
 
203
- ## `clivly ping` / `clivly doctor`
147
+ Requires:
204
148
 
205
- `clivly ping` reads `CLIVLY_SECRET_KEY` from the environment, sends one heartbeat, and prints a clear ✅/❌ with the resolved org or the failure reason — so you can confirm a connection from the terminal without writing any code. Point it at a non-default backend with `--api-url <url>` (or `CLIVLY_API_URL`).
149
+ - `cloudflared` on `PATH`
150
+ - `CLIVLY_SECRET_KEY` set
151
+
152
+ ## `clivly push-schema`
206
153
 
207
154
  ```bash
208
- CLIVLY_SECRET_KEY=sk_live_… npx clivly ping
209
- #
210
- # Clivly ping
211
- # ✅ Connected to Clivly
212
- # Org: Acme (org_1)
155
+ npx clivly push-schema [--config <path>]
213
156
  ```
214
157
 
215
- `clivly doctor` loads your config and runs the same read-only checks as
216
- `await clivly.doctor()`: API key, entity config, sources, Drizzle cursor/id
217
- columns, sample fetch, and heartbeat.
158
+ Reports your discovered schema to Clivly without waiting for a deployed app to
159
+ heartbeat it first.
218
160
 
219
- ```bash
220
- npx clivly doctor
221
- npx clivly doctor --config ./apps/web/clivly.config.ts
222
- ```
161
+ ## `clivly ping` / `clivly doctor`
162
+
163
+ `clivly ping` sends one heartbeat and prints a terse pass/fail result.
164
+
165
+ `clivly doctor` loads your config and runs the same read-only checks exposed by
166
+ `await clivly.doctor()`.
223
167
 
224
168
  ## Telemetry
225
169
 
226
- **Clivly collects no telemetry.** The CLI makes network requests only to the
227
- Clivly API you point it at, and only to do what you asked: pairing, heartbeats,
228
- schema pushes, and status checks. No usage analytics, no crash reporting, no
229
- phone-home. See [SECURITY.md](https://github.com/amani-joseph/clivly.com/blob/master/SECURITY.md#telemetry).
170
+ Clivly collects no telemetry. The CLI makes network requests only to the
171
+ Clivly API you point it at, and only to do the work you asked for: pairing,
172
+ heartbeats, schema pushes, status checks, and tunnel override registration.
173
+
174
+ See the telemetry section in:
175
+ [SECURITY.md](https://github.com/amani-joseph/clivly.com/blob/master/SECURITY.md#telemetry)
230
176
 
231
177
  ## More docs
232
178
 
233
- - Onboarding guide:
234
- [connecting to Clivly Cloud](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md)
235
- - Adding the chat widget:
236
- [guide](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/adding-the-chat-widget.md)
237
- - Security policy:
238
- [SECURITY.md](https://github.com/amani-joseph/clivly.com/blob/master/SECURITY.md)
179
+ - Cloud onboarding guide:
180
+ [Connecting to Clivly Cloud](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md)
181
+ - Chat widget guide:
182
+ [Adding the chat widget](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/adding-the-chat-widget.md)
239
183
  - SDK docs:
240
- [`@clivly/sdk` README](https://github.com/amani-joseph/clivly.com/blob/master/packages/sdk/README.md)
184
+ [packages/sdk/README.md](https://github.com/amani-joseph/clivly.com/blob/master/packages/sdk/README.md)
241
185
  - Release notes:
242
- [CHANGELOG](https://github.com/amani-joseph/clivly.com/blob/master/CHANGELOG.md)
186
+ [CHANGELOG.md](https://github.com/amani-joseph/clivly.com/blob/master/CHANGELOG.md)
243
187
 
244
188
  ## License
245
189
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "clivly",
3
- "version": "0.7.1",
3
+ "version": "0.7.2",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "Clivly CLI — scaffold a CRM into your app (clivly init).",