Skip to content

feat: the direct sends follow, steer and explain a send timed by a sending schedule - #34

Merged
ArtemKosolap merged 15 commits into
mainfrom
fix/linkedin-scheduled-reference
Oct 31, 2026
Merged

ArtemKosolap merged 15 commits into
mainfrom
fix/linkedin-scheduled-reference

Conversation

@ArtemKosolap

@ArtemKosolap ArtemKosolap commented Oct 31, 2026 •

Copy link
Copy Markdown
Contributor

What

The direct sends now cover everything Reply's API answers for a send timed by a sending schedule, LinkedIn or email:

  1. direct-send get and direct-send cancel accept linkedin-scheduled-<n>, the reference of a LinkedIn send held for later.
  2. The send's answer and direct-send get/cancel pass on estimated_send_at.
  3. The waitingForSchedule state and a failed send without a failure code are read and documented.
  4. direct-send cancel maps direct_send.already_sending and direct_send.cancel_not_confirmed.
  5. Every direct send takes --use-contact-time-zone / --no-use-contact-time-zone, and the four LinkedIn sends also take --retry-window-minutes <n>.
  6. All five direct sends map Reply's three refusals of a send it cannot time to schedule.not_found, schedule.no_slot and contact.time_zone_missing, whichever route gave them.

Why

Reply sends a LinkedIn message, invitation, InMail or voice message later in two ways: at a moment (sendAfter) or at the next opening of a sending schedule (scheduleId). The scheduled path gives the send new references, states, fields and refusals. Before this change the CLI refused the new reference before making any call. It also dropped the new fields and could not ask for the new options. And it reported the new refusals as the generic reply.refused, or as outcome.unknown for the 503 on a cancel. So a caller could make a scheduled LinkedIn send through the CLI but could not follow it, steer it or tell its refusals apart.

Changes

References. Reply gives a LinkedIn send held for later the reference linkedin-scheduled-<n>, and it keeps that reference for the whole life of the send. A LinkedIn send that goes out at once keeps linkedin-<n>. The local check is now /^(email|linkedin|linkedin-scheduled)-[1-9]\d{0,9}$/. The new form follows the same one-spelling rule as the other two: n starts at 1, has no leading zero and has at most ten digits. Any other form is still refused before a call (usage.reference, exit 2), so a bare 404 still means only that this Reply has no such route.

estimated_send_at. A send timed by a schedule, email or LinkedIn, can wait for its schedule's next opening. Reply then answers it with state waitingForSchedule, no sendAfter, and estimatedSendAt. That field is when Reply expects to send it, a UTC moment Reply sends within about 10 minutes of. Reply sets it in waitingForSchedule only and gives it null in every other state; it is null in waitingForSchedule too when the schedule does not open within 30 days of the moment the send waits from (the requested sendAfter, or the acceptance; on a read, now once sendAfter has passed). The send's answer and direct-send get/cancel pass it on as estimated_send_at, as text or null exactly as Reply gives it. The field is left out when Reply gives neither, so an answer from a Reply without the field prints as it did before.

States and failure codes. direct-send get already passed on any state that is a non-empty string, and gave failure_code as text or null. A new test holds that for every state the scheduler gives (queued, waitingForSchedule, sending, sent, failed, cancelled). It also covers a failed send with a null failure code and the failure codes Reply names (directLinkedIn.*, directSend.dispatchWindowMissed, directSend.dispatchInterrupted), including directLinkedIn.contactNotFound and a code the CLI does not know yet: any failure code passes through as Reply gives it. The help and the README now list waitingForSchedule among the states not yet sent. They also say that a failed send may carry no failure_code.

Cancel.

  • A 409 directSend.alreadySending is direct_send.already_sending, beside direct_send.already_sent and direct_send.already_failed. Reply answers it for a LinkedIn send made for later that it is handing to the account's queue, or that waits or runs there, even while a read still says queued.
  • A send of another team is direct_send.not_found, to a read and a cancel alike; direct_send.not_owned (403) is only an email send made by a teammate the user may not act for. The help and README now say so.
  • A 503 directSend.cancelNotConfirmed means Reply could not confirm the cancel, and the send is still queued or waitingForSchedule; Reply asks for the cancel again. It is now direct_send.cancel_not_confirmed (exit 1), with a hint to run the cancel again, and Reply's Retry-After in retry_after when Reply sends one (Reply does not promise the header on this answer). Before, it ended as outcome.unknown (exit 3) like any 5xx to a write. Only that code under 503 on a cancel is read this way. Any other 5xx to a cancel stays outcome.unknown, and a read that answers the code maps like any other 5xx.

Flags. The time-zone pair goes on all five direct sends (send-email, linkedin-connect, linkedin-message, linkedin-inmail, linkedin-voice); the retry window on the four LinkedIn sends only.

  • --use-contact-time-zone sends useContactTimeZone: true, so Reply reads the schedule's windows in the contact's time zone. --no-use-contact-time-zone sends false, the schedule's own zone. With neither flag nothing is sent, so the schedule's own setting holds.
  • --retry-window-minutes <n> sends retryWindowMinutes: how long Reply keeps trying once the send is due, 1 to 4320 minutes (Reply's default is 90). A number outside that range is refused before any call (usage.range), as the CLI does for its other numeric flags.
  • Each flag goes to Reply only when it is given. The rules between fields are left to Reply: the retry window only with a deferral, the time zone only with --schedule-id. Reply answers a broken rule with errors[], which the CLI reports as reply.invalid_request.
  • contact send-email does not take --retry-window-minutes: Reply's email route has no retry window.

Refusals when a send is taken. These are now mapped instead of the generic reply.refused. The email route and the LinkedIn routes name each in their own family, and both map to the code of its meaning, so a caller branches on the meaning rather than on the channel; reply_code keeps the code Reply gave. Each is definite, so nothing was sent, and each is read only under the status Reply gives it with:

  • 404 directLinkedIn.scheduleNotFound or contact.scheduleNotFound → schedule.not_found: the id names no schedule this account can read
  • 409 directLinkedIn.scheduleHasNoSlot or contact.scheduleHasNoSlot → schedule.no_slot: the schedule has no active day with a time range, so it never opens
  • 409 directLinkedIn.contactTimeZoneMissing or contact.contactTimeZoneMissing → contact.time_zone_missing: --use-contact-time-zone asks for a time zone the contact does not have

Each change comes with its help text and README section.

Verification

  • Every behaviour has a vitest test in src/__tests__/operations/ (direct-send.test.ts, direct-sends.test.ts, commands.test.ts). Each test was seen failing before its change, except the ones that passed at once because the behaviour already held: the state-reading test and its failure-code rows, which pass any code through as Reply gives it.
  • The help assertions in commands.test.ts pin the new flags, codes and wording.
  • With commander, the flag pair gives useContactTimeZone as true, false or absent. This was checked by parsing each of the three argument lists.
  • npm run build (tsc): clean.
  • npm test (vitest): 60 files, 942 passed, 5 skipped, 0 failed.
  • The repository has no lint script. commitlint ran on every commit through the husky hook.

Release

The branch carries feat: commits, so semantic-release publishes a minor release, 0.18.0, once this is merged with its commits. All the new output is additive: one optional field, new error codes and new optional flags.

…rred LinkedIn send's reference

Reply gives a LinkedIn send held for later the reference linkedin-scheduled-<n> for its whole
life; one sent at once keeps linkedin-<n>. The local check refused the new form with
usage.reference before any call, so a deferred LinkedIn send made through the CLI could not be
read or cancelled through it. The form takes the same one-spelling rule as the other two: n from
1, no leading zero, at most ten digits. The refusal message, the help of both commands and the
README name the third form.
@ArtemKosolap
ArtemKosolap marked this pull request as ready for review October 31, 2026 01:42
…ng for its schedule

A LinkedIn send timed by a sending schedule can wait for the schedule's next opening. Reply then
answers it with state waitingForSchedule, no sendAfter, and estimatedSendAt: when it expects to
send it, or null when no opening falls within the 30 days it looks ahead. The send's answer and
direct-send get and cancel now pass it on as estimated_send_at, text or null as Reply gives it,
and leave it out when Reply gives neither, so an answer from a Reply without the field prints as
it did. The help of the four LinkedIn sends and of direct-send, and the README, say so.
…hout a failure code

Reply's LinkedIn scheduler adds the state waitingForSchedule, and a failed send may come with a
null failureCode. direct-send get already passes both on: any state that is a non-empty string is
read, and failure_code is given as text or null. A test now holds that over every state the
scheduler gives and over the failure codes it names, and the help and the README list the new
state among those not yet sent and say what a failure without a code means.
…l Reply could not confirm

Reply refuses to cancel a send it is already sending with a 409 directSend.alreadySending; it is
now direct_send.already_sending, beside direct_send.already_sent and direct_send.already_failed.

A 503 directSend.cancelNotConfirmed is Reply saying it could not confirm the cancel: it may not
have taken, and repeating it is safe. It is now direct_send.cancel_not_confirmed (exit 1), with a
hint that running it again is safe and Reply's Retry-After in retry_after when it sends one,
instead of the outcome.unknown (exit 3) any 5xx to a write ends in. Only that code under 503 on a
cancel is read so: any other 5xx to a cancel stays outcome.unknown, and a read answering the code
maps as any other 5xx. The help of direct-send cancel and the README say so.
…y-window-minutes

Reply's LinkedIn sends timed by a schedule take useContactTimeZone: true reads the schedule's
windows in the contact's time zone, false in the schedule's own, and without it the schedule's
own setting holds. They also take retryWindowMinutes, how long Reply keeps trying once the send is
due, 1 to 4320 minutes with a default of 90.

The four LinkedIn sends now take --use-contact-time-zone and --no-use-contact-time-zone, so each
of the three cases can be asked for, and --retry-window-minutes <n>. Each goes to Reply only when
given. A retry window outside 1 to 4320 is refused before any call (usage.range), as the CLI
checks its other numbers; which other flag each needs is left to Reply, which answers with
errors[] (reply.invalid_request). contact send-email takes neither. The help of the four sends
and the README say so.
…ot time

When Reply takes a LinkedIn send timed by a schedule it may refuse it before anything is held:
a 404 directLinkedIn.scheduleNotFound for a schedule it has no record of, a 409
directLinkedIn.scheduleHasNoSlot for a schedule with no window it can send in, and a 409
directLinkedIn.contactTimeZoneMissing for a contact without the time zone the schedule is to be
read in. They are now schedule.not_found, schedule.no_slot and contact.time_zone_missing, each
definite and read only under the status Reply gives it, instead of the generic reply.refused. The
help of the four LinkedIn sends lists them, and the README says what each means.
…ing and asks to cancel again

Reply documents its 503 directSend.cancelNotConfirmed as a cancel it could not confirm while the
send is still queued or waiting for its schedule, and asks for the cancel again. The refusal's
title, hint, help and README said the cancel may or may not have taken; they now say what Reply
says.
…sals as Reply documents them

- schedule.not_found is a schedule id naming no schedule this account can read, and
  schedule.no_slot a schedule with no active day that has a time range, so it never opens.
- direct_send.not_found covers a send of another team; direct_send.not_owned is only an email
  send made by a teammate this user may not act for.
- direct_send.already_sending is a LinkedIn send made for later that Reply is handing to the
  account's queue or that waits or runs there, even while a read still says queued.

A read passes any failure code Reply gives through as failure_code; rows for the scheduler's
codes and for a code the CLI does not know yet hold that.
@ArtemKosolap ArtemKosolap changed the title fix: direct-send get and cancel accept linkedin-scheduled-<n>, a deferred LinkedIn send's reference feat: direct sends carry Reply's LinkedIn scheduler: linkedin-scheduled references, estimated_send_at, the new cancel and schedule refusals, and the time-zone and retry-window flags Oct 31, 2026
…aits from

Reply leaves estimatedSendAt null when the schedule does not open within 30 days of the moment
the send waits from: the requested sendAfter, or the acceptance; on a read, now once sendAfter
has passed. The help and README said only "the 30 days it looks ahead"; they now say from when,
that the value is a UTC moment, and that Reply sends within about 10 minutes of it.
@ArtemKosolap ArtemKosolap changed the title feat: direct sends carry Reply's LinkedIn scheduler: linkedin-scheduled references, estimated_send_at, the new cancel and schedule refusals, and the time-zone and retry-window flags feat: the direct sends follow, steer and explain a LinkedIn send timed by a sending schedule Oct 31, 2026
…ts schedule

Reply gives estimatedSendAt null on every answer whose state is not waitingForSchedule. The help
and README now say that only there does null mean the schedule does not open within 30 days; on
any other state the null says nothing.
…ontact-time-zone

Reply's direct email route reads a sending schedule in the contact's time zone or in the
schedule's own, as its LinkedIn routes do, so send-email now takes the same pair and sends
useContactTimeZone true or false only when one is given. The retry window stays on the four
LinkedIn sends: the email route takes none.

The help of every direct send now explains waitingForSchedule and estimated_send_at, since an
email timed by a schedule waits the same way. Reply's three refusals of an email it cannot time
(contact.scheduleNotFound, contact.scheduleHasNoSlot, contact.contactTimeZoneMissing) stay
reply.refused with Reply's code as reply_code; the help and README name them.
…ighbours

Edits had left README lines past the file's width and short ragged lines in the help of the
direct sends, direct-send get and direct-send cancel. The words are unchanged; only the line
breaks moved.
@ArtemKosolap ArtemKosolap changed the title feat: the direct sends follow, steer and explain a LinkedIn send timed by a sending schedule feat: the direct sends follow, steer and explain a send timed by a sending schedule Oct 31, 2026
…edule-id on a LinkedIn send

A Reply without the LinkedIn scheduler ignores sendAfter and scheduleId on the LinkedIn routes
and sends at once, which the answer without state already says; it never answers them with
errors[]. The help and the README no longer say it does.
…uch a LinkedIn send

The email route refuses a schedule it cannot read (404 contact.scheduleNotFound), a schedule that
never opens (409 contact.scheduleHasNoSlot) and a contact without the time zone it is asked to read
the schedule in (409 contact.contactTimeZoneMissing). Each now maps, under its own status, to the
code a LinkedIn send's refusal of the same meaning maps to: schedule.not_found, schedule.no_slot
and contact.time_zone_missing. A caller branches on the meaning rather than on the channel, and
reply_code keeps Reply's code. send-email's help lists the three.
…here past 30 days

Reply sets estimatedSendAt while a send waits for its schedule and gives it null in every other
state; in waitingForSchedule it is null as well when the schedule does not open within 30 days
of the moment the send waits from. The help of the five sends and of direct-send get and cancel,
and the README, now say it in those words.
@ArtemKosolap
ArtemKosolap merged commit c913f1e into main Oct 31, 2026
6 checks passed
@ArtemKosolap
ArtemKosolap deleted the fix/linkedin-scheduled-reference branch October 31, 2026 07:47
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