Skip to content

feat: sends for later, direct-send get and cancel, and the inbox changes feed - #31

Merged
ArtemKosolap merged 24 commits into
mainfrom
dev/REPLY-53114-deferred-sends-and-events
Oct 29, 2026
Merged

ArtemKosolap merged 24 commits into
mainfrom
dev/REPLY-53114-deferred-sends-and-events

Conversation

@ArtemKosolap

@ArtemKosolap ArtemKosolap commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

What changed

  • Every direct send (contact send-email, linkedin-connect, linkedin-message, linkedin-inmail, linkedin-voice) takes three new flags:
    • --send-after <moment> goes in the body as sendAfter, normalised to UTC. A moment without its offset is refused as usage.date (exit 2).
    • --schedule-id <id> goes in the body as scheduleId.
    • --idempotency-key <key> goes as the Idempotency-Key header, never in the body. A key must be 1 to 255 printable ASCII characters, a space inside included; a space at either end is refused (usage.idempotency_key), since a header value loses it on the way out and the key would reach Reply as another key.
  • The send's answer keeps status: "sent" with its meaning today: Reply took the send. It adds reference, send_after and state only when Reply gives them, so an answer from a Reply without these fields is printed as before.
  • A refused key has a code of its own: idempotency_key.in_use (an earlier send under the key is still being made) and idempotency_key.reused (the key was taken for a different send). Each is listed in the sends' --help, after each send's own codes. idempotency_key.reused names the send the key was first taken for under the error's details: reference, state and send_after, each only when Reply gives it as a string. Every other refusal of a direct send names the send the same way when Reply gives these fields (Reply answers an email that fails after its row exists with them, and replays that answer under the key): they sit beside the refusal's own details, such as missing_variables, and the refusal's code and class are unchanged. Without them there is no details. A repeat of a send given a person's fields (--contact -) answers contact.already_held first, since the first one created the contact; the help and the README say so.
  • contact send-email also:
    • takes --track-links and --track-opens, sent as trackLinks and trackOpens only when given, since Reply tracks neither unless asked;
    • adds rendered_subject and rendered_body to its answer when Reply sent the email within the request and gives them;
    • maps contact.missingVariables (400) to contact.missing_variables, with the names under the error's details.missing_variables when Reply lists them, and contact.renderingFailed (400) to contact.rendering_failed, with Reply's message as the detail. Both codes are read only from this command's answer; a LinkedIn send answering either maps as it does today.
  • direct-send get <reference> (GET /v3/direct-sends/{reference}) and direct-send cancel <reference> (POST /v3/direct-sends/{reference}/cancel) are new.
    • Both answer the send as {reference, channel, contact_id, state, send_after, sent_at, message_id, failure_reason, cancelled_at}, each null when Reply gives none. failure_code, missing_variables, rendered_subject and rendered_body (Reply's failureCode, missingVariables, renderedSubject, renderedBody) are added only when Reply gives them, so an answer without them prints exactly as before. failure_reason is a sentence for a person and never parsed; failure_code is Reply's code for the failure. missing_variables is printed only as a list of names.
    • The reference's form is checked against Reply's route, email-<n> or linkedin-<n> (n from 1, at most ten digits), and nothing else is read from it. A reference of any other form is refused as usage.reference (exit 2) before any call, with a message that names the form and does not repeat the input. Reply answers a reference outside that form with a bare 404, as it does when it has no such route, so the check keeps a bare 404 on these commands meaning only that this Reply has no such route. state is passed on as Reply gives it.
    • Reply's refusals map to direct_send.not_found, direct_send.not_owned, direct_send.already_sent and direct_send.already_failed.
    • A cancel of a send already cancelled is a success. A cancel whose answer was lost is outcome.unknown (exit 3), and its hint says running it again is safe.
  • inbox changes [--cursor <c> | --since <moment>] [--top <n>] (GET /v3/inbox/threads/changes) is new. It names the threads that changed, one item per thread.
    • It prints one page as {items, has_more, cursor}, with the items as Reply gives them, as inbox list does.
    • --cursor together with --since is a usage error. With neither, Reply reads the last 30 days.
    • --since is sent in UTC and not shifted, since Reply's since is already inclusive.
    • An empty page keeps the cursor Reply gives with it.
    • A cursor or a --since older than the 30 days the feed keeps is refused with Reply's code inboxThread.changeWindowExpired (400). It becomes inbox.cursor_expired, and its hint says to start again with --since.
    • Reply refuses any other cursor it will not read (unreadable, or ahead of its clock) with a 400 that has no code and an errors[] entry pointing at /cursor. When a cursor was sent, that answer becomes inbox.cursor_refused, with the same hint. Every other refusal of the feed maps as it does today.
  • On the send call of the five direct sends, a 400 whose JSON or problem+json body carries neither a code nor an errors[] is how Reply answers an exception escaping the send, which may already be made. It is now outcome.unknown (exit 3), with the same hint as a 5xx: a repeat may send it twice. A 400 with errors[] stays reply.invalid_request, a 400 page that is not JSON maps as before, and the import call of a send given a person's fields keeps its mapping.
  • On every new command, a 404 with no code of Reply's own (an empty body, problem+json without a code, or an HTML or plain-text page) stays reply.refused with status 404 and no reply_code. That is how a Reply that does not have the route yet answers. Every other answer maps as it does today.
  • The README's command table and a new section describe the flags, what status and state each mean, the rendered text and the two template refusals, the two direct-send commands and inbox changes. Each new command's --help lists its result, its codes and its exit codes.

Why

An agent sending outside a sequence could only send at once, and had no way to see later whether a send had gone out or to take one back. A send held for later needs three things: a moment, a schedule to time it by, and a key, so that a repeat does not send twice wherever Reply honours the key. It also needs a reference to follow up with. Following the inbox meant re-listing threads and comparing them, and a cursor feed replaces that.

status: "sent" keeps its meaning, so existing callers read the same answer as before. state is the field that says whether a send has gone out (queued or sending means not yet). The key does not make a send safe to repeat after exit 3: a Reply that does not know the header yet would make the send again, so the hint on a lost send is unchanged.

Each Reply code a new CLI code maps from appears in one table, beside the CLI code, with the status Reply publishes it under. A code that arrives under any other status falls through to the usual mapping.

How it was verified

  • npm run build && npm test was run on each commit. Before: 862 passed, 5 skipped. After: 924 passed, 5 skipped.
  • Each behaviour's test was written first and seen failing. A missing function or module, a missing key in a strict-equal, or a list of 7 flags against an expected 10 all failed before the code that makes them pass.
  • These mutations were run against the committed code, and a test failed for each one:
    • the bare 404 mapped to another code
    • the later-keys filter dropped
    • the reference's form loosened in any of eight ways: a leading zero, an eleventh digit, either anchor dropped, a third channel, any word character after the dash, the case ignored, the end anchor matched before a line break
    • the direct-send table skipped on a cancel
    • the page's cursor check removed
    • the reused key's details given when empty, or with fields that are not strings
    • either template refusal matched under another status, or the missing names dropped when absent
    • either tracking flag sent without being asked, or one sent for the other
    • the rendered keys dropped from the send's answer, or the details not passed to the error
    • missing_variables passed through unchecked, or failure_code dropped, in the projection
    • the expired window matched under any status, or on any 400
    • the code-less cursor refusal mapped generically, matched without a cursor sent, or given another hint
    • the four new fields of a direct send added in any shape, without their null, or not at all
    • the list-of-names check widened to any array
    • the send's reference, state and send_after given only on a reused key
    • the exception 400 matched without the errors[] check
    • a text body read as Reply's code on a 404
  • The bare-404 rows of the sends, of direct-send get and cancel, and of the feed include an HTML page and a plain-text body, each asserting reply.refused, status 404 and no reply_code.
  • direct-send get and cancel send email-1, linkedin-42, email-9999999999 and email-1001 as given, and refuse before any call, as usage.reference (exit 2) naming the form: email-0, email-01, email-12345678901 (eleven digits), sms-1, email-, email-1a, email-1, email-1 , EMAIL-1, email--1, linkedin, ., .., a.b, ..., .a, .., a/b c?d, ds_8F2k, email-1/cancel and email-1 followed by a line break.
  • A refusal of contact.missingVariables without a list of names carries no details, and a LinkedIn send answering either template code is reply.refused with Reply's code kept.
  • Refused sends with reference, state and send_after: an email's contact.rendering_failed with all three, one with only reference, a non-string state dropped, LinkedIn refusals (a known code and one mapped generically), contact.missing_variables with its names beside the three, a LinkedIn limit beside its limit, and refusals without them carrying no details. The reused rows are unchanged.
  • A 500 on each of the five sends is outcome.unknown (exit 3), made once, with the hint that a repeat may send it twice.
  • A 400 with neither a code nor errors[], as problem+json and as plain JSON, is outcome.unknown (exit 3, one call, the repeat hint) on each of the five sends; with errors[] (empty included) it is reply.invalid_request; an HTML, plain-text or empty 400 is reply.refused; the same 400 to the import of a send given a person's fields is reply.refused and nothing is sent.
  • An Idempotency-Key with a space at either end was checked on Node: the header value comes back trimmed.
  • The program-level tests run the commands through commander and the top-level error handler, and check exit codes 1 and 2.
  • Every test stubs fetch and uses a scratch configuration directory. No call reaches Reply.

…ency-key

A caller that times its own sends needs Reply to hold a send until a
moment, within a schedule, and to tell a repeat of a send from a new
one. Each flag is sent only when given: the moment as sendAfter in UTC,
the schedule as scheduleId, the key as the Idempotency-Key header and
never in the body. A moment without its offset is refused, since the
CLI would have to choose a zone for it.

The answer adds Reply's reference, sendAfter and state, each only when
Reply gives it, so an answer without them prints what it printed
before. status keeps its meaning, that Reply took the send; state says
whether it has gone out. A key does not relax the hint after a lost
answer: a Reply that ignores the header would send twice.
A send route refuses a key two ways: Reply is still making an earlier
send with that key, or the key was used for a different send. Both are
409s under the route's own family, contact for the email and
directLinkedIn for the LinkedIn sends, and neither sent anything, so a
caller needs to tell them from a refusal of the send itself. They are
idempotency_key.in_use and idempotency_key.reused, read only under 409
and only in the route's own family; every other answer maps as before.

The codes sit in one table with the CLI code each maps to.
…e for later

A send made with --send-after answers a reference, and until now nothing could follow it: an
agent that scheduled a message could neither see whether it went out nor take it back.
direct-send get reads GET /v3/direct-sends/{reference} and direct-send cancel posts to its
/cancel route. The reference is Reply's and is passed on encoded into the path, never parsed.
A cancel of a send already cancelled is a success, so a cancel whose answer was lost says that
running it again is safe. Reply's directSend codes get CLI codes of their own; a bare 404 from
a Reply without the route stays reply.refused.
Following the inbox meant re-listing it and diffing threads. inbox events reads GET
/v3/inbox/events one page at a time: --cursor goes on from the cursor a previous page answered,
--since starts at a moment given with its offset and sent in UTC, and with neither Reply reads the
last 30 days. The page is {items, has_more, cursor} with the items as Reply gives them, and an
empty page keeps its cursor. Reply answers a cursor it will not read as a validation problem that
points at /cursor, so that answer is inbox.cursor_refused, whose hint says to start again with
--since.
…x feed

The command table gains the three send flags, direct-send get and cancel, and inbox events. A
section says what status "sent" and state each mean, so a caller does not read a queued send as
one that has gone out, how the idempotency key is sent and refused, and how the feed is read
forward by cursor. The note on re-running after exit 3 now says a key does not make a send safe
to repeat, since a Reply that does not know the header would send again.
… call carries

The comment named the headers by the object that holds them; it now says what they are.
The comment pointed at a pull request outside this repository; it now names the document itself.
…d not fill and a reused send

Reply now answers an email sent within the request with its subject and body as it filled them
in, and the CLI passes them on as rendered_subject and rendered_body when Reply gives them; a send
held for later has neither. A template variable Reply could not fill is contact.missing_variables,
with the names under details.missing_variables, and a template Reply could not render is
contact.rendering_failed with Reply's message as the detail. Neither sent anything.

idempotency_key.reused may name the send the key was first taken for: reference, state and
send_after go under details, each only when Reply gives it as a string, so a caller that built a
repeat differently still learns which send holds the key.

The handler sends trackLinks and trackOpens only when asked to track: Reply tracks neither
unless asked, so a send without them is the request it always was. The flags follow.
…lled variables and the text

Reply's model of a direct send now carries failureCode, missingVariables, renderedSubject and
renderedBody. They are printed as failure_code, missing_variables, rendered_subject and
rendered_body, each null when Reply gives none, as the other fields are. failure_reason stays a
sentence for a person and is never read; failure_code is the one a caller branches on.
missing_variables is printed only as a list of names, and as null for anything else.
…inbox.cursor_expired

Reply now refuses a cursor or a since older than the 30 days the feed keeps under a code of its
own, inboxThread.eventWindowExpired, a 400 business problem. It maps to inbox.cursor_expired with
Reply's detail and a hint to start again with --since, in one matcher that asks for both the
status and the code. Every other refusal of the feed, an unreadable cursor included, is a
validation problem without a code and maps as everywhere else, to reply.invalid_request with the
field in details.fields, so the guess at the cursor's pointer that stood in for a code is gone.
…names the new answers

send-email gains --track-links and --track-opens. Each is off unless given, as Reply tracks
neither unless asked. Its help lists contact.missing_variables and contact.rendering_failed, says
the unfilled names go under details.missing_variables, and says an email sent within the request
adds rendered_subject and rendered_body. Every direct send's help says idempotency_key.reused names
the send the key was first taken for under details. direct-send get and cancel list their new
fields and say failure_reason is never parsed. inbox events lists inbox.cursor_expired in place of
the earlier cursor code.
…ables and the expired feed

The direct sends section now says send-email tracks nothing unless --track-links or --track-opens
asks it to, that an email sent within the request adds rendered_subject and rendered_body, where
contact.missing_variables puts the names, and what contact.rendering_failed carries. It says what
idempotency_key.reused names under details and which keys are taken. direct-send get and cancel
list every field they answer, and inbox events names inbox.cursor_expired for a cursor or a since
past the feed's 30 days.
…not read, beside the window

Reply publishes a cursor it will not read, unreadable or ahead of its clock, as a validation
problem with no code that points at /cursor. That form is again inbox.cursor_refused, with the
field in details.fields, when a cursor was sent. The window's own code, eventWindowExpired, is
still inbox.cursor_expired and is matched first. Both give the same hint, to start again with
--since, from one constant, and both are listed in inbox events --help and the README.
…nd unfilled names when given

An answer from a Reply without failureCode, missingVariables, renderedSubject and renderedBody now
prints exactly as it did before them, instead of carrying four new nulls. Each is added when
Reply gives it: failure_code, rendered_subject and rendered_body as text or null, and
missing_variables as a list of names or null. A value of any other shape is left out. The fields
that were there before keep printing null when Reply leaves them out.
… any call

Encoding leaves a dot as it is, and the URL parser reads a path segment of . or .. as a step up
the path, so cancel .. would reach another route. Both are refused as usage.reference (exit 2);
every other reference is still sent as given.
…th no reply code

A proxy in front of Reply can answer a route it does not know with a page that is not JSON. The
sends, direct-send get and cancel, and the inbox feed each now hold that such a 404 is
reply.refused with status 404 and no reply_code, as an empty one and a problem without a code are.
…no list

A refusal without Reply's list printed an empty one, which reads as Reply having said no variable
was missing. The key is now left out, as the reused key's fields and the read of a send leave out
what Reply does not give.
contact.missingVariables and contact.renderingFailed sat in the table all five sends share, so a
LinkedIn send answering either would have been named an email's refusal. They now sit in a table
kept per channel, as the idempotency key's codes do, and a LinkedIn send falls to the usual mapping.
…ady_held first

The help and the README said a repeat with the same key answers with the send the key first made.
A send given a person's fields finds the contact the first one created before the key is read, so
its repeat answers contact.already_held, which is safe as well: nothing is sent twice.
…threads/changes

The feed names which threads changed, not what happened in them, so Reply names the route
threads/changes and its window code inboxThread.changeWindowExpired. The command follows as inbox
changes, with the same flags, the same page and the same two CLI codes. Nothing has shipped under
the old name, so there is no alias.
…a reused key

Reply now answers an email that fails after its row exists with its refusal plus reference, state
and sendAfter, and replays that answer under the key. Each one given as a string goes under the
error's details, beside the refusal's own such as missing_variables, through one helper for all
five sends. The refusal's code and class are unchanged, and without the fields there is no details.
…once

Reply answers 500 for an exception escaping a send, on the LinkedIn routes as on the email one.
No row held that for a 500 itself, so the answers that may hide a send now include it, on every
send: exit 3, one call, and the hint that a repeat may send it twice.
…ome.unknown

Reply answers an exception escaping a send, on the LinkedIn routes as well, with a 400 whose body
carries no code and no errors[], and the send may already be made. It is now outcome.unknown (exit
3) with the hint that a repeat may send twice, on the send call only. A 400 with errors[], a page
that is not JSON, and the import call of a send given a person's fields map as before.
… of Reply's route

Reply's route takes a reference only as email-<n> or linkedin-<n>, n from 1 and at most ten
digits, and answers any other with a bare 404, the answer of a Reply without the route at all.
Both commands now check that form before any call and refuse anything else as usage.reference
(exit 2), with a message that names the form and does not repeat the input. A bare 404 on these
commands therefore always means the route is absent. The rule refusing . and .. is gone, since
neither has the form; nothing else is read from the reference, and the form leaves nothing to
encode. The help and the README state the form and what the bare 404 then means.
@ArtemKosolap
ArtemKosolap merged commit 7aad87c into main Oct 29, 2026
6 checks passed
@ArtemKosolap
ArtemKosolap deleted the dev/REPLY-53114-deferred-sends-and-events branch October 29, 2026 01:22
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