pp-shopper

# Shopper — Printing Press CLI ## Prerequisites: Install the CLI This skill drives the `shopper-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 shopper --cli-only ``` 2. Verify: `shopper-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.5 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead: ```bash go install github.com/mvanhorn/printing-press-library/library/commerce/shopper/cmd/shopper-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. shopper-pp-cli covers all six Shopper storefronts (Compra Programada, Fresh, Pet, Compra Única, Now, Now Bebidas) with correct store/cluster scoping, full siteapi REST surface, browser-deep-link helpers for subscription mutations, and a local SQLite layer for offline product search, basket diffs, price tracking, and cross-store spend rollup. ## When to Use This CLI Use shopper-pp-cli when automating Shopper basket management, monitoring charge schedules, analyzing spend patterns across storefronts, or building agent workflows around the Shopper subscription cycle. Ideal for recurring-basket optimization, pre-cycle audit, and delivery-schedule awareness. ## Anti-triggers Do not use this CLI for: - Do not use for placing orders or confirming checkout — use checkout open to hand off to the browser - Do not use for adding or removing saved credit cards — card management requires browser session - Do not use for ultra-fast delivery slot selection on now/now-bebidas — delivery slots for these stores require the browser checkout flow - Do not use for cancelling orders — cancellation is not available via siteapi REST ## Unique Capabilities These capabilities aren't available in any other tool for this API. ### Subscription intelligence - **`charge-calendar`** — Every upcoming cycle's charge date, edit-lock deadline, and delivery date in one timeline so you never miss an edit window or get surprised by a charge. _Use when an agent needs to know whether the edit window is still open before modifying a recurring basket._ ```bash shopper-pp-cli charge-calendar --store programada --agent ``` - **`basket diff`** — Compares your current recurring basket against a previous cycle's snapshot to show exactly what was added, dropped, or re-quantified before the template locks. _Use when an agent needs to verify what changed in the basket since the last confirmed delivery cycle._ ```bash shopper-pp-cli basket diff --store programada --agent ``` - **`cashback optimize`** — Computes the cheapest set of items to add (or whether to wait) to cross the next cashback tier, favoring things you'll need anyway. _Use when an agent is finalising a basket and wants to maximise cashback return before the edit window closes._ ```bash shopper-pp-cli cashback optimize --tier 2399 --store programada --agent ``` ### Local state that compounds - **`price-watch`** — Tracks the price history of the SKUs you actually buy and alerts when one rises or drops meaningfully versus your own purchase baseline. _Use when an agent needs to know if a subscribed product has changed price significantly since the last order._ ```bash shopper-pp-cli price-watch --store programada --agent ``` - **`restock predict`** — Predicts when you'll run out of each staple from your historical buying cadence and suggests what to add to the upcoming basket. _Use when an agent needs to pre-populate a recurring basket with items likely running low before the next cycle._ ```bash shopper-pp-cli restock predict --store programada --agent ``` - **`catalog drift`** — Flags products you buy that were discontinued, silently swapped, or kept their price while shrinking the pack, surfacing the real R$/kg or R$/L change. _Use when an agent needs to audit whether the recurring basket still contains the same products as originally added._ ```bash shopper-pp-cli catalog drift --store programada --agent ``` ### Customer journey plumbing - **`checkout preview`** — Aggregates cart totals, next delivery date, charge date, minimum-order status, and accepted payment types into one pre-checkout view before you open the browser. _Use when an agent needs to confirm basket readiness and charge schedule before directing the user to open the browser for final payment._ ```bash shopper-pp-cli checkout preview --store programada --agent ``` ## Command Reference **address** — Saved delivery addresses with per-address available-store information - `shopper-pp-cli address` — List delivery addresses and which stores are available at each address **cart** — Cart: view summary, add products, remove products - `shopper-pp-cli cart add` — Add a product to the cart or increase its quantity - `shopper-pp-cli cart list-summary` — Show current basket: items, quantities, totals, cashback, and minimum-order status - `shopper-pp-cli cart remove` — Remove a product from the cart or decrease its quantity **catalog** — Product catalog: search, departments, banners, suggestions - `shopper-pp-cli catalog create-count` — Count products matching a search query and optional filters - `shopper-pp-cli catalog create-filters` — Get available filter options for a search query - `shopper-pp-cli catalog create-search` — Search the product catalog by query with optional brand/type/metadata filters - `shopper-pp-cli catalog get-view` — Get details for a specific catalog banner - `shopper-pp-cli catalog list-banners` — List promotional banners for the current store - `shopper-pp-cli catalog list-departments` — List product departments/categories for the current store - `shopper-pp-cli catalog list-news` — List new product arrivals for the current store - `shopper-pp-cli catalog list-suggest` — Get search suggestions for a query prefix **delivery** — Delivery schedule: upcoming delivery date, edit-lock window, and reschedule calendar - `shopper-pp-cli delivery list-calendar` — Get delivery reschedule calendar — allowed date range and disabled days - `shopper-pp-cli delivery list-summary` — Show scheduled delivery date, current delivery status, and store message **features** — Storefront configuration, feature toggles, and timer state - `shopper-pp-cli features create-select` — Select active store (sets session context; no-op for header-scoped reads) - `shopper-pp-cli features create-start` — Start a named feature timer - `shopper-pp-cli features create-view` — Mark a feature toggle as viewed - `shopper-pp-cli features list-stores` — List all available storefronts with store IDs, cluster IDs, payment parameters, and feature flags - `shopper-pp-cli features list-tick` — Get current timer state - `shopper-pp-cli features list-toggle` — Get active feature toggles for the current store **orders** — Purchase history and spend — reads from GET /orders/orders (web 'Histórico de compras') - `shopper-pp-cli orders` — List past orders for the active store (newest-first, paginated by size) **session** — Session and social-login validation - `shopper-pp-cli session` — Validate social-login session status ## Freshness Contract This printed CLI owns bounded freshness only for registered store-backed read command paths. In `--data-source auto` mode, those paths check `sync_state` and may run a bounded refresh before reading local data. `--data-source local` never refreshes. `--data-source live` reads the API and does not mutate the local store. Set `SHOPPER_NO_AUTO_REFRESH=1` to skip the freshness hook without changing source selection. Covered paths: - `shopper-pp-cli address` - `shopper-pp-cli address get` - `shopper-pp-cli address list` - `shopper-pp-cli address search` - `shopper-pp-cli cart` - `shopper-pp-cli cart get` - `shopper-pp-cli cart list` - `shopper-pp-cli cart search` - `shopper-pp-cli catalog` - `shopper-pp-cli catalog get` - `shopper-pp-cli catalog list` - `shopper-pp-cli catalog search` - `shopper-pp-cli catalog-departments` - `shopper-pp-cli catalog-departments get` - `shopper-pp-cli catalog-departments list` - `shopper-pp-cli catalog-departments search` - `shopper-pp-cli catalog-products-news` - `shopper-pp-cli catalog-products-news get` - `shopper-pp-cli catalog-products-news list` - `shopper-pp-cli catalog-products-news search` - `shopper-pp-cli catalog-search-suggest` - `shopper-pp-cli catalog-search-suggest get` - `shopper-pp-cli catalog-search-suggest list` - `shopper-pp-cli catalog-search-suggest search` - `shopper-pp-cli delivery` - `shopper-pp-cli delivery get` - `shopper-pp-cli delivery list` - `shopper-pp-cli delivery search` - `shopper-pp-cli delivery-v2-calendar` - `shopper-pp-cli delivery-v2-calendar get` - `shopper-pp-cli delivery-v2-calendar list` - `shopper-pp-cli delivery-v2-calendar search` - `shopper-pp-cli features` - `shopper-pp-cli features get` - `shopper-pp-cli features list` - `shopper-pp-cli features search` - `shopper-pp-cli features-timer-tick` - `shopper-pp-cli features-timer-tick get` - `shopper-pp-cli features-timer-tick list` - `shopper-pp-cli features-timer-tick search` - `shopper-pp-cli features-toggle` - `shopper-pp-cli features-toggle get` - `shopper-pp-cli features-toggle list` - `shopper-pp-cli features-toggle search` - `shopper-pp-cli orders` - `shopper-pp-cli orders get` - `shopper-pp-cli orders list` - `shopper-pp-cli orders search` - `shopper-pp-cli session` - `shopper-pp-cli session get` - `shopper-pp-cli session list` - `shopper-pp-cli session search` When JSON output uses the generated provenance envelope, freshness metadata appears at `meta.freshness`. Treat it as current-cache freshness for the covered command path, not a guarantee of complete historical backfill or API-specific enrichment. ### Finding the right command When you know what you want to do but not which command does it, ask the CLI directly: ```bash shopper-pp-cli which "<capability in your own words>" ``` `which` resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code `0` means at least one match; exit code `2` means no confident match — fall back to `--help` or use a narrower query. ## Hand-written Extensions These commands are declared by the spec author and require separate hand-written wiring; the generator does not emit Cobra registration for them. They are listed here for discoverability and are intentionally outside `## Command Reference` so the verify-skill unknown-command check does not treat them as generator-owned paths. - `shopper-pp-cli stores` — List all available Shopper storefronts with IDs, cluster IDs, payment parameters, and capability flags - `shopper-pp-cli checkout preview` — Pre-checkout summary: basket totals, delivery date, charge date, min-order status, and accepted payment types (read-only - `shopper-pp-cli checkout open` — Open the Shopper checkout page in the system browser (subscription-based payment via session login) - `shopper-pp-cli delivery reschedule [--store <store>]` — Open the delivery reschedule calendar in the browser (POST /shop/minha-conta/alterar-data requires session cookie) - `shopper-pp-cli delivery skip` — Open the skip-delivery page in the browser — subscription stores only (POST /shop/minha-conta/pular-entrega/ requires - `shopper-pp-cli delivery suspend` — Open the suspend-subscription page in the browser (POST /shop/minha-conta/suspender-entrega requires session cookie) - `shopper-pp-cli delivery boleto` — Open the boleto-retrieval page in the browser to get the bank slip for the current order - `shopper-pp-cli subscription pause` — Open the subscription-pause page in the browser (POST /shop/carrinho/pause/ requires session cookie) - `shopper-pp-cli subscription resume` — Open the subscription-resume page in the browser (POST /shop/carrinho/play/ requires session cookie) - `shopper-pp-cli payment cards` — Show saved payment card count and open card-management in the browser (card add/delete is browser-required ## Recipes ### Check if the edit window is still open ```bash shopper-pp-cli charge-calendar --store programada --agent --select next_delivery_date,edit_lock_date,charge_date ``` Returns the key dates for the next cycle; compare edit_lock_date to today to know if the basket can still be changed. ### Find items to add for next cashback tier ```bash shopper-pp-cli cashback optimize --store programada --agent ``` Computes the cheapest catalog additions to cross the next cashback threshold using your live cart and synced product data. ### Cross-store spend rollup for last 12 months ```bash shopper-pp-cli orders spend --agent --select store,month,total ``` Queries all 6 storefronts and returns a month-by-store spend matrix for budgeting analysis. ### Detect if a subscribed product changed price ```bash shopper-pp-cli price-watch --store programada --agent --select product_id,name,price_now,price_baseline,change_pct ``` Scans synced price history for products in your basket and flags meaningful price movements. ### Pre-checkout summary with charge date ```bash shopper-pp-cli checkout preview --store programada --agent --select total_amount,delivery_date,charge_date,min_order_met,payment_methods ``` Aggregates cart/delivery/payment data so an agent can confirm basket readiness before directing the user to open the checkout browser. ## Auth Setup Set SHOPPER_TOKEN to your Shopper JWT (from the siteapi Authorization header in browser DevTools). Run 'shopper-pp-cli doctor' to verify. The token is long-lived for the subscription cycle. Never store raw card numbers or CPF in config; card management always opens the browser. Run `shopper-pp-cli doctor` to verify setup. ## Agent Mode Add `--agent` to any command. Expands to: `--json --compact --no-input --no-color --yes`. - **Pipeable** — JSON on stdout, errors on stderr - **Filterable** — `--select` keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs: ```bash shopper-pp-cli address --agent --select id,name,status ``` - **Previewable** — `--dry-run` shows the request without sending - **Offline-friendly** — sync/search commands can use the local SQLite store when available - **Non-interactive** — never prompts, every input is a flag - **Explicit retries** — use `--idempotent` only when an already-existing create should count as success ### Response envelope Commands that read from the local store or the API wrap output in a provenance envelope: ```json { "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."}, "results": <data> } ``` Parse `.results` for data and `.meta.source` to know whether it's live or local. A human-readable `N results (live)` summary is printed to stderr only when stdout is a terminal AND no machine-format flag (`--json`, `--csv`, `--compact`, `--quiet`, `--plain`, `--select`) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout. ## Paths and state Agents should treat the CLI's path resolver as part of the runtime contract: - Use `--home <dir>` for one invocation, or set `SHOPPER_HOME=<dir>` to relocate all four path kinds under one root. - Use per-kind env vars only when a specific kind must diverge: `SHOPPER_CONFIG_DIR`, `SHOPPER_DATA_DIR`, `SHOPPER_STATE_DIR`, `SHOPPER_CACHE_DIR`. - Resolution order is per-kind env var, `--home`, `SHOPPER_HOME`, XDG (`XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME`), then platform defaults. - `config` contains settings like `config.toml` and profiles. `data` contains `credentials.toml`, `data.db`, cookies, and auth sidecars. `state` contains persisted queries, jobs, and `teach.log`. `cache` contains regenerable HTTP/cache files. - Stored secrets live in `credentials.toml` under the data dir. Existing legacy `config.toml` secrets are read for compatibility and leave `config.toml` on the first auth write. - Run `shopper-pp-cli doctor --fail-on warn` to surface path and credential-location warnings. `agent-context` exposes a schema v4 `paths` block for agents that need the resolved dirs. - For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags: ```json { "mcpServers": { "shopper": { "command": "shopper-pp-mcp", "env": { "SHOPPER_HOME": "/srv/shopper" } } } } ``` Fleet precedence: an inherited per-kind env var overrides an explicit `--home` for that kind. Use `SHOPPER_HOME` or per-kind vars as durable fleet levers, and use `--home` only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing `SHOPPER_HOME`, or `doctor` will not find credentials left under the former root. ## Automatic learning This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a `flag_alias` candidate, and a `teach` on a query family without a playbook auto-synthesizes a `playbook_candidate` from the session's journal. Your job is judgment only: `recall` first, act on surfaced candidates, `teach` the final answer, `playbook amend` when you observe a correction. You never record failures by hand. ### Step 1: `recall` before any discovery Before list/search/drill commands on a new user question, run: ```bash