Repository navigation
feat: the direct sends follow, steer and explain a send timed by a sending schedule - #34
Merged
Merged
Conversation
…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
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.
…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.
…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.
…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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The direct sends now cover everything Reply's API answers for a send timed by a sending schedule, LinkedIn or email:
direct-send getanddirect-send cancelacceptlinkedin-scheduled-<n>, the reference of a LinkedIn send held for later.direct-send get/cancelpass onestimated_send_at.waitingForSchedulestate and a failed send without a failure code are read and documented.direct-send cancelmapsdirect_send.already_sendinganddirect_send.cancel_not_confirmed.--use-contact-time-zone/--no-use-contact-time-zone, and the four LinkedIn sends also take--retry-window-minutes <n>.schedule.not_found,schedule.no_slotandcontact.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 genericreply.refused, or asoutcome.unknownfor 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 keepslinkedin-<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 withstatewaitingForSchedule, nosendAfter, andestimatedSendAt. That field is when Reply expects to send it, a UTC moment Reply sends within about 10 minutes of. Reply sets it inwaitingForScheduleonly and gives it null in every other state; it is null inwaitingForScheduletoo when the schedule does not open within 30 days of the moment the send waits from (the requestedsendAfter, or the acceptance; on a read, now oncesendAfterhas passed). The send's answer anddirect-send get/cancelpass it on asestimated_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 getalready passed on any state that is a non-empty string, and gavefailure_codeas 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), includingdirectLinkedIn.contactNotFoundand a code the CLI does not know yet: any failure code passes through as Reply gives it. The help and the README now listwaitingForScheduleamong the states not yet sent. They also say that a failed send may carry nofailure_code.Cancel.
directSend.alreadySendingisdirect_send.already_sending, besidedirect_send.already_sentanddirect_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 saysqueued.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.directSend.cancelNotConfirmedmeans Reply could not confirm the cancel, and the send is stillqueuedorwaitingForSchedule; Reply asks for the cancel again. It is nowdirect_send.cancel_not_confirmed(exit 1), with a hint to run the cancel again, and Reply'sRetry-Afterinretry_afterwhen Reply sends one (Reply does not promise the header on this answer). Before, it ended asoutcome.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 staysoutcome.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-zonesendsuseContactTimeZone: true, so Reply reads the schedule's windows in the contact's time zone.--no-use-contact-time-zonesendsfalse, the schedule's own zone. With neither flag nothing is sent, so the schedule's own setting holds.--retry-window-minutes <n>sendsretryWindowMinutes: 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.--schedule-id. Reply answers a broken rule witherrors[], which the CLI reports asreply.invalid_request.contact send-emaildoes 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_codekeeps the code Reply gave. Each is definite, so nothing was sent, and each is read only under the status Reply gives it with:directLinkedIn.scheduleNotFoundorcontact.scheduleNotFound→schedule.not_found: the id names no schedule this account can readdirectLinkedIn.scheduleHasNoSlotorcontact.scheduleHasNoSlot→schedule.no_slot: the schedule has no active day with a time range, so it never opensdirectLinkedIn.contactTimeZoneMissingorcontact.contactTimeZoneMissing→contact.time_zone_missing:--use-contact-time-zoneasks for a time zone the contact does not haveEach change comes with its help text and README section.
Verification
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.commands.test.tspin the new flags, codes and wording.useContactTimeZoneas 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.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.