@commissionsight/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) CommissionSight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,248 @@
+# @commissionsight/cli
+
+Command-line interface for the [CommissionSight](https://commissionsight.com) API
+— authentication, workspace selection, and statement uploads for **any carrier,
+any period, in any workspace**. A thin, faithful wrapper over
+[`@commissionsight/sdk`](https://www.npmjs.com/package/@commissionsight/sdk).
+
+It is designed to be driven by **humans and by AI coding agents** (Claude Code,
+Cursor, etc.) running locally: every command is fully non-interactive, supports
+machine-readable `--json` output, and returns deterministic exit codes.
+
+```bash
+npm install -g @commissionsight/cli
+cs --version
+```
+
+Binaries: `cs` (and the alias `commissionsight`). Requires **Node ≥ 20**.
+
+---
+
+## Quick start
+
+```bash
+# 1. Authenticate (token issued by CommissionSight; piped, never in argv)
+printf '%s' "$COMMISSIONSIGHT_TOKEN" | cs auth login --token-stdin
+cs auth status                                  # verifies via me()
+
+# 2. Pick a workspace (only needed on multi-workspace accounts)
+cs workspace list
+cs workspace use "Main Book"
+
+# 3. Upload a statement — any carrier, any period, any workspace
+cs upload ./aetna-2026-05.xlsx --carrier aetna --period 2026-05 --wait --results --json
+
+# 4. Bulk upload a folder (idempotent, resumable, mixed carriers/periods)
+cs upload batch ./statements --workspace "Main Book" --wait --report ./ingest.json
+```
+
+---
+
+## Using this CLI from an AI agent (Claude Code, etc.)
+
+This section is the contract an autonomous agent should rely on. Everything here
+is stable and machine-checkable.
+
+### 1. Discover the surface programmatically — don't guess
+
+```bash
+cs schema --json
+```
+
+Returns the **entire** command/flag tree as JSON: every command, its positional
+args (with `required`/`variadic`), and every option (`type`, `short`, `desc`,
+`choices`, `default`). Parse this instead of memorizing commands. Shape:
+
+```json
+{
+  "ok": true,
+  "data": {
+    "name": "cs",
+    "version": "0.1.0",
+    "globalOptions": [ { "flag": "json", "type": "boolean", "desc": "…" }, … ],
+    "commands": [
+      {
+        "command": "upload",
+        "path": ["upload"],
+        "summary": "Upload a statement for a carrier + period",
+        "args": [ { "name": "file", "required": true, "variadic": false } ],
+        "options": [ { "flag": "carrier", "type": "string", "desc": "…" }, … ]
+      },
+      …
+    ]
+  }
+}
+```
+
+### 2. Always pass `--json` — parse only stdout
+
+In `--json` mode, **stdout carries exactly one JSON value: the envelope.** All
+human chrome (spinners, progress, warnings) goes to **stderr**. So an agent can
+safely `JSON.parse(stdout)` without stripping anything.
+
+- **Success** (exit 0):
+  ```json
+  { "ok": true, "data": <command result> }
+  ```
+- **Failure** (nonzero exit):
+  ```json
+  { "ok": false, "error": { "status": 409, "code": "period_exists", "message": "…", "body": { … } } }
+  ```
+
+`error.code` is a stable slug derived from the API's problem+json body
+(`period_exists`, `already_retracted`, …) or `null`. Branch on `error.code` /
+`error.status`, not on `message` text.
+
+### 3. Use exit codes for control flow
+
+| Code | Meaning | Typical agent reaction |
+|---|---|---|
+| 0 | Success | continue |
+| 1 | Unexpected/internal error (incl. a job that finished `failed`) | inspect `error.message`; surface to user |
+| 2 | Usage error (bad flags/args) | fix the invocation |
+| 3 | Auth error (401/403) | token missing/invalid/insufficient — re-auth |
+| 4 | Not found (404) | the id/ref doesn't exist |
+| 5 | Conflict (409), e.g. `period_exists` | retry with `--replace` |
+| 6 | Validation (400/422) | inputs rejected; read `error.body` |
+| 7 | Rate limited (429) | back off and retry |
+| 124 | Timeout (`--wait` exceeded `--timeout`) | poll again or raise `--timeout` |
+
+### 4. Stay non-interactive
+
+- **Token**: prefer `COMMISSIONSIGHT_TOKEN` in the environment, or
+  `--token-stdin` (pipe it). Avoid `--token <t>` — it lands in process listings
+  and shell history.
+- **Destructive ops** (`file retract|purge`, `team remove`, `rate delete`,
+  `webhook delete`, `admin … purge-files`, `admin user delete`) require `--yes`
+  / `-y` when there's no TTY. Without it they exit `2` and perform nothing.
+- **Carrier refs** accept an id, slug, or case-insensitive name; an ambiguous
+  name exits `2` and lists candidates on stderr.
+- **Periods** are `--period YYYY-MM` (or `--year` + `--month`).
+
+### 5. Idempotency makes retries safe
+
+`cs upload` derives an idempotency key per file
+(`<context>-<carrierSlug>-<period>-<sha8(file)>`). Re-running the same upload or
+the same `upload batch` is safe and **resumable**: already-ingested
+carrier+periods come back as `skipped`, not duplicated. Override with
+`--idempotency-key` if you need to.
+
+### 6. Recipes
+
+```bash
+# Upload and block until scored, get rows back as JSON in one call
+cs upload ./uhc-2026-05.csv --carrier uhc --period 2026-05 \
+  --wait --results --json
+# → data.upload.{jobId,fileId}, data.results[] (scored ResultRows)
+
+# Handle "period already exists" deterministically
+cs upload ./aetna-2026-05.xlsx --carrier aetna --period 2026-05 --json
+# exit 5 + error.code=period_exists  → re-run with --replace:
+cs upload ./aetna-2026-05.xlsx --carrier aetna --period 2026-05 --replace --json
+
+# Bulk ingest a directory, keep going past failures, write a machine report
+cs upload batch ./statements --continue-on-error --report ./out.json --json
+# data.{total,uploaded,replaced,skipped,failed,unmatched,outcomes[]}
+
+# Pull a full month rollup as JSON, or export rows as CSV
+cs report rollup --period 2026-05 --json
+cs job results <jobId> --all --csv -o ./scored.csv
+
+# Export exception (rejected) rows for a job
+cs job exceptions <jobId> -o ./exceptions.csv      # exit 4 if none/purged
+
+# Audit a single member across every period
+cs member journey <memberRefId> --json
+```
+
+### 7. Multiple environments
+
+Contexts bundle a base URL + token + default workspace. Switch with
+`--context <name>` on any command, or set the active one:
+
+```bash
+cs context add staging --base-url https://staging.api.commissionsight.com/v1
+printf '%s' "$STAGING_TOKEN" | cs context add staging --token-stdin
+cs context use staging
+```
+
+---
+
+## Authentication & config
+
+Auth is a per-account **API bearer token** issued by CommissionSight (there is no
+email/password login in the API). Token resolution precedence (highest first):
+
+1. `--token <t>` (discouraged — visible in shell history)
+2. `--token-file <path>` / `--token-stdin` (preferred for scripts)
+3. `COMMISSIONSIGHT_TOKEN` env var
+4. active context token in the config file
+
+Config lives at `${XDG_CONFIG_HOME:-~/.config}/commissionsight/config.json`
+(dir `0700`, file `0600`). The token is never printed — `auth status` shows a
+masked suffix (`…a1b2`). `--base-url` / `COMMISSIONSIGHT_BASE_URL` override the
+API base (default `https://api.commissionsight.com/v1`).
+
+---
+
+## Global flags
+
+| Flag | Purpose |
+|---|---|
+| `--json` (or `CS_OUTPUT=json`) | Emit only the envelope on stdout |
+| `--quiet` / `-q` | Suppress human chrome |
+| `--no-color` (or `NO_COLOR`) | Disable ANSI color |
+| `--yes` / `-y` | Assume "yes" for destructive confirmations |
+| `--token` / `--token-file` / `--token-stdin` | Token sources |
+| `--base-url <url>` | Override API base URL |
+| `--context <name>` | Use a named config context |
+| `--help` / `-h`, `--version` / `-V` | Help / version |
+
+---
+
+## Command reference
+
+100 commands across these groups (run `cs <group> --help`, or `cs schema --json`
+for the full machine-readable tree).
+
+| Group | Commands |
+|---|---|
+| **Session** | `whoami` · `health` · `version` · `schema` · `completion bash\|zsh\|fish` |
+| **Auth** | `auth login` · `auth status` · `auth logout` · `auth token issue` |
+| **Context** | `context list\|current\|use\|add\|remove` |
+| **Workspace** | `workspace list` · `workspace create <name>` · `workspace use <name\|id>` |
+| **Carrier** | `carrier list` · `carrier get` · `carrier config list\|get\|create\|test\|infer` |
+| **Upload** | `upload <file>` · `upload batch <target>` |
+| **File** | `file list\|get\|rescore\|retract\|purge\|rescore-stale` |
+| **Job** | `job list\|get\|wait\|results\|deltas\|exceptions\|retry` |
+| **Member / Policy** | `member list\|get\|timeline\|journey\|last-seen` · `policy journey` |
+| **Team / Audit** | `team list\|invite\|remove` · `audit list` |
+| **Reports** | `report rollup\|compare\|attrition\|attrition-series\|data-quality\|chargebacks` |
+| **Rates** | `rate list\|set\|delete` |
+| **Webhooks** | `webhook list\|create\|delete` |
+| **Billing** | `billing get\|preview\|update` |
+| **Admin** | `admin account *` · `admin token *` · `admin carrier *` · `admin user *` · `admin job *` · `admin allowlist add` · `admin metrics\|logs\|revenue\|cron-runs` |
+
+List commands accept `--limit`, `--all` (auto-paginate), and `--offset` or
+`--cursor` as appropriate; result/report commands accept `--csv` (with `-o` to
+write a file). Reports take `--period`/`--carrier`/`--from`/`--to` as listed in
+`--help`.
+
+### Notes & limitations
+
+- **Workspace creation** (`cs workspace create <name>`) requires
+  `@commissionsight/sdk` **≥ 2.3.0** (`createWorkspace` → `POST /workspaces`).
+  The command is capability-gated: on an older SDK it fails with a clear,
+  actionable message instead of silently no-opping.
+- **Report workspace scoping**: the API documents an optional `?workspaceId` on
+  reports, but the SDK's report methods do not yet accept it, so `cs report *`
+  omits `--workspace`. As a thin wrapper the CLI never bypasses the SDK; this
+  lands when the SDK exposes the parameter.
+- **Stripe payment-method / setup-intent** flows are web-app only and out of
+  scope; use `cs billing get/preview/update` for billing details.
+
+---
+
+## License
+
+MIT © CommissionSight

package/bin/cs.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import('../dist/main.js').then((m) => m.run(process.argv.slice(2)));

package/dist/commands/admin.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Admin namespace (plan §6.12) — maps the entire `client.admin.*` surface 1:1.
+ * Every call is wrapped by `adminGate`, which turns a 401/403 into exit 3 with
+ * an "admin token required" message so non-admin tokens fail clearly.
+ */
+import type { Cmd } from '../types.js';
+export declare function adminCommands(): Cmd[];