From 25582e33420846c2dc63533b5c7d6e4f32915e6a Mon Sep 17 00:00:00 2001 From: vigubikReply Date: Mon, 9 Nov 2026 12:53:39 -0500 Subject: [PATCH 1/4] feat: live-data commands, and contact-list create, get, delete and contacts 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. --- README.md | 56 ++++- skills/reply-adapter/reply-cli/SKILL.md | 13 +- .../reply-operations-mapping/SKILL.md | 18 +- src/__tests__/operations/commands.test.ts | 6 +- src/__tests__/operations/contact-list.test.ts | 83 ++++++- .../operations/live-data-preview.test.ts | 98 ++++++++ src/__tests__/operations/live-data.test.ts | 175 ++++++++++++++ src/__tests__/operations/program.test.ts | 9 + src/index.ts | 4 +- src/operations/commands.ts | 216 +++++++++++++++++- src/operations/contact-list.ts | 111 ++++++++- src/operations/live-data-preview.ts | 142 ++++++++++++ src/operations/live-data.ts | 198 ++++++++++++++++ src/operations/sequence-by-name.ts | 21 +- src/operations/stdin-input.ts | 16 +- 15 files changed, 1119 insertions(+), 47 deletions(-) create mode 100644 src/__tests__/operations/live-data-preview.test.ts create mode 100644 src/__tests__/operations/live-data.test.ts create mode 100644 src/operations/live-data-preview.ts create mode 100644 src/operations/live-data.ts diff --git a/README.md b/README.md index 851dd9f..b26c5aa 100644 --- a/README.md +++ b/README.md @@ -196,6 +196,14 @@ prints JSON (indented; compact with `--json`) and says what happened in a stable | `reply sequence pause ` | → `paused` | | `reply sequence start [--expect-contacts N]` | → `started` / `already_active` | | `reply contact-list add-contact [--refuse-opted-out]` | → `added` | +| `reply contact-list create --name - [--shared]` | make an empty list of a name → `created` | +| `reply contact-list get ` · `reply contact-list delete ` | the list as Reply holds it · → `deleted` | +| `reply contact-list contacts [--live-data-only] [--limit] [--offset]` | one page of the people on a list, oldest first | +| `reply live-data preview (--filters … \| --job-id …) [--wait-seconds N]` | how many people and companies the filters match, and up to ten of them → `done` / `pending` | +| `reply live-data start --filters … --count N [--list-id N]… [--max-per-company N] [--with-phones]` | a search that adds the people it finds and puts them on the lists → `started` | +| `reply live-data get ` · `reply live-data list` | a search's status and counts · the team's searches, newest first | +| `reply live-data pause ` · `resume ` · `delete ` | → `paused` · `resumed` / `finished` · `deleted` | +| `reply live-data filter-values [--search …]` | values Reply suggests for industries, departments, seniorities, locations or job titles | | `reply contact find --contact -` | the id of the contact under an email or a LinkedIn URL, or null; never creates one | | `reply contact get ` | the contact as Reply holds it | | `reply contact update ( \| ) --fields -` | change some fields and custom fields; null clears one → `updated` | @@ -447,9 +455,49 @@ reply schedule list --json # "reply_status":"isDefaultForCurrentUser"}]} ``` -`inbox reply`, `sequence create` and the five direct sends are the work commands that are not safe to -re-run. On exit 3 (outcome unknown) a reply or a send may already have gone, and running it again may -send it twice, unless the hint says nothing was sent. A direct send's exit 3 comes from a lost +Live Data finds people Reply does not hold yet. `reply live-data preview` sizes an audience before +anything is spent: how many people and companies the filters match, and up to ten of them. Nothing is +saved or charged. Reply works a preview out as a background job, which the command reads every two +seconds for up to `--wait-seconds` (default 120). Reading it needs the key's `other:read` scope. When +the wait runs out first the answer is `pending` with the `job_id`, and `--job-id` goes on waiting. +The filters are Reply's own object, as the API documents it, passed on untouched; the +`filter-values` lists are suggestions, not a vocabulary Reply checks. + +A search adds the people it finds as contacts and puts them on the lists named, so make a list first +and read the people off it: + +```sh +echo '{"name":"Audience 12"}' | reply contact-list create --name - --json +# {"status":"created","list_id":77,"name":"Audience 12","is_shared":false} +echo '{"jobTitles":[{"value":"CTO","type":"include"}]}' | reply live-data start --filters - --count 25 --list-id 77 --json +# {"status":"started","search_id":901} +reply live-data get 901 --json # status, contactsFound, usedCredits, lists +reply contact-list contacts 77 --limit 1000 --offset 0 --json # the people found so far, oldest first +``` + +`contact-list contacts` reads oldest first by the date a contact was added, equal dates by contact id, +highest first, an order that holds from page to page. A search adds each batch at the end of it, so for a +list one search fills, the number of people already read is a cursor that only moves forward: pass it +as `--offset`. A person Reply already holds is skipped by the search, not put on the list. + +Reply refuses a start (`live_data.search_in_progress`) while an unfinished search of the same team has +the same filters, running or paused; the lists, the count, people per company and phones don't count, +and searches with different filters run side by side. That refusal holds only while the first search +is unfinished: one that already finished or was deleted no longer blocks, so after exit 3 a second +`live-data start` may start, and charge for, a second search. Look in `live-data list` first, where a +search shows its lists. `pause` applies to a running +search, `resume` to a paused one (`live_data.invalid_status` otherwise, Reply's detail naming the +status), and a resume without the credits for one contact is `live_data.insufficient_credits`. A +search paused by the plan's contact limit stays paused while its owner has no room for another +contact: that resume is `live_data.contact_limit_reached`. +`live_data.service_failed` is Reply's search service failing: nothing changed, and the call can be +made again. Read a search's final counts before `live-data delete`: a deleted search answers +`live_data.not_found`. The contacts it added stay. + +`inbox reply`, `sequence create`, `live-data start` and the five direct sends are the work commands that +are not safe to re-run. On exit 3 (outcome unknown) a reply or a send may already have gone, and running +it again may send it twice, unless the hint says nothing was sent; a search may already have started +(above). A direct send's exit 3 comes from a lost answer, a 5xx, or a 400 to the send whose JSON carries neither a `code` nor `errors[]`, which is Reply failing while it made the send. On a LinkedIn send, a 400 `directLinkedIn.unknown` is the same: Reply failed while making the send or could not map the provider's answer, and its code is @@ -470,7 +518,7 @@ Reply refused the add. `reply.invalid_request` means Reply didn't accept a field **Exit codes.** `0` done · `1` failed, and the main effect did not happen · `2` usage error, nothing sent · `3` **outcome unknown**: a write may have happened and no answer came back. Re-running the -same command is safe, except `inbox reply`, `sequence create` and the direct sends (above): each of +same command is safe, except `inbox reply`, `sequence create`, `live-data start` and the direct sends (above): each of the others checks or relies on Reply's own state rather than repeating an effect blindly. **Retries.** Reads are retried on errors. A write is retried only when it can't have reached Reply: diff --git a/skills/reply-adapter/reply-cli/SKILL.md b/skills/reply-adapter/reply-cli/SKILL.md index c5651ec..0dc6265 100644 --- a/skills/reply-adapter/reply-cli/SKILL.md +++ b/skills/reply-adapter/reply-cli/SKILL.md @@ -6,7 +6,7 @@ description: > Use when executing any Reply.io operation from a shell, setting up authentication, or when another Reply skill needs commands executed. metadata: - version: 1.3.1 + version: 1.3.2 pack: reply-adapter category: execution maturity: reviewed @@ -145,10 +145,10 @@ exit codes with their error `code` slugs. - `Not authenticated` → run the auth setup above. - `TEAM_REQUIRED` / `TEAM_NOT_ACCESSIBLE` / `USER_REQUIRED` / `USER_NOT_FOUND` → see `reply-auth` skill; the CLI's stderr guidance shows the exact fix. -- Discrete domain commands (e.g. `reply sequences list`) are **not available yet**. The command - groups are `auth`, `profile`, `team`, `api`, `skills` and `install` — nothing else exists. - Don't invent one: reach the operation through `reply api`, using the endpoint mapping in - `reply-operations-mapping`. +- Work commands exist for the most common operations (`sequence`, `contact-list`, `live-data`, + `contact`, `inbox`, `account`, `schedule`, `direct-send`); `reply --help` lists them and each + command's `--help` gives its result and error codes. Don't invent one: reach any other operation + through `reply api`, using the endpoint mapping in `reply-operations-mapping`. ## Safety @@ -165,6 +165,9 @@ explicit confirmation its Safety section requires. ## Changelog +- 1.3.2 (2026-11-06): *Failure modes* no longer says the work commands don't exist: it names the groups + (`sequence`, `contact-list`, `live-data`, `contact`, `inbox`, `account`, `schedule`, `direct-send`) and + keeps `reply api` for every other operation. - 1.3.1 (2026-11-05): `reply api` says that a 429 naming a `reference` or saying a daily or weekly limit was reached is never resent and comes back at once as the refusal it is. - 1.3.0 (2026-08-10): said plainly that reaching the whole API is not reaching the whole job — the diff --git a/skills/reply-adapter/reply-operations-mapping/SKILL.md b/skills/reply-adapter/reply-operations-mapping/SKILL.md index c94e0de..e7a2cd2 100644 --- a/skills/reply-adapter/reply-operations-mapping/SKILL.md +++ b/skills/reply-adapter/reply-operations-mapping/SKILL.md @@ -8,7 +8,7 @@ description: > interpreting in business terms, or when you need to know whether Reply can do a thing at all before promising it to a user. metadata: - version: 2.3.0 + version: 2.3.1 pack: reply-adapter category: execution maturity: draft @@ -261,10 +261,12 @@ them wrong: and the AI-SDR cluster are documented Beta or Coming soon. That belongs in the sentence where the user chooses the route, before they commit to it — not in a caveat after the work. Fetch the doc page and confirm the endpoint is callable, exactly as with any other surface. -3. **One Live Data search runs per team at a time.** This is a Reply fact and it belongs nowhere - else. An agent that does not know it will plan several searches in parallel and stall, or read - the refusal as a failure and retry it. Plan searches in series, and if one is already running, - the honest report is that the queue is occupied and by what. +3. **One unfinished search per filter set.** Reply refuses a start while an unfinished search of + the same team has the same filters, running or paused; searches with different filters run side + by side, and the target lists don't count. This is a Reply fact and it belongs nowhere else. An + agent that does not know it will read the refusal as a failure and retry it. Before running the + same filters again, finish the earlier search: resume it, or delete it once its final counts + are read. Build the filter from the typeahead values — departments, industries, job titles, locations, seniorities — rather than guessing accepted ones. Check the existing searches before starting a @@ -388,7 +390,8 @@ says — never let it disappear from the report because nothing was called. what *this credential* may do is `capability.list`, and here that is answered by an `insufficient_scope` refusal rather than by a listing. - **Parallelising measurement** reads and hitting `429`, then retrying harder. -- **Planning two Live Data searches at once.** One runs per team at a time; the second stalls. +- **Running the same Live Data filters twice at once.** The second start is refused while the first + search is unfinished, running or paused; searches with different filters run side by side. - **Starting a Live Data search without previewing it.** Start spends the user's allowance; the mistake is only visible once it is already paid for. - **Presenting a beta surface as settled**, or a *coming soon* one as callable. Contact enrichment @@ -424,6 +427,9 @@ those as irreversible with no window and say so before acting rather than after. ## Changelog +- 2.3.1 (2026-11-06): Live Data's limit stated as Reply enforces it: one unfinished search per filter + set, not one per team; searches with different filters run side by side, and finishing the earlier + search (resume it, or delete it once its final counts are read) frees its filters. - 2.3.0 (2026-10-30): `message.send` in the fulfilment register says that a message composed as a template goes by the same command and that Reply fills it in, before anything goes or when it goes, and points to reply-api's *Templates* for the rest. diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index 90b879f..ef8142f 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -1,7 +1,7 @@ import {describe, it, expect} from 'vitest'; import type {Command} from 'commander'; import {sequence_command, contact_list_command, contact_command, inbox_command, account_command, schedule_command, - direct_send_command} from '../../operations/commands'; + direct_send_command, live_data_command} from '../../operations/commands'; const sub = (parent: Command, name: string): Command=>{ const found = parent.commands.find(c=>c.name() === name); @@ -21,7 +21,9 @@ describe('operations/commands', ()=>{ it('names the commands in Reply\'s words', ()=>{ expect(sequence_command.commands.map(c=>c.name())).toEqual( ['list', 'create', 'get', 'contacts', 'stats', 'add-contact', 'remove-contact', 'pause', 'start']); - expect(contact_list_command.commands.map(c=>c.name())).toEqual(['add-contact']); + expect(contact_list_command.commands.map(c=>c.name())).toEqual(['create', 'get', 'delete', 'contacts', 'add-contact']); + expect(live_data_command.commands.map(c=>c.name())).toEqual( + ['preview', 'start', 'get', 'list', 'pause', 'resume', 'delete', 'filter-values']); expect(contact_command.commands.map(c=>c.name())).toEqual(['find', 'get', 'update', 'delete', 'opt-out', 'send-email', 'linkedin-connect', 'linkedin-message', 'linkedin-inmail', 'linkedin-voice']); expect(inbox_command.commands.map(c=>c.name())).toEqual(['list', 'changes', 'get', 'reply', 'categories', 'categorize', 'mark-read', 'mark-unread']); diff --git a/src/__tests__/operations/contact-list.test.ts b/src/__tests__/operations/contact-list.test.ts index 83d5863..a850697 100644 --- a/src/__tests__/operations/contact-list.test.ts +++ b/src/__tests__/operations/contact-list.test.ts @@ -1,6 +1,9 @@ import {describe, it, expect, beforeEach} from 'vitest'; import {mock_fetch, json, ctx, sent, answer, capture} from './helpers'; -import {handle_contact_list_add_contact} from '../../operations/contact-list'; +import { + handle_contact_list_add_contact, handle_contact_list_create, handle_contact_list_get, handle_contact_list_delete, + handle_contact_list_contacts, +} from '../../operations/contact-list'; const run = (opts: Record)=>capture(()=>handle_contact_list_add_contact('77', opts, ctx(), {json: true})); @@ -40,3 +43,81 @@ describe('contact-list add-contact', ()=>{ }); }); }); + +describe('contact-list create', ()=>{ + const create = (opts: Record)=> + handle_contact_list_create({name: '-', ...opts}, ctx(), {json: true}, ()=>'{"name":"Audience 12"}'); + + it('makes a private list by default and answers created', async()=>{ + answer(json({id: 77, name: 'Audience 12', isShared: false}, 201)); + const {out} = await capture(()=>create({})); + expect(JSON.parse(out)).toEqual({status: 'created', list_id: 77, name: 'Audience 12', is_shared: false}); + expect(sent()[0]).toEqual({method: 'POST', url: 'https://api/v3/contact-lists', body: {name: 'Audience 12', isShared: false}}); + }); + + it('--shared asks for a shared list', async()=>{ + answer(json({id: 77, name: 'Audience 12', isShared: true}, 201)); + await capture(()=>create({shared: true})); + expect(sent()[0].body).toEqual({name: 'Audience 12', isShared: true}); + }); + + it('a name in use is contact-list.name_taken', async()=>{ + answer(json({code: 'contactsList.duplicateName'}, 409)); + await expect(create({})).rejects.toMatchObject({code: 'contact-list.name_taken', reply_code: 'contactsList.duplicateName', exit_code: 1}); + expect(mock_fetch).toHaveBeenCalledTimes(1); + }); +}); + +describe('contact-list get', ()=>{ + it('prints Reply\'s list as it is', async()=>{ + answer(json({id: 77, name: 'Audience 12', isShared: false})); + const {out} = await capture(()=>handle_contact_list_get('77', ctx(), {json: true})); + expect(JSON.parse(out)).toEqual({id: 77, name: 'Audience 12', isShared: false}); + expect(sent()[0]).toMatchObject({method: 'GET', url: 'https://api/v3/contact-lists/77'}); + }); + + it('a 404 is contact-list.not_found', async()=>{ + answer(json({code: 'contactsList.notFound'}, 404)); + await expect(handle_contact_list_get('77', ctx(), {})).rejects.toMatchObject({code: 'contact-list.not_found', exit_code: 1}); + }); +}); + +describe('contact-list delete', ()=>{ + it('answers deleted', async()=>{ + answer(json(null, 204)); + const {out} = await capture(()=>handle_contact_list_delete('77', ctx(), {json: true})); + expect(JSON.parse(out)).toEqual({status: 'deleted', list_id: 77}); + expect(sent()[0]).toMatchObject({method: 'DELETE', url: 'https://api/v3/contact-lists/77'}); + }); + + it('a 404 is contact-list.not_found', async()=>{ + answer(json({code: 'contactsList.notFound'}, 404)); + await expect(handle_contact_list_delete('77', ctx(), {})).rejects.toMatchObject({code: 'contact-list.not_found', ids: {list_id: 77}}); + }); +}); + +describe('contact-list contacts', ()=>{ + const ORDER = {listId: 77, sortBy: 'addedOn', sortDirection: 'asc'}; + + it('reads the list oldest first and passes Reply\'s contacts through', async()=>{ + const contact = {id: 5, email: 'ann@example.com', addingDate: '2026-11-06T10:00:01.20+00:00'}; + answer(json({items: [contact], hasMore: false})); + const {out} = await capture(()=>handle_contact_list_contacts('77', {limit: '1000', offset: '25'}, ctx(), {json: true})); + expect(JSON.parse(out)).toEqual({items: [contact], has_more: false}); + expect(sent()[0]).toEqual({method: 'POST', url: 'https://api/v3/contacts/filter?top=1000&skip=25', body: ORDER}); + }); + + it('--live-data-only adds the creation-source condition', async()=>{ + answer(json({items: [], hasMore: false})); + await capture(()=>handle_contact_list_contacts('77', {liveDataOnly: true}, ctx(), {json: true})); + expect(sent()[0]).toEqual({method: 'POST', url: 'https://api/v3/contacts/filter?top=100&skip=0', body: { + ...ORDER, conditions: [{field: 'creationSource', operator: 'equals', value: 'liveData'}], + }}); + }); + + it('an offset past the end is an empty last page', async()=>{ + answer(json({items: [], hasMore: false})); + const {out} = await capture(()=>handle_contact_list_contacts('77', {offset: '500'}, ctx(), {json: true})); + expect(JSON.parse(out)).toEqual({items: [], has_more: false}); + }); +}); diff --git a/src/__tests__/operations/live-data-preview.test.ts b/src/__tests__/operations/live-data-preview.test.ts new file mode 100644 index 0000000..89e59f6 --- /dev/null +++ b/src/__tests__/operations/live-data-preview.test.ts @@ -0,0 +1,98 @@ +import {describe, it, expect, beforeEach, afterEach} from 'vitest'; +import {mock_fetch, json, ctx, sent, answer, capture, instant_timers, real_timers} from './helpers'; +import {handle_live_data_preview} from '../../operations/live-data-preview'; + +const J = '3f2504e0-4f89-11d3-9a0c-0305e82c3301'; +const FILTERS = '{"jobTitles":[{"value":"CTO","type":"include"}]}'; +const job = (status: string, extra: Record = {})=>json({jobId: J, status, ...extra}); +const preview = (opts: Record)=>handle_live_data_preview(opts, ctx(), {json: true}); + +beforeEach(()=>{ + mock_fetch.mockReset(); + instant_timers(); +}); +afterEach(()=>{ real_timers(); }); + +describe('live-data preview', ()=>{ + it('starts, waits for the job and answers the counts and the samples in the CLI\'s names', async()=>{ + answer(json({jobId: J}, 202), job('Processing', {progress: 0.5}), job('Done', {jsonDataResult: JSON.stringify({ + ContactsCount: 1200, CompaniesCount: 300, SampleContacts: [{ + FirstName: 'Ann', LastName: 'Example', JobTitle: 'CTO', Location: 'Berlin', + LinkedInUrl: 'https://www.linkedin.com/in/ann-example', CompanyName: 'Example GmbH', CompanyDomain: 'example.com', + }], + })})); + const {out} = await capture(()=>preview({filters: FILTERS})); + expect(JSON.parse(out)).toEqual({status: 'done', job_id: J, contacts_count: 1200, companies_count: 300, sample_contacts: [{ + first_name: 'Ann', last_name: 'Example', job_title: 'CTO', location: 'Berlin', + linkedin_url: 'https://www.linkedin.com/in/ann-example', company_name: 'Example GmbH', company_domain: 'example.com', + }]}); + expect(sent()[0]).toEqual({method: 'POST', url: 'https://api/v3/live-data/searches/preview', body: {filters: JSON.parse(FILTERS)}}); + expect(sent()[1]).toMatchObject({method: 'GET', url: `https://api/v3/background-jobs/${J}`}); + }); + + it('answers pending with the job id when the wait runs out', async()=>{ + answer(json({jobId: J}, 202), job('Processing', {progress: 0.2}), job('Processing', {progress: 0.2}), job('Processing', {progress: 0.2})); + const {out} = await capture(()=>preview({filters: FILTERS, waitSeconds: '4'})); + expect(JSON.parse(out)).toEqual({status: 'pending', job_id: J, progress: 0.2}); + expect(mock_fetch).toHaveBeenCalledTimes(4); + }); + + it('--wait-seconds 0 reads the job once and answers pending', async()=>{ + answer(json({jobId: J}, 202), job('Scheduled')); + const {out} = await capture(()=>preview({filters: FILTERS, waitSeconds: '0', maxPerCompany: '2'})); + expect(JSON.parse(out)).toEqual({status: 'pending', job_id: J, progress: null}); + expect(mock_fetch).toHaveBeenCalledTimes(2); + expect(sent()[0].body).toEqual({filters: JSON.parse(FILTERS), maxPeoplePerCompany: 2}); + }); + + it('--job-id goes on waiting for a preview already started, without starting one', async()=>{ + answer(job('Done', {jsonDataResult: '{"ContactsCount":5,"CompaniesCount":2,"SampleContacts":[]}'})); + const {out} = await capture(()=>preview({jobId: J})); + expect(JSON.parse(out)).toMatchObject({status: 'done', contacts_count: 5}); + expect(sent().map(r=>r.url)).toEqual([`https://api/v3/background-jobs/${J}`]); + }); + + it('a job Reply does not know is live_data.preview_not_found', async()=>{ + answer(json({code: 'backgroundJob.notFound'}, 404)); + await expect(preview({jobId: J})).rejects.toMatchObject({code: 'live_data.preview_not_found', details: {job_id: J}, exit_code: 1}); + }); + + it('a job that settled Failed is live_data.preview_failed with Reply\'s status and the job id', async()=>{ + answer(json({jobId: J}, 202), job('Failed')); + await expect(preview({filters: FILTERS})).rejects.toMatchObject({ + code: 'live_data.preview_failed', details: {job_status: 'Failed', job_id: J}, exit_code: 1, + }); + }); + + it('counts Reply did not give are null', async()=>{ + answer(job('Done', {jsonDataResult: '{"SampleContacts":[]}'})); + const {out} = await capture(()=>preview({jobId: J})); + expect(JSON.parse(out)).toEqual({status: 'done', job_id: J, contacts_count: null, companies_count: null, sample_contacts: []}); + }); + + it('a Done job whose result is not JSON is reply.unavailable with the job id', async()=>{ + answer(job('Done', {jsonDataResult: 'not json'})); + await expect(preview({jobId: J})).rejects.toMatchObject({code: 'reply.unavailable', details: {job_id: J}, exit_code: 1}); + }); + + it('a poll refused for the scope is access.feature_unavailable with the job id', async()=>{ + answer(json({jobId: J}, 202), json({}, 403)); + await expect(preview({filters: FILTERS})).rejects.toMatchObject({code: 'access.feature_unavailable', details: {job_id: J}}); + }); + + it('a start answered without a job id is outcome.unknown', async()=>{ + answer(json({}, 202)); + await expect(preview({filters: FILTERS})).rejects.toMatchObject({code: 'outcome.unknown', exit_code: 3}); + }); + + it('a --job-id that is not a GUID is a usage error before any call', async()=>{ + await expect(preview({jobId: '123'})).rejects.toMatchObject({exit_code: 2}); + expect(mock_fetch).not.toHaveBeenCalled(); + }); + + it('takes exactly one of --filters and --job-id', async()=>{ + await expect(preview({filters: FILTERS, jobId: J})).rejects.toMatchObject({exit_code: 2}); + await expect(preview({})).rejects.toMatchObject({exit_code: 2}); + expect(mock_fetch).not.toHaveBeenCalled(); + }); +}); diff --git a/src/__tests__/operations/live-data.test.ts b/src/__tests__/operations/live-data.test.ts new file mode 100644 index 0000000..57180e5 --- /dev/null +++ b/src/__tests__/operations/live-data.test.ts @@ -0,0 +1,175 @@ +import {describe, it, expect, beforeEach} from 'vitest'; +import {mock_fetch, json, ctx, sent, answer, capture} from './helpers'; +import { + handle_live_data_get, handle_live_data_list, handle_live_data_start, handle_live_data_pause, handle_live_data_resume, handle_live_data_delete, + handle_live_data_filter_values, +} from '../../operations/live-data'; + +beforeEach(()=>{ mock_fetch.mockReset(); }); + +describe('live-data get', ()=>{ + it('prints Reply\'s search as it is', async()=>{ + const search = {id: 901, status: 'inProgress', contactsFound: 3, lists: [{id: 77, name: 'L'}], filters: {}}; + answer(json(search)); + const {out} = await capture(()=>handle_live_data_get('901', ctx(), {json: true})); + expect(JSON.parse(out)).toEqual(search); + expect(sent()[0]).toMatchObject({method: 'GET', url: 'https://api/v3/live-data/searches/901'}); + }); + + it('a 404 is live_data.not_found', async()=>{ + answer(json({code: 'liveDataSearch.notFound'}, 404)); + await expect(handle_live_data_get('901', ctx(), {})).rejects.toMatchObject({ + code: 'live_data.not_found', reply_code: 'liveDataSearch.notFound', exit_code: 1, + }); + }); +}); + +describe('live-data list', ()=>{ + it('prints one page newest first as Reply gives it', async()=>{ + answer(json({items: [{id: 2}, {id: 1}], hasMore: true})); + const {out} = await capture(()=>handle_live_data_list({limit: '50', offset: '100'}, ctx(), {json: true})); + expect(JSON.parse(out)).toEqual({items: [{id: 2}, {id: 1}], has_more: true}); + expect(sent()[0].url).toBe('https://api/v3/live-data/searches?top=50&skip=100'); + }); + + it('defaults to 100 from the start', async()=>{ + answer(json({items: [], hasMore: false})); + await capture(()=>handle_live_data_list({}, ctx(), {json: true})); + expect(sent()[0].url).toBe('https://api/v3/live-data/searches?top=100&skip=0'); + }); +}); + +describe('live-data start', ()=>{ + const FILTERS = '{"jobTitles":[{"value":"CTO","type":"include"}],"accountKeywords":{"values":[],"type":"or"}}'; + const start = (opts: Record)=>handle_live_data_start({filters: FILTERS, count: '25', ...opts}, ctx(), {json: true}); + + it('sends the filters untouched with the count, lists, people per company and phones, and answers started', async()=>{ + answer(json({searchId: 901})); + const {out} = await capture(()=>start({listId: ['77', '78'], maxPerCompany: '2', withPhones: true})); + expect(JSON.parse(out)).toEqual({status: 'started', search_id: 901}); + expect(sent()[0]).toEqual({method: 'POST', url: 'https://api/v3/live-data/searches', body: { + filters: JSON.parse(FILTERS), contactsCountToAdd: 25, listIds: [77, 78], maxPeoplePerCompany: 2, searchContactPhones: true, + }}); + }); + + it('leaves out what was not given', async()=>{ + answer(json({searchId: 901})); + await capture(()=>start({})); + expect(sent()[0].body).toEqual({filters: JSON.parse(FILTERS), contactsCountToAdd: 25}); + }); + + it('a 409 is live_data.search_in_progress with Reply\'s words', async()=>{ + answer(json({code: 'liveDataSearch.searchInProgress', detail: 'A live data search is already in progress.'}, 409)); + await expect(start({})).rejects.toMatchObject({ + code: 'live_data.search_in_progress', detail: 'A live data search is already in progress.', exit_code: 1, + }); + }); + + it('a 422 is live_data.insufficient_credits', async()=>{ + answer(json({code: 'liveDataSearch.insufficientCredits'}, 422)); + await expect(start({})).rejects.toMatchObject({code: 'live_data.insufficient_credits', exit_code: 1}); + }); + + it('a 400 invalidParameter is live_data.invalid_filters', async()=>{ + answer(json({code: 'liveDataSearch.invalidParameter', detail: 'Filters are invalid.'}, 400)); + await expect(start({})).rejects.toMatchObject({code: 'live_data.invalid_filters', detail: 'Filters are invalid.'}); + }); + + it('Reply\'s 502 upstreamFailure is live_data.service_failed, exit 1, not an unknown outcome', async()=>{ + answer(json({code: 'liveDataSearch.upstreamFailure'}, 502)); + await expect(start({})).rejects.toMatchObject({code: 'live_data.service_failed', exit_code: 1}); + }); + + it('a 502 without Reply\'s code is outcome.unknown', async()=>{ + answer(json('bad gateway', 502)); + await expect(start({})).rejects.toMatchObject({code: 'outcome.unknown', exit_code: 3}); + }); + + it('a 200 without a searchId is outcome.unknown', async()=>{ + answer(json({})); + await expect(start({})).rejects.toMatchObject({code: 'outcome.unknown', exit_code: 3}); + }); + + it('filters that are not a JSON object are usage.filters before any call', async()=>{ + await expect(start({filters: '[]'})).rejects.toMatchObject({code: 'usage.filters', exit_code: 2}); + expect(mock_fetch).not.toHaveBeenCalled(); + }); + + it('a missing or bad --count is a usage error before any call', async()=>{ + await expect(start({count: '0'})).rejects.toMatchObject({exit_code: 2}); + await expect(start({count: undefined})).rejects.toMatchObject({exit_code: 2}); + expect(mock_fetch).not.toHaveBeenCalled(); + }); +}); + +describe('live-data pause', ()=>{ + it('answers paused', async()=>{ + answer(json({id: 901, status: 'manuallyPaused'})); + const {out} = await capture(()=>handle_live_data_pause('901', ctx(), {json: true})); + expect(JSON.parse(out)).toEqual({status: 'paused', search_id: 901}); + expect(sent()[0]).toMatchObject({method: 'POST', url: 'https://api/v3/live-data/searches/901/pause'}); + }); + + it('a 409 passes Reply\'s words on as live_data.invalid_status', async()=>{ + const detail = 'The search is pausedDueToInsufficientCredits; pause applies to inProgress searches only.'; + answer(json({code: 'liveDataSearch.invalidStatus', detail}, 409)); + await expect(handle_live_data_pause('901', ctx(), {})).rejects.toMatchObject({ + code: 'live_data.invalid_status', detail, ids: {search_id: 901}, exit_code: 1, + }); + expect(mock_fetch).toHaveBeenCalledTimes(1); + }); +}); + +describe('live-data resume', ()=>{ + it('answers resumed, or finished when Reply finished it', async()=>{ + answer(json({id: 901, status: 'inProgress'}), json({id: 902, status: 'finished'})); + const resumed = await capture(()=>handle_live_data_resume('901', ctx(), {json: true})); + const finished = await capture(()=>handle_live_data_resume('902', ctx(), {json: true})); + expect(JSON.parse(resumed.out)).toEqual({status: 'resumed', search_id: 901}); + expect(JSON.parse(finished.out)).toEqual({status: 'finished', search_id: 902}); + expect(sent()[0]).toMatchObject({method: 'POST', url: 'https://api/v3/live-data/searches/901/resume'}); + }); + + it('a 422 is live_data.insufficient_credits or live_data.contact_limit_reached by Reply\'s code; Reply\'s 502 upstreamFailure is live_data.service_failed', async()=>{ + answer(json({code: 'liveDataSearch.insufficientCredits'}, 422), json({code: 'liveDataSearch.contactLimitReached'}, 422), + json({code: 'liveDataSearch.upstreamFailure'}, 502)); + await expect(handle_live_data_resume('901', ctx(), {})).rejects.toMatchObject({code: 'live_data.insufficient_credits', ids: {search_id: 901}}); + await expect(handle_live_data_resume('901', ctx(), {})).rejects.toMatchObject({code: 'live_data.contact_limit_reached', exit_code: 1}); + await expect(handle_live_data_resume('901', ctx(), {})).rejects.toMatchObject({code: 'live_data.service_failed', exit_code: 1}); + }); +}); + +describe('live-data delete', ()=>{ + it('answers deleted', async()=>{ + answer(json(null, 204)); + const {out} = await capture(()=>handle_live_data_delete('901', ctx(), {json: true})); + expect(JSON.parse(out)).toEqual({status: 'deleted', search_id: 901}); + expect(sent()[0]).toMatchObject({method: 'DELETE', url: 'https://api/v3/live-data/searches/901'}); + }); + + it('a 404 is live_data.not_found', async()=>{ + answer(json({code: 'liveDataSearch.notFound'}, 404)); + await expect(handle_live_data_delete('901', ctx(), {})).rejects.toMatchObject({code: 'live_data.not_found', ids: {search_id: 901}}); + }); + + it('a lost answer is outcome.unknown whose hint says a repeat answers live_data.not_found if it went through', async()=>{ + answer(json('bad gateway', 502)); + await expect(handle_live_data_delete('901', ctx(), {})).rejects.toMatchObject({ + code: 'outcome.unknown', exit_code: 3, ids: {search_id: 901}, hint: expect.stringContaining('live_data.not_found'), + }); + }); +}); + +describe('live-data filter-values', ()=>{ + it('reads one page of a kind with the search text', async()=>{ + answer(json({items: ['CTO'], hasMore: false})); + const {out} = await capture(()=>handle_live_data_filter_values('job-titles', {search: 'chief tech', limit: '20'}, ctx(), {json: true})); + expect(JSON.parse(out)).toEqual({items: ['CTO'], has_more: false}); + expect(sent()[0]).toMatchObject({method: 'GET', url: 'https://api/v3/live-data/filter-values/job-titles?search=chief%20tech&top=20&skip=0'}); + }); + + it('an unknown kind is usage.choice before any call', async()=>{ + await expect(handle_live_data_filter_values('titles', {}, ctx(), {})).rejects.toMatchObject({code: 'usage.choice', exit_code: 2}); + expect(mock_fetch).not.toHaveBeenCalled(); + }); +}); diff --git a/src/__tests__/operations/program.test.ts b/src/__tests__/operations/program.test.ts index 8006a89..c307b16 100644 --- a/src/__tests__/operations/program.test.ts +++ b/src/__tests__/operations/program.test.ts @@ -153,6 +153,15 @@ describe('the program', ()=>{ expect((mock_fetch.mock.calls[0] as [string, RequestInit])[1].headers).toMatchObject({'Idempotency-Key': 'send-456-1'}); }); + it('live-data start takes repeated --list-id and inline --filters', async()=>{ + answer(json({code: 'liveDataSearch.searchInProgress'}, 409)); + const {code} = await run_program(['--json', '-k', 'key-1', 'live-data', 'start', '--filters', '{"jobTitles":[]}', '--count', '5', + '--list-id', '77', '--list-id', '78']); + expect(code).toBe(1); + expect(requests()).toEqual([{method: 'POST', url: 'https://api.reply.io/v3/live-data/searches', + body: {filters: {jobTitles: []}, contactsCountToAdd: 5, listIds: [77, 78]}}]); + }); + it('a send for later at a moment without its offset exits 2 before any request', async()=>{ pipe_stdin(JSON.stringify({body: 'Thanks for connecting.'})); const {code, err} = await run_program([...LATER_SEND, '--send-after', '2026-11-03T14:00:00']); diff --git a/src/index.ts b/src/index.ts index 6598ea0..37e8c45 100644 --- a/src/index.ts +++ b/src/index.ts @@ -9,6 +9,7 @@ import {skills_command} from './commands/skills'; import {install_command} from './commands/install'; import { sequence_command, contact_list_command, contact_command, inbox_command, account_command, schedule_command, direct_send_command, + live_data_command, } from './operations/commands'; import {update_notice} from './selfupdate/notice'; import {CliError, format_hint} from './utils/errors'; @@ -49,7 +50,8 @@ const build_program = (): Command=>{ const WORK = 'Work with your Reply account:'; const SETUP = 'Setup:'; for (const c of [ - sequence_command, contact_list_command, contact_command, inbox_command, account_command, schedule_command, direct_send_command, api_command, + sequence_command, contact_list_command, live_data_command, contact_command, inbox_command, account_command, schedule_command, + direct_send_command, api_command, ]) { program.addCommand(c.helpGroup(WORK)); diff --git a/src/operations/commands.ts b/src/operations/commands.ts index 3c09c0a..fd7b602 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -11,13 +11,21 @@ import { handle_inbox_list, handle_inbox_changes, handle_inbox_get, handle_inbox_categories, handle_inbox_categorize, handle_inbox_mark_read, handle_inbox_mark_unread, } from './inbox'; import {handle_inbox_reply} from './inbox-reply'; -import {handle_contact_list_add_contact} from './contact-list'; +import { + handle_contact_list_add_contact, handle_contact_list_create, handle_contact_list_get, handle_contact_list_delete, + handle_contact_list_contacts, +} from './contact-list'; import {handle_contact_opt_out} from './contact'; import {handle_contact_find, handle_contact_get, handle_contact_update, handle_contact_delete} from './contact-record'; import {handle_direct_send, type Direct_send_name} from './direct-send'; import {handle_account_list} from './accounts'; import {handle_schedule_list} from './schedules'; import {handle_direct_send_get, handle_direct_send_cancel} from './direct-sends'; +import { + handle_live_data_get, handle_live_data_list, handle_live_data_start, handle_live_data_pause, handle_live_data_resume, handle_live_data_delete, + handle_live_data_filter_values, FILTER_VALUE_KINDS, +} from './live-data'; +import {handle_live_data_preview} from './live-data-preview'; const P = PROGRAM_NAME; const COMMON_ERRORS = [ @@ -178,7 +186,61 @@ sequence_command.command('start') await handle_sequence_start(cmd.args[0], cmd.opts(), ctx, g); })); -const contact_list_command = new Command('contact-list').description('Put contacts on a contact list'); +const contact_list_command = new Command('contact-list').description('Create, read or delete a contact list, read its contacts, put contacts on it'); + +contact_list_command.command('create') + .option('--name ', 'Only -: {name} as JSON on stdin') + .option('--shared', 'Share the list with the team (private unless given)') + .description('Make an empty contact list of this name') + .addHelpText('after', help([`echo '{"name":"Audience 12"}' | ${P} contact-list create --name -`], ['contact-list.name_taken'], true, + 'Result: {"status":"created","list_id","name","is_shared"}, name and is_shared as Reply answers them, each null when it\n' + + 'gives none. The name is read from stdin only, so it never sits in the argument list. contact-list.name_taken: the\n' + + 'account already has a list of that name; nothing is looked up, so pick another name.\n', + 'the list may have been made; running the command again then answers contact-list.name_taken')) + .action(run(async(cmd)=>{ + const {g, ctx} = ctx_of(cmd); + await handle_contact_list_create(cmd.opts(), ctx, g); + })); + +contact_list_command.command('get') + .argument('', 'Contact list id') + .description('The contact list as Reply holds it: name and whether it is shared') + .addHelpText('after', help([ex('contact-list get 77')], ['contact-list.not_found'], false, + 'Result: Reply\'s list as it gives it (id, name, isShared). Its contacts: `contact-list contacts`.\n')) + .action(run(async(cmd)=>{ + const {g, ctx} = ctx_of(cmd); + await handle_contact_list_get(cmd.args[0], ctx, g); + })); + +contact_list_command.command('delete') + .argument('', 'Contact list id') + .description('Delete a contact list; the contacts on it stay in the account') + .addHelpText('after', help([ex('contact-list delete 77')], ['contact-list.not_found'], true, + 'Result: {"status":"deleted","list_id"}. A shared list can be deleted only by the user who made it.\n' + + 'After exit 3 the list may already be gone: running the command again is safe, and then answers contact-list.not_found.\n')) + .action(run(async(cmd)=>{ + const {g, ctx} = ctx_of(cmd); + await handle_contact_list_delete(cmd.args[0], ctx, g); + })); + +contact_list_command.command('contacts') + .argument('', 'Contact list id') + .option('--live-data-only', 'Only contacts Live Data created') + .option('--limit ', 'Contacts per page, 1-1000 (default 100)') + .option('--offset ', 'Contacts to skip (default 0)') + .description('One page of the contacts on a list, oldest first') + .addHelpText('after', help([ex('contact-list contacts 77 --limit 1000'), ex('contact-list contacts 77 --live-data-only --offset 25')], [], false, + 'Result: {"items","has_more"}, Reply\'s contacts as it gives them (id, email, names, title, company, linkedInUrl,\n' + + 'addingDate, …). Oldest first: by the date the contact was added, equal dates by contact id, highest first; the order\n' + + 'holds from page to page. A Live Data search adds each batch at the end of that order, so for a list one search fills,\n' + + 'an offset kept by the caller (the number already read) only moves forward. A contact deleted in Reply, or taken off the\n' + + 'list, moves everyone behind it up by one. Only contacts the caller may see are returned: a team\'s rules can hide a\n' + + 'teammate\'s contacts, and Live Data\'s contacts belong to the user who started the search. Reply does not check the\n' + + 'list id here, so a list it does not have reads as empty; `contact-list get` tells the two apart.\n')) + .action(run(async(cmd)=>{ + const {g, ctx} = ctx_of(cmd); + await handle_contact_list_contacts(cmd.args[0], cmd.opts(), ctx, g); + })); add_contact_options(contact_list_command.command('add-contact') .argument('', 'Contact list id')) @@ -657,4 +719,152 @@ direct_send_command.command('cancel') await handle_direct_send_cancel(cmd.args[0], ctx, g); })); -export {sequence_command, contact_list_command, contact_command, inbox_command, account_command, schedule_command, direct_send_command}; +const live_data_command = new Command('live-data') + .description('Preview a Live Data audience, start a search that puts the people it finds on contact lists, follow, pause, resume or delete it'); + +const SEARCH_STATUSES = 'Statuses: inProgress, finished (the count asked for was reached), noMoreContacts (the source ran out first),\n' + + 'manuallyPaused, pausedDueToInsufficientCredits, pausedDueToContactLimit (the plan\'s contact limit).\n'; + +const FILTERS_HELP = '--filters is Reply\'s filter object as the API documents it (jobTitles, departments, seniorities, contactLocations,\n' + + 'industries, companyLocations, companySizes, accountKeywords, …), passed on untouched: inline JSON, @file, or - for\n' + + 'stdin. Reply checks the values, never against the filter-value lists: they are free text.\n'; + +const collect = (value: string, previous: string[]): string[]=>[...previous, value]; + +live_data_command.command('preview') + .option('--filters ', 'Reply\'s filters: inline JSON, @file, or - for stdin') + .option('--job-id ', 'Go on waiting for a preview already started, by the job id it answered') + .option('--max-per-company ', 'People per company (Reply\'s default: 1)') + .option('--wait-seconds ', 'How long to wait for the result, 0-600 (default 120; 0 answers at once)') + .description('Size an audience before spending on it: how many people and companies the filters match, and up to ten of them') + .addHelpText('after', help( + [`echo '{"jobTitles":[{"value":"CTO","type":"include"}]}' | ${P} live-data preview --filters -`, + ex('live-data preview --job-id 3f2504e0-4f89-11d3-9a0c-0305e82c3301 --wait-seconds 60')], + ['live_data.invalid_filters', 'live_data.search_in_progress', 'live_data.service_failed', 'live_data.preview_failed', + 'live_data.preview_not_found'], true, + 'Result: {"status":"done","job_id","contacts_count","companies_count","sample_contacts":[{"first_name","last_name",\n' + + '"job_title","location","linkedin_url","company_name","company_domain"}]}, each count null when Reply gives none; or\n' + + '{"status":"pending","job_id","progress"} when the wait ran out first (exit 0): run it again with --job-id to go on\n' + + 'waiting. Nothing is saved and nothing is charged. Reply works the preview out as a background job, read every two\n' + + 'seconds; reading it needs the key\'s other:read scope, without which the read is access.feature_unavailable. Every\n' + + 'failure after the start carries the job id in details.job_id. A newer preview by the same user replaces an older one,\n' + + 'whose job then never finishes. live_data.preview_failed: the job ended Failed, Cancelled, Expired or Unknown\n' + + '(details.job_status). live_data.preview_not_found: Reply has no such job for this user.\n' + FILTERS_HELP)) + .action(run(async(cmd)=>{ + const {g, ctx} = ctx_of(cmd); + await handle_live_data_preview(cmd.opts(), ctx, g); + })); + +live_data_command.command('start') + .option('--filters ', 'Reply\'s filters: inline JSON, @file, or - for stdin') + .option('--count ', 'The most people the search may add (an upper bound, not a promise)') + .option('--list-id ', 'A contact list the people found are put on (repeat for more)', collect, []) + .option('--max-per-company ', 'People per company (Reply\'s default: 1)') + .option('--with-phones', 'Also look for phone numbers (3 more credits for each one found)') + .description('Start a search that adds the people it finds as contacts and puts them on the lists named') + .addHelpText('after', help( + [`echo '{"jobTitles":[{"value":"CTO","type":"include"}],"companySizes":["fifty"]}' | ${P} live-data start --filters - --count 25 --list-id 77`], + ['live_data.invalid_filters', 'live_data.search_in_progress', 'live_data.insufficient_credits', 'live_data.service_failed'], true, + 'Result: {"status":"started","search_id"}. The search runs on at Reply: follow it with `live-data get`, and read the people\n' + + 'off its list with `contact-list contacts`. A person Reply already holds is skipped, not added to the list.\n' + + FILTERS_HELP + + 'live_data.search_in_progress: an unfinished search (running or paused) of the same team with the same filters, both\n' + + 'with or both without account lists, blocks a start; the lists, the count, people per company and phones do not count.\n' + + 'A deleted search no longer blocks. live_data.insufficient_credits: the team cannot afford a single contact; nothing\n' + + 'started. live_data.service_failed: Reply\'s search service failed and Reply saved no search; the call can be made again.\n' + + 'A key without the contact permissions gets access.feature_unavailable.\n', + 'a search may have started; `live-data list` shows the team\'s searches with their lists')) + .action(run(async(cmd)=>{ + const {g, ctx} = ctx_of(cmd); + await handle_live_data_start(cmd.opts(), ctx, g); + })); + +live_data_command.command('get') + .argument('', 'Live Data search id') + .description('One search as Reply holds it: status, contacts found, credits used, its lists and its filters') + .addHelpText('after', help([ex('live-data get 901')], ['live_data.not_found'], false, + 'Result: Reply\'s search as it gives it (id, status, startedAt, contactsFound, usedCredits, userId, sequenceId,\n' + + 'sequenceName, lists [{id, name}], filters). Never the people: read them off the search\'s list with\n' + + '`contact-list contacts`. ' + SEARCH_STATUSES + + 'A deleted search answers live_data.not_found, so read a search\'s final counts before deleting it.\n')) + .action(run(async(cmd)=>{ + const {g, ctx} = ctx_of(cmd); + await handle_live_data_get(cmd.args[0], ctx, g); + })); + +live_data_command.command('list') + .option('--limit ', 'Searches per page, 1-1000 (default 100)') + .option('--offset ', 'Searches to skip (default 0)') + .description('One page of the team\'s searches, newest first') + .addHelpText('after', help([ex('live-data list'), ex('live-data list --limit 20 --offset 20')], [], false, + 'Result: {"items","has_more"}, Reply\'s searches as it gives them (without their filters; `live-data get` has them).\n' + + 'Every search of the team is listed, whoever started it (userId); deleted ones are left out. ' + SEARCH_STATUSES)) + .action(run(async(cmd)=>{ + const {g, ctx} = ctx_of(cmd); + await handle_live_data_list(cmd.opts(), ctx, g); + })); + +live_data_command.command('pause') + .argument('', 'Live Data search id') + .description('Pause a running search; resume it later') + .addHelpText('after', help([ex('live-data pause 901')], ['live_data.not_found', 'live_data.invalid_status'], true, + 'Result: {"status":"paused","search_id"}. The search stops at its next step: the batch it is working on is still added,\n' + + 'so its counts can grow once more after the call. live_data.invalid_status: pause applies to inProgress searches only;\n' + + 'Reply\'s detail names the search\'s current status. A key without the contact permissions gets\n' + + 'access.feature_unavailable.\n')) + .action(run(async(cmd)=>{ + const {g, ctx} = ctx_of(cmd); + await handle_live_data_pause(cmd.args[0], ctx, g); + })); + +live_data_command.command('resume') + .argument('', 'Live Data search id') + .description('Resume a paused search, or finish one that has nothing left to find') + .addHelpText('after', help([ex('live-data resume 901')], + ['live_data.not_found', 'live_data.invalid_status', 'live_data.insufficient_credits', 'live_data.contact_limit_reached', + 'live_data.service_failed'], true, + 'Result: {"status":"resumed"|"finished","search_id"}: finished when the search had already found everything asked for.\n' + + 'Resume applies to manuallyPaused, pausedDueToInsufficientCredits and pausedDueToContactLimit; live_data.invalid_status\n' + + 'carries Reply\'s detail naming the current status. live_data.insufficient_credits: the team cannot afford a single\n' + + 'contact, and the search stays paused. live_data.contact_limit_reached: the search was paused by the plan\'s contact\n' + + 'limit and its owner still has no room for another contact; the search stays paused. live_data.service_failed:\n' + + 'Reply\'s search service failed and the search stays paused; the call can be made again.\n')) + .action(run(async(cmd)=>{ + const {g, ctx} = ctx_of(cmd); + await handle_live_data_resume(cmd.args[0], ctx, g); + })); + +live_data_command.command('delete') + .argument('', 'Live Data search id') + .description('Delete a search whatever its status; the contacts it added stay') + .addHelpText('after', help([ex('live-data delete 901')], ['live_data.not_found', 'live_data.service_failed'], true, + 'Result: {"status":"deleted","search_id"}. Read the search\'s final counts first: after a delete, `live-data get` answers\n' + + 'live_data.not_found. The search stops and its filters are free for a new search. The batch it was working on is either\n' + + 'still added, and charged, right after the delete, or kept for the next search with the same filters, which receives\n' + + 'those people first. live_data.service_failed: Reply\'s search service failed and the search is kept.\n' + + 'After exit 3 the search may already be gone: running the command again is safe, and then answers live_data.not_found.\n')) + .action(run(async(cmd)=>{ + const {g, ctx} = ctx_of(cmd); + await handle_live_data_delete(cmd.args[0], ctx, g); + })); + +live_data_command.command('filter-values') + .argument('', FILTER_VALUE_KINDS.join(' | ')) + .option('--search ', 'Only values containing this text, ignoring case') + .option('--limit ', 'Values per page, 1-1000 (default 100)') + .option('--offset ', 'Values to skip (default 0)') + .description('One page of the values Reply suggests for a filter: industries, departments, seniorities, locations or job titles') + .addHelpText('after', help([ex('live-data filter-values job-titles --search "chief tech"'), ex('live-data filter-values locations --search berlin')], + ['live_data.service_failed'], false, + 'Result: {"items","has_more"}, plain strings. They are suggestions only: Reply checks no filter value against these\n' + + 'lists, so a filter takes free text. locations mixes countries, regions and cities. seniorities go into the filters as\n' + + 'plain strings; the other kinds as {value, type}.\n')) + .action(run(async(cmd)=>{ + const {g, ctx} = ctx_of(cmd); + await handle_live_data_filter_values(cmd.args[0], cmd.opts(), ctx, g); + })); + +export { + sequence_command, contact_list_command, contact_command, inbox_command, account_command, schedule_command, direct_send_command, + live_data_command, +}; diff --git a/src/operations/contact-list.ts b/src/operations/contact-list.ts index dfea2fa..7a7d177 100644 --- a/src/operations/contact-list.ts +++ b/src/operations/contact-list.ts @@ -1,20 +1,25 @@ -import {Operation_error, type Ids} from '../utils/errors'; -import {call_reply, expect_object, item_failure, refusal, reply_code_of, open_session, type Op_session} from './call'; -import {parse_id, type Op_globals} from './options'; +import {Operation_error, Unknown_outcome_error, type Ids} from '../utils/errors'; +import { + call_reply, expect_object, is_reply_id, item_failure, read_page, refusal, reply_code_of, unreadable, open_session, type Answer, + type Op_session, +} from './call'; +import {parse_id, parse_int_in, type Op_globals} from './options'; import {read_contact_input, type Contact_flags} from './contact-input'; import {ensure_contact, read_opted_out} from './contacts'; +import {read_stdin_name} from './stdin-input'; import {print_result, with_ids} from './result'; import type {Cli_context} from '../context'; type List_add_opts = Contact_flags & {refuseOptedOut?: boolean}; +const list_not_found = (list_id: number, a: Answer): Operation_error=> + new Operation_error('contact-list.not_found', `This account has no contact list ${list_id}.`, {status: a.status, reply_code: reply_code_of(a)}); + const add_to_list = async(s: Op_session, list_id: number, contact_id: number): Promise=>{ const a = await call_reply(s, 'POST', `/v3/contact-lists/${list_id}/add-contacts`, 'write', {contactIds: [contact_id]}); if (a.status === 404) { - throw new Operation_error('contact-list.not_found', `This account has no contact list ${list_id}.`, { - status: 404, reply_code: reply_code_of(a), - }); + throw list_not_found(list_id, a); } if (a.status !== 200) { @@ -54,5 +59,97 @@ const handle_contact_list_add_contact = async( } }; -export {handle_contact_list_add_contact}; +// Reply refuses a second list of one name; the caller picks another name, nothing is looked up here. +const handle_contact_list_create = async( + opts: {name?: string; shared?: boolean}, ctx: Cli_context, g: Op_globals, read_stdin?: () => string, +): Promise=>{ + const name = read_stdin_name(opts.name, 'contact-list create', read_stdin); + const s = await open_session(ctx, g); + const a = await call_reply(s, 'POST', '/v3/contact-lists', 'write', {name, isShared: opts.shared === true}); + if (a.status === 409 && reply_code_of(a) === 'contactsList.duplicateName') + { + throw new Operation_error('contact-list.name_taken', 'This account already has a contact list of that name.', { + status: 409, reply_code: reply_code_of(a), + }); + } + if (a.status !== 201 && a.status !== 200) + { + throw refusal(a, 'write'); + } + const made = expect_object(a, 'write'); + if (!is_reply_id(made.id)) + { + throw unreadable(a, 'write'); + } + print_result({ + status: 'created', list_id: made.id, + name: typeof made.name === 'string' ? made.name : null, + is_shared: typeof made.isShared === 'boolean' ? made.isShared : null, + }, g); +}; + +const handle_contact_list_get = async(list_arg: string, ctx: Cli_context, g: Op_globals): Promise=>{ + const list_id = parse_id(list_arg, 'List id'); + const s = await open_session(ctx, g); + const a = await call_reply(s, 'GET', `/v3/contact-lists/${list_id}`, 'read'); + if (a.status === 404) + { + throw list_not_found(list_id, a); + } + if (a.status !== 200) + { + throw refusal(a, 'read'); + } + print_result(expect_object(a, 'read'), g); +}; + +const handle_contact_list_delete = async(list_arg: string, ctx: Cli_context, g: Op_globals): Promise=>{ + const list_id = parse_id(list_arg, 'List id'); + const s = await open_session(ctx, g); + try { + const a = await call_reply(s, 'DELETE', `/v3/contact-lists/${list_id}`, 'write'); + if (a.status === 404) + { + throw list_not_found(list_id, a); + } + if (a.status !== 204 && a.status !== 200) + { + throw refusal(a, 'write'); + } + print_result({status: 'deleted', list_id}, g); + } catch (e) { + if (e instanceof Unknown_outcome_error) + { + e.hint = 'The list may have been deleted. Running the command again is safe; it answers contact-list.not_found if it was.'; + } + throw with_ids(e, {list_id}); + } +}; + +// Oldest first. Reply sorts by date added, equal dates by contact id, highest first, so the order holds from page to +// page; for a list one search fills, each batch lands at its end. A POST that changes nothing: the filter is the body. +const handle_contact_list_contacts = async( + list_arg: string, opts: {liveDataOnly?: boolean; limit?: string; offset?: string}, ctx: Cli_context, g: Op_globals, +): Promise=>{ + const list_id = parse_id(list_arg, 'List id'); + const limit = parse_int_in(opts.limit, '--limit', 1, 1000, 100); + const offset = parse_int_in(opts.offset, '--offset', 0, 1000000, 0); + const filter: Record = {listId: list_id, sortBy: 'addedOn', sortDirection: 'asc'}; + if (opts.liveDataOnly === true) + { + filter.conditions = [{field: 'creationSource', operator: 'equals', value: 'liveData'}]; + } + const s = await open_session(ctx, g); + const a = await call_reply(s, 'POST', `/v3/contacts/filter?top=${limit}&skip=${offset}`, 'read', filter); + if (a.status !== 200) + { + throw refusal(a, 'read'); + } + const page = read_page(a); + print_result({items: page.items, has_more: page.has_more}, g); +}; + +export { + handle_contact_list_add_contact, handle_contact_list_create, handle_contact_list_get, handle_contact_list_delete, handle_contact_list_contacts, +}; export type {List_add_opts}; diff --git a/src/operations/live-data-preview.ts b/src/operations/live-data-preview.ts new file mode 100644 index 0000000..6de498a --- /dev/null +++ b/src/operations/live-data-preview.ts @@ -0,0 +1,142 @@ +import {Operation_error, UsageError} from '../utils/errors'; +import {call_reply, expect_object, is_object, refusal, reply_code_of, unreadable, open_session, type Answer, type Op_session} from './call'; +import {parse_int_in, LARGEST_REPLY_ID, type Op_globals} from './options'; +import {live_data_error, read_filters} from './live-data'; +import {print_result} from './result'; +import type {Cli_context} from '../context'; + +const POLL_MS = 2000; +const DEFAULT_WAIT_SECONDS = 120; +const MAX_WAIT_SECONDS = 600; +const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; +const FAILED = ['Failed', 'Cancelled', 'Expired', 'Unknown']; + +type Preview_opts = {filters?: string; jobId?: string; maxPerCompany?: string; waitSeconds?: string}; + +const sleep = (ms: number): Promise=>new Promise(resolve=>setTimeout(resolve, ms)); + +const number_or_null = (v: unknown): number | null=>(typeof v === 'number' ? v : null); +const string_or_null = (v: unknown): string | null=>(typeof v === 'string' ? v : null); + +// INTERIM (API gap): a preview job's result is a JSON string with PascalCase keys, not an object in v3's casing. +// Needed: jsonDataResult as an object, named as the rest of v3 names its fields. +// Workaround: parse the string and rename the fields a preview answers. +const preview_result = (job: Record, a: Answer): Record=>{ + let result: unknown; + try { + result = typeof job.jsonDataResult === 'string' ? JSON.parse(job.jsonDataResult) : undefined; + } catch { + result = undefined; + } + if (!is_object(result)) + { + throw unreadable(a, 'read'); + } + const samples = Array.isArray(result.SampleContacts) ? result.SampleContacts.filter(is_object) : []; + return { + contacts_count: number_or_null(result.ContactsCount), + companies_count: number_or_null(result.CompaniesCount), + sample_contacts: samples.map(c=>({ + first_name: string_or_null(c.FirstName), + last_name: string_or_null(c.LastName), + job_title: string_or_null(c.JobTitle), + location: string_or_null(c.Location), + linkedin_url: string_or_null(c.LinkedInUrl), + company_name: string_or_null(c.CompanyName), + company_domain: string_or_null(c.CompanyDomain), + })), + }; +}; + +const start_preview = async(s: Op_session, filters: Record, max_per_company: number | undefined): Promise=>{ + const body: Record = {filters}; + if (max_per_company !== undefined) + { + body.maxPeoplePerCompany = max_per_company; + } + const a = await call_reply(s, 'POST', '/v3/live-data/searches/preview', 'write', body); + if (a.status !== 202 && a.status !== 200) + { + throw live_data_error(a, 'write'); + } + const job_id = expect_object(a, 'write').jobId; + if (typeof job_id !== 'string' || !GUID.test(job_id)) + { + throw unreadable(a, 'write'); + } + return job_id; +}; + +const read_job = async(s: Op_session, job_id: string): Promise<{job: Record; a: Answer}>=>{ + const a = await call_reply(s, 'GET', `/v3/background-jobs/${job_id}`, 'read'); + if (a.status === 404) + { + throw new Operation_error('live_data.preview_not_found', 'Reply has no such preview job for this user.', { + status: 404, reply_code: reply_code_of(a), + }); + } + if (a.status !== 200) + { + throw refusal(a, 'read'); + } + const job = expect_object(a, 'read'); + if (typeof job.status !== 'string') + { + throw unreadable(a, 'read'); + } + return {job, a}; +}; + +// The wait is the sum of the pauses slept between reads, never the clock: the job is read at once, +// then again every POLL_MS while the next pause still fits in the wait. +const wait_for_job = async(s: Op_session, job_id: string, wait_ms: number, g: Op_globals): Promise=>{ + for (let slept = 0; ; slept += POLL_MS) + { + const {job, a} = await read_job(s, job_id); + if (job.status === 'Done') + { + print_result({status: 'done', job_id, ...preview_result(job, a)}, g); + return; + } + if (FAILED.includes(job.status as string)) + { + throw new Operation_error('live_data.preview_failed', 'The preview ended without a result.', { + status: 200, details: {job_status: job.status}, + }); + } + if (slept + POLL_MS > wait_ms) + { + print_result({status: 'pending', job_id, progress: number_or_null(job.progress)}, g); + return; + } + await sleep(POLL_MS); + } +}; + +const handle_live_data_preview = async(opts: Preview_opts, ctx: Cli_context, g: Op_globals, read_stdin?: () => string): Promise=>{ + if ((opts.filters === undefined) === (opts.jobId === undefined)) + { + throw new UsageError('Give exactly one of --filters and --job-id.', {code: 'usage.filters'}); + } + if (opts.jobId !== undefined && !GUID.test(opts.jobId)) + { + throw new UsageError('--job-id must be the job id a preview answered (a GUID).', {code: 'usage.id', hint: `Got: ${opts.jobId}`}); + } + const filters = opts.filters === undefined ? undefined : read_filters(opts.filters, read_stdin); + const max_per_company = opts.maxPerCompany === undefined + ? undefined : parse_int_in(opts.maxPerCompany, '--max-per-company', 1, LARGEST_REPLY_ID, 1); + const wait_ms = parse_int_in(opts.waitSeconds, '--wait-seconds', 0, MAX_WAIT_SECONDS, DEFAULT_WAIT_SECONDS) * 1000; + const s = await open_session(ctx, g); + const job_id = filters === undefined ? opts.jobId as string : await start_preview(s, filters, max_per_company); + try { + await wait_for_job(s, job_id, wait_ms, g); + } catch (e) { + if (e instanceof Operation_error) + { + e.details = {...e.details, job_id}; + } + throw e; + } +}; + +export {handle_live_data_preview}; diff --git a/src/operations/live-data.ts b/src/operations/live-data.ts new file mode 100644 index 0000000..82528f8 --- /dev/null +++ b/src/operations/live-data.ts @@ -0,0 +1,198 @@ +import {PROGRAM_NAME} from '../config'; +import {Operation_error, Unknown_outcome_error, UsageError} from '../utils/errors'; +import type {Call_kind} from '../utils/client'; +import {read_json_arg} from '../utils/json-arg'; +import { + call_reply, detail_of, expect_object, is_object, is_reply_id, read_page, refusal, reply_code_of, unreadable, open_session, + type Answer, +} from './call'; +import {parse_id, parse_int_in, parse_choice, LARGEST_REPLY_ID, type Op_globals} from './options'; +import {print_result, with_ids} from './result'; +import type {Cli_context} from '../context'; + +const LIVE_DATA_CODES: Record = { + 'liveDataSearch.searchInProgress': 'live_data.search_in_progress', + 'liveDataSearch.invalidStatus': 'live_data.invalid_status', + 'liveDataSearch.insufficientCredits': 'live_data.insufficient_credits', + 'liveDataSearch.contactLimitReached': 'live_data.contact_limit_reached', + 'liveDataSearch.invalidParameter': 'live_data.invalid_filters', +}; + +const LIVE_DATA_TITLES: Record = { + 'live_data.not_found': 'This team has no such Live Data search.', + 'live_data.search_in_progress': 'An unfinished search of this team with the same filters blocks the start.', + 'live_data.invalid_status': 'The search is not in a status this applies to.', + 'live_data.insufficient_credits': 'The team does not have the credits for a single contact.', + 'live_data.contact_limit_reached': 'The search owner\'s plan has no room for another contact.', + 'live_data.invalid_filters': 'Reply did not accept the filters.', + 'live_data.service_failed': 'Reply\'s search service failed; nothing changed, and the call can be made again.', +}; + +// Live Data's own refusals; any other answer reads as every operation reads it. Reply's 502 with its +// own upstreamFailure code is definite, even on a write: Reply saved nothing, or kept the search as it was. +const live_data_error = (a: Answer, kind: Call_kind, search_id?: number): Operation_error=>{ + const reply_code = reply_code_of(a); + const by_code = reply_code === undefined ? undefined : LIVE_DATA_CODES[reply_code]; + const code = a.status === 404 ? 'live_data.not_found' + : a.status === 502 && reply_code?.endsWith('.upstreamFailure') ? 'live_data.service_failed' + : by_code; + if (code === undefined) + { + return refusal(a, kind); + } + return new Operation_error(code, LIVE_DATA_TITLES[code], { + status: a.status, reply_code, detail: detail_of(a), ids: search_id === undefined ? undefined : {search_id}, + }); +}; + +const handle_live_data_get = async(id_arg: string, ctx: Cli_context, g: Op_globals): Promise=>{ + const id = parse_id(id_arg, 'Search id'); + const s = await open_session(ctx, g); + const a = await call_reply(s, 'GET', `/v3/live-data/searches/${id}`, 'read'); + if (a.status !== 200) + { + throw live_data_error(a, 'read', id); + } + print_result(expect_object(a, 'read'), g); +}; + +const handle_live_data_list = async(opts: {limit?: string; offset?: string}, ctx: Cli_context, g: Op_globals): Promise=>{ + const limit = parse_int_in(opts.limit, '--limit', 1, 1000, 100); + const offset = parse_int_in(opts.offset, '--offset', 0, 1000000, 0); + const s = await open_session(ctx, g); + const a = await call_reply(s, 'GET', `/v3/live-data/searches?top=${limit}&skip=${offset}`, 'read'); + if (a.status !== 200) + { + throw live_data_error(a, 'read'); + } + const page = read_page(a); + print_result({items: page.items, has_more: page.has_more}, g); +}; + +// Reply's own filter shape, passed on untouched: the CLI neither translates nor checks Reply's vocabulary. +const read_filters = (raw: string | undefined, read_stdin?: () => string): Record=>{ + if (raw === undefined) + { + throw new UsageError('No --filters was given.', {code: 'usage.filters', hint: 'Give the filters in Reply\'s shape: , @file or - for stdin.'}); + } + const value = read_json_arg(raw, {flag: '--filters', what: 'filters', code: 'usage.filters', read_stdin}); + if (!is_object(value)) + { + throw new UsageError('--filters must be a JSON object in Reply\'s filter shape.', {code: 'usage.filters'}); + } + return value; +}; + +type Start_opts = {filters?: string; count?: string; listId?: string[]; maxPerCompany?: string; withPhones?: boolean}; + +const handle_live_data_start = async(opts: Start_opts, ctx: Cli_context, g: Op_globals, read_stdin?: () => string): Promise=>{ + const filters = read_filters(opts.filters, read_stdin); + if (opts.count === undefined) + { + throw new UsageError('No --count was given.', {code: 'usage.range', hint: 'The most people the search may add, e.g. --count 25.'}); + } + const body: Record = {filters, contactsCountToAdd: parse_int_in(opts.count, '--count', 1, LARGEST_REPLY_ID, 0)}; + if (opts.listId !== undefined && opts.listId.length > 0) + { + body.listIds = opts.listId.map(id=>parse_id(id, '--list-id')); + } + if (opts.maxPerCompany !== undefined) + { + body.maxPeoplePerCompany = parse_int_in(opts.maxPerCompany, '--max-per-company', 1, LARGEST_REPLY_ID, 1); + } + if (opts.withPhones === true) + { + body.searchContactPhones = true; + } + const s = await open_session(ctx, g); + try { + const a = await call_reply(s, 'POST', '/v3/live-data/searches', 'write', body); + if (a.status !== 200 && a.status !== 201) + { + throw live_data_error(a, 'write'); + } + const started = expect_object(a, 'write'); + if (!is_reply_id(started.searchId)) + { + throw unreadable(a, 'write'); + } + print_result({status: 'started', search_id: started.searchId}, g); + } catch (e) { + if (e instanceof Unknown_outcome_error) + { + e.hint = `The search may have started. \`${PROGRAM_NAME} live-data list\` shows the team's searches with their lists.`; + } + throw e; + } +}; + +// One act on one search. Whatever it fails with names the search; a lost answer gets the hint given. +const act_on_search = async( + id_arg: string, method: 'POST' | 'DELETE', suffix: string, ctx: Cli_context, g: Op_globals, + answered: (a: Answer) => T, unknown_hint?: string, +): Promise<{id: number; result: T}>=>{ + const id = parse_id(id_arg, 'Search id'); + const s = await open_session(ctx, g); + try { + const a = await call_reply(s, method, `/v3/live-data/searches/${id}${suffix}`, 'write'); + if (a.status !== 200 && a.status !== 204) + { + throw live_data_error(a, 'write', id); + } + return {id, result: answered(a)}; + } catch (e) { + if (e instanceof Unknown_outcome_error && unknown_hint !== undefined) + { + e.hint = unknown_hint; + } + throw with_ids(e, {search_id: id}); + } +}; + +const handle_live_data_pause = async(id_arg: string, ctx: Cli_context, g: Op_globals): Promise=>{ + const {id} = await act_on_search(id_arg, 'POST', '/pause', ctx, g, ()=>undefined); + print_result({status: 'paused', search_id: id}, g); +}; + +// Reply answers the search as it now holds it: running again, or finished when nothing was left to find. +const handle_live_data_resume = async(id_arg: string, ctx: Cli_context, g: Op_globals): Promise=>{ + const {id, result} = await act_on_search(id_arg, 'POST', '/resume', ctx, g, a=>{ + const status = expect_object(a, 'write').status; + if (typeof status !== 'string') + { + throw unreadable(a, 'write'); + } + return status; + }); + print_result({status: result === 'finished' ? 'finished' : 'resumed', search_id: id}, g); +}; + +const handle_live_data_delete = async(id_arg: string, ctx: Cli_context, g: Op_globals): Promise=>{ + const {id} = await act_on_search(id_arg, 'DELETE', '', ctx, g, ()=>undefined, + 'The search may have been deleted. Running the command again is safe; it answers live_data.not_found if it was.'); + print_result({status: 'deleted', search_id: id}, g); +}; + +const FILTER_VALUE_KINDS = ['industries', 'departments', 'seniorities', 'locations', 'job-titles'] as const; + +const handle_live_data_filter_values = async( + kind_arg: string, opts: {search?: string; limit?: string; offset?: string}, ctx: Cli_context, g: Op_globals, +): Promise=>{ + const kind = parse_choice(kind_arg, 'The kind', FILTER_VALUE_KINDS) as string; + const limit = parse_int_in(opts.limit, '--limit', 1, 1000, 100); + const offset = parse_int_in(opts.offset, '--offset', 0, 1000000, 0); + const search = opts.search === undefined ? '' : `search=${encodeURIComponent(opts.search)}&`; + const s = await open_session(ctx, g); + const a = await call_reply(s, 'GET', `/v3/live-data/filter-values/${kind}?${search}top=${limit}&skip=${offset}`, 'read'); + if (a.status !== 200) + { + throw live_data_error(a, 'read'); + } + const page = read_page(a); + print_result({items: page.items, has_more: page.has_more}, g); +}; + +export { + live_data_error, read_filters, handle_live_data_get, handle_live_data_list, handle_live_data_start, + handle_live_data_pause, handle_live_data_resume, handle_live_data_delete, handle_live_data_filter_values, FILTER_VALUE_KINDS, +}; diff --git a/src/operations/sequence-by-name.ts b/src/operations/sequence-by-name.ts index 5f9925e..2622d31 100644 --- a/src/operations/sequence-by-name.ts +++ b/src/operations/sequence-by-name.ts @@ -1,8 +1,8 @@ import {PROGRAM_NAME} from '../config'; -import {Operation_error, Unknown_outcome_error, UsageError} from '../utils/errors'; +import {Operation_error, Unknown_outcome_error} from '../utils/errors'; import {call_reply, expect_object, read_page, is_object, is_reply_id, refusal, unreadable, open_session} from './call'; import type {Op_globals} from './options'; -import {read_stdin_object} from './stdin-input'; +import {read_stdin_name} from './stdin-input'; import {print_result} from './result'; import type {Cli_context} from '../context'; @@ -19,19 +19,6 @@ const PLACEHOLDER = { description: 'Added because a sequence needs one step to exist; replace it before this sequence is ever started.', }; -// A sequence's name is a person's text: read from stdin only, sent as given, never repeated in a message. -const read_name = (source: string | undefined, command: string, read_stdin?: () => string): string=>{ - const raw = read_stdin_object(source, { - flag: '--name', what: 'name', fields: ['name'], code: 'usage.name', - hint: `Pipe it in: echo '{"name":"…"}' | ${PROGRAM_NAME} sequence ${command} --name -`, - }, read_stdin); - if (typeof raw.name !== 'string' || raw.name.trim() === '') - { - throw new UsageError('The name must be a string that is not blank.', {code: 'usage.name'}); - } - return raw.name; -}; - const words_of = (seq: Record)=>({ status: typeof seq.status === 'string' ? seq.status : null, is_archived: typeof seq.isArchived === 'boolean' ? seq.isArchived : null, @@ -45,7 +32,7 @@ const words_of = (seq: Record)=>({ const handle_sequence_list = async( opts: {name?: string}, ctx: Cli_context, g: Op_globals, read_stdin?: () => string, ): Promise=>{ - const name = read_name(opts.name, 'list', read_stdin); + const name = read_stdin_name(opts.name, 'sequence list', read_stdin); const wanted = name.toLowerCase(); const s = await open_session(ctx, g); const items: Record[] = []; @@ -88,7 +75,7 @@ const handle_sequence_list = async( const handle_sequence_create = async( opts: {name?: string}, ctx: Cli_context, g: Op_globals, read_stdin?: () => string, ): Promise=>{ - const name = read_name(opts.name, 'create', read_stdin); + const name = read_stdin_name(opts.name, 'sequence create', read_stdin); const s = await open_session(ctx, g); try { const a = await call_reply(s, 'POST', '/v3/sequences', 'write', {name, steps: [PLACEHOLDER]}); diff --git a/src/operations/stdin-input.ts b/src/operations/stdin-input.ts index 55a6fba..96092a0 100644 --- a/src/operations/stdin-input.ts +++ b/src/operations/stdin-input.ts @@ -1,3 +1,4 @@ +import {PROGRAM_NAME} from '../config'; import {UsageError} from '../utils/errors'; import {read_all_stdin} from '../utils/json-arg'; import {is_object} from './call'; @@ -80,5 +81,18 @@ const stdin_inputs = ( return Object.fromEntries(names.map(n=>[n, sources[n] === '-' ? ()=>JSON.stringify(input[n]) : read])) as Record string>; }; -export {read_stdin_object, stdin_inputs}; +// A name a person gave (a sequence's, a list's) is read from stdin only, sent as given, never repeated in a message. +const read_stdin_name = (source: string | undefined, command: string, read_stdin?: () => string): string=>{ + const raw = read_stdin_object(source, { + flag: '--name', what: 'name', fields: ['name'], code: 'usage.name', + hint: `Pipe it in: echo '{"name":"…"}' | ${PROGRAM_NAME} ${command} --name -`, + }, read_stdin); + if (typeof raw.name !== 'string' || raw.name.trim() === '') + { + throw new UsageError('The name must be a string that is not blank.', {code: 'usage.name'}); + } + return raw.name; +}; + +export {read_stdin_object, stdin_inputs, read_stdin_name}; export type {Stdin_object_opts}; From e0c5d33c2c08fd2563deffde14ed7c84f353cbe2 Mon Sep 17 00:00:00 2001 From: vigubikReply Date: Mon, 9 Nov 2026 14:08:50 -0500 Subject: [PATCH 2/4] fix(live-data): read refusals at their status, and resume and preview 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. --- README.md | 8 +- .../reply-operations-mapping/SKILL.md | 23 +++-- src/__tests__/operations/contact-list.test.ts | 23 ++++- src/__tests__/operations/helpers.ts | 6 +- .../operations/live-data-preview.test.ts | 40 +++++++- src/__tests__/operations/live-data.test.ts | 56 ++++++++--- src/operations/commands.ts | 15 ++- src/operations/contact-list.ts | 41 +++++--- src/operations/live-data-preview.ts | 93 ++++++++++++------- src/operations/live-data.ts | 48 ++++++---- src/utils/client.ts | 2 +- 11 files changed, 253 insertions(+), 102 deletions(-) diff --git a/README.md b/README.md index b26c5aa..cc7a782 100644 --- a/README.md +++ b/README.md @@ -199,7 +199,7 @@ prints JSON (indented; compact with `--json`) and says what happened in a stable | `reply contact-list create --name - [--shared]` | make an empty list of a name → `created` | | `reply contact-list get ` · `reply contact-list delete ` | the list as Reply holds it · → `deleted` | | `reply contact-list contacts [--live-data-only] [--limit] [--offset]` | one page of the people on a list, oldest first | -| `reply live-data preview (--filters … \| --job-id …) [--wait-seconds N]` | how many people and companies the filters match, and up to ten of them → `done` / `pending` | +| `reply live-data preview (--filters … [--max-per-company N] \| --job-id …) [--wait-seconds N]` | how many people and companies the filters match, and up to ten of them → `done` / `pending` | | `reply live-data start --filters … --count N [--list-id N]… [--max-per-company N] [--with-phones]` | a search that adds the people it finds and puts them on the lists → `started` | | `reply live-data get ` · `reply live-data list` | a search's status and counts · the team's searches, newest first | | `reply live-data pause ` · `resume ` · `delete ` | → `paused` · `resumed` / `finished` · `deleted` | @@ -485,11 +485,13 @@ the same filters, running or paused; the lists, the count, people per company an and searches with different filters run side by side. That refusal holds only while the first search is unfinished: one that already finished or was deleted no longer blocks, so after exit 3 a second `live-data start` may start, and charge for, a second search. Look in `live-data list` first, where a -search shows its lists. `pause` applies to a running +search shows its lists. A `--list-id` the account does not have or cannot reach is `contact-list.not_found`, +and nothing starts. `pause` applies to a running search, `resume` to a paused one (`live_data.invalid_status` otherwise, Reply's detail naming the status), and a resume without the credits for one contact is `live_data.insufficient_credits`. A search paused by the plan's contact limit stays paused while its owner has no room for another -contact: that resume is `live_data.contact_limit_reached`. +contact: that resume is `live_data.contact_limit_reached`. A resume answers `finished`, with Reply's `search_status`, +when the search already had everything it was asked for. `live_data.service_failed` is Reply's search service failing: nothing changed, and the call can be made again. Read a search's final counts before `live-data delete`: a deleted search answers `live_data.not_found`. The contacts it added stay. diff --git a/skills/reply-adapter/reply-operations-mapping/SKILL.md b/skills/reply-adapter/reply-operations-mapping/SKILL.md index e7a2cd2..d0961da 100644 --- a/skills/reply-adapter/reply-operations-mapping/SKILL.md +++ b/skills/reply-adapter/reply-operations-mapping/SKILL.md @@ -265,16 +265,19 @@ them wrong: the same team has the same filters, running or paused; searches with different filters run side by side, and the target lists don't count. This is a Reply fact and it belongs nowhere else. An agent that does not know it will read the refusal as a failure and retry it. Before running the - same filters again, finish the earlier search: resume it, or delete it once its final counts - are read. + same filters again, let the earlier search finish, or delete it once its final counts are read; + a resumed search is unfinished again and still holds its filters. Build the filter from the typeahead values — departments, industries, job titles, locations, seniorities — rather than guessing accepted ones. Check the existing searches before starting a -near-identical one: a repeat spends again and returns a different world. Whatever comes back then -enters the normal path — `contact.create` or `import.apply` into a named list, with the same -mapping, dedupe policy and approval gate as any other import. Start can optionally drop the found -people straight into a sequence; treat that as `campaign.enroll` and hold it to the enrolment -gate rather than letting it ride along. +near-identical one: a repeat spends again and returns a different world. A start adds the people it +finds as contacts and puts them on the lists it names itself, so nothing it finds goes through +`contact.create` or `import.apply`: hold the start to the approval gate of an import before it +runs, and read the people back off its list. Start can optionally drop the found people straight +into a sequence; treat that as `campaign.enroll` and hold it to the enrolment gate rather than +letting it ride along. With reply-cli these are `reply live-data preview`, `start`, `get`, `list`, +`pause`, `resume`, `delete` and `filter-values`, and `reply contact-list contacts` reads a list's +people back. **Contact enrichment is documented as available late August 2026 and is not callable today.** `contact.enrich`, `company.enrich` and `phone_number.verify` are `absent` for that reason. Say @@ -428,8 +431,10 @@ those as irreversible with no window and say so before acting rather than after. ## Changelog - 2.3.1 (2026-11-06): Live Data's limit stated as Reply enforces it: one unfinished search per filter - set, not one per team; searches with different filters run side by side, and finishing the earlier - search (resume it, or delete it once its final counts are read) frees its filters. + set, not one per team; searches with different filters run side by side, and only an earlier + search that finished or was deleted frees its filters. A start puts the people it finds on its + lists itself, so nothing goes through `contact.create` or `import.apply`; the reply-cli commands + are named. - 2.3.0 (2026-10-30): `message.send` in the fulfilment register says that a message composed as a template goes by the same command and that Reply fills it in, before anything goes or when it goes, and points to reply-api's *Templates* for the rest. diff --git a/src/__tests__/operations/contact-list.test.ts b/src/__tests__/operations/contact-list.test.ts index a850697..5955ba0 100644 --- a/src/__tests__/operations/contact-list.test.ts +++ b/src/__tests__/operations/contact-list.test.ts @@ -1,5 +1,5 @@ import {describe, it, expect, beforeEach} from 'vitest'; -import {mock_fetch, json, ctx, sent, answer, capture} from './helpers'; +import {mock_fetch, json, ctx, sent, answer, capture, lost_connection} from './helpers'; import { handle_contact_list_add_contact, handle_contact_list_create, handle_contact_list_get, handle_contact_list_delete, handle_contact_list_contacts, @@ -66,6 +66,27 @@ describe('contact-list create', ()=>{ await expect(create({})).rejects.toMatchObject({code: 'contact-list.name_taken', reply_code: 'contactsList.duplicateName', exit_code: 1}); expect(mock_fetch).toHaveBeenCalledTimes(1); }); + + it('a 5xx or a lost answer is outcome.unknown whose hint finds the list by its name, without repeating the name', async()=>{ + for (const outcome of [()=>json('', 503), 'lost'] as const) + { + mock_fetch.mockReset(); + if (outcome === 'lost') + { + mock_fetch.mockRejectedValueOnce(lost_connection()); + } + else + { + answer(outcome()); + } + const e = await create({}).catch(x=>x); + expect(e, String(outcome)).toMatchObject({code: 'outcome.unknown', exit_code: 3}); + expect(e.hint, String(outcome)).toContain('contact-list.name_taken'); + expect(e.hint, String(outcome)).toContain('/v3/contact-lists?search='); + expect(e.hint, String(outcome)).not.toContain('Audience 12'); + expect(mock_fetch, String(outcome)).toHaveBeenCalledTimes(1); + } + }); }); describe('contact-list get', ()=>{ diff --git a/src/__tests__/operations/helpers.ts b/src/__tests__/operations/helpers.ts index bbdaf8d..a09da8d 100644 --- a/src/__tests__/operations/helpers.ts +++ b/src/__tests__/operations/helpers.ts @@ -55,4 +55,8 @@ const real_timers = (): void=>{ vi.stubGlobal('setTimeout', real_set_timeout); }; -export {mock_fetch, json, ctx, sent, answer, capture, instant_timers, real_timers}; +// A send whose answer never came back: the connection dropped after the request went out. +const lost_connection = ()=>Object.assign(new TypeError('fetch failed'), + {cause: Object.assign(new Error('ECONNRESET'), {code: 'ECONNRESET'})}); + +export {mock_fetch, json, ctx, sent, answer, capture, instant_timers, real_timers, lost_connection}; diff --git a/src/__tests__/operations/live-data-preview.test.ts b/src/__tests__/operations/live-data-preview.test.ts index 89e59f6..eb9f493 100644 --- a/src/__tests__/operations/live-data-preview.test.ts +++ b/src/__tests__/operations/live-data-preview.test.ts @@ -1,5 +1,5 @@ import {describe, it, expect, beforeEach, afterEach} from 'vitest'; -import {mock_fetch, json, ctx, sent, answer, capture, instant_timers, real_timers} from './helpers'; +import {mock_fetch, json, ctx, sent, answer, capture, instant_timers, real_timers, lost_connection} from './helpers'; import {handle_live_data_preview} from '../../operations/live-data-preview'; const J = '3f2504e0-4f89-11d3-9a0c-0305e82c3301'; @@ -64,6 +64,21 @@ describe('live-data preview', ()=>{ }); }); + it('a result given as an object in v3\'s casing, under a status in another case, reads the same', async()=>{ + answer(job('done', {jsonDataResult: {contactsCount: 5, companiesCount: 2, sampleContacts: [{firstName: 'Ann', companyDomain: 'example.com'}]}})); + const {out} = await capture(()=>preview({jobId: J})); + expect(JSON.parse(out)).toEqual({status: 'done', job_id: J, contacts_count: 5, companies_count: 2, sample_contacts: [{ + first_name: 'Ann', last_name: null, job_title: null, location: null, linkedin_url: null, company_name: null, + company_domain: 'example.com', + }]}); + }); + + it('a status v3 does not name is reply.unavailable with the job id, read once, not a pending after the whole wait', async()=>{ + answer(job('Paused')); + await expect(preview({jobId: J})).rejects.toMatchObject({code: 'reply.unavailable', details: {job_id: J}, exit_code: 1}); + expect(mock_fetch).toHaveBeenCalledTimes(1); + }); + it('counts Reply did not give are null', async()=>{ answer(job('Done', {jsonDataResult: '{"SampleContacts":[]}'})); const {out} = await capture(()=>preview({jobId: J})); @@ -80,9 +95,23 @@ describe('live-data preview', ()=>{ await expect(preview({filters: FILTERS})).rejects.toMatchObject({code: 'access.feature_unavailable', details: {job_id: J}}); }); - it('a start answered without a job id is outcome.unknown', async()=>{ - answer(json({}, 202)); - await expect(preview({filters: FILTERS})).rejects.toMatchObject({code: 'outcome.unknown', exit_code: 3}); + it('a start answered without a job id, or lost, is outcome.unknown whose hint says a repeat is safe', async()=>{ + for (const outcome of [()=>json({}, 202), 'lost'] as const) + { + mock_fetch.mockReset(); + if (outcome === 'lost') + { + mock_fetch.mockRejectedValueOnce(lost_connection()); + } + else + { + answer(outcome()); + } + const e = await preview({filters: FILTERS}).catch(x=>x); + expect(e, String(outcome)).toMatchObject({code: 'outcome.unknown', exit_code: 3}); + expect(e.hint, String(outcome)).toContain('again is safe'); + expect(mock_fetch, String(outcome)).toHaveBeenCalledTimes(1); + } }); it('a --job-id that is not a GUID is a usage error before any call', async()=>{ @@ -90,9 +119,10 @@ describe('live-data preview', ()=>{ expect(mock_fetch).not.toHaveBeenCalled(); }); - it('takes exactly one of --filters and --job-id', async()=>{ + it('takes exactly one of --filters and --job-id, and --max-per-company only with --filters', async()=>{ await expect(preview({filters: FILTERS, jobId: J})).rejects.toMatchObject({exit_code: 2}); await expect(preview({})).rejects.toMatchObject({exit_code: 2}); + await expect(preview({jobId: J, maxPerCompany: '2'})).rejects.toMatchObject({exit_code: 2}); expect(mock_fetch).not.toHaveBeenCalled(); }); }); diff --git a/src/__tests__/operations/live-data.test.ts b/src/__tests__/operations/live-data.test.ts index 57180e5..0eb354c 100644 --- a/src/__tests__/operations/live-data.test.ts +++ b/src/__tests__/operations/live-data.test.ts @@ -1,5 +1,5 @@ import {describe, it, expect, beforeEach} from 'vitest'; -import {mock_fetch, json, ctx, sent, answer, capture} from './helpers'; +import {mock_fetch, json, ctx, sent, answer, capture, lost_connection} from './helpers'; import { handle_live_data_get, handle_live_data_list, handle_live_data_start, handle_live_data_pause, handle_live_data_resume, handle_live_data_delete, handle_live_data_filter_values, @@ -37,6 +37,11 @@ describe('live-data list', ()=>{ await capture(()=>handle_live_data_list({}, ctx(), {json: true})); expect(sent()[0].url).toBe('https://api/v3/live-data/searches?top=100&skip=0'); }); + + it('a 404 names no search, so it is Reply\'s refusal and not live_data.not_found', async()=>{ + answer(json({code: 'liveDataSearch.notFound'}, 404)); + await expect(handle_live_data_list({}, ctx(), {})).rejects.toMatchObject({code: 'reply.refused', status: 404}); + }); }); describe('live-data start', ()=>{ @@ -75,19 +80,39 @@ describe('live-data start', ()=>{ await expect(start({})).rejects.toMatchObject({code: 'live_data.invalid_filters', detail: 'Filters are invalid.'}); }); - it('Reply\'s 502 upstreamFailure is live_data.service_failed, exit 1, not an unknown outcome', async()=>{ - answer(json({code: 'liveDataSearch.upstreamFailure'}, 502)); + it('Reply\'s 502 upstreamFailure is live_data.service_failed, exit 1, not an unknown outcome; a Live Data code at a ' + + 'status Reply does not answer it with is read by its status', async()=>{ + answer(json({code: 'liveDataSearch.upstreamFailure'}, 502), json({code: 'liveDataSearch.searchInProgress'}, 500)); await expect(start({})).rejects.toMatchObject({code: 'live_data.service_failed', exit_code: 1}); + await expect(start({})).rejects.toMatchObject({code: 'outcome.unknown', exit_code: 3}); }); - it('a 502 without Reply\'s code is outcome.unknown', async()=>{ - answer(json('bad gateway', 502)); - await expect(start({})).rejects.toMatchObject({code: 'outcome.unknown', exit_code: 3}); + it('a 404 is contact-list.not_found with Reply\'s detail naming the list, not a search that does not exist', async()=>{ + answer(json({code: 'liveDataSearch.notFound', detail: 'List(s) not found or not accessible: 78.'}, 404)); + await expect(start({listId: ['77', '78']})).rejects.toMatchObject({ + code: 'contact-list.not_found', detail: 'List(s) not found or not accessible: 78.', exit_code: 1, + }); }); - it('a 200 without a searchId is outcome.unknown', async()=>{ - answer(json({})); - await expect(start({})).rejects.toMatchObject({code: 'outcome.unknown', exit_code: 3}); + it('a 5xx without Reply\'s code, a lost answer, or a 2xx without a searchId is outcome.unknown (exit 3), posted once, and the ' + + 'hint sends the reader to live-data list instead of saying a repeat is safe', async()=>{ + for (const outcome of [()=>json('bad gateway', 502), ()=>json({}), 'lost'] as const) + { + mock_fetch.mockReset(); + if (outcome === 'lost') + { + mock_fetch.mockRejectedValueOnce(lost_connection()); + } + else + { + answer(outcome()); + } + const e = await start({}).catch(x=>x); + expect(e, String(outcome)).toMatchObject({code: 'outcome.unknown', exit_code: 3}); + expect(e.hint, String(outcome)).toContain('live-data list'); + expect(e.hint, String(outcome)).not.toContain('safe to re-run'); + expect(mock_fetch, String(outcome)).toHaveBeenCalledTimes(1); + } }); it('filters that are not a JSON object are usage.filters before any call', async()=>{ @@ -121,12 +146,19 @@ describe('live-data pause', ()=>{ }); describe('live-data resume', ()=>{ - it('answers resumed, or finished when Reply finished it', async()=>{ - answer(json({id: 901, status: 'inProgress'}), json({id: 902, status: 'finished'})); + it('answers resumed for a running search, finished with Reply\'s status for an ended one, and any other status is ' + + 'outcome.unknown', async()=>{ + answer(json({id: 901, status: 'inProgress'}), json({id: 902, status: 'finished'}), json({id: 903, status: 'noMoreContacts'}), + json({id: 904, status: 'manuallyPaused'})); const resumed = await capture(()=>handle_live_data_resume('901', ctx(), {json: true})); const finished = await capture(()=>handle_live_data_resume('902', ctx(), {json: true})); + const ran_out = await capture(()=>handle_live_data_resume('903', ctx(), {json: true})); expect(JSON.parse(resumed.out)).toEqual({status: 'resumed', search_id: 901}); - expect(JSON.parse(finished.out)).toEqual({status: 'finished', search_id: 902}); + expect(JSON.parse(finished.out)).toEqual({status: 'finished', search_id: 902, search_status: 'finished'}); + expect(JSON.parse(ran_out.out)).toEqual({status: 'finished', search_id: 903, search_status: 'noMoreContacts'}); + await expect(handle_live_data_resume('904', ctx(), {})).rejects.toMatchObject({ + code: 'outcome.unknown', exit_code: 3, ids: {search_id: 904}, + }); expect(sent()[0]).toMatchObject({method: 'POST', url: 'https://api/v3/live-data/searches/901/resume'}); }); diff --git a/src/operations/commands.ts b/src/operations/commands.ts index fd7b602..be69cb0 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -749,7 +749,8 @@ live_data_command.command('preview') + 'seconds; reading it needs the key\'s other:read scope, without which the read is access.feature_unavailable. Every\n' + 'failure after the start carries the job id in details.job_id. A newer preview by the same user replaces an older one,\n' + 'whose job then never finishes. live_data.preview_failed: the job ended Failed, Cancelled, Expired or Unknown\n' - + '(details.job_status). live_data.preview_not_found: Reply has no such job for this user.\n' + FILTERS_HELP)) + + '(details.job_status). live_data.preview_not_found: Reply has no such job for this user. --max-per-company goes\n' + + 'with --filters only. After exit 3 on the start, running the command again is safe.\n' + FILTERS_HELP)) .action(run(async(cmd)=>{ const {g, ctx} = ctx_of(cmd); await handle_live_data_preview(cmd.opts(), ctx, g); @@ -764,14 +765,17 @@ live_data_command.command('start') .description('Start a search that adds the people it finds as contacts and puts them on the lists named') .addHelpText('after', help( [`echo '{"jobTitles":[{"value":"CTO","type":"include"}],"companySizes":["fifty"]}' | ${P} live-data start --filters - --count 25 --list-id 77`], - ['live_data.invalid_filters', 'live_data.search_in_progress', 'live_data.insufficient_credits', 'live_data.service_failed'], true, + ['live_data.invalid_filters', 'live_data.search_in_progress', 'live_data.insufficient_credits', 'contact-list.not_found', + 'live_data.service_failed'], true, 'Result: {"status":"started","search_id"}. The search runs on at Reply: follow it with `live-data get`, and read the people\n' + 'off its list with `contact-list contacts`. A person Reply already holds is skipped, not added to the list.\n' + FILTERS_HELP + 'live_data.search_in_progress: an unfinished search (running or paused) of the same team with the same filters, both\n' + 'with or both without account lists, blocks a start; the lists, the count, people per company and phones do not count.\n' + 'A deleted search no longer blocks. live_data.insufficient_credits: the team cannot afford a single contact; nothing\n' - + 'started. live_data.service_failed: Reply\'s search service failed and Reply saved no search; the call can be made again.\n' + + 'started. contact-list.not_found: a --list-id the account does not have or cannot reach; nothing started.\n' + + 'live_data.invalid_filters: Reply did not accept the request, most often the filters; Reply\'s detail names what.\n' + + 'live_data.service_failed: Reply\'s search service failed and Reply saved no search; the call can be made again.\n' + 'A key without the contact permissions gets access.feature_unavailable.\n', 'a search may have started; `live-data list` shows the team\'s searches with their lists')) .action(run(async(cmd)=>{ @@ -819,11 +823,12 @@ live_data_command.command('pause') live_data_command.command('resume') .argument('', 'Live Data search id') - .description('Resume a paused search, or finish one that has nothing left to find') + .description('Resume a paused search, or finish one that already has everything it was asked for') .addHelpText('after', help([ex('live-data resume 901')], ['live_data.not_found', 'live_data.invalid_status', 'live_data.insufficient_credits', 'live_data.contact_limit_reached', 'live_data.service_failed'], true, - 'Result: {"status":"resumed"|"finished","search_id"}: finished when the search had already found everything asked for.\n' + 'Result: {"status":"resumed","search_id"}, or {"status":"finished","search_id","search_status"} when the search had\n' + + 'already found everything asked for (search_status finished) or Reply ended it otherwise (noMoreContacts).\n' + 'Resume applies to manuallyPaused, pausedDueToInsufficientCredits and pausedDueToContactLimit; live_data.invalid_status\n' + 'carries Reply\'s detail naming the current status. live_data.insufficient_credits: the team cannot afford a single\n' + 'contact, and the search stays paused. live_data.contact_limit_reached: the search was paused by the plan\'s contact\n' diff --git a/src/operations/contact-list.ts b/src/operations/contact-list.ts index 7a7d177..5e0b146 100644 --- a/src/operations/contact-list.ts +++ b/src/operations/contact-list.ts @@ -8,6 +8,7 @@ import {read_contact_input, type Contact_flags} from './contact-input'; import {ensure_contact, read_opted_out} from './contacts'; import {read_stdin_name} from './stdin-input'; import {print_result, with_ids} from './result'; +import {PROGRAM_NAME} from '../config'; import type {Cli_context} from '../context'; type List_add_opts = Contact_flags & {refuseOptedOut?: boolean}; @@ -65,21 +66,31 @@ const handle_contact_list_create = async( ): Promise=>{ const name = read_stdin_name(opts.name, 'contact-list create', read_stdin); const s = await open_session(ctx, g); - const a = await call_reply(s, 'POST', '/v3/contact-lists', 'write', {name, isShared: opts.shared === true}); - if (a.status === 409 && reply_code_of(a) === 'contactsList.duplicateName') - { - throw new Operation_error('contact-list.name_taken', 'This account already has a contact list of that name.', { - status: 409, reply_code: reply_code_of(a), - }); - } - if (a.status !== 201 && a.status !== 200) - { - throw refusal(a, 'write'); - } - const made = expect_object(a, 'write'); - if (!is_reply_id(made.id)) - { - throw unreadable(a, 'write'); + let made: Record; + try { + const a = await call_reply(s, 'POST', '/v3/contact-lists', 'write', {name, isShared: opts.shared === true}); + if (a.status === 409 && reply_code_of(a) === 'contactsList.duplicateName') + { + throw new Operation_error('contact-list.name_taken', 'This account already has a contact list of that name.', { + status: 409, reply_code: reply_code_of(a), + }); + } + if (a.status !== 201 && a.status !== 200) + { + throw refusal(a, 'write'); + } + made = expect_object(a, 'write'); + if (!is_reply_id(made.id)) + { + throw unreadable(a, 'write'); + } + } catch (e) { + if (e instanceof Unknown_outcome_error) + { + e.hint = 'The list may have been made, and a repeat under the same name answers contact-list.name_taken. ' + + `\`${PROGRAM_NAME} api '/v3/contact-lists?search='\` finds it by its name.`; + } + throw e; } print_result({ status: 'created', list_id: made.id, diff --git a/src/operations/live-data-preview.ts b/src/operations/live-data-preview.ts index 6de498a..11fc4f4 100644 --- a/src/operations/live-data-preview.ts +++ b/src/operations/live-data-preview.ts @@ -1,49 +1,59 @@ -import {Operation_error, UsageError} from '../utils/errors'; +import {Operation_error, Unknown_outcome_error, UsageError} from '../utils/errors'; +import {sleep} from '../utils/client'; import {call_reply, expect_object, is_object, refusal, reply_code_of, unreadable, open_session, type Answer, type Op_session} from './call'; import {parse_int_in, LARGEST_REPLY_ID, type Op_globals} from './options'; import {live_data_error, read_filters} from './live-data'; import {print_result} from './result'; +import {PROGRAM_NAME} from '../config'; import type {Cli_context} from '../context'; const POLL_MS = 2000; const DEFAULT_WAIT_SECONDS = 120; const MAX_WAIT_SECONDS = 600; const GUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i; -const FAILED = ['Failed', 'Cancelled', 'Expired', 'Unknown']; +// v3's background-job statuses, read without regard to case; any other is not one the CLI can read. +const RUNNING = ['scheduled', 'processing']; +const FAILED = ['failed', 'cancelled', 'expired', 'unknown']; type Preview_opts = {filters?: string; jobId?: string; maxPerCompany?: string; waitSeconds?: string}; -const sleep = (ms: number): Promise=>new Promise(resolve=>setTimeout(resolve, ms)); - const number_or_null = (v: unknown): number | null=>(typeof v === 'number' ? v : null); const string_or_null = (v: unknown): string | null=>(typeof v === 'string' ? v : null); +// A field under its PascalCase name or its camelCase one. +const field = (o: Record, pascal: string): unknown=> + (pascal in o ? o[pascal] : o[pascal[0].toLowerCase() + pascal.slice(1)]); + // INTERIM (API gap): a preview job's result is a JSON string with PascalCase keys, not an object in v3's casing. // Needed: jsonDataResult as an object, named as the rest of v3 names its fields. -// Workaround: parse the string and rename the fields a preview answers. +// Workaround: parse the string and rename the fields a preview answers; an object, in either casing, reads the same. const preview_result = (job: Record, a: Answer): Record=>{ - let result: unknown; - try { - result = typeof job.jsonDataResult === 'string' ? JSON.parse(job.jsonDataResult) : undefined; - } catch { - result = undefined; + let result: unknown = job.jsonDataResult; + if (typeof result === 'string') + { + try { + result = JSON.parse(result); + } catch { + result = undefined; + } } if (!is_object(result)) { throw unreadable(a, 'read'); } - const samples = Array.isArray(result.SampleContacts) ? result.SampleContacts.filter(is_object) : []; + const sample_list = field(result, 'SampleContacts'); + const samples = Array.isArray(sample_list) ? sample_list.filter(is_object) : []; return { - contacts_count: number_or_null(result.ContactsCount), - companies_count: number_or_null(result.CompaniesCount), + contacts_count: number_or_null(field(result, 'ContactsCount')), + companies_count: number_or_null(field(result, 'CompaniesCount')), sample_contacts: samples.map(c=>({ - first_name: string_or_null(c.FirstName), - last_name: string_or_null(c.LastName), - job_title: string_or_null(c.JobTitle), - location: string_or_null(c.Location), - linkedin_url: string_or_null(c.LinkedInUrl), - company_name: string_or_null(c.CompanyName), - company_domain: string_or_null(c.CompanyDomain), + first_name: string_or_null(field(c, 'FirstName')), + last_name: string_or_null(field(c, 'LastName')), + job_title: string_or_null(field(c, 'JobTitle')), + location: string_or_null(field(c, 'Location')), + linkedin_url: string_or_null(field(c, 'LinkedInUrl')), + company_name: string_or_null(field(c, 'CompanyName')), + company_domain: string_or_null(field(c, 'CompanyDomain')), })), }; }; @@ -54,17 +64,25 @@ const start_preview = async(s: Op_session, filters: Record, max { body.maxPeoplePerCompany = max_per_company; } - const a = await call_reply(s, 'POST', '/v3/live-data/searches/preview', 'write', body); - if (a.status !== 202 && a.status !== 200) - { - throw live_data_error(a, 'write'); - } - const job_id = expect_object(a, 'write').jobId; - if (typeof job_id !== 'string' || !GUID.test(job_id)) - { - throw unreadable(a, 'write'); + try { + const a = await call_reply(s, 'POST', '/v3/live-data/searches/preview', 'write', body); + if (a.status !== 202 && a.status !== 200) + { + throw live_data_error(a, 'write'); + } + const job_id = expect_object(a, 'write').jobId; + if (typeof job_id !== 'string' || !GUID.test(job_id)) + { + throw unreadable(a, 'write'); + } + return job_id; + } catch (e) { + if (e instanceof Unknown_outcome_error) + { + e.hint = `A preview saves and charges nothing, and a newer one replaces an older one: running \`${PROGRAM_NAME} live-data preview\` again is safe.`; + } + throw e; } - return job_id; }; const read_job = async(s: Op_session, job_id: string): Promise<{job: Record; a: Answer}>=>{ @@ -93,17 +111,22 @@ const wait_for_job = async(s: Op_session, job_id: string, wait_ms: number, g: Op for (let slept = 0; ; slept += POLL_MS) { const {job, a} = await read_job(s, job_id); - if (job.status === 'Done') + const status = (job.status as string).toLowerCase(); + if (status === 'done') { print_result({status: 'done', job_id, ...preview_result(job, a)}, g); return; } - if (FAILED.includes(job.status as string)) + if (FAILED.includes(status)) { throw new Operation_error('live_data.preview_failed', 'The preview ended without a result.', { - status: 200, details: {job_status: job.status}, + details: {job_status: job.status}, }); } + if (!RUNNING.includes(status)) + { + throw unreadable(a, 'read'); + } if (slept + POLL_MS > wait_ms) { print_result({status: 'pending', job_id, progress: number_or_null(job.progress)}, g); @@ -122,6 +145,10 @@ const handle_live_data_preview = async(opts: Preview_opts, ctx: Cli_context, g: { throw new UsageError('--job-id must be the job id a preview answered (a GUID).', {code: 'usage.id', hint: `Got: ${opts.jobId}`}); } + if (opts.jobId !== undefined && opts.maxPerCompany !== undefined) + { + throw new UsageError('--max-per-company goes with --filters: a preview already started keeps its own.', {code: 'usage.filters'}); + } const filters = opts.filters === undefined ? undefined : read_filters(opts.filters, read_stdin); const max_per_company = opts.maxPerCompany === undefined ? undefined : parse_int_in(opts.maxPerCompany, '--max-per-company', 1, LARGEST_REPLY_ID, 1); diff --git a/src/operations/live-data.ts b/src/operations/live-data.ts index 82528f8..2b19edb 100644 --- a/src/operations/live-data.ts +++ b/src/operations/live-data.ts @@ -10,12 +10,14 @@ import {parse_id, parse_int_in, parse_choice, LARGEST_REPLY_ID, type Op_globals} import {print_result, with_ids} from './result'; import type {Cli_context} from '../context'; -const LIVE_DATA_CODES: Record = { - 'liveDataSearch.searchInProgress': 'live_data.search_in_progress', - 'liveDataSearch.invalidStatus': 'live_data.invalid_status', - 'liveDataSearch.insufficientCredits': 'live_data.insufficient_credits', - 'liveDataSearch.contactLimitReached': 'live_data.contact_limit_reached', - 'liveDataSearch.invalidParameter': 'live_data.invalid_filters', +// Each code at the status Reply answers it with: a 5xx that happens to carry one stays an unknown outcome on a write. +const LIVE_DATA_CODES: Record = { + 'liveDataSearch.searchInProgress': {status: 409, code: 'live_data.search_in_progress'}, + 'liveDataSearch.invalidStatus': {status: 409, code: 'live_data.invalid_status'}, + 'liveDataSearch.insufficientCredits': {status: 422, code: 'live_data.insufficient_credits'}, + 'liveDataSearch.contactLimitReached': {status: 422, code: 'live_data.contact_limit_reached'}, + 'liveDataSearch.invalidParameter': {status: 400, code: 'live_data.invalid_filters'}, + 'liveDataSearch.upstreamFailure': {status: 502, code: 'live_data.service_failed'}, }; const LIVE_DATA_TITLES: Record = { @@ -24,18 +26,19 @@ const LIVE_DATA_TITLES: Record = { 'live_data.invalid_status': 'The search is not in a status this applies to.', 'live_data.insufficient_credits': 'The team does not have the credits for a single contact.', 'live_data.contact_limit_reached': 'The search owner\'s plan has no room for another contact.', - 'live_data.invalid_filters': 'Reply did not accept the filters.', + 'live_data.invalid_filters': 'Reply did not accept the request, most often the filters; its detail names what.', 'live_data.service_failed': 'Reply\'s search service failed; nothing changed, and the call can be made again.', }; -// Live Data's own refusals; any other answer reads as every operation reads it. Reply's 502 with its -// own upstreamFailure code is definite, even on a write: Reply saved nothing, or kept the search as it was. +// Live Data's own refusals; any other answer reads as every operation reads it. A 404 means "no such +// search" only on a call that names one. Reply's 502 with its own upstreamFailure code is definite, +// even on a write: Reply saved nothing, or kept the search as it was. const live_data_error = (a: Answer, kind: Call_kind, search_id?: number): Operation_error=>{ const reply_code = reply_code_of(a); - const by_code = reply_code === undefined ? undefined : LIVE_DATA_CODES[reply_code]; - const code = a.status === 404 ? 'live_data.not_found' - : a.status === 502 && reply_code?.endsWith('.upstreamFailure') ? 'live_data.service_failed' - : by_code; + const known = reply_code === undefined ? undefined : LIVE_DATA_CODES[reply_code]; + const code = a.status === 404 && search_id !== undefined ? 'live_data.not_found' + : known?.status === a.status ? known.code + : undefined; if (code === undefined) { return refusal(a, kind); @@ -91,7 +94,7 @@ const handle_live_data_start = async(opts: Start_opts, ctx: Cli_context, g: Op_g { throw new UsageError('No --count was given.', {code: 'usage.range', hint: 'The most people the search may add, e.g. --count 25.'}); } - const body: Record = {filters, contactsCountToAdd: parse_int_in(opts.count, '--count', 1, LARGEST_REPLY_ID, 0)}; + const body: Record = {filters, contactsCountToAdd: parse_int_in(opts.count, '--count', 1, LARGEST_REPLY_ID, 1)}; if (opts.listId !== undefined && opts.listId.length > 0) { body.listIds = opts.listId.map(id=>parse_id(id, '--list-id')); @@ -107,6 +110,12 @@ const handle_live_data_start = async(opts: Start_opts, ctx: Cli_context, g: Op_g const s = await open_session(ctx, g); try { const a = await call_reply(s, 'POST', '/v3/live-data/searches', 'write', body); + if (a.status === 404) + { + throw new Operation_error('contact-list.not_found', 'A list given with --list-id does not exist or is not accessible.', { + status: 404, reply_code: reply_code_of(a), detail: detail_of(a), + }); + } if (a.status !== 200 && a.status !== 201) { throw live_data_error(a, 'write'); @@ -154,17 +163,22 @@ const handle_live_data_pause = async(id_arg: string, ctx: Cli_context, g: Op_glo print_result({status: 'paused', search_id: id}, g); }; -// Reply answers the search as it now holds it: running again, or finished when nothing was left to find. +// Reply answers the search as it now holds it: running again, or ended because it already had everything asked +// for. Any other status is not what a resume leaves behind. +const RESUMED: Record = {inProgress: 'resumed', finished: 'finished', noMoreContacts: 'finished'}; + const handle_live_data_resume = async(id_arg: string, ctx: Cli_context, g: Op_globals): Promise=>{ const {id, result} = await act_on_search(id_arg, 'POST', '/resume', ctx, g, a=>{ const status = expect_object(a, 'write').status; - if (typeof status !== 'string') + if (typeof status !== 'string' || RESUMED[status] === undefined) { throw unreadable(a, 'write'); } return status; }); - print_result({status: result === 'finished' ? 'finished' : 'resumed', search_id: id}, g); + print_result(RESUMED[result] === 'resumed' + ? {status: 'resumed', search_id: id} + : {status: 'finished', search_id: id, search_status: result}, g); }; const handle_live_data_delete = async(id_arg: string, ctx: Cli_context, g: Op_globals): Promise=>{ diff --git a/src/utils/client.ts b/src/utils/client.ts index c3d7cad..693a243 100644 --- a/src/utils/client.ts +++ b/src/utils/client.ts @@ -291,5 +291,5 @@ const create_client = ( get(base_url, token, endpoint, {...opts, headers: {...headers, ...opts?.headers}}), }); -export {request, get, request_raw, create_client, parse_retry_after}; +export {request, get, request_raw, create_client, parse_retry_after, sleep}; export type {Request_opts, Client, Raw_response, Call_kind}; From e2ee29f794168f699ddb19e6195a0d8f6de5d349 Mon Sep 17 00:00:00 2001 From: vigubikReply Date: Mon, 9 Nov 2026 15:24:41 -0500 Subject: [PATCH 3/4] fix(live-data): read a preview's result as Reply sends it 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. --- .../operations/live-data-preview.test.ts | 19 +++++------- src/__tests__/operations/live-data.test.ts | 4 +-- src/operations/live-data-preview.ts | 31 ++++++++----------- 3 files changed, 22 insertions(+), 32 deletions(-) diff --git a/src/__tests__/operations/live-data-preview.test.ts b/src/__tests__/operations/live-data-preview.test.ts index eb9f493..95185c3 100644 --- a/src/__tests__/operations/live-data-preview.test.ts +++ b/src/__tests__/operations/live-data-preview.test.ts @@ -14,15 +14,16 @@ beforeEach(()=>{ afterEach(()=>{ real_timers(); }); describe('live-data preview', ()=>{ + // The job as Reply's dev API answered it on 2026-11-09: the result a JSON string, its counts null it('starts, waits for the job and answers the counts and the samples in the CLI\'s names', async()=>{ answer(json({jobId: J}, 202), job('Processing', {progress: 0.5}), job('Done', {jsonDataResult: JSON.stringify({ - ContactsCount: 1200, CompaniesCount: 300, SampleContacts: [{ - FirstName: 'Ann', LastName: 'Example', JobTitle: 'CTO', Location: 'Berlin', - LinkedInUrl: 'https://www.linkedin.com/in/ann-example', CompanyName: 'Example GmbH', CompanyDomain: 'example.com', + contactsCount: null, companiesCount: null, sampleContacts: [{ + firstName: 'Ann', lastName: 'Example', jobTitle: 'CTO', location: 'Berlin', + linkedInUrl: 'https://www.linkedin.com/in/ann-example', companyName: 'Example GmbH', companyDomain: 'example.com', }], })})); const {out} = await capture(()=>preview({filters: FILTERS})); - expect(JSON.parse(out)).toEqual({status: 'done', job_id: J, contacts_count: 1200, companies_count: 300, sample_contacts: [{ + expect(JSON.parse(out)).toEqual({status: 'done', job_id: J, contacts_count: null, companies_count: null, sample_contacts: [{ first_name: 'Ann', last_name: 'Example', job_title: 'CTO', location: 'Berlin', linkedin_url: 'https://www.linkedin.com/in/ann-example', company_name: 'Example GmbH', company_domain: 'example.com', }]}); @@ -46,7 +47,7 @@ describe('live-data preview', ()=>{ }); it('--job-id goes on waiting for a preview already started, without starting one', async()=>{ - answer(job('Done', {jsonDataResult: '{"ContactsCount":5,"CompaniesCount":2,"SampleContacts":[]}'})); + answer(job('Done', {jsonDataResult: '{"contactsCount":5,"companiesCount":2,"sampleContacts":[]}'})); const {out} = await capture(()=>preview({jobId: J})); expect(JSON.parse(out)).toMatchObject({status: 'done', contacts_count: 5}); expect(sent().map(r=>r.url)).toEqual([`https://api/v3/background-jobs/${J}`]); @@ -64,7 +65,7 @@ describe('live-data preview', ()=>{ }); }); - it('a result given as an object in v3\'s casing, under a status in another case, reads the same', async()=>{ + it('a result given as an object, under a status in another case, reads the same', async()=>{ answer(job('done', {jsonDataResult: {contactsCount: 5, companiesCount: 2, sampleContacts: [{firstName: 'Ann', companyDomain: 'example.com'}]}})); const {out} = await capture(()=>preview({jobId: J})); expect(JSON.parse(out)).toEqual({status: 'done', job_id: J, contacts_count: 5, companies_count: 2, sample_contacts: [{ @@ -79,12 +80,6 @@ describe('live-data preview', ()=>{ expect(mock_fetch).toHaveBeenCalledTimes(1); }); - it('counts Reply did not give are null', async()=>{ - answer(job('Done', {jsonDataResult: '{"SampleContacts":[]}'})); - const {out} = await capture(()=>preview({jobId: J})); - expect(JSON.parse(out)).toEqual({status: 'done', job_id: J, contacts_count: null, companies_count: null, sample_contacts: []}); - }); - it('a Done job whose result is not JSON is reply.unavailable with the job id', async()=>{ answer(job('Done', {jsonDataResult: 'not json'})); await expect(preview({jobId: J})).rejects.toMatchObject({code: 'reply.unavailable', details: {job_id: J}, exit_code: 1}); diff --git a/src/__tests__/operations/live-data.test.ts b/src/__tests__/operations/live-data.test.ts index 0eb354c..fa35e2e 100644 --- a/src/__tests__/operations/live-data.test.ts +++ b/src/__tests__/operations/live-data.test.ts @@ -64,9 +64,9 @@ describe('live-data start', ()=>{ }); it('a 409 is live_data.search_in_progress with Reply\'s words', async()=>{ - answer(json({code: 'liveDataSearch.searchInProgress', detail: 'A live data search is already in progress.'}, 409)); + answer(json({code: 'liveDataSearch.searchInProgress', detail: 'Cannot start search with unfinished searches: 19465'}, 409)); await expect(start({})).rejects.toMatchObject({ - code: 'live_data.search_in_progress', detail: 'A live data search is already in progress.', exit_code: 1, + code: 'live_data.search_in_progress', detail: 'Cannot start search with unfinished searches: 19465', exit_code: 1, }); }); diff --git a/src/operations/live-data-preview.ts b/src/operations/live-data-preview.ts index 11fc4f4..dc9e82f 100644 --- a/src/operations/live-data-preview.ts +++ b/src/operations/live-data-preview.ts @@ -20,13 +20,9 @@ type Preview_opts = {filters?: string; jobId?: string; maxPerCompany?: string; w const number_or_null = (v: unknown): number | null=>(typeof v === 'number' ? v : null); const string_or_null = (v: unknown): string | null=>(typeof v === 'string' ? v : null); -// A field under its PascalCase name or its camelCase one. -const field = (o: Record, pascal: string): unknown=> - (pascal in o ? o[pascal] : o[pascal[0].toLowerCase() + pascal.slice(1)]); - -// INTERIM (API gap): a preview job's result is a JSON string with PascalCase keys, not an object in v3's casing. -// Needed: jsonDataResult as an object, named as the rest of v3 names its fields. -// Workaround: parse the string and rename the fields a preview answers; an object, in either casing, reads the same. +// INTERIM (API gap): a preview job's result is a JSON string, not an object. +// Needed: jsonDataResult as an object. +// Workaround: parse the string; an object reads the same. const preview_result = (job: Record, a: Answer): Record=>{ let result: unknown = job.jsonDataResult; if (typeof result === 'string') @@ -41,19 +37,18 @@ const preview_result = (job: Record, a: Answer): Record({ - first_name: string_or_null(field(c, 'FirstName')), - last_name: string_or_null(field(c, 'LastName')), - job_title: string_or_null(field(c, 'JobTitle')), - location: string_or_null(field(c, 'Location')), - linkedin_url: string_or_null(field(c, 'LinkedInUrl')), - company_name: string_or_null(field(c, 'CompanyName')), - company_domain: string_or_null(field(c, 'CompanyDomain')), + first_name: string_or_null(c.firstName), + last_name: string_or_null(c.lastName), + job_title: string_or_null(c.jobTitle), + location: string_or_null(c.location), + linkedin_url: string_or_null(c.linkedInUrl), + company_name: string_or_null(c.companyName), + company_domain: string_or_null(c.companyDomain), })), }; }; From 49f236cc56706c8171b81a4c0db63daa3347e64b Mon Sep 17 00:00:00 2001 From: vigubikReply Date: Mon, 9 Nov 2026 15:24:41 -0500 Subject: [PATCH 4/4] docs: the dev profile's api base is the host --- CONTRIBUTING.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e0f6b75..06752d2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -80,7 +80,7 @@ another environment (internal testing only): ```sh reply profile add dev \ --authority https://oauth.dev.replyapp.io \ - --api-base https://api.dev.reply.io/v3 + --api-base https://api.dev.reply.io reply --profile dev auth login ``` @@ -89,7 +89,7 @@ Any field left off is inherited from the default (prod). Profiles live in ```jsonc // ~/.config/reply/config.json -{ "profiles": { "dev": { "authority": "https://…", "api_base": "https://…/v3" } } } +{ "profiles": { "dev": { "authority": "https://…", "api_base": "https://…" } } } ``` ## Packages: public vs internal