Shop Watches

The person's own watches through the codespar_watch tool. Tell them when a researched offer's price drops or a purchase's order moves, in the app and by e-mail. A watch the assistant prepares runs only after the person confirms it.

A watch follows something for the signed-in person and tells them when it changes: the total of an offer from a research, or the order of a purchase. The tool is codespar_watch, on the hosted server. It never buys anything.

A person, not a key. Like Shop memory, every call needs a verified person. A project API key or an OAuth token is refused with 403 bearer_token_has_no_person.

Actions

`action`	What it does	Money	Needs
`watch_create` example below	Prepare a watch on a researched offer's price (price_drop) or a purchase's order (delivery_track); it waits for the person's confirmation	no	`kindoffer_ref`or`purchase_id`
`watch_list`	List the person's watches	no	—
`watch_cancel`	Stop a watch; nothing runs after it	no	`watch_id`

Names come from the published tool document (/v1/meta-tools.json, the same list the MCP server answers to tools/list); the one-line summaries and the money class are kept in the docs repository and checked against it on every build.

How a watch runs

Prepared. watch_create answers a watch in paused with reason awaiting_confirmation. Nothing is observed yet.
Confirmed by the person. The person taps Confirmar on its card in the Shop conversation (or on Shop › Preferências). The tool cannot confirm it.
Observed. A price_drop watch is looked at every 6 hours at most, a delivery_track watch every 3 hours. A price_drop watch quotes the offer again and tells the person when its total, shipping included, falls below the total it started from (and, with target_total_minor, only at or below that target); a delivery_track watch tells them when the order's status changes, and is done once the order reaches its last status.
Notice. Each change is a notice in the app and, with the email channel, an e-mail to the person's verified address. A price notice links to the offer, from which the person may prepare a purchase; nothing is bought until the person presses Pagar.
Ends. A watch ends when it is done, cancelled, or expires: 30 days by default for price_drop, 60 for delivery_track, at most 90 (expires_in_days).

Each person has at most 20 watches that are not finished per project.

Example

tools/call

{
  "name": "codespar_watch",
  "arguments": {
    "action": "watch_create",
    "kind": "price_drop",
    "offer_ref": "sof_0000",
    "target_total_minor": 19990,
    "channels": ["in_app", "email"]
  }
}

The answer carries the watch with state: "paused" and paused_reason: "awaiting_confirmation". Tell the person to confirm it on its card.

Arguments

Field	Type	Required	Description
`action`	`string`	Yes	`watch_create` \| `watch_list` \| `watch_cancel`
`kind`	`string`	For `watch_create`	`price_drop` or `delivery_track`
`offer_ref`	`string`	For `price_drop`	The `offer_id` (`sof_…`) of an offer from a research of this person (`codespar_shop` `research`)
`purchase_id`	`string`	For `delivery_track`	The person's purchase (`prp_…`)
`target_total_minor`	`integer`	No	`price_drop`: tell only at or below this total, in centavos
`channels`	`string[]`	No	`in_app` (default) and/or `email`
`expires_in_days`	`integer`	No	1..90
`watch_id`	`string`	For `watch_cancel`	The watch to stop

Errors and what to do

Code	Status	Cause	What to do
`bearer_token_has_no_person`	403	The call carries a key or an OAuth token, not a verified person.	Call as the signed-in person.
`watch_kind_unsupported`	400	A kind this delivery does not create.	Use `price_drop` or `delivery_track`.
`watch_channel_unavailable`	400	A channel this delivery does not send through, or `email` without a verified address or a configured sender.	Use `in_app`, or have the person verify an e-mail.
`watch_limit_reached`	409	The person already has 20 open watches in this project.	Cancel one first.
`watch_subject_unavailable`	422	The offer or purchase is unknown, not the person's, or not resolvable yet; or `expires_in_days` is out of range.	Use an offer from a research of this person, or one of their purchases.
`watch_not_active`	409	The watch is not in a state that takes this action (confirm, change channels, run).	Read it again.
`watch_not_found`	404	No watch of the calling person has this id. Another person's answers the same.	`watch_list`.
`notification_not_found`	404	No notice of the calling person has this id (the dashboard's notice routes).	None: it is not theirs or not there.
`watch_run_test_only`	403	A manual run of a watch, which exists only in Test projects.	Let the schedule run it.

codespar_shop: research is where the offers a price_drop watch follows come from
Shop memory: the person's remembered preferences
Test mode: what a Test project's purchases and notices are

Notes

Notices. The person reads their notices in the dashboard; an e-mail links to the notice's page (ids only, no content in the link). A notice of another person, or one that does not exist, answers the same 404 notification_not_found.