\n \n \n\n","label",[167,67],"frontend","pulls","branches","forks","envVars",{"_175":39,"_177":39},"connections",{"_175":26,"_176":26},"count","unfilledCount","emptyCount",{"_32":264,"_13":248,"_65":240,"_42":-5,"_34":35,"_160":39,"_161":86,"_36":265,"_38":26,"_68":235,"_163":-5,"_69":24,"_165":-5,"_194":266,"_17":267},{"_32":257,"_13":258,"_65":259,"_42":240,"_34":35,"_160":243,"_161":86,"_36":260,"_38":26,"_68":209,"_163":261,"_69":24,"_165":-5,"_194":262,"_17":263},{"_32":249,"_13":250,"_65":251,"_42":240,"_34":35,"_160":252,"_161":86,"_36":253,"_38":39,"_68":209,"_163":254,"_69":24,"_165":-5,"_194":255,"_17":256},{"_32":238,"_13":239,"_65":84,"_42":240,"_34":35,"_160":241,"_161":86,"_36":242,"_38":243,"_68":244,"_163":245,"_69":24,"_165":-5,"_194":246,"_17":247},{"_32":233,"_13":167,"_65":159,"_42":-5,"_34":35,"_160":39,"_161":86,"_36":234,"_38":26,"_68":235,"_163":-5,"_69":24,"_165":-5,"_194":236,"_17":237},{"_32":224,"_13":225,"_65":226,"_42":159,"_34":35,"_160":227,"_161":86,"_36":228,"_38":229,"_68":209,"_163":230,"_69":24,"_165":-5,"_194":231,"_17":232},{"_32":216,"_13":217,"_65":218,"_42":159,"_34":35,"_160":219,"_161":86,"_36":220,"_38":39,"_68":209,"_163":221,"_69":24,"_165":-5,"_194":222,"_17":223},{"_32":158,"_13":67,"_65":66,"_42":159,"_34":35,"_160":39,"_161":86,"_36":213,"_38":26,"_68":21,"_163":164,"_69":24,"_165":-5,"_194":214,"_17":215},{"_32":205,"_13":206,"_65":207,"_42":159,"_34":35,"_160":39,"_161":86,"_36":208,"_38":26,"_68":209,"_163":210,"_69":24,"_165":-5,"_194":211,"_17":212},{"_32":197,"_13":198,"_65":199,"_42":-5,"_34":35,"_160":200,"_161":86,"_36":201,"_38":26,"_68":21,"_163":202,"_69":24,"_165":-5,"_194":203,"_17":204},{"_32":189,"_13":190,"_65":191,"_42":-5,"_34":35,"_160":109,"_161":86,"_36":192,"_38":39,"_68":21,"_163":193,"_69":24,"_165":-5,"_194":195,"_17":196},"5f59c932-5cb5-11f1-9916-1607ee4eb77e","README.md","019e7c96-9fd0-77c8-93fb-1ca4fb092182",["D",1780206948352],"# 🏷️ Hidden Clearances API\n\nA UI **+ JSON API** that proxies [hiddenclearances.com](https://www.hiddenclearances.com).\nBrowse the clearance deal feed and check live per-store stock for any SKU — and consume it\nfrom a **Discord bot** via a clean, documented REST API.\n\n## What it does\n\n- **Deals feed** — paginated grid of clearance leads (sort by newest/discount/price).\n- **Search** — keyword search across the feed.\n- **Random deal** — one-shot endpoint, perfect for a `!deal` command.\n- **Stock lookup** — which nearby stores have a SKU in stock for a ZIP (qty, price, aisle).\n\n## API\n\nFull docs (with discord.js recipes): **[`/docs`](./API.md)** or hit `GET /api` live for a\nself-describing index.\n\n| Route | Description |\n| --- | --- |\n| `GET /api` | Self-describing index of all endpoints. |\n| `GET /api/health` | Liveness + token check. |\n| `GET /api/deals?limit=24&page=1&sort=newest` | Paginated clearance feed. |\n| `GET /api/deals/:id` | Single deal by id or SKU. |\n| `GET /api/search?q=dewalt&limit=20` | Keyword search. |\n| `GET /api/random?sort=discount` | One random recent deal. |\n| `GET /api/stock?retailer=home_depot&sku=336764660&zip=80019` | Per-store live stock. |\n| `GET /api/retailers` | Supported retailers. |\n\nAll responses share an envelope: `{ success: true, ... }` or\n`{ success: false, error: { code, message } }`.\n\n`retailer` accepts `home_depot` / `lowes` / `walmart`.\n\n## Auth\n\n**Upstream (`HC_TOKEN`) — required.** The upstream API needs a Supabase JWT Bearer token\nthat expires (~1hr). When `/api/health` returns `token_expired`, refresh it.\n\n👉 Set/refresh HC_TOKEN here: https://www.val.town/x/xn5n7y11/hidden-clearances-api/environment-variables?key=HC_TOKEN\n\n**Your API key (`API_KEY`) — optional.** Leave unset to keep the API open. Set it to require\ncallers to pass `?key=`, `x-api-key`, or `Authorization: Bearer`.\n\n👉 Set API_KEY here: https://www.val.town/x/xn5n7y11/hidden-clearances-api/environment-variables?key=API_KEY\n\n## Structure\n\n```mermaid\ngraph TD\n UI[\"frontend/App.tsx + StockModal.tsx\"] -->|/api/deals, /api/stock| R[\"backend/index.ts (Hono router)\"]\n BOT[\"Your Discord bot\"] -->|/api/*| R\n R -->|mounts /api| A[\"backend/api.ts (typed endpoints)\"]\n A -->|getLeads / getStock| H[\"backend/hc.ts (client)\"]\n H -->|Bearer HC_TOKEN| API[\"api.hiddenclearances.com\"]\n```\n","children",[],[190],"4a3629b0-5cb5-11f1-9916-1607ee4eb77e","API.md","4a362ac8-5cb5-11f1-9916-1607ee4eb77e",12,["D",1780206912899],"# Hidden Clearances API\n\nA clean JSON API that proxies [hiddenclearances.com](https://www.hiddenclearances.com):\na **clearance deal feed** plus **per-store live stock lookups**. Built for Discord bots\nand other automated clients.\n\n**Base URL:** `https://xn5n7y11--019e7c969fd077c893fb01c422d7249b.web.val.run`\n\n> Tip: hit `GET /api` for a live, self-describing index of every endpoint, and\n> `GET /docs` for this document.\n\n---\n\n## Response envelope\n\nEvery endpoint returns JSON with a `success` boolean.\n\n**Success**\n```json\n{ \"success\": true, \"deals\": [ ... ], \"count\": 24, \"pagination\": { ... } }\n```\n\n**Error**\n```json\n{ \"success\": false, \"error\": { \"code\": \"token_expired\", \"message\": \"...\" } }\n```\n\n| HTTP | error.code | Meaning |\n| ---- | --------------------- | ---------------------------------------------------- |\n| 400 | `bad_request` | Missing/invalid query params. |\n| 401 | `unauthorized` | API key required but missing/wrong (if enabled). |\n| 404 | `not_found` | No matching deal / no stores. |\n| 502 | `upstream_error` | Upstream returned a non-OK response. |\n| 502 | `upstream_unreachable`| Network error reaching upstream. |\n| 503 | `token_expired` | `HC_TOKEN` expired — refresh it (see bottom). |\n| 500 | `internal_error` | Unexpected server error. |\n\nYour bot should always check `success` and surface `error.message` to the user.\n\n---\n\n## Authentication (optional)\n\nBy default the API is **open**. To lock it down, set an `API_KEY` env var. Then every\n`/api/*` request must include the key one of these ways:\n\n- Query param: `?key=YOUR_KEY`\n- Header: `x-api-key: YOUR_KEY`\n- Header: `Authorization: Bearer YOUR_KEY`\n\n👉 Set API_KEY here: https://www.val.town/x/xn5n7y11/hidden-clearances-api/environment-variables?key=API_KEY\n\nCORS is enabled (`*`) so the API also works from browsers/web dashboards.\n\n---\n\n## Endpoints\n\n### `GET /api`\nSelf-describing index. No params. Lists endpoints, retailers, and sorts.\n\n### `GET /api/health`\nLiveness + token sanity check. Returns `{ success, status, upstream, totalDeals }`.\nIf the token is dead you'll get `503` with `status: \"token_expired\"`.\n\n### `GET /api/retailers`\nReturns the supported retailers and their display names.\n\n### `GET /api/deals`\nPaginated clearance feed.\n\n| Param | Type | Default | Notes |\n| ---------- | ------ | -------- | ------------------------------------------------ |\n| `limit` | int | `24` | 1–100 per page. |\n| `page` | int | `1` | |\n| `sort` | string | `newest` | `newest` \\| `oldest` \\| `discount` \\| `price`. |\n| `retailer` | string | — | Optional filter: `home_depot`/`lowes`/`walmart`. |\n\n```json\n{\n \"success\": true,\n \"count\": 24,\n \"pagination\": { \"total\": 5231, \"page\": 1, \"limit\": 24, \"totalPages\": 218 },\n \"deals\": [\n {\n \"id\": \"abc123\",\n \"sku\": \"336764660\",\n \"title\": \"DeWalt 20V MAX Drill\",\n \"retailer\": \"home_depot\",\n \"retailerName\": \"Home Depot\",\n \"image\": \"https://.../img.jpg\",\n \"originalPrice\": 199.0,\n \"clearancePrice\": 49.0,\n \"discountPercent\": 75,\n \"savings\": 150.0,\n \"url\": \"https://www.homedepot.com/...\",\n \"createdAt\": \"2026-05-30T12:00:00Z\",\n \"expiresAt\": null\n }\n ]\n}\n```\n\n### `GET /api/deals/:id`\nFetch a single deal by its `id` **or** `sku` (scans recent pages). Returns `{ success, deal }`\nor `404 not_found`.\n\n### `GET /api/search`\nKeyword search over recent deals (matches title + SKU).\n\n| Param | Type | Default | Notes |\n| ------- | ------ | ------- | -------------------------------------- |\n| `q` | string | — | **Required.** Search term. |\n| `limit` | int | `20` | 1–50 results. |\n| `pages` | int | `3` | How many upstream pages to scan (1–10).|\n\nReturns `{ success, query, count, deals: [...] }`.\n\n### `GET /api/random`\nOne random recent deal — perfect for a `!deal` command.\n\n| Param | Type | Default | Notes |\n| ---------- | ------ | ---------- | ---------------------------------- |\n| `sort` | string | `discount` | Pool to pick from. |\n| `retailer` | string | — | Optional filter. |\n\nReturns `{ success, deal }`.\n\n### `GET /api/stock`\nPer-store live stock for a SKU near a ZIP.\n\n| Param | Type | Default | Notes |\n| ------------- | ------ | ------------ | -------------------------------------- |\n| `sku` | string | — | **Required.** |\n| `zip` | string | — | **Required.** 5-digit US ZIP. |\n| `retailer` | string | `home_depot` | `home_depot`/`lowes`/`walmart`. |\n| `inStockOnly` | bool | `false` | `true` to drop out-of-stock stores. |\n| `limit` | int | `100` | Max stores returned (1–200). |\n\n```json\n{\n \"success\": true,\n \"sku\": \"336764660\",\n \"zip\": \"80019\",\n \"retailer\": \"homedepot\",\n \"retailerName\": \"Home Depot\",\n \"retailPrice\": 199.0,\n \"summary\": { \"totalStores\": 32, \"inStock\": 4 },\n \"stores\": [\n {\n \"storeId\": \"1234\",\n \"storeName\": \"Aurora\",\n \"address\": \"123 Main St\",\n \"city\": \"Aurora\", \"state\": \"CO\", \"zip\": \"80012\",\n \"quantity\": 3, \"inStock\": true, \"price\": 49.0,\n \"itemLocation\": \"Aisle 12, Bay 004\",\n \"distance\": 4.2\n }\n ]\n}\n```\nStores are sorted in-stock-first, then by distance.\n\n---\n\n## Discord bot recipes\n\n### discord.js — `!deal` slash/prefix command (random deal embed)\n```js\nconst BASE = \"https://xn5n7y11--019e7c969fd077c893fb01c422d7249b.web.val.run\";\nconst API_KEY = process.env.HC_API_KEY; // omit if you didn't set one\n\nasync function hc(path) {\n const res = await fetch(`${BASE}${path}`, {\n headers: API_KEY ? { \"x-api-key\": API_KEY } : {},\n });\n const data = await res.json();\n if (!data.success) throw new Error(data.error?.message ?? \"API error\");\n return data;\n}\n\nclient.on(\"messageCreate\", async (msg) => {\n if (msg.content === \"!deal\") {\n try {\n const { deal: d } = await hc(\"/api/random\");\n await msg.reply({\n embeds: [{\n title: d.title,\n url: d.url ?? undefined,\n description: `**$${d.clearancePrice}** ~~$${d.originalPrice}~~ · **-${d.discountPercent}%**`,\n thumbnail: d.image ? { url: d.image } : undefined,\n fields: [\n { name: \"Retailer\", value: d.retailerName, inline: true },\n { name: \"SKU\", value: String(d.sku), inline: true },\n ],\n color: 0x10b981,\n }],\n });\n } catch (e) {\n await msg.reply(`⚠️ ${e.message}`);\n }\n }\n});\n```\n\n### `!search `\n```js\nconst term = msg.content.slice(\"!search \".length).trim();\nconst { deals } = await hc(`/api/search?q=${encodeURIComponent(term)}&limit=5`);\nawait msg.reply(deals.length\n ? deals.map(d => `• **${d.title}** — $${d.clearancePrice} (-${d.discountPercent}%) [link](${d.url})`).join(\"\\n\")\n : \"No deals found.\");\n```\n\n### `!stock ` (Home Depot by default)\n```js\nconst [, sku, zip] = msg.content.split(/\\s+/);\nconst s = await hc(`/api/stock?sku=${sku}&zip=${zip}&inStockOnly=true&limit=5`);\nawait msg.reply(s.summary.inStock\n ? `**${s.summary.inStock}/${s.summary.totalStores}** stores have it:\\n` +\n s.stores.map(st => `• ${st.storeName} — ${st.quantity} @ $${st.price} (${st.distance.toFixed(1)} mi)`).join(\"\\n\")\n : \"Out of stock at all nearby stores.\");\n```\n\n---\n\n## Auth — keeping the upstream token fresh\n\nThe upstream `api.hiddenclearances.com` requires a **Supabase JWT** that expires roughly\nhourly. It lives in the `HC_TOKEN` env var. When `/api/health` returns `token_expired`\n(or deals stop loading), grab a fresh `authorization` Bearer value from a logged-in\nrequest on hiddenclearances.com and update the env var.\n\n👉 Refresh HC_TOKEN here: https://www.val.town/x/xn5n7y11/hidden-clearances-api/environment-variables?key=HC_TOKEN\n",[],[198],"cf480034-5cb4-11f1-ae2b-1607ee4eb77e","main.tsx","019e7c96-9fd0-77c8-93fb-177a3cebda86",["D",1780206706547],"script","/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport React from \"https://esm.sh/react@18.2.0\";\nimport { createRoot } from \"https://esm.sh/react-dom@18.2.0/client?deps=react@18.2.0\";\nimport { App } from \"./App.tsx\";\n\ncreateRoot(document.getElementById(\"root\")!).render();\n",[],[167,206],["D",1780206706547],[],[167,67],"338f03ee-5cb5-11f1-9916-1607ee4eb77e","StockModal.tsx","019e7c96-9fd0-77c8-93fb-0c20bc0ac4ac",11,["D",1780206874890],"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport React, { useEffect, useState } from \"https://esm.sh/react@18.2.0\";\n\ninterface Store {\n storeId: string;\n storeName: string;\n address: string;\n city: string;\n state: string;\n zip: string;\n quantity: number;\n inStock: boolean;\n price: number;\n itemLocation: string;\n distance: number;\n}\n\nexport function StockModal(\n { sku, retailer, title, onClose }: {\n sku: string;\n retailer: string;\n title: string;\n onClose: () => void;\n },\n) {\n const [zip, setZip] = useState(localStorage.getItem(\"hc_zip\") || \"80019\");\n const [loading, setLoading] = useState(false);\n const [error, setError] = useState(null);\n const [item, setItem] = useState(null);\n const [stores, setStores] = useState([]);\n const [onlyInStock, setOnlyInStock] = useState(false);\n\n async function check(e?: React.FormEvent) {\n e?.preventDefault();\n setLoading(true);\n setError(null);\n localStorage.setItem(\"hc_zip\", zip);\n try {\n const r = await fetch(\n `/api/stock?retailer=${encodeURIComponent(retailer)}&sku=${encodeURIComponent(sku)}&zip=${encodeURIComponent(zip)}`,\n );\n const data = await r.json();\n if (!data.success) throw new Error(data.error?.message || \"Lookup failed\");\n setItem({ retailPrice: data.retailPrice, summary: data.summary });\n setStores(data.stores || []);\n } catch (err) {\n setError(String(err));\n setStores([]);\n } finally {\n setLoading(false);\n }\n }\n\n useEffect(() => {\n check();\n // eslint-disable-next-line\n }, []);\n\n const shown = (onlyInStock ? stores.filter((s) => s.inStock) : stores)\n .slice()\n .sort((a, b) => Number(b.inStock) - Number(a.inStock) || a.distance - b.distance);\n const inStockCount = stores.filter((s) => s.inStock).length;\n\n return (\n \n e.stopPropagation()}\n >\n

{title}

SKU {sku} · {retailer.replace(/_/g, \" \")}

\n \n ×\n \n

\n\n

\n ZIP\n setZip(e.target.value)}\n className=\"border border-gray-300 rounded-lg px-3 py-1.5 w-28 text-sm\"\n placeholder=\"80019\"\n />\n \n {loading ? \"Checking…\" : \"Check stock\"}\n \n {stores.length > 0 && (\n \n setOnlyInStock(e.target.checked)}\n />\n In stock only\n \n )}\n \n\n

\n {error && (\n

{error}

\n )}\n\n {!error && item && (\n

\n {inStockCount} of{\" \"}\n {stores.length} stores in stock · retail ${item.retailPrice}\n

\n )}\n\n

\n {shown.map((s) => (\n

\n \n

\n {s.storeName}{\" \"}\n · {s.distance.toFixed(1)} mi\n

\n {s.address}, {s.city} {s.zip}\n {s.itemLocation && · {s.itemLocation}}\n

\n {s.inStock\n ? (\n <>\n

{s.quantity} in stock

${s.price}

\n \n )\n :

Out

}\n

\n ))}\n {!loading && shown.length === 0 && !error && (\n

No stores to show.

\n )}\n

\n \n \n );\n}\n",[],[167,217],"30e53244-5cb5-11f1-87b7-1607ee4eb77e","App.tsx","019e7c96-9fd0-77c8-93fb-0b152394eb92",10,["D",1780206870418],4,"/** @jsxImportSource https://esm.sh/react@18.2.0 */\nimport React, { useEffect, useState } from \"https://esm.sh/react@18.2.0\";\nimport { StockModal } from \"./StockModal.tsx\";\n\ninterface Lead {\n id: string;\n retailer: string;\n sku: string;\n title: string;\n image: string | null;\n originalPrice: number | string;\n clearancePrice: number | string;\n discountPercent: number;\n url: string | null;\n createdAt: string;\n}\n\nconst RETAILER_BADGE: Record = {\n home_depot: \"bg-orange-100 text-orange-700\",\n lowes: \"bg-blue-100 text-blue-700\",\n walmart: \"bg-sky-100 text-sky-700\",\n};\n\nfunction DealCard({ lead, onCheck }: { lead: Lead; onCheck: (l: Lead) => void }) {\n return (\n

\n {lead.image\n ? {lead.title}

\n : 📦}\n \n -{lead.discountPercent}%\n \n

\n \n {lead.retailer.replace(/_/g, \" \")}\n \n

{lead.title}

\n ${lead.clearancePrice}\n ${lead.originalPrice}\n

\n onCheck(lead)}\n className=\"flex-1 bg-emerald-600 hover:bg-emerald-700 text-white text-xs font-semibold py-1.5 rounded-lg\"\n >\n 📍 Check stock\n \n {lead.url && (\n \n ↗\n \n )}\n

SKU {lead.sku}

\n );\n}\n\nexport function App() {\n const [leads, setLeads] = useState([]);\n const [loading, setLoading] = useState(true);\n const [error, setError] = useState(null);\n const [page, setPage] = useState(1);\n const [sort, setSort] = useState(\"newest\");\n const [total, setTotal] = useState(0);\n const [totalPages, setTotalPages] = useState(1);\n const [query, setQuery] = useState(\"\");\n const [active, setActive] = useState(null);\n\n const limit = 24;\n\n async function load() {\n setLoading(true);\n setError(null);\n try {\n const r = await fetch(`/api/deals?limit=${limit}&page=${page}&sort=${sort}`);\n const data = await r.json();\n if (!data.success) throw new Error(data.error?.message || \"Failed to load\");\n setLeads(data.deals);\n setTotal(data.pagination.total);\n setTotalPages(data.pagination.totalPages);\n } catch (err) {\n setError(String(err));\n } finally {\n setLoading(false);\n }\n }\n\n useEffect(() => {\n load();\n // eslint-disable-next-line\n }, [page, sort]);\n\n const filtered = query.trim()\n ? leads.filter((l) =>\n (l.title + \" \" + l.sku).toLowerCase().includes(query.toLowerCase())\n )\n : leads;\n\n return (\n

🏷️ Hidden Clearances

\n setQuery(e.target.value)}\n placeholder=\"Filter this page…\"\n className=\"border border-gray-300 rounded-lg px-3 py-1.5 text-sm w-44\"\n />\n { setPage(1); setSort(e.target.value); }}\n className=\"border border-gray-300 rounded-lg px-3 py-1.5 text-sm bg-white\"\n >\n \n \n \n \n \n

\n\n {error && (\n

\n {error}\n

\n If this is an auth error, the HC_TOKEN env var likely expired — refresh it.\n

\n )}\n\n {loading\n ?

Loading deals…

\n : (\n

\n {filtered.map((l) => )}\n

\n )}\n\n {!loading && (\n

\n setPage((p) => p - 1)}\n className=\"px-4 py-1.5 border rounded-lg text-sm disabled:opacity-40 bg-white\"\n >\n ← Prev\n \n \n Page {page} / {totalPages} · {total.toLocaleString()} deals\n \n = totalPages}\n onClick={() => setPage((p) => p + 1)}\n className=\"px-4 py-1.5 border rounded-lg text-sm disabled:opacity-40 bg-white\"\n >\n Next →\n \n

\n )}\n\n \n\n {active && (\n setActive(null)}\n />\n )}\n

\n );\n}\n",[],[167,225],"cf4803f4-5cb4-11f1-ae2b-1607ee4eb77e",["D",1780206706547],"directory",[183,184,185,186],[167],"290f4b40-5cb5-11f1-87b7-1607ee4eb77e","index.ts","019e7c96-9fd0-77c8-93fb-0672408dacfa",6,["D",1780206857265],3,"http","import { Hono } from \"npm:hono\";\nimport { readFile, parseVal, serveFile } from \"https://esm.town/v/std/utils/index.ts\";\nimport { api } from \"./api.ts\";\n\nconst app = new Hono();\napp.onError((err) => Promise.reject(err));\n\n// --- Frontend ---\napp.get(\"/\", async (c) => {\n const html = await readFile(\"/frontend/index.html\", import.meta.url);\n return c.html(html);\n});\n\napp.get(\"/frontend/*\", (c) => serveFile(new URL(c.req.url).pathname, import.meta.url));\n\napp.get(\"/source\", (c) => c.redirect(parseVal().links.self.val));\n\n// --- Human-readable API docs ---\napp.get(\"/docs\", async (c) => {\n const md = await readFile(\"/API.md\", import.meta.url);\n return c.text(md, 200, { \"content-type\": \"text/markdown; charset=utf-8\" });\n});\n\n// --- New structured API (Discord-bot friendly) mounted under /api ---\napp.route(\"/api\", api);\n\nexport default app.fetch;\n",[],[248,239],"backend","00d8a8a6-5cb5-11f1-ae2b-1607ee4eb77e","hc.ts","019e7c96-9fd0-77c8-93fa-ff1490d26874",2,["D",1780206789802],"// Thin typed client for the HiddenClearances upstream API.\n//\n// AUTH: the upstream requires a Supabase JWT Bearer token that EXPIRES (~1hr).\n// It lives in the HC_TOKEN env var. When requests start returning 401/403 (or the\n// feed stops loading), refresh HC_TOKEN with a fresh `authorization` Bearer value\n// copied from a logged-in request on https://www.hiddenclearances.com.\n\nconst BASE = \"https://api.hiddenclearances.com/api/v1\";\n\n/** Retailer slugs as exposed by our API (human-friendly, underscored). */\nexport type Retailer = \"home_depot\" | \"lowes\" | \"walmart\";\n\n/** Map our friendly slug -> the slug the upstream path expects. */\nconst RETAILER_PATH: Record = {\n home_depot: \"homedepot\",\n homedepot: \"homedepot\",\n lowes: \"lowes\",\n walmart: \"walmart\",\n};\n\nexport function normalizeRetailer(input?: string | null): string {\n if (!input) return \"homedepot\";\n const key = input.toLowerCase().trim();\n return RETAILER_PATH[key] ?? key.replace(/[_\\s]/g, \"\");\n}\n\nfunction token(): string {\n const t = Deno.env.get(\"HC_TOKEN\");\n if (!t) throw new HcError(\"Missing HC_TOKEN env var\", 500, \"config_error\");\n return t.replace(/^Bearer\\s+/i, \"\").trim();\n}\n\n/** Structured error so the HTTP layer can map upstream failures to clean codes. */\nexport class HcError extends Error {\n constructor(\n message: string,\n public status: number,\n public code: string,\n public upstream?: string,\n ) {\n super(message);\n this.name = \"HcError\";\n }\n}\n\nasync function hcFetch(path: string): Promise {\n let r: Response;\n try {\n r = await fetch(`${BASE}${path}`, {\n headers: {\n \"authorization\": `Bearer ${token()}`,\n \"accept\": \"*/*\",\n \"origin\": \"https://www.hiddenclearances.com\",\n \"referer\": \"https://www.hiddenclearances.com/\",\n \"user-agent\":\n \"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/148.0.0.0 Safari/537.36\",\n },\n });\n } catch (e) {\n throw new HcError(`Network error reaching upstream: ${e}`, 502, \"upstream_unreachable\");\n }\n\n if (r.status === 401 || r.status === 403) {\n const body = await r.text().catch(() => \"\");\n throw new HcError(\n \"Upstream rejected the token — HC_TOKEN has likely expired, refresh it.\",\n 503,\n \"token_expired\",\n body.slice(0, 300),\n );\n }\n if (!r.ok) {\n const body = await r.text().catch(() => \"\");\n throw new HcError(`Upstream ${r.status}`, 502, \"upstream_error\", body.slice(0, 300));\n }\n return r;\n}\n\n// ---- Shapes returned by the upstream (subset we rely on) ----\n\nexport interface Lead {\n id: string;\n retailer: string;\n sku: string;\n title: string;\n imageUrl: string | null;\n originalPrice: string;\n clearancePrice: string;\n discountPercent: number;\n productUrl: string | null;\n createdAt: string;\n expiresAt?: string;\n}\n\nexport interface LeadsResult {\n success: boolean;\n data: Lead[];\n pagination: { total: number; page: number; limit: number; totalPages: number };\n}\n\nexport interface Store {\n storeId: string;\n storeName: string;\n address: string;\n city: string;\n state: string;\n zip: string;\n quantity: number;\n inStock: boolean;\n price: number;\n itemLocation: string;\n distance: number;\n}\n\nexport interface StockResult {\n success: boolean;\n item?: { retailPrice?: number; [k: string]: unknown };\n stores: Store[];\n}\n\n// ---- Calls ----\n\nexport async function getLeads(\n { limit = 24, page = 1, sort = \"newest\" }: { limit?: number; page?: number; sort?: string },\n): Promise {\n const qs = new URLSearchParams({ limit: String(limit), page: String(page), sort });\n const r = await hcFetch(`/leads?${qs}`);\n return r.json();\n}\n\nexport async function getStock(retailer: string, sku: string, zip: string): Promise {\n const slug = normalizeRetailer(retailer);\n const qs = new URLSearchParams({ sku, zip });\n const r = await hcFetch(`/${slug}/stock?${qs}`);\n return r.json();\n}\n",[],[248,250],"19d99248-5cb5-11f1-a344-1607ee4eb77e","api.ts","19d99324-5cb5-11f1-a344-1607ee4eb77e",["D",1780206831752],"// Public JSON API for the Hidden Clearances proxy — designed for Discord bots\n// and other automated clients. All responses share a consistent envelope:\n//\n// success: true -> { success: true, ...payload }\n// success: false -> { success: false, error: { code, message } }\n//\n// Optional auth: set the API_KEY env var to require callers to send the key via\n// ?key=... query param OR the x-api-key header OR Authorization: Bearer .\n// If API_KEY is unset, the API is open (handy while wiring up your bot).\n\nimport { Hono } from \"npm:hono\";\nimport { cors } from \"npm:hono/cors\";\nimport { getLeads, getStock, HcError, normalizeRetailer, type Lead } from \"./hc.ts\";\n\nexport const api = new Hono();\n\napi.use(\"/*\", cors());\n\n// ---- helpers ----\n\nconst RETAILER_LABEL: Record = {\n homedepot: \"Home Depot\",\n home_depot: \"Home Depot\",\n lowes: \"Lowe's\",\n walmart: \"Walmart\",\n};\n\nfunction clampInt(v: string | undefined, def: number, min: number, max: number): number {\n const n = Number(v);\n if (!Number.isFinite(n)) return def;\n return Math.min(max, Math.max(min, Math.trunc(n)));\n}\n\nfunction fail(c: any, status: number, code: string, message: string) {\n return c.json({ success: false, error: { code, message } }, status);\n}\n\n/** Map an HcError (or anything) to a clean JSON error response. */\nfunction handleError(c: any, e: unknown) {\n if (e instanceof HcError) {\n return c.json(\n { success: false, error: { code: e.code, message: e.message, upstream: e.upstream } },\n e.status,\n );\n }\n return c.json({ success: false, error: { code: \"internal_error\", message: String(e) } }, 500);\n}\n\n/** Optional API-key gate. No-op when API_KEY env var is not set. */\nfunction requireKey(c: any): Response | null {\n const required = Deno.env.get(\"API_KEY\");\n if (!required) return null;\n const provided = c.req.query(\"key\") ||\n c.req.header(\"x-api-key\") ||\n (c.req.header(\"authorization\") || \"\").replace(/^Bearer\\s+/i, \"\").trim();\n if (provided !== required) {\n return fail(c, 401, \"unauthorized\", \"Missing or invalid API key. Pass ?key=, x-api-key, or Authorization: Bearer.\");\n }\n return null;\n}\n\napi.use(\"/*\", async (c, next) => {\n const blocked = requireKey(c);\n if (blocked) return blocked;\n await next();\n});\n\n/** Shape a raw upstream lead into a flatter, bot-friendly deal object. */\nfunction shapeDeal(l: Lead) {\n const original = Number(l.originalPrice);\n const clearance = Number(l.clearancePrice);\n return {\n id: l.id,\n sku: l.sku,\n title: l.title,\n retailer: l.retailer,\n retailerName: RETAILER_LABEL[l.retailer] ?? l.retailer.replace(/_/g, \" \"),\n image: l.imageUrl,\n originalPrice: Number.isFinite(original) ? original : l.originalPrice,\n clearancePrice: Number.isFinite(clearance) ? clearance : l.clearancePrice,\n discountPercent: l.discountPercent,\n savings: Number.isFinite(original) && Number.isFinite(clearance)\n ? Math.round((original - clearance) * 100) / 100\n : null,\n url: l.productUrl,\n createdAt: l.createdAt,\n expiresAt: l.expiresAt ?? null,\n };\n}\n\n// =====================================================================\n// GET /api — self-describing index so a bot dev can discover endpoints\n// =====================================================================\napi.get(\"/\", (c) => {\n const base = new URL(c.req.url).origin;\n return c.json({\n success: true,\n name: \"Hidden Clearances API\",\n description: \"Clearance deal feed + per-store live stock lookup.\",\n docs: `${base}/docs`,\n authRequired: Boolean(Deno.env.get(\"API_KEY\")),\n endpoints: {\n deals: `${base}/api/deals?limit=24&page=1&sort=newest`,\n search: `${base}/api/search?q=dewalt&limit=20`,\n random: `${base}/api/random`,\n stock: `${base}/api/stock?retailer=home_depot&sku=336764660&zip=80019`,\n retailers: `${base}/api/retailers`,\n health: `${base}/api/health`,\n },\n retailers: [\"home_depot\", \"lowes\", \"walmart\"],\n sorts: [\"newest\", \"oldest\", \"discount\", \"price\"],\n });\n});\n\n// =====================================================================\n// GET /api/health — quick liveness + token sanity check\n// =====================================================================\napi.get(\"/health\", async (c) => {\n try {\n const r = await getLeads({ limit: 1, page: 1, sort: \"newest\" });\n return c.json({ success: true, status: \"ok\", upstream: \"reachable\", totalDeals: r.pagination?.total ?? null });\n } catch (e) {\n if (e instanceof HcError && e.code === \"token_expired\") {\n return c.json({ success: false, status: \"token_expired\", error: { code: e.code, message: e.message } }, 503);\n }\n return handleError(c, e);\n }\n});\n\n// =====================================================================\n// GET /api/retailers\n// =====================================================================\napi.get(\"/retailers\", (c) =>\n c.json({\n success: true,\n retailers: [\n { slug: \"home_depot\", name: \"Home Depot\" },\n { slug: \"lowes\", name: \"Lowe's\" },\n { slug: \"walmart\", name: \"Walmart\" },\n ],\n }));\n\n// =====================================================================\n// GET /api/deals — paginated clearance feed\n// ?limit (1-100, def 24) ?page (def 1) ?sort (newest|oldest|discount|price)\n// ?retailer (optional client-side filter on the returned page)\n// =====================================================================\napi.get(\"/deals\", async (c) => {\n try {\n const limit = clampInt(c.req.query(\"limit\"), 24, 1, 100);\n const page = clampInt(c.req.query(\"page\"), 1, 1, 100000);\n const sort = c.req.query(\"sort\") ?? \"newest\";\n const retailerFilter = c.req.query(\"retailer\");\n\n const r = await getLeads({ limit, page, sort });\n let deals = (r.data ?? []).map(shapeDeal);\n if (retailerFilter) {\n const slug = retailerFilter.toLowerCase();\n deals = deals.filter((d) =>\n d.retailer.toLowerCase() === slug || d.retailer.replace(/_/g, \"\") === normalizeRetailer(slug)\n );\n }\n\n return c.json({\n success: true,\n deals,\n count: deals.length,\n pagination: r.pagination,\n });\n } catch (e) {\n return handleError(c, e);\n }\n});\n\n// =====================================================================\n// GET /api/deals/:id — single deal by id (scans recent pages)\n// =====================================================================\napi.get(\"/deals/:id\", async (c) => {\n try {\n const id = c.req.param(\"id\");\n for (let page = 1; page <= 5; page++) {\n const r = await getLeads({ limit: 100, page, sort: \"newest\" });\n const found = (r.data ?? []).find((l) => l.id === id || l.sku === id);\n if (found) return c.json({ success: true, deal: shapeDeal(found) });\n if (page >= (r.pagination?.totalPages ?? 1)) break;\n }\n return fail(c, 404, \"not_found\", `No deal found with id/sku \"${id}\" in recent pages.`);\n } catch (e) {\n return handleError(c, e);\n }\n});\n\n// =====================================================================\n// GET /api/search?q=... — keyword search across the feed\n// ?q (required) ?limit (1-50, def 20) ?pages (how many upstream pages to scan, 1-10 def 3)\n// =====================================================================\napi.get(\"/search\", async (c) => {\n try {\n const q = (c.req.query(\"q\") ?? \"\").trim().toLowerCase();\n if (!q) return fail(c, 400, \"bad_request\", \"Query param 'q' is required.\");\n const limit = clampInt(c.req.query(\"limit\"), 20, 1, 50);\n const pages = clampInt(c.req.query(\"pages\"), 3, 1, 10);\n\n const matches: Lead[] = [];\n for (let page = 1; page <= pages; page++) {\n const r = await getLeads({ limit: 100, page, sort: \"newest\" });\n for (const l of r.data ?? []) {\n if ((l.title + \" \" + l.sku).toLowerCase().includes(q)) matches.push(l);\n }\n if (matches.length >= limit || page >= (r.pagination?.totalPages ?? 1)) break;\n }\n\n return c.json({\n success: true,\n query: q,\n deals: matches.slice(0, limit).map(shapeDeal),\n count: Math.min(matches.length, limit),\n });\n } catch (e) {\n return handleError(c, e);\n }\n});\n\n// =====================================================================\n// GET /api/random — one random recent deal (great for a !deal command)\n// ?sort (def discount) ?retailer (optional)\n// =====================================================================\napi.get(\"/random\", async (c) => {\n try {\n const sort = c.req.query(\"sort\") ?? \"discount\";\n const retailerFilter = c.req.query(\"retailer\");\n const r = await getLeads({ limit: 100, page: 1, sort });\n let pool = r.data ?? [];\n if (retailerFilter) {\n const slug = retailerFilter.toLowerCase();\n pool = pool.filter((l) => l.retailer.toLowerCase() === slug);\n }\n if (pool.length === 0) return fail(c, 404, \"not_found\", \"No deals available for that filter.\");\n const pick = pool[Math.floor(Math.random() * pool.length)];\n return c.json({ success: true, deal: shapeDeal(pick) });\n } catch (e) {\n return handleError(c, e);\n }\n});\n\n// =====================================================================\n// GET /api/stock — per-store live stock for a SKU near a ZIP\n// ?retailer (def home_depot) ?sku (required) ?zip (required)\n// ?inStockOnly=true ?limit (cap stores returned)\n// =====================================================================\napi.get(\"/stock\", async (c) => {\n try {\n const sku = c.req.query(\"sku\");\n const zip = c.req.query(\"zip\");\n if (!sku || !zip) return fail(c, 400, \"bad_request\", \"Both 'sku' and 'zip' query params are required.\");\n\n const retailer = c.req.query(\"retailer\") ?? \"home_depot\";\n const inStockOnly = c.req.query(\"inStockOnly\") === \"true\";\n const limit = clampInt(c.req.query(\"limit\"), 100, 1, 200);\n\n const r = await getStock(retailer, sku, zip);\n let stores = (r.stores ?? []).slice();\n if (inStockOnly) stores = stores.filter((s) => s.inStock);\n stores.sort((a, b) => Number(b.inStock) - Number(a.inStock) || a.distance - b.distance);\n stores = stores.slice(0, limit);\n\n const inStockCount = (r.stores ?? []).filter((s) => s.inStock).length;\n return c.json({\n success: true,\n sku,\n zip,\n retailer: normalizeRetailer(retailer),\n retailerName: RETAILER_LABEL[normalizeRetailer(retailer)] ?? retailer,\n retailPrice: r.item?.retailPrice ?? null,\n summary: { totalStores: (r.stores ?? []).length, inStock: inStockCount },\n stores,\n });\n } catch (e) {\n return handleError(c, e);\n }\n});\n",[],[248,258],"cf477678-5cb4-11f1-ae2b-1607ee4eb77e",["D",1780206706547],[179,180,181],[248],["D",1780206706547],{"_11":12,"_125":72},{"_11":12,"_121":72,"_71":72,"_30":70,"_122":123,"_124":24},{"_38":109,"_13":16,"_32":35,"_110":74,"_111":62,"_112":113,"_114":78,"_115":116,"_117":118,"_119":14,"_120":12},"ctx",{"_51":-5,"_146":305,"_306":307,"_308":309,"_310":24,"_311":24,"_312":24,"_313":86,"_314":-5,"_315":-7,"_316":-7,"_317":26,"_318":24,"_319":24,"_320":-5,"_321":24,"_322":24,"_323":24,"_324":-5},"ENV",{"_276":277,"_278":279,"_280":16,"_281":282,"_283":284,"_285":286,"_287":288,"_289":290,"_291":292,"_293":294,"_295":296,"_297":298,"_299":300,"_301":302,"_303":304},"REACT_APP_SENTRY_DSN","https://586020d86f05489db63a554690acf1e9@o1398359.ingest.sentry.io/6724499","RENDER_GIT_COMMIT","e87eb04e707cf64e7e532c8e8ec395f209e17f15","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"]

History · index.html