report

Invocation#

echo-cli report market --week-of <YYYY-MM-DD>
echo-cli report recipients
echo-cli report subscribe --recipient <email|https webhook> --by <name>
echo-cli report unsubscribe --recipient <email|https webhook>
echo-cli report send [--week-of <YYYY-MM-DD>] --by <name>

Inputs and output#

market writes week_start and week_end (Monday 00:00 UTC and the next Monday) and items, oldest first, each with kind (pricing, capture, release or trend), at, summary and evidence: the table, id and address of the stored record it comes from. recipients writes recipients (recipient — an address in lower case or a webhook address as given — declared_by, declared_at) and deliveries, the archive newest week first: id, week_start, recipient, report (the report as it was sent), sent_by, attempted_at and error (null when it was sent). subscribe and unsubscribe write the recipient; send writes { deliveries }, the attempts it made. A webhook is sent one POST of JSON { text, report }: text is the plain text an email carries, report the same object market writes, so a chat channel's incoming webhook that reads text shows the report and any other receiver reads its items.

State effect#

report market calls Echo Web's authenticated /api/market/report, and recipients, subscribe, unsubscribe and send /api/market/report/deliveries, with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Weekly market report and Market report delivery sections of the competitors screen and the Market report section of Echo Desktop's GEO screen (with its delivery under it) call the same operations, and echo-mcp reads the report (echo_market_report) and the subscribers with the archive (echo_market_report_deliveries). --week-of may be any day of the week wanted; the report covers the ISO week holding it, up to but not including the next Monday's first instant. It lists every competitor price move (competitors pricing), every competitor page capture, including one that could not be read with its error (competitors captures), every competitor release first seen on a watched changelog in that week, at the time Echo first saw it, with its heading and the date the changelog gives it (competitors releases list), and every collected platform trend stored in that week, and nothing stored in another. Every Monday at 07:29 UTC /api/cron/market-report delivers the report of the week that just ended to each subscribed recipient not yet sent that week: an address is emailed the plain text with every item's evidence, from ECHO_MARKET_REPORT_FROM through Echo's Resend integration; a webhook is posted { text, report } and counts as reached once it answers a success status. send does the same now, for the week holding --week-of or the last ended week. Every attempt is kept in market_report_deliveries with the report as it was sent, or the error that stopped it (for a webhook "the webhook answered HTTP <status>: <body>" or "the webhook could not be reached: <why the connection failed>"); a week is sent to a recipient once, and a failed attempt is tried again by the next run. A suppressed address is not emailed; the webhook address is itself the credential, as a chat channel's incoming webhook is, so keep it as secret as one.

Refusals#

• A wrong invocation is refused before anything is sent: "report takes <every verb's usage, separated by semicolons>; got <word>", "report <verb> does not take <flag>; it takes …", "<flag> needs a value" and "report <verb> needs <flag>".
• Echo Web answers a bad request with "week_of must be a YYYY-MM-DD day; got <value>", "address must be one email address, a local part and a domain around one @; got <value>", "recipient <value> is a plain http address; a webhook must be HTTPS, since the report travels to it", "recipient <value> starts as an HTTPS webhook address but is not one", "declared_by is required: an internal caller has no signed-in user, so it names who is acting" (and sent_by) or "no address is subscribed to the market report; echo-cli report subscribe --recipient <email> --by <name> adds one"; and not found with "<recipient> is not subscribed to the market report; echo-cli report recipients lists who is". A send that fails for one recipient — a suppressed address, ECHO_MARKET_REPORT_FROM not declared, Resend refusing, a webhook unreachable or answering an error status — is not a refusal: it is archived with that error and tried again by the next send. The command prints Echo Web's sentence and exits non-zero.