Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 40 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -195,11 +195,11 @@ prints JSON (indented; compact with `--json`) and says what happened in a stable
| `reply contact-list add-contact <list-id> <contact> [--refuse-opted-out]` | → `added` |
| `reply contact find --contact -` | the id of the contact under an email or a LinkedIn URL, or null; never creates one |
| `reply contact get <id>` | the contact as Reply holds it |
| `reply contact update <id> --fields -` | change some fields and custom fields; null clears one → `updated` |
| `reply contact update (<id> \| <contact>) --fields -` | change some fields and custom fields; null clears one → `updated` |
| `reply contact delete <id>` | → `deleted` |
| `reply contact opt-out <contact>` | → `opted_out` |
| `reply contact send-email --contact-id N --email-account-id N --message -` | one email now, outside any sequence → `sent` |
| `reply contact linkedin-connect --contact-id N --linkedin-account-id N [--message -]` | a LinkedIn invitation, with or without a note → `sent` / `already_connected` |
| `reply contact send-email <contact> --email-account-id N --message -` | one email now, outside any sequence → `sent` |
| `reply contact linkedin-connect <contact> --linkedin-account-id N [--message -]` | a LinkedIn invitation, with or without a note → `sent` / `already_connected` |
| `reply contact linkedin-message …` · `linkedin-inmail …` · `linkedin-voice …` | a LinkedIn message, an InMail, or an AI voice message spoken from a script → `sent` |
| `reply inbox list (--contact-id \| --sequence-id) [--source] [--channel] [--category-id] [--since]` | one page of threads |
| `reply inbox get <thread-id>` | a thread with its subject, and one page of its messages |
Expand All @@ -221,9 +221,27 @@ echo '{"linkedin_url":"https://www.linkedin.com/in/ann-example","first_name":"An

The two `add-contact` commands always import a contact given by email, and Reply refuses an import
without a first name, even for a contact it already holds; a contact given only by LinkedIn URL is
looked up first and imported only when Reply holds nobody under it. `contact opt-out` imports only
someone Reply doesn't hold yet; `sequence remove-contact` never imports. A contact is looked up, and
an import matched, by its email; one with only a LinkedIn URL, by that. The lookup is Reply's exact
looked up first and imported only when Reply holds nobody under it. `contact opt-out`, `contact
update` and the direct sends look first and import only someone Reply doesn't hold yet, so only then
is a first name needed, and a direct send sends only to a contact it created (below); `sequence
remove-contact` never imports. Each of these except `sequence remove-contact` answers the
`contact_id` it acted on and `contact_created`, so a caller can keep the id. A send looks the person
up by every address it was given, the one it reaches them at first (the email for `contact send-email`,
the LinkedIn URL for the LinkedIn sends), then the other when there is one. Otherwise a contact is
looked up by its email, and one with only a LinkedIn URL by that; an import is matched by the email
when there is one.

A direct send given a person's fields sends only to a contact it creates. When a lookup by any address
it was given finds a contact, or its import matches one Reply already holds (by the email, say, or a teammate's), nothing
is sent: the answer is `contact.already_held` (exit 1) with that contact's id in `ids.contact_id`.
Read that contact first with `reply contact get`, its opt-out included, and send to it with
`--contact-id` if it is the one to reach. Reply does not refuse a direct send to a contact it holds
as opted out, so a send never reaches a contact Reply already held without that read. A LinkedIn
send needs a `linkedin_url` in `--contact` (or `--contact-id`): `--email` alone is refused. On a send,
`contact_created` is kept for consistency with the add commands: given a person's fields it is always `true`,
and with `--contact-id` it is always `false`; in both cases a successful answer says the send was made.

The lookup is Reply's exact
one: an email matches ignoring case, and a LinkedIn URL is matched by its lowercased slug — on
linkedin.com the path's case does not count, nor the scheme's or host's, a default port, one trailing
slash or a fragment, while `www` and the query do. Reply is asked for a LinkedIn URL in that form
Expand All @@ -242,7 +260,18 @@ echo '{"name":"Q4 outreach"}' | reply sequence list --name -
```

`contact update` refuses a custom field the account has none of, `contact.field_not_found`, before
it changes anything.
it changes or imports anything. Given the contact by its flags rather than its id, it changes only
what `--fields` names: the contact's own fields find the contact, or import it, and never change one
Reply already holds.

When `--contact -` and the command's own input (`--message -` or `--fields -`) both read stdin, it
holds one object with each under its flag's name, so neither the person nor the text ever sits in
the argument list:

```sh
echo '{"contact":{"email":"ann@example.com","first_name":"Ann"},"fields":{"title":"CTO"}}' | reply contact update --contact - --fields -
echo '{"contact":{"linkedin_url":"https://www.linkedin.com/in/ann-example","first_name":"Ann"},"message":{"body":"Thanks for connecting, Ann."}}' | reply contact linkedin-message --contact - --linkedin-account-id 34 --message -
```

`inbox reply` takes its message, `{body, reply_to_message_id}`, from stdin only, and refuses it on
the argument list. The reply goes to the thread's contact from the account that owns the thread;
Expand Down Expand Up @@ -276,7 +305,10 @@ variables, and refuses one it cannot fill with `linkedin.missing_variables`.

`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; for `inbox reply`, read the thread with `reply inbox get` before trying again. For
send it twice, unless the hint says nothing was sent: a send whose contact's import lost its answer
was never made, and its hint says so; run again, it answers `contact.already_held` if that import did
create the contact.
For `inbox reply`, read the thread with `reply inbox get` before trying again. For
`sequence create`, Reply allows two sequences of one name, so after exit 3 look the name up with
`sequence list --name -` first. Every other work command can simply be run again; a `contact delete`
repeated after its first one took effect answers `contact.not_found`.
Expand Down
85 changes: 73 additions & 12 deletions src/__tests__/operations/commands.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,17 +42,21 @@ describe('operations/commands', ()=>{
expect(text, text).not.toContain('outcome.unknown');
});

// The sends and contact update find or import the person as the add commands do.
const SENDS_AND_UPDATE = ['update', 'send-email', 'linkedin-connect', 'linkedin-message', 'linkedin-inmail', 'linkedin-voice'];
const CONTACT_FLAGS = ['--contact-id', '--email', '--first-name', '--last-name', '--company', '--title', '--contact'];

it('the commands about a person take the contact flags', ()=>{
for (const c of [sub(sequence_command, 'add-contact'), sub(sequence_command, 'remove-contact'),
sub(contact_list_command, 'add-contact'), sub(contact_command, 'opt-out')])
sub(contact_list_command, 'add-contact'), sub(contact_command, 'opt-out'), ...SENDS_AND_UPDATE.map(n=>sub(contact_command, n))])
{
expect(flags(c)).toEqual(expect.arrayContaining(['--contact-id', '--email', '--contact']));
expect(flags(c), c.name()).toEqual(expect.arrayContaining(CONTACT_FLAGS));
}
});

it('the commands about a person say their JSON takes linkedin_url, and a lookup is never left incomplete', ()=>{
for (const c of [sub(sequence_command, 'add-contact'), sub(sequence_command, 'remove-contact'),
sub(contact_list_command, 'add-contact'), sub(contact_command, 'opt-out')])
sub(contact_list_command, 'add-contact'), sub(contact_command, 'opt-out'), ...SENDS_AND_UPDATE.map(n=>sub(contact_command, n))])
{
const text = help_of(c);
expect(text, text).toContain('linkedin_url');
Expand All @@ -61,11 +65,42 @@ describe('operations/commands', ()=>{
// Each of them looks a contact up by address, and two contacts under one address is refused.
expect(text, text).toContain(' contact.not_unique\n');
}
for (const c of [sub(sequence_command, 'add-contact'), sub(contact_list_command, 'add-contact'), sub(contact_command, 'opt-out')])
for (const c of [sub(sequence_command, 'add-contact'), sub(contact_list_command, 'add-contact'), sub(contact_command, 'opt-out'),
...SENDS_AND_UPDATE.map(n=>sub(contact_command, n))])
{
const text = help_of(c);
expect(text, text).toContain('contact.invalid_linkedin_url');
for (const code of ['contact.invalid_email', 'contact.invalid_linkedin_url', 'account.contact_limit_reached'])
{
expect(text, `${c.name()} ${code}`).toContain(` ${code}\n`);
}
}
});

it('the sends and contact update say a contact is imported only when Reply holds nobody, and how stdin holds both inputs', ()=>{
for (const name of SENDS_AND_UPDATE)
{
const text = help_of(sub(contact_command, name));
const flat = text.replace(/\s+/g, ' ');
const input = name === 'update' ? 'fields' : 'message';
expect(flat, text).toContain('imported only when Reply holds nobody under');
expect(flat, text).toContain(name === 'update' ? 'contact_created says whether this command created'
: 'contact_created is kept for consistency with the add commands: given a person\'s fields it is always true, and with --contact-id it is always false; in both cases a successful answer says the send was made');
expect(flat, text).toContain(`With --contact - and --${input} - both, stdin holds one object: {"contact": {…}, "${input}": {…}}`);
expect(text, text).toContain(`--contact - `);
}
const email = help_of(sub(contact_command, 'send-email')).replace(/\s+/g, ' ');
expect(email, email).toContain('looked up by its email');
for (const name of ['linkedin-connect', 'linkedin-message', 'linkedin-inmail', 'linkedin-voice'])
{
const text = help_of(sub(contact_command, name)).replace(/\s+/g, ' ');
expect(text, text).toContain('looked up by its LinkedIn URL');
}
const update = help_of(sub(contact_command, 'update')).replace(/\s+/g, ' ');
expect(update, update).toContain('looked up as the add commands look one up');
// An update acts on a contact it finds, so only an import needs a first name.
expect(update, update).toContain('only then does Reply need a first name');
expect(update, update).toContain('only what --fields names is changed');
expect(update, update).toContain('contact update 456 is contact update --contact-id 456');
});

it('carries each command\'s own flags', ()=>{
Expand Down Expand Up @@ -98,7 +133,7 @@ describe('operations/commands', ()=>{

it('contact update takes its values only through --fields -, and contact delete says what a re-run answers', ()=>{
const update = sub(contact_command, 'update');
expect(flags(update)).toEqual(['--fields']);
expect(flags(update)).toEqual([...CONTACT_FLAGS, '--fields']);
const text = help_of(update);
expect(text, text).toContain('--fields -');
expect(text, text).toContain('contact.field_not_found');
Expand All @@ -117,13 +152,30 @@ describe('operations/commands', ()=>{
expect(text.replace(/\s+/g, ' '), text).toContain('matched by its lowercased slug');
});

it('the commands that look a contact up first say the name flags are used only if it is imported; the add commands do not', ()=>{
const described = (c: Command, flag: string)=>c.options.find(o=>o.long === flag)?.description as string;
const lookups = ['update', 'opt-out', 'send-email', 'linkedin-connect', 'linkedin-message', 'linkedin-inmail', 'linkedin-voice'];
for (const name of lookups)
{
for (const flag of ['--last-name', '--company', '--title'])
{
expect(described(sub(contact_command, name), flag), `${name} ${flag}`).toContain('used only if the contact is imported');
}
}
for (const flag of ['--last-name', '--company', '--title'])
{
expect(described(sub(sequence_command, 'add-contact'), flag), flag).not.toContain('used only if');
}
});

// Each direct send: the flag naming the account it goes from, the codes its endpoint publishes, and what its help
// says sent_at is.
const LINKEDIN = ['contact.not_found', 'contact.no_linkedin_profile', 'linkedin.account_not_found', 'linkedin.feature_disabled',
'linkedin.account_inactive', 'linkedin.invalid_cookie'];
const IMPORT = ['contact.not_unique', 'contact.invalid_email', 'contact.invalid_linkedin_url', 'account.contact_limit_reached'];
const LINKEDIN = ['contact.not_found', ...IMPORT, 'contact.already_held', 'contact.no_linkedin_profile', 'linkedin.account_not_found',
'linkedin.feature_disabled', 'linkedin.account_inactive', 'linkedin.invalid_cookie'];
const SENT_AT_AS_GIVEN = 'sentAtUtc as Reply gives them, each null when it gives none; the CLI adds no time of its own';
const DIRECT_SENDS: [string, string, string[], string][] = [
['send-email', '--email-account-id', ['contact.not_found', 'email_account.not_found', 'contact.blacklisted'],
['send-email', '--email-account-id', ['contact.not_found', ...IMPORT, 'contact.already_held', 'email_account.not_found', 'contact.blacklisted'],
'sent_at is always null; the CLI adds none of its own'],
['linkedin-connect', '--linkedin-account-id', [...LINKEDIN, 'linkedin.not_connected', 'linkedin.limit_reached',
'linkedin.message_too_long', 'linkedin.missing_variables'], SENT_AT_AS_GIVEN],
Expand All @@ -143,16 +195,25 @@ describe('operations/commands', ()=>{
expect(text, text).not.toContain('connected or not');
});

it('each direct send takes ids by flag and its text only through --message -, and says a repeat may send it twice', ()=>{
it('each direct send takes the contact flags, the account by flag and its text only through --message -, and says a '
+ 'repeat may send it twice', ()=>{
for (const [name, account_flag, codes, sent_at] of DIRECT_SENDS)
{
const c = sub(contact_command, name);
expect(flags(c), name).toEqual(['--contact-id', account_flag, '--message']);
expect(flags(c), name).toEqual([...CONTACT_FLAGS, account_flag, '--message']);
const text = help_of(c);
const flat = text.replace(/\s+/g, ' ');
expect(text, text).toContain('--message -');
expect(flat, text).toContain('may send it twice');
expect(flat, text).toContain('may send it twice, unless the hint says nothing was sent');
expect(text, text).not.toContain('re-running is safe');
// A send given a person's fields sends only to a contact it creates, and names one Reply already holds.
expect(flat, text).toContain('A send given a person\'s fields sends only to a contact it creates');
expect(flat, text).toContain('a lookup finds a contact, or the import matches one Reply already holds, nothing is sent');
expect(flat, text).toContain(`then by its ${name === 'send-email' ? 'LinkedIn URL' : 'email'} when it was given one`);
expect(flat, text).toContain('imported only when Reply holds nobody under any address given');
expect(flat, text).toContain('the answer is contact.already_held (exit 1) with that contact\'s id in ids.contact_id');
expect(flat, text).toContain('send to it with --contact-id');
expect(flat.includes('--email alone is refused (usage.contact)'), text).toBe(name !== 'send-email');
expect(flat, text).toContain(sent_at);
expect(flat, text).toContain('read from stdin only');
// Exactly the codes its endpoint publishes, then the shared ones, as the help lists them.
Expand Down
Loading
Loading