Paknsave Nz

---
name: paknsave-nz
description: "Query PAK'nSAVE NZ stores, product categories, product search results, specials, and store-specific grocery prices using guest APIs, plus a user's own previous orders, purchases, shopping lists, and cart when they explicitly provide Club+ credentials. Manage the user's shopping lists or cart when they explicitly request a specific change."
license: MIT
compatibility: "Requires Python 3.10+ and network access for live data"
metadata:
  thecolab.category: "food-and-fuel"
  thecolab.source_owner: "Foodstuffs New Zealand"
  thecolab.source_type: "commercial"
  thecolab.auth: "mixed"
  thecolab.access_mode: "authenticated-personal"
  thecolab.data_class: "personal"
  thecolab.writes: "true"
  thecolab.browser: "false"
  thecolab.risk: "high"
  thecolab.cache_ttl: "30m"
  thecolab.schema_version: "1"
  thecolab.skill_type: "authenticated-personal"
  thecolab.pack: "nz-personal-data"
  thecolab.public_pack: "nz-commercial-web"
  thecolab.public_commands: "token,stores,categories,search,specials,product"
  thecolab.public_description: "Query PAK'nSAVE NZ stores, categories, products, specials, and store-specific guest prices without an account."
  thecolab.public_access_mode: "public-api"
  thecolab.public_health: "healthy"
  thecolab.public_risk: "medium"
  thecolab.public_allowed_domains: "api-prod.clubplus.co.nz,api-prod.paknsave.co.nz,www.paknsave.co.nz"
  thecolab.source_url: "https://www.paknsave.co.nz"
  thecolab.allowed_domains: "api-prod.clubplus.co.nz,api-prod.paknsave.co.nz,login.clubplus.co.nz,www.paknsave.co.nz"
  thecolab.last_verified: "2026-07-24"
  thecolab.health: "gated"
  thecolab.maintainer: "@adam91holt"
  thecolab.mutations: "authenticated-api-put,authenticated-api-post,authenticated-api-delete"
---

# PAK'nSAVE NZ

## Goal

Query live PAK'nSAVE NZ store and grocery product data, optionally retrieve the authenticated user's own account history, and perform explicit shopping-list or cart changes through a small deterministic CLI.

## Use this when

- A user asks for PAK'nSAVE NZ product prices or specials
- A user wants to search PAK'nSAVE products by keyword
- A user needs store IDs, store lookup, or category browsing
- A user has PAK'nSAVE product IDs and wants store-specific price/details
- A workflow needs machine-readable PAK'nSAVE product data
- A user explicitly wants their own previous PAK'nSAVE orders or purchases
- A user explicitly wants to retrieve their own saved PAK'nSAVE shopping lists
- A user explicitly asks to create, rename, delete, or change products in one of their own shopping lists
- A user explicitly asks to inspect their cart or add, update, or remove one of its products

## Do not use this for

- New World, Four Square, Woolworths, or non-PAK'nSAVE retailers
- Historical pricing or price-change claims unless another dataset provides history
- Checkout, ordering, payment, timeslot, fulfilment, or account/profile changes
- List or cart mutation that the user has not explicitly requested
- Reading another person's account or using credentials not supplied by the account holder

## Preferred workflow

1. Run `scripts/cli.py` with the narrowest subcommand that answers the task
2. Use `stores` first when the requested location is not the default store
3. Use `search` for keyword price/product lookup and `specials` for promotional products
4. Use `product` when exact product IDs are known
5. Use authenticated commands only after the user has supplied their own credentials through environment variables
6. Run list or cart mutation commands only when the user has explicitly requested that exact change
7. Preserve the `--yes` guard on list deletion and list/cart product removal; never infer confirmation from unrelated work
8. Use `--json` for agent chaining, comparisons, or structured reports
9. Treat authenticated JSON as personal data and mention that the integration is unofficial

## Authentication and privacy

Public catalogue commands need no account. Personal commands require the user's own Club+ credentials:

```bash
export PAKNSAVE_USERNAME='member@example.nz'
export PAKNSAVE_PASSWORD='...'
paknsave auth login
```

- The CLI registers and displays account, order, list, and cart commands only when both `PAKNSAVE_USERNAME` (or `PAKNSAVE_EMAIL`) and `PAKNSAVE_PASSWORD` are present in its environment.
- Without that credential pair, `--help` and command parsing expose only the guest catalogue commands.
- The password is read only from the environment and is never written to disk.
- Rotating access and refresh tokens are cached at `~/.cache/paknsave-cli/auth.json` with file mode `0600`.
- Override the cache location with `PAKNSAVE_AUTH_FILE`.
- If Club+ requires MFA, set `PAKNSAVE_MFA_CODE` to the six-digit code and run `auth mfa`.
- `auth status` never prints token values. `auth logout` removes only the local token cache; it does not mutate the PAK'nSAVE account.
- `PAKNSAVE_ACCESS_TOKEN` and `PAKNSAVE_REFRESH_TOKEN` may be used as runtime overrides.
- Orders, list names, item history, addresses, and raw JSON are personal data. Do not paste them into shared logs, issues, or pull requests.

## CLI

Run with:

```bash
python3 skills/paknsave-nz/scripts/cli.py <command> [flags]
```

Default store is PAK'nSAVE Papakura: `a7d09522-bee2-41e4-8fe0-0b82b7f342f5`.
Override with `--store-id <id>` or `PAKNSAVE_STORE_ID`.

### Commands

The first six guest commands are always available. The remaining account commands appear only when the Club+ username/email and password environment variables are set.

- `stores [--query text] [--limit N] [--json]` — list or filter PAK'nSAVE stores
- `categories [--store-id id] [--depth N] [--json]` — browse a store category tree
- `search <query> [--store-id id] [--limit N] [--page N] [--promo] [--json]` — product search with prices
- `specials [query] [--store-id id] [--limit N] [--page N] [--json]` — promotional products
- `product <product-id...> [--store-id id] [--json]` — decorate exact product IDs with details
- `token [--refresh] [--json]` — fetch/cache a short-lived guest token without emitting its value
- `auth login [--json]` — log in with environment-provided Club+ credentials
- `auth mfa [--json]` — finish an MFA login using `PAKNSAVE_MFA_CODE`
- `auth refresh [--json]` — rotate the cached PAK'nSAVE access token
- `auth status [--json]` — report token availability without revealing tokens
- `auth logout [--json]` — remove only the local authenticated-token cache
- `store-select [--store-id id] [--json]` — select the store used for authenticated list and cart writes
- `orders [--page N] [--limit N] [--source ALL|ONLINE|IN_STORE] [--json]` — retrieve previous orders
- `order <order-id> [--source ONLINE|IN_STORE]` — retrieve one previous order
- `previous-purchases [--limit N] [--include-cart] [--json]` — retrieve previously purchased products
- `lists [--json]` — retrieve saved shopping lists
- `list <list-id>` — retrieve one saved shopping list
- `list-create <name> [--json]` — create an empty shopping list
- `list-rename <list-id> <name> [--json]` — rename a shopping list
- `list-delete <list-id> --yes [--json]` — permanently delete a shopping list
- `list-add <list-id> <product-id> [--quantity N] [--sale-type UNITS|WEIGHT] [--json]` — add a product
- `list-update <list-id> <product-id> --quantity N [--sale-type UNITS|WEIGHT] [--json]` — change quantity
- `list-remove <list-id> <product-id> --yes [--sale-type UNITS|WEIGHT] [--json]` — remove a product
- `cart [--json]` — retrieve the current cart
- `cart-add <product-id> [--quantity N] [--sale-type UNITS|WEIGHT] [--json]` — increment a cart product quantity
- `cart-update <product-id> --quantity N [--sale-type UNITS|WEIGHT] [--json]` — set a cart product quantity
- `cart-remove <product-id> --yes [--sale-type UNITS|WEIGHT] [--json]` — remove a cart product

Examples:

```bash
python3 skills/paknsave-nz/scripts/cli.py stores --query auckland --limit 5
python3 skills/paknsave-nz/scripts/cli.py search milk --limit 10
python3 skills/paknsave-nz/scripts/cli.py specials cheese --limit 10 --json
python3 skills/paknsave-nz/scripts/cli.py product 5201479 --json
paknsave auth status
paknsave store-select
paknsave orders --limit 20 --json
paknsave lists --json
paknsave list-create "Weekly shop"
paknsave list-add <list-id> 5201479 --quantity 2
paknsave cart
paknsave cart-add 5201479 --quantity 2
```

## Resources

- CLI entrypoint: `scripts/cli.py`
- Live smoke test: `scripts/smoke_test.py`
- API and stability notes: `references/api-notes.md`

## Notes

- Public commands use the guest-token flow and cache tokens under `~/.cache/paknsave-cli/guest-token.json`
- Personal commands mirror the Club+ login, secure-code exchange, and rotating PAK'nSAVE refresh flow used by the website
- If a fresh authenticated session has no store, the CLI selects `PAKNSAVE_STORE_ID` (or the Papakura default) once and retries the request; `store-select` can change it explicitly
- List writes use the same endpoints as the website and are intentionally exposed only as explicit subcommands
- `list-delete` and `list-remove` require `--yes`; they cannot be invoked accidentally through a zero quantity
- Cart writes use target quantities internally: `cart-add` reads and increments, while `cart-update` sets the target directly
- `cart-remove` requires `--yes`; use grams for `WEIGHT` quantities and units for `UNITS`
- Email verification must be completed in the normal PAK'nSAVE login page before CLI login
- Endpoint shapes can change; retry with a fresh token before assuming data is unavailable
- `--json` output is intended for exact matching and private agent workflows