sizmo 0.4.0 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
 # sizmo
 
-**Unofficial read-only GoHighLevel CLI for coaches and consultants.**
+**Unofficial read-only GoHighLevel CLI.** Your GoHighLevel CRM — leads, bookings, pipeline, receivables, payments, and a money-ranked to-do list — from the terminal, in one command.
 
 > Not affiliated with, endorsed by, or supported by HighLevel. This is an independent open-source tool.
 
@@ -10,7 +10,16 @@
 
 Requires Node.js 20+.
 
-**Option A — clone + install (puts `sizmo` on your PATH):**
+**Option A — npm (recommended):**
+
+```sh
+npx sizmo brief            # run with no install
+# or install globally:
+npm install -g sizmo
+sizmo brief
+```
+
+**Option B — clone + install (puts `sizmo` on your PATH from source):**
 
 ```sh
 git clone https://github.com/csalamida07-cyber/sizmo-ghl-cli
@@ -20,12 +29,6 @@ bash install.sh
 
 `install.sh` symlinks `bin/sizmo.mjs` into `~/.local/bin/sizmo`. Add `~/.local/bin` to `$PATH` if not already present (the script will warn you if needed).
 
-**Option B — run with no install, straight from GitHub:**
-
-```sh
-npx github:csalamida07-cyber/sizmo-ghl-cli brief
-```
-
 **Option C — clone + run directly:**
 
 ```sh
@@ -33,8 +36,6 @@ git clone https://github.com/csalamida07-cyber/sizmo-ghl-cli && cd sizmo-ghl-cli
 node bin/sizmo.mjs brief
 ```
 
-> `npx sizmo` (npm install) is coming once the package is published to npm.
-
 Then configure a profile:
 
 ```sh
@@ -43,6 +44,17 @@ echo "pit-yourtoken..." | sizmo config set --profile myclient --loc YOUR_LOCATIO
 
 PIT = Private Integration Token. Find it under GoHighLevel Settings > Integrations > Private Integrations. Never pass it as a command-line argument — always pipe it via stdin.
 
+When creating the Private Integration, grant these scopes for the full `brief`:
+
+```
+contacts.readonly · conversations.readonly · opportunities.readonly
+calendars.readonly · invoices.readonly · payments/transactions.readonly
+```
+
+Granting fewer is fine — missing scopes show as ⚠ in affected metrics rather than failing the whole command. Run `sizmo auth check` after setup to see a per-lane scope report.
+
+**Auth: PIT vs MCP** — `sizmo` uses a Private Integration Token (PIT), not the GoHighLevel MCP server. See [`docs/how-to/auth-pit-vs-mcp.md`](docs/how-to/auth-pit-vs-mcp.md) for the comparison and when you'd want each.
+
 Verify auth:
 
 ```sh
@@ -149,4 +161,4 @@ MIT. See LICENSE.
 
 ---
 
-Built by Sizmo — productized GHL systems for coaches & consultants. Unofficial; not affiliated with HighLevel.
+Built by [Sizmo](https://github.com/csalamida07-cyber/sizmo-ghl-cli) — GHL CRM systems & automation. Unofficial; not affiliated with HighLevel.

package/SKILL.md

@@ -28,4 +28,4 @@ Read-only GoHighLevel ops. Every command takes `--json` (stable envelope: `{sche
 - No location resolved → exit 3. Pass `--profile` or set `GHL_LOCATION_ID`; there is no default location.
 
 ---
-Built by Sizmo — productized GHL systems for coaches & consultants. Unofficial; not affiliated with HighLevel.
+Built by Sizmo — GHL CRM systems & automation. Unofficial; not affiliated with HighLevel.

package/docs/how-to/auth-pit-vs-mcp.md

@@ -0,0 +1,77 @@
+# Auth: PIT vs GoHighLevel MCP
+
+Two ways to authenticate with GoHighLevel from external tooling. `sizmo` uses one; here is why, and when you might want the other.
+
+---
+
+## What sizmo uses: PIT (Private Integration Token)
+
+A Private Integration Token is a scoped API credential you create inside your GoHighLevel account under **Settings → Integrations → Private Integrations**. When you create one you choose exactly which API scopes it carries. The token is a long string starting with `pit-`.
+
+Why `sizmo` uses it:
+
+- **Precise scope control.** You decide which scopes are granted — `sizmo` requests read-only scopes only (`contacts.readonly`, `conversations.readonly`, etc.). The token cannot do anything beyond what you explicitly allowed.
+- **Deterministic.** The token is stable and usable in any headless environment — scripts, cron jobs, CI, terminal aliases. No browser, no interactive login flow, no per-session refresh.
+- **Least-privilege.** A read-only PIT cannot create contacts, send messages, charge invoices, or modify workflows. If the token is ever compromised, the blast radius is limited to read access.
+- **No token server required.** The CLI resolves the token from a local profile file or an environment variable. There is no OAuth callback server to run.
+
+**PIT = more control** over what the credential can do.
+
+---
+
+## GoHighLevel also offers an official MCP server
+
+GoHighLevel provides an official MCP (Model Context Protocol) server — the LeadConnector MCP server — as a sanctioned, public feature you can enable inside your GoHighLevel account. Once enabled, MCP clients (such as AI assistants like Claude) can connect to it and perform CRM operations through the MCP protocol.
+
+Key characteristics of GHL's MCP server:
+
+- It is OAuth-connected. Authorization goes through GoHighLevel's standard OAuth flow.
+- It is designed for AI agent and LLM use cases — giving an AI assistant the ability to read and write CRM data through natural language requests.
+- It exposes a broader surface area of CRM operations compared to a scoped read-only PIT.
+
+For information on enabling GoHighLevel's MCP server, refer to [GoHighLevel's official MCP documentation](https://help.gohighlevel.com) (search for "MCP" or "Model Context Protocol" in their help center).
+
+---
+
+## When to use which
+
+| | PIT (what sizmo uses) | GHL MCP server |
+|---|---|---|
+| **Use case** | CLI tools, shell scripts, cron jobs, precise read-only reporting | AI assistants / LLM agents that need to read or write CRM data via natural language |
+| **Auth mechanism** | Static token in local profile or env var | OAuth flow |
+| **Scope control** | Explicit, per-scope — grant only what you need | Managed by the MCP server and OAuth grant |
+| **Headless / scriptable** | Yes — no browser required | Requires initial OAuth browser flow |
+| **Write operations** | Not applicable for sizmo (read-only tool) | Yes — MCP can expose write operations |
+| **Setup** | Create PIT in GHL settings, save with `sizmo config set` | Enable MCP in GHL settings, connect an MCP-capable client |
+
+**Use a PIT** when you want a CLI tool, shell automation, or any situation where you need deterministic, headless, read-only access with explicit scope control. That is what `sizmo auth check` validates.
+
+**Use GHL's MCP server** when you are wiring GoHighLevel into an AI assistant or agent that communicates via the MCP protocol and you want the AI to be able to interact with your CRM through natural language.
+
+The two are not mutually exclusive — you can use `sizmo` for terminal-based reporting alongside an MCP-connected AI assistant in the same GoHighLevel location.
+
+---
+
+## Checking which scopes your PIT has
+
+After setting up a profile, run:
+
+```sh
+sizmo auth check
+```
+
+This probes all six read lanes and reports which scopes are present and which are missing:
+
+```
+auth check: probing 6 GoHighLevel API scopes...
+  ✅ contacts
+  ✅ conversations
+  ✖ opportunities — add scope opportunities.readonly
+  ✅ calendars
+  ✅ invoices
+  ✅ payments
+
+5/6 lanes readable — `brief` will show ⚠ on opportunities until you add: opportunities.readonly
+```
+
+Add the missing scope in your GoHighLevel Private Integration settings, then re-run `sizmo auth check` to confirm.

package/docs/how-to/configure-a-client-profile.md

@@ -4,7 +4,20 @@ A profile stores a PIT (Private Integration Token) and Location ID under a name.
 
 ## Step 1 — get your PIT
 
-In GoHighLevel: Settings → Integrations → Private Integrations → Create. Grant read-only scopes. Copy the token (starts with `pit-`).
+In GoHighLevel: Settings → Integrations → Private Integrations → Create. Copy the token (starts with `pit-`).
+
+Grant the following scopes when creating the integration (minimum set for a full `brief`):
+
+```
+contacts.readonly
+conversations.readonly
+opportunities.readonly
+calendars.readonly
+invoices.readonly
+payments/transactions.readonly
+```
+
+Grant all six for the complete `brief`. Granting fewer is fine — any missing scope shows as ⚠ in the affected metric rather than hard-failing. Run `sizmo auth check` after setup to see exactly which lanes are readable and which scopes are still needed.
 
 ## Step 2 — find your Location ID
 

package/lib/cli.mjs

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { registry } from './registry.mjs';
 import { resolve, loadProfiles, saveProfiles, validateToken, mask, pitAgeDays } from './config.mjs';
 import { makeHttp } from './http.mjs';
+import { mapLimit } from './pool.mjs';
 import { buildCtx } from './context.mjs';
 import { buildSchema } from './schema.mjs';
 import { GhlError, EXIT } from './errors.mjs';
@@ -92,24 +93,77 @@ async function routerVerb(cmd, args, io) {
   // ── auth ────────────────────────────────────────────────────────────────────
   if (cmd === 'auth') {
     if (verb === 'check') {
-      // auth check: verify PIT scopes by probing the API directly
+      // auth check: per-lane scope diagnostic — probes all fleet read lanes concurrently.
+      // Rule: 401/403 = scope MISSING; 200 or 4xx param error (400/422) = scope PRESENT.
+      // Exit 0 if contacts lane is readable (tool is usable); per-lane ✖ lines guide the user.
       const creds = resolve(profile);
       if (!creds.pit) return die('no credentials found', EXIT.AUTH, 'set GHL_PIT, or: sizmo config set --profile <name> --pit-stdin');
       if (!creds.loc) return die('no location resolved', EXIT.AUTH, 'pass --profile <name>, or set GHL_LOCATION_ID');
-      write('auth check: probing GoHighLevel API scopes...\n');
+
+      const loc = creds.loc;
+      const LANES = [
+        { name: 'contacts',      scope: 'contacts.readonly',             path: `/contacts/?locationId=${loc}&limit=1` },
+        { name: 'conversations', scope: 'conversations.readonly',        path: `/conversations/search?locationId=${loc}&limit=1` },
+        { name: 'opportunities', scope: 'opportunities.readonly',        path: `/opportunities/search?location_id=${loc}&limit=1` },
+        { name: 'calendars',     scope: 'calendars.readonly',            path: `/calendars/?locationId=${loc}` },
+        { name: 'invoices',      scope: 'invoices.readonly',             path: `/invoices/?altId=${loc}&altType=location&limit=1` },
+        { name: 'payments',      scope: 'payments/transactions.readonly', path: `/payments/transactions?altId=${loc}&altType=location&limit=1` },
+      ];
+
+      if (!json) write(`auth check: probing ${LANES.length} GoHighLevel API scopes...\n`);
+
+      let lanes;
       try {
         const http = makeHttp({ pit: creds.pit });
-        const result = await validateToken(http, creds.loc);
-        if (!result.ok) {
-          writeErr(`WARN: token check failed — ${result.reason}\n`);
-          return EXIT.AUTH;
-        }
-        write(`auth check: PIT accepted for location ${creds.loc}\n`);
-        return EXIT.OK;
+        lanes = await mapLimit(LANES, 5, async (lane) => {
+          try {
+            const r = await http.get(lane.path);
+            // 401/403 = scope blocked; 200 or param-error (400/422) = authorized
+            const ok = r.code !== 401 && r.code !== 403;
+            return { name: lane.name, scope: lane.scope, ok, code: r.code };
+          } catch (e) {
+            return { name: lane.name, scope: lane.scope, ok: false, code: 0, error: e?.message ?? 'error' };
+          }
+        });
       } catch (e) {
         writeErr(`auth check: could not reach GoHighLevel (${e?.message ?? 'error'})\n`);
         return EXIT.API;
       }
+
+      const okCount = lanes.filter(l => l.ok).length;
+      const total = lanes.length;
+
+      if (json) {
+        const contactsOk = lanes.find(l => l.name === 'contacts')?.ok ?? false;
+        write(JSON.stringify({
+          schemaVersion: 1,
+          location: loc,
+          lanes: lanes.map(l => ({ name: l.name, scope: l.scope, ok: l.ok, httpCode: l.code })),
+          summary: `${okCount}/${total} lanes readable`,
+          usable: contactsOk,
+        }) + '\n');
+        return contactsOk ? EXIT.OK : EXIT.AUTH;
+      }
+
+      // human output — per-lane lines then summary
+      for (const l of lanes) {
+        if (l.ok) {
+          write(`  ✅ ${l.name}\n`);
+        } else {
+          writeErr(`  ✖ ${l.name} — add scope ${l.scope}\n`);
+        }
+      }
+
+      const missing = lanes.filter(l => !l.ok).map(l => l.scope);
+      if (missing.length === 0) {
+        write(`\n${okCount}/${total} lanes readable — full brief available\n`);
+      } else {
+        const missingNames = lanes.filter(l => !l.ok).map(l => l.name).join(', ');
+        writeErr(`\n${okCount}/${total} lanes readable — \`brief\` will show ⚠ on ${missingNames} until you add: ${missing.join(', ')}\n`);
+      }
+
+      const contactsOk = lanes.find(l => l.name === 'contacts')?.ok ?? false;
+      return contactsOk ? EXIT.OK : EXIT.AUTH;
     }
     if (verb !== 'status') return die('usage: sizmo auth status|check', EXIT.USAGE);
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sizmo",
-  "version": "0.4.0",
-  "description": "Unofficial read-only GoHighLevel CLI for coaches and consultants. Not affiliated with HighLevel.",
+  "version": "0.4.1",
+  "description": "Unofficial read-only GoHighLevel CLI — read your CRM (leads, bookings, pipeline, A/R, payments) from the terminal. Not affiliated with HighLevel.",
   "type": "module",
   "bin": {
     "sizmo": "bin/sizmo.mjs"