@mynameistito/hcc-bin-day 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tito
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# hcc-bin-day-api
+
+[![CI](https://github.com/mynameistito/hcc-bin-day-api/actions/workflows/ci.yml/badge.svg)](https://github.com/mynameistito/hcc-bin-day-api/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
+
+TypeScript client for the Hamilton City Council Fight the Landfill bin-day lookup API.
+
+## What it does
+
+- searches Hamilton addresses
+- resolves a street address to a bin collection schedule
+- supports text and JSON output
+
+## API endpoints
+
+This client talks to the public Hamilton City Council backend used by the Fight the Landfill page:
+
+- `GET /FightTheLandFill/get_Addresses?search_string=...`
+- `GET /FightTheLandFill/get_Collection_Dates?address_string=...`
+
+Base URL:
+
+```text
+https://api2.hcc.govt.nz
+```
+
+## Usage
+
+```bash
+bun run src/index.ts
+bun run src/index.ts search "12 Grey Street"
+bun run src/index.ts lookup "12 Grey Street"
+bun run src/index.ts schedule "12 Grey Street"
+bun run src/index.ts --json lookup "12 Grey Street"
+```
+
+## Output modes
+
+- `search` returns matching addresses
+- `schedule` returns the collection schedule for an exact match
+- `lookup` searches for an exact match and falls back to suggestions
+- `--json` prints structured JSON for scripting
+
+## Project structure
+
+```text
+src/
+  hamilton-api.ts
+  index.ts
+  types.ts
+```
+
+## Development
+
+```bash
+bun install
+bun run check
+bun run typecheck
+bun run fix
+bun run build
+```
+
+## Tooling
+
+- Type checking: `@typescript/native-preview` via `tsgo`
+- Bundling: `tsdown` targeting Node.js
+
+## Disclaimer
+
+This project is unofficial and is not affiliated with, endorsed by, supported by, or associated with Hamilton City Council.
+
+It is provided independently as a convenience for accessing publicly available collection data. API behavior, availability, response formats, and returned data may change without notice.
+
+## License
+
+MIT

package/dist/index.mjs

@@ -0,0 +1,301 @@
+//#region src/schedule.ts
+const COLLECTION_DAY_NAMES = [
+	"Monday",
+	"Tuesday",
+	"Wednesday",
+	"Thursday",
+	"Friday",
+	"Saturday",
+	"Sunday"
+];
+const BINS_BY_WEEK = {
+	red: ["red bin", "food scraps bin"],
+	yellow: [
+		"yellow bin",
+		"glass crate",
+		"food scraps bin"
+	]
+};
+const parseCouncilDate = (value) => value.slice(0, 10);
+const collectionDayName = (day) => {
+	const name = COLLECTION_DAY_NAMES[day - 1];
+	if (!name) throw new Error(`Invalid collection day: ${day}`);
+	return name;
+};
+const buildSchedule = (result) => {
+	const redBin = parseCouncilDate(result.RedBin);
+	const yellowBin = parseCouncilDate(result.YellowBin);
+	const upcomingWeek = redBin < yellowBin ? "red" : "yellow";
+	const nextDate = upcomingWeek === "red" ? redBin : yellowBin;
+	return {
+		address: result.Address,
+		collectionDay: result.CollectionDay,
+		collectionDayName: collectionDayName(result.CollectionDay),
+		collectionWeek: result.CollectionWeek,
+		nextCollection: {
+			bins: BINS_BY_WEEK[upcomingWeek],
+			date: nextDate,
+			type: upcomingWeek
+		},
+		redBin,
+		upcomingWeek,
+		yellowBin
+	};
+};
+const formatWeekLabel = (week) => week === "red" ? "Red week" : "Yellow week";
+const formatScheduleDate = (date) => {
+	return (/* @__PURE__ */ new Date(`${date}T12:00:00`)).toLocaleDateString("en-NZ", {
+		day: "numeric",
+		month: "long",
+		weekday: "long",
+		year: "numeric"
+	});
+};
+const formatScheduleText = (schedule) => {
+	const oppositeWeek = schedule.upcomingWeek === "red" ? "yellow" : "red";
+	const oppositeDate = schedule.upcomingWeek === "red" ? schedule.yellowBin : schedule.redBin;
+	return [
+		`${schedule.address} — ${schedule.collectionDayName} collection`,
+		`${formatWeekLabel(schedule.upcomingWeek)} (${formatScheduleDate(schedule.nextCollection.date)})`,
+		`  Put out: ${schedule.nextCollection.bins.join(", ")}`,
+		`${formatWeekLabel(oppositeWeek)} (${formatScheduleDate(oppositeDate)})`,
+		`  Put out: ${BINS_BY_WEEK[oppositeWeek].join(", ")}`
+	].join("\n");
+};
+const toScheduleJson = (schedule) => {
+	const followingWeek = schedule.upcomingWeek === "red" ? "yellow" : "red";
+	const followingDate = schedule.upcomingWeek === "red" ? schedule.yellowBin : schedule.redBin;
+	return {
+		address: schedule.address,
+		collectionDay: schedule.collectionDay,
+		collectionDayName: schedule.collectionDayName,
+		collectionWeek: schedule.collectionWeek,
+		following: {
+			bins: [...BINS_BY_WEEK[followingWeek]],
+			date: followingDate,
+			dateFormatted: formatScheduleDate(followingDate),
+			week: followingWeek,
+			weekLabel: formatWeekLabel(followingWeek)
+		},
+		redBin: schedule.redBin,
+		upcoming: {
+			bins: [...schedule.nextCollection.bins],
+			date: schedule.nextCollection.date,
+			dateFormatted: formatScheduleDate(schedule.nextCollection.date),
+			week: schedule.upcomingWeek,
+			weekLabel: formatWeekLabel(schedule.upcomingWeek)
+		},
+		yellowBin: schedule.yellowBin
+	};
+};
+
+//#endregion
+//#region src/hamilton-api.ts
+const API_BASE_URL = "https://api2.hcc.govt.nz";
+const fetchJson = async (url) => {
+	const response = await fetch(url);
+	if (!response.ok) {
+		if (response.status === 404) return [];
+		throw new Error(`Request failed: ${response.status} ${response.statusText}`);
+	}
+	return await response.json();
+};
+const searchAddresses = async (searchString) => {
+	const url = new URL("/FightTheLandFill/get_Addresses", API_BASE_URL);
+	url.searchParams.set("search_string", searchString);
+	return (await fetchJson(url.toString())).map((result) => result.Collection_Address);
+};
+const getCollectionSchedule = async (address) => {
+	const url = new URL("/FightTheLandFill/get_Collection_Dates", API_BASE_URL);
+	url.searchParams.set("address_string", address);
+	const [first] = await fetchJson(url.toString());
+	if (!first) return null;
+	return buildSchedule(first);
+};
+
+//#endregion
+//#region src/normalize-address.ts
+const STREET_TYPE_ALIASES = {
+	av: "avenue",
+	ave: "avenue",
+	avenue: "avenue",
+	blvd: "boulevard",
+	boulevard: "boulevard",
+	cct: "circuit",
+	circuit: "circuit",
+	cl: "close",
+	close: "close",
+	court: "court",
+	cres: "crescent",
+	crescent: "crescent",
+	ct: "court",
+	dr: "drive",
+	drive: "drive",
+	gr: "grove",
+	grove: "grove",
+	heights: "heights",
+	hts: "heights",
+	lane: "lane",
+	ln: "lane",
+	parade: "parade",
+	pde: "parade",
+	pl: "place",
+	place: "place",
+	rd: "road",
+	rise: "rise",
+	road: "road",
+	st: "street",
+	street: "street",
+	tce: "terrace",
+	terrace: "terrace",
+	way: "way"
+};
+const collapseWhitespace = (value) => value.trim().replaceAll(/\s+/gu, " ");
+const normalizeUnitSuffix = (value) => value.replaceAll(/\b(?<number>\d+)\s*(?<suffix>[a-zA-Z])\b/gu, (_, number, suffix) => `${number}${suffix.toUpperCase()}`);
+const expandStreetTypes = (value) => {
+	return value.split(" ").map((token) => STREET_TYPE_ALIASES[token.toLowerCase()] ?? token).join(" ");
+};
+const normalizeAddress = (address) => {
+	return expandStreetTypes(normalizeUnitSuffix(collapseWhitespace(address).toLowerCase()));
+};
+const expandAddressQuery = (query) => {
+	return expandStreetTypes(normalizeUnitSuffix(collapseWhitespace(query)));
+};
+const pickMatchingAddress = (query, matches) => {
+	const normalizedQuery = normalizeAddress(query);
+	const exactMatches = matches.filter((match) => normalizeAddress(match) === normalizedQuery);
+	if (exactMatches.length === 1) return exactMatches[0] ?? null;
+	return null;
+};
+
+//#endregion
+//#region src/address.ts
+const NO_ADDRESS_FOUND = "No address found";
+const filterMatches = (matches) => matches.filter((match) => match !== NO_ADDRESS_FOUND);
+const resolveAddressQuery = async (query) => {
+	const expandedQuery = expandAddressQuery(query);
+	let matches = filterMatches(await searchAddresses(query));
+	if (matches.length === 0 && expandedQuery !== query) matches = filterMatches(await searchAddresses(expandedQuery));
+	if (matches.length === 0) return {
+		matches: [],
+		ok: false
+	};
+	const matchedAddress = pickMatchingAddress(query, matches);
+	if (!matchedAddress) return {
+		matches,
+		ok: false
+	};
+	const schedule = await getCollectionSchedule(matchedAddress);
+	if (!schedule) return {
+		matches,
+		ok: false
+	};
+	return {
+		matchedAddress,
+		ok: true,
+		schedule
+	};
+};
+
+//#endregion
+//#region src/index.ts
+const TEXT_FLAGS = new Set([
+	"--text",
+	"--pretty",
+	"-p"
+]);
+const JSON_FLAGS = new Set(["--json", "-j"]);
+const printHelp = () => {
+	console.log(`Hamilton bin-day client
+
+Usage:
+  bun run src/index.ts search <address>
+  bun run src/index.ts schedule <address>
+  bun run src/index.ts lookup <address>
+  bun run src/index.ts schedule <address> --text
+
+Examples:
+  bun run src/index.ts schedule "14b mountbatten pl"
+  bun run src/index.ts schedule "14b mountbatten pl" --text
+  bun run src/index.ts lookup "12 grey st"
+
+Output is JSON by default. Use --text (or --pretty) for human-readable output.
+Address input is flexible: unit suffixes (14b -> 14B) and street types (pl, st, rd, etc.).
+`);
+};
+const parseArgs = (argv) => {
+	const rawArgs = argv.slice(2);
+	let textFromFlag = false;
+	const args = [];
+	for (const arg of rawArgs) if (TEXT_FLAGS.has(arg) || JSON_FLAGS.has(arg)) {
+		if (TEXT_FLAGS.has(arg)) textFromFlag = true;
+	} else args.push(arg);
+	const [command, ...queryParts] = args;
+	const query = queryParts.join(" ");
+	return {
+		command,
+		json: !textFromFlag,
+		query
+	};
+};
+const printJson = (value) => {
+	console.log(JSON.stringify(value, null, 2));
+};
+const main = async () => {
+	const { json, command, query } = parseArgs(process.argv);
+	if (!command || command === "help" || command === "--help" || command === "-h") {
+		printHelp();
+		return;
+	}
+	if (!query) {
+		printHelp();
+		return;
+	}
+	if (command === "search") {
+		const matches = await searchAddresses(query);
+		if (json) {
+			printJson({
+				command,
+				matches,
+				query
+			});
+			return;
+		}
+		console.log("Matches:", matches);
+		return;
+	}
+	if (command === "schedule" || command === "lookup") {
+		const resolved = await resolveAddressQuery(query);
+		if (!resolved.ok) {
+			if (json) {
+				printJson({
+					command,
+					found: false,
+					matches: resolved.matches,
+					query
+				});
+				return;
+			}
+			console.log(`No match found for: ${query}`);
+			if (resolved.matches.length > 0) console.log("Did you mean:", resolved.matches.slice(0, 10));
+			return;
+		}
+		if (json) {
+			printJson({
+				command,
+				found: true,
+				matchedAddress: resolved.matchedAddress,
+				query,
+				schedule: toScheduleJson(resolved.schedule)
+			});
+			return;
+		}
+		console.log(formatScheduleText(resolved.schedule));
+		return;
+	}
+	printHelp();
+};
+await main();
+
+//#endregion
+export {  };

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@mynameistito/hcc-bin-day",
+  "version": "0.1.0",
+  "description": "TypeScript client for Hamilton City Council Fight the Landfill bin-day lookup API.",
+  "keywords": [
+    "api",
+    "bin-day",
+    "hamilton",
+    "hamilton-city-council",
+    "typescript",
+    "waste"
+  ],
+  "homepage": "https://github.com/mynameistito/hcc-bin-day#readme",
+  "bugs": {
+    "url": "https://github.com/mynameistito/hcc-bin-day/issues"
+  },
+  "license": "MIT",
+  "author": "Tito <contact@mynameistito.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mynameistito/hcc-bin-day.git"
+  },
+  "bin": {
+    "hcc-bin-day-api": "dist/src/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "scripts": {
+    "build": "tsdown",
+    "dev": "bun run src/index.ts",
+    "check": "ultracite check",
+    "fix": "ultracite fix",
+    "typecheck": "tsgo --noEmit",
+    "knip": "bunx knip@latest",
+    "ci": "bun run check && bun run typecheck && bun run build",
+    "prepare": "lefthook install"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "^7.0.0-dev.20260624.1",
+    "lefthook": "^2.1.9",
+    "oxfmt": "^0.56.0",
+    "oxlint": "^1.71.0",
+    "tsdown": "0.16.0",
+    "ultracite": "7.8.3"
+  }
+}