hints

Invocation#

echo-cli hints list --app <web source>
echo-cli hints add --app <web source> --key <name> --title <text> --body <text> [--when-did <event> [--times <n>] [--property <name=value>]] [--unless-did <event>] [--within-days <days>] --by <name>
echo-cli hints remove --hint <hint-id>
echo-cli hints activity --hint <hint-id>
echo-cli hints widget --app <web source>

Inputs and output#

list writes the web source's hints by key: id, app_id, key, title, body, when_did, when_count, when_property, when_value, unless_did, within_days (each null when the hint states none), created_by and created_at. add and remove write the hint. activity writes impressions (hint_id, subject_id, shown_at) and dismissals (hint_id, subject_id, dismissed_at), newest first. widget writes script_url, snippet (the script tag with data-app and data-subject, which the page fills with the anonymous or user id its analytics send, and the element the hints are shown in) and script_bytes, the size of the script Echo Web serves now.

State effect#

Every verb calls Echo Web's authenticated /api/analytics/hints with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL, except widget, which reads the public /api/public/hints/widget without a bearer; the Product hints section of the tracking screen and of Echo Desktop's GEO screen call the same operation (both print the widget HTML), and echo-mcp reads hints and their activity as echo_product_hints and the widget as echo_hint_widget. A hint is shown to a subject who sent the --when-did event — at least --times times when stated (else once), each carrying --property's name with its value (compared as text) when stated — and did not send the --unless-did event, both read over the last --within-days days when stated (else every stored event), across every identifier the identity edges link to them, in the web and mobile events; a hint states at least one of the two events, and one key exists per web source. A product reads GET /api/public/hints?app_id=<source>&subject=<id> from a browser on an origin CORS_ALLOWED_ORIGINS declares and is answered { hints: [{ key, title, body }] }, every hint answered stored as an impression; it posts { app_id, key, subject } to the same address when the user closes a hint, stored once per hint and subject, and a dismissed hint is not answered to that subject again. The widget script does both from the page: it writes each hint's title and body as text with a Dismiss button into the element carrying data-echo-hints, and writes a missing element, missing data-app or data-subject, or a refusal into the element (or the console without one) with its reason. Removing a hint removes its impressions and dismissals.

Refusals#

• A wrong invocation is refused before anything is sent: "hints takes <every verb's usage, separated by semicolons>; got <word>", "hints <verb> does not take <flag>; it takes …", "<flag> needs a value" and "hints <verb> needs <flag>".
• add is refused before anything is sent with "--times must be a number; got <text>" (and --within-days) and "--property must be name=value; got <text>"; Echo Web refuses "when_count must be a positive whole number: how many times when_did must have been sent; got <value>" (and within_days), "when_count counts when_did, which the hint does not state", "when_property is read on when_did, which the hint does not state" and "when_property and when_value go together: …".
• Echo Web answers a bad request with "app_id is required: …", "key is required: the hint's name, as the product refers to it", "title is required: the hint's heading", "body is required: what the hint says" or "a hint needs a condition: when_did, unless_did or both, so it is shown only to subjects whose usage calls for it"; not found with "no hint has id <id>; echo-cli hints list --app <source> shows them"; and a conflict with "<source> already has hint <key>, <id>". The public endpoint answers "<name> is required: …" for a missing app_id, key or subject, and "<source> has no hint <key>" with 404 for a dismissal of a hint that does not exist. The command prints Echo Web's sentence and exits 1.