surveys

Invocation#

echo-cli surveys list --product <id>
echo-cli surveys publish --product <id> --name <text> --question <text> [--choice <text>]... [--when-did <event> [--times <n>] [--property <name=value>]] [--unless-did <event>] [--within-days <days>] --by <name>
echo-cli surveys results --product <id> --name <text>

Inputs and output#

list writes every version of every survey of the product, by name and newest version first: id, product_id, name, version, question, choices (null for a free answer), when_did, when_count, when_property, when_value, unless_did, within_days (each null when the version states none), created_by and created_at. publish writes the version it wrote. results writes each version of the named survey, newest first, with survey_id, version, question, answers and counts, each answer with how many gave it.

State effect#

Every verb calls Echo Web's authenticated /api/analytics/surveys with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Micro-surveys section of the tracking screen and of Echo Desktop's GEO screen call the same operations, and echo-mcp lists surveys (echo_list_surveys) and reads results (echo_survey_results). Publishing a name the product already uses writes its next version; no version is ever edited, so every answer stays tied to the wording it answered and results never mix a reworded question with the old one. --choice repeats once per answer offered; with none, any answer is taken. A version asks the signed-in users whose events — across every identifier linked to them, web and mobile — meet its usage condition, as product hints read it (hints describes --when-did, --times, --property, --unless-did and --within-days); a version stating none asks everyone. Inside a product, GET /api/public/surveys?id=<version id> shows the question and choices to anyone; GET /api/public/surveys?product_id=<id>&name=<survey> answers the signed-in user the newest version if it asks them and they have not answered it, else { survey: null, not_asked: answered | condition }; and POST /api/public/surveys { survey_id, answer } takes a signed-in user's answer, once per user and version, only from a user the version asks.

Refusals#

• A wrong invocation is refused before anything is sent: "surveys takes <every verb's usage, separated by semicolons>; got <word>", "surveys <verb> does not take <flag>; it takes …", "<flag> needs a value" and "surveys <verb> needs <flag>" for each flag the verb needs.
• publish 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>", and by Echo Web with "when_count counts when_did, which the survey does not state", "when_property is read on when_did, which the survey does not state" and "when_property and when_value go together: …". The public reads refuse "sign in to be asked: a survey asks a signed-in user by what they did" as unauthorized, and an answer from a user the version does not ask with "survey version <id> does not ask you: what you did does not meet the usage it asks for".
• Echo Web answers a bad request with "product_id is required: …", "name is required: …", "question is required: what the users are asked", "choices must offer at least two different answers, or be null for a free answer", "choices[<n>] is required: an answer offered, in words" 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 "product <id> has no survey named <name>; echo-cli surveys list --product <id> lists them". The public answer is refused with "sign in to answer: an answer belongs to a signed-in user" as unauthorized, "answer must be one of <choices>; got <answer>" as a bad request, "no survey version has id <id>" as not found and "you already answered this survey at <time>" as a conflict. The command prints Echo Web's sentence and exits non-zero.