kenso 0.0.0-stage → 0.1.8

package/docs/leads.md

@@ -0,0 +1,214 @@
+# Leads
+
+Leads are contacts in a campaign. The lead commands live under `kenso contacts`, and `kenso leads` is the same thing: `kenso leads import` runs `kenso contacts import`.
+
+| Command | What it does |
+|---|---|
+| `contacts import` | Add leads from a CSV or JSONL file to a campaign, with one result per row |
+| `contacts update` | Edit leads in bulk from a file, matched by id or by email |
+| `contacts remove` / `restore` | Remove (soft-delete) leads by id, and undo it |
+| `contacts pause` / `resume` | Pause and resume the campaign sequence of leads (pause is beta, `pause_leads` flag) |
+| `contacts tag` / `untag` | Add or remove a tag on leads by id |
+| `contacts export` | Download a campaign's leads as one CSV file |
+
+All of them except `export` are batch commands: without `--yes` they print a plan and change nothing. [Batch runs](batch.md) explains plans, run folders, results files and resume.
+
+## Import a CSV into a campaign
+
+```bash
+kenso contacts import --template
+kenso contacts import --campaign 812 --file leads.csv --dry-run
+kenso contacts import --campaign 812 --file leads.csv --yes
+```
+
+`--template` prints the accepted columns. A minimal file:
+
+```csv
+email,firstName,lastName,companyName,Pain Point
+ann@acme.io,Ann,Lee,Acme,Slow onboarding
+cid@globex.com,Cid,Moe,Globex,Churn
+```
+
+### Columns
+
+Headers are matched without regard to case, spaces or punctuation. The known fields and the other headers each one reads:
+
+| Field | Also read from | Rule |
+|---|---|---|
+| `email` | email address, e-mail, work email | Required, unless the campaign is LinkedIn-only and the row has a linkedin.com/in/ URL |
+| `firstName` | first name, first, given name | Required |
+| `lastName` | last name, last, surname, family name | Required |
+| `title` | job title, position, role | Optional |
+| `linkedInUrl` | linkedin, linkedin url, linkedin profile, profile url | Optional |
+| `companyName` | company, organization, account, account name | `companyName` or `companyDomain` is required |
+| `companyDomain` | website, domain, company website, url | `companyName` or `companyDomain` is required |
+
+Every other column becomes a custom variable, named like its header in snake_case: a `Pain Point` column fills `{{pain_point}}` in your sequence. Names Kenso keeps for its own fields (`city`, `country`, `phone_number` and others) are not sent: the CLI warns and the plan lists them under `droppedColumns`. Rename them with `--map`.
+
+### Cells
+
+- A blank cell is never sent, so importing a file never erases data on a lead that is already in the campaign.
+- The literal value `null` clears a custom variable.
+
+### Rename or drop columns with --map
+
+`--map` takes a JSON object, `@file` or `-` for stdin. A value names the target field, and `null` drops the column:
+
+```bash
+kenso contacts import --campaign 812 --file leads.csv --map '{"Pain": "customVariables.pain_point", "Notes": null}' --yes
+```
+
+### JSONL
+
+Each line is one lead. Keys work like CSV headers, and a `customVariables` object is spread into custom variables:
+
+```json
+{"email":"ann@acme.io","firstName":"Ann","lastName":"Lee","companyName":"Acme","customVariables":{"pain_point":"Slow onboarding"}}
+```
+
+```bash
+kenso contacts import --campaign 812 --file leads.jsonl --yes
+cat leads.jsonl | kenso contacts import --campaign 812 --file - --yes
+```
+
+A run read from stdin cannot be resumed with `kenso runs resume`, so prefer a file for large imports.
+
+### What the CLI checks before sending
+
+Every row is checked locally first. A row that fails goes to `invalid.csv` with one of these reasons and is not sent:
+
+| Reason | Meaning |
+|---|---|
+| `missing_email` | The row has no email (and is not a LinkedIn-only lead) |
+| `invalid_email` | The email is not a valid address |
+| `missing_first_name` | The row has no first name |
+| `missing_last_name` | The row has no last name |
+| `missing_company` | The row has neither a company name nor a company domain |
+| `sales_navigator_url` | An email-less row whose LinkedIn URL is a Sales Navigator link: add the email or a linkedin.com/in/ URL |
+| `duplicate_in_file` | An earlier row of the file has the same email |
+
+Kenso stays the authority and checks every row again.
+
+### What the dry run shows
+
+The dry run maps the columns, checks the rows, reads the campaign, and asks for a credit estimate (`credit-estimates create`, kind `leads`). Its plan holds `rows`, `valid`, `invalid`, `mapping`, `customVariableKeys`, `estimate`, `credits` (`needed`, `available`, `sufficient`) and `next`, the exact apply command. If the estimate call fails, the plan still prints with `"estimate":null` and an `estimateError`.
+
+### How rows are sent
+
+The CLI sends 1,000 rows per call to `POST /v1/campaigns/{campaignId}/contacts`, one call at a time per campaign, because two overlapping upserts of the same email could create duplicates. After a 5xx answer or a dropped connection it does not retry right away: it waits 130 seconds, so the first request has finished on the server, then resends the chunk once. Rows the first request saved come back `updated`.
+
+### Reading the result
+
+Each row in `results.csv` gets one status:
+
+| Status | Meaning |
+|---|---|
+| `created` | A new lead in the campaign |
+| `updated` | The lead was already there and was updated |
+| `skipped` | Kenso kept the lead out on purpose. `reason` is `duplicate`, `blocklisted`, `already_contacted`, `excluded` or another code |
+| `failed` | Kenso refused the row (`reason` such as `invalid_email` or `validation`, and an `error` message), or the call failed |
+| `invalid` | The CLI refused the row before sending it (see the table above) |
+
+A saved lead that cannot be emailed yet has `sendable` false, and the summary counts those leads in `notSendable` with a warning on stderr.
+
+Exit codes: 0 when no row failed (skipped rows are not failures), 5 when some rows failed or were invalid, 6 when the plan's or campaign's lead limit stopped the run (`limit_reached`; raise the limit, then rerun the same command to send the rest).
+
+## Import a very large file on the server
+
+For up to 100,000 rows, `--server-import` uploads the CSV as one server import job and waits for it (default 30 minutes, `--timeout`). It reports the job's counts but no per-row results.
+
+```bash
+kenso contacts import --campaign 812 --file big.csv --server-import --yes
+kenso contacts import --campaign 812 --file big.csv --server-import --timeout 1h --yes
+```
+
+## Update leads in bulk
+
+```bash
+kenso contacts update --file edits.csv --match id
+kenso contacts update --file edits.csv --match id --yes
+kenso contacts update --file edits.csv --match email --campaign 812 --yes
+```
+
+- `--match id` reads the contact id from an `id` or `contactId` column.
+- `--match email` finds each email among the leads of `--campaign`. An email it cannot find is `not_found`. The email column only finds the lead; it is never sent as an edit.
+- A column that is absent, or a blank cell, leaves that field unchanged. The literal `null` clears it.
+- The lead fields you can edit are `firstName`, `lastName`, `title`, `linkedInUrl`, and `email` with `--match id`. `companyName` and `companyDomain` cannot change here and are not sent. Every other column is a custom variable, mapped the same way as in an import, and `--map` works here too.
+- A row with nothing to change is `skipped` with reason `no_changes` and is not sent. Rows go 1,000 per call to `POST /v1/contacts/bulk-update`.
+
+To edit one lead, use a one-row file from stdin:
+
+```bash
+printf 'id,title\n9001,VP Sales\n' | kenso contacts update --file - --match id --yes
+```
+
+## Remove, restore, pause and resume
+
+These four take contact ids from `--ids` (one id per line, or a CSV or JSONL file with an `id` or `contactId` column, or `-` for stdin), or from a search with `--where` (remove, pause and resume). `--where` takes the body of `POST /v1/contacts/search` as JSON, `@file` or `-`.
+
+```bash
+kenso contacts remove --ids ids.txt
+kenso contacts remove --ids ids.txt --yes
+kenso contacts remove --where '{"campaignIds": [812], "q": "acme"}' --yes
+kenso contacts remove --ids big.csv --confirm 2500 --yes
+```
+
+- Without `--yes`, the plan prints the count and the first ids.
+- Removing more than 1,000 contacts also needs `--confirm <count>`, and the count must match. The plan's `next` already carries the right `--confirm`.
+- Each id comes back `ok`, `skipped` when there was nothing to do (for example `not_deleted` when you restore a contact that is not removed), `not_found` or `failed`.
+- The remove summary carries the undo command, `"undo":"kenso contacts restore --run r_ubqu7wtx"`.
+
+```bash
+kenso contacts restore --run r_ubqu7wtx --yes
+kenso contacts restore --ids ids.txt --yes
+kenso contacts pause --where '{"campaignIds": [812]}' --yes
+kenso contacts resume --ids ids.txt --yes
+```
+
+`restore` takes `--ids` or `--run <runId>` of an earlier remove, not `--where`: a search cannot find removed contacts. `pause` is a beta command for workspaces with the `pause_leads` flag.
+
+## Tag and untag
+
+```bash
+kenso tags list
+kenso contacts tag --tag 31 --ids ids.txt --yes
+kenso contacts untag --tag 31 --ids ids.txt --yes
+```
+
+`tag` calls `POST /v1/tags/{tagId}/assignments` once per contact. A contact that already has the tag is `skipped` with reason `already_tagged`.
+
+## Export a campaign's leads
+
+```bash
+kenso contacts export --campaign 812 --out contacts.csv
+kenso contacts export --campaign 812 --wait
+```
+
+With `--out`, the CLI creates the export, waits for the job (default 30 minutes, `--timeout`) and writes one CSV file (mode 0600). Without `--out` it prints the export job; `--wait` waits for it, or run the `next` it prints, `kenso jobs wait <jobId> --type contact_export`.
+
+## Recipes
+
+**Tag every lead of a campaign.** List the ids, then tag them:
+
+```bash
+kenso contacts list --campaign-id 812 --all -o ids > ids.txt
+kenso contacts tag --tag 31 --ids ids.txt --yes
+```
+
+**Fix the invalid rows and send them.** `invalid.csv` keeps each refused row's number and reason. Fix those rows in a new file and import it. Rerunning the original file also works: rows Kenso already saved come back `updated` or `skipped`.
+
+**Retry only what failed.** Filter `results.csv` to the `failed` rows, take those rows from the input by `row` number, and import that file.
+
+**Pause leads who replied elsewhere.** Search by filter, check the count, then apply:
+
+```bash
+kenso contacts pause --where @replied.json
+kenso contacts pause --where @replied.json --yes
+```
+
+**Edit one field on many leads by email.**
+
+```bash
+kenso contacts update --file titles.csv --match email --campaign 812 --dry-run
+kenso contacts update --file titles.csv --match email --campaign 812 --yes
+```

package/docs/output-and-errors.md

@@ -0,0 +1,154 @@
+# Output and errors
+
+Every command follows one contract, so a script or an agent can parse any of them the same way.
+
+## stdout and stderr
+
+- **stdout carries data only.** Progress, warnings, notices and errors go to stderr.
+- No colors, spinners or pagers. On a terminal you get readable tables; in a pipe you get JSON.
+- The CLI never prompts. A batch command (an import, update, remove, tag or `--each` write) takes `--yes`; without it, the command plans or refuses. A single generated write, such as `kenso tags delete --tag-id 7`, and a write through `kenso api` send at once: add `--dry-run` to see the request first, then run the command without it.
+
+## Formats
+
+| What the command returns | stdout is a terminal | stdout is a pipe or file |
+|---|---|---|
+| One object | key-value lines | compact JSON on one line |
+| A list | a table (first 8 scalar fields, cells cut at 60 characters) | NDJSON: one JSON object per line |
+| A batch run | key-value lines | one JSON summary object |
+| No content (HTTP 204) | nothing | nothing |
+
+`-o` or `--output` picks the format: `json`, `ndjson`, `table` or `ids`.
+
+- `-o json` on a list prints one JSON array. On a terminal, `-o json` pretty-prints an object.
+- `-o ids` prints one id per line, ready for `--ids -`. Items without an `id` are skipped with one warning.
+
+```bash
+kenso campaigns list --limit 3
+kenso campaigns list --limit 3 -o json
+kenso contacts list --campaign-id 812 --all -o ids
+```
+
+## Shape the output
+
+- `--fields a,b.c` keeps only those fields (dots reach into nested objects).
+- `--query <JMESPath>` filters or reshapes in-process, so you need no `jq`. On a list it sees the whole list.
+- Neither applies to a batch summary, which always prints in full.
+
+```bash
+kenso campaigns list --fields id,name,status
+kenso campaigns list --all --query "[?status=='active'].id"
+kenso me get --query "length(features)"
+```
+
+## Lists and pages
+
+A list command prints one page. When there are more, it prints the command for the next page on stderr, for example `next: kenso tags list --limit 1 --cursor MQ`. `--all` follows every page and streams the items. `--limit` sets the page size and `--cursor` starts at a cursor.
+
+```bash
+kenso tags list --limit 50
+kenso tags list --all
+```
+
+## Errors
+
+When stderr is not a terminal, an error is one JSON line on stderr:
+
+```json
+{"error":{"code":"unknown_flag","message":"Unknown flag --fiel for kenso contacts import.","field":"fiel","hint":"did you mean --file?","next":"kenso contacts import --help"}}
+```
+
+| Key | Always there | Meaning |
+|---|---|---|
+| `code` | yes | A stable snake_case code to branch on |
+| `message` | yes | One sentence for a person |
+| `field` | no | The flag or input field at fault |
+| `hint` | no | What to change |
+| `next` | no | The exact command to run next, such as `kenso auth login`, `kenso workspace list --q <name>` or the same command with `--yes` |
+| `httpStatus` | no | The API's HTTP status, when the API answered |
+| `requestId` | no | The API's request id: quote it when you contact Kenso support |
+
+On a terminal the same error prints as text: `Error: <message>`, then `field:`, `hint:`, `next:` and `requestId:` lines. The key never appears in an error.
+
+### How API errors map
+
+The CLI looks at the HTTP status first, then at the API's own `error.code`, which wins when present.
+
+| HTTP status | Default code | Exit |
+|---|---|---|
+| 400, 422 | `validation_failed` | 2 |
+| 401 | `unauthorized` (`next`: `kenso auth login`) | 3 |
+| 403 | `forbidden`: the key's user or role cannot do this in this workspace | 3 |
+| 404 | `not_found` | 4 |
+| 409 | `conflict` | 7 |
+| 429 | `rate_limited`, after the CLI waited and retried | 6 |
+| 5xx | `server_error`, after retries where they are safe | 8 |
+| anything else | `http_error` | 1 |
+
+Two API codes change the exit code: `workspace_required` exits 2 with `"next":"kenso workspace list --q <name>"`, and `limit_reached` (the plan's or the campaign's lead limit) exits 6.
+
+### Errors from the CLI itself
+
+| Code | Exit | When |
+|---|---|---|
+| `usage_error` | 2 | A required flag or argument is missing, or two flags conflict (`--yes` with `--dry-run`) |
+| `unknown_command` | 2 | No such command; `hint` suggests the closest one |
+| `unknown_flag`, `invalid_flag`, `invalid_flag_value`, `unexpected_argument` | 2 | A flag or argument the command does not take |
+| `invalid_query` | 2 | `--query` is not valid JMESPath |
+| `file_unreadable` | 2 | An input file is missing or cannot be parsed |
+| `config_invalid` | 2 | `~/.kenso/config.json` is not valid JSON: fix or delete it |
+| `feature_not_enabled` | 2 | Every action of the resource is a beta command your workspace has not enabled |
+| `invalid_key_format`, `key_required` | 2 | `auth login --with-key` read something that is not a Kenso key, or stdin is a terminal instead of a pipe |
+| `invalid_workspace_id` | 2 | `kenso workspace use` got an id that is not a positive whole number |
+| `unknown_topic` | 2 | `kenso docs` got a topic it does not have; `hint` lists the topics |
+| `file_unwritable` | 2 or 1 | An output file cannot be written: `contacts export --out` (2), `skill install` (1) |
+| `no_api_key` | 3 | No key in `KENSO_API_KEY` or the profile (`next`: `kenso auth login`) |
+| `browser_login_unavailable`, `access_denied`, `login_expired` | 3 | Browser login is off, was denied, or timed out |
+| `run_not_found` | 4 | `kenso runs show` or `resume` got an unknown run id |
+| `docs_not_found` | 4 | `kenso docs reference` before the reference was generated (a source checkout without `pnpm build`) |
+| `run_in_progress`, `already_filled` | 7 | Another process is working on the run, or `studio fill` already ran with this file and these flags |
+| `skill_exists` | 7 | `kenso skill install` found a different `SKILL.md`; `next` adds `--force` to replace it |
+| `job_timeout`, `job_failed`, `job_canceled` | 1 | `kenso jobs wait` (or a command that waits on a job) ran out of time, or the job failed or was canceled |
+| `mcp_tool_error` | 1 | `kenso mcp call`: the MCP tool answered with an error |
+| `unsafe_path` | 1 | `studio pull` refused a file path that would land outside `--dir` |
+| `network_error` | 8 | The API could not be reached after retries |
+| `upload_failed`, `download_failed` | 8 or 1 | A signed upload or download of a Studio file failed: 8 when storage was unreachable or answered 5xx, 1 on a 4xx (often an expired link: run the command again) |
+| `pull_incomplete` | 8 | `studio pull`: a file came back with neither text nor a download link |
+| `unexpected_response` | 1 or 8 | The API answered something the CLI could not read |
+| `unexpected_error` | 1 | A bug: run again with `--verbose` and report it |
+| `interrupted` | 130 | Ctrl-C |
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | OK, including a batch where every row succeeded or was skipped |
+| 1 | Unexpected error |
+| 2 | Usage or input error: a bad flag, a bad file, a validation error |
+| 3 | Auth: no key, an invalid, revoked or expired key, or HTTP 401 or 403 |
+| 4 | Not found |
+| 5 | Partial: the batch finished and some rows failed, were not found or were invalid. See `results.csv` |
+| 6 | Rate limited after retries, or a plan or campaign lead limit stopped the run (`limit_reached`) |
+| 7 | Conflict or invalid state (HTTP 409), or a run another process holds |
+| 8 | Server error after retries (5xx), or the API is unreachable |
+| 130 | Interrupted. A batch run can be resumed: see its `next` |
+
+Skipped rows (duplicates, blocklisted, already contacted) are not failures: a batch with only created, updated and skipped rows exits 0.
+
+## Flags
+
+- Command flags go after the command: `kenso contacts import --campaign 812`. Global flags can go anywhere.
+- A boolean flag takes `--flag`, `--no-flag`, `--flag=true` and `--flag=false`.
+- `--help` on any command prints its flags, arguments and examples. `kenso describe <resource> <action>` prints the same as JSON, with the body schema.
+
+## Beta commands
+
+Commands that need a workspace feature flag (CRM, Studio and others) are beta. Help and `kenso describe` hide the ones your workspace has not enabled and say how many they hid; `--all-commands` shows them. Calling a hidden command still works: Kenso decides. `kenso <resource>` on a resource whose every action is hidden answers `feature_not_enabled` (exit 2) and names the flags it needs.
+
+```bash
+kenso --help --all-commands
+kenso describe --all-commands
+```
+
+## What the CLI sends
+
+Every API call carries `Authorization: Bearer <key>`, `Ken-Version: 1.1`, `X-Ken-Workspace-Id` (when a workspace is picked), `User-Agent: kenso-cli/<version> (node <version>; <platform>)` and `X-Ken-Client: Kenso CLI`. When a coding agent runs the CLI, `X-Ken-Client` names it (`Kenso CLI via Claude Code`) and writes carry `X-Ken-Actor: agent`, so Kenso's activity log shows who made a change.