pp-slickdeals

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/commerce/slickdeals/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Slickdeals — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `slickdeals-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install slickdeals --cli-only
   ```
2. Verify: `slickdeals-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/commerce/slickdeals/cmd/slickdeals-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

## When to Use This CLI

Use this CLI when you need agent-native access to Slickdeals data — hot deals, frontpage feed, coupons, category browsing, and local deal-tracking over time. The v0.2 release expands beyond v0.1's Nuxt endpoint wrapping: it adds an RSS surface for live frontpage data and a local SQLite snapshot store so agents can track deal velocity, run compound queries, and generate merchant analytics entirely offline.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.
- **`hot`** — Top live frontpage deals filtered by min-thumbs, sorted thumbs DESC.
- **`frontpage-fresh`** — Live unfiltered frontpage RSS feed (today's drops).
- **`popular`** — Slickdeals "Popular Deals" feed (community-voted, distinct from editor-curated frontpage). _New in v0.3_
- **`search --live`** — Real server-side keyword search via the `q=` parameter, optionally scoped with `--forum N`. _Fixed in v0.3 — v0.2 used the wrong parameter name and silently fell back to client-side filtering._
- **`category`** — Forum-scoped RSS feed via `forumchoice[]=N`. Five Slickdeals-advertised forum IDs: 4 (Freebies), 9 (Hot Deals), 10 (Coupons), 25 (Contests), 38 (Drugstore/Grocery). _Rewritten in v0.3 to use real server-side filtering instead of v0.2's client-side keyword map._
- **`coupons`** — Live featured coupon list with optional --store merchant filter (Nuxt JSON endpoint).
- **`watch`** — Fetch a single deal from the live frontpage RSS, optionally persisting a snapshot row for time-series analytics.
- **`digest`** — Summarize the top-N captured snapshots over a window, optionally capped per merchant and grouped by merchant/category.
- **`deals`** — Flagship SQL compound query over captured snapshots: --store costco --since 24h --min-thumbs 50.
- **`analytics top-stores`** — Merchant aggregation over a time window: deal_count, avg_thumbs, max_thumbs, first/last seen.
- **`analytics thumbs-velocity`** — Chronological thumb-count observations for a deal with per-step delta — momentum signal for arbitrage and auto-snipe.

## HTTP Transport

This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.

## Command Reference

### v0.1 Commands (Nuxt endpoint wrappers)

**ad-stats** — Operations on ad-events

- `slickdeals-pp-cli ad-stats <id>` — POST /ad-stats/{id}/ad-events

**ajax** — Operations on bSubNavPlacement.php

- `slickdeals-pp-cli ajax create_threadrate.php` — POST /ajax/threadrate.php
- `slickdeals-pp-cli ajax list_bSubNavPlacement.php` — GET /ajax/bSubNavPlacement.php

**frontpage** — Operations on recommendations

- `slickdeals-pp-cli frontpage list_json` — GET /frontpage/promoted-content/json
- `slickdeals-pp-cli frontpage list_recommendations` — GET /frontpage/recommendation-carousel/recommendations

**web-api** — Operations on missed-deals

- `slickdeals-pp-cli web-api list_featured_coupons` — GET /web-api/frontpage/featured-coupons/
- `slickdeals-pp-cli web-api list_missed_deals` — GET /web-api/frontpage/missed-deals/

### v0.2 Commands (Live RSS surface + local snapshot transcendence)

**hot** — Top Slickdeals frontpage deals by thumb count (live RSS)

- `slickdeals-pp-cli hot [--min-thumbs N] [--limit N]` — Pulls the live frontpage RSS and surfaces only deals whose community thumb score meets `--min-thumbs`. Results sorted by thumbs descending. Client-side filter (the `forum=9&hotdeals=1` RSS lever returns empty feeds).

**frontpage-fresh** — Fresh Slickdeals frontpage RSS feed (live, unfiltered)

- `slickdeals-pp-cli frontpage-fresh [--limit N]` — Pulls today's drops from the live frontpage RSS (`/newsearch.php?mode=frontpage&rss=1`). Items in feed order (newest first). Unlike v0.1 `frontpage list-json`, this is not Nuxt-cached.

**search** — Full-text search across synced data or live API

- `slickdeals-pp-cli search "<query>" [--live] [--limit N]` — FTS5 search against locally synced data, or `--live` to hit the live RSS search endpoint. Client-side keyword filter on the frontpage feed (Slickdeals' RSS does not honor server-side `search=` params).

**category** — Browse deals by Slickdeals forum category

- `slickdeals-pp-cli category <id|name> [--limit N]` — Fetch live RSS deals for a forum category by numeric ID or friendly name (e.g. `tech`, `gaming`). Use `--list` to print the full built-in category→forum-ID map. Client-side filter against the frontpage feed.

**coupons** — List Slickdeals featured coupons (live Nuxt JSON)

- `slickdeals-pp-cli coupons [--store <name>] [--limit N]` — Fetch the live featured-coupons list via `/web-api/frontpage/featured-coupons/`. Uses the Nuxt endpoint because the RSS coupon filter (`f2=1`) does not work — Slickdeals ignores it and returns the frontpage feed.

**watch** — Fetch a single Slickdeals deal by ID from the live frontpage RSS feed

- `slickdeals-pp-cli watch <deal-id> [--persist] [--once]` — Fetch the current frontpage RSS and report the matching item. Use `--persist` to write the snapshot to the local SQLite store for later `digest`/`deals`/`analytics` queries. `--once` is the default (v0.2); background polling is v0.3.

**digest** — Summarize the top deals captured locally over a recent window

- `slickdeals-pp-cli digest [--since 24h] [--top N] [--merchant-cap N] [--grouped-by merchant|category]` — Read the local `deal_snapshots` store and return top deals within the window, sorted by thumbs. Snapshots are populated by `watch --persist`. Empty store returns a hint and an empty envelope.

**deals** — Compound query over locally captured deal snapshots

- `slickdeals-pp-cli deals [--store <name>] [--category <name>] [--since <dur>] [--min-thumbs N] [--deal-id <id>] [--latest]` — SQL compound query over the local `deal_snapshots` table. Returns the latest snapshot per deal by default (`--latest=true`). Does not hit the live feed.

**analytics top-stores** — Rank merchants by deal count and thumb score over a window

- `slickdeals-pp-cli analytics top-stores [--window 30d] [--limit N]` — Aggregate `deal_snapshots` by merchant over the given window, sorted by distinct deal count then max thumbs. Window accepts the same suffixes as `--since`: `30d`, `24h`, `1w`, `30m`, or `0` for all-time.

**analytics thumbs-velocity** — Time-series of thumb scores for one deal, with deltas

- `slickdeals-pp-cli analytics thumbs-velocity <deal-id>` — Return the chronological sequence of thumb observations for a single deal ID. Each row carries the absolute thumb count plus delta from the previous