Skip to content

feat: the direct sends and contact update find or import the person given by their fields - #29

Merged
ArtemKosolap merged 11 commits into
mainfrom
dev/REPLY-53117-sends-find-or-import
Oct 22, 2026
Merged

ArtemKosolap merged 11 commits into
mainfrom
dev/REPLY-53117-sends-find-or-import

Conversation

@ArtemKosolap

@ArtemKosolap ArtemKosolap commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

What changed

contact send-email, contact linkedin-connect, contact linkedin-message, contact linkedin-inmail,
contact linkedin-voice and contact update now take the same contact flags as sequence add-contact:
--contact-id, --email with its name flags, or --contact <json>|@file|-.

  • --contact-id works as before: one call, no lookup.
  • A person given by their fields is looked up, and imported only when Reply holds nobody:
    1. Reply's exact lookup. A send looks the person up by every address it was given, the one it reaches
      them at first (the email for send-email, the LinkedIn URL for the four LinkedIn sends) and then the
      other when the person has one. contact update looks up by the email, or by the LinkedIn URL when
      there is no email; unlike the add commands, which import a person given by email straight away.
    2. When Reply holds nobody under it, the person is imported exactly as the add commands import one:
      the same POST /v3/contacts/import call, keyed by the email when there is one and by the LinkedIn URL
      otherwise, carrying the first name the caller gave. Reply requires a first name on an import, so a
      person it does not hold yet needs one; contact update of a person it holds does not, because the
      lookup comes first.
    3. Then contact update makes its PATCH on the contact it found or imported. A send acts only on a
      contact it created (next point).
  • A 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 (so a contact held under the LinkedIn URL is refused for an email send too),
    or its import matches one Reply already holds (by the email, say, or a teammate's contact), nothing is
    sent: the answer is the new contact.already_held, exit 1, with that contact's id in ids.contact_id.
    Its hint says to read the contact (reply contact get <id>) and to send to it with --contact-id if it
    is the one to reach. If two different contacts are held, one under each address, the answer names the
    first one found, the one under the address the send reaches them at, and the second is not looked up.
    When the import creates the contact, the send goes to it. --contact-id is
    unchanged, and so is contact update, which acts on a contact it finds or the import matches: an update
    sends nothing.
  • A send given a person without the address it goes to (an email send without an email, a LinkedIn send
    without a LinkedIn URL) is refused before any call: usage.contact, exit 2.
  • The answer names the contact the command acted on, as the add commands do: contact_id and
    contact_created; 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. A failure after the contact was found or created carries its id in ids.
  • The same error rows as the add commands: contact.not_unique, contact.invalid_email,
    contact.invalid_linkedin_url, account.contact_limit_reached, and reply.refused for an item the
    import failed. Each is exit 1, and nothing is sent or changed.
  • A lost answer to a write (the import, the send, the PATCH) is exit 3 (outcome.unknown). When the
    import's answer is lost, the hint says nothing was sent and a re-run is safe; that re-run answers
    contact.already_held if the import did create the contact. When the send's answer is lost, the hint
    says a re-run may send it twice. A lost answer to a read (the lookup) is reply.unavailable, exit 1,
    nothing written.
  • Stdin. A person's text stays off the argument list. 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,
    {"contact": {...}, "message": {...}} or {"contact": {...}, "fields": {...}}, read once. When only
    one flag reads stdin, nothing changes. A malformed object is usage.stdin, exit 2, nothing repeated.
  • contact update keeps its id argument (contact update 456 is contact update --contact-id 456);
    the argument together with a contact flag is usage.contact. Custom field names are still checked
    before anything is written, and now before the contact is imported too. The fields that name the
    person only find or import them: the PATCH carries exactly what --fields names.
  • contact opt-out now goes through the same shared find-or-import function; its behaviour is unchanged.
  • --help of the six commands and the README describe all of the above.
  • A send never reads or changes a contact Reply already holds: it refuses it by name, as above.

Why

A send or an update to a person Reply did not hold yet needed a separate add command first, only to make
the contact exist. That was two commands for one act, two places where an answer could be lost, and a
list or sequence touched for no reason of its own. Now one command finds the person, creates them only
when Reply has nobody under the address, and acts.

A send is held to a contact it created because Reply does not refuse a direct send to a contact it holds
as opted out. The only guard on that opt-out is a caller that reads a contact Reply already holds before
sending to it, so a send given a person's fields never sends to such a contact on its own: it names it,
and the caller reads it and sends by id. A contact this command has just created was not held by Reply
before, so there is no opt-out on it to miss.

How it was verified

  • npm run build and npm test: 57 files, 853 passed, 5 skipped (824 passed before the change). The
    suite is offline; every test stubs fetch.
  • New tests in direct-send.test.ts, contact-record.test.ts, commands.test.ts and program.test.ts
    read each request and its body in order (lookup, import, act), and each asserts that the argument list
    carries none of the person's text. Three run the whole program from its argument list with the
    combined object on stdin.
  • For each of the five sends, given a person's fields: a contact held only under the other address it was
    given (the LinkedIn URL for send-email, the email for each LinkedIn send) is refused, with only the two
    lookups made; two contacts held, one under each address, name the first and ask only once; the lookup finds a contact (refused with
    contact.already_held, exit 1, the contact's id in ids, only the lookup made); the import matches one,
    answered updated or skipped (refused the same way, only the lookup and the import made); the import
    creates it (sent to it, after both lookups found nobody). contact update acts on a contact it found or the import matched, as its own
    tests assert.
  • Two mutants of the lookups, each red and then restored byte for byte: the second lookup skipped (5 tests
    red); a hit on the second lookup not refused (1 test red).
  • Four mutants of the refusal, each red and then restored byte for byte, with a clean tree after: the
    refusal skipped on a lookup hit; the refusal skipped on an import match; the refusal built but not
    thrown; contact update refusing a contact it found.
  • Seven mutants of the find-or-import path, each turned red by the new tests and then restored: the import skipped when the lookup finds nobody; the import made before the lookup;
    contact update importing before it checks custom field names; contact update writing the contact's
    address into the PATCH; the first name dropped from the import; a LinkedIn send looking the person up
    by email; a lost import answer hinted as a possible double send.

Two properties checked on purpose

  1. An import of a person named by a LinkedIn profile without an email. The code sends
    {"items":[{"linkedInUrl":…,"firstName":…}],"options":{"keys":{"linkedInUrl":true}}} when there is no
    email, the same path sequence add-contact already uses for such a person. Reply's published
    reference for POST /v3/contacts/import agrees: only firstName is required per item and the other
    fields are optional, skipWithoutEmails defaults to false, keys.linkedInUrl makes the LinkedIn URL
    a deduplication key, and the per-item "Invalid data" error names a missing firstName or a
    malformed email, not a missing email. This PR does not exercise it against a live account.
  2. contact update never changes the address of a contact Reply holds. Tests give the person with an
    email and a different LinkedIn URL and assert that the PATCH body is exactly the --fields object,
    in a unit test and through the whole program; a linkedin_url changes only when --fields names one.
    The mutant that copies the person's address into the PATCH turns four tests red.

The five direct sends took only --contact-id, so a send to someone Reply did
not hold yet needed an add command first. They now take the contact flags the
add commands take. A person given by their fields is looked up by the address
the send reaches them at (the email for send-email, the LinkedIn URL for the
four LinkedIn sends) and imported, as the add commands import one, only when
Reply holds nobody under it. The answer names the contact the send went to and
says whether the command created it.

When --contact - and --message - both read stdin, it holds one object,
{"contact": {...}, "message": {...}}, so neither the person nor the text ever
sits in the argument list. A lost answer to the import says nothing was sent.
contact update took only a contact id, so changing the fields of someone Reply
did not hold yet needed an add command first. It now also takes the contact
flags the add commands take. A person given by their fields is looked up as
the add commands look one up and imported only when Reply holds nobody under
the address; the id argument keeps working and counts as one of the ways.

The fields that name the person only find or import them: on a contact Reply
holds, the PATCH carries exactly what --fields names, never the address the
contact was found by. Custom fields are read before the person is found or
imported, so an unknown name still changes nothing. With --contact - and
--fields - both, stdin holds one object, {"contact": {...}, "fields": {...}}.
…er from the argument list

A send to a person Reply does not hold and an update of one it holds, run as
reply runs them: the argument list carries no personal data, the requests
carry the person and the text, and the update's PATCH carries only its fields.
… person

The table names the sends and contact update by <contact>, the paragraph on
imports says which commands look first, by which address a send looks, and
that each answers the contact id it acted on; a new paragraph shows stdin
holding the person and the text together.
…s given

When the person is given by fields and nobody is found by the LinkedIn URL, the import
is matched by the email and may return a contact Reply already holds. That contact is
now read before the send: a different LinkedIn profile refuses the send with
contact.channel_conflict (exit 1, nothing sent or changed, the contact in ids); an empty
one is given the profile, and only that field, before the send; the same profile
(compared ignoring the scheme and www) goes ahead. A contact found by the URL or created
by the import is not read. The hint after a lost answer to any step before the send
says the send was never made.
… the import matched

--help of the four LinkedIn sends and the README state the contact.channel_conflict
refusal, the profile set on a contact that holds none, and that --email alone is refused;
the exit 3 line says "unless the hint says nothing was sent"; the name flags of the
commands that look a contact up first say they are used only if it is imported; the
README no longer implies sequence remove-contact answers contact_created.
The import runs before the read, so it may already have filled the held
contact's empty fields. The refusal now says nothing is sent and the
contact's LinkedIn profile is not changed, names the contact as one Reply
already holds, and adds "if it is a different person" to the hint.
@ArtemKosolap

Copy link
Copy Markdown
Contributor Author

Approved at ca8a237 — first reader.

Read: the body, the find-or-import path in contacts.ts and direct-send.ts, the fix that refuses a LinkedIn send when the contact an import matched carries another LinkedIn profile (contact.channel_conflict), and the wording commit. CI green at ca8a237 (ci, commitlint).

@ArtemKosolap

Copy link
Copy Markdown
Contributor Author

Approved at ca8a237 — second reader, independent.

The first read at 2bb812c asked for one change: a LinkedIn send given an email as well could reach a contact Reply holds under that email with a different LinkedIn profile, and report success. At b9c4bca the contact an import matched is read before the send: another profile is refused (contact.channel_conflict, exit 1, the contact id in ids, nothing sent), an empty profile is given the LinkedIn URL alone, a contact found by the URL or created by the import is not read. Ten mutants against the fix were caught; 854 tests pass, 5 skipped. The find-then-import-then-act order, the error rows and exit codes match the add commands; contact update's PATCH carries only --fields; contact opt-out is unchanged; the combined stdin object is read once and the single-flag cases are unchanged. The wording commit ca8a237 makes the refusal's text say exactly what it leaves untouched.

@ArtemKosolap
ArtemKosolap marked this pull request as ready for review October 22, 2026 02:09
@ArtemKosolap
ArtemKosolap marked this pull request as draft October 22, 2026 03:34
auto-merge was automatically disabled October 22, 2026 03:34

Pull request was converted to draft

Reply does not refuse a direct send to a contact it holds as opted out, so the only guard on
that opt-out is a caller that reads the contact before it sends. Given a person's fields, the
five sends now act only on a contact the command created: when the lookup finds a contact, or
the import matches one Reply already holds, nothing is sent and the answer is the new
contact.already_held (exit 1), with the contact in ids.contact_id and a hint to read it and
send with --contact-id. contact update and --contact-id are unchanged.

A matched contact is now refused before anything else, so the read of an import-matched
contact before a LinkedIn send (contact.channel_conflict, and the PATCH of an empty LinkedIn
URL) could no longer be reached; it is removed with its tests. The hint after a lost import
answer says a re-run answers contact.already_held if that import did create the contact.
…contact it creates

The paragraph on the LinkedIn profile check gives way to the rule: a direct send given a
person's fields refuses a contact Reply already holds with contact.already_held, naming it, so
the caller reads it and sends with --contact-id. The note on exit 3 names the import as the only
step before a send whose answer can be lost.
…ess it was given

A send looked the person up only by the address it reaches them at, so a
contact Reply held under the other address (the LinkedIn URL for an email
send, the email for a LinkedIn send) was neither read nor refused, and a
second contact was created beside it.

The lookups now run in a fixed order, the address the send reaches them at
first and the other when it was given. A hit under either is refused with
contact.already_held naming the first contact found, and nothing is
imported or sent.

The help of the five sends and the README say so, and say that
contact_created is kept on a send for consistency with the add commands
and is always true when something was sent.
…t's unused channel

contact_created is always true when a send was given a person's fields and always false
with --contact-id; in both cases a successful answer says the send was made. The help, the
README and the test that pins the sentence now say so. find_or_import no longer takes a
channel, since the sends look a person up themselves.
@ArtemKosolap

Copy link
Copy Markdown
Contributor Author

Approved at cabd40a — first reader (supersedes the approval at ca8a237).

Read the rounds after ca8a237: a send given a person's fields now acts only on a contact it creates. It looks the person up by every address given, the one the send reaches first; any hit, or an import that lands on a contact Reply already held, is refused with contact.already_held naming that contact, and nothing is sent. Reply does not refuse a direct send to a contact it holds as opted out, so a caller that reads a held contact before sending to it by --contact-id keeps that stop. The earlier read-and-patch path for a matched contact is removed rather than left unreachable; contact update and --contact-id are unchanged; the lost-import hint is truthful. CI green at cabd40a.

@ArtemKosolap

Copy link
Copy Markdown
Contributor Author

Approved at cabd40a — second reader, independent (supersedes the approval at ca8a237).

Since ca8a237: the refusal holds before any send on both paths (a lookup hit; an import that matched) for all five sends, by every address given; created → sent; contact update, contact opt-out and --contact-id sends unchanged; contact_created documented exactly (always true for a person given by their fields, always false with --contact-id, success meaning the send was made); no dead code left. 853 tests pass, 5 skipped; the mutants of each round were caught. Hygiene clean.

@ArtemKosolap
ArtemKosolap marked this pull request as ready for review October 22, 2026 04:03
@ArtemKosolap
ArtemKosolap disabled auto-merge October 22, 2026 04:07
@ArtemKosolap
ArtemKosolap merged commit aee6f14 into main Oct 22, 2026
6 checks passed
@ArtemKosolap
ArtemKosolap deleted the dev/REPLY-53117-sends-find-or-import branch October 22, 2026 04:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant