🥬 Friday Grocery Cart

${body}\n`;\n}\n\napp.get(\"/\", (c) => c.html(html(\"

The grocery automation is running. Administrative details require the private setup link.

\")));\n\napp.get(\"/admin\", async (c) => {\n const key = c.req.query(\"key\");\n if (!authorized(key)) return c.text(\"Unauthorized\", 401);\n const info = await status();\n const checks = [\n [\"Notion token\", info.notionConfigured],\n [\"Kroger credentials\", info.krogerConfigured],\n [\"Kroger account\", info.krogerConnected],\n [\"Kroger location\", info.locationConfigured],\n [\"Live cart writes\", info.liveCart],\n ];\n return c.html(html(`\n

Setup status

${ok ? \"✓\" : \"○\"} ${label}

Connect Kroger

Latest run

${info.latest ? escape(JSON.stringify(info.latest, null, 2)) : \"No run yet.\"}

\n `));\n});\n\napp.get(\"/connect/kroger\", async (c) => {\n if (!authorized(c.req.query(\"key\"))) return c.text(\"Unauthorized\", 401);\n return c.redirect(await makeAuthorizeUrl());\n});\n\napp.get(\"/auth/kroger/callback\", async (c) => {\n const error = c.req.query(\"error\");\n if (error) return c.html(html(`

Kroger authorization failed: ${escape(error)}

`), 400);\n const code = c.req.query(\"code\");\n const stateValue = c.req.query(\"state\");\n if (!code || !stateValue) return c.text(\"Missing OAuth code or state\", 400);\n await exchangeCode(code, stateValue);\n return c.html(html('

Kroger is connected. Checkout permission was not requested.

'));\n});\n\napp.get(\"/api/products-batch\", async (c) => {\n if (!authorized(c.req.query(\"key\"))) return c.json({ error: \"Unauthorized\" }, 401);\n const queries = (c.req.query(\"q\") ?? \"\").split(\"|\").map((value) => value.trim()).filter(Boolean);\n if (!queries.length || queries.length > 25) return c.json({ error: \"Provide 1-25 pipe-separated queries\" }, 400);\n const results = await Promise.all(queries.map(async (query) => {\n const products = await searchPickupProducts(query);\n return {\n query,\n candidates: products.slice(0, 5).map((product: any) => ({\n upc: product.upc,\n description: product.description,\n brand: product.brand,\n size: product.items?.[0]?.size,\n price: product.items?.[0]?.price?.regular,\n curbside: product.items?.[0]?.fulfillment?.curbside,\n })),\n };\n }));\n return c.json(results);\n});\n\napp.get(\"/api/products\", async (c) => {\n if (!authorized(c.req.query(\"key\"))) return c.json({ error: \"Unauthorized\" }, 401);\n const query = c.req.query(\"q\")?.trim();\n if (!query) return c.json({ error: \"Missing q\" }, 400);\n const products = await searchPickupProducts(query);\n return c.json(products.map((product: any) => ({\n upc: product.upc,\n description: product.description,\n brand: product.brand,\n size: product.items?.[0]?.size,\n price: product.items?.[0]?.price,\n fulfillment: product.items?.[0]?.fulfillment,\n })));\n});\n\napp.get(\"/api/stores\", async (c) => {\n if (!authorized(c.req.query(\"key\"))) return c.json({ error: \"Unauthorized\" }, 401);\n const locations = await findKrogerLocations(c.req.query(\"zip\") ?? \"23452\");\n return c.json(locations.map((location: any) => ({\n locationId: location.locationId,\n name: location.name,\n address: location.address,\n departments: location.departments,\n })));\n});\n\napp.get(\"/api/dry-run\", async (c) => {\n if (!authorized(c.req.query(\"key\"))) return c.json({ error: \"Unauthorized\" }, 401);\n const todos = await readKrogerTodos();\n return c.json({\n count: todos.length,\n items: todos.map(({ text, section }) => ({ text, section })),\n mutationAttempted: false,\n });\n});\n\napp.post(\"/api/run\", async (c) => {\n if (!authorized(c.req.query(\"key\"))) return c.json({ error: \"Unauthorized\" }, 401);\n return c.json(await runShoppingList({ live: c.req.query(\"live\") === \"true\" }));\n});\n\napp.onError((error) => Promise.reject(error));\nexport default app.fetch;\n","deleted","label",[113],"e9dab901-8f12-4870-8e9c-ad8010a29c78","lib.ts","6396105a-a364-11f1-9887-1607ee4eb77e",27,["D",1788463176362],8,"script","import { blob } from \"https://esm.town/v/std/blob/main.ts\";\n\nexport const PAGE_ID = \"303c869b2f04804bbf24f393fd074bd1\";\nconst NOTION_VERSION = \"2026-03-11\";\nconst KROGER_API = \"https://api.kroger.com/v1\";\nconst OAUTH_BASE = `${KROGER_API}/connect/oauth2`;\n\ntype Todo = { id: string; text: string; section: string };\ntype Match = { upc: string; description: string; confidence: \"remembered\" | \"exact\" | \"candidate\" };\n\nfunction env(name: string): string {\n const value = Deno.env.get(name);\n if (!value) throw new Error(`Missing environment variable: ${name}`);\n return value;\n}\n\nasync function notion(path: string, init: RequestInit = {}) {\n const response = await fetch(`https://api.notion.com/v1${path}`, {\n ...init,\n headers: {\n Authorization: `Bearer ${env(\"NOTION_TOKEN\")}`,\n \"Notion-Version\": NOTION_VERSION,\n \"Content-Type\": \"application/json\",\n ...init.headers,\n },\n });\n if (!response.ok) throw new Error(`Notion ${response.status}: ${await response.text()}`);\n return response.json();\n}\n\nasync function children(blockId: string): Promise {\n const all: any[] = [];\n let cursor: string | undefined;\n do {\n const query = new URLSearchParams({ page_size: \"100\" });\n if (cursor) query.set(\"start_cursor\", cursor);\n const page = await notion(`/blocks/${blockId}/children?${query}`);\n all.push(...page.results);\n cursor = page.has_more ? page.next_cursor : undefined;\n } while (cursor);\n return all;\n}\n\nfunction plainText(block: any): string {\n const rich = block?.[block.type]?.rich_text ?? [];\n return rich.map((part: any) => part.plain_text ?? \"\").join(\"\").trim();\n}\n\nexport async function readKrogerTodos(): Promise {\n const found: Todo[] = [];\n async function walk(parentId: string, inheritedSection = \"\") {\n let section = inheritedSection;\n for (const block of await children(parentId)) {\n if (/^heading_[1-4]$/.test(block.type)) section = plainText(block);\n if (\n block.type === \"to_do\" &&\n section.toLowerCase() === \"kroger\" &&\n block.to_do.checked === false\n ) {\n const text = plainText(block);\n if (text) found.push({ id: block.id, text, section });\n }\n if (block.has_children) await walk(block.id, section);\n }\n }\n await walk(PAGE_ID);\n return found;\n}\n\nfunction parseItem(text: string) {\n const match = text.match(/^\\s*(?:(\\d+)\\s*(?:x|×)?\\s+)?(.+?)\\s*$/i);\n return { quantity: Math.max(1, Number(match?.[1] ?? 1)), query: (match?.[2] ?? text).trim() };\n}\n\nasync function appToken(): Promise {\n const credentials = btoa(`${env(\"KROGER_CLIENT_ID\")}:${env(\"KROGER_CLIENT_SECRET\")}`);\n const response = await fetch(`${OAUTH_BASE}/token`, {\n method: \"POST\",\n headers: {\n Authorization: `Basic ${credentials}`,\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n },\n body: new URLSearchParams({ grant_type: \"client_credentials\", scope: \"product.compact\" }),\n });\n if (!response.ok) throw new Error(`Kroger app token ${response.status}: ${await response.text()}`);\n return (await response.json()).access_token;\n}\n\nexport async function findKrogerLocations(zipCode: string) {\n const token = await appToken();\n const params = new URLSearchParams({\n \"filter.zipCode.near\": zipCode,\n \"filter.radiusInMiles\": \"10\",\n \"filter.limit\": \"50\",\n \"filter.chain\": \"Kroger\",\n });\n const response = await fetch(`${KROGER_API}/locations?${params}`, {\n headers: { Authorization: `Bearer ${token}`, Accept: \"application/json\" },\n });\n if (!response.ok) throw new Error(`Kroger locations ${response.status}: ${await response.text()}`);\n return (await response.json()).data ?? [];\n}\n\nexport async function customerToken(): Promise {\n const saved = await blob.getJSON(\"kroger:oauth\") as any;\n if (!saved?.refresh_token) throw new Error(\"Kroger account is not connected\");\n if (saved.access_token && saved.expires_at > Date.now() + 60_000) return saved.access_token;\n\n const credentials = btoa(`${env(\"KROGER_CLIENT_ID\")}:${env(\"KROGER_CLIENT_SECRET\")}`);\n const response = await fetch(`${OAUTH_BASE}/token`, {\n method: \"POST\",\n headers: {\n Authorization: `Basic ${credentials}`,\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n },\n body: new URLSearchParams({ grant_type: \"refresh_token\", refresh_token: saved.refresh_token }),\n });\n if (!response.ok) throw new Error(`Kroger refresh ${response.status}: ${await response.text()}`);\n const next = await response.json();\n const merged = {\n ...saved,\n ...next,\n refresh_token: next.refresh_token ?? saved.refresh_token,\n expires_at: Date.now() + Number(next.expires_in ?? 1800) * 1000,\n };\n await blob.setJSON(\"kroger:oauth\", merged);\n return merged.access_token;\n}\n\nexport async function makeAuthorizeUrl(): Promise {\n const state = crypto.randomUUID();\n await blob.setJSON(`oauth:state:${state}`, { createdAt: Date.now() });\n const query = new URLSearchParams({\n client_id: env(\"KROGER_CLIENT_ID\"),\n redirect_uri: env(\"KROGER_REDIRECT_URI\"),\n response_type: \"code\",\n scope: \"cart.basic:write\",\n state,\n });\n return `${OAUTH_BASE}/authorize?${query}`;\n}\n\nexport async function exchangeCode(code: string, state: string) {\n const record = await blob.getJSON(`oauth:state:${state}`) as any;\n if (!record || Date.now() - record.createdAt > 10 * 60_000) throw new Error(\"Invalid or expired OAuth state\");\n await blob.delete(`oauth:state:${state}`);\n\n const credentials = btoa(`${env(\"KROGER_CLIENT_ID\")}:${env(\"KROGER_CLIENT_SECRET\")}`);\n const response = await fetch(`${OAUTH_BASE}/token`, {\n method: \"POST\",\n headers: {\n Authorization: `Basic ${credentials}`,\n \"Content-Type\": \"application/x-www-form-urlencoded\",\n },\n body: new URLSearchParams({\n grant_type: \"authorization_code\",\n code,\n redirect_uri: env(\"KROGER_REDIRECT_URI\"),\n }),\n });\n if (!response.ok) throw new Error(`Kroger code exchange ${response.status}: ${await response.text()}`);\n const token = await response.json();\n await blob.setJSON(\"kroger:oauth\", {\n ...token,\n expires_at: Date.now() + Number(token.expires_in ?? 1800) * 1000,\n });\n}\n\nexport async function searchPickupProducts(query: string) {\n const token = await appToken();\n const params = new URLSearchParams({\n \"filter.term\": query,\n \"filter.locationId\": env(\"KROGER_LOCATION_ID\"),\n \"filter.fulfillment\": \"csp\",\n \"filter.limit\": \"10\",\n });\n const response = await fetch(`${KROGER_API}/products?${params}`, {\n headers: { Authorization: `Bearer ${token}`, Accept: \"application/json\" },\n });\n if (!response.ok) throw new Error(`Kroger products ${response.status}: ${await response.text()}`);\n return (await response.json()).data ?? [];\n}\n\nasync function matchProduct(text: string): Promise {\n const { query } = parseItem(text);\n const key = `match:${query.toLowerCase()}`;\n const remembered = await blob.getJSON(key) as Match | null;\n\n let products = await searchPickupProducts(query);\n if (!products.length && !remembered?.upc) return null;\n\n if (remembered?.upc) {\n let current = products.find((product: any) => String(product.upc) === String(remembered.upc));\n if (!current) {\n const exactProducts = await searchPickupProducts(remembered.upc);\n current = exactProducts.find((product: any) => String(product.upc) === String(remembered.upc));\n }\n if (!current) return null;\n\n return { ...remembered, description: current.description ?? remembered.description, confidence: \"remembered\" };\n }\n\n const normalized = query.toLowerCase();\n const exact = products.find((p: any) => String(p.description ?? \"\").toLowerCase() === normalized);\n if (!exact) return null; // Conservative first version: never guess.\n const match = { upc: exact.upc, description: exact.description, confidence: \"exact\" as const };\n await blob.setJSON(key, match);\n return match;\n}\n\nasync function markChecked(blockId: string) {\n await notion(`/blocks/${blockId}`, {\n method: \"PATCH\",\n body: JSON.stringify({ to_do: { checked: true } }),\n });\n}\n\nexport async function runShoppingList(options: { live?: boolean } = {}) {\n const live = options.live === true && Deno.env.get(\"LIVE_CART\") === \"true\";\n const todos = await readKrogerTodos();\n const report: any = { live, startedAt: new Date().toISOString(), added: [], review: [], failed: [] };\n\n for (const todo of todos) {\n const runKey = `run:${new Date().toISOString().slice(0, 10)}:${todo.id}`;\n const prior = await blob.getJSON(runKey) as any;\n if (prior?.status === \"added\" || prior?.status === \"uncertain\") continue;\n\n try {\n const parsed = parseItem(todo.text);\n const match = await matchProduct(todo.text);\n if (!match) {\n report.review.push({ item: todo.text, reason: \"No exact or remembered product match\" });\n continue;\n }\n if (!live) {\n report.review.push({ item: todo.text, candidate: match, quantity: parsed.quantity, reason: \"Dry run\" });\n continue;\n }\n\n await blob.setJSON(runKey, { status: \"attempting\", item: todo.text, match, at: Date.now() });\n const token = await customerToken();\n const response = await fetch(`${KROGER_API}/cart/add`, {\n method: \"PUT\",\n headers: {\n Authorization: `Bearer ${token}`,\n \"Content-Type\": \"application/json\",\n Accept: \"application/json\",\n },\n body: JSON.stringify({ items: [{ upc: match.upc, quantity: parsed.quantity }] }),\n });\n if (!response.ok) throw new Error(`Kroger cart ${response.status}: ${await response.text()}`);\n\n await blob.setJSON(runKey, { status: \"added\", item: todo.text, match, at: Date.now() });\n await markChecked(todo.id);\n report.added.push({ item: todo.text, product: match.description, quantity: parsed.quantity });\n } catch (error) {\n const message = error instanceof Error ? error.message : String(error);\n const current = await blob.getJSON(runKey) as any;\n if (current?.status === \"attempting\") {\n await blob.setJSON(runKey, { ...current, status: \"uncertain\", error: message });\n report.failed.push({ item: todo.text, error: message, retry: \"blocked to prevent duplicates\" });\n } else report.failed.push({ item: todo.text, error: message });\n }\n }\n\n report.finishedAt = new Date().toISOString();\n await blob.setJSON(\"run:latest\", report);\n return report;\n}\n\nexport async function status() {\n const oauth = await blob.getJSON(\"kroger:oauth\") as any;\n const latest = await blob.getJSON(\"run:latest\");\n return {\n notionPageId: PAGE_ID,\n notionConfigured: Boolean(Deno.env.get(\"NOTION_TOKEN\")),\n krogerConfigured: Boolean(Deno.env.get(\"KROGER_CLIENT_ID\") && Deno.env.get(\"KROGER_CLIENT_SECRET\")),\n krogerConnected: Boolean(oauth?.refresh_token),\n locationConfigured: Boolean(Deno.env.get(\"KROGER_LOCATION_ID\")),\n liveCart: Deno.env.get(\"LIVE_CART\") === \"true\",\n latest,\n };\n}\n",[130],"1399fe0c-f04f-4f2c-a9fa-0cbde9f69883","dry-run.ts","64d69472-a368-11f1-9f7a-1607ee4eb77e",7,["D",1787980418848],"import { readKrogerTodos } from \"./lib.ts\";\n\nexport default async function () {\n const todos = await readKrogerTodos();\n const result = {\n pageId: \"303c869b2f04804bbf24f393fd074bd1\",\n krogerUncheckedItems: todos.map(({ id: _id, ...safe }) => safe),\n count: todos.length,\n mutationAttempted: false,\n };\n console.log(JSON.stringify(result, null, 2));\n return result;\n}\n",[139],"b253754d-6ea2-4e76-a659-a78f4f6fcdbf","cron.ts","6759e964-a364-11f1-a1d0-1607ee4eb77e",19,["D",1788442759984],1,"interval","import { runShoppingList } from \"./lib.ts\";\n\nfunction easternClock(date: Date) {\n const parts = new Intl.DateTimeFormat(\"en-US\", {\n timeZone: \"America/New_York\",\n weekday: \"short\",\n hour: \"2-digit\",\n minute: \"2-digit\",\n hourCycle: \"h23\",\n }).formatToParts(date);\n\n return Object.fromEntries(parts.map(({ type, value }) => [type, value]));\n}\n\nexport default async function () {\n const now = new Date();\n const local = easternClock(now);\n\n if (local.weekday !== \"Fri\" || local.hour !== \"21\" || local.minute !== \"00\") {\n const result = {\n skipped: true,\n reason: \"Outside Friday 9:00 p.m. America/New_York window\",\n checkedAt: now.toISOString(),\n eastern: local,\n };\n console.log(JSON.stringify(result, null, 2));\n return result;\n }\n\n const report = await runShoppingList({ live: true });\n console.log(JSON.stringify(report, null, 2));\n return report;\n}\n",[146],"824ea274-4ab7-4562-85a7-c3997437a162","README.md","69e1dbc4-a364-11f1-977a-1607ee4eb77e",["D",1788464523105],"# Friday Grocery Cart\n\nFriday Grocery Cart turns a normal shared Notion checklist into a weekly Kroger cart without converting the document into a database.\n\nEvery Friday at 9:00 p.m. Eastern, a Val Town interval reads the Notion page, finds unchecked non-empty to-do blocks under the **Kroger** heading, resolves their text to pickup-eligible products at a configured store, adds confirmed matches to the authenticated customer's Kroger cart, and checks off each Notion block only after Kroger reports success. The customer reviews the cart and completes checkout in Kroger manually.\n\n> The Notion API exposes blocks, text, headings, checkbox state, and block IDs. The application still owns the business rules that give those blocks meaning.\n\n## Current state\n\nThe first end-to-end integration test passed on August 29, 2026:\n\n1. Val Town read the live shared Notion page.\n2. It found one unchecked item under the Kroger heading: `Lettuce`.\n3. The first dry run refused to guess among several Kroger results.\n4. The user selected **Kroger® Green Leaf Lettuce**, UPC `0001111018167`.\n5. That preference was saved as the meaning of the exact text `Lettuce`.\n6. Kroger accepted one item into the real customer cart.\n7. Only after Kroger returned success, the Val checked off the exact Notion block.\n8. A second Notion read returned zero eligible unchecked Kroger items.\n9. The customer independently confirmed that the product appeared in the Kroger cart.\n\nA production mapping run completed on September 3, 2026:\n\n- The user reviewed live pickup candidates and selected exact products for the current list.\n- Thirteen products were added and committed to Notion on the first pass.\n- A generic-search pagination issue initially hid the chosen six-count pepper UPC.\n- Matching was updated to fall back to an exact UPC lookup for remembered choices.\n- The pepper was added successfully on a second pass, for 14 products total.\n- There were no failed or uncertain cart writes.\n- Strawberries were initially held behind a sale-price condition. That condition has since been removed; the remembered 1 lb strawberry selection is now unconditional.\n- Wraps were intentionally excluded.\n\nConfigured production context:\n\n- Notion page: `Grocery List`\n- Page ID: `303c869b2f04804bbf24f393fd074bd1`\n- Store: Kroger Marketplace – Holland Road\n- Address: 3901 Holland Rd, Virginia Beach, VA 23452\n- Kroger location ID: `02900540`\n- Schedule: Friday at 9:00 p.m. America/New_York\n- UTC mechanism: hourly interval plus an Eastern-time execution guard\n- Checkout: always manual\n\n## Architecture\n\n```text\nNotion shared page\n ↓ read blocks\nVal Town interval and business rules\n ↓ search pickup products\nKroger Products API\n ↓ add remembered/confirmed matches\nKroger Cart API\n ↓ successful response\nNotion Update Block API\n ↓\nCustomer reviews cart and checks out manually\n```\n\nFiles:\n\n- `main.ts` — protected admin page, OAuth routes, diagnostics, and manual-run endpoint\n- `lib.ts` — Notion parser, Kroger clients, matching, OAuth refresh, cart writes, and state transitions\n- `cron.ts` — scheduled Friday entrypoint\n- `dry-run.ts` — read-only parser diagnostic\n- `README.md` — setup and operational documentation\n\nPersistent state uses Val-scoped `std/blob` storage:\n\n- `kroger:oauth` — Kroger access and refresh tokens\n- `oauth:state:*` — short-lived OAuth anti-forgery state\n- `match:` — remembered checklist-text-to-UPC mappings\n- `run::` — per-item execution ledger\n- `run:latest` — latest run report\n\nCredentials belong in Val Town environment variables, never blob storage or source code.\n\n## Notion document contract\n\nThe page remains a normal shared document. No Notion database is required.\n\nExample:\n\n```markdown\n## 09/04/26 - next shop\n\n### Kroger\n- [ ] Lettuce\n- [ ] 2x whole milk\n- [x] Coffee\n\n### Costco\n- [ ] Paper towels\n```\n\nCurrent parsing rules:\n\n1. Recursively retrieve all blocks and handle Notion pagination.\n2. Treat headings as the current section name.\n3. Process only `to_do` blocks under a heading exactly equal to `Kroger`, ignoring case.\n4. Ignore checked boxes.\n5. Ignore empty boxes.\n6. Parse a leading integer such as `2x`, `2×`, or `2 ` as quantity; otherwise use quantity 1.\n7. Preserve the remaining text as the product query and preference key.\n8. Do not alter headings, prose, other stores, checked items, or empty boxes.\n\n## Environment variables\n\nOpen the Val's **Environment Variables** page and create the following values:\n\n| Variable | Secret? | Purpose |\n| --- | --- | --- |\n| `NOTION_TOKEN` | Yes | Notion internal connection token with access to the grocery page |\n| `KROGER_CLIENT_ID` | Yes | Client ID from the Kroger Developer Portal |\n| `KROGER_CLIENT_SECRET` | Yes | Client secret from the Kroger Developer Portal |\n| `KROGER_REDIRECT_URI` | No | Exact deployed OAuth callback URL |\n| `KROGER_LOCATION_ID` | No | Kroger location used for product and pickup filtering |\n| `SETUP_KEY` | Yes | Protects admin, diagnostics, connect, and manual-run routes |\n| `LIVE_CART` | No | Master write switch; must equal the string `true` for cart and Notion mutations |\n\nPrefilled environment-variable pages:\n\n👉 Add NOTION_TOKEN here: https://www.val.town/x/pchinjr/friday-grocery-cart/environment-variables?key=NOTION_TOKEN\n\n👉 Add KROGER_CLIENT_ID here: https://www.val.town/x/pchinjr/friday-grocery-cart/environment-variables?key=KROGER_CLIENT_ID\n\n👉 Add KROGER_CLIENT_SECRET here: https://www.val.town/x/pchinjr/friday-grocery-cart/environment-variables?key=KROGER_CLIENT_SECRET\n\n👉 Add KROGER_REDIRECT_URI here: https://www.val.town/x/pchinjr/friday-grocery-cart/environment-variables?key=KROGER_REDIRECT_URI\n\n👉 Add KROGER_LOCATION_ID here: https://www.val.town/x/pchinjr/friday-grocery-cart/environment-variables?key=KROGER_LOCATION_ID\n\n👉 Add SETUP_KEY here: https://www.val.town/x/pchinjr/friday-grocery-cart/environment-variables?key=SETUP_KEY\n\n👉 Add LIVE_CART here: https://www.val.town/x/pchinjr/friday-grocery-cart/environment-variables?key=LIVE_CART\n\nFor this deployment:\n\n```text\nKROGER_REDIRECT_URI=https://pchinjr--373b716ca36411f1a6f51607ee4eb77e.web.val.run/auth/kroger/callback\nKROGER_LOCATION_ID=02900540\nLIVE_CART=false\n```\n\nGenerate `SETUP_KEY` as a long random value. Do not reuse a password. The HTTP Val must remain public so Kroger can reach its OAuth callback, so every administrative route is separately protected by this key.\n\nKeep `LIVE_CART=false` during setup and every dry run. Turn it on only after Notion parsing, store selection, OAuth, and product matching have been verified.\n\n## Notion setup\n\nYou must be able to create an internal connection in the target Notion workspace.\n\n1. In Notion, open **Settings → Connections**.\n2. Enable **Developer Mode** if prompted.\n3. Open **Personal access tokens** or **Internal connections**.\n4. Choose **New connection**.\n5. Name it, for example, `PrefilledGroceryCart`.\n6. Select the workspace containing the grocery page.\n7. Grant **Read content** and **Update content** capabilities.\n8. Create the connection.\n9. Copy its installation access token into the Val's `NOTION_TOKEN` environment variable.\n10. Open the Grocery List page.\n11. Use the page's upper-right `•••` menu.\n12. Choose **Connections** or **Add connections**.\n13. Select the new connection and confirm.\n\nThe token alone is insufficient. If the page was not shared with the connection, Notion returns `404 object_not_found` even when the page ID is correct.\n\nOnly the Grocery List page needs to be connected. It does not need to be published, converted into a database, or exposed to the web.\n\n## Kroger developer application setup\n\n1. Sign in to the [Kroger Developer Portal](https://developer.kroger.com/).\n2. Create a developer application.\n3. Enable the public APIs required by this project:\n - Authorization\n - Locations\n - Products\n - Cart\n4. Copy the generated client ID to `KROGER_CLIENT_ID`.\n5. Copy the generated client secret to `KROGER_CLIENT_SECRET`.\n6. In the application's redirect/callback configuration, register the exact deployed callback URL from `KROGER_REDIRECT_URI`.\n7. Match the URL byte-for-byte, including protocol, host, path, and trailing slash behavior.\n\nThe application uses two OAuth grant types:\n\n- **Client credentials** with `product.compact` for stores and product search.\n- **Authorization code** with `cart.basic:write` for acting on behalf of the customer's cart.\n\nThe Val never receives or stores the customer's Kroger password or payment information.\n\n## Authorizing a Kroger customer account\n\nAfter setting the Kroger credentials and callback:\n\n1. Open the protected admin route:\n `/admin?key=`\n2. Select **Connect Kroger**.\n3. The Val creates a random, ten-minute OAuth `state` record.\n4. The browser redirects to Kroger.\n5. Sign in directly on Kroger's site.\n6. Approve cart access.\n7. Kroger redirects to `/auth/kroger/callback` with a temporary code.\n8. The callback verifies `state`.\n9. The Val exchanges the code for access and refresh tokens.\n10. Tokens are stored in Val-scoped blob storage.\n11. Future runs refresh access automatically without requiring weekly login.\n\nThe requested scope can add products to the cart. It does not grant checkout or payment permission.\n\n## Store and pickup configuration\n\nUse the protected endpoint below to look up stores:\n\n```text\nGET /api/stores?zip=&key=\n```\n\nCopy the desired `locationId` into `KROGER_LOCATION_ID`.\n\nProduct searches include:\n\n```text\nfilter.locationId=\nfilter.fulfillment=csp\n```\n\nThe `csp` filter restricts candidates to products Kroger reports as eligible for curbside pickup at that location.\n\nImportant limitation: the public Cart API adds items but does not choose a fulfillment mode, reserve a pickup window, or place an order. The customer confirms pickup, selects a time, reviews substitutions and prices, and checks out in Kroger.\n\n## Product matching and preferences\n\nA broad human description can return several valid products. For example, `Lettuce` returned iceberg, romaine, green leaf, shredded, hearts, and organic products.\n\nCurrent policy:\n\n1. Look for a remembered mapping under `match:`.\n2. Search pickup-eligible products at the configured store and confirm the remembered UPC is still available.\n3. If the UPC is not among the first generic search results, retry using the exact UPC.\n4. Without a remembered mapping, automatically accept only a case-insensitive exact Kroger description match.\n5. Leave ambiguous or unavailable items unchecked and place them in `review`.\n6. Once a human chooses a candidate, save its UPC as the unconditional meaning of that exact checklist text.\n\nRemembered mappings do not contain price conditions. The selected product is added whenever Kroger reports that exact UPC as pickup-eligible. This deliberately prioritizes a correct cart over a full cart.\n\n## State transition and duplicate protection\n\nFor every eligible Notion block:\n\n```text\nunchecked\n → matched\n → attempting cart write\n → Kroger success\n → ledger marked added\n → Notion checked\n```\n\nThe Notion checkbox is the commit step from the user's perspective.\n\nBefore a live cart request, the Val writes an `attempting` ledger record. After Kroger returns success, it writes `added`, then checks the Notion block.\n\nIf a network error occurs after the request begins, the ledger becomes `uncertain`. Automatic retry is blocked because Kroger's public cart surface cannot reliably read or remove items. A human must inspect the cart before resolving an uncertain item.\n\n## Safe testing procedure\n\n### 1. Parser test\n\nKeep `LIVE_CART=false`, then call:\n\n```text\nGET /api/dry-run?key=\n```\n\nExpected output contains only unchecked, non-empty Kroger items and `mutationAttempted: false`.\n\n### 2. Product search\n\n```text\nGET /api/products?q=Lettuce&key=\n```\n\nReview UPC, description, size, price, and curbside fulfillment.\n\n### 3. Full dry run\n\n```text\nPOST /api/run?live=false&key=\n```\n\nThis resolves remembered/exact candidates but does not add to Kroger or update Notion.\n\n### 4. Controlled integration test\n\n1. Put exactly one known unchecked item under the Kroger heading.\n2. Confirm its remembered UPC.\n3. Set `LIVE_CART=true`.\n4. Call `POST /api/run?live=true&key=`.\n5. Confirm the report contains one item in `added` and none in `failed`.\n6. Confirm the item appears in the Kroger cart.\n7. Rerun the parser diagnostic and confirm the item is no longer returned.\n8. Set `LIVE_CART=false` while reviewing results.\n\n## Schedule and operations\n\n`cron.ts` calls `runShoppingList({ live: true })`, but actual writes still require `LIVE_CART=true`.\n\nThe interval uses:\n\n```cron\n0 * * * *\n```\n\nVal Town cron expressions use UTC and do not adjust for daylight-saving time. The interval therefore wakes at the top of each hour, and `cron.ts` uses `Intl.DateTimeFormat` with `America/New_York` to continue only when the local clock is Friday at 21:00. Every other hourly invocation exits without reading the grocery list or calling Kroger. This keeps execution at exactly 9:00 p.m. Eastern during both EDT and EST.\n\nUse the protected admin page to inspect configuration state and the latest run report. Never publish a run report on an unprotected route because it may reveal private grocery-list contents.\n\n## Confirmed behavior\n\n- Reads a normal shared Notion document.\n- Recurses through child blocks and paginated responses.\n- Scopes processing to the Kroger heading.\n- Ignores checked and blank to-do blocks.\n- Searches the correct Kroger location.\n- Filters for curbside-pickup eligibility.\n- Completes Kroger OAuth with customer consent.\n- Refreshes customer tokens.\n- Remembers human-approved UPC mappings.\n- Adds an item to the authenticated Kroger cart.\n- Checks off the exact Notion block only after Kroger success.\n- Prevents ordinary duplicate processing.\n- Stops before checkout.\n\n## Known limitations\n\n- Product ambiguity currently requires manually writing a preference mapping.\n- No built-in review UI exists yet.\n- The public Kroger API cannot read or remove everything from the customer cart.\n- A lost response after a cart write creates an uncertain outcome that requires manual inspection.\n- Prices and availability can change between Friday morning and checkout.\n- Pickup time and substitutions are finalized in Kroger.\n- The page ID and expected section name are currently defined in source code.\n- Run notifications are not yet implemented.\n- The scheduled production workflow should remain disabled until preference review is mature.\n\n## Next steps\n\n1. Build an admin review screen showing ambiguous items and Kroger candidates.\n2. Let the user choose a product and save the mapping without editing blob storage manually.\n3. Add controls to forget or replace a remembered preference.\n4. Add a preflight page showing Friday's proposed cart before writes.\n5. Send a Friday completion report with added, review, failed, and uncertain items.\n6. Add a direct Kroger cart link to the report.\n7. Decide whether one ambiguous item should block the whole run or only itself.\n8. Add tests for headings, nesting, pagination, quantities, blank items, and malformed content.\n9. Make page ID, section name, schedule, store, and default quantity configurable.\n10. Add explicit recovery tooling for `uncertain` ledger entries.\n11. Add token-revocation and disconnect controls.\n12. Add structured logs that redact tokens, setup keys, and OAuth codes.\n13. Re-enable `LIVE_CART` only when the review and notification workflow is ready.\n\n## Security notes\n\n- Never commit environment-variable values.\n- Never place Notion or Kroger tokens in README files, logs, query strings, or screenshots.\n- Treat `SETUP_KEY` as a password because the HTTP endpoint must be publicly reachable for OAuth.\n- Rotate the setup key if an administrative URL is exposed.\n- Keep OAuth `state` validation enabled.\n- Request only `product.compact` and `cart.basic:write`.\n- Do not add checkout automation.\n- Keep run reports behind the setup-key check.\n- Review `uncertain` outcomes manually rather than retrying blindly.\n\n## Handoff summary\n\nThe infrastructure and first real integration are working. The remaining work is primarily product judgment and operational UX, not connectivity. Notion is acting as the collaborative human interface; Val Town supplies the hidden schema, parser, state machine, matching memory, OAuth lifecycle, idempotency rules, and side effects; Kroger remains the final review and checkout surface.\n",[155],"pulls","branches","forks","envVars",{"_167":141,"_169":42},"connections",{"_167":42,"_168":42},"count","unfilledCount","emptyCount",{"_18":154,"_20":155,"_114":156,"_115":-5,"_116":68,"_117":66,"_119":38,"_22":188,"_65":134,"_122":96,"_124":158,"_126":26,"_127":-5,"_176":189,"_85":190},{"_18":145,"_20":146,"_114":147,"_115":-5,"_116":68,"_117":148,"_119":38,"_22":185,"_65":150,"_122":151,"_124":152,"_126":26,"_127":-5,"_176":186,"_85":187},{"_18":138,"_20":139,"_114":140,"_115":-5,"_116":68,"_117":141,"_119":38,"_22":182,"_65":42,"_122":135,"_124":143,"_126":26,"_127":-5,"_176":183,"_85":184},{"_18":129,"_20":130,"_114":131,"_115":-5,"_116":68,"_117":132,"_119":38,"_22":179,"_65":134,"_122":135,"_124":136,"_126":26,"_127":-5,"_176":180,"_85":181},{"_18":112,"_20":113,"_114":36,"_115":-5,"_116":68,"_117":118,"_119":38,"_22":175,"_65":121,"_122":123,"_124":125,"_126":26,"_127":-5,"_176":177,"_85":178},["D",1788459920317],"children",[],[113],["D",1788463176362],[],[130],["D",1787980418848],[],[139],["D",1788442759984],[],[146],["D",1788464523105],[],[155],["D",1787978624302],{"_16":17,"_83":79},{"_16":17,"_77":-5,"_78":79,"_33":34,"_80":81,"_82":26},{"_65":66,"_20":67,"_18":68,"_69":19,"_70":-5,"_71":-5,"_72":-5,"_73":-5,"_74":-5,"_75":21,"_76":17},"ctx",{"_58":-5,"_104":228,"_229":230,"_231":232,"_233":26,"_234":26,"_235":26,"_236":38,"_237":-5,"_238":-7,"_239":-7,"_240":42,"_241":26,"_242":26,"_243":-5,"_244":26,"_245":26,"_246":26,"_247":-5},"ENV",{"_199":200,"_201":202,"_203":67,"_204":205,"_206":207,"_208":209,"_210":211,"_212":213,"_214":215,"_216":217,"_218":219,"_220":221,"_222":223,"_224":225,"_226":227},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","fdb67791413f4386b4dbf18f354029a617f6160f","RENDER_GIT_BRANCH","POSTHOG_API_TOKEN","phc_nmoyuAkStEZuUp69rYlg1DZgrIt19Gx0Y4Hwf8tGgJP","POSTHOG_API_HOST","https://wart.val.town","WEB_API_TEMPLATE","https://{val}.web.val.run","APP_URL","https://www.val.town","MODULE_URL","https://esm.town","VANITY_WEB_API_TEMPLATE","https://{label}.val.run/","DENOLS_URL","https://lsp.val.town","NODE_ENV","production","CLOUDFLARE_TURNSTILE_SITE_KEY","0x4AAAAAACtaIZJH7s9rBMZ6","GOOGLE_CLIENT_ID","875989696899-jtsqkhlbdv5jrlsk8631p7ipjg3c6o62.apps.googleusercontent.com","STRIPE_PUBLISHABLE_KEY","pk_live_51N2zvWEpZTTLipIkVEwXrUG9AT0yeOOEYxszarZT1jpsZV58Ly6wlg3SltZpHN26CUalOBmUSY7adQRQiSkCZz2500qSXNkf8Y","API_URL","https://api.val.town",[],"preferencesKeybindings","default","preferencesTheme","light","preferencesFixers","preferencesCopilot","preferencesSelectionAi","preferencesCloseBrackets","preferencesChatPanelState","preferencesDprint","preferencesDenofmt","notificationCount","flagDenols","isBusinessOrgMember","businessOrgHandle","isBusinessOrgAdmin","isHigherTownieTier","navCollapsed","currentOrgId"]