From d03c22adcc4d3f0339190fb647ed0284e6cb4be8 Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 18:39:09 -0700 Subject: [PATCH 01/15] fix: direct-send get and cancel accept linkedin-scheduled-, a deferred LinkedIn send's reference Reply gives a LinkedIn send held for later the reference linkedin-scheduled- for its whole life; one sent at once keeps linkedin-. 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. --- README.md | 3 +- src/__tests__/operations/commands.test.ts | 4 +-- src/__tests__/operations/direct-sends.test.ts | 30 ++++++++++++++++++- src/operations/commands.ts | 10 +++---- src/operations/direct-sends.ts | 7 +++-- 5 files changed, 42 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 95896b7..38749c3 100644 --- a/README.md +++ b/README.md @@ -327,7 +327,8 @@ schedule list`). The answer then adds Reply's `reference`, `send_after` and `sta Reply gives it. `status: "sent"` means Reply took the send, and `state`, when present, says whether it has gone out: `queued` or `sending` is not yet, then `sent`, `failed` or `cancelled`. `reply direct-send get ` reads the send later, and `reply direct-send cancel ` stops -one that has not gone out. The reference is Reply's, `email-` or `linkedin-`, the form +one that has not gone out. The reference is Reply's, `email-`, `linkedin-` or +`linkedin-scheduled-` (a LinkedIn send held for later keeps that one for its whole life), the form Reply's route takes: a reference of any other form is refused before any call (`usage.reference`, exit 2), and nothing else is read from it. An answer without `state` comes from a Reply that does not know these flags yet: it sent at once, as without them. diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index c6e3845..7373c2e 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -47,11 +47,11 @@ describe('operations/commands', ()=>{ expect(flat, name).toContain('The reference is Reply\'s, from the answer of a send made with --send-after'); expect(flat, name).toContain('state is Reply\'s own word: queued or sending is not yet sent, then sent, failed or cancelled'); expect(flat, name).toContain('A Reply without this route answers reply.refused with status 404 and no reply_code'); - expect(flat, name).toContain('email- or linkedin-, the form Reply\'s route takes'); + expect(flat, name).toContain('email-, linkedin- or linkedin-scheduled-, the form Reply\'s route takes'); expect(flat, name).toContain('any other form is refused before any call (usage.reference, exit 2), and nothing else is read from it'); expect(flat, name).toContain('a reference of any other form never leaves the CLI, so that 404 means this Reply has no such route'); expect(flat, name).not.toContain('step up'); - expect(c.registeredArguments[0].description, name).toContain('email- or linkedin-'); + expect(c.registeredArguments[0].description, name).toContain('email-, linkedin- or linkedin-scheduled-'); expect(flat, name).toContain('failure_code, missing_variables, rendered_subject and rendered_body are added only when Reply gives them'); expect(flat, name).toContain('failure_reason is a sentence for a person, never parsed; failure_code is Reply\'s code for the failure'); } diff --git a/src/__tests__/operations/direct-sends.test.ts b/src/__tests__/operations/direct-sends.test.ts index 0abbd10..99a6f47 100644 --- a/src/__tests__/operations/direct-sends.test.ts +++ b/src/__tests__/operations/direct-sends.test.ts @@ -106,7 +106,35 @@ describe('direct-send get', ()=>{ { const e = await failure(()=>fn(reference, ctx(), {})); expect(e, `${fn.name} ${JSON.stringify(reference)}`).toMatchObject({code: 'usage.reference', exit_code: 2}); - expect((e as Error).message, JSON.stringify(reference)).toContain('email- or linkedin-'); + expect((e as Error).message, JSON.stringify(reference)).toContain('email-, linkedin- or linkedin-scheduled-'); + } + } + expect(mock_fetch).not.toHaveBeenCalled(); + }); + + it('sends a deferred LinkedIn send\'s reference, linkedin-scheduled-, as given to get and cancel', async()=>{ + for (const reference of ['linkedin-scheduled-1', 'linkedin-scheduled-1042', 'linkedin-scheduled-9999999999']) + { + for (const [fn, suffix] of [[get, ''], [cancel, '/cancel']] as const) + { + mock_fetch.mockReset(); + answer(json({...QUEUED, channel: 'linkedin', reference})); + expect((await fn(reference)).reference, reference).toBe(reference); + expect(sent()[0].url, reference).toBe(`https://api/v3/direct-sends/${reference}${suffix}`); + } + } + }); + + it('refuses a malformed scheduled reference before any call, by the same one-spelling rule', async()=>{ + const malformed = ['linkedin-scheduled-0', 'linkedin-scheduled-01', 'linkedin-scheduled-12345678901', 'linkedin-scheduled-', + 'linkedin-scheduled', 'linkedin-scheduled--1', 'linkedin-scheduled-1a', 'LINKEDIN-SCHEDULED-1', 'email-scheduled-1', + 'scheduled-1', 'linkedin-scheduled-scheduled-1', ' linkedin-scheduled-1', 'linkedin-scheduled-1/cancel']; + for (const reference of malformed) + { + for (const fn of [handle_direct_send_get, handle_direct_send_cancel]) + { + expect(await failure(()=>fn(reference, ctx(), {})), `${fn.name} ${JSON.stringify(reference)}`) + .toMatchObject({code: 'usage.reference', exit_code: 2}); } } expect(mock_fetch).not.toHaveBeenCalled(); diff --git a/src/operations/commands.ts b/src/operations/commands.ts index d67ed67..89de08a 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -581,9 +581,9 @@ const direct_send_command = new Command('direct-send').description('Read or canc const DIRECT_SEND = 'Result: {"reference","channel","contact_id","state","send_after","sent_at","message_id","failure_reason",\n' + '"cancelled_at"}, Reply\'s fields under these names, each null when Reply gives none. The reference is Reply\'s, from the\n' - + 'answer of a send made with --send-after: email- or linkedin-, the form Reply\'s route takes. A reference of\n' - + 'any other form is refused before any call (usage.reference, exit 2), and nothing else is read from it. state is\n' - + 'Reply\'s own word: queued or sending is not yet sent, then sent, failed or cancelled. failure_code,\n' + + 'answer of a send made with --send-after: email-, linkedin- or linkedin-scheduled-, the form Reply\'s route\n' + + 'takes. A reference of any other form is refused before any call (usage.reference, exit 2), and nothing else is read\n' + + 'from it. state is Reply\'s own word: queued or sending is not yet sent, then sent, failed or cancelled. failure_code,\n' + 'missing_variables, rendered_subject and rendered_body are added only when Reply gives them: failure_reason is a\n' + 'sentence for a person, never parsed; failure_code is Reply\'s code for the failure, the one to branch on.\n' + 'missing_variables lists the template variables Reply could not fill, and rendered_subject and rendered_body are the\n' @@ -592,7 +592,7 @@ const DIRECT_SEND = 'Result: {"reference","channel","contact_id","state","send_a + 'direct_send.not_found is a reference that Reply has no send for.\n'; direct_send_command.command('get') - .argument('', 'The send\'s reference, email- or linkedin-, as a send made with --send-after answered it') + .argument('', 'The send\'s reference, email-, linkedin- or linkedin-scheduled-, as a send made with --send-after answered it') .description('One direct send as Reply holds it: whether it has gone out, when, and why it failed') .addHelpText('after', help([ex('direct-send get email-1001')], ['direct_send.not_found', 'direct_send.not_owned'], false, DIRECT_SEND)) .action(run(async(cmd)=>{ @@ -601,7 +601,7 @@ direct_send_command.command('get') })); direct_send_command.command('cancel') - .argument('', 'The send\'s reference, email- or linkedin-, as a send made with --send-after answered it') + .argument('', 'The send\'s reference, email-, linkedin- or linkedin-scheduled-, as a send made with --send-after answered it') .description('Stop a direct send that has not gone out yet') .addHelpText('after', help([ex('direct-send cancel email-1001')], ['direct_send.not_found', 'direct_send.not_owned', 'direct_send.already_sent', 'direct_send.already_failed'], true, diff --git a/src/operations/direct-sends.ts b/src/operations/direct-sends.ts index 188b0cd..439c8fc 100644 --- a/src/operations/direct-sends.ts +++ b/src/operations/direct-sends.ts @@ -7,8 +7,9 @@ import type {Cli_context} from '../context'; // Reply's route takes exactly this form and answers anything else with a bare 404, as it does when it // has no such route at all. Checking the form here keeps that 404 meaning only the latter; nothing else -// is read from the reference, and the form leaves nothing to encode. -const REFERENCE = /^(email|linkedin)-[1-9]\d{0,9}$/; +// is read from the reference, and the form leaves nothing to encode. A LinkedIn send held for later keeps +// linkedin-scheduled- for its whole life; one sent at once is linkedin-. +const REFERENCE = /^(email|linkedin|linkedin-scheduled)-[1-9]\d{0,9}$/; const path_of = (reference: string): string=>{ if (reference.trim() === '') @@ -17,7 +18,7 @@ const path_of = (reference: string): string=>{ } if (!REFERENCE.test(reference)) { - throw new UsageError('That is not a reference Reply gives: email- or linkedin-, n from 1.', + throw new UsageError('That is not a reference Reply gives: email-, linkedin- or linkedin-scheduled-, n from 1.', {code: 'usage.reference', hint: 'A send made with --send-after answers its reference.'}); } return `/v3/direct-sends/${reference}`; From bbbc370d2e7ac047c12baaa546dcb21e1ee42a21 Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 21:51:19 -0700 Subject: [PATCH 02/15] feat: direct sends answer estimated_send_at for a LinkedIn send waiting 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. --- README.md | 8 +++++- src/__tests__/operations/commands.test.ts | 4 +++ src/__tests__/operations/direct-send.test.ts | 19 ++++++++++++++ src/__tests__/operations/direct-sends.test.ts | 26 +++++++++++++++++++ src/operations/commands.ts | 11 ++++++-- src/operations/direct-send.ts | 9 +++++-- src/operations/direct-sends.ts | 4 +-- 7 files changed, 74 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 38749c3..f974380 100644 --- a/README.md +++ b/README.md @@ -333,6 +333,11 @@ Reply's route takes: a reference of any other form is refused before any call (` exit 2), and nothing else is read from it. An answer without `state` comes from a Reply that does not know these flags yet: it sent at once, as without them. +A LinkedIn send timed by `--schedule-id` may answer `state` `waitingForSchedule`: Reply holds it for +the schedule's next opening, so `send_after` is left out, and `estimated_send_at` is when Reply +expects to send it, or null when no opening falls within the 30 days it looks ahead. It is added +only when Reply gives it. + `--idempotency-key` goes to Reply as the `Idempotency-Key` header, never in the body. A Reply that knows the header answers a repeat with the same key with the send the key first made; while that one is still being made the answer is `idempotency_key.in_use`, and the same key on a different @@ -356,7 +361,8 @@ reply direct-send cancel linkedin-1042 Both answer the send under the CLI's names, each null when Reply gives none: `reference`, `channel`, `contact_id`, `state`, `send_after`, `sent_at`, `message_id`, `failure_reason` and `cancelled_at`. `failure_code`, `missing_variables`, `rendered_subject` and `rendered_body` are -added only when Reply gives them. `failure_reason` is a sentence for a person and never parsed; +added only when Reply gives them, and so is `estimated_send_at`, read the same way as on the send. +`failure_reason` is a sentence for a person and never parsed; `failure_code` is Reply's code for the failure, the one to branch on. `direct-send cancel` of a send already cancelled answers it again. A send already gone out or failed is `direct_send.already_sent` or `direct_send.already_failed`, and a reference Reply has no send for is `direct_send.not_found`. diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index 7373c2e..700bdbe 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -54,6 +54,8 @@ describe('operations/commands', ()=>{ expect(c.registeredArguments[0].description, name).toContain('email-, linkedin- or linkedin-scheduled-'); expect(flat, name).toContain('failure_code, missing_variables, rendered_subject and rendered_body are added only when Reply gives them'); expect(flat, name).toContain('failure_reason is a sentence for a person, never parsed; failure_code is Reply\'s code for the failure'); + expect(flat, name).toContain('estimated_send_at is added only when Reply gives it: when Reply expects a send waiting for its ' + + 'schedule\'s next opening to go out, or null when no opening falls within the 30 days it looks ahead'); } expect(help_of(sub(direct_send_command, 'cancel')).replace(/\s+/g, ' ')) .toContain('Cancelling a send already cancelled answers it again, so running it again is safe'); @@ -294,6 +296,8 @@ describe('operations/commands', ()=>{ expect(flat, text).toContain('status "sent" means Reply took the send; state, when Reply gives it, says whether it has gone ' + 'out: queued or sending is not yet, then sent, failed or cancelled'); expect(flat, text).toContain('direct-send get reads it later, and direct-send cancel stops one not yet sent'); + expect(flat.includes('A LinkedIn send timed by --schedule-id may answer state waitingForSchedule'), text).toBe(name !== 'send-email'); + expect(flat.includes('estimated_send_at'), text).toBe(name !== 'send-email'); expect(flat, text).toContain('An answer without state comes from a Reply that does not know --send-after and --schedule-id'); expect(flat, text).toContain('--idempotency-key goes as the Idempotency-Key header'); expect(flat, text).toContain('A Reply that knows the header answers a repeat with the same key with the send the key first made; while that one is still ' diff --git a/src/__tests__/operations/direct-send.test.ts b/src/__tests__/operations/direct-send.test.ts index 08b62c1..3e5710c 100644 --- a/src/__tests__/operations/direct-send.test.ts +++ b/src/__tests__/operations/direct-send.test.ts @@ -674,6 +674,25 @@ describe('a send for later', ()=>{ }); }); + it('adds estimated_send_at to a send waiting for its schedule\'s opening, a null kept as null, only when Reply gives it', async()=>{ + const waiting = {reference: 'linkedin-scheduled-77', state: 'waitingForSchedule', sendAfter: null, linkedInActivityId: null, sentAtUtc: null}; + const cases: [unknown, Record][] = [ + ['2026-11-04T09:00:00Z', {estimated_send_at: '2026-11-04T09:00:00Z'}], + [null, {estimated_send_at: null}], + [undefined, {}], + [7, {}], + ]; + for (const [estimatedSendAt, added] of cases) + { + mock_fetch.mockReset(); + answer(json({...waiting, estimatedSendAt})); + expect(await run('linkedin-message', {body: TEXT}, {...LINKEDIN_OPTS, scheduleId: '41'}), JSON.stringify(estimatedSendAt)).toStrictEqual({ + status: 'sent', contact_id: 456, contact_created: false, activity_id: null, sent_at: null, + reference: 'linkedin-scheduled-77', state: 'waitingForSchedule', ...added, + }); + } + }); + it('adds the rendered subject and body of an email sent inside the request, each only when Reply gives it', async()=>{ answer(accepted('send-email', {renderedSubject: 'Quick question, Marta', renderedBody: '

Hi Marta

', state: 'sent'})); expect(await run('send-email', {subject: SUBJECT, body: BODY}, EMAIL_OPTS)).toStrictEqual({ diff --git a/src/__tests__/operations/direct-sends.test.ts b/src/__tests__/operations/direct-sends.test.ts index 99a6f47..38d7f8c 100644 --- a/src/__tests__/operations/direct-sends.test.ts +++ b/src/__tests__/operations/direct-sends.test.ts @@ -68,6 +68,32 @@ describe('direct-send get', ()=>{ } }); + it('adds estimated_send_at, Reply\'s estimatedSendAt, as text or null and only when Reply gives it, to get and cancel', async()=>{ + const WAITING = {...QUEUED, reference: 'linkedin-scheduled-77', channel: 'linkedin', state: 'waitingForSchedule', sendAfter: null}; + const cases: [unknown, Record][] = [ + ['2026-11-04T09:00:00Z', {estimated_send_at: '2026-11-04T09:00:00Z'}], + [null, {estimated_send_at: null}], + ]; + for (const fn of [get, cancel]) + { + for (const [estimatedSendAt, added] of cases) + { + mock_fetch.mockReset(); + answer(json({...WAITING, estimatedSendAt})); + expect(await fn('linkedin-scheduled-77'), JSON.stringify(estimatedSendAt)).toStrictEqual({ + reference: 'linkedin-scheduled-77', channel: 'linkedin', contact_id: 456, state: 'waitingForSchedule', send_after: null, + ...added, sent_at: null, message_id: null, failure_reason: null, cancelled_at: null, + }); + } + for (const odd of [undefined, 7, ['2026-11-04T09:00:00Z']]) + { + mock_fetch.mockReset(); + answer(json({...WAITING, estimatedSendAt: odd})); + expect(await fn('linkedin-scheduled-77'), JSON.stringify(odd)).not.toHaveProperty('estimated_send_at'); + } + } + }); + it('gives missing_variables only as a list of names, and the others only as text: anything else is left out', async()=>{ for (const missing of [[], ['FirstName']]) { diff --git a/src/operations/commands.ts b/src/operations/commands.ts index 89de08a..538687c 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -364,6 +364,11 @@ const VARIABLES = (where: string): string=> `Reply reads {{…}} in the ${where} as its template variables; one it cannot fill is linkedin.missing_variables.\n`; const LINKEDIN_EXAMPLE = '--contact-id 456 --linkedin-account-id 34'; +// What a LinkedIn send timed by a schedule answers while it waits for the schedule's next opening. +const SCHEDULED = 'A LinkedIn send timed by --schedule-id may answer state waitingForSchedule, held for the schedule\'s next\n' + + 'opening: send_after is then left out, and estimated_send_at is when Reply expects to send it, or null when no opening\n' + + 'falls within the 30 days it looks ahead; it is added only when Reply gives it.\n'; + const linkedin_send = ( name: Exclude, description: string, message: string, examples: string[], codes: string[], extra: string, what: string, @@ -372,7 +377,7 @@ const linkedin_send = ( .option('--linkedin-account-id ', 'The LinkedIn account to send from (see `account list`)') .option('--message ', `Only -: the ${message} as JSON on stdin`)) .description(description) - .addHelpText('after', help(examples, [...LINKEDIN_SEND_CODES, ...codes, ...KEY_CODES], true, extra + LATER + SENT_TO('linkedin', what), + .addHelpText('after', help(examples, [...LINKEDIN_SEND_CODES, ...codes, ...KEY_CODES], true, extra + LATER + SCHEDULED + SENT_TO('linkedin', what), SEND_TWICE(what))) .action(run(async(cmd)=>{ const {g, ctx} = ctx_of(cmd); @@ -587,7 +592,9 @@ const DIRECT_SEND = 'Result: {"reference","channel","contact_id","state","send_a + 'missing_variables, rendered_subject and rendered_body are added only when Reply gives them: failure_reason is a\n' + 'sentence for a person, never parsed; failure_code is Reply\'s code for the failure, the one to branch on.\n' + 'missing_variables lists the template variables Reply could not fill, and rendered_subject and rendered_body are the\n' - + 'text as Reply filled it in. A Reply without this route answers reply.refused with status 404 and no reply_code; a\n' + + 'text as Reply filled it in. estimated_send_at is added only when Reply gives it: when Reply expects a send waiting\n' + + 'for its schedule\'s next opening to go out, or null when no opening falls within the 30 days it looks ahead.\n' + + 'A Reply without this route answers reply.refused with status 404 and no reply_code; a\n' + 'reference of any other form never leaves the CLI, so that 404 means this Reply has no such route.\n' + 'direct_send.not_found is a reference that Reply has no send for.\n'; diff --git a/src/operations/direct-send.ts b/src/operations/direct-send.ts index 7d2b846..4c0f05c 100644 --- a/src/operations/direct-send.ts +++ b/src/operations/direct-send.ts @@ -280,7 +280,12 @@ const positive_integer = (v: unknown): number | null=> const HELD_KEYS: [string, string][] = [['reference', 'reference'], ['sendAfter', 'send_after'], ['state', 'state']]; const LATER_KEYS: [string, string][] = [...HELD_KEYS, ['renderedSubject', 'rendered_subject'], ['renderedBody', 'rendered_body']]; -const later_of = (sent: Record): Record=>picked(LATER_KEYS, sent); +// When Reply expects a send waiting for its schedule's next opening to go out, as text, or null when no opening falls +// within the 30 days it looks ahead; left out when Reply gives neither, as a Reply before its scheduler does. +const estimated_of = (from: Record): Record=> + typeof from.estimatedSendAt === 'string' || from.estimatedSendAt === null ? {estimated_send_at: from.estimatedSendAt} : {}; + +const later_of = (sent: Record): Record=>({...picked(LATER_KEYS, sent), ...estimated_of(sent)}); // What the CLI answers for a send Reply took: the contact it went to, as the add commands name it, so // a caller can keep its id. Neither adds a time of its own: Reply's answer to a direct email carries @@ -429,5 +434,5 @@ const handle_direct_send = async( } }; -export {handle_direct_send, known_refusal, strings_of, DIRECT_SEND_REFUSALS}; +export {handle_direct_send, known_refusal, strings_of, estimated_of, DIRECT_SEND_REFUSALS}; export type {Direct_send_name, Direct_send_opts}; diff --git a/src/operations/direct-sends.ts b/src/operations/direct-sends.ts index 439c8fc..887d2a7 100644 --- a/src/operations/direct-sends.ts +++ b/src/operations/direct-sends.ts @@ -1,6 +1,6 @@ import {Unknown_outcome_error, UsageError} from '../utils/errors'; import {call_reply, expect_object, refusal, unreadable, open_session, type Answer} from './call'; -import {known_refusal, strings_of, DIRECT_SEND_REFUSALS} from './direct-send'; +import {known_refusal, strings_of, estimated_of, DIRECT_SEND_REFUSALS} from './direct-send'; import {print_result} from './result'; import type {Op_globals} from './options'; import type {Cli_context} from '../context'; @@ -51,7 +51,7 @@ const direct_send_of = (a: Answer, kind: 'read' | 'write'): Recordbody[name] ?? null; return { reference: body.reference, channel: field('channel'), contact_id: field('contactId'), state: body.state, - send_after: field('sendAfter'), sent_at: field('sentAt'), message_id: field('messageId'), + send_after: field('sendAfter'), ...estimated_of(body), sent_at: field('sentAt'), message_id: field('messageId'), failure_reason: field('failureReason'), ...rendering_of(body), cancelled_at: field('cancelledAt'), }; }; From a7a6e95eb9705a6e2d4293d2270d051f416fce11 Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 21:52:36 -0700 Subject: [PATCH 03/15] docs: direct-send help names waitingForSchedule and a failed send without 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. --- README.md | 5 +++-- src/__tests__/operations/commands.test.ts | 5 +++-- src/__tests__/operations/direct-sends.test.ts | 19 +++++++++++++++++++ src/operations/commands.ts | 11 ++++++----- 4 files changed, 31 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index f974380..4ad8ab6 100644 --- a/README.md +++ b/README.md @@ -325,7 +325,7 @@ Every direct send also takes `--send-after `, `--schedule-id ` and ` (`usage.date`). `--schedule-id` names the sending schedule Reply times the send by (see `reply schedule list`). The answer then adds Reply's `reference`, `send_after` and `state`, each only when Reply gives it. `status: "sent"` means Reply took the send, and `state`, when present, says whether -it has gone out: `queued` or `sending` is not yet, then `sent`, `failed` or `cancelled`. `reply +it has gone out: `queued`, `waitingForSchedule` or `sending` is not yet, then `sent`, `failed` or `cancelled`. `reply direct-send get ` reads the send later, and `reply direct-send cancel ` stops one that has not gone out. The reference is Reply's, `email-`, `linkedin-` or `linkedin-scheduled-` (a LinkedIn send held for later keeps that one for its whole life), the form @@ -363,7 +363,8 @@ Both answer the send under the CLI's names, each null when Reply gives none: `re `cancelled_at`. `failure_code`, `missing_variables`, `rendered_subject` and `rendered_body` are added only when Reply gives them, and so is `estimated_send_at`, read the same way as on the send. `failure_reason` is a sentence for a person and never parsed; -`failure_code` is Reply's code for the failure, the one to branch on. `direct-send cancel` of a send already cancelled answers it +`failure_code` is Reply's code for the failure, the one to branch on. A failed send may carry no +`failure_code`: it is then null, and `failure_reason` is all Reply says of it. `direct-send cancel` of a send already cancelled answers it again. A send already gone out or failed is `direct_send.already_sent` or `direct_send.already_failed`, and a reference Reply has no send for is `direct_send.not_found`. diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index 700bdbe..6548813 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -45,7 +45,8 @@ describe('operations/commands', ()=>{ expect(text, name).toContain(codes.map(code=>` ${code}\n`).join('')); expect(text.includes('outcome.unknown'), name).toBe(write); expect(flat, name).toContain('The reference is Reply\'s, from the answer of a send made with --send-after'); - expect(flat, name).toContain('state is Reply\'s own word: queued or sending is not yet sent, then sent, failed or cancelled'); + expect(flat, name).toContain('state is Reply\'s own word: queued, waitingForSchedule or sending is not yet sent, then sent, failed or cancelled'); + expect(flat, name).toContain('A failed send may carry no failure_code: it is then null'); expect(flat, name).toContain('A Reply without this route answers reply.refused with status 404 and no reply_code'); expect(flat, name).toContain('email-, linkedin- or linkedin-scheduled-, the form Reply\'s route takes'); expect(flat, name).toContain('any other form is refused before any call (usage.reference, exit 2), and nothing else is read from it'); @@ -294,7 +295,7 @@ describe('operations/commands', ()=>{ expect(flat, text).toContain('read from stdin only'); // A send for later: what status and state each say, and what an older Reply does with the flags. expect(flat, text).toContain('status "sent" means Reply took the send; state, when Reply gives it, says whether it has gone ' - + 'out: queued or sending is not yet, then sent, failed or cancelled'); + + 'out: queued, waitingForSchedule or sending is not yet, then sent, failed or cancelled'); expect(flat, text).toContain('direct-send get reads it later, and direct-send cancel stops one not yet sent'); expect(flat.includes('A LinkedIn send timed by --schedule-id may answer state waitingForSchedule'), text).toBe(name !== 'send-email'); expect(flat.includes('estimated_send_at'), text).toBe(name !== 'send-email'); diff --git a/src/__tests__/operations/direct-sends.test.ts b/src/__tests__/operations/direct-sends.test.ts index 38d7f8c..bfd7ff0 100644 --- a/src/__tests__/operations/direct-sends.test.ts +++ b/src/__tests__/operations/direct-sends.test.ts @@ -94,6 +94,25 @@ describe('direct-send get', ()=>{ } }); + it('reads a LinkedIn send through the states Reply\'s scheduler gives it, and a failure with or without its code', async()=>{ + const LINKEDIN = {...QUEUED, reference: 'linkedin-scheduled-77', channel: 'linkedin'}; + const cases: [Record, Record][] = [ + [{state: 'waitingForSchedule', sendAfter: null, estimatedSendAt: null}, {state: 'waitingForSchedule', send_after: null}], + [{state: 'sending'}, {state: 'sending'}], + [{state: 'failed', failureReason: 'The send failed.', failureCode: null}, {state: 'failed', failure_code: null}], + [{state: 'failed', failureCode: 'directSend.dispatchWindowMissed'}, {state: 'failed', failure_code: 'directSend.dispatchWindowMissed'}], + [{state: 'failed', failureCode: 'directSend.dispatchInterrupted'}, {state: 'failed', failure_code: 'directSend.dispatchInterrupted'}], + [{state: 'failed', failureCode: 'directLinkedIn.notConnected'}, {state: 'failed', failure_code: 'directLinkedIn.notConnected'}], + [{state: 'cancelled', cancelledAt: '2026-11-02T09:15:00Z'}, {state: 'cancelled', cancelled_at: '2026-11-02T09:15:00Z'}], + ]; + for (const [given, read] of cases) + { + mock_fetch.mockReset(); + answer(json({...LINKEDIN, ...given})); + expect(await get('linkedin-scheduled-77'), JSON.stringify(given)).toMatchObject({reference: 'linkedin-scheduled-77', ...read}); + } + }); + it('gives missing_variables only as a list of names, and the others only as text: anything else is left out', async()=>{ for (const missing of [[], ['FirstName']]) { diff --git a/src/operations/commands.ts b/src/operations/commands.ts index 538687c..254dfc9 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -300,8 +300,8 @@ const later_options = (c: Command): Command=>c const LATER = 'With --send-after Reply holds the send until that moment, given with its offset and sent to Reply in UTC; a moment\n' + 'without an offset is refused (usage.date). --schedule-id names the sending schedule Reply times the send by. The answer\n' + 'then adds Reply\'s reference, send_after and state, each only when Reply gives it: status "sent" means Reply took the\n' - + 'send; state, when Reply gives it, says whether it has gone out: queued or sending is not yet, then sent, failed or\n' - + 'cancelled. direct-send get reads it later, and direct-send cancel stops one not yet sent. An\n' + + 'send; state, when Reply gives it, says whether it has gone out: queued, waitingForSchedule or sending is not yet,\n' + + 'then sent, failed or cancelled. direct-send get reads it later, and direct-send cancel stops one not yet sent. An\n' + 'answer without state comes from a Reply that does not know --send-after and --schedule-id: it sent at once, as\n' + 'without them. --idempotency-key goes as the Idempotency-Key header, never in the body. A Reply that knows the header\n' + 'answers a repeat with the same key with the send the key first made; while that one is still being made the answer\n' @@ -588,9 +588,10 @@ const DIRECT_SEND = 'Result: {"reference","channel","contact_id","state","send_a + '"cancelled_at"}, Reply\'s fields under these names, each null when Reply gives none. The reference is Reply\'s, from the\n' + 'answer of a send made with --send-after: email-, linkedin- or linkedin-scheduled-, the form Reply\'s route\n' + 'takes. A reference of any other form is refused before any call (usage.reference, exit 2), and nothing else is read\n' - + 'from it. state is Reply\'s own word: queued or sending is not yet sent, then sent, failed or cancelled. failure_code,\n' - + 'missing_variables, rendered_subject and rendered_body are added only when Reply gives them: failure_reason is a\n' - + 'sentence for a person, never parsed; failure_code is Reply\'s code for the failure, the one to branch on.\n' + + 'from it. state is Reply\'s own word: queued, waitingForSchedule or sending is not yet sent, then sent, failed or\n' + + 'cancelled. failure_code, missing_variables, rendered_subject and rendered_body are added only when Reply gives them:\n' + + 'failure_reason is a sentence for a person, never parsed; failure_code is Reply\'s code for the failure, the one to\n' + + 'branch on. A failed send may carry no failure_code: it is then null, and failure_reason is all Reply says of it.\n' + 'missing_variables lists the template variables Reply could not fill, and rendered_subject and rendered_body are the\n' + 'text as Reply filled it in. estimated_send_at is added only when Reply gives it: when Reply expects a send waiting\n' + 'for its schedule\'s next opening to go out, or null when no opening falls within the 30 days it looks ahead.\n' From 525f0748f594747803fe4ad5c9f3597c2a633b01 Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 21:54:53 -0700 Subject: [PATCH 04/15] feat: direct-send cancel answers a send already going out and a cancel 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. --- README.md | 8 +++- src/__tests__/operations/commands.test.ts | 12 ++++-- src/__tests__/operations/direct-sends.test.ts | 38 ++++++++++++++++++- src/operations/commands.ts | 9 +++-- src/operations/direct-send.ts | 18 ++++++++- src/operations/direct-sends.ts | 4 +- 6 files changed, 75 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 4ad8ab6..82d8802 100644 --- a/README.md +++ b/README.md @@ -365,8 +365,12 @@ added only when Reply gives them, and so is `estimated_send_at`, read the same w `failure_reason` is a sentence for a person and never parsed; `failure_code` is Reply's code for the failure, the one to branch on. A failed send may carry no `failure_code`: it is then null, and `failure_reason` is all Reply says of it. `direct-send cancel` of a send already cancelled answers it -again. A send already gone out or failed is `direct_send.already_sent` or -`direct_send.already_failed`, and a reference Reply has no send for is `direct_send.not_found`. +again. A send already gone out, failed or going out is `direct_send.already_sent`, +`direct_send.already_failed` or `direct_send.already_sending`, and a reference Reply has no send for +is `direct_send.not_found`. A `503` that Reply answers with `directSend.cancelNotConfirmed` is +`direct_send.cancel_not_confirmed` (exit 1): Reply could not confirm the cancel, so it may not have +taken, and running it again is safe; `retry_after` carries Reply's `Retry-After` when it sends one. +Any other `5xx` to a cancel stays `outcome.unknown` (exit 3). `reply inbox changes` reads the inbox feed forward. Each page holds the threads whose latest message, inbound or outbound, changed, oldest first and as Reply gives them, with `has_more` and a `cursor`. diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index 6548813..d5ffed6 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -33,7 +33,8 @@ describe('operations/commands', ()=>{ it('direct-send get and cancel each take one reference and no flag, and list the refusals Reply gives each', ()=>{ const expected: [string, string[], boolean][] = [ ['get', ['direct_send.not_found', 'direct_send.not_owned'], false], - ['cancel', ['direct_send.not_found', 'direct_send.not_owned', 'direct_send.already_sent', 'direct_send.already_failed'], true], + ['cancel', ['direct_send.not_found', 'direct_send.not_owned', 'direct_send.already_sent', 'direct_send.already_failed', + 'direct_send.already_sending', 'direct_send.cancel_not_confirmed'], true], ]; for (const [name, codes, write] of expected) { @@ -58,8 +59,13 @@ describe('operations/commands', ()=>{ expect(flat, name).toContain('estimated_send_at is added only when Reply gives it: when Reply expects a send waiting for its ' + 'schedule\'s next opening to go out, or null when no opening falls within the 30 days it looks ahead'); } - expect(help_of(sub(direct_send_command, 'cancel')).replace(/\s+/g, ' ')) - .toContain('Cancelling a send already cancelled answers it again, so running it again is safe'); + const cancel = help_of(sub(direct_send_command, 'cancel')).replace(/\s+/g, ' '); + expect(cancel).toContain('Cancelling a send already cancelled answers it again, so running it again is safe'); + expect(cancel).toContain('direct_send.already_sent, direct_send.already_failed and direct_send.already_sending mean the send ' + + 'was past cancelling; nothing changed'); + expect(cancel).toContain('direct_send.cancel_not_confirmed is a 503 from Reply that could not confirm the cancel: it may not ' + + 'have taken, and running it again is safe; retry_after carries Reply\'s Retry-After when it sends one. Any other 5xx ' + + 'is outcome.unknown (exit 3)'); }); it('schedule list takes no flag and no id, and says how a time zone, a weekday, a time and a state are written', ()=>{ diff --git a/src/__tests__/operations/direct-sends.test.ts b/src/__tests__/operations/direct-sends.test.ts index bfd7ff0..24a81c1 100644 --- a/src/__tests__/operations/direct-sends.test.ts +++ b/src/__tests__/operations/direct-sends.test.ts @@ -1,5 +1,5 @@ import {describe, it, expect, beforeEach} from 'vitest'; -import {mock_fetch, json, ctx, sent, answer, capture} from './helpers'; +import {mock_fetch, json, ctx, sent, answer, capture, instant_timers, real_timers} from './helpers'; import {handle_direct_send_get, handle_direct_send_cancel} from '../../operations/direct-sends'; beforeEach(()=>{ mock_fetch.mockReset(); }); @@ -251,13 +251,15 @@ describe('direct-send cancel', ()=>{ expect(mock_fetch).toHaveBeenCalledTimes(2); }); - it('maps Reply\'s four refusals of a cancel, each definite', async()=>{ + it('maps Reply\'s five refusals of a cancel, each definite', async()=>{ const cases: [Response, string][] = [ [json({code: 'directSend.notFound'}, 404), 'direct_send.not_found'], [json({code: 'directSend.notOwned'}, 403), 'direct_send.not_owned'], [json({code: 'directSend.alreadySent'}, 409), 'direct_send.already_sent'], [json({code: 'directSend.alreadyFailed'}, 409), 'direct_send.already_failed'], + [json({code: 'directSend.alreadySending'}, 409), 'direct_send.already_sending'], [json({code: 'directSend.alreadySent'}, 400), 'reply.refused'], + [json({code: 'directSend.alreadySending'}, 400), 'reply.refused'], ]; for (const [res, code] of cases) { @@ -283,6 +285,8 @@ describe('direct-send cancel', ()=>{ const answers: [string, ()=>void][] = [ ['lost answer', ()=>{ mock_fetch.mockRejectedValueOnce(lost_connection()); }], ['503', ()=>answer(json({title: 'Service Unavailable'}, 503))], + ['503 with another code', ()=>answer(json({code: 'directSend.somethingElse'}, 503))], + ['500 with the unconfirmed cancel\'s code', ()=>answer(json({code: 'directSend.cancelNotConfirmed'}, 500))], ['unreadable 200', ()=>answer(json('ok', 200))], ]; for (const [label, give] of answers) @@ -296,6 +300,36 @@ describe('direct-send cancel', ()=>{ } }); + it('a 503 directSend.cancelNotConfirmed is direct_send.cancel_not_confirmed (exit 1), made once, says running it again ' + + 'is safe, and passes on Reply\'s wait', async()=>{ + const cases: [Record, number | undefined][] = [[{}, undefined], [{'Retry-After': '5'}, 5]]; + for (const [headers, retry_after] of cases) + { + mock_fetch.mockReset(); + answer(json({code: 'directSend.cancelNotConfirmed', detail: 'The cancel could not be confirmed.'}, 503, headers)); + const e = await failure(()=>handle_direct_send_cancel('linkedin-scheduled-77', ctx(), {})); + expect(e, JSON.stringify(headers)).toMatchObject({ + code: 'direct_send.cancel_not_confirmed', exit_code: 1, status: 503, reply_code: 'directSend.cancelNotConfirmed', + detail: 'The cancel could not be confirmed.', + }); + expect((e as {retry_after?: number}).retry_after, JSON.stringify(headers)).toBe(retry_after); + expect((e as {hint?: string}).hint ?? '').toContain('running it again is safe'); + expect(mock_fetch).toHaveBeenCalledTimes(1); + } + }); + + it('reads an unconfirmed cancel only on a cancel: a read answering its code maps as any other 5xx', async()=>{ + instant_timers(); + try { + mock_fetch.mockImplementation(()=>Promise.resolve(json({code: 'directSend.cancelNotConfirmed'}, 503))); + expect(await failure(()=>handle_direct_send_get('linkedin-scheduled-77', ctx(), {}))) + .toMatchObject({code: 'reply.unavailable', exit_code: 1}); + } finally { + real_timers(); + mock_fetch.mockReset(); + } + }); + it('refuses a blank reference before any call', async()=>{ expect(await failure(()=>handle_direct_send_cancel(' ', ctx(), {}))).toMatchObject({code: 'usage.reference', exit_code: 2}); expect(mock_fetch).not.toHaveBeenCalled(); diff --git a/src/operations/commands.ts b/src/operations/commands.ts index 254dfc9..6383bfb 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -612,10 +612,13 @@ direct_send_command.command('cancel') .argument('', 'The send\'s reference, email-, linkedin- or linkedin-scheduled-, as a send made with --send-after answered it') .description('Stop a direct send that has not gone out yet') .addHelpText('after', help([ex('direct-send cancel email-1001')], - ['direct_send.not_found', 'direct_send.not_owned', 'direct_send.already_sent', 'direct_send.already_failed'], true, + ['direct_send.not_found', 'direct_send.not_owned', 'direct_send.already_sent', 'direct_send.already_failed', + 'direct_send.already_sending', 'direct_send.cancel_not_confirmed'], true, DIRECT_SEND + 'The answer is the send as Reply now holds it, state cancelled. Cancelling a send already cancelled answers\n' - + 'it again, so running it again is safe. direct_send.already_sent and direct_send.already_failed mean the send\n' - + 'was past cancelling; nothing changed.\n')) + + 'it again, so running it again is safe. direct_send.already_sent, direct_send.already_failed and\n' + + 'direct_send.already_sending mean the send was past cancelling; nothing changed. direct_send.cancel_not_confirmed\n' + + 'is a 503 from Reply that could not confirm the cancel: it may not have taken, and running it again is safe;\n' + + 'retry_after carries Reply\'s Retry-After when it sends one. Any other 5xx is outcome.unknown (exit 3).\n')) .action(run(async(cmd)=>{ const {g, ctx} = ctx_of(cmd); await handle_direct_send_cancel(cmd.args[0], ctx, g); diff --git a/src/operations/direct-send.ts b/src/operations/direct-send.ts index 4c0f05c..0cb866f 100644 --- a/src/operations/direct-send.ts +++ b/src/operations/direct-send.ts @@ -93,8 +93,9 @@ const read_text = (name: Direct_send_name, send: Direct_send, source: string | u // A refusal Reply publishes, under the status it comes with; details reads what the problem body // carries beside its code, for the error output's details. +// waits passes on the Retry-After Reply sends with a refusal worth repeating. type Refusal = { - status: number; code: string; title: string; hint?: string; + status: number; code: string; title: string; hint?: string; waits?: boolean; details?: (body: Record) => Record | undefined; }; @@ -210,6 +211,18 @@ const DIRECT_SEND_REFUSALS: Record = { 'directSend.alreadyFailed': { status: 409, code: 'direct_send.already_failed', title: 'The direct send has already failed, so it was not cancelled.', }, + 'directSend.alreadySending': { + status: 409, code: 'direct_send.already_sending', title: 'The direct send is already going out, so it was not cancelled.', + }, +}; +// A cancel Reply could not confirm: it may not have taken, and Reply says repeating it is safe, so it is a refusal of its +// own rather than an outcome left unknown. Only a cancel answers it; a read answering this code maps as any other 5xx. +const CANCEL_REFUSALS: Record = { + 'directSend.cancelNotConfirmed': { + status: 503, code: 'direct_send.cancel_not_confirmed', title: 'Reply could not confirm the cancel; it may not have taken.', + hint: 'The send may or may not have been cancelled; running it again is safe, and direct-send get reads where it stands.', + waits: true, + }, }; // The refusal a table holds for this answer, under the status Reply publishes it with, or undefined. @@ -219,6 +232,7 @@ const known_refusal = (a: Answer, table: Record): Operation_err return known !== undefined && known.status === a.status ? new Operation_error(known.code, known.title, { status: a.status, reply_code, detail: detail_of(a), hint: known.hint, details: known.details?.(a.data as Record), + retry_after: known.waits === true ? parse_retry_after(a.headers['retry-after']) ?? undefined : undefined, }) : undefined; }; @@ -434,5 +448,5 @@ const handle_direct_send = async( } }; -export {handle_direct_send, known_refusal, strings_of, estimated_of, DIRECT_SEND_REFUSALS}; +export {handle_direct_send, known_refusal, strings_of, estimated_of, DIRECT_SEND_REFUSALS, CANCEL_REFUSALS}; export type {Direct_send_name, Direct_send_opts}; diff --git a/src/operations/direct-sends.ts b/src/operations/direct-sends.ts index 887d2a7..1ddf0c9 100644 --- a/src/operations/direct-sends.ts +++ b/src/operations/direct-sends.ts @@ -1,6 +1,6 @@ import {Unknown_outcome_error, UsageError} from '../utils/errors'; import {call_reply, expect_object, refusal, unreadable, open_session, type Answer} from './call'; -import {known_refusal, strings_of, estimated_of, DIRECT_SEND_REFUSALS} from './direct-send'; +import {known_refusal, strings_of, estimated_of, DIRECT_SEND_REFUSALS, CANCEL_REFUSALS} from './direct-send'; import {print_result} from './result'; import type {Op_globals} from './options'; import type {Cli_context} from '../context'; @@ -74,7 +74,7 @@ const handle_direct_send_cancel = async(reference: string, ctx: Cli_context, g: const a = await call_reply(s, 'POST', path, 'write'); if (a.status !== 200) { - throw known_refusal(a, DIRECT_SEND_REFUSALS) ?? refusal(a, 'write'); + throw known_refusal(a, DIRECT_SEND_REFUSALS) ?? known_refusal(a, CANCEL_REFUSALS) ?? refusal(a, 'write'); } print_result(direct_send_of(a, 'write'), g); } catch (e) { From 5f6b50fd57bcd5be0d4b13d04e6702b7e0db10df Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 21:56:46 -0700 Subject: [PATCH 05/15] feat: the four LinkedIn sends take --use-contact-time-zone and --retry-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 . 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. --- README.md | 15 ++++++ src/__tests__/operations/commands.test.ts | 9 +++- src/__tests__/operations/direct-send.test.ts | 50 ++++++++++++++++++++ src/operations/commands.ts | 22 +++++++-- src/operations/direct-send.ts | 12 ++++- 5 files changed, 102 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 82d8802..f1ab46e 100644 --- a/README.md +++ b/README.md @@ -202,6 +202,7 @@ prints JSON (indented; compact with `--json`) and says what happened in a stable | `reply contact linkedin-connect --linkedin-account-id N [--message -]` | a LinkedIn invitation, with or without a note → `sent` / `already_connected` | | `reply contact linkedin-message …` · `linkedin-inmail …` · `linkedin-voice …` | a LinkedIn message, an InMail, or an AI voice message spoken from a script → `sent` | | any direct send `… [--send-after ] [--schedule-id N] [--idempotency-key K]` | the send held until a moment, timed by a schedule, under a key of yours → `sent`, with its `reference` and `state` | +| a LinkedIn send `… [--use-contact-time-zone \| --no-use-contact-time-zone] [--retry-window-minutes N]` | the schedule read in the contact's time zone or its own, and how long Reply keeps trying once the send is due | | `reply direct-send get ` | a send as Reply holds it: whether it has gone out, when, and why it failed | | `reply direct-send cancel ` | stop a send that has not gone out yet → `state` `cancelled` | | `reply inbox list (--contact-id \| --sequence-id) [--source] [--channel] [--category-id] [--since]` | one page of threads | @@ -338,6 +339,20 @@ the schedule's next opening, so `send_after` is left out, and `estimated_send_at expects to send it, or null when no opening falls within the 30 days it looks ahead. It is added only when Reply gives it. +The four LinkedIn sends also take `--use-contact-time-zone` / `--no-use-contact-time-zone` and +`--retry-window-minutes `; `contact send-email` takes neither. `--use-contact-time-zone` reads the +schedule's windows in the contact's time zone and `--no-use-contact-time-zone` in the schedule's +own; with neither, the schedule's own setting holds. `--retry-window-minutes` is how long Reply keeps +trying to send once the send is due, 1 to 4320 minutes (Reply's default is 90); a number outside +that is refused before any call (`usage.range`). Reply takes them only for a send made later, the +time zone only with `--schedule-id`, and answers them otherwise with `reply.invalid_request`; a +Reply before its LinkedIn scheduler answers `--schedule-id` on a LinkedIn send the same way. + +```sh +echo '{"body":"Following up on my note."}' | reply contact linkedin-message --contact-id 456 --linkedin-account-id 34 --message - --schedule-id 41 --use-contact-time-zone --retry-window-minutes 120 +# {"status":"sent",…,"activity_id":null,"sent_at":null,"reference":"linkedin-scheduled-77","state":"waitingForSchedule","estimated_send_at":"2026-11-04T09:00:00Z"} +``` + `--idempotency-key` goes to Reply as the `Idempotency-Key` header, never in the body. A Reply that knows the header answers a repeat with the same key with the send the key first made; while that one is still being made the answer is `idempotency_key.in_use`, and the same key on a different diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index d5ffed6..ea7bd3e 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -283,7 +283,8 @@ describe('operations/commands', ()=>{ { const c = sub(contact_command, name); expect(flags(c), name).toEqual([...CONTACT_FLAGS, account_flag, '--message', - ...(name === 'send-email' ? ['--track-links', '--track-opens'] : []), '--send-after', '--schedule-id', '--idempotency-key']); + ...(name === 'send-email' ? ['--track-links', '--track-opens'] : []), '--send-after', '--schedule-id', '--idempotency-key', + ...(name === 'send-email' ? [] : ['--use-contact-time-zone', '--no-use-contact-time-zone', '--retry-window-minutes'])]); const text = help_of(c); const flat = text.replace(/\s+/g, ' '); expect(text, text).toContain('--message -'); @@ -305,6 +306,12 @@ describe('operations/commands', ()=>{ expect(flat, text).toContain('direct-send get reads it later, and direct-send cancel stops one not yet sent'); expect(flat.includes('A LinkedIn send timed by --schedule-id may answer state waitingForSchedule'), text).toBe(name !== 'send-email'); expect(flat.includes('estimated_send_at'), text).toBe(name !== 'send-email'); + expect(flat.includes('--use-contact-time-zone sends useContactTimeZone true: the schedule\'s windows are read in the ' + + 'contact\'s time zone; --no-use-contact-time-zone sends false, the schedule\'s own zone; with neither, the schedule\'s ' + + 'own setting holds'), text).toBe(name !== 'send-email'); + expect(flat.includes('--retry-window-minutes is how long Reply keeps trying to send it once it is due, 1 to 4320 ' + + 'minutes (Reply\'s default is 90); one outside that is refused before any call (usage.range)'), text).toBe(name !== 'send-email'); + expect(flat.includes('Reply takes them only with --schedule-id or --send-after'), text).toBe(name !== 'send-email'); expect(flat, text).toContain('An answer without state comes from a Reply that does not know --send-after and --schedule-id'); expect(flat, text).toContain('--idempotency-key goes as the Idempotency-Key header'); expect(flat, text).toContain('A Reply that knows the header answers a repeat with the same key with the send the key first made; while that one is still ' diff --git a/src/__tests__/operations/direct-send.test.ts b/src/__tests__/operations/direct-send.test.ts index 3e5710c..b1bfc58 100644 --- a/src/__tests__/operations/direct-send.test.ts +++ b/src/__tests__/operations/direct-send.test.ts @@ -732,6 +732,56 @@ describe('a send for later', ()=>{ expect(mock_fetch).not.toHaveBeenCalled(); }); + it('a LinkedIn send carries useContactTimeZone, true or false, and retryWindowMinutes only when given, as Reply takes them', async()=>{ + const cases: [Partial, Record][] = [ + [{useContactTimeZone: true}, {useContactTimeZone: true}], + [{useContactTimeZone: false}, {useContactTimeZone: false}], + [{retryWindowMinutes: '1'}, {retryWindowMinutes: 1}], + [{retryWindowMinutes: ' 4320 '}, {retryWindowMinutes: 4320}], + [{useContactTimeZone: true, retryWindowMinutes: '90'}, {useContactTimeZone: true, retryWindowMinutes: 90}], + [{}, {}], + ]; + for (const [name, message, opts] of SENDS.filter(([n])=>n !== 'send-email')) + { + for (const [extra, carried] of cases) + { + mock_fetch.mockReset(); + answer(accepted(name, {})); + await run(name, message, {...opts, ...LATER, ...extra}); + const body = sent()[0].body as Record; + const label = `${name} ${JSON.stringify(extra)}`; + expect(body.scheduleId, label).toBe(41); + expect(Object.fromEntries(Object.entries(body).filter(([k])=>k === 'useContactTimeZone' || k === 'retryWindowMinutes')), label) + .toStrictEqual(carried); + } + } + }); + + it('refuses a retry window outside 1 to 4320 minutes before any call, and leaves the rules between the fields to Reply', async()=>{ + for (const [name, message, opts] of SENDS.filter(([n])=>n !== 'send-email')) + { + for (const raw of ['0', '4321', '-5', '1.5', 'ninety', '', '90m']) + { + const e = await failure(name, message, {...opts, retryWindowMinutes: raw}); + expect(e, `${name} ${JSON.stringify(raw)}`).toMatchObject({code: 'usage.range', exit_code: 2}); + } + } + expect(mock_fetch).not.toHaveBeenCalled(); + // Without --schedule-id or --send-after either goes to Reply as given, for Reply to refuse with errors[]. + answer(json({errors: [{pointer: '/useContactTimeZone', detail: 'Only with scheduleId.'}]}, 400)); + const e = await failure('linkedin-message', {body: TEXT}, {...LINKEDIN_OPTS, useContactTimeZone: true, retryWindowMinutes: '30'}); + expect(sent()[0].body).toMatchObject({useContactTimeZone: true, retryWindowMinutes: 30}); + expect(e).toMatchObject({code: 'reply.invalid_request', exit_code: 1, details: {fields: ['useContactTimeZone']}}); + }); + + it('a direct email never carries either, even when the options reach it', async()=>{ + answer(accepted('send-email', {})); + await run('send-email', {subject: SUBJECT, body: BODY}, {...EMAIL_OPTS, ...LATER, useContactTimeZone: true, retryWindowMinutes: '30'}); + const body = sent()[0].body as Record; + expect('useContactTimeZone' in body).toBe(false); + expect('retryWindowMinutes' in body).toBe(false); + }); + it('a key does not make a lost answer safe to repeat: a Reply that ignores the header would send it twice', async()=>{ mock_fetch.mockRejectedValueOnce(lost_connection()); const e = await failure('send-email', {subject: SUBJECT, body: BODY}, {...EMAIL_OPTS, ...LATER}); diff --git a/src/operations/commands.ts b/src/operations/commands.ts index 6383bfb..bddd896 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -364,18 +364,32 @@ const VARIABLES = (where: string): string=> `Reply reads {{…}} in the ${where} as its template variables; one it cannot fill is linkedin.missing_variables.\n`; const LINKEDIN_EXAMPLE = '--contact-id 456 --linkedin-account-id 34'; -// What a LinkedIn send timed by a schedule answers while it waits for the schedule's next opening. +// The flags only Reply's LinkedIn sends take for a send made later. Without either time-zone flag nothing is sent, so the +// schedule's own setting holds. +const scheduler_options = (c: Command): Command=>c + .option('--use-contact-time-zone', 'Read the schedule\'s windows in the contact\'s time zone (with --schedule-id)') + .option('--no-use-contact-time-zone', 'Read the schedule\'s windows in the schedule\'s own time zone (with --schedule-id)') + .option('--retry-window-minutes ', 'How long Reply keeps trying once the send is due, 1 to 4320 (Reply\'s default: 90)'); + +// What a LinkedIn send timed by a schedule answers while it waits for the schedule's next opening, and the flags only +// a LinkedIn send takes. const SCHEDULED = 'A LinkedIn send timed by --schedule-id may answer state waitingForSchedule, held for the schedule\'s next\n' + 'opening: send_after is then left out, and estimated_send_at is when Reply expects to send it, or null when no opening\n' - + 'falls within the 30 days it looks ahead; it is added only when Reply gives it.\n'; + + 'falls within the 30 days it looks ahead; it is added only when Reply gives it. --use-contact-time-zone sends\n' + + 'useContactTimeZone true: the schedule\'s windows are read in the contact\'s time zone; --no-use-contact-time-zone sends\n' + + 'false, the schedule\'s own zone; with neither, the schedule\'s own setting holds. --retry-window-minutes is how long\n' + + 'Reply keeps trying to send it once it is due, 1 to 4320 minutes (Reply\'s default is 90); one outside that is refused\n' + + 'before any call (usage.range). Reply takes them only with --schedule-id or --send-after, the time zone only with\n' + + '--schedule-id, and answers them otherwise with errors[] (reply.invalid_request), as a Reply before its scheduler\n' + + 'answers --schedule-id on a LinkedIn send.\n'; const linkedin_send = ( name: Exclude, description: string, message: string, examples: string[], codes: string[], extra: string, what: string, ): void=>{ - later_options(add_contact_options(contact_command.command(name), true) + scheduler_options(later_options(add_contact_options(contact_command.command(name), true) .option('--linkedin-account-id ', 'The LinkedIn account to send from (see `account list`)') - .option('--message ', `Only -: the ${message} as JSON on stdin`)) + .option('--message ', `Only -: the ${message} as JSON on stdin`))) .description(description) .addHelpText('after', help(examples, [...LINKEDIN_SEND_CODES, ...codes, ...KEY_CODES], true, extra + LATER + SCHEDULED + SENT_TO('linkedin', what), SEND_TWICE(what))) diff --git a/src/operations/direct-send.ts b/src/operations/direct-send.ts index 0cb866f..f0bc283 100644 --- a/src/operations/direct-send.ts +++ b/src/operations/direct-send.ts @@ -2,7 +2,7 @@ import {PROGRAM_NAME} from '../config'; import {Operation_error, Unknown_outcome_error, UsageError, type Ids} from '../utils/errors'; import {parse_retry_after} from '../utils/client'; import {call_reply, expect_object, refusal, is_object, reply_code_of, detail_of, open_session, type Answer} from './call'; -import {parse_id, parse_moment, parse_idempotency_key, LARGEST_SAFE_ID, type Op_globals} from './options'; +import {parse_id, parse_int_in, parse_moment, parse_idempotency_key, LARGEST_SAFE_ID, type Op_globals} from './options'; import {read_contact_input, type Contact_flags, type Contact_ref} from './contact-input'; import {contact_not_found, find_contact_by_address, import_contact, type Channel, type Ensured} from './contacts'; import {read_stdin_object, stdin_inputs} from './stdin-input'; @@ -13,6 +13,7 @@ type Direct_send_name = 'send-email' | 'linkedin-connect' | 'linkedin-message' | type Direct_send_opts = Contact_flags & { emailAccountId?: string; linkedinAccountId?: string; message?: string; sendAfter?: string; scheduleId?: string; idempotencyKey?: string; trackLinks?: boolean; trackOpens?: boolean; + useContactTimeZone?: boolean; retryWindowMinutes?: string; }; type Text = Record; @@ -373,6 +374,15 @@ const handle_direct_send = async( { later.scheduleId = parse_id(opts.scheduleId, '--schedule-id'); } + // Only Reply's LinkedIn routes take these. Which other flag each needs is Reply's rule, refused there with errors[]. + if (by === 'linkedin' && opts.useContactTimeZone !== undefined) + { + later.useContactTimeZone = opts.useContactTimeZone; + } + if (by === 'linkedin' && opts.retryWindowMinutes !== undefined) + { + later.retryWindowMinutes = parse_int_in(opts.retryWindowMinutes, '--retry-window-minutes', 1, 4320, 0); + } // Reply tracks neither unless asked, so each is sent only to turn it on. if (opts.trackLinks === true) { From b88e269db392561fdc09612b977874755e4fc481 Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 21:57:50 -0700 Subject: [PATCH 06/15] feat: the LinkedIn sends map Reply's three refusals of a send it cannot 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. --- README.md | 4 ++++ src/__tests__/operations/commands.test.ts | 6 +++++- src/__tests__/operations/direct-send.test.ts | 5 +++++ src/operations/commands.ts | 7 +++++-- src/operations/direct-send.ts | 10 ++++++++++ 5 files changed, 29 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f1ab46e..035cc07 100644 --- a/README.md +++ b/README.md @@ -347,6 +347,10 @@ trying to send once the send is due, 1 to 4320 minutes (Reply's default is 90); that is refused before any call (`usage.range`). Reply takes them only for a send made later, the time zone only with `--schedule-id`, and answers them otherwise with `reply.invalid_request`; a Reply before its LinkedIn scheduler answers `--schedule-id` on a LinkedIn send the same way. +Reply refuses a LinkedIn send it cannot time when it takes it, and nothing is sent: `--schedule-id` +naming no schedule is `schedule.not_found`, a schedule with no window Reply can send in is +`schedule.no_slot`, and a contact without the time zone `--use-contact-time-zone` reads the +schedule in is `contact.time_zone_missing`. ```sh echo '{"body":"Following up on my note."}' | reply contact linkedin-message --contact-id 456 --linkedin-account-id 34 --message - --schedule-id 41 --use-contact-time-zone --retry-window-minutes 120 diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index ea7bd3e..87cd605 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -253,7 +253,8 @@ describe('operations/commands', ()=>{ // says sent_at is. const IMPORT = ['contact.not_unique', 'contact.invalid_email', 'contact.invalid_linkedin_url', 'account.contact_limit_reached']; const LINKEDIN = ['contact.not_found', ...IMPORT, 'contact.already_held', 'contact.no_linkedin_profile', 'linkedin.account_not_found', - 'linkedin.feature_disabled', 'linkedin.account_inactive', 'linkedin.invalid_cookie']; + 'linkedin.feature_disabled', 'linkedin.account_inactive', 'linkedin.invalid_cookie', 'schedule.not_found', 'schedule.no_slot', + 'contact.time_zone_missing']; const SENT_AT_AS_GIVEN = 'sentAtUtc as Reply gives them, each null when it gives none; the CLI adds no time of its own'; const DIRECT_SENDS: [string, string, string[], string][] = [ ['send-email', '--email-account-id', ['contact.not_found', ...IMPORT, 'contact.already_held', 'email_account.not_found', 'contact.blacklisted', @@ -312,6 +313,9 @@ describe('operations/commands', ()=>{ expect(flat.includes('--retry-window-minutes is how long Reply keeps trying to send it once it is due, 1 to 4320 ' + 'minutes (Reply\'s default is 90); one outside that is refused before any call (usage.range)'), text).toBe(name !== 'send-email'); expect(flat.includes('Reply takes them only with --schedule-id or --send-after'), text).toBe(name !== 'send-email'); + expect(flat.includes('schedule.not_found is a --schedule-id Reply has no schedule for, schedule.no_slot a schedule with ' + + 'no window Reply can send in, and contact.time_zone_missing a contact without the time zone ' + + '--use-contact-time-zone reads it in; none sends anything'), text).toBe(name !== 'send-email'); expect(flat, text).toContain('An answer without state comes from a Reply that does not know --send-after and --schedule-id'); expect(flat, text).toContain('--idempotency-key goes as the Idempotency-Key header'); expect(flat, text).toContain('A Reply that knows the header answers a repeat with the same key with the send the key first made; while that one is still ' diff --git a/src/__tests__/operations/direct-send.test.ts b/src/__tests__/operations/direct-send.test.ts index b1bfc58..b77cff5 100644 --- a/src/__tests__/operations/direct-send.test.ts +++ b/src/__tests__/operations/direct-send.test.ts @@ -156,6 +156,11 @@ describe('the LinkedIn sends', ()=>{ [['linkedin-inmail', {subject: SUBJECT, body: TEXT}], 400, 'directLinkedIn.noInMailCredits', 'linkedin.no_inmail_credits'], [['linkedin-voice', {script: SCRIPT}], 400, 'directLinkedIn.voiceProfileMissing', 'linkedin.voice_profile_missing'], [['linkedin-voice', {script: SCRIPT}], 400, 'directLinkedIn.voiceTooLong', 'linkedin.voice_too_long'], + [message, 404, 'directLinkedIn.scheduleNotFound', 'schedule.not_found'], + [['linkedin-connect', {note: NOTE}], 409, 'directLinkedIn.scheduleHasNoSlot', 'schedule.no_slot'], + [['linkedin-voice', {script: SCRIPT}], 409, 'directLinkedIn.contactTimeZoneMissing', 'contact.time_zone_missing'], + [message, 400, 'directLinkedIn.scheduleNotFound', 'reply.refused'], + [message, 404, 'directLinkedIn.contactTimeZoneMissing', 'reply.refused'], // Reply's code is read only under the status it publishes it with. [message, 400, 'directLinkedIn.notConnected', 'reply.refused'], [message, 403, 'directLinkedIn.somethingElse', 'access.denied'], diff --git a/src/operations/commands.ts b/src/operations/commands.ts index bddd896..1424e8b 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -355,7 +355,8 @@ later_options(add_contact_options(contact_command.command('send-email'), true) // The four LinkedIn sends share their flags, their first codes and the shape of their result. const LINKEDIN_SEND_CODES = [ 'contact.not_found', ...IMPORT_CODES, 'contact.already_held', 'contact.no_linkedin_profile', 'linkedin.account_not_found', - 'linkedin.feature_disabled', 'linkedin.account_inactive', 'linkedin.invalid_cookie', + 'linkedin.feature_disabled', 'linkedin.account_inactive', 'linkedin.invalid_cookie', 'schedule.not_found', 'schedule.no_slot', + 'contact.time_zone_missing', ]; const LINKEDIN_SENT = '"contact_id","contact_created","activity_id","sent_at"}:\n' + 'activity_id and sent_at are Reply\'s linkedInActivityId and sentAtUtc as Reply gives them, each null when it gives\n' @@ -381,7 +382,9 @@ const SCHEDULED = 'A LinkedIn send timed by --schedule-id may answer state waiti + 'Reply keeps trying to send it once it is due, 1 to 4320 minutes (Reply\'s default is 90); one outside that is refused\n' + 'before any call (usage.range). Reply takes them only with --schedule-id or --send-after, the time zone only with\n' + '--schedule-id, and answers them otherwise with errors[] (reply.invalid_request), as a Reply before its scheduler\n' - + 'answers --schedule-id on a LinkedIn send.\n'; + + 'answers --schedule-id on a LinkedIn send. schedule.not_found is a --schedule-id Reply has no schedule for,\n' + + 'schedule.no_slot a schedule with no window Reply can send in, and contact.time_zone_missing a contact without the\n' + + 'time zone --use-contact-time-zone reads it in; none sends anything.\n'; const linkedin_send = ( name: Exclude, description: string, message: string, examples: string[], codes: string[], diff --git a/src/operations/direct-send.ts b/src/operations/direct-send.ts index f0bc283..1d8abdb 100644 --- a/src/operations/direct-send.ts +++ b/src/operations/direct-send.ts @@ -176,6 +176,16 @@ const REFUSALS: Record = { 'directLinkedIn.voiceTooLong': { status: 400, code: 'linkedin.voice_too_long', title: 'The voice message would be longer than Reply allows, so nothing was sent.', }, + // A LinkedIn send timed by a schedule: refused when it is taken, before anything is held. + 'directLinkedIn.scheduleNotFound': { + status: 404, code: 'schedule.not_found', title: 'Reply has no sending schedule by that id that this account can use, so nothing was sent.', + }, + 'directLinkedIn.scheduleHasNoSlot': { + status: 409, code: 'schedule.no_slot', title: 'The sending schedule has no window Reply can send in, so nothing was sent.', + }, + 'directLinkedIn.contactTimeZoneMissing': { + status: 409, code: 'contact.time_zone_missing', title: 'Reply holds no time zone for the contact to read the schedule in, so nothing was sent.', + }, }; const LIMITS: Record = {'directLinkedIn.dailyLimitReached': 'daily', 'directLinkedIn.weeklyLimitReached': 'weekly'}; From 6aaaf8faac2d84eae0c460899f602486d5445ca2 Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 22:02:44 -0700 Subject: [PATCH 07/15] fix: direct-send cancel says an unconfirmed cancel left the send waiting 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. --- README.md | 4 ++-- src/__tests__/operations/commands.test.ts | 4 ++-- src/__tests__/operations/direct-sends.test.ts | 8 +++++--- src/operations/commands.ts | 3 ++- src/operations/direct-send.ts | 9 +++++---- 5 files changed, 16 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 035cc07..d1b04dc 100644 --- a/README.md +++ b/README.md @@ -387,8 +387,8 @@ added only when Reply gives them, and so is `estimated_send_at`, read the same w again. A send already gone out, failed or going out is `direct_send.already_sent`, `direct_send.already_failed` or `direct_send.already_sending`, and a reference Reply has no send for is `direct_send.not_found`. A `503` that Reply answers with `directSend.cancelNotConfirmed` is -`direct_send.cancel_not_confirmed` (exit 1): Reply could not confirm the cancel, so it may not have -taken, and running it again is safe; `retry_after` carries Reply's `Retry-After` when it sends one. +`direct_send.cancel_not_confirmed` (exit 1): Reply could not confirm the cancel, and says the send is +still queued or waiting for its schedule, so run the cancel again, as Reply asks; `retry_after` carries Reply's `Retry-After` when it sends one. Any other `5xx` to a cancel stays `outcome.unknown` (exit 3). `reply inbox changes` reads the inbox feed forward. Each page holds the threads whose latest message, diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index 87cd605..7d9fa30 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -63,8 +63,8 @@ describe('operations/commands', ()=>{ expect(cancel).toContain('Cancelling a send already cancelled answers it again, so running it again is safe'); expect(cancel).toContain('direct_send.already_sent, direct_send.already_failed and direct_send.already_sending mean the send ' + 'was past cancelling; nothing changed'); - expect(cancel).toContain('direct_send.cancel_not_confirmed is a 503 from Reply that could not confirm the cancel: it may not ' - + 'have taken, and running it again is safe; retry_after carries Reply\'s Retry-After when it sends one. Any other 5xx ' + expect(cancel).toContain('direct_send.cancel_not_confirmed is a 503 from Reply that could not confirm the cancel: the send ' + + 'is still queued or waiting for its schedule, so run the cancel again, as Reply asks; retry_after carries Reply\'s Retry-After when it sends one. Any other 5xx ' + 'is outcome.unknown (exit 3)'); }); diff --git a/src/__tests__/operations/direct-sends.test.ts b/src/__tests__/operations/direct-sends.test.ts index 24a81c1..bd53841 100644 --- a/src/__tests__/operations/direct-sends.test.ts +++ b/src/__tests__/operations/direct-sends.test.ts @@ -300,8 +300,8 @@ describe('direct-send cancel', ()=>{ } }); - it('a 503 directSend.cancelNotConfirmed is direct_send.cancel_not_confirmed (exit 1), made once, says running it again ' - + 'is safe, and passes on Reply\'s wait', async()=>{ + it('a 503 directSend.cancelNotConfirmed is direct_send.cancel_not_confirmed (exit 1), made once, says the send is still ' + + 'waiting and to cancel again, and passes on Reply\'s wait', async()=>{ const cases: [Record, number | undefined][] = [[{}, undefined], [{'Retry-After': '5'}, 5]]; for (const [headers, retry_after] of cases) { @@ -313,7 +313,9 @@ describe('direct-send cancel', ()=>{ detail: 'The cancel could not be confirmed.', }); expect((e as {retry_after?: number}).retry_after, JSON.stringify(headers)).toBe(retry_after); - expect((e as {hint?: string}).hint ?? '').toContain('running it again is safe'); + expect((e as {title?: string}).title).toBe('Reply could not confirm the cancel; the send is still waiting to go out.'); + expect((e as {hint?: string}).hint).toBe('Reply says the send is still queued or waiting for its schedule: run the ' + + 'cancel again, as Reply asks; running it again is safe.'); expect(mock_fetch).toHaveBeenCalledTimes(1); } }); diff --git a/src/operations/commands.ts b/src/operations/commands.ts index 1424e8b..6a66163 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -634,7 +634,8 @@ direct_send_command.command('cancel') DIRECT_SEND + 'The answer is the send as Reply now holds it, state cancelled. Cancelling a send already cancelled answers\n' + 'it again, so running it again is safe. direct_send.already_sent, direct_send.already_failed and\n' + 'direct_send.already_sending mean the send was past cancelling; nothing changed. direct_send.cancel_not_confirmed\n' - + 'is a 503 from Reply that could not confirm the cancel: it may not have taken, and running it again is safe;\n' + + 'is a 503 from Reply that could not confirm the cancel: the send is still queued or waiting for its schedule, so\n' + + 'run the cancel again, as Reply asks;\n' + 'retry_after carries Reply\'s Retry-After when it sends one. Any other 5xx is outcome.unknown (exit 3).\n')) .action(run(async(cmd)=>{ const {g, ctx} = ctx_of(cmd); diff --git a/src/operations/direct-send.ts b/src/operations/direct-send.ts index 1d8abdb..b20df39 100644 --- a/src/operations/direct-send.ts +++ b/src/operations/direct-send.ts @@ -226,12 +226,13 @@ const DIRECT_SEND_REFUSALS: Record = { status: 409, code: 'direct_send.already_sending', title: 'The direct send is already going out, so it was not cancelled.', }, }; -// A cancel Reply could not confirm: it may not have taken, and Reply says repeating it is safe, so it is a refusal of its -// own rather than an outcome left unknown. Only a cancel answers it; a read answering this code maps as any other 5xx. +// A cancel Reply could not confirm: Reply says the send is still queued or waiting for its schedule and asks for the +// cancel again, so it is a refusal of its own rather than an outcome left unknown. Only a cancel answers it; a read +// answering this code maps as any other 5xx. const CANCEL_REFUSALS: Record = { 'directSend.cancelNotConfirmed': { - status: 503, code: 'direct_send.cancel_not_confirmed', title: 'Reply could not confirm the cancel; it may not have taken.', - hint: 'The send may or may not have been cancelled; running it again is safe, and direct-send get reads where it stands.', + status: 503, code: 'direct_send.cancel_not_confirmed', title: 'Reply could not confirm the cancel; the send is still waiting to go out.', + hint: 'Reply says the send is still queued or waiting for its schedule: run the cancel again, as Reply asks; running it again is safe.', waits: true, }, }; From e3661116011c1a876e284cca0670a81dfd19e239 Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 22:04:23 -0700 Subject: [PATCH 08/15] docs: direct-send help words the schedule, ownership and sending refusals 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. --- README.md | 11 +++++++---- src/__tests__/operations/commands.test.ts | 8 ++++++-- src/__tests__/operations/direct-send.test.ts | 4 ++++ src/__tests__/operations/direct-sends.test.ts | 5 +++++ src/operations/commands.ts | 13 ++++++++----- src/operations/direct-send.ts | 2 +- 6 files changed, 31 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index d1b04dc..9ecee23 100644 --- a/README.md +++ b/README.md @@ -348,8 +348,8 @@ that is refused before any call (`usage.range`). Reply takes them only for a sen time zone only with `--schedule-id`, and answers them otherwise with `reply.invalid_request`; a Reply before its LinkedIn scheduler answers `--schedule-id` on a LinkedIn send the same way. Reply refuses a LinkedIn send it cannot time when it takes it, and nothing is sent: `--schedule-id` -naming no schedule is `schedule.not_found`, a schedule with no window Reply can send in is -`schedule.no_slot`, and a contact without the time zone `--use-contact-time-zone` reads the +naming no schedule this account can read is `schedule.not_found`, a schedule with no active day +that has a time range, so it never opens, is `schedule.no_slot`, and a contact without the time zone `--use-contact-time-zone` reads the schedule in is `contact.time_zone_missing`. ```sh @@ -385,8 +385,11 @@ added only when Reply gives them, and so is `estimated_send_at`, read the same w `failure_code` is Reply's code for the failure, the one to branch on. A failed send may carry no `failure_code`: it is then null, and `failure_reason` is all Reply says of it. `direct-send cancel` of a send already cancelled answers it again. A send already gone out, failed or going out is `direct_send.already_sent`, -`direct_send.already_failed` or `direct_send.already_sending`, and a reference Reply has no send for -is `direct_send.not_found`. A `503` that Reply answers with `directSend.cancelNotConfirmed` is +`direct_send.already_failed` or `direct_send.already_sending`; the last is a LinkedIn send made for +later that Reply is handing to the account's queue or that waits or runs there, even while +`direct-send get` still reads it `queued`. A reference Reply has no send for, a send of another +team included, is `direct_send.not_found`, and an email send made by a teammate this user may not +act for is `direct_send.not_owned`, to a read and a cancel alike. A `503` that Reply answers with `directSend.cancelNotConfirmed` is `direct_send.cancel_not_confirmed` (exit 1): Reply could not confirm the cancel, and says the send is still queued or waiting for its schedule, so run the cancel again, as Reply asks; `retry_after` carries Reply's `Retry-After` when it sends one. Any other `5xx` to a cancel stays `outcome.unknown` (exit 3). diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index 7d9fa30..b8c1b3a 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -52,6 +52,8 @@ describe('operations/commands', ()=>{ expect(flat, name).toContain('email-, linkedin- or linkedin-scheduled-, the form Reply\'s route takes'); expect(flat, name).toContain('any other form is refused before any call (usage.reference, exit 2), and nothing else is read from it'); expect(flat, name).toContain('a reference of any other form never leaves the CLI, so that 404 means this Reply has no such route'); + expect(flat, name).toContain('direct_send.not_found is a reference that Reply has no send for, a send of another team ' + + 'included. direct_send.not_owned is an email send made by a teammate this user may not act for'); expect(flat, name).not.toContain('step up'); expect(c.registeredArguments[0].description, name).toContain('email-, linkedin- or linkedin-scheduled-'); expect(flat, name).toContain('failure_code, missing_variables, rendered_subject and rendered_body are added only when Reply gives them'); @@ -63,6 +65,8 @@ describe('operations/commands', ()=>{ expect(cancel).toContain('Cancelling a send already cancelled answers it again, so running it again is safe'); expect(cancel).toContain('direct_send.already_sent, direct_send.already_failed and direct_send.already_sending mean the send ' + 'was past cancelling; nothing changed'); + expect(cancel).toContain('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 direct-send get still reads it queued'); expect(cancel).toContain('direct_send.cancel_not_confirmed is a 503 from Reply that could not confirm the cancel: the send ' + 'is still queued or waiting for its schedule, so run the cancel again, as Reply asks; retry_after carries Reply\'s Retry-After when it sends one. Any other 5xx ' + 'is outcome.unknown (exit 3)'); @@ -313,8 +317,8 @@ describe('operations/commands', ()=>{ expect(flat.includes('--retry-window-minutes is how long Reply keeps trying to send it once it is due, 1 to 4320 ' + 'minutes (Reply\'s default is 90); one outside that is refused before any call (usage.range)'), text).toBe(name !== 'send-email'); expect(flat.includes('Reply takes them only with --schedule-id or --send-after'), text).toBe(name !== 'send-email'); - expect(flat.includes('schedule.not_found is a --schedule-id Reply has no schedule for, schedule.no_slot a schedule with ' - + 'no window Reply can send in, and contact.time_zone_missing a contact without the time zone ' + expect(flat.includes('schedule.not_found is a --schedule-id naming no schedule this account can read, schedule.no_slot a ' + + 'schedule with no active day that has a time range, so it never opens, and contact.time_zone_missing a contact without the time zone ' + '--use-contact-time-zone reads it in; none sends anything'), text).toBe(name !== 'send-email'); expect(flat, text).toContain('An answer without state comes from a Reply that does not know --send-after and --schedule-id'); expect(flat, text).toContain('--idempotency-key goes as the Idempotency-Key header'); diff --git a/src/__tests__/operations/direct-send.test.ts b/src/__tests__/operations/direct-send.test.ts index b77cff5..1340227 100644 --- a/src/__tests__/operations/direct-send.test.ts +++ b/src/__tests__/operations/direct-send.test.ts @@ -176,6 +176,10 @@ describe('the LinkedIn sends', ()=>{ expect(shown(e), shown(e)).not.toContain('Marta'); expect(mock_fetch, `${name} ${reply_code}`).toHaveBeenCalledTimes(1); } + mock_fetch.mockReset(); + answer(json({status: 409, code: 'directLinkedIn.scheduleHasNoSlot'}, 409)); + expect((await failure('linkedin-message', {body: TEXT}, LINKEDIN_OPTS) as {title?: string}).title) + .toBe('The sending schedule has no active day with a time range, so it never opens; nothing was sent.'); }); it('reads contact-not-found, the limits and already-connected only under the status Reply publishes each with', async()=>{ diff --git a/src/__tests__/operations/direct-sends.test.ts b/src/__tests__/operations/direct-sends.test.ts index bd53841..53176cc 100644 --- a/src/__tests__/operations/direct-sends.test.ts +++ b/src/__tests__/operations/direct-sends.test.ts @@ -103,6 +103,11 @@ describe('direct-send get', ()=>{ [{state: 'failed', failureCode: 'directSend.dispatchWindowMissed'}, {state: 'failed', failure_code: 'directSend.dispatchWindowMissed'}], [{state: 'failed', failureCode: 'directSend.dispatchInterrupted'}, {state: 'failed', failure_code: 'directSend.dispatchInterrupted'}], [{state: 'failed', failureCode: 'directLinkedIn.notConnected'}, {state: 'failed', failure_code: 'directLinkedIn.notConnected'}], + [{state: 'failed', failureCode: 'directLinkedIn.contactNotFound'}, {state: 'failed', failure_code: 'directLinkedIn.contactNotFound'}], + [{state: 'failed', failureCode: 'directLinkedIn.scheduleNotFound'}, {state: 'failed', failure_code: 'directLinkedIn.scheduleNotFound'}], + [{state: 'failed', failureCode: 'directLinkedIn.contactTimeZoneMissing'}, + {state: 'failed', failure_code: 'directLinkedIn.contactTimeZoneMissing'}], + [{state: 'failed', failureCode: 'directLinkedIn.aCodeNotYetKnown'}, {state: 'failed', failure_code: 'directLinkedIn.aCodeNotYetKnown'}], [{state: 'cancelled', cancelledAt: '2026-11-02T09:15:00Z'}, {state: 'cancelled', cancelled_at: '2026-11-02T09:15:00Z'}], ]; for (const [given, read] of cases) diff --git a/src/operations/commands.ts b/src/operations/commands.ts index 6a66163..1de7471 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -382,9 +382,9 @@ const SCHEDULED = 'A LinkedIn send timed by --schedule-id may answer state waiti + 'Reply keeps trying to send it once it is due, 1 to 4320 minutes (Reply\'s default is 90); one outside that is refused\n' + 'before any call (usage.range). Reply takes them only with --schedule-id or --send-after, the time zone only with\n' + '--schedule-id, and answers them otherwise with errors[] (reply.invalid_request), as a Reply before its scheduler\n' - + 'answers --schedule-id on a LinkedIn send. schedule.not_found is a --schedule-id Reply has no schedule for,\n' - + 'schedule.no_slot a schedule with no window Reply can send in, and contact.time_zone_missing a contact without the\n' - + 'time zone --use-contact-time-zone reads it in; none sends anything.\n'; + + 'answers --schedule-id on a LinkedIn send. schedule.not_found is a --schedule-id naming no schedule this account can\n' + + 'read, schedule.no_slot a schedule with no active day that has a time range, so it never opens, and\n' + + 'contact.time_zone_missing a contact without the time zone --use-contact-time-zone reads it in; none sends anything.\n'; const linkedin_send = ( name: Exclude, description: string, message: string, examples: string[], codes: string[], @@ -614,7 +614,8 @@ const DIRECT_SEND = 'Result: {"reference","channel","contact_id","state","send_a + 'for its schedule\'s next opening to go out, or null when no opening falls within the 30 days it looks ahead.\n' + 'A Reply without this route answers reply.refused with status 404 and no reply_code; a\n' + 'reference of any other form never leaves the CLI, so that 404 means this Reply has no such route.\n' - + 'direct_send.not_found is a reference that Reply has no send for.\n'; + + 'direct_send.not_found is a reference that Reply has no send for, a send of another team included.\n' + + 'direct_send.not_owned is an email send made by a teammate this user may not act for.\n'; direct_send_command.command('get') .argument('', 'The send\'s reference, email-, linkedin- or linkedin-scheduled-, as a send made with --send-after answered it') @@ -633,7 +634,9 @@ direct_send_command.command('cancel') 'direct_send.already_sending', 'direct_send.cancel_not_confirmed'], true, DIRECT_SEND + 'The answer is the send as Reply now holds it, state cancelled. Cancelling a send already cancelled answers\n' + 'it again, so running it again is safe. direct_send.already_sent, direct_send.already_failed and\n' - + 'direct_send.already_sending mean the send was past cancelling; nothing changed. direct_send.cancel_not_confirmed\n' + + 'direct_send.already_sending mean the send was past cancelling; nothing changed. direct_send.already_sending is a\n' + + 'LinkedIn send made for later that Reply is handing to the account\'s queue or that waits or runs there, even while\n' + + 'direct-send get still reads it queued. direct_send.cancel_not_confirmed\n' + 'is a 503 from Reply that could not confirm the cancel: the send is still queued or waiting for its schedule, so\n' + 'run the cancel again, as Reply asks;\n' + 'retry_after carries Reply\'s Retry-After when it sends one. Any other 5xx is outcome.unknown (exit 3).\n')) diff --git a/src/operations/direct-send.ts b/src/operations/direct-send.ts index b20df39..6fa2385 100644 --- a/src/operations/direct-send.ts +++ b/src/operations/direct-send.ts @@ -181,7 +181,7 @@ const REFUSALS: Record = { status: 404, code: 'schedule.not_found', title: 'Reply has no sending schedule by that id that this account can use, so nothing was sent.', }, 'directLinkedIn.scheduleHasNoSlot': { - status: 409, code: 'schedule.no_slot', title: 'The sending schedule has no window Reply can send in, so nothing was sent.', + status: 409, code: 'schedule.no_slot', title: 'The sending schedule has no active day with a time range, so it never opens; nothing was sent.', }, 'directLinkedIn.contactTimeZoneMissing': { status: 409, code: 'contact.time_zone_missing', title: 'Reply holds no time zone for the contact to read the schedule in, so nothing was sent.', From 04cdbbf13dde0c8f0cce1f2ee054dbf4a897e067 Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 22:06:32 -0700 Subject: [PATCH 09/15] docs: estimated_send_at counts its 30 days from the moment the send waits 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. --- README.md | 8 +++++--- src/__tests__/operations/commands.test.ts | 5 ++++- src/operations/commands.ts | 8 +++++--- src/operations/direct-send.ts | 2 +- 4 files changed, 15 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 9ecee23..f313df3 100644 --- a/README.md +++ b/README.md @@ -336,8 +336,9 @@ not know these flags yet: it sent at once, as without them. A LinkedIn send timed by `--schedule-id` may answer `state` `waitingForSchedule`: Reply holds it for the schedule's next opening, so `send_after` is left out, and `estimated_send_at` is when Reply -expects to send it, or null when no opening falls within the 30 days it looks ahead. It is added -only when Reply gives it. +expects to send it, an ISO-8601 UTC moment, or null when the schedule does not open within 30 days +of the moment the send waits from: its `--send-after`, or when Reply took it. Reply sends it within +about 10 minutes of that moment. It is added only when Reply gives it. The four LinkedIn sends also take `--use-contact-time-zone` / `--no-use-contact-time-zone` and `--retry-window-minutes `; `contact send-email` takes neither. `--use-contact-time-zone` reads the @@ -380,7 +381,8 @@ reply direct-send cancel linkedin-1042 Both answer the send under the CLI's names, each null when Reply gives none: `reference`, `channel`, `contact_id`, `state`, `send_after`, `sent_at`, `message_id`, `failure_reason` and `cancelled_at`. `failure_code`, `missing_variables`, `rendered_subject` and `rendered_body` are -added only when Reply gives them, and so is `estimated_send_at`, read the same way as on the send. +added only when Reply gives them, and so is `estimated_send_at`, read the same way as on the send +but as of the read: its 30 days then count from `--send-after`, or from now once that has passed. `failure_reason` is a sentence for a person and never parsed; `failure_code` is Reply's code for the failure, the one to branch on. A failed send may carry no `failure_code`: it is then null, and `failure_reason` is all Reply says of it. `direct-send cancel` of a send already cancelled answers it diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index b8c1b3a..45e79a7 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -59,7 +59,8 @@ describe('operations/commands', ()=>{ expect(flat, name).toContain('failure_code, missing_variables, rendered_subject and rendered_body are added only when Reply gives them'); expect(flat, name).toContain('failure_reason is a sentence for a person, never parsed; failure_code is Reply\'s code for the failure'); expect(flat, name).toContain('estimated_send_at is added only when Reply gives it: when Reply expects a send waiting for its ' - + 'schedule\'s next opening to go out, or null when no opening falls within the 30 days it looks ahead'); + + 'schedule\'s next opening to go out, or null when the schedule does not open within 30 days of the moment the send ' + + 'waits from: its --send-after, or now once that has passed'); } const cancel = help_of(sub(direct_send_command, 'cancel')).replace(/\s+/g, ' '); expect(cancel).toContain('Cancelling a send already cancelled answers it again, so running it again is safe'); @@ -311,6 +312,8 @@ describe('operations/commands', ()=>{ expect(flat, text).toContain('direct-send get reads it later, and direct-send cancel stops one not yet sent'); expect(flat.includes('A LinkedIn send timed by --schedule-id may answer state waitingForSchedule'), text).toBe(name !== 'send-email'); expect(flat.includes('estimated_send_at'), text).toBe(name !== 'send-email'); + expect(flat.includes('estimated_send_at is when Reply expects to send it, or null when the schedule does not open within ' + + '30 days of the moment the send waits from: its --send-after, or when Reply took it'), text).toBe(name !== 'send-email'); expect(flat.includes('--use-contact-time-zone sends useContactTimeZone true: the schedule\'s windows are read in the ' + 'contact\'s time zone; --no-use-contact-time-zone sends false, the schedule\'s own zone; with neither, the schedule\'s ' + 'own setting holds'), text).toBe(name !== 'send-email'); diff --git a/src/operations/commands.ts b/src/operations/commands.ts index 1de7471..1ac1f4c 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -375,8 +375,9 @@ const scheduler_options = (c: Command): Command=>c // What a LinkedIn send timed by a schedule answers while it waits for the schedule's next opening, and the flags only // a LinkedIn send takes. const SCHEDULED = 'A LinkedIn send timed by --schedule-id may answer state waitingForSchedule, held for the schedule\'s next\n' - + 'opening: send_after is then left out, and estimated_send_at is when Reply expects to send it, or null when no opening\n' - + 'falls within the 30 days it looks ahead; it is added only when Reply gives it. --use-contact-time-zone sends\n' + + 'opening: send_after is then left out, and estimated_send_at is when Reply expects to send it, or null when the\n' + + 'schedule does not open within 30 days of the moment the send waits from: its --send-after, or when Reply took it.\n' + + 'estimated_send_at is added only when Reply gives it. --use-contact-time-zone sends\n' + 'useContactTimeZone true: the schedule\'s windows are read in the contact\'s time zone; --no-use-contact-time-zone sends\n' + 'false, the schedule\'s own zone; with neither, the schedule\'s own setting holds. --retry-window-minutes is how long\n' + 'Reply keeps trying to send it once it is due, 1 to 4320 minutes (Reply\'s default is 90); one outside that is refused\n' @@ -611,7 +612,8 @@ const DIRECT_SEND = 'Result: {"reference","channel","contact_id","state","send_a + 'branch on. A failed send may carry no failure_code: it is then null, and failure_reason is all Reply says of it.\n' + 'missing_variables lists the template variables Reply could not fill, and rendered_subject and rendered_body are the\n' + 'text as Reply filled it in. estimated_send_at is added only when Reply gives it: when Reply expects a send waiting\n' - + 'for its schedule\'s next opening to go out, or null when no opening falls within the 30 days it looks ahead.\n' + + 'for its schedule\'s next opening to go out, or null when the schedule does not open within 30 days of the moment the\n' + + 'send waits from: its --send-after, or now once that has passed.\n' + 'A Reply without this route answers reply.refused with status 404 and no reply_code; a\n' + 'reference of any other form never leaves the CLI, so that 404 means this Reply has no such route.\n' + 'direct_send.not_found is a reference that Reply has no send for, a send of another team included.\n' diff --git a/src/operations/direct-send.ts b/src/operations/direct-send.ts index 6fa2385..9ead372 100644 --- a/src/operations/direct-send.ts +++ b/src/operations/direct-send.ts @@ -307,7 +307,7 @@ const HELD_KEYS: [string, string][] = [['reference', 'reference'], ['sendAfter', const LATER_KEYS: [string, string][] = [...HELD_KEYS, ['renderedSubject', 'rendered_subject'], ['renderedBody', 'rendered_body']]; // When Reply expects a send waiting for its schedule's next opening to go out, as text, or null when no opening falls -// within the 30 days it looks ahead; left out when Reply gives neither, as a Reply before its scheduler does. +// within 30 days of the moment the send waits from; left out when Reply gives neither, as a Reply before its scheduler does. const estimated_of = (from: Record): Record=> typeof from.estimatedSendAt === 'string' || from.estimatedSendAt === null ? {estimated_send_at: from.estimatedSendAt} : {}; From 4921023a0bfb3f2d4bb3e7fdd17ef35598ceae99 Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 22:08:21 -0700 Subject: [PATCH 10/15] docs: estimated_send_at means something only while a send waits for its 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. --- README.md | 7 +++++-- src/__tests__/operations/commands.test.ts | 5 +++++ src/operations/commands.ts | 8 ++++++-- 3 files changed, 16 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f313df3..9aee08a 100644 --- a/README.md +++ b/README.md @@ -338,7 +338,9 @@ A LinkedIn send timed by `--schedule-id` may answer `state` `waitingForSchedule` the schedule's next opening, so `send_after` is left out, and `estimated_send_at` is when Reply expects to send it, an ISO-8601 UTC moment, or null when the schedule does not open within 30 days of the moment the send waits from: its `--send-after`, or when Reply took it. Reply sends it within -about 10 minutes of that moment. It is added only when Reply gives it. +about 10 minutes of that moment. `estimated_send_at` means something only with `state` +`waitingForSchedule`, where null says the schedule does not open within those 30 days; Reply gives +it null on any other state, and that null says nothing. It is added only when Reply gives it. The four LinkedIn sends also take `--use-contact-time-zone` / `--no-use-contact-time-zone` and `--retry-window-minutes `; `contact send-email` takes neither. `--use-contact-time-zone` reads the @@ -382,7 +384,8 @@ Both answer the send under the CLI's names, each null when Reply gives none: `re `channel`, `contact_id`, `state`, `send_after`, `sent_at`, `message_id`, `failure_reason` and `cancelled_at`. `failure_code`, `missing_variables`, `rendered_subject` and `rendered_body` are added only when Reply gives them, and so is `estimated_send_at`, read the same way as on the send -but as of the read: its 30 days then count from `--send-after`, or from now once that has passed. +but as of the read: its 30 days then count from `--send-after`, or from now once that has passed, +and it means something only while `state` is `waitingForSchedule`. `failure_reason` is a sentence for a person and never parsed; `failure_code` is Reply's code for the failure, the one to branch on. A failed send may carry no `failure_code`: it is then null, and `failure_reason` is all Reply says of it. `direct-send cancel` of a send already cancelled answers it diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index 45e79a7..ed19467 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -61,6 +61,8 @@ describe('operations/commands', ()=>{ expect(flat, name).toContain('estimated_send_at is added only when Reply gives it: when Reply expects a send waiting for its ' + 'schedule\'s next opening to go out, or null when the schedule does not open within 30 days of the moment the send ' + 'waits from: its --send-after, or now once that has passed'); + expect(flat, name).toContain('estimated_send_at means something only with state waitingForSchedule, where null says the ' + + 'schedule does not open within those 30 days; Reply gives it null on any other state, and that null says nothing'); } const cancel = help_of(sub(direct_send_command, 'cancel')).replace(/\s+/g, ' '); expect(cancel).toContain('Cancelling a send already cancelled answers it again, so running it again is safe'); @@ -314,6 +316,9 @@ describe('operations/commands', ()=>{ expect(flat.includes('estimated_send_at'), text).toBe(name !== 'send-email'); expect(flat.includes('estimated_send_at is when Reply expects to send it, or null when the schedule does not open within ' + '30 days of the moment the send waits from: its --send-after, or when Reply took it'), text).toBe(name !== 'send-email'); + expect(flat.includes('estimated_send_at means something only with state waitingForSchedule, where null says the ' + + 'schedule does not open within those 30 days; Reply gives it null on any other state, and that null says nothing'), + text).toBe(name !== 'send-email'); expect(flat.includes('--use-contact-time-zone sends useContactTimeZone true: the schedule\'s windows are read in the ' + 'contact\'s time zone; --no-use-contact-time-zone sends false, the schedule\'s own zone; with neither, the schedule\'s ' + 'own setting holds'), text).toBe(name !== 'send-email'); diff --git a/src/operations/commands.ts b/src/operations/commands.ts index 1ac1f4c..b53cb8a 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -377,7 +377,9 @@ const scheduler_options = (c: Command): Command=>c const SCHEDULED = 'A LinkedIn send timed by --schedule-id may answer state waitingForSchedule, held for the schedule\'s next\n' + 'opening: send_after is then left out, and estimated_send_at is when Reply expects to send it, or null when the\n' + 'schedule does not open within 30 days of the moment the send waits from: its --send-after, or when Reply took it.\n' - + 'estimated_send_at is added only when Reply gives it. --use-contact-time-zone sends\n' + + 'estimated_send_at means something only with state waitingForSchedule, where null says the schedule does not open\n' + + 'within those 30 days; Reply gives it null on any other state, and that null says nothing. It is added only when\n' + + 'Reply gives it. --use-contact-time-zone sends\n' + 'useContactTimeZone true: the schedule\'s windows are read in the contact\'s time zone; --no-use-contact-time-zone sends\n' + 'false, the schedule\'s own zone; with neither, the schedule\'s own setting holds. --retry-window-minutes is how long\n' + 'Reply keeps trying to send it once it is due, 1 to 4320 minutes (Reply\'s default is 90); one outside that is refused\n' @@ -613,7 +615,9 @@ const DIRECT_SEND = 'Result: {"reference","channel","contact_id","state","send_a + 'missing_variables lists the template variables Reply could not fill, and rendered_subject and rendered_body are the\n' + 'text as Reply filled it in. estimated_send_at is added only when Reply gives it: when Reply expects a send waiting\n' + 'for its schedule\'s next opening to go out, or null when the schedule does not open within 30 days of the moment the\n' - + 'send waits from: its --send-after, or now once that has passed.\n' + + 'send waits from: its --send-after, or now once that has passed. estimated_send_at means something only with state\n' + + 'waitingForSchedule, where null says the schedule does not open within those 30 days; Reply gives it null on any other\n' + + 'state, and that null says nothing.\n' + 'A Reply without this route answers reply.refused with status 404 and no reply_code; a\n' + 'reference of any other form never leaves the CLI, so that 404 means this Reply has no such route.\n' + 'direct_send.not_found is a reference that Reply has no send for, a send of another team included.\n' From 4dfe133cfe56e7229ac807112d431b88b539161a Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 22:11:09 -0700 Subject: [PATCH 11/15] feat: contact send-email takes --use-contact-time-zone and --no-use-contact-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. --- README.md | 42 ++++++------ src/__tests__/operations/commands.test.ts | 30 +++++---- src/__tests__/operations/direct-send.test.ts | 27 ++++++-- src/operations/commands.ts | 67 ++++++++++++-------- src/operations/direct-send.ts | 5 +- 5 files changed, 104 insertions(+), 67 deletions(-) diff --git a/README.md b/README.md index 9aee08a..97af899 100644 --- a/README.md +++ b/README.md @@ -202,7 +202,8 @@ prints JSON (indented; compact with `--json`) and says what happened in a stable | `reply contact linkedin-connect --linkedin-account-id N [--message -]` | a LinkedIn invitation, with or without a note → `sent` / `already_connected` | | `reply contact linkedin-message …` · `linkedin-inmail …` · `linkedin-voice …` | a LinkedIn message, an InMail, or an AI voice message spoken from a script → `sent` | | any direct send `… [--send-after ] [--schedule-id N] [--idempotency-key K]` | the send held until a moment, timed by a schedule, under a key of yours → `sent`, with its `reference` and `state` | -| a LinkedIn send `… [--use-contact-time-zone \| --no-use-contact-time-zone] [--retry-window-minutes N]` | the schedule read in the contact's time zone or its own, and how long Reply keeps trying once the send is due | +| any direct send `… [--use-contact-time-zone \| --no-use-contact-time-zone]` | with `--schedule-id`, the schedule read in the contact's time zone or its own | +| a LinkedIn send `… [--retry-window-minutes N]` | how long Reply keeps trying once the send is due | | `reply direct-send get ` | a send as Reply holds it: whether it has gone out, when, and why it failed | | `reply direct-send cancel ` | stop a send that has not gone out yet → `state` `cancelled` | | `reply inbox list (--contact-id \| --sequence-id) [--source] [--channel] [--category-id] [--since]` | one page of threads | @@ -334,26 +335,31 @@ Reply's route takes: a reference of any other form is refused before any call (` exit 2), and nothing else is read from it. An answer without `state` comes from a Reply that does not know these flags yet: it sent at once, as without them. -A LinkedIn send timed by `--schedule-id` may answer `state` `waitingForSchedule`: Reply holds it for -the schedule's next opening, so `send_after` is left out, and `estimated_send_at` is when Reply -expects to send it, an ISO-8601 UTC moment, or null when the schedule does not open within 30 days -of the moment the send waits from: its `--send-after`, or when Reply took it. Reply sends it within -about 10 minutes of that moment. `estimated_send_at` means something only with `state` +A send timed by `--schedule-id` may answer `state` `waitingForSchedule`: Reply holds it for the +schedule's next opening, so `send_after` is left out, and `estimated_send_at` is when Reply expects +to send it, an ISO-8601 UTC moment, or null when the schedule does not open within 30 days of the +moment the send waits from: its `--send-after`, or when Reply took it. Reply sends it within about +10 minutes of that moment. `estimated_send_at` means something only with `state` `waitingForSchedule`, where null says the schedule does not open within those 30 days; Reply gives it null on any other state, and that null says nothing. It is added only when Reply gives it. -The four LinkedIn sends also take `--use-contact-time-zone` / `--no-use-contact-time-zone` and -`--retry-window-minutes `; `contact send-email` takes neither. `--use-contact-time-zone` reads the -schedule's windows in the contact's time zone and `--no-use-contact-time-zone` in the schedule's -own; with neither, the schedule's own setting holds. `--retry-window-minutes` is how long Reply keeps -trying to send once the send is due, 1 to 4320 minutes (Reply's default is 90); a number outside -that is refused before any call (`usage.range`). Reply takes them only for a send made later, the -time zone only with `--schedule-id`, and answers them otherwise with `reply.invalid_request`; a -Reply before its LinkedIn scheduler answers `--schedule-id` on a LinkedIn send the same way. -Reply refuses a LinkedIn send it cannot time when it takes it, and nothing is sent: `--schedule-id` -naming no schedule this account can read is `schedule.not_found`, a schedule with no active day -that has a time range, so it never opens, is `schedule.no_slot`, and a contact without the time zone `--use-contact-time-zone` reads the -schedule in is `contact.time_zone_missing`. +Every direct send also takes `--use-contact-time-zone` / `--no-use-contact-time-zone`, and the four +LinkedIn sends take `--retry-window-minutes ` as well; `contact send-email` does not take the +retry window. `--use-contact-time-zone` reads the schedule's windows in the contact's time zone and +`--no-use-contact-time-zone` in the schedule's own; with neither, the schedule's own setting holds. +`--retry-window-minutes` is how long Reply keeps trying to send once the send is due, 1 to 4320 +minutes (Reply's default is 90); a number outside that is refused before any call (`usage.range`). +Reply takes the time zone only with `--schedule-id` and the retry window only for a send made +later, and answers them otherwise with `reply.invalid_request`; a Reply before its LinkedIn +scheduler answers `--schedule-id` on a LinkedIn send the same way. + +Reply refuses a send it cannot time when it takes it, and nothing is sent. On a LinkedIn send, +`--schedule-id` naming no schedule this account can read is `schedule.not_found`, a schedule with +no active day that has a time range, so it never opens, is `schedule.no_slot`, and a contact +without the time zone `--use-contact-time-zone` reads the schedule in is +`contact.time_zone_missing`. On an email the same three are `reply.refused`, with Reply's +`contact.scheduleNotFound`, `contact.scheduleHasNoSlot` or `contact.contactTimeZoneMissing` as +`reply_code`. ```sh echo '{"body":"Following up on my note."}' | reply contact linkedin-message --contact-id 456 --linkedin-account-id 34 --message - --schedule-id 41 --use-contact-time-zone --retry-window-minutes 120 diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index ed19467..d377879 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -292,7 +292,7 @@ describe('operations/commands', ()=>{ const c = sub(contact_command, name); expect(flags(c), name).toEqual([...CONTACT_FLAGS, account_flag, '--message', ...(name === 'send-email' ? ['--track-links', '--track-opens'] : []), '--send-after', '--schedule-id', '--idempotency-key', - ...(name === 'send-email' ? [] : ['--use-contact-time-zone', '--no-use-contact-time-zone', '--retry-window-minutes'])]); + '--use-contact-time-zone', '--no-use-contact-time-zone', ...(name === 'send-email' ? [] : ['--retry-window-minutes'])]); const text = help_of(c); const flat = text.replace(/\s+/g, ' '); expect(text, text).toContain('--message -'); @@ -312,22 +312,26 @@ describe('operations/commands', ()=>{ expect(flat, text).toContain('status "sent" means Reply took the send; state, when Reply gives it, says whether it has gone ' + 'out: queued, waitingForSchedule or sending is not yet, then sent, failed or cancelled'); expect(flat, text).toContain('direct-send get reads it later, and direct-send cancel stops one not yet sent'); - expect(flat.includes('A LinkedIn send timed by --schedule-id may answer state waitingForSchedule'), text).toBe(name !== 'send-email'); - expect(flat.includes('estimated_send_at'), text).toBe(name !== 'send-email'); - expect(flat.includes('estimated_send_at is when Reply expects to send it, or null when the schedule does not open within ' - + '30 days of the moment the send waits from: its --send-after, or when Reply took it'), text).toBe(name !== 'send-email'); - expect(flat.includes('estimated_send_at means something only with state waitingForSchedule, where null says the ' - + 'schedule does not open within those 30 days; Reply gives it null on any other state, and that null says nothing'), - text).toBe(name !== 'send-email'); - expect(flat.includes('--use-contact-time-zone sends useContactTimeZone true: the schedule\'s windows are read in the ' + // Every send takes a schedule and its time zone; only the LinkedIn sends take a retry window and map the refusals. + const linkedin = name !== 'send-email'; + expect(flat, text).toContain('A send timed by --schedule-id may answer state waitingForSchedule'); + expect(flat, text).toContain('estimated_send_at is when Reply expects to send it, or null when the schedule does not open within ' + + '30 days of the moment the send waits from: its --send-after, or when Reply took it'); + expect(flat, text).toContain('estimated_send_at means something only with state waitingForSchedule, where null says the ' + + 'schedule does not open within those 30 days; Reply gives it null on any other state, and that null says nothing'); + expect(flat, text).toContain('--use-contact-time-zone sends useContactTimeZone true: the schedule\'s windows are read in the ' + 'contact\'s time zone; --no-use-contact-time-zone sends false, the schedule\'s own zone; with neither, the schedule\'s ' - + 'own setting holds'), text).toBe(name !== 'send-email'); + + 'own setting holds. Reply takes it only with --schedule-id, and answers it otherwise with errors[] (reply.invalid_request)'); expect(flat.includes('--retry-window-minutes is how long Reply keeps trying to send it once it is due, 1 to 4320 ' - + 'minutes (Reply\'s default is 90); one outside that is refused before any call (usage.range)'), text).toBe(name !== 'send-email'); - expect(flat.includes('Reply takes them only with --schedule-id or --send-after'), text).toBe(name !== 'send-email'); + + 'minutes (Reply\'s default is 90); one outside that is refused before any call (usage.range)'), text).toBe(linkedin); + expect(flat.includes('Reply takes it only with --schedule-id or --send-after'), text).toBe(linkedin); expect(flat.includes('schedule.not_found is a --schedule-id naming no schedule this account can read, schedule.no_slot a ' + 'schedule with no active day that has a time range, so it never opens, and contact.time_zone_missing a contact without the time zone ' - + '--use-contact-time-zone reads it in; none sends anything'), text).toBe(name !== 'send-email'); + + '--use-contact-time-zone reads it in; none sends anything'), text).toBe(linkedin); + expect(flat.includes('Reply refuses an email it cannot time when it takes it, and nothing is sent: a --schedule-id naming no ' + + 'schedule this account can read, a schedule with no active day that has a time range, and a contact without the time zone ' + + '--use-contact-time-zone reads it in are reply.refused, with Reply\'s contact.scheduleNotFound, contact.scheduleHasNoSlot ' + + 'or contact.contactTimeZoneMissing as reply_code'), text).toBe(!linkedin); expect(flat, text).toContain('An answer without state comes from a Reply that does not know --send-after and --schedule-id'); expect(flat, text).toContain('--idempotency-key goes as the Idempotency-Key header'); expect(flat, text).toContain('A Reply that knows the header answers a repeat with the same key with the send the key first made; while that one is still ' diff --git a/src/__tests__/operations/direct-send.test.ts b/src/__tests__/operations/direct-send.test.ts index 1340227..b31f4d5 100644 --- a/src/__tests__/operations/direct-send.test.ts +++ b/src/__tests__/operations/direct-send.test.ts @@ -74,6 +74,10 @@ describe('contact send-email', ()=>{ [json({title: 'Validation failed', errors: [{pointer: '/subject', detail: '\'subject\' must not be empty.'}]}, 400), 'reply.invalid_request', undefined], [json({code: 'contact.somethingElse'}, 400), 'reply.refused', 'contact.somethingElse'], + // An email Reply cannot time is refused under Reply's own codes, passed on unchanged. + [json({code: 'contact.scheduleNotFound'}, 404), 'reply.refused', 'contact.scheduleNotFound'], + [json({code: 'contact.scheduleHasNoSlot'}, 409), 'reply.refused', 'contact.scheduleHasNoSlot'], + [json({code: 'contact.contactTimeZoneMissing'}, 409), 'reply.refused', 'contact.contactTimeZoneMissing'], ]; for (const [res, code, reply_code] of cases) { @@ -783,12 +787,23 @@ describe('a send for later', ()=>{ expect(e).toMatchObject({code: 'reply.invalid_request', exit_code: 1, details: {fields: ['useContactTimeZone']}}); }); - it('a direct email never carries either, even when the options reach it', async()=>{ - answer(accepted('send-email', {})); - await run('send-email', {subject: SUBJECT, body: BODY}, {...EMAIL_OPTS, ...LATER, useContactTimeZone: true, retryWindowMinutes: '30'}); - const body = sent()[0].body as Record; - expect('useContactTimeZone' in body).toBe(false); - expect('retryWindowMinutes' in body).toBe(false); + it('a direct email carries useContactTimeZone, true or false, only when given, and never a retry window', async()=>{ + const cases: [Partial, Record][] = [ + [{useContactTimeZone: true}, {useContactTimeZone: true}], + [{useContactTimeZone: false, retryWindowMinutes: '30'}, {useContactTimeZone: false}], + [{retryWindowMinutes: '30'}, {}], + [{}, {}], + ]; + for (const [extra, carried] of cases) + { + mock_fetch.mockReset(); + answer(accepted('send-email', {})); + await run('send-email', {subject: SUBJECT, body: BODY}, {...EMAIL_OPTS, ...LATER, ...extra}); + const body = sent()[0].body as Record; + expect(body.scheduleId, JSON.stringify(extra)).toBe(41); + expect(Object.fromEntries(Object.entries(body).filter(([k])=>k === 'useContactTimeZone' || k === 'retryWindowMinutes')), + JSON.stringify(extra)).toStrictEqual(carried); + } }); it('a key does not make a lost answer safe to repeat: a Reply that ignores the header would send it twice', async()=>{ diff --git a/src/operations/commands.ts b/src/operations/commands.ts index b53cb8a..2e74df9 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -324,11 +324,46 @@ const piped_send = (command: string, contact: string, message: string, flags: st const ANN_EMAIL = '{"email":"ann@example.com","first_name":"Ann"}'; const ANN_PROFILE = '{"linkedin_url":"https://www.linkedin.com/in/ann-example","first_name":"Ann"}'; -later_options(add_contact_options(contact_command.command('send-email'), true) +// The time zone a send timed by a schedule is read in, which every send takes. Without either flag nothing is sent, so +// the schedule's own setting holds. +const time_zone_options = (c: Command): Command=>c + .option('--use-contact-time-zone', 'Read the schedule\'s windows in the contact\'s time zone (with --schedule-id)') + .option('--no-use-contact-time-zone', 'Read the schedule\'s windows in the schedule\'s own time zone (with --schedule-id)'); + +// The flags Reply's LinkedIn sends take for a send made later: the time zone, and the retry window only they take. +const scheduler_options = (c: Command): Command=>time_zone_options(c) + .option('--retry-window-minutes ', 'How long Reply keeps trying once the send is due, 1 to 4320 (Reply\'s default: 90)'); + +// What a send timed by a schedule answers while it waits for the schedule's next opening, and the time zone it is read in. +const SCHEDULED = 'A send timed by --schedule-id may answer state waitingForSchedule, held for the schedule\'s next opening:\n' + + 'send_after is then left out, and estimated_send_at is when Reply expects to send it, or null when the schedule does\n' + + 'not open within 30 days of the moment the send waits from: its --send-after, or when Reply took it.\n' + + 'estimated_send_at means something only with state waitingForSchedule, where null says the schedule does not open\n' + + 'within those 30 days; Reply gives it null on any other state, and that null says nothing. It is added only when\n' + + 'Reply gives it. --use-contact-time-zone sends useContactTimeZone true: the schedule\'s windows are read in the\n' + + 'contact\'s time zone; --no-use-contact-time-zone sends false, the schedule\'s own zone; with neither, the schedule\'s\n' + + 'own setting holds. Reply takes it only with --schedule-id, and answers it otherwise with errors[]\n' + + '(reply.invalid_request).\n'; + +// The retry window only a LinkedIn send takes, and the refusals of a LinkedIn send Reply cannot time. +const LINKEDIN_SCHEDULED = '--retry-window-minutes is how long Reply keeps trying to send it once it is due, 1 to 4320\n' + + 'minutes (Reply\'s default is 90); one outside that is refused before any call (usage.range). Reply takes it only with\n' + + '--schedule-id or --send-after, and answers it otherwise with errors[] (reply.invalid_request), as a Reply before its\n' + + 'scheduler answers --schedule-id on a LinkedIn send. schedule.not_found is a --schedule-id naming no schedule this\n' + + 'account can read, schedule.no_slot a schedule with no active day that has a time range, so it never opens, and\n' + + 'contact.time_zone_missing a contact without the time zone --use-contact-time-zone reads it in; none sends anything.\n'; + +// An email Reply cannot time is refused under Reply's own codes, which reach the caller unchanged. +const EMAIL_SCHEDULED = 'Reply refuses an email it cannot time when it takes it, and nothing is sent: a --schedule-id naming no\n' + + 'schedule this account can read, a schedule with no active day that has a time range, and a contact without the time\n' + + 'zone --use-contact-time-zone reads it in are reply.refused, with Reply\'s contact.scheduleNotFound,\n' + + 'contact.scheduleHasNoSlot or contact.contactTimeZoneMissing as reply_code.\n'; + +time_zone_options(later_options(add_contact_options(contact_command.command('send-email'), true) .option('--email-account-id ', 'The mailbox to send from (see `account list`)') .option('--message ', 'Only -: the email {subject, body} as JSON on stdin') .option('--track-links', 'Track the links in the email (off unless given)') - .option('--track-opens', 'Track the opens of the email (off unless given)')) + .option('--track-opens', 'Track the opens of the email (off unless given)'))) .description('Send one email to a contact now, outside any sequence, from the mailbox you name') .addHelpText('after', help( [`echo '{"subject":"Quick question","body":"

Hi Ann, does Tuesday work?

"}' | ${P} contact send-email --contact-id 456 --email-account-id 12 --message -`, @@ -345,7 +380,7 @@ later_options(add_contact_options(contact_command.command('send-email'), true) + 'them; a send held for later has neither. contact.missing_variables names the variables Reply could not fill in\n' + 'details.missing_variables when Reply lists them, and contact.rendering_failed is a template Reply could not\n' + 'render, its message in detail. Neither sends anything.\n' - + LATER + SENT_TO('email', 'email'), + + LATER + SCHEDULED + EMAIL_SCHEDULED + SENT_TO('email', 'email'), SEND_TWICE('email'))) .action(run(async(cmd)=>{ const {g, ctx} = ctx_of(cmd); @@ -365,30 +400,6 @@ const VARIABLES = (where: string): string=> `Reply reads {{…}} in the ${where} as its template variables; one it cannot fill is linkedin.missing_variables.\n`; const LINKEDIN_EXAMPLE = '--contact-id 456 --linkedin-account-id 34'; -// The flags only Reply's LinkedIn sends take for a send made later. Without either time-zone flag nothing is sent, so the -// schedule's own setting holds. -const scheduler_options = (c: Command): Command=>c - .option('--use-contact-time-zone', 'Read the schedule\'s windows in the contact\'s time zone (with --schedule-id)') - .option('--no-use-contact-time-zone', 'Read the schedule\'s windows in the schedule\'s own time zone (with --schedule-id)') - .option('--retry-window-minutes ', 'How long Reply keeps trying once the send is due, 1 to 4320 (Reply\'s default: 90)'); - -// What a LinkedIn send timed by a schedule answers while it waits for the schedule's next opening, and the flags only -// a LinkedIn send takes. -const SCHEDULED = 'A LinkedIn send timed by --schedule-id may answer state waitingForSchedule, held for the schedule\'s next\n' - + 'opening: send_after is then left out, and estimated_send_at is when Reply expects to send it, or null when the\n' - + 'schedule does not open within 30 days of the moment the send waits from: its --send-after, or when Reply took it.\n' - + 'estimated_send_at means something only with state waitingForSchedule, where null says the schedule does not open\n' - + 'within those 30 days; Reply gives it null on any other state, and that null says nothing. It is added only when\n' - + 'Reply gives it. --use-contact-time-zone sends\n' - + 'useContactTimeZone true: the schedule\'s windows are read in the contact\'s time zone; --no-use-contact-time-zone sends\n' - + 'false, the schedule\'s own zone; with neither, the schedule\'s own setting holds. --retry-window-minutes is how long\n' - + 'Reply keeps trying to send it once it is due, 1 to 4320 minutes (Reply\'s default is 90); one outside that is refused\n' - + 'before any call (usage.range). Reply takes them only with --schedule-id or --send-after, the time zone only with\n' - + '--schedule-id, and answers them otherwise with errors[] (reply.invalid_request), as a Reply before its scheduler\n' - + 'answers --schedule-id on a LinkedIn send. schedule.not_found is a --schedule-id naming no schedule this account can\n' - + 'read, schedule.no_slot a schedule with no active day that has a time range, so it never opens, and\n' - + 'contact.time_zone_missing a contact without the time zone --use-contact-time-zone reads it in; none sends anything.\n'; - const linkedin_send = ( name: Exclude, description: string, message: string, examples: string[], codes: string[], extra: string, what: string, @@ -397,7 +408,7 @@ const linkedin_send = ( .option('--linkedin-account-id ', 'The LinkedIn account to send from (see `account list`)') .option('--message ', `Only -: the ${message} as JSON on stdin`))) .description(description) - .addHelpText('after', help(examples, [...LINKEDIN_SEND_CODES, ...codes, ...KEY_CODES], true, extra + LATER + SCHEDULED + SENT_TO('linkedin', what), + .addHelpText('after', help(examples, [...LINKEDIN_SEND_CODES, ...codes, ...KEY_CODES], true, extra + LATER + SCHEDULED + LINKEDIN_SCHEDULED + SENT_TO('linkedin', what), SEND_TWICE(what))) .action(run(async(cmd)=>{ const {g, ctx} = ctx_of(cmd); diff --git a/src/operations/direct-send.ts b/src/operations/direct-send.ts index 9ead372..da2a4e3 100644 --- a/src/operations/direct-send.ts +++ b/src/operations/direct-send.ts @@ -385,8 +385,9 @@ const handle_direct_send = async( { later.scheduleId = parse_id(opts.scheduleId, '--schedule-id'); } - // Only Reply's LinkedIn routes take these. Which other flag each needs is Reply's rule, refused there with errors[]. - if (by === 'linkedin' && opts.useContactTimeZone !== undefined) + // Every send route takes the time zone, and only Reply's LinkedIn routes take the retry window. Which other flag each + // needs is Reply's rule, refused there with errors[]. + if (opts.useContactTimeZone !== undefined) { later.useContactTimeZone = opts.useContactTimeZone; } From 560eabe352748a59e4897c55a9d5620b1468b10e Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 22:12:44 -0700 Subject: [PATCH 12/15] docs: rewrap the direct-send help and README to the width of their neighbours 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. --- README.md | 63 +++++++++++++++++++------------------- src/operations/commands.ts | 58 +++++++++++++++++------------------ 2 files changed, 60 insertions(+), 61 deletions(-) diff --git a/README.md b/README.md index 97af899..7cc4499 100644 --- a/README.md +++ b/README.md @@ -321,19 +321,19 @@ Reply cannot fill is `contact.missing_variables`, with the names under the error # {"error":{"code":"contact.missing_variables",…,"details":{"missing_variables":["FirstName","Company"]}}} ``` -Every direct send also takes `--send-after `, `--schedule-id ` and `--idempotency-key -`. Reply holds the send until the moment, given with its offset (`2026-11-03T14:00:00Z`, -`2026-11-03T16:00:00+02:00`) and sent to Reply in UTC; a moment without an offset is refused -(`usage.date`). `--schedule-id` names the sending schedule Reply times the send by (see `reply -schedule list`). The answer then adds Reply's `reference`, `send_after` and `state`, each only when -Reply gives it. `status: "sent"` means Reply took the send, and `state`, when present, says whether -it has gone out: `queued`, `waitingForSchedule` or `sending` is not yet, then `sent`, `failed` or `cancelled`. `reply -direct-send get ` reads the send later, and `reply direct-send cancel ` stops -one that has not gone out. The reference is Reply's, `email-`, `linkedin-` or -`linkedin-scheduled-` (a LinkedIn send held for later keeps that one for its whole life), the form -Reply's route takes: a reference of any other form is refused before any call (`usage.reference`, -exit 2), and nothing else is read from it. An answer without `state` comes from a Reply that does -not know these flags yet: it sent at once, as without them. +Every direct send also takes `--send-after `, `--schedule-id ` and +`--idempotency-key `. Reply holds the send until the moment, given with its offset +(`2026-11-03T14:00:00Z`, `2026-11-03T16:00:00+02:00`) and sent to Reply in UTC; a moment without an +offset is refused (`usage.date`). `--schedule-id` names the sending schedule Reply times the send by +(see `reply schedule list`). The answer then adds Reply's `reference`, `send_after` and `state`, +each only when Reply gives it. `status: "sent"` means Reply took the send, and `state`, when +present, says whether it has gone out: `queued`, `waitingForSchedule` or `sending` is not yet, then +`sent`, `failed` or `cancelled`. `reply direct-send get ` reads the send later, and +`reply direct-send cancel ` stops one that has not gone out. The reference is Reply's, +`email-`, `linkedin-` or `linkedin-scheduled-` (a LinkedIn send held for later keeps that +one for its whole life), the form Reply's route takes: a reference of any other form is refused +before any call (`usage.reference`, exit 2), and nothing else is read from it. An answer without +`state` comes from a Reply that does not know these flags yet: it sent at once, as without them. A send timed by `--schedule-id` may answer `state` `waitingForSchedule`: Reply holds it for the schedule's next opening, so `send_after` is left out, and `estimated_send_at` is when Reply expects @@ -386,24 +386,25 @@ reply direct-send get linkedin-1042 reply direct-send cancel linkedin-1042 ``` -Both answer the send under the CLI's names, each null when Reply gives none: `reference`, -`channel`, `contact_id`, `state`, `send_after`, `sent_at`, `message_id`, `failure_reason` and -`cancelled_at`. `failure_code`, `missing_variables`, `rendered_subject` and `rendered_body` are -added only when Reply gives them, and so is `estimated_send_at`, read the same way as on the send -but as of the read: its 30 days then count from `--send-after`, or from now once that has passed, -and it means something only while `state` is `waitingForSchedule`. -`failure_reason` is a sentence for a person and never parsed; -`failure_code` is Reply's code for the failure, the one to branch on. A failed send may carry no -`failure_code`: it is then null, and `failure_reason` is all Reply says of it. `direct-send cancel` of a send already cancelled answers it -again. A send already gone out, failed or going out is `direct_send.already_sent`, -`direct_send.already_failed` or `direct_send.already_sending`; the last is a LinkedIn send made for -later that Reply is handing to the account's queue or that waits or runs there, even while -`direct-send get` still reads it `queued`. A reference Reply has no send for, a send of another -team included, is `direct_send.not_found`, and an email send made by a teammate this user may not -act for is `direct_send.not_owned`, to a read and a cancel alike. A `503` that Reply answers with `directSend.cancelNotConfirmed` is -`direct_send.cancel_not_confirmed` (exit 1): Reply could not confirm the cancel, and says the send is -still queued or waiting for its schedule, so run the cancel again, as Reply asks; `retry_after` carries Reply's `Retry-After` when it sends one. -Any other `5xx` to a cancel stays `outcome.unknown` (exit 3). +Both answer the send under the CLI's names, each null when Reply gives none: `reference`, `channel`, +`contact_id`, `state`, `send_after`, `sent_at`, `message_id`, `failure_reason` and `cancelled_at`. +`failure_code`, `missing_variables`, `rendered_subject` and `rendered_body` are added only when +Reply gives them, and so is `estimated_send_at`, read the same way as on the send but as of the +read: its 30 days then count from `--send-after`, or from now once that has passed, and it means +something only while `state` is `waitingForSchedule`. `failure_reason` is a sentence for a person +and never parsed; `failure_code` is Reply's code for the failure, the one to branch on. A failed +send may carry no `failure_code`: it is then null, and `failure_reason` is all Reply says of it. +`direct-send cancel` of a send already cancelled answers it again. A send already gone out, failed +or going out is `direct_send.already_sent`, `direct_send.already_failed` or +`direct_send.already_sending`; the last is a LinkedIn send made for later that Reply is handing to +the account's queue or that waits or runs there, even while `direct-send get` still reads it +`queued`. A reference Reply has no send for, a send of another team included, is +`direct_send.not_found`, and an email send made by a teammate this user may not act for is +`direct_send.not_owned`, to a read and a cancel alike. A `503` that Reply answers with +`directSend.cancelNotConfirmed` is `direct_send.cancel_not_confirmed` (exit 1): Reply could not +confirm the cancel, and says the send is still queued or waiting for its schedule, so run the cancel +again, as Reply asks; `retry_after` carries Reply's `Retry-After` when it sends one. Any other `5xx` +to a cancel stays `outcome.unknown` (exit 3). `reply inbox changes` reads the inbox feed forward. Each page holds the threads whose latest message, inbound or outbound, changed, oldest first and as Reply gives them, with `has_more` and a `cursor`. diff --git a/src/operations/commands.ts b/src/operations/commands.ts index 2e74df9..67bf38a 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -298,22 +298,22 @@ const later_options = (c: Command): Command=>c .option('--idempotency-key ', 'Your own key for this send, sent as the Idempotency-Key header'); const LATER = 'With --send-after Reply holds the send until that moment, given with its offset and sent to Reply in UTC; a moment\n' - + 'without an offset is refused (usage.date). --schedule-id names the sending schedule Reply times the send by. The answer\n' - + 'then adds Reply\'s reference, send_after and state, each only when Reply gives it: status "sent" means Reply took the\n' - + 'send; state, when Reply gives it, says whether it has gone out: queued, waitingForSchedule or sending is not yet,\n' - + 'then sent, failed or cancelled. direct-send get reads it later, and direct-send cancel stops one not yet sent. An\n' - + 'answer without state comes from a Reply that does not know --send-after and --schedule-id: it sent at once, as\n' - + 'without them. --idempotency-key goes as the Idempotency-Key header, never in the body. A Reply that knows the header\n' - + 'answers a repeat with the same key with the send the key first made; while that one is still being made the answer\n' - + 'is idempotency_key.in_use, and the same key on a different send is idempotency_key.reused. Neither sends anything.\n' - + 'A repeat of a send given a person\'s fields answers contact.already_held first, since the first one created the\n' - + 'contact: that is safe too, as nothing is sent twice. idempotency_key.reused names the send the key was first taken\n' - + 'for in details: reference, state and send_after, each only when Reply gives it. Any other refusal of a send Reply\n' - + 'already holds names that send the same way, beside the refusal\'s own details; its code is the refusal\'s own.\n' - + 'A 400 to the send with neither a code nor errors[] is Reply failing while it made the send: like a 5xx or a lost\n' - + 'answer, it is outcome.unknown (exit 3). So is a 400 directLinkedIn.unknown to a LinkedIn send, Reply\'s answer when\n' - + 'it failed while making the send or could not map the provider\'s answer; Reply\'s code is kept in reply_code. A 400\n' - + 'with errors[] is reply.invalid_request, and nothing was sent.\n'; + + 'without an offset is refused (usage.date). --schedule-id names the sending schedule Reply times the send by. The\n' + + 'answer then adds Reply\'s reference, send_after and state, each only when Reply gives it: status "sent" means Reply\n' + + 'took the send; state, when Reply gives it, says whether it has gone out: queued, waitingForSchedule or sending is not\n' + + 'yet, then sent, failed or cancelled. direct-send get reads it later, and direct-send cancel \n' + + 'stops one not yet sent. An answer without state comes from a Reply that does not know --send-after and --schedule-id:\n' + + 'it sent at once, as without them. --idempotency-key goes as the Idempotency-Key header, never in the body. A Reply\n' + + 'that knows the header answers a repeat with the same key with the send the key first made; while that one is still\n' + + 'being made the answer is idempotency_key.in_use, and the same key on a different send is idempotency_key.reused.\n' + + 'Neither sends anything. A repeat of a send given a person\'s fields answers contact.already_held first, since the first\n' + + 'one created the contact: that is safe too, as nothing is sent twice. idempotency_key.reused names the send the key was\n' + + 'first taken for in details: reference, state and send_after, each only when Reply gives it. Any other refusal of a\n' + + 'send Reply already holds names that send the same way, beside the refusal\'s own details; its code is the refusal\'s\n' + + 'own. A 400 to the send with neither a code nor errors[] is Reply failing while it made the send: like a 5xx or a lost\n' + + 'answer, it is outcome.unknown (exit 3). So is a 400 directLinkedIn.unknown to a LinkedIn send, Reply\'s answer when it\n' + + 'failed while making the send or could not map the provider\'s answer; Reply\'s code is kept in reply_code. A 400 with\n' + + 'errors[] is reply.invalid_request, and nothing was sent.\n'; // The refusals of a send's key, the same on every direct send, after each send's own. const KEY_CODES = ['idempotency_key.in_use', 'idempotency_key.reused']; @@ -624,13 +624,12 @@ const DIRECT_SEND = 'Result: {"reference","channel","contact_id","state","send_a + 'failure_reason is a sentence for a person, never parsed; failure_code is Reply\'s code for the failure, the one to\n' + 'branch on. A failed send may carry no failure_code: it is then null, and failure_reason is all Reply says of it.\n' + 'missing_variables lists the template variables Reply could not fill, and rendered_subject and rendered_body are the\n' - + 'text as Reply filled it in. estimated_send_at is added only when Reply gives it: when Reply expects a send waiting\n' - + 'for its schedule\'s next opening to go out, or null when the schedule does not open within 30 days of the moment the\n' - + 'send waits from: its --send-after, or now once that has passed. estimated_send_at means something only with state\n' + + 'text as Reply filled it in. estimated_send_at is added only when Reply gives it: when Reply expects a send waiting for\n' + + 'its schedule\'s next opening to go out, or null when the schedule does not open within 30 days of the moment the send\n' + + 'waits from: its --send-after, or now once that has passed. estimated_send_at means something only with state\n' + 'waitingForSchedule, where null says the schedule does not open within those 30 days; Reply gives it null on any other\n' - + 'state, and that null says nothing.\n' - + 'A Reply without this route answers reply.refused with status 404 and no reply_code; a\n' - + 'reference of any other form never leaves the CLI, so that 404 means this Reply has no such route.\n' + + 'state, and that null says nothing. A Reply without this route answers reply.refused with status 404 and no reply_code;\n' + + 'a reference of any other form never leaves the CLI, so that 404 means this Reply has no such route.\n' + 'direct_send.not_found is a reference that Reply has no send for, a send of another team included.\n' + 'direct_send.not_owned is an email send made by a teammate this user may not act for.\n'; @@ -649,14 +648,13 @@ direct_send_command.command('cancel') .addHelpText('after', help([ex('direct-send cancel email-1001')], ['direct_send.not_found', 'direct_send.not_owned', 'direct_send.already_sent', 'direct_send.already_failed', 'direct_send.already_sending', 'direct_send.cancel_not_confirmed'], true, - DIRECT_SEND + 'The answer is the send as Reply now holds it, state cancelled. Cancelling a send already cancelled answers\n' - + 'it again, so running it again is safe. direct_send.already_sent, direct_send.already_failed and\n' - + 'direct_send.already_sending mean the send was past cancelling; nothing changed. direct_send.already_sending is a\n' - + 'LinkedIn send made for later that Reply is handing to the account\'s queue or that waits or runs there, even while\n' - + 'direct-send get still reads it queued. direct_send.cancel_not_confirmed\n' - + 'is a 503 from Reply that could not confirm the cancel: the send is still queued or waiting for its schedule, so\n' - + 'run the cancel again, as Reply asks;\n' - + 'retry_after carries Reply\'s Retry-After when it sends one. Any other 5xx is outcome.unknown (exit 3).\n')) + DIRECT_SEND + 'The answer is the send as Reply now holds it, state cancelled. Cancelling a send already cancelled answers it again,\n' + + 'so running it again is safe. direct_send.already_sent, direct_send.already_failed and direct_send.already_sending mean\n' + + 'the send was past cancelling; nothing changed. direct_send.already_sending is a LinkedIn send made for later that\n' + + 'Reply is handing to the account\'s queue or that waits or runs there, even while direct-send get still reads it queued.\n' + + 'direct_send.cancel_not_confirmed is a 503 from Reply that could not confirm the cancel: the send is still queued or\n' + + 'waiting for its schedule, so run the cancel again, as Reply asks; retry_after carries Reply\'s Retry-After when it\n' + + 'sends one. Any other 5xx is outcome.unknown (exit 3).\n')) .action(run(async(cmd)=>{ const {g, ctx} = ctx_of(cmd); await handle_direct_send_cancel(cmd.args[0], ctx, g); From fc706a7e662b553b20d241b7eaaa1606c93d9235 Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 22:15:36 -0700 Subject: [PATCH 13/15] docs: drop the claim that a Reply without the scheduler refuses --schedule-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. --- README.md | 3 +-- src/__tests__/operations/commands.test.ts | 2 ++ src/operations/commands.ts | 8 ++++---- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 7cc4499..852db72 100644 --- a/README.md +++ b/README.md @@ -350,8 +350,7 @@ retry window. `--use-contact-time-zone` reads the schedule's windows in the cont `--retry-window-minutes` is how long Reply keeps trying to send once the send is due, 1 to 4320 minutes (Reply's default is 90); a number outside that is refused before any call (`usage.range`). Reply takes the time zone only with `--schedule-id` and the retry window only for a send made -later, and answers them otherwise with `reply.invalid_request`; a Reply before its LinkedIn -scheduler answers `--schedule-id` on a LinkedIn send the same way. +later, and answers them otherwise with `reply.invalid_request`. Reply refuses a send it cannot time when it takes it, and nothing is sent. On a LinkedIn send, `--schedule-id` naming no schedule this account can read is `schedule.not_found`, a schedule with diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index d377879..d63ac7b 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -325,6 +325,8 @@ describe('operations/commands', ()=>{ expect(flat.includes('--retry-window-minutes is how long Reply keeps trying to send it once it is due, 1 to 4320 ' + 'minutes (Reply\'s default is 90); one outside that is refused before any call (usage.range)'), text).toBe(linkedin); expect(flat.includes('Reply takes it only with --schedule-id or --send-after'), text).toBe(linkedin); + // A Reply without the scheduler ignores both on a LinkedIn send and sends at once; no refusal stands for it. + expect(flat, text).not.toContain('before its scheduler'); expect(flat.includes('schedule.not_found is a --schedule-id naming no schedule this account can read, schedule.no_slot a ' + 'schedule with no active day that has a time range, so it never opens, and contact.time_zone_missing a contact without the time zone ' + '--use-contact-time-zone reads it in; none sends anything'), text).toBe(linkedin); diff --git a/src/operations/commands.ts b/src/operations/commands.ts index 67bf38a..048d849 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -348,10 +348,10 @@ const SCHEDULED = 'A send timed by --schedule-id may answer state waitingForSche // The retry window only a LinkedIn send takes, and the refusals of a LinkedIn send Reply cannot time. const LINKEDIN_SCHEDULED = '--retry-window-minutes is how long Reply keeps trying to send it once it is due, 1 to 4320\n' + 'minutes (Reply\'s default is 90); one outside that is refused before any call (usage.range). Reply takes it only with\n' - + '--schedule-id or --send-after, and answers it otherwise with errors[] (reply.invalid_request), as a Reply before its\n' - + 'scheduler answers --schedule-id on a LinkedIn send. schedule.not_found is a --schedule-id naming no schedule this\n' - + 'account can read, schedule.no_slot a schedule with no active day that has a time range, so it never opens, and\n' - + 'contact.time_zone_missing a contact without the time zone --use-contact-time-zone reads it in; none sends anything.\n'; + + '--schedule-id or --send-after, and answers it otherwise with errors[] (reply.invalid_request). schedule.not_found is\n' + + 'a --schedule-id naming no schedule this account can read, schedule.no_slot a schedule with no active day that has a\n' + + 'time range, so it never opens, and contact.time_zone_missing a contact without the time zone\n' + + '--use-contact-time-zone reads it in; none sends anything.\n'; // An email Reply cannot time is refused under Reply's own codes, which reach the caller unchanged. const EMAIL_SCHEDULED = 'Reply refuses an email it cannot time when it takes it, and nothing is sent: a --schedule-id naming no\n' From 39a06def06a38c3deb28dcba95c2eb784be95060 Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 22:17:47 -0700 Subject: [PATCH 14/15] feat: an email Reply cannot time is refused under the same codes as such 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. --- README.md | 12 ++++---- src/__tests__/operations/commands.test.ts | 12 ++++---- src/__tests__/operations/direct-send.test.ts | 11 ++++--- src/operations/commands.ts | 30 +++++++++----------- src/operations/direct-send.ts | 29 ++++++++++++------- 5 files changed, 49 insertions(+), 45 deletions(-) diff --git a/README.md b/README.md index 852db72..d69d295 100644 --- a/README.md +++ b/README.md @@ -352,13 +352,11 @@ minutes (Reply's default is 90); a number outside that is refused before any cal Reply takes the time zone only with `--schedule-id` and the retry window only for a send made later, and answers them otherwise with `reply.invalid_request`. -Reply refuses a send it cannot time when it takes it, and nothing is sent. On a LinkedIn send, -`--schedule-id` naming no schedule this account can read is `schedule.not_found`, a schedule with -no active day that has a time range, so it never opens, is `schedule.no_slot`, and a contact -without the time zone `--use-contact-time-zone` reads the schedule in is -`contact.time_zone_missing`. On an email the same three are `reply.refused`, with Reply's -`contact.scheduleNotFound`, `contact.scheduleHasNoSlot` or `contact.contactTimeZoneMissing` as -`reply_code`. +Reply refuses a send it cannot time when it takes it, and nothing is sent. A `--schedule-id` +naming no schedule this account can read is `schedule.not_found`, a schedule with no active day +that has a time range, so it never opens, is `schedule.no_slot`, and a contact without the time +zone `--use-contact-time-zone` reads the schedule in is `contact.time_zone_missing`. The codes are +the same on an email and on a LinkedIn send; `reply_code` keeps the one Reply gave. ```sh echo '{"body":"Following up on my note."}' | reply contact linkedin-message --contact-id 456 --linkedin-account-id 34 --message - --schedule-id 41 --use-contact-time-zone --retry-window-minutes 120 diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index d63ac7b..f675011 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -265,7 +265,7 @@ describe('operations/commands', ()=>{ const SENT_AT_AS_GIVEN = 'sentAtUtc as Reply gives them, each null when it gives none; the CLI adds no time of its own'; const DIRECT_SENDS: [string, string, string[], string][] = [ ['send-email', '--email-account-id', ['contact.not_found', ...IMPORT, 'contact.already_held', 'email_account.not_found', 'contact.blacklisted', - 'contact.missing_variables', 'contact.rendering_failed'], + 'contact.missing_variables', 'contact.rendering_failed', 'schedule.not_found', 'schedule.no_slot', 'contact.time_zone_missing'], 'sent_at is always null; the CLI adds none of its own'], ['linkedin-connect', '--linkedin-account-id', [...LINKEDIN, 'linkedin.not_connected', 'linkedin.limit_reached', 'linkedin.message_too_long', 'linkedin.missing_variables'], SENT_AT_AS_GIVEN], @@ -327,13 +327,11 @@ describe('operations/commands', ()=>{ expect(flat.includes('Reply takes it only with --schedule-id or --send-after'), text).toBe(linkedin); // A Reply without the scheduler ignores both on a LinkedIn send and sends at once; no refusal stands for it. expect(flat, text).not.toContain('before its scheduler'); - expect(flat.includes('schedule.not_found is a --schedule-id naming no schedule this account can read, schedule.no_slot a ' + // A send Reply cannot time is refused under the same three codes on every route. + expect(flat, text).toContain('schedule.not_found is a --schedule-id naming no schedule this account can read, schedule.no_slot a ' + 'schedule with no active day that has a time range, so it never opens, and contact.time_zone_missing a contact without the time zone ' - + '--use-contact-time-zone reads it in; none sends anything'), text).toBe(linkedin); - expect(flat.includes('Reply refuses an email it cannot time when it takes it, and nothing is sent: a --schedule-id naming no ' - + 'schedule this account can read, a schedule with no active day that has a time range, and a contact without the time zone ' - + '--use-contact-time-zone reads it in are reply.refused, with Reply\'s contact.scheduleNotFound, contact.scheduleHasNoSlot ' - + 'or contact.contactTimeZoneMissing as reply_code'), text).toBe(!linkedin); + + '--use-contact-time-zone reads it in; none sends anything'); + expect(flat, text).not.toContain('as reply_code'); expect(flat, text).toContain('An answer without state comes from a Reply that does not know --send-after and --schedule-id'); expect(flat, text).toContain('--idempotency-key goes as the Idempotency-Key header'); expect(flat, text).toContain('A Reply that knows the header answers a repeat with the same key with the send the key first made; while that one is still ' diff --git a/src/__tests__/operations/direct-send.test.ts b/src/__tests__/operations/direct-send.test.ts index b31f4d5..bd69535 100644 --- a/src/__tests__/operations/direct-send.test.ts +++ b/src/__tests__/operations/direct-send.test.ts @@ -74,10 +74,13 @@ describe('contact send-email', ()=>{ [json({title: 'Validation failed', errors: [{pointer: '/subject', detail: '\'subject\' must not be empty.'}]}, 400), 'reply.invalid_request', undefined], [json({code: 'contact.somethingElse'}, 400), 'reply.refused', 'contact.somethingElse'], - // An email Reply cannot time is refused under Reply's own codes, passed on unchanged. - [json({code: 'contact.scheduleNotFound'}, 404), 'reply.refused', 'contact.scheduleNotFound'], - [json({code: 'contact.scheduleHasNoSlot'}, 409), 'reply.refused', 'contact.scheduleHasNoSlot'], - [json({code: 'contact.contactTimeZoneMissing'}, 409), 'reply.refused', 'contact.contactTimeZoneMissing'], + // An email Reply cannot time maps to the codes a LinkedIn send's refusals of the same meaning map to, each + // read only under the status Reply publishes it with. + [json({code: 'contact.scheduleNotFound'}, 404), 'schedule.not_found', 'contact.scheduleNotFound'], + [json({code: 'contact.scheduleHasNoSlot'}, 409), 'schedule.no_slot', 'contact.scheduleHasNoSlot'], + [json({code: 'contact.contactTimeZoneMissing'}, 409), 'contact.time_zone_missing', 'contact.contactTimeZoneMissing'], + [json({code: 'contact.scheduleNotFound'}, 400), 'reply.refused', 'contact.scheduleNotFound'], + [json({code: 'contact.contactTimeZoneMissing'}, 404), 'reply.refused', 'contact.contactTimeZoneMissing'], ]; for (const [res, code, reply_code] of cases) { diff --git a/src/operations/commands.ts b/src/operations/commands.ts index 048d849..8d38263 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -334,7 +334,8 @@ const time_zone_options = (c: Command): Command=>c const scheduler_options = (c: Command): Command=>time_zone_options(c) .option('--retry-window-minutes ', 'How long Reply keeps trying once the send is due, 1 to 4320 (Reply\'s default: 90)'); -// What a send timed by a schedule answers while it waits for the schedule's next opening, and the time zone it is read in. +// What a send timed by a schedule answers while it waits for the schedule's next opening, the time zone it is read in, and +// the refusals of one Reply cannot time. const SCHEDULED = 'A send timed by --schedule-id may answer state waitingForSchedule, held for the schedule\'s next opening:\n' + 'send_after is then left out, and estimated_send_at is when Reply expects to send it, or null when the schedule does\n' + 'not open within 30 days of the moment the send waits from: its --send-after, or when Reply took it.\n' @@ -343,21 +344,17 @@ const SCHEDULED = 'A send timed by --schedule-id may answer state waitingForSche + 'Reply gives it. --use-contact-time-zone sends useContactTimeZone true: the schedule\'s windows are read in the\n' + 'contact\'s time zone; --no-use-contact-time-zone sends false, the schedule\'s own zone; with neither, the schedule\'s\n' + 'own setting holds. Reply takes it only with --schedule-id, and answers it otherwise with errors[]\n' - + '(reply.invalid_request).\n'; + + '(reply.invalid_request). schedule.not_found is a --schedule-id naming no schedule this account can read,\n' + + 'schedule.no_slot a schedule with no active day that has a time range, so it never opens, and\n' + + 'contact.time_zone_missing a contact without the time zone --use-contact-time-zone reads it in; none sends anything.\n'; -// The retry window only a LinkedIn send takes, and the refusals of a LinkedIn send Reply cannot time. +// The codes of a send Reply cannot time, the same on every route. +const SCHEDULE_CODES = ['schedule.not_found', 'schedule.no_slot', 'contact.time_zone_missing']; + +// The retry window only a LinkedIn send takes. const LINKEDIN_SCHEDULED = '--retry-window-minutes is how long Reply keeps trying to send it once it is due, 1 to 4320\n' + 'minutes (Reply\'s default is 90); one outside that is refused before any call (usage.range). Reply takes it only with\n' - + '--schedule-id or --send-after, and answers it otherwise with errors[] (reply.invalid_request). schedule.not_found is\n' - + 'a --schedule-id naming no schedule this account can read, schedule.no_slot a schedule with no active day that has a\n' - + 'time range, so it never opens, and contact.time_zone_missing a contact without the time zone\n' - + '--use-contact-time-zone reads it in; none sends anything.\n'; - -// An email Reply cannot time is refused under Reply's own codes, which reach the caller unchanged. -const EMAIL_SCHEDULED = 'Reply refuses an email it cannot time when it takes it, and nothing is sent: a --schedule-id naming no\n' - + 'schedule this account can read, a schedule with no active day that has a time range, and a contact without the time\n' - + 'zone --use-contact-time-zone reads it in are reply.refused, with Reply\'s contact.scheduleNotFound,\n' - + 'contact.scheduleHasNoSlot or contact.contactTimeZoneMissing as reply_code.\n'; + + '--schedule-id or --send-after, and answers it otherwise with errors[] (reply.invalid_request).\n'; time_zone_options(later_options(add_contact_options(contact_command.command('send-email'), true) .option('--email-account-id ', 'The mailbox to send from (see `account list`)') @@ -369,7 +366,7 @@ time_zone_options(later_options(add_contact_options(contact_command.command('sen [`echo '{"subject":"Quick question","body":"

Hi Ann, does Tuesday work?

"}' | ${P} contact send-email --contact-id 456 --email-account-id 12 --message -`, piped_send('send-email', ANN_EMAIL, '{"subject":"Quick question","body":"

Hi Ann

"}', '--email-account-id 12')], ['contact.not_found', ...IMPORT_CODES, 'contact.already_held', 'email_account.not_found', 'contact.blacklisted', - 'contact.missing_variables', 'contact.rendering_failed', ...KEY_CODES], true, + 'contact.missing_variables', 'contact.rendering_failed', ...SCHEDULE_CODES, ...KEY_CODES], true, 'Result: {"status":"sent","contact_id","contact_created","message_id","sent_at","reply_status"}: sent means Reply\n' + 'accepted the email, and reply_status is Reply\'s own word for it (new or sent). message_id is Reply\'s messageId,\n' + 'null when it gives none. Reply\'s answer carries no time, so sent_at is always null; the CLI adds none of its own.\n' @@ -380,7 +377,7 @@ time_zone_options(later_options(add_contact_options(contact_command.command('sen + 'them; a send held for later has neither. contact.missing_variables names the variables Reply could not fill in\n' + 'details.missing_variables when Reply lists them, and contact.rendering_failed is a template Reply could not\n' + 'render, its message in detail. Neither sends anything.\n' - + LATER + SCHEDULED + EMAIL_SCHEDULED + SENT_TO('email', 'email'), + + LATER + SCHEDULED + SENT_TO('email', 'email'), SEND_TWICE('email'))) .action(run(async(cmd)=>{ const {g, ctx} = ctx_of(cmd); @@ -390,8 +387,7 @@ time_zone_options(later_options(add_contact_options(contact_command.command('sen // The four LinkedIn sends share their flags, their first codes and the shape of their result. const LINKEDIN_SEND_CODES = [ 'contact.not_found', ...IMPORT_CODES, 'contact.already_held', 'contact.no_linkedin_profile', 'linkedin.account_not_found', - 'linkedin.feature_disabled', 'linkedin.account_inactive', 'linkedin.invalid_cookie', 'schedule.not_found', 'schedule.no_slot', - 'contact.time_zone_missing', + 'linkedin.feature_disabled', 'linkedin.account_inactive', 'linkedin.invalid_cookie', ...SCHEDULE_CODES, ]; const LINKEDIN_SENT = '"contact_id","contact_created","activity_id","sent_at"}:\n' + 'activity_id and sent_at are Reply\'s linkedInActivityId and sentAtUtc as Reply gives them, each null when it gives\n' diff --git a/src/operations/direct-send.ts b/src/operations/direct-send.ts index da2a4e3..bc201f2 100644 --- a/src/operations/direct-send.ts +++ b/src/operations/direct-send.ts @@ -126,6 +126,17 @@ const TEMPLATE_REFUSALS: Record> = { linkedin: {}, }; +// The refusals of a send Reply cannot time, whichever route it went to. +const SCHEDULE_NOT_FOUND: Refusal = { + status: 404, code: 'schedule.not_found', title: 'Reply has no sending schedule by that id that this account can use, so nothing was sent.', +}; +const SCHEDULE_NO_SLOT: Refusal = { + status: 409, code: 'schedule.no_slot', title: 'The sending schedule has no active day with a time range, so it never opens; nothing was sent.', +}; +const TIME_ZONE_MISSING: Refusal = { + status: 409, code: 'contact.time_zone_missing', title: 'Reply holds no time zone for the contact to read the schedule in, so nothing was sent.', +}; + // Reply's refusals of a direct send, by status and code. Each one is definite: nothing was sent. const REFUSALS: Record = { 'contact.emailAccountNotFound': { @@ -176,16 +187,14 @@ const REFUSALS: Record = { 'directLinkedIn.voiceTooLong': { status: 400, code: 'linkedin.voice_too_long', title: 'The voice message would be longer than Reply allows, so nothing was sent.', }, - // A LinkedIn send timed by a schedule: refused when it is taken, before anything is held. - 'directLinkedIn.scheduleNotFound': { - status: 404, code: 'schedule.not_found', title: 'Reply has no sending schedule by that id that this account can use, so nothing was sent.', - }, - 'directLinkedIn.scheduleHasNoSlot': { - status: 409, code: 'schedule.no_slot', title: 'The sending schedule has no active day with a time range, so it never opens; nothing was sent.', - }, - 'directLinkedIn.contactTimeZoneMissing': { - status: 409, code: 'contact.time_zone_missing', title: 'Reply holds no time zone for the contact to read the schedule in, so nothing was sent.', - }, + // A send timed by a schedule: refused when it is taken, before anything is held. The email route and + // the LinkedIn routes each name it in their own family, and both map to the code of its meaning. + 'directLinkedIn.scheduleNotFound': SCHEDULE_NOT_FOUND, + 'directLinkedIn.scheduleHasNoSlot': SCHEDULE_NO_SLOT, + 'directLinkedIn.contactTimeZoneMissing': TIME_ZONE_MISSING, + 'contact.scheduleNotFound': SCHEDULE_NOT_FOUND, + 'contact.scheduleHasNoSlot': SCHEDULE_NO_SLOT, + 'contact.contactTimeZoneMissing': TIME_ZONE_MISSING, }; const LIMITS: Record = {'directLinkedIn.dailyLimitReached': 'daily', 'directLinkedIn.weeklyLimitReached': 'weekly'}; From 84307e836837a2dfbd2b6fa31e66c9e40d139382 Mon Sep 17 00:00:00 2001 From: Artem Kosolap Date: Fri, 30 Oct 2026 22:19:28 -0700 Subject: [PATCH 15/15] docs: estimated_send_at is set in waitingForSchedule only, and null there 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. --- README.md | 31 +++++++++++------------ src/__tests__/operations/commands.test.ts | 20 ++++++++------- src/operations/commands.ts | 29 ++++++++++----------- 3 files changed, 40 insertions(+), 40 deletions(-) diff --git a/README.md b/README.md index d69d295..53a2868 100644 --- a/README.md +++ b/README.md @@ -337,11 +337,10 @@ before any call (`usage.reference`, exit 2), and nothing else is read from it. A A send timed by `--schedule-id` may answer `state` `waitingForSchedule`: Reply holds it for the schedule's next opening, so `send_after` is left out, and `estimated_send_at` is when Reply expects -to send it, an ISO-8601 UTC moment, or null when the schedule does not open within 30 days of the -moment the send waits from: its `--send-after`, or when Reply took it. Reply sends it within about -10 minutes of that moment. `estimated_send_at` means something only with `state` -`waitingForSchedule`, where null says the schedule does not open within those 30 days; Reply gives -it null on any other state, and that null says nothing. It is added only when Reply gives it. +to send it, an ISO-8601 UTC moment; Reply sends it within about 10 minutes of that moment. Reply +sets `estimated_send_at` 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: its `--send-after`, or when Reply took it. It is added only when Reply gives it. Every direct send also takes `--use-contact-time-zone` / `--no-use-contact-time-zone`, and the four LinkedIn sends take `--retry-window-minutes ` as well; `contact send-email` does not take the @@ -387,17 +386,17 @@ Both answer the send under the CLI's names, each null when Reply gives none: `re `contact_id`, `state`, `send_after`, `sent_at`, `message_id`, `failure_reason` and `cancelled_at`. `failure_code`, `missing_variables`, `rendered_subject` and `rendered_body` are added only when Reply gives them, and so is `estimated_send_at`, read the same way as on the send but as of the -read: its 30 days then count from `--send-after`, or from now once that has passed, and it means -something only while `state` is `waitingForSchedule`. `failure_reason` is a sentence for a person -and never parsed; `failure_code` is Reply's code for the failure, the one to branch on. A failed -send may carry no `failure_code`: it is then null, and `failure_reason` is all Reply says of it. -`direct-send cancel` of a send already cancelled answers it again. A send already gone out, failed -or going out is `direct_send.already_sent`, `direct_send.already_failed` or -`direct_send.already_sending`; the last is a LinkedIn send made for later that Reply is handing to -the account's queue or that waits or runs there, even while `direct-send get` still reads it -`queued`. A reference Reply has no send for, a send of another team included, is -`direct_send.not_found`, and an email send made by a teammate this user may not act for is -`direct_send.not_owned`, to a read and a cancel alike. A `503` that Reply answers with +read: set in `waitingForSchedule` only and null in every other state, and null there too when the +schedule does not open within 30 days counted from `--send-after`, or from now once that has passed. +`failure_reason` is a sentence for a person and never parsed; `failure_code` is Reply's code for the +failure, the one to branch on. A failed send may carry no `failure_code`: it is then null, and +`failure_reason` is all Reply says of it. `direct-send cancel` of a send already cancelled answers +it again. A send already gone out, failed or going out is `direct_send.already_sent`, +`direct_send.already_failed` or `direct_send.already_sending`; the last is a LinkedIn send made for +later that Reply is handing to the account's queue or that waits or runs there, even while +`direct-send get` still reads it `queued`. A reference Reply has no send for, a send of another team +included, is `direct_send.not_found`, and an email send made by a teammate this user may not act for +is `direct_send.not_owned`, to a read and a cancel alike. A `503` that Reply answers with `directSend.cancelNotConfirmed` is `direct_send.cancel_not_confirmed` (exit 1): Reply could not confirm the cancel, and says the send is still queued or waiting for its schedule, so run the cancel again, as Reply asks; `retry_after` carries Reply's `Retry-After` when it sends one. Any other `5xx` diff --git a/src/__tests__/operations/commands.test.ts b/src/__tests__/operations/commands.test.ts index f675011..6852ce3 100644 --- a/src/__tests__/operations/commands.test.ts +++ b/src/__tests__/operations/commands.test.ts @@ -58,11 +58,12 @@ describe('operations/commands', ()=>{ expect(c.registeredArguments[0].description, name).toContain('email-, linkedin- or linkedin-scheduled-'); expect(flat, name).toContain('failure_code, missing_variables, rendered_subject and rendered_body are added only when Reply gives them'); expect(flat, name).toContain('failure_reason is a sentence for a person, never parsed; failure_code is Reply\'s code for the failure'); - expect(flat, name).toContain('estimated_send_at is added only when Reply gives it: when Reply expects a send waiting for its ' - + 'schedule\'s next opening to go out, or null when the schedule does not open within 30 days of the moment the send ' - + 'waits from: its --send-after, or now once that has passed'); - expect(flat, name).toContain('estimated_send_at means something only with state waitingForSchedule, where null says the ' - + 'schedule does not open within those 30 days; Reply gives it null on any other state, and that null says nothing'); + expect(flat, name).toContain('estimated_send_at is added only when Reply gives it, and is when Reply expects a send waiting ' + + 'for its schedule\'s next opening to go out'); + expect(flat, name).toContain('Reply sets estimated_send_at 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: its --send-after, or now once that has passed'); + expect(flat, name).not.toContain('that null says nothing'); } const cancel = help_of(sub(direct_send_command, 'cancel')).replace(/\s+/g, ' '); expect(cancel).toContain('Cancelling a send already cancelled answers it again, so running it again is safe'); @@ -315,10 +316,11 @@ describe('operations/commands', ()=>{ // Every send takes a schedule and its time zone; only the LinkedIn sends take a retry window and map the refusals. const linkedin = name !== 'send-email'; expect(flat, text).toContain('A send timed by --schedule-id may answer state waitingForSchedule'); - expect(flat, text).toContain('estimated_send_at is when Reply expects to send it, or null when the schedule does not open within ' - + '30 days of the moment the send waits from: its --send-after, or when Reply took it'); - expect(flat, text).toContain('estimated_send_at means something only with state waitingForSchedule, where null says the ' - + 'schedule does not open within those 30 days; Reply gives it null on any other state, and that null says nothing'); + expect(flat, text).toContain('send_after is then left out, and estimated_send_at is when Reply expects to send it.'); + expect(flat, text).toContain('Reply sets estimated_send_at 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: its --send-after, or when Reply took it'); + expect(flat, text).not.toContain('that null says nothing'); expect(flat, text).toContain('--use-contact-time-zone sends useContactTimeZone true: the schedule\'s windows are read in the ' + 'contact\'s time zone; --no-use-contact-time-zone sends false, the schedule\'s own zone; with neither, the schedule\'s ' + 'own setting holds. Reply takes it only with --schedule-id, and answers it otherwise with errors[] (reply.invalid_request)'); diff --git a/src/operations/commands.ts b/src/operations/commands.ts index 8d38263..b28d421 100644 --- a/src/operations/commands.ts +++ b/src/operations/commands.ts @@ -336,17 +336,16 @@ const scheduler_options = (c: Command): Command=>time_zone_options(c) // What a send timed by a schedule answers while it waits for the schedule's next opening, the time zone it is read in, and // the refusals of one Reply cannot time. -const SCHEDULED = 'A send timed by --schedule-id may answer state waitingForSchedule, held for the schedule\'s next opening:\n' - + 'send_after is then left out, and estimated_send_at is when Reply expects to send it, or null when the schedule does\n' - + 'not open within 30 days of the moment the send waits from: its --send-after, or when Reply took it.\n' - + 'estimated_send_at means something only with state waitingForSchedule, where null says the schedule does not open\n' - + 'within those 30 days; Reply gives it null on any other state, and that null says nothing. It is added only when\n' - + 'Reply gives it. --use-contact-time-zone sends useContactTimeZone true: the schedule\'s windows are read in the\n' - + 'contact\'s time zone; --no-use-contact-time-zone sends false, the schedule\'s own zone; with neither, the schedule\'s\n' +const SCHEDULED = 'A send timed by --schedule-id may answer state waitingForSchedule, held for the schedule\'s next opening: send_after is\n' + + 'then left out, and estimated_send_at is when Reply expects to send it. Reply sets estimated_send_at in\n' + + 'waitingForSchedule only and gives it null in every other state; it is null in waitingForSchedule too when the schedule\n' + + 'does not open within 30 days of the moment the send waits from: its --send-after, or when Reply took it. It is added\n' + + 'only when Reply gives it. --use-contact-time-zone sends useContactTimeZone true: the schedule\'s windows are read in\n' + + 'the contact\'s time zone; --no-use-contact-time-zone sends false, the schedule\'s own zone; with neither, the schedule\'s\n' + 'own setting holds. Reply takes it only with --schedule-id, and answers it otherwise with errors[]\n' + '(reply.invalid_request). schedule.not_found is a --schedule-id naming no schedule this account can read,\n' - + 'schedule.no_slot a schedule with no active day that has a time range, so it never opens, and\n' - + 'contact.time_zone_missing a contact without the time zone --use-contact-time-zone reads it in; none sends anything.\n'; + + 'schedule.no_slot a schedule with no active day that has a time range, so it never opens, and contact.time_zone_missing\n' + + 'a contact without the time zone --use-contact-time-zone reads it in; none sends anything.\n'; // The codes of a send Reply cannot time, the same on every route. const SCHEDULE_CODES = ['schedule.not_found', 'schedule.no_slot', 'contact.time_zone_missing']; @@ -620,12 +619,12 @@ const DIRECT_SEND = 'Result: {"reference","channel","contact_id","state","send_a + 'failure_reason is a sentence for a person, never parsed; failure_code is Reply\'s code for the failure, the one to\n' + 'branch on. A failed send may carry no failure_code: it is then null, and failure_reason is all Reply says of it.\n' + 'missing_variables lists the template variables Reply could not fill, and rendered_subject and rendered_body are the\n' - + 'text as Reply filled it in. estimated_send_at is added only when Reply gives it: when Reply expects a send waiting for\n' - + 'its schedule\'s next opening to go out, or null when the schedule does not open within 30 days of the moment the send\n' - + 'waits from: its --send-after, or now once that has passed. estimated_send_at means something only with state\n' - + 'waitingForSchedule, where null says the schedule does not open within those 30 days; Reply gives it null on any other\n' - + 'state, and that null says nothing. A Reply without this route answers reply.refused with status 404 and no reply_code;\n' - + 'a reference of any other form never leaves the CLI, so that 404 means this Reply has no such route.\n' + + 'text as Reply filled it in. estimated_send_at is added only when Reply gives it, and is when Reply expects a send\n' + + 'waiting for its schedule\'s next opening to go out. Reply sets estimated_send_at in waitingForSchedule only and gives\n' + + 'it null in every other state; it is null in waitingForSchedule too when the schedule does not open within 30 days of\n' + + 'the moment the send waits from: its --send-after, or now once that has passed. A Reply without this route answers\n' + + 'reply.refused with status 404 and no reply_code; a reference of any other form never leaves the CLI, so that 404 means\n' + + 'this Reply has no such route.\n' + 'direct_send.not_found is a reference that Reply has no send for, a send of another team included.\n' + 'direct_send.not_owned is an email send made by a teammate this user may not act for.\n';