Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
d03c22a
fix: direct-send get and cancel accept linkedin-scheduled-<n>, a defe…
ArtemKosolap Oct 31, 2026
bbbc370
feat: direct sends answer estimated_send_at for a LinkedIn send waiti…
ArtemKosolap Oct 31, 2026
a7a6e95
docs: direct-send help names waitingForSchedule and a failed send wit…
ArtemKosolap Oct 31, 2026
525f074
feat: direct-send cancel answers a send already going out and a cance…
ArtemKosolap Oct 31, 2026
5f6b50f
feat: the four LinkedIn sends take --use-contact-time-zone and --retr…
ArtemKosolap Oct 31, 2026
b88e269
feat: the LinkedIn sends map Reply's three refusals of a send it cann…
ArtemKosolap Oct 31, 2026
6aaaf8f
fix: direct-send cancel says an unconfirmed cancel left the send wait…
ArtemKosolap Oct 31, 2026
e366111
docs: direct-send help words the schedule, ownership and sending refu…
ArtemKosolap Oct 31, 2026
04cdbbf
docs: estimated_send_at counts its 30 days from the moment the send w…
ArtemKosolap Oct 31, 2026
4921023
docs: estimated_send_at means something only while a send waits for i…
ArtemKosolap Oct 31, 2026
4dfe133
feat: contact send-email takes --use-contact-time-zone and --no-use-c…
ArtemKosolap Oct 31, 2026
560eabe
docs: rewrap the direct-send help and README to the width of their ne…
ArtemKosolap Oct 31, 2026
fc706a7
docs: drop the claim that a Reply without the scheduler refuses --sch…
ArtemKosolap Oct 31, 2026
39a06de
feat: an email Reply cannot time is refused under the same codes as s…
ArtemKosolap Oct 31, 2026
84307e8
docs: estimated_send_at is set in waitingForSchedule only, and null t…
ArtemKosolap Oct 31, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
80 changes: 61 additions & 19 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -202,6 +202,8 @@ prints JSON (indented; compact with `--json`) and says what happened in a stable
| `reply contact linkedin-connect <contact> --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 <moment>] [--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` |
| 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 <reference>` | a send as Reply holds it: whether it has gone out, when, and why it failed |
| `reply direct-send cancel <reference>` | 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 |
Expand Down Expand Up @@ -319,18 +321,46 @@ 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 <moment>`, `--schedule-id <id>` and `--idempotency-key
<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` or `sending` is not yet, then `sent`, `failed` or `cancelled`. `reply
direct-send get <reference>` reads the send later, and `reply direct-send cancel <reference>` stops
one that has not gone out. The reference is Reply's, `email-<n>` or `linkedin-<n>`, 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 <moment>`, `--schedule-id <id>` and
`--idempotency-key <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 <reference>` reads the send later, and
`reply direct-send cancel <reference>` stops one that has not gone out. The reference is Reply's,
`email-<n>`, `linkedin-<n>` or `linkedin-scheduled-<n>` (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
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 <n>` 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`.

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
# {"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
Expand All @@ -352,13 +382,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. `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`.
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: 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`
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`.
Expand Down
60 changes: 50 additions & 10 deletions src/__tests__/operations/commands.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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)
{
Expand All @@ -45,18 +46,34 @@ 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-<n> or linkedin-<n>, the form Reply\'s route takes');
expect(flat, name).toContain('email-<n>, linkedin-<n> or linkedin-scheduled-<n>, 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-<n> or linkedin-<n>');
expect(c.registeredArguments[0].description, name).toContain('email-<n>, linkedin-<n> or linkedin-scheduled-<n>');
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, 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');
}
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.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)');
});

it('schedule list takes no flag and no id, and says how a time zone, a weekday, a time and a state are written', ()=>{
Expand Down Expand Up @@ -244,11 +261,12 @@ 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',
'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],
Expand All @@ -274,7 +292,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',
'--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 -');
Expand All @@ -292,8 +311,29 @@ 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 <reference> reads it later, and direct-send cancel <reference> stops one not yet sent');
// 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('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)');
expect(flat.includes('--retry-window-minutes <n> 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');
// 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');
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 '
Expand Down
Loading
Loading