clivly 0.7.2 → 0.7.3

package/README.md

@@ -1,40 +1,34 @@
 # clivly
 
-Clivly's consolidated public package.
+Configure and integrate [Clivly](https://clivly.com) — the CRM that lives inside
+your app.
 
-It serves two roles:
+For the full integration path, including when to use `start()` versus
+`runScheduled()` / `createClivlyHandler()`, see the
+[connecting to Clivly Cloud guide](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md).
 
-- the CLI you run as `npx clivly ...`
-- the package that exposes the stable runtime subpaths such as `clivly/sdk`
-
-## Install
+## Usage
 
 ```bash
 npm install clivly
-```
-
-Stable releases publish on npm's `latest` tag. Use `@next` only when you are
-intentionally testing a prerelease build.
 
-This package requires Node `>=22`.
-
-## CLI commands
-
-```bash
-npx clivly init          # scaffold config, route files, and .env placeholders
-npx clivly add widget    # scaffold the chat-session route for the widget
-npx clivly login         # pair this machine and write credentials to .env
+npx clivly init          # scaffold config, routes and .env, then pair this machine
+npx clivly login         # pair this machine and write your credentials to .env
 npx clivly status        # check your setup, step by step
 npx clivly dev           # tunnel localhost so remote sync can reach you
 npx clivly push-schema   # report your schema to Clivly without deploying
 ```
 
-`ping` and `doctor` remain available as focused aliases around parts of the
-`status` ladder.
+`ping` and `doctor` remain as aliases that run subsets of the `status` ladder.
 
-## Runtime imports
+Clivly's stable packages publish on npm's `latest` tag. Once installed, the
+`npx clivly …` commands above use your local copy. Use `@next` only when you
+are intentionally testing a prerelease cut.
 
-Application code should import from subpaths, not from the package root:
+## Imports
+
+`clivly` is the consolidated public package. The CLI remains available as
+`npx clivly`, while application code imports from typed subpaths:
 
 ```ts
 import { createClivlySDK, defineClivlyConfig } from "clivly/sdk";
@@ -45,43 +39,71 @@ import { createWorkOSAuthAdapter } from "clivly/auth/workos";
 import { createBetterAuthAdapter } from "clivly/auth/better-auth";
 ```
 
-Do **not** import application code from `clivly` (the package root). The root
-entry is the CLI.
-
-Provider and framework integrations use optional peer dependencies. Install only
+Provider and framework integrations use optional peer dependencies.
+**Supported auth providers: Clerk, WorkOS, and BetterAuth.** Install only
 what your app actually uses, such as `drizzle-orm`, `vite`, `@clerk/backend`,
 `@workos-inc/node`, or `better-auth`.
 
-## `clivly init`
-
 `clivly init` detects your framework from `package.json`, locates your Drizzle
-schema, and writes:
+schema, and generates a `clivly.config.ts` that maps likely contact and company
+tables. The init command currently generates config for Drizzle only; Prisma and
+Kysely projects should use a hand-written `fetchPage` source for now.
 
-- `clivly.config.ts`
-- the supported Clivly route files for your framework
-- missing `.env` placeholders
+Use `--schema` when your Drizzle schema is not in a common location or in
+`drizzle.config.ts`. Re-run with `--force` to overwrite an existing config.
 
-It currently targets Drizzle-backed integrations. Prisma and Kysely projects
-can still integrate, but should provide hand-written `fetchPage` sources rather
-than relying on the generated Drizzle path.
+### Monorepos
 
-Useful flags:
+In a workspace, `init` reads your `pnpm-workspace.yaml` (or `workspaces` array)
+and imports anything owned by a *sibling* package by **package name** rather than
+by a relative path that climbs out of your app:
+
+```ts
+import * as schema from "@acme/database"; // not "../../packages/database/src/index"
+```
+
+`--schema` accepts a package specifier as well as a path, so all of these work:
+
+```bash
+clivly init --schema @acme/database                  # the package entry
+clivly init --schema @acme/database/src/schema.ts    # a subpath inside it
+clivly init --schema ./src/db/schema.ts              # a plain path (unchanged)
+```
+
+A real file always wins over a same-named package, so existing relative paths
+keep their meaning.
 
 | Flag | Purpose |
 | --- | --- |
-| `--schema <path\|package>` | Where your Drizzle schema lives |
-| `--db-import <specifier>` | Where the Drizzle client lives when it is not beside the schema |
-| `--auth-import <specifier>` | Where your auth instance lives |
-| `--contact-table <name>` | Force the contact entity table |
-| `--company-table <name>` | Force the company entity table |
-| `--force` | Overwrite generated files / `.env` values |
-| `--no-login` | Skip the browser pairing step |
-| `--no-browser` | Print the approval URL instead of opening it |
+| `--schema <path\|package>` | Where your Drizzle tables live. |
+| `--db-import <specifier>` | Where the Drizzle instance lives, when it isn't beside the schema. Accepts `@acme/database#database` to name the export. |
+| `--auth-import <specifier>` | Where your better-auth instance lives. Same `#exportName` form. Overrides on-disk probing, which cannot see across a package boundary. |
+| `--contact-table <name>` | Use this table as the contact entity, skipping the naming heuristics. |
+| `--company-table <name>` | Same for companies. |
+
+`--contact-table` and `--company-table` accept either the SQL table name or the
+name it is exported under in your schema module — whichever you have in front of
+you.
+
+### When no contact entity can be found
 
-If no usable contact entity can be found, `init` writes nothing rather than
-generating a broken config.
+`init` **writes nothing** rather than scaffolding a config that cannot compile.
+Clivly needs one entity before a config will load, and it will not invent one:
+
+```
+No usable contact entity
 
-Supported first-class route scaffolding today:
+  Tables in @acme/database:
+    widgets
+    invoices
+
+  Pick the one that holds your people and re-run:
+    clivly init --schema @acme/database --contact-table widgets
+
+  Nothing was written — Clivly needs one entity before a config can load.
+```
+
+First-class route scaffolding currently exists for:
 
 - Next.js
 - TanStack Start
@@ -89,50 +111,81 @@ Supported first-class route scaffolding today:
 - Remix
 - Nuxt
 
-## `clivly add widget`
+Vue.js apps can still integrate Clivly, but they usually need a manual server
+layer for the tick route unless they are using Nuxt.
+
+When `init` finishes and `CLIVLY_SECRET_KEY` is still empty, it hands you straight
+into `clivly login` so you don't end up staring at a blank `.env`. That step is
+interactive, so it is skipped automatically when there is no TTY or when `CI` is
+set — and you can always turn it off yourself:
 
 ```bash
-npx clivly add widget
+npx clivly init --no-login     # scaffold only; pair later with `clivly login`
+npx clivly init --no-browser   # pair, but print the URL instead of opening it
 ```
 
-Scaffolds the host-side widget session route that mounts
-`createChatSessionHandler()` from `clivly/sdk`. It is idempotent and supports
-`--dry-run` and `--force`.
-
 ## `clivly login`
 
 ```bash
 npx clivly login [--force] [--rotate] [--api-url <url>] [--no-browser]
 ```
 
-Pairs this machine with a Clivly workspace and writes:
-
-- `CLIVLY_SECRET_KEY`
-- `CLIVLY_SYNC_TRIGGER_SECRET`
-
-into your project's `.env`.
-
-The approval URL is always printed, so headless or SSH sessions can still be
-approved in another browser.
-
-Notes:
-
-- `--force` overwrites existing real values
-- `--rotate` rotates the remote-sync trigger secret instead of revealing the
-  current one
-- pairing is feature-flagged server-side with `CLIVLY_CLI_PAIRING_ENABLED`
-
-If pairing is unavailable, you can still set credentials manually and then run
-`clivly status`.
+Pairs this machine with a Clivly workspace and writes `CLIVLY_SECRET_KEY` and
+`CLIVLY_SYNC_TRIGGER_SECRET` into your project's `.env`. It creates a pairing
+session, prints (and by default opens) an approval link, and waits while you
+approve it in a signed-in browser. The approval link is always printed, so an
+SSH or headless session can be approved by opening the link elsewhere.
+
+- `--no-browser` — print the approval URL without opening a browser.
+- `--force` — overwrite `.env` values that already have a real value. Without
+  it, existing values are kept and reported as skipped; an empty placeholder
+  (`CLIVLY_SECRET_KEY=`) is always filled in.
+- `--rotate` — rotate the workspace's remote-sync trigger secret instead of
+  revealing the current one. Your already-deployed host app will stop receiving
+  sync triggers until you redeploy it with the new secret.
+
+Before anything is written, the CLI prints which workspace approved the pairing
+and asks you to confirm. Declining writes nothing and exits non-zero. In a
+non-interactive run (no TTY, or `CI` set) the workspace is still printed but
+you are not prompted, so scripted pairing cannot hang.
+
+The pairing endpoints are feature-flagged server-side
+(`CLIVLY_CLI_PAIRING_ENABLED`); if the backend you point at has not enabled
+them, `clivly login` says so and exits non-zero.
+
+**Clivly Cloud has pairing enabled**, so `clivly login` is the normal path there.
+The flag defaults to `false`, so a self-hosted backend must opt in.
+
+### Manual credential path
+
+If pairing is unavailable — a self-hosted backend with the flag off, or a
+restricted environment — every credential can be set by hand. Nothing about the
+CLI requires pairing.
+
+| Value | Where to get it | Notes |
+| --- | --- | --- |
+| `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. |
+| `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. |
+| `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. |
+
+Write them into the `.env` of the package that imports `clivly`, then re-run
+`clivly status` to confirm each rung goes green.
+
+> **Running your own Clivly backend?** `CLIVLY_TRIGGER_SECRET_WRAPPING_KEY` (a
+> 32-byte hex key) is a **hard production prerequisite** for pairing. The
+> trigger secret is stored encrypted with it, so without the key set on the
+> server, `clivly login` fails with a 500 at the moment it would hand over
+> credentials. Set it before enabling `CLIVLY_CLI_PAIRING_ENABLED`.
 
 ## `clivly status`
 
 ```bash
-npx clivly status [--verbose] [--config <path>] [--env-file <path>]
+npx clivly status [--verbose] [--config <path>]
 ```
 
-Walks the setup one rung at a time: credentials, config, schema, sources, and
-connectivity. This is the main diagnostic command for integration issues.
+Walks your setup one rung at a time — credentials, config, schema, sources,
+connectivity — and stops at the first thing that isn't ready, telling you what
+to do about it. This is the command to reach for when something isn't working.
 
 ## `clivly dev`
 
@@ -141,49 +194,52 @@ npx clivly dev [--port <n>] [--api-url <url>] [--route-path <path>] [-- <cmd>]
 ```
 
 Opens a `cloudflared` tunnel to your local app and registers it with Clivly for
-the lifetime of the session, so remote sync can reach `localhost` during local
-development. The override is cleared on exit.
-
-Requires:
+the length of the session, so remote sync can reach `localhost` while you
+develop. Your dev server is detected from `package.json` scripts, or pass it
+explicitly after `--`. Needs `cloudflared` on `PATH` and `CLIVLY_SECRET_KEY` set.
+The override is cleared when the process exits; remote sync is otherwise
+deploy-only.
 
-- `cloudflared` on `PATH`
-- `CLIVLY_SECRET_KEY` set
+## `clivly ping` / `clivly doctor`
 
-## `clivly push-schema`
+`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`).
 
 ```bash
-npx clivly push-schema [--config <path>]
+CLIVLY_SECRET_KEY=sk_live_… npx clivly ping
+#
+# Clivly ping
+#   ✅ Connected to Clivly
+#      Org: Acme (org_1)
 ```
 
-Reports your discovered schema to Clivly without waiting for a deployed app to
-heartbeat it first.
-
-## `clivly ping` / `clivly doctor`
-
-`clivly ping` sends one heartbeat and prints a terse pass/fail result.
+`clivly doctor` loads your config and runs the same read-only checks as
+`await clivly.doctor()`: API key, entity config, sources, Drizzle cursor/id
+columns, sample fetch, and heartbeat.
 
-`clivly doctor` loads your config and runs the same read-only checks exposed by
-`await clivly.doctor()`.
+```bash
+npx clivly doctor
+npx clivly doctor --config ./apps/web/clivly.config.ts
+```
 
 ## Telemetry
 
-Clivly collects no telemetry. The CLI makes network requests only to the
-Clivly API you point it at, and only to do the work you asked for: pairing,
-heartbeats, schema pushes, status checks, and tunnel override registration.
-
-See the telemetry section in:
-[SECURITY.md](https://github.com/amani-joseph/clivly.com/blob/master/SECURITY.md#telemetry)
+**Clivly collects no telemetry.** The CLI makes network requests only to the
+Clivly API you point it at, and only to do what you asked: pairing, heartbeats,
+schema pushes, and status checks. No usage analytics, no crash reporting, no
+phone-home. See [SECURITY.md](https://github.com/amani-joseph/clivly.com/blob/master/SECURITY.md#telemetry).
 
 ## More docs
 
-- Cloud onboarding guide:
-  [Connecting to Clivly Cloud](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md)
-- Chat widget guide:
-  [Adding the chat widget](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/adding-the-chat-widget.md)
+- Onboarding guide:
+  [connecting to Clivly Cloud](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/connecting-to-clivly-cloud.md)
+- Adding the chat widget:
+  [guide](https://github.com/amani-joseph/clivly.com/blob/master/docs/guides/adding-the-chat-widget.md)
+- Security policy:
+  [SECURITY.md](https://github.com/amani-joseph/clivly.com/blob/master/SECURITY.md)
 - SDK docs:
-  [packages/sdk/README.md](https://github.com/amani-joseph/clivly.com/blob/master/packages/sdk/README.md)
+  [`@clivly/sdk` README](https://github.com/amani-joseph/clivly.com/blob/master/packages/sdk/README.md)
 - Release notes:
-  [CHANGELOG.md](https://github.com/amani-joseph/clivly.com/blob/master/CHANGELOG.md)
+  [CHANGELOG](https://github.com/amani-joseph/clivly.com/blob/master/CHANGELOG.md)
 
 ## License
 

package/drizzle.d.cts

@@ -1,14 +1,6 @@
 import { t as discoverFromDrizzle } from "./drizzle-DmeKSqeF.cjs";
-import { n as SyncSource } from "./types-CsL0rFYh.cjs";
+import { m as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-DRzOtaRT.cjs";
 import { Table } from "drizzle-orm";
-//#region ../sdk/src/namespace-probe.d.ts
-interface NamespaceIntrospector {
-  /** All base table names in the reachable schema. */
-  listTables(): Promise<string[]>;
-  /** Prove a table is genuinely selectable (SELECT ... LIMIT 1). Throws if unreachable/denied. */
-  sampleSelect(table: string): Promise<void>;
-}
-//#endregion
 //#region ../sdk/src/drizzle.d.ts
 interface DrizzleDb {
   select: (...args: any[]) => any;

package/drizzle.d.mts

@@ -1,14 +1,6 @@
 import { t as discoverFromDrizzle } from "./drizzle-CFOr9dU9.mjs";
-import { n as SyncSource } from "./types-CsL0rFYh.mjs";
+import { m as SyncSource, t as NamespaceIntrospector } from "./namespace-probe-B4WE45TH.mjs";
 import { Table } from "drizzle-orm";
-//#region ../sdk/src/namespace-probe.d.ts
-interface NamespaceIntrospector {
-  /** All base table names in the reachable schema. */
-  listTables(): Promise<string[]>;
-  /** Prove a table is genuinely selectable (SELECT ... LIMIT 1). Throws if unreachable/denied. */
-  sampleSelect(table: string): Promise<void>;
-}
-//#endregion
 //#region ../sdk/src/drizzle.d.ts
 interface DrizzleDb {
   select: (...args: any[]) => any;