autotouch-cli 0.2.25__tar.gz → 0.2.27__tar.gz

{autotouch_cli-0.2.25 → autotouch_cli-0.2.27}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: autotouch-cli
-Version: 0.2.25
+Version: 0.2.27
 Summary: Autotouch Smart Table CLI
 Requires-Python: >=3.9
 Description-Content-Type: text/markdown
@@ -21,7 +21,7 @@ Use this order when you are orienting in the CLI:
 2. Use the API endpoint -> CLI command map when translating an existing API workflow.
 3. Use `autotouch columns recipe` before creating provider-backed workflow columns.
 4. Use `autotouch jobs get` as the source of truth for async run state.
-5. Use raw HTTP for sequences/tasks workflows; those endpoints share the same developer-key model but do not yet have dedicated CLI commands.
+5. Use `autotouch sequences ...` for sequence definitions, status changes, and direct enrollments; tasks still use raw HTTP.
 
 ### Quick decision guide
 
@@ -36,13 +36,20 @@ Use this order when you are orienting in the CLI:
 | run one exact row or an explicit list of row IDs | `scope=row` for one ID, `scope=subset` for many IDs |
 | verify whether a job is really done | `autotouch jobs get --job-id <JOB_ID>` |
 | create projections from JSON output | `autotouch columns projections` |
-| work with sequences/tasks | raw HTTP plus `docs/platform/external-workflows-api.md` |
+| create/manage sequence definitions directly | `autotouch sequences recipe`, then `autotouch sequences create/update/activate` |
+| enroll leads directly into a sequence | `autotouch sequences enroll --sequence-id <SEQUENCE_ID> ...` |
+| enroll table rows into an existing sequence | `autotouch columns recipe --type add_to_sequence`, then `autotouch columns create` + `autotouch columns run` |
+| create or update a CRM lead | `autotouch leads recipe --type create`, then `autotouch leads create` / `autotouch leads update` |
+| add email or phone contact info to a lead | `autotouch leads recipe --type contact_upsert`, then `autotouch leads upsert-contact-channels --lead-id <LEAD_ID> ...` |
+| bulk update lead status or owner | `autotouch leads update-status` / `autotouch leads reassign-owner` |
+| manage tasks directly | raw HTTP plus `docs/platform/external-workflows-api.md` |
+| query/filter CRM leads and attached research | `autotouch leads query` then `autotouch leads research` |
 
 ### Operating model
 
 - This file is the full CLI reference and the package readme published to PyPI.
 - The installed package gives you CLI entrypoints and package metadata; do not assume there is a separate installed docs directory.
-- Research-table APIs are the primary CLI surface today; workflow APIs (sequences/tasks) are still HTTP-first.
+- Research-table APIs, sequence commands, and lead create/query/update operations are the primary CLI surface today; direct task management is still HTTP-first.
 - For async operations, backend bulk-job state is authoritative; local terminal output is only a convenience layer.
 - For staged or cost-sensitive runs, estimate first and prefer filtered scopes plus `firstN` or `run-next`.
 
@@ -128,9 +135,41 @@ Notes:
 | `POST /api/tables/{table_id}/columns/{column_id}/stop` | `autotouch columns stop --table-id <TABLE_ID> --column-id <COLUMN_ID>` |
 | `GET /api/bulk-jobs` | `autotouch jobs list --table-id <TABLE_ID> --column-id <COLUMN_ID> --limit 10` |
 | `GET /api/bulk-jobs/{job_id}` | `autotouch jobs get --job-id <JOB_ID>` |
+| `GET /api/sequences` | `autotouch sequences list --limit 50` |
+| `GET /api/sequences/{sequence_id}` | `autotouch sequences get --sequence-id <SEQUENCE_ID>` |
+| `GET /api/sequences/{sequence_id}/stats` | `autotouch sequences stats --sequence-id <SEQUENCE_ID>` |
+| `GET /api/sequences/delivery-status` | `autotouch sequences delivery-status` |
+| `POST /api/sequences` | `autotouch sequences create --data-file sequence.json` |
+| `PUT /api/sequences/{sequence_id}` | `autotouch sequences update --sequence-id <SEQUENCE_ID> --data-file sequence.json` |
+| `DELETE /api/sequences/{sequence_id}` | `autotouch sequences delete --sequence-id <SEQUENCE_ID> --yes` |
+| `POST /api/sequences/{sequence_id}/clone` | `autotouch sequences clone --sequence-id <SEQUENCE_ID>` |
+| `PATCH /api/sequences/{sequence_id}/status` | `autotouch sequences status --sequence-id <SEQUENCE_ID> --status ACTIVE` |
+| `POST /api/sequences/{sequence_id}/enroll` | `autotouch sequences enroll --sequence-id <SEQUENCE_ID> --lead-id <LEAD_ID>` |
+| `POST /api/sequences/{sequence_id}/enrollments/pause` | `autotouch sequences pause-enrollment --sequence-id <SEQUENCE_ID> --lead-id <LEAD_ID>` |
+| `GET /api/leads/{lead_id}` | `autotouch leads get --lead-id <LEAD_ID>` |
+| `POST /api/leads` | `autotouch leads create --data-file lead.json` |
+| `PUT /api/leads/{lead_id}` | `autotouch leads update --lead-id <LEAD_ID> --data-file patch.json` |
+| `POST /api/leads/{lead_id}/contact-channels` | `autotouch leads upsert-contact-channels --lead-id <LEAD_ID> --data-file contacts.json` |
+| `POST /api/leads/bulk_update_status` | `autotouch leads update-status --lead-id <LEAD_ID> --status contacting` |
+| `POST /api/leads/bulk_reassign_owner` | `autotouch leads reassign-owner --lead-id <LEAD_ID> --user-id <USER_ID>` |
+| `POST /api/leads/query` | `autotouch leads query --filter-file lead-filter.json --limit 50` |
+| `POST /api/leads/query/count` | `autotouch leads count --filter-file lead-filter.json` |
+| `POST /api/leads/query/stats` | `autotouch leads stats --filter-file lead-filter.json` |
+| `POST /api/leads/query/research` | `autotouch leads research --lead-id <LEAD_ID> --source-table-id <TABLE_ID>` |
+| `GET /api/leads/filters/metadata` | `autotouch leads filters-metadata` |
+| `GET /api/leads/research-tables/available` | `autotouch leads research-tables` |
 | `GET /api/tables/{table_id}/webhook` | `autotouch webhooks get --table-id <TABLE_ID>` |
 | `POST /api/tables/{table_id}/webhook` | `autotouch webhooks rotate --table-id <TABLE_ID>` |
 | `POST /api/webhooks/tables/{table_id}/ingest` | `autotouch webhooks ingest --table-id <TABLE_ID> --records-file records.json --webhook-token <WEBHOOK_TOKEN>` |
+| `GET /api/webhook-subscriptions` | `autotouch webhooks subscriptions list --limit 100` |
+| `POST /api/webhook-subscriptions` | `autotouch webhooks subscriptions create --data-file subscription.json` |
+| `GET /api/webhook-subscriptions/{subscription_id}` | `autotouch webhooks subscriptions get --subscription-id <SUBSCRIPTION_ID>` |
+| `PATCH /api/webhook-subscriptions/{subscription_id}` | `autotouch webhooks subscriptions update --subscription-id <SUBSCRIPTION_ID> --data-file patch.json` |
+| `DELETE /api/webhook-subscriptions/{subscription_id}` | `autotouch webhooks subscriptions delete --subscription-id <SUBSCRIPTION_ID>` |
+| `POST /api/webhook-subscriptions/{subscription_id}/pause` | `autotouch webhooks subscriptions pause --subscription-id <SUBSCRIPTION_ID>` |
+| `POST /api/webhook-subscriptions/{subscription_id}/resume` | `autotouch webhooks subscriptions resume --subscription-id <SUBSCRIPTION_ID>` |
+| `POST /api/webhook-subscriptions/{subscription_id}/rotate-secret` | `autotouch webhooks subscriptions rotate-secret --subscription-id <SUBSCRIPTION_ID>` |
+| `POST /api/webhook-subscriptions/{subscription_id}/test` | `autotouch webhooks subscriptions test --subscription-id <SUBSCRIPTION_ID>` |
 | `POST /api/auth/agent-bootstrap` | HTTP-only bootstrap (no direct CLI wrapper yet) |
 
 ## Delete column
@@ -146,19 +185,81 @@ CLI:
 autotouch columns delete --table-id <TABLE_ID> --column-id <COLUMN_ID> --yes
 ```
 
-## Workflow API coverage (sequences/tasks)
+## Sequence commands
+
+The CLI now exposes the public Sequences endpoints under `autotouch sequences`.
+Tasks still use raw HTTP plus `docs/platform/external-workflows-api.md`.
+
+Common commands:
+- `autotouch sequences recipe --type create --out-file sequence.json`
+- `autotouch sequences recipe --type bulk_automated --out-file sequence.json`
+- `autotouch sequences create --data-file sequence.json`
+- `autotouch sequences update --sequence-id <SEQUENCE_ID> --data-file sequence.json`
+- `autotouch sequences activate --sequence-id <SEQUENCE_ID>`
+- `autotouch sequences pause --sequence-id <SEQUENCE_ID>`
+- `autotouch sequences archive --sequence-id <SEQUENCE_ID>`
+- `autotouch sequences enroll --sequence-id <SEQUENCE_ID> --lead-id <LEAD_ID> --wait`
+- `autotouch sequences pause-enrollment --sequence-id <SEQUENCE_ID> --lead-id <LEAD_ID>`
+- `autotouch sequences delivery-status`
+- `autotouch sequences list --include-stats`
+
+Important contract notes:
+- Create/update via developer key still requires `sourceTableId`.
+- Mutating sequence commands accept `--actor-user-id` for explicit actor resolution.
+- Recommended default: personal delivery plus `EMAIL` steps with `emailSendMode=MANUAL` and `aiDraft=true`.
+- Use `bulk_automated` only when the provider should send email automatically at scale. `aiDraft` does not apply to bulk automated email steps.
+- Personal delivery uses the connected inbox for the enrolled owner (`assignedToUserId`, else the enrolling actor); there is no per-sequence personal sender picker yet.
+- If that user has multiple connected personal inboxes for the same provider, the most recently updated one is used. Gmail is tried before Microsoft. Sender stays pinned after the first personal email in that enrollment.
+- Bulk delivery uses `emailDelivery.bulkProvider`; Instantly can also narrow sending accounts via `emailDelivery.providerConfig.instantly.selectedAccounts`.
+- `activate`, `pause`, and `archive` are convenience wrappers around `autotouch sequences status`.
+- `autotouch sequences enroll --wait` polls `/api/bulk-jobs/{job_id}` and preserves the API response `task_id` as the bulk job id.
+- Research-table `add_to_sequence` is still available through `autotouch columns create/update/run` and still targets an existing sequence.
+- Real enrollment requires the target sequence to be `ACTIVE` unless direct enroll uses `reviewOnly=true`.
+- Tasks remain HTTP-only.
+
+AI draft outputs:
+- Manual new email: subject + body
+- Manual reply email: reply body
+- LinkedIn connect: connection note
+- LinkedIn message: message copy
+- Call: call script
+
+Example:
 
-Sequences/tasks APIs are supported by the backend developer-key model but do not yet have dedicated `autotouch` CLI commands.
+```bash
+autotouch sequences recipe --type create --out-file sequence.json
+autotouch sequences create --data-file sequence.json
+autotouch sequences activate --sequence-id <SEQUENCE_ID>
+```
+
+Cookbooks:
+
+1. Recommended personal AI-assisted outreach
+
+```bash
+autotouch sequences recipe --type create --out-file sequence.json
+autotouch sequences create --data-file sequence.json
+autotouch sequences activate --sequence-id <SEQUENCE_ID>
+autotouch sequences enroll --sequence-id <SEQUENCE_ID> --lead-ids-file lead_ids.json --wait
+```
 
-Use raw HTTP for these endpoints today, with the same `stk_...` key:
-- `POST /api/sequences`
-- `PUT /api/sequences/{sequence_id}`
-- `PATCH /api/sequences/{sequence_id}/status`
-- `POST /api/sequences/{sequence_id}/enroll`
-- `POST /api/task-queue/create`
-- `PUT /api/task-queue/{task_id}`
-- `POST /api/task-queue/{task_id}/draft`
-- `POST /api/task-queue/{task_id}/email/schedule`
+Notes:
+- `recipe --type create` is the recommended default.
+- It starts with personal delivery, a manual AI-drafted email, then AI-drafted call and LinkedIn follow-up steps.
+- Favorite/starred research fields are the default grounding context when explicit `fieldIds` are not provided.
+
+2. Bulk automated email sequence
+
+```bash
+autotouch sequences recipe --type bulk_automated --out-file sequence.json
+autotouch sequences create --data-file sequence.json
+autotouch sequences activate --sequence-id <SEQUENCE_ID>
+autotouch sequences enroll --sequence-id <SEQUENCE_ID> --lead-ids-file lead_ids.json --wait
+```
+
+Notes:
+- Use this when Instantly or Smartlead should send email automatically.
+- Bulk automated email steps do not support `aiDraft`; author the templates directly in `subjectTemplate` and `bodyTemplate`.
 
 Reference contract (actor model + manual/automated/AI-draft nuances):
 - `docs/platform/external-workflows-api.md`
@@ -168,6 +269,116 @@ Signature controls for sequence payloads:
 - `steps[].appendSignature` (optional, step-level) overrides signature behavior for a specific email step.
 - Signature append is deterministic at send time when enabled for the step.
 
+## Leads API coverage
+
+The CLI now exposes the public leads read + write endpoints under `autotouch leads`.
+
+Use this pattern:
+
+1. `autotouch leads create` when you need to create one lead from canonical JSON input.
+2. `autotouch leads recipe` when you want a ready-to-edit payload for create, update, or contact upsert.
+3. `autotouch leads update` for scalar or partial lead updates.
+4. `autotouch leads upsert-contact-channels` when you need to add or merge emails/phones without replacing the full arrays.
+5. `autotouch leads update-status` / `autotouch leads reassign-owner` for operational bulk changes by explicit IDs or descriptor selection.
+6. `autotouch leads query` to page through leads, apply descriptor filters, and inspect `related_tables` / `research_summary`.
+7. `autotouch leads research` when you need actual research field values for specific lead IDs from one source table.
+
+Important contract notes:
+- External callers should use `POST /api/leads/query` rather than the older `GET /api/leads` list route.
+- `autotouch leads get` is the direct single-lead lookup path.
+- Use `autotouch leads update` for scalar lead fields only.
+- `autotouch leads update` rejects email/phone fields and points callers to `autotouch leads upsert-contact-channels`.
+- Contact upsert merges into canonical `email_addresses` and `phone_numbers` instead of replacing those arrays.
+- `update-status` and `reassign-owner` accept either explicit lead IDs or descriptor selection input (`--filter-json`, `--search`, `--scope`, etc.).
+- `autotouch leads query` accepts the same descriptor payload shape as the backend:
+  - `filter`
+  - `search`
+  - `sort`
+  - `pagination`
+  - `scope`
+  - optional research context (`source_table_id`, `source_table_scope`, `related_tables_mode`)
+- Research values are best treated as a follow-up call:
+  - `query` returns lead rows plus research linkage metadata
+  - `research` returns `research_data_by_id` keyed by lead id for one `source_table_id`
+
+Examples:
+
+```bash
+autotouch leads recipe --type create --out-file lead.json
+autotouch leads create --data-file lead.json
+autotouch leads get --lead-id <LEAD_ID>
+```
+
+```bash
+autotouch leads recipe --type update --out-file lead-patch.json
+autotouch leads update \
+  --lead-id <LEAD_ID> \
+  --data-file lead-patch.json
+```
+
+```bash
+autotouch leads recipe --type contact_upsert --out-file contacts.json
+autotouch leads upsert-contact-channels \
+  --lead-id <LEAD_ID> \
+  --data-file contacts.json
+```
+
+`contacts.json` example:
+
+```json
+{
+  "emails": [
+    { "address": "john@acme.com", "type": "work", "primary": true }
+  ],
+  "phones": [
+    { "number": "+14155551234", "type": "mobile", "primary": true }
+  ]
+}
+```
+
+```bash
+autotouch leads update-status \
+  --filter-json '{"root":{"kind":"rule","field":"lead_status","operator":"eq","value":"new"}}' \
+  --status contacting
+```
+
+```bash
+autotouch leads reassign-owner \
+  --lead-id <LEAD_ID_1> \
+  --lead-id <LEAD_ID_2> \
+  --user-id <USER_ID>
+```
+
+```bash
+autotouch leads query \
+  --filter-json '{"root":{"kind":"rule","field":"status","operator":"eq","value":"new"}}' \
+  --limit 25
+```
+
+```bash
+autotouch leads count \
+  --search "fintech" \
+  --scope org
+```
+
+```bash
+autotouch leads stats \
+  --source-table-id <TABLE_ID> \
+  --source-table-scope company
+```
+
+```bash
+autotouch leads research \
+  --lead-id <LEAD_ID_1> \
+  --lead-id <LEAD_ID_2> \
+  --source-table-id <TABLE_ID>
+```
+
+```bash
+autotouch leads filters-metadata
+autotouch leads research-tables
+```
+
 ## Bulk job status contract (authoritative run state)
 
 Use bulk jobs as the source of truth for run lifecycle:
@@ -184,6 +395,7 @@ Important fields:
 - `total_rows`: scoped row count for the run
 - `pending_batches`: derived remaining batches
 - `terminal_reason`: terminal classifier
+- timing checkpoints: `enqueued_at`, `orchestrator_started_at`, `provider_started_at`, `provider_completed_at`
 
 Terminal states:
 - `completed`
@@ -435,11 +647,13 @@ Notes:
 }
 ```
 
-Add-to-Leads note: mapped LinkedIn URL + company domain are required; run is non-billable.
+Add-to-Leads note: `companyDomain` is required; LinkedIn is optional. Each row still needs at least one usable hard identity signal (LinkedIn, email, or phone). Names and location fields are metadata only for this flow. Run is non-billable.
 If `companyDomain` is missing in the table, derive or enrich that domain column first, then rerun `add_to_crm`.
+Queued lifecycle: the CLI/API accepts the run immediately, then the backend hands off `ops -> data_io` for execution.
 
 CRM data model expectations (recommended before `add_to_crm`):
-- Lead identity/dedupe expects `linkedin_url` + `company_domain` (clean domain like `example.com`).
+- Lead identity/dedupe expects `company_domain` plus one usable hard identity signal. `linkedin_url` is a strong optional signal, not a requirement.
+- Placeholder or malformed hard identifiers are treated as missing during research-table export. Rows without any surviving LinkedIn/email/phone signal are skipped instead of erroring.
 - `company_domain` is required; `company_name` is only a display hint and is applied to the linked Company record when provided.
 - Lead records link to Company via `company_id`; company names live on Company docs, not as canonical lead fields.
 - Canonical contact fields are arrays (`email_addresses[]`, `phone_numbers[]`); top-level `email`/`mobile_number` may exist on legacy rows but should not be treated as source of truth.
@@ -496,7 +710,7 @@ Notes:
 ```
 
 Notes:
-- `sourceLeadColumn` must point to a column that stores lead IDs (for example `add_to_crm` or `lead_finder` output).
+- `sourceLeadColumn` must be the source column key that stores lead IDs (for example `add_to_leads` or another lead-id column key from `lead_finder` output), not the provider name `add_to_crm`.
 - `sequenceId` is the target sequence workflow ID.
 - The target sequence must already be `ACTIVE` for real enrollment. Table `add_to_sequence` runs and direct `POST /api/sequences/{id}/enroll` share the same activation check.
 - `add_to_sequence` runs auto-attach `research_context.source_table_id` (and table name when available). Field selection stays implicit so sequence drafts/audience resolve favorites from current starred columns by default.
@@ -511,12 +725,21 @@ autotouch tables create --name "CLI Contacts"
 autotouch rows import-csv --table-id <TABLE_ID> --file contacts.csv
 autotouch columns recipe --type add_to_crm --out-file column.json
 autotouch columns create --table-id <TABLE_ID> --data-file column.json
+autotouch sequences recipe --type create --out-file sequence.json
+autotouch sequences create --data-file sequence.json
+autotouch sequences activate --sequence-id <SEQUENCE_ID>
 autotouch columns recipe --type add_to_sequence --out-file add-to-sequence.json
 autotouch columns create --table-id <TABLE_ID> --data-file add-to-sequence.json
 autotouch columns run-next --table-id <TABLE_ID> --column-id <COLUMN_ID> --count 25 --filters-file filters.json --show-estimate --wait
 autotouch jobs get --job-id <JOB_ID>
 ```
 
+Sequence creation note:
+- The CLI can create/update/activate sequence definitions directly with `autotouch sequences ...`.
+- Research-table `add_to_sequence` columns and direct `autotouch sequences enroll` both target an existing sequence.
+- Real enrollment still requires that sequence to be `ACTIVE` unless direct enroll uses `reviewOnly=true`.
+- Tasks still use raw HTTP.
+
 ## Safe run patterns (`firstN` + `--unprocessed-only`)
 
 Use this pattern for progressive rollouts.