@solidnumber/cli 1.9.14 → 1.9.15

package/platform-docs/COOKBOOK.md

@@ -172,9 +172,14 @@ solid auth token create \
 export SOLID_TOKEN=$(jq -r .key /tmp/key.json)
 ```
 
-Now the agent has read-only access for a week. Agency tip: add
-`--require-approval` in the token request so every destructive call
-queues a human approval instead of firing.
+Now the agent has read-only access for a week. For scripted use, the
+CLI also honors `SOLID_TOKEN=<key>` and `SOLID_API_KEY=<key>` env vars —
+either takes precedence over the cached session for that process.
+
+**Not yet shipped (don't reference in agent code yet):** a per-key
+`require_approval` flag that queues every destructive call for a
+human OK before firing. It's on the roadmap but does NOT exist on
+`solid auth token create` today.
 
 ---
 

package/platform-docs/SCHEMAS.md

@@ -1,8 +1,16 @@
 # `--json` Output Schemas
 
-The contract: **every `--json` payload is the backend's response body, unmodified** — no CLI-added wrapping, no "status" key glued on top. If you want the authoritative schema, that's the OpenAPI spec. This doc is the practical field guide — what you'll actually see in stdout when you run the command.
+**Verified against live production responses** on 2026-04-18 using
+`@solidnumber/cli@1.9.14`. If you find drift, the backend shape is the
+ground truth — update this doc or open an issue.
 
-Schemas below use TypeScript interface shorthand. Optional fields are `?`. Values shown in samples are representative, not fixed.
+The contract: **every `--json` payload is the backend's response body,
+unmodified** (except for list commands using `--all`, which wrap the
+flattened page as `{ items: T[], count: number }`).
+
+Schemas are TypeScript interfaces for readability. Optional fields are
+`?`. Backend inconsistencies (e.g. both `created_at` and `createdAt` on
+the same record) are noted where they occur.
 
 ---
 
@@ -12,13 +20,13 @@ Schemas below use TypeScript interface shorthand. Optional fields are `?`. Value
 
 ```ts
 interface WhoamiResponse {
-  authenticated: boolean | 'offline';  // 'offline' = cached session, couldn't reach server
+  authenticated: boolean | 'offline';   // 'offline' = cached session, couldn't reach server
   email: string | null;
   company_id: number | null;
-  user_id?: number;
+  user_id?: number;                     // only populated when the server confirmed auth
   environment: 'production' | 'sandbox' | 'development';
   api_url: string;
-  token_expires_at: string | null;  // ISO 8601, null if no expiry tracked
+  token_expires_at: string | null;      // ISO 8601, null if no expiry tracked
 }
 ```
 
@@ -32,15 +40,15 @@ interface AuthRefreshResponse {
 }
 ```
 
-### `solid auth token create` (always JSON in output)
+### `solid auth token create` (always emits JSON on success)
 
 ```ts
 interface ApiKeyCreateResponse {
   id: number;
   name: string;
-  key: string;            // sk_solid_... — shown once, never again
-  key_prefix: string;     // first 12 chars, safe to log
-  scopes: string[];       // e.g. ['kb:read', 'pages:write']
+  key: string;             // sk_solid_... — shown once, never again
+  key_prefix: string;      // first 12 chars, safe to log
+  scopes: string[];        // e.g. ['kb:read', 'pages:write']
   expires_at: string | null;
   created_at: string;
 }
@@ -71,37 +79,31 @@ interface SwitchListResponse {
 
 ### `solid company info --json`
 
+Top-level envelope has a `status` sibling alongside the `company` object:
+
 ```ts
 interface CompanyInfoResponse {
+  status: 'ok' | 'error' | string;
   company: {
     id: number;
     name: string;
-    kb_sub_code?: string;       // industry slug (plumber, hvac, dentist, …)
-    business_type?: string;
-    industry_name?: string;
-    mcc_code?: string;
-    feature_settings?: Record<string, boolean>;
+    slug: string;
+    created_at: string;
+    is_demo: boolean;
+    logo_asset_id: number | null;
+    logo_url: string | null;
+    parent_id: number | null;
+    portal_type: string | null;
+    public_domain: string | null;
+    sandbox_enabled: boolean;
+    timezone: string;
   };
 }
 ```
 
-### `solid company lock-status --json` (T10 agency-managed)
-
-```ts
-interface LockStatus {
-  company_id: number;
-  agency_managed: boolean;
-  agency_owner_user_id: number | null;
-  locks: {
-    pages: boolean;
-    brand: boolean;
-    domains: boolean;
-    modules: boolean;
-    design: boolean;
-    billing_lock: boolean;
-  };
-}
-```
+Note: `kb_sub_code`, `business_type`, `industry_name`, `mcc_code` are
+NOT on this endpoint — fetch them via `solid company current` or the
+direct `/api/v1/companies/me` endpoint instead.
 
 ---
 
@@ -109,32 +111,59 @@ interface LockStatus {
 
 ### `solid crm contacts list --json`
 
+Two envelope shapes — single page returns the backend body as-is
+(flexible), `--all` normalizes to `{ items, count }`.
+
 ```ts
+// Single page (default)
 interface ContactsListResponse {
-  items?: Contact[];        // pass-through; `--all` wraps as { items, count }
-  contacts?: Contact[];     // some backend paths use this key
+  contacts?: Contact[];     // most responses use this key
+  items?: Contact[];        // some paths use this
+  total?: number;
+}
+
+// --all wrapper
+interface ContactsAllResponse {
+  items: Contact[];
   count: number;
-  offset?: number;
-  page_size?: number;
 }
 
+// Contact — snake_case and camelCase BOTH appear on the same record
+// (legacy fields from the dashboard side kept for backwards compat)
 interface Contact {
   id: number;
   first_name: string | null;
   last_name: string | null;
+  full_name: string | null;
+  name: string | null;                  // camelCase alias
   email: string | null;
   phone: string | null;
+  company: string | null;               // company name
+  company_id: number | null;            // tenant id (Solid# owner)
   company_name: string | null;
-  status?: 'active' | 'inactive' | 'blocked' | string;
-  source?: string;
-  contact_type?: string;
+  contact_type: string | null;
+  source: string | null;
+  status: string | null;
+  grade: string | null;
+  score: number | null;
+  tags: string[];
+  assigned_at: string | null;
+  assigned_to_user_id: number | null;
+  assigned_to_user_name: string | null;
+  assigned_to_agent: string | null;
+  totalOrders: number | null;           // camelCase
+  totalSpent: number | null;            // camelCase
+  lastOrderDate: string | null;         // camelCase
   created_at: string;
+  createdAt: string;                    // dupe — camelCase
   updated_at: string;
 }
 ```
 
 ### `solid crm contacts import --json`
 
+Same shape as `solid ecommerce orders import --json`:
+
 ```ts
 interface ImportResponse {
   summary: {
@@ -145,33 +174,46 @@ interface ImportResponse {
     dry_run: boolean;
   };
   results: Array<{
-    row: number;                          // 1-indexed within the CSV (row 1 = header)
+    row: number;                        // 1-indexed within the CSV
     status: 'created' | 'failed' | 'skipped' | 'dry-run';
-    id?: number;                          // only when status === 'created'
-    error?: string;                       // only when status !== 'created'
+    id?: number;                        // only when status === 'created'
+    error?: string;                     // only when status !== 'created'
   }>;
 }
 ```
 
-Same shape for `solid ecommerce orders import --json`.
-
 ### `solid crm deals list --json`
 
+Envelope is NOT `{ items, count }` like contacts — it's `{ deals, limit, offset, total }`.
+
 ```ts
 interface DealsListResponse {
-  items: Deal[];
-  count: number;
+  deals: Deal[];
+  limit: number;
+  offset: number;
+  total: number;
 }
 
 interface Deal {
   id: number;
   title: string;
-  value: number | null;
   stage: string;
+  source: string | null;
+  amount: number | null;                // dollars
+  amount_cents: number | null;          // cents (authoritative)
+  lead_cost_cents: number | null;
+  notes: string | null;
   contact_id: number | null;
-  contact_name?: string;
-  closed_at?: string | null;
-  outcome?: 'won' | 'lost' | null;
+  contact_name: string | null;
+  company_id: number;                   // tenant
+  company_name: string | null;
+  assigned_at: string | null;
+  assigned_to_user_id: number | null;
+  assigned_to_user_name: string | null;
+  assigned_to_agent: string | null;
+  follow_up_date: string | null;
+  created_at: string;
+  updated_at: string;
 }
 ```
 
@@ -181,19 +223,21 @@ interface Deal {
 
 ### `solid kb list --json`
 
+Minimal envelope — just `{ results }`, no total / count / pagination
+metadata returned:
+
 ```ts
 interface KBListResponse {
-  entries: KBEntry[];
-  total: number;
+  results: KBEntry[];
 }
 
 interface KBEntry {
   id: number;
   title: string;
   category: string | null;
-  content: string;           // may be truncated on list endpoint
-  version: number;
-  updated_at: string;
+  content: string;
+  // Other fields (version, updated_at) are returned by the /kb/entries/{id}
+  // detail endpoint, not the list endpoint.
 }
 ```
 
@@ -220,17 +264,23 @@ interface KBHistoryResponse {
 
 ### `solid pages list --json`
 
+Pages list uses the `--all` envelope even for single-page requests
+(we added this consistency in 1.9.14).
+
 ```ts
 interface PagesListResponse {
-  pages: Array<{
-    id: number;
-    slug: string;
-    title: string;
-    is_published: boolean;
-    current_version: number;
-    updated_at: string;
-  }>;
-  total: number;
+  items: Page[];
+  count: number;
+}
+
+interface Page {
+  id: number;
+  slug: string;
+  title: string;
+  page_type: 'website' | 'landing' | 'blog' | 'booking' | string;
+  is_published: boolean;
+  current_version: number;
+  updated_at: string;
 }
 ```
 
@@ -263,17 +313,32 @@ interface PagesHistoryResponse {
 
 ### `solid billing status --json`
 
+**Backend changed this shape recently — verified 2026-04-18.**
+
 ```ts
-interface BillingOverviewResponse {
+interface BillingStatusResponse {
+  has_payment_method: boolean;
+  next_billing_date: string | null;        // ISO
+  subscription: Subscription | null;       // null = no active subscription
+  sms_pack: PackState | null;
+  voice_plan: PackState | null;
+  token_budget: PackState | null;
+}
+
+interface Subscription {
   tier: 'starter' | 'builder' | 'professional' | 'enterprise';
-  plan?: string;                       // legacy field, mirrors tier
   status: 'active' | 'past_due' | 'cancelled' | 'trialing';
-  current_period_end: string;          // ISO
-  amount: number;                      // monthly dollars
-  processor?: string;
-  mcc_code?: string;
-  industry?: string;
-  active?: boolean;
+  amount_cents: number;
+  current_period_start: string;
+  current_period_end: string;
+  cancel_at_period_end: boolean;
+}
+
+interface PackState {
+  included: number;
+  used: number;
+  remaining: number;
+  overage_price_cents: number;
 }
 ```
 
@@ -283,12 +348,12 @@ interface BillingOverviewResponse {
 interface InvoicesListResponse {
   invoices: Array<{
     id: number;
-    invoice_id: string;                // Stripe in_... id
+    invoice_id: string;                    // Stripe in_... id
     amount: number;
     total: number;
     currency: string;
     status: 'paid' | 'open' | 'void' | 'uncollectible';
-    date: string;                      // ISO
+    date: string;
     hosted_url?: string;
     pdf_url?: string;
   }>;
@@ -306,10 +371,10 @@ Shape depends on the report. The envelope is stable:
 
 ```ts
 interface ReportRunResponse {
-  rows?: Array<Record<string, unknown>>;   // tabular reports
-  data?: Array<Record<string, unknown>>;   // some endpoints use this key
+  rows?: Array<Record<string, unknown>>;
+  data?: Array<Record<string, unknown>>;
   results?: Array<Record<string, unknown>>;
-  summary?: Record<string, number | string>;  // aggregates
+  summary?: Record<string, number | string>;
   meta?: {
     report: string;
     date_from: string;
@@ -323,17 +388,35 @@ Use `solid reports run --list --json` to enumerate types.
 
 ### `solid analytics dashboard --json`
 
+**Re-verified 2026-04-18 — fully rewritten from the old `{ revenue, transactions, ... }` shape.** Everything is nested under `metrics`, `quick_stats`, `revenue_chart`, `recent_orders`, `top_products`:
+
 ```ts
 interface DashboardSummary {
-  revenue?: number;
-  transactions?: number;
-  customers?: number;
-  new_customers?: number;
-  avg_transaction?: number;
-  chargebacks?: number;
-  period?: string;         // days
-  date_from?: string;
-  date_to?: string;
+  period: string;                          // '7', '30', '90'
+  metrics: {
+    total_revenue: TrendMetric;            // see below
+    total_orders: TrendMetric;
+    customers: { total: number; new: number; trend: number; trend_direction: 'up' | 'down' };
+    active_products: { value: number };
+    growth_rate: { value: number; formatted: string };
+  };
+  quick_stats: {
+    daily_sales: { value: number; formatted: string; orders: number; date: string };
+    month_previous: { value: number; formatted: string; orders: number; month: string };
+  };
+  revenue_chart: Array<{ date: string; revenue: number }>;
+  recent_orders: Array<{ id: number; total: number; customer: string; created_at: string }>;
+  top_products: Array<{ id: number; name: string; revenue: number; units: number }>;
+}
+
+interface TrendMetric {
+  value: number;
+  formatted?: string;
+  trend: number;                           // % change vs prior period
+  trend_direction: 'up' | 'down';
+  daily_average: number;
+  daily_average_formatted?: string;
+  prev_daily_average: number;
 }
 ```
 
@@ -363,8 +446,8 @@ interface AgentListResponse {
 ```ts
 interface AgentClonesResponse {
   profiles: Array<{
-    agent_type: string;           // base — e.g. 'customer_service'
-    display_name: string;         // company-specific rename
+    agent_type: string;                    // base — e.g. 'customer_service'
+    display_name: string;                  // company-specific rename
     system_prompt: string | null;
     personality: string | null;
     model: string | null;
@@ -376,14 +459,61 @@ interface AgentClonesResponse {
 
 ---
 
+## E-commerce
+
+### `solid ecommerce orders list --json`
+
+Single-page envelope from the backend; `--all` normalizes as usual.
+
+```ts
+interface OrdersListResponse {
+  orders?: Order[];                        // backend key
+  items?: Order[];                         // fallback key on some paths
+}
+
+interface Order {
+  id: number;
+  customer_email?: string;
+  customer_name?: string;
+  total: number;
+  status: 'pending' | 'paid' | 'shipped' | 'cancelled' | 'refunded';
+  currency: string;
+  created_at: string;
+}
+```
+
+---
+
+## Conversation Insights
+
+### `solid insights list --json`
+
+Uses the unified `{ items, count }` envelope from command-kit's
+`runListCommand`:
+
+```ts
+interface InsightListResponse {
+  items: Array<{
+    insight_type?: 'kb_gap' | 'pattern' | 'suggestion' | string;
+    type?: string;                         // some paths duplicate this
+    title?: string;
+    summary?: string;
+    recommendation?: string;
+  }>;
+  count: number;
+}
+```
+
+---
+
 ## MCP Tools / Chains
 
 ### `solid chains execute <id> --json`
 
 ```ts
 interface ChainExecutionResponse {
-  execution_id: string;         // UUID — the job handle
-  id?: string;                  // legacy alias for execution_id
+  execution_id: string;                    // UUID — the job handle
+  id?: string;                             // legacy alias
   status: 'queued' | 'running' | 'completed' | 'failed' | 'cancelled';
   chain_id: number;
   started_at: string;
@@ -397,36 +527,36 @@ interface ChainExecutionResponse {
 }
 ```
 
-### `solid mcp-server health` / `GET /health` on mcp.solidnumber.com
+### MCP server `/health` on `mcp.solidnumber.com`
 
 ```ts
 interface MCPHealthResponse {
   status: 'healthy';
   server: string;
   version: string;
-  tools: number;              // 608+ for the main registry
+  tools: number;                           // 608+ for the main registry
   categories: number;
-  backend: string;            // internal URL
-  uptime: number;             // seconds
+  backend: string;                         // internal URL
+  uptime: number;                          // seconds
   timestamp: string;
 }
 ```
 
 ---
 
-## Error responses
+## Error shapes
 
-Any command that hits the backend surfaces the backend's error payload
-inside the CLI's red-line formatter. The backend's structured shape:
+Backend 4xx/5xx responses:
 
 ```ts
 interface ApiError {
-  detail: string | Array<{ loc: string[]; msg: string; type: string }>;  // FastAPI 422s
+  detail: string | Array<{ loc: string[]; msg: string; type: string }>;
   message?: string;
 }
 ```
 
-The CLI flattens `detail` arrays into `loc.path: msg` lines before printing. Structured MCP-protocol errors follow the JSON-RPC 2.0 envelope:
+The CLI flattens `detail` arrays into `loc.path: msg` lines before
+printing (on stderr). MCP protocol errors follow JSON-RPC 2.0:
 
 ```ts
 interface MCPError {
@@ -436,8 +566,8 @@ interface MCPError {
     code: number;
     message: string;
     data?: {
-      error_class?: string;    // stable identifier — branch on this, not message
-      hint?: string;           // human-readable remediation
+      error_class?: string;                // stable identifier — branch on this, not message
+      hint?: string;                       // human-readable remediation
     };
   };
 }
@@ -445,12 +575,34 @@ interface MCPError {
 
 ---
 
-## Pagination envelope (global)
+## `--all` envelope (universal)
 
-List endpoints that support `--limit` / `--offset` / `--all` return a common pagination shape when available. `--all` wraps the flattened collection as:
+When you pass `--all`, command-kit's `runListCommand` normalizes the
+flattened collection as:
 
 ```ts
 { items: T[]; count: number }
 ```
 
-Single-page responses keep whatever native shape the backend emits (`{ items }`, `{ contacts }`, `{ deals }`, etc.). Use `--all` for schema normalization.
+regardless of the backend's native key (`contacts`, `deals`, `orders`,
+`items`, etc.). This lets scripts write `jq '.items[]'` without
+per-endpoint special-casing.
+
+Single-page responses keep the backend's native shape — documented
+above per command.
+
+---
+
+## Gotchas I actually hit while writing this
+
+- `billing status` used to return `{ tier, status, amount, ... }` flat.
+  It's now `{ subscription: {...}, sms_pack, voice_plan, token_budget, ... }`.
+  If you wrote scripts against the old shape, they're broken.
+- Contact records double-serialize both `created_at` (snake) AND
+  `createdAt` (camel), `totalOrders`/`totalSpent` (camel) alongside
+  snake_case fields from the same row. The backend is mid-migration.
+- Deals use `deals` as the envelope key; contacts use `contacts` or
+  `items`; orders use `orders`; insights uses `items` (because we wrap it).
+  No universal naming — use `--all` if you want consistency.
+- `kb list` returns just `{ results }` — no `total` or pagination
+  metadata. Use `solid history kb` if you need versioned history.