feat(watch): add watchlist and price-drop check via Serval #63

README.md

@@ -78,6 +78,7 @@ All data commands accept `--json`. Use `--help` on a command group to see all it
 |------|----------|
 | Find | `search <query> [--limit]` · `autocomplete` · `trending` · `deals` · `info <plid> [--credit-options\|--bundle\|--card\|--reviews]` |
 | Price history | `price history <product> [--since <window>] [--series] [--no-cache]` |
+| Price watch | `watch add <product> [--target <rand>] [--drop <percent>]` · `watch add --from-wishlist <groupId>` · `watch list` · `watch check` · `watch rm <product>` |
 | Reviews | `reviews <plid> [--page <n>] [--sort <key>]` · `myreviews …` |
 | Recommend | `recommend layout [--location <location>] [--plid <id>]` · `recommend <location> --model <key> [--plid <id>] [--limit 10]` · `buy-again` |
 | Cart | `cart` · `cart add <query>` · `cart add --sku <id>` · `cart add --plid <id>` · `cart set-qty` · `cart remove` · `cart basket` · `cart clear` |
@@ -99,6 +100,14 @@ All data commands accept `--json`. Use `--help` on a command group to see all it
 
 Use `--since 90d` to select a time window. Use `--series --json` to include the points in JSON output.
 
+### Price watch
+
+`takealot watch add <product>` adds a product to a local watchlist. It makes no request. `takealot watch check` gets price data from Serval. Run it once a day.
+
+The `target` reason means that the price is at or below your target. The `drop` reason means that the price fell by the selected percentage. The `low` reason means that the price is at or below the earlier low in a history of at least 30 points.
+
+The watchlist can hold 50 products. A check can make at most 50 HTTP attempts by default. Use `--max-requests` to set a lower limit. A check stops new requests when Serval returns HTTP 429 or 403.
+
 ### Writes and account-security changes
 
 A command that changes state is a dry run until you add `--confirm`. Add `--yes` to skip the interactive prompt. An agent must get the owner's clear yes for the specific action before it uses `--confirm`. `--i-know` is a safety flag, not permission.

skill/SKILL.md

@@ -60,6 +60,21 @@ takealot price history <plid-or-url> --since 90d --json
 
 Serval usually records one price each day, but the history can have gaps. The last price can be stale. Code `not_tracked` with exit 4 means that Serval does not track the product.
 
+## Price watch
+
+Add a product. Then inspect the local watchlist once a day:
+
+```bash
+takealot watch add <plid-or-url> --target 500 --drop 5 --json
+takealot watch check --json
+```
+
+`watch add` makes no request. `watch check` gets data from Serval. A `target` alert is at or below the target. A `drop` alert meets the selected percentage. A `low` alert is at or below the earlier low in a history of at least 30 points.
+
+The watchlist has a limit of 50 products. The request cap is 50 HTTP attempts by default. The run stops new requests after HTTP 429 or 403.
+
+`watch` writes only the local watchlist file. It never changes the Takealot account. It does not need `--confirm`.
+
 ## Cart changes that remove or change lines
 
 `cart remove <sku>` and `cart set-qty <sku> <n>` read the cart before and after the write.

skill/references/commands.md

@@ -32,12 +32,21 @@ takealot deals
 takealot info <plid> [--card] [--reviews] [--credit-options] [--bundle <ids>]
 takealot reviews <plid> [--page <n>] [--sort <key>]
 takealot price history <product> [--since <window>] [--series] [--no-cache]
+takealot watch add <product> [--target <rand>] [--drop <percent>]
+takealot watch add --from-wishlist <groupId> [--drop <percent>]
+takealot watch list
+takealot watch check [--no-update] [--max-requests <n>]
+takealot watch rm <product>
 ```
 
 If the price data is missing, `info` tries again one time. If it is still missing, `price` and `skuId` are null and `unavailableReason` gives the cause. `cart add --plid` then stops with exit 1.
 
 The `price history` command reads data from Serval. Serval usually records one price each day, but the history can have gaps. The last price can be stale. Code `not_tracked` with exit 4 means that Serval does not track the product.
 
+`watch add` makes no request. `watch check` gets data from Serval once a day. `target` means at or below the target. `drop` means a fall by the selected percentage. `low` means at or below the earlier low in a history of at least 30 points.
+
+The watchlist has a limit of 50 products. A check has a default cap of 50 HTTP attempts. It stops new requests after HTTP 429 or 403. These commands write only the local watchlist. They do not change the Takealot account and do not need `--confirm`.
+
 ## Recommendations
 
 ```bash