Skip to content

feat: live-data commands, and contact-list create, get, delete and contacts - #38

Merged
vigubikReply merged 4 commits into
mainfrom
dev/REPLY-53637-live-data-commands
Nov 9, 2026
Merged

vigubikReply merged 4 commits into
mainfrom
dev/REPLY-53637-live-data-commands

Conversation

@vigubikReply

@vigubikReply vigubikReply commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

What changed

  • reply live-data, a new command group over Reply's v3 Live Data searches:
    • preview (--filters … | --job-id …) [--max-per-company N] [--wait-seconds N] starts a preview and reads its job every 2 seconds for up to --wait-seconds (default 120, at most 600). It answers done with the people and companies the filters match and up to ten of them, or pending with the job id, which --job-id picks up later. A job that ends without a result is live_data.preview_failed, and an unknown job id is live_data.preview_not_found.
    • start --filters … --count N [--list-id N]… [--max-per-company N] [--with-phones] starts a search that adds up to N people and puts them on the given lists. It answers started with the search id.
    • get <id> and list read a search's status and counts, and the team's searches newest first.
    • pause <id>, resume <id> and delete <id> answer paused, resumed (or finished, with Reply's search_status, when the search already had everything it was asked for) and deleted.
    • filter-values <kind> [--search …] reads the values Reply suggests for industries, departments, seniorities, locations or job titles.
  • reply contact-list gains create --name - [--shared], get <list-id>, delete <list-id> and contacts <list-id> [--live-data-only]. contacts reads one page of the people on a list, oldest first by the date they were added, so the results of a search can be read back from the list it fills.
  • A list's name is read from stdin, like a sequence's. The reader that sequence list and sequence create used moves to stdin-input.ts and is shared.
  • The README's command table and Live Data section, and the reply-cli and reply-operations-mapping skills, describe the new commands.

How Reply's answers map

  • Filters go to Reply in Reply's own shape, untouched; the CLI does not translate or check its vocabulary. Reply's 400 invalidParameter is live_data.invalid_filters.
  • 409 searchInProgress is live_data.search_in_progress: an unfinished search of the same team with the same filters blocks a start.
  • 409 invalidStatus is live_data.invalid_status, with Reply's detail naming the status: pause applies to a running search, resume to a paused one.
  • 422 insufficientCredits is live_data.insufficient_credits, and 422 contactLimitReached is live_data.contact_limit_reached, the search owner's plan having no room for another contact.
  • 404 is live_data.not_found on a call that names a search. On start it is contact-list.not_found, a --list-id the account does not have or cannot reach; elsewhere it is Reply's refusal.
  • Each code is read only at the status Reply answers it with, so a 5xx that carries one stays outcome.unknown on a write.
  • Reply's 502 with its own upstreamFailure code is live_data.service_failed, exit 1. That 502 is definite: Reply saved nothing, or kept the search as it was, so the call can be made again. A 502 without that code stays outcome.unknown.
  • A lost answer to start is outcome.unknown with a hint to look in live-data list, since a second start may start, and charge for, a second search. A lost answer to delete says a repeat is safe and answers live_data.not_found if the first one went through.

Not in this PR

  • A preview job's result comes back from Reply as a JSON string with PascalCase keys, not as an object in v3's casing. preview parses it and renames the fields it answers, and the code marks this as a workaround until the API answers an object.
  • pause, resume and delete, and resume's contactLimitReached, need a Reply API that has them. This PR stays unmerged until they are live and the commands have been run against them.

How it was verified

The commands were built test-first against a stubbed fetch: each of Reply's refusals above, a lost answer on start and delete (the delete hint included), the usage errors raised before any call, preview's polling within its wait and its --job-id pick-up, and contacts' filter and order.

npm test: 63 files, 1016 passed, 2 skipped. tsc --noEmit passes.

…ntacts

Live Data finds people Reply does not hold yet. `reply live-data` covers its v3 searches end to end:
`preview` sizes an audience (and polls a running preview with `--job-id` and `--wait-seconds`),
`start` adds the people a search finds and puts them on the given lists, `get` and `list` read a
search's status and counts, `pause`, `resume` and `delete` manage a search, and `filter-values`
lists the values Reply suggests for a filter. Reply's refusals map to stable codes:
`live_data.search_in_progress`, `live_data.insufficient_credits`, `live_data.contact_limit_reached`,
`live_data.invalid_status`, `live_data.invalid_filters`, `live_data.not_found` and
`live_data.service_failed`.

`reply contact-list` gains `create`, `get`, `delete` and `contacts` (one page of the people on a
list, oldest first, optionally Live Data contacts only), so the results of a search can be read
back from the list it fills. A list's name is read from stdin like a sequence's, through one shared
reader.

The README and the reply-adapter skills describe the new commands.

@ArtemKosolap ArtemKosolap left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read against the public OpenAPI document and the CLI's own conventions, with tsc --noEmit and the suite run in a fresh clone (63 files green; the skipped count differs from the body only by the three POSIX-only file-permission tests).

The unit is sound: every Live Data refusal goes through the repository's own refusal fall-through, nothing repeats a write that could charge twice, the filters are never logged or written, the stdin reader's move keeps sequence list and sequence create as they were, the tests cover each refusal the body names, and the added lines carry nothing internal.

Five points are worth fixing before the dev-API run the body already waits for, so this is a comment rather than an approval until they are in; the rest are suggestions. Inline, by weight:

  1. 422 liveDataSearch.noMatchingContacts at start is not mapped and falls to the generic reply.refused.
  2. Every 404 reads as "no such search", including from start, preview, list and filter-values, and codes are matched without their status.
  3. resume prints resumed for any status but finished; the body and the help give finished two meanings.
  4. The preview's result is accepted only as a string, so the API change the INTERIM note asks for would break every finished preview; a status the code does not name polls silently to pending.
  5. The operations-mapping skill still routes what a search finds through contact.create / import.apply.

Also worth a test: the hint on start's lost answer, on both the 5xx and the transport-loss path, since start is the one Live Data verb where a repeat charges.

Comment thread src/operations/live-data.ts Resolved
Comment thread src/operations/live-data.ts Resolved
Comment thread src/operations/live-data.ts Resolved
Comment thread src/operations/live-data.ts Resolved
Comment thread src/operations/live-data.ts Resolved
Comment thread src/operations/contact-list.ts Resolved
Comment thread src/operations/contact-list.ts Resolved
Comment thread README.md Resolved
… answers as Reply gives them

- Each Live Data code is read only at the status Reply answers it with, so a 5xx carrying one
  stays an unknown outcome on a write. A 404 is live_data.not_found only on a call that names a
  search; on start it is contact-list.not_found (a --list-id the account does not have or cannot
  reach), and elsewhere Reply's refusal.
- resume answers resumed for inProgress, finished with Reply's search_status for finished or
  noMoreContacts, and any other status is an unknown outcome.
- preview reads the job's result as a string or an object, in either key casing, and its status
  without regard to case; a status v3 does not name is unreadable instead of a silent pending.
  --max-per-company with --job-id is a usage error, and a lost answer to the start says a repeat
  is safe.
- contact-list create, after an unknown outcome, points at the lookup by name.
- The operations-mapping skill no longer routes Live Data results through contact.create or
  import.apply, and says resuming does not free a search's filters.

@ArtemKosolap ArtemKosolap left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Read e0c5d33 whole against the first review, with tsc --noEmit and the suite in a fresh clone (63 files, 1013 passed, 5 skipped).

The five points are in: every Live Data code is read at its status, and a 404 means a missing search only where one is named; resume answers resumed, or finished with Reply's status, and any other status is an unknown outcome; the preview reads its result as a string or an object in either casing, and a status it does not know is unreadable after one read instead of a silent pending; the operations-mapping skill no longer routes a search's people through contact.create or import.apply; start's lost answer is tested on the 5xx, the empty 2xx and the lost-connection paths, with the hint asserted. The nits are in as well, and the two answers hold: the start's 422 under its older name is the credits refusal and stays unmapped, and creationSource is documented with the coming change.

Approving. The merge waits, as the body says, on the pause, resume and delete endpoints being on dev and the run against them.

Run against Reply's dev API, a preview job answers its result as a JSON string in v3's camelCase,
not in PascalCase. The reader takes exactly that, as a string or an object, and the tests' recorded
answers are now the ones dev gave: a preview with null counts, and the start refusal's own words.
@vigubikReply
vigubikReply merged commit 73e5b0c into main Nov 9, 2026
6 checks passed
@vigubikReply
vigubikReply deleted the dev/REPLY-53637-live-data-commands branch November 9, 2026 20:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants