sizmo 0.4.0

package/docs/how-to/multi-client.md

@@ -0,0 +1,86 @@
+# Multi-client workflow
+
+`sizmo` supports multiple GoHighLevel locations via named profiles. Each profile holds one PIT and one Location ID.
+
+## Setup — one profile per client
+
+```sh
+echo "pit-clientA..." | sizmo config set --profile clientA --loc LOC_A --pit-stdin
+echo "pit-clientB..." | sizmo config set --profile clientB --loc LOC_B --pit-stdin
+echo "pit-clientC..." | sizmo config set --profile clientC --loc LOC_C --pit-stdin
+```
+
+## Check all profiles
+
+```sh
+sizmo config list
+```
+
+Output (verified format from `lib/cli.mjs`):
+
+```
+* clientA         loc LOC_A   pit-…AAAA  day 12/90
+  clientB         loc LOC_B   pit-…BBBB  day 8/90
+  clientC         loc LOC_C   pit-…CCCC  day 45/90
+```
+
+`*` marks the default profile (used when `--profile` is not passed).
+
+## Switch default
+
+```sh
+sizmo config use clientB
+```
+
+## Run a command against a specific client
+
+Pass `--profile` to any command:
+
+```sh
+sizmo brief --profile clientA
+sizmo brief --profile clientB
+sizmo receivables --profile clientC --top 10
+```
+
+## Morning sweep across all clients
+
+There is no built-in "run all profiles" command. Use a shell loop:
+
+```sh
+for p in clientA clientB clientC; do
+  echo "=== $p ===";
+  sizmo brief --profile $p --json;
+done
+```
+
+Or with `--json` piped to a processor:
+
+```sh
+for p in clientA clientB clientC; do
+  sizmo snapshot --profile $p --json
+done
+```
+
+## PIT rotation per client
+
+Each PIT expires at 90 days. `sizmo config list` shows `day N/90` for each. Rotate before day 80:
+
+```sh
+echo "pit-newtoken..." | sizmo config set --profile clientA --pit-stdin --created $(date +%Y-%m-%d)
+sizmo auth check --profile clientA
+```
+
+## JSON output for automation
+
+Every command supports `--json --profile <name>`. The envelope includes `"location"` so you can route results by location ID in your processing code:
+
+```json
+{
+  "schemaVersion": 1,
+  "command": "snapshot",
+  "location": "LOC_A",
+  "data": { ... },
+  "degraded": false,
+  "warnings": []
+}
+```

package/docs/how-to/noshow.md

@@ -0,0 +1,45 @@
+# noshow — no-show recovery
+
+## What it answers
+
+"Who no-showed and hasn't been re-booked?" Lists contacts whose appointment status is `no-show` within the lookback window, so you can follow up and get them rescheduled.
+
+## Command
+
+```sh
+sizmo noshow
+sizmo noshow --days 14         # last 14 days
+sizmo noshow --top 20          # show up to 20
+sizmo noshow --json
+sizmo noshow --profile myclient
+```
+
+Flags (verified from `meta` in `commands/noshow.mjs`):
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--days` | int | 30 | Lookback window |
+| `--top` | int | 15 | Max results |
+
+## How it works
+
+Fetches all calendars for the location, then fetches events for each calendar within the window. Events with status `no-show` are collected, deduplicated by contact, and sorted by most recent occurrence.
+
+**Known limitation:** GHL's `/calendars/events` endpoint does not support cursor-based pagination. If a calendar returns >= 100 events the result may be silently truncated. The CLI emits `degraded: true` with a warning when this threshold is hit. Full fix (date-window splitting) is tracked as a follow-up.
+
+## Sample output shape (example — no live creds in this context)
+
+```
+  NO-SHOWS (last 30d)
+  1. Carlo Reyes       3d ago    Calendar: Consultation
+  2. Ana Lim           8d ago    Calendar: Strategy Call
+  3. Bong Santos       12d ago   Calendar: Consultation
+```
+
+*Sample shape only.*
+
+## Notes
+
+- The CLI never sends a message or re-books the appointment. Use this list to identify who to contact; the action stays with you.
+- If `degraded: true` appears in `--json` output, at least one calendar was truncated or blocked. The list is incomplete.
+- Contacts may appear once per no-show event. If someone no-showed twice, they may appear twice.

package/docs/how-to/pipeline.md

@@ -0,0 +1,47 @@
+# pipeline — pipeline health
+
+## What it answers
+
+"How much value is in each stage, and which deals are stuck?" Shows total opportunity value by pipeline stage plus a stuck-deal sweep listing deals that haven't moved in N days.
+
+## Command
+
+```sh
+sizmo pipeline
+sizmo pipeline --stuck-days 14     # flag deals idle for 14+ days
+sizmo pipeline --top 20            # show top 20 stuck deals
+sizmo pipeline --json
+sizmo pipeline --profile myclient
+```
+
+Flags (verified from `meta` in `commands/pipeline.mjs`):
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--stuck-days` | int | 7 | Idle threshold in days |
+| `--top` | int | 100 | Max stuck deals to show |
+
+## How it works
+
+Paginates all opportunities to completion before sorting. A deal is "stuck" when its last status change, stage change, or update timestamp is older than `--stuck-days`. The stuck sweep shows value, stage, and idle age per deal.
+
+## Sample output shape (example — no live creds in this context)
+
+```
+  PIPELINE VALUE BY STAGE
+  Discovery          ₱85,000   (4 deals)
+  Proposal           ₱140,000  (3 deals)
+  Closed Won         ₱32,000   (2 deals)
+
+  STUCK DEALS (idle > 7d)
+  1. Maria Santos      Proposal    ₱45,000    idle 12d
+  2. Juan dela Cruz    Discovery   ₱22,000    idle 9d
+```
+
+*Sample shape only.*
+
+## Notes
+
+- GHL opportunity `monetaryValue` has no currency field — it inherits the pipeline configuration. The CLI renders the raw value; no currency conversion is performed.
+- `--top N` caps the stuck-deal list. All opportunities are fetched before the cap is applied.
+- A deal last touched via `lastStatusChangeAt`, `lastStageChangeAt`, `updatedAt`, `dateUpdated`, or `dateAdded` (in that priority order) — whichever is most recent.

package/docs/how-to/receivables.md

@@ -0,0 +1,45 @@
+# receivables — A/R who owes
+
+## What it answers
+
+"Who owes money, how much, and how old is the invoice?" Lists all outstanding invoices (status: sent, overdue, partially paid, payment processing, viewed, due) sorted by age descending.
+
+## Command
+
+```sh
+sizmo receivables
+sizmo receivables --top 30     # show up to 30 invoices
+sizmo receivables --json
+sizmo receivables --profile myclient
+```
+
+Flags (verified from `meta` in `commands/receivables.mjs`):
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--top` | int | 20 | Max rows to display |
+
+## How it works
+
+Paginates all invoices to completion (was previously offset-capped at 2000 — that bug is fixed). Filters to unpaid statuses. Per-currency totals are calculated separately — PHP, USD, EUR, GBP are never cross-summed.
+
+Unpaid statuses: `sent`, `overdue`, `partially_paid`, `partially paid`, `payment_processing`, `viewed`, `due`.
+
+## Sample output shape (example — no live creds in this context)
+
+```
+  A/R — outstanding invoices
+  1. Juan dela Cruz     ₱25,000   21d   overdue
+  2. Maria Santos       ₱18,000   14d   sent
+  3. Carlo Reyes        ₱8,500    7d    viewed
+
+  TOTAL: ₱51,500 (PHP)
+```
+
+*Sample shape only.*
+
+## Notes
+
+- The CLI never sends an invoice or charges a card. To follow up, use GoHighLevel's invoice tools or your approved agent workflow.
+- Per-currency totals are always separated. If your location has both PHP and USD invoices, each currency totals independently.
+- `--top N` caps the display list. All invoices are fetched before the cap is applied.

package/docs/how-to/reconcile.md

@@ -0,0 +1,52 @@
+# reconcile — money collected by source
+
+## What it answers
+
+"How much was collected, from which payment sources, and are there any flags?" Breaks down successful transactions by payment provider/source within a window. Also surfaces subscriptions and anomaly flags.
+
+## Command
+
+```sh
+sizmo reconcile
+sizmo reconcile --days 7       # last 7 days
+sizmo reconcile --top 30       # show top 30 sources
+sizmo reconcile --json
+sizmo reconcile --profile myclient
+```
+
+Flags (verified from `meta` in `commands/reconcile.mjs`):
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--days` | int | 30 | Window in days |
+| `--top` | int | 20 | Max source rows |
+
+## How it works
+
+Paginates both transactions and subscriptions to completion. Groups successful transactions by source (payment provider, entity source type, or charge snapshot provider — whichever is available). Per-currency totals are kept separate. Flags transactions that look anomalous (e.g. unusually large amounts, missing source attribution).
+
+Successful statuses: `succeeded`, `success`, `paid`, `completed`, `captured`.
+
+## Sample output shape (example — no live creds in this context)
+
+```
+  COLLECTED — last 30d
+
+  SOURCE             PHP          COUNT
+  stripe             ₱120,000     8
+  manual             ₱45,000      3
+  unknown            ₱8,000       1
+
+  TOTAL: ₱173,000 (PHP)
+
+  RECURRING SUBSCRIPTIONS: 4 active
+```
+
+*Sample shape only.*
+
+## Notes
+
+- The CLI never refunds, voids, or charges. Read-only.
+- Per-currency totals are always separate — never cross-summed.
+- Source attribution relies on GHL's `paymentProviderType`, `providerType`, `source`, or `entitySourceType` fields. Transactions without any of these show as `unknown`.
+- `--days` window is applied to transaction date. Transactions outside the window are excluded.

package/docs/how-to/segment.md

@@ -0,0 +1,55 @@
+# segment — find contacts by criteria
+
+## What it answers
+
+"Which contacts match this combination of criteria?" Filters your contact list by tag, phone presence, creation date, or tag absence. Returns a sample of matching contacts and a total count.
+
+## Command
+
+```sh
+sizmo segment --tag "vip"
+sizmo segment --no-phone
+sizmo segment --tag "lead" --created-days 7
+sizmo segment --without-tag "contacted" --has-phone
+sizmo segment --no-tags
+sizmo segment --top 50 --json
+sizmo segment --profile myclient
+```
+
+Flags (verified from `meta` in `commands/segment.mjs`):
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--tag` | str | — | Must have this tag (case-insensitive) |
+| `--without-tag` | str | — | Must NOT have this tag (case-insensitive) |
+| `--no-tags` | bool | false | Contacts with zero tags |
+| `--created-days` | int | — | Created within N days |
+| `--has-phone` | bool | false | Must have phone number |
+| `--no-phone` | bool | false | Must NOT have phone number |
+| `--top` | int | 20 | Max rows to show in sample |
+
+Flags can be combined. All criteria are ANDed.
+
+## How it works
+
+Paginates all contacts to completion before applying filters. Tag matching is case-insensitive. The result includes a total match count plus a sample capped at `--top`.
+
+## Sample output shape (example — no live creds in this context)
+
+```
+  SEGMENT: tag=vip, no-phone
+  Total matching: 8
+
+  1. Maria Santos       (no phone)    tags: vip, inquiry
+  2. Juan dela Cruz     (no phone)    tags: vip
+  3. Carlo Reyes        (no phone)    tags: vip, paid
+```
+
+*Sample shape only.*
+
+## Notes
+
+- The CLI never writes a tag or modifies a contact. Read-only.
+- `--no-tags` and `--tag` are mutually exclusive in practical use — a contact with zero tags cannot also have a specific tag.
+- Pagination exhausts all contacts before filtering. For large locations (10k+ contacts) this may take a few seconds.
+- `--top N` caps the display sample, not the total count. The total count in the output reflects all matching contacts.

package/docs/how-to/snapshot.md

@@ -0,0 +1,52 @@
+# snapshot — 6-metric card
+
+## What it answers
+
+"How did the last N days look?" One-screen summary: new leads, bookings, show rate, collected revenue (per currency), conversation reply rate, and total pipeline value.
+
+## Command
+
+```sh
+sizmo snapshot
+sizmo snapshot --days 30       # 30-day window instead of 7
+sizmo snapshot --json
+sizmo snapshot --profile myclient
+```
+
+Flags (verified from `meta` in `commands/snapshot.mjs`):
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--days` | int | 7 | Window in days |
+
+## Metrics
+
+All six metrics are derived from live API reads. Each can appear as blocked (scope missing) in which case `degraded: true` is set and the value shows `⚠ can't see (reason)`.
+
+| Metric | Source |
+|--------|--------|
+| New leads | Contacts created within window |
+| Bookings | Calendar appointments created within window (all calendars) |
+| Show rate | Attended / (Attended + No-show) within window |
+| Collected | Sum of successful payment transactions within window, per currency |
+| Reply rate | Conversations with an outbound message / total conversations with inbound activity |
+| Pipeline | Sum of all open opportunity values across all pipelines |
+
+## Sample output shape (example — no live creds in this context)
+
+```
+  New leads        12
+  Bookings         8
+  Show rate        75%
+  Collected        ₱48,000
+  Reply rate       83%
+  Pipeline         ₱320,000
+```
+
+*Sample shape only. Actual values depend on your GoHighLevel location data.*
+
+## Notes
+
+- Revenue is tracked per currency — never cross-summed. If you have both PHP and USD transactions, each appears on its own line.
+- Pipeline value uses GHL opportunity `monetaryValue`. GHL does not attach a currency field to individual opportunities — they inherit pipeline config. The CLI renders the value without conversion.
+- Show rate requires `calendars.read` scope. If blocked, the metric shows degraded.

package/docs/how-to/triage.md

@@ -0,0 +1,44 @@
+# triage — who's waiting on a reply
+
+## What it answers
+
+"Who has been waiting the longest for a response?" Surfaces conversation threads where the last message was inbound (from the contact) and no outbound reply has been sent, sorted by wait time descending.
+
+## Command
+
+```sh
+sizmo triage
+sizmo triage --top 20          # show top 20 threads
+sizmo triage --days 14         # narrow lookback to 14 days
+sizmo triage --json
+sizmo triage --profile myclient
+```
+
+Flags (verified from `meta` in `commands/triage.mjs`):
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--top` | int | 10 | Max threads to show |
+| `--days` | int | 30 | Lookback window |
+
+## How it works
+
+Paginates all conversations to completion (not capped at a single page) before applying `--top`, so the top N results are truly the longest-waiting — not just the first page. Each thread is examined for its last message direction. Threads where the last message was inbound and is older than the lookback threshold surface as waiting.
+
+Channel labels: SMS, Email, Call, FB, IG, WhatsApp, GMB, Chat.
+
+## Sample output shape (example — no live creds in this context)
+
+```
+  1. Maria Santos        SMS    waiting 8d    → reply or log
+  2. Juan dela Cruz      Email  waiting 5d    → reply or log
+  3. Carlo Reyes         WhatsApp waiting 3d  → reply or log
+```
+
+*Sample shape only.*
+
+## Notes
+
+- `--top N` caps the final sorted list, not the pagination. All pages are fetched before the cap is applied.
+- The CLI never sends a reply. To act on a thread, use your GoHighLevel inbox or your approved agent workflow.
+- `--days` filters the lookback window for which conversations are considered. Threads older than the window are excluded.

package/lib/cache.mjs

@@ -0,0 +1,36 @@
+// lib/cache.mjs — honest on-disk TTL cache.
+// Guardrails: short TTL, age always tracked, atomic write (temp+rename), 0700 dir / 0600 files.
+// NEVER stores whether a response is healthy/degraded — callers only cache 2xx (see http.mjs).
+import { createHash } from 'node:crypto';
+import { mkdirSync, writeFileSync, readFileSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+function keyFile(dir, key) {
+  const h = createHash('sha256').update(key).digest('hex');
+  return join(dir, h + '.json');
+}
+
+export function makeCache({ dir, ttlMs, now = Date.now }) {
+  return {
+    set(key, value) {
+      try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const payload = JSON.stringify({ ts: now(), value });
+        // atomic: write to tmp then rename
+        const tmp = join(tmpdir(), 'ghl-cache-' + createHash('sha256').update(key + now()).digest('hex').slice(0, 16) + '.tmp');
+        writeFileSync(tmp, payload, { mode: 0o600 });
+        renameSync(tmp, keyFile(dir, key));
+      } catch { /* best-effort — cache write failures are non-fatal */ }
+    },
+    get(key) {
+      try {
+        const raw = readFileSync(keyFile(dir, key), 'utf8');
+        const { ts, value } = JSON.parse(raw);
+        const ageMs = now() - ts;
+        if (ageMs > ttlMs) return null; // expired
+        return { value, ageMs };
+      } catch { return null; } // missing or corrupt → null, no throw
+    },
+  };
+}