calendar

Invocation#

echo-cli calendar list --product <id> --from <YYYY-MM-DD> --to <YYYY-MM-DD>
echo-cli calendar add --product <id> --kind <kind> --title <text> --starts-on <YYYY-MM-DD> --ends-on <YYYY-MM-DD> --by <name>
echo-cli calendar remove <event-id>
echo-cli calendar place --product <id> --source ad|crm --campaign <campaign-id> --starts-on <YYYY-MM-DD> --ends-on <YYYY-MM-DD> --by <name>
echo-cli calendar unplace <placement-id>

Inputs and output#

list writes product_id, from, to, events (id, product_id, kind, title, starts_on, ends_on, created_by, created_at), campaigns (id, name, platform, action, status, window_start, window_end, null when open), scheduled (id, campaign_id, target, scheduled_for, status, account_id), launches (id, product_id, name, launch_on, created_by, created_at), launch_tasks (id, launch_id, launch_name, title, owner, due_on, asset, asset_ref, done_by, done_at) and placed (id, product_id, source, campaign_id, starts_on, ends_on, placed_by, placed_at, and the campaign's name and status). add and remove write the event they made or removed; place writes the placement with the campaign's name and status, unplace the placement it removed.

State effect#

Every verb calls Echo Web's authenticated /api/analytics/calendar, and place and unplace /api/analytics/calendar/placements, with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the GTM calendar and Paid and CRM campaigns on the calendar sections of the tracking screen and the GTM calendar section of Echo Desktop's GEO screen call the same operations, and echo-mcp reads the calendar (echo_gtm_calendar) but cannot change it. list runs from the start of --from through the end of --to: an event counts when its days overlap them, a posting campaign when its window does (an open window overlaps every later day), a campaign item when it is due within them, a launch (echo-cli launch) when its day falls within them, a launch task when it is due within them, whatever its launch's day, and a placed campaign when its placed days overlap them. Events and placements are what the calendar stores; campaigns, their items, launches and their tasks are read from where the scheduler and the launch playbooks keep them, so the view always matches them. The kind is the operator's own word (launch, campaign, season or anything else) and is kept as written. A synced paid-ads campaign (ad_campaigns) and a CRM outreach campaign (crm_campaigns) name neither a product nor the days they run, so place puts one on a product's calendar over the days given, kept in gtm_calendar_placements, once per campaign; its name and status are read from its own table on every list, so a renamed or paused campaign shows as it is.

Refusals#

• A wrong invocation is refused before anything is sent: "calendar takes <every verb's usage, separated by semicolons>; got <word>", "calendar <verb> does not take <flag>; it takes …", "<flag> needs a value", "calendar <verb> needs <flag>" for each flag the verb needs, "calendar remove needs an event id, as calendar list prints it" and "calendar unplace needs a placement id, as calendar list prints it".
• Echo Web answers a bad request with "product_id is required: …", "from is required: the first day to read" (and to), "from must be a YYYY-MM-DD day; got <value>" (to, starts_on, ends_on), "to <day> is before from <day>", "kind is required: what sort of event it is, such as launch, campaign or season", "title is required: what the event is, in words", "ends_on <day> is before starts_on <day>" or "created_by is required: an internal caller has no signed-in user, so it names who is acting"; and not found with "no product has id <id>; echo-cli products lists the ones that exist" or "no calendar event has id <id>; echo-cli calendar list --product <id> --from <day> --to <day> lists them". The command prints Echo Web's sentence and exits non-zero.
• place and unplace are refused with "source must be one of ad, crm: the store the campaign lives in; got <value>", "campaign_id is required: the campaign, by its id in that store", "ends_on <day> is before starts_on <day>", "placed_by is required: …", a conflict with "<source> campaign <id> is already placed as <placement-id>, <first day> to <last day>; remove that placement first", and not found with "no synced paid-ads campaign has id <id> in ad_campaigns", "no CRM outreach campaign has id <id> in crm_campaigns" or "no calendar placement has id <id>; echo-cli calendar list --product <id> --from <day> --to <day> lists them".