Repository navigation
feat: sends for later, direct-send get and cancel, and the inbox changes feed - #31
Merged
Merged
Conversation
…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.
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 changed
contact send-email,linkedin-connect,linkedin-message,linkedin-inmail,linkedin-voice) takes three new flags:--send-after <moment>goes in the body assendAfter, normalised to UTC. A moment without its offset is refused asusage.date(exit 2).--schedule-id <id>goes in the body asscheduleId.--idempotency-key <key>goes as theIdempotency-Keyheader, 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.status: "sent"with its meaning today: Reply took the send. It addsreference,send_afterandstateonly when Reply gives them, so an answer from a Reply without these fields is printed as before.idempotency_key.in_use(an earlier send under the key is still being made) andidempotency_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.reusednames the send the key was first taken for under the error'sdetails:reference,stateandsend_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 asmissing_variables, and the refusal's code and class are unchanged. Without them there is nodetails. A repeat of a send given a person's fields (--contact -) answerscontact.already_heldfirst, since the first one created the contact; the help and the README say so.contact send-emailalso:--track-linksand--track-opens, sent astrackLinksandtrackOpensonly when given, since Reply tracks neither unless asked;rendered_subjectandrendered_bodyto its answer when Reply sent the email within the request and gives them;contact.missingVariables(400) tocontact.missing_variables, with the names under the error'sdetails.missing_variableswhen Reply lists them, andcontact.renderingFailed(400) tocontact.rendering_failed, with Reply's message as thedetail. 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}) anddirect-send cancel <reference>(POST /v3/direct-sends/{reference}/cancel) are new.{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_subjectandrendered_body(Reply'sfailureCode,missingVariables,renderedSubject,renderedBody) are added only when Reply gives them, so an answer without them prints exactly as before.failure_reasonis a sentence for a person and never parsed;failure_codeis Reply's code for the failure.missing_variablesis printed only as a list of names.email-<n>orlinkedin-<n>(n from 1, at most ten digits), and nothing else is read from it. A reference of any other form is refused asusage.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.stateis passed on as Reply gives it.direct_send.not_found,direct_send.not_owned,direct_send.already_sentanddirect_send.already_failed.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.{items, has_more, cursor}, with the items as Reply gives them, asinbox listdoes.--cursortogether with--sinceis a usage error. With neither, Reply reads the last 30 days.--sinceis sent in UTC and not shifted, since Reply'ssinceis already inclusive.--sinceolder than the 30 days the feed keeps is refused with Reply's codeinboxThread.changeWindowExpired(400). It becomesinbox.cursor_expired, and its hint says to start again with--since.errors[]entry pointing at/cursor. When a cursor was sent, that answer becomesinbox.cursor_refused, with the same hint. Every other refusal of the feed maps as it does today.codenor anerrors[]is how Reply answers an exception escaping the send, which may already be made. It is nowoutcome.unknown(exit 3), with the same hint as a 5xx: a repeat may send it twice. A 400 witherrors[]staysreply.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.reply.refusedwith status 404 and noreply_code. That is how a Reply that does not have the route yet answers. Every other answer maps as it does today.statusandstateeach mean, the rendered text and the two template refusals, the twodirect-sendcommands andinbox changes. Each new command's--helplists 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.stateis the field that says whether a send has gone out (queuedorsendingmeans 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 testwas run on each commit. Before: 862 passed, 5 skipped. After: 924 passed, 5 skipped.missing_variablespassed through unchecked, orfailure_codedropped, in the projectionerrors[]checkdirect-send getandcancel, and of the feed include an HTML page and a plain-text body, each assertingreply.refused, status 404 and noreply_code.direct-send getandcancelsendemail-1,linkedin-42,email-9999999999andemail-1001as given, and refuse before any call, asusage.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/cancelandemail-1followed by a line break.contact.missingVariableswithout a list of names carries nodetails, and a LinkedIn send answering either template code isreply.refusedwith Reply's code kept.reference,stateandsend_after: an email'scontact.rendering_failedwith all three, one with onlyreference, a non-stringstatedropped, LinkedIn refusals (a known code and one mapped generically),contact.missing_variableswith its names beside the three, a LinkedIn limit beside itslimit, and refusals without them carrying nodetails. The reused rows are unchanged.outcome.unknown(exit 3), made once, with the hint that a repeat may send it twice.errors[], as problem+json and as plain JSON, isoutcome.unknown(exit 3, one call, the repeat hint) on each of the five sends; witherrors[](empty included) it isreply.invalid_request; an HTML, plain-text or empty 400 isreply.refused; the same 400 to the import of a send given a person's fields isreply.refusedand nothing is sent.fetchand uses a scratch configuration directory. No call reaches Reply.