{"id":46128470,"url":"https://github.com/wolffruoff/package_tracker","last_synced_at":"2026-04-02T15:47:11.353Z","repository":{"id":341272125,"uuid":"1169341980","full_name":"WolffRuoff/package_tracker","owner":"WolffRuoff","description":"HACS custom integration for tracking USPS, UPS, and FedEx packages in Home Assistant","archived":false,"fork":false,"pushed_at":"2026-02-28T20:15:05.000Z","size":102,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-28T23:31:43.969Z","etag":null,"topics":["hacs","home-assistant","homeassistant-integration","package-tracking"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/WolffRuoff.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-28T14:44:14.000Z","updated_at":"2026-02-28T20:15:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/WolffRuoff/package_tracker","commit_stats":null,"previous_names":["wolffruoff/package_tracker"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/WolffRuoff/package_tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WolffRuoff%2Fpackage_tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WolffRuoff%2Fpackage_tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WolffRuoff%2Fpackage_tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WolffRuoff%2Fpackage_tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/WolffRuoff","download_url":"https://codeload.github.com/WolffRuoff/package_tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/WolffRuoff%2Fpackage_tracker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29991319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-02T01:47:34.672Z","status":"online","status_checked_at":"2026-03-02T02:00:07.342Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacs","home-assistant","homeassistant-integration","package-tracking"],"created_at":"2026-03-02T03:12:05.292Z","updated_at":"2026-04-02T15:47:11.345Z","avatar_url":"https://github.com/WolffRuoff.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Package Tracker for Home Assistant\n\n[![coverage](https://raw.githubusercontent.com/WolffRuoff/package_tracker/main/coverage.svg)](https://github.com/WolffRuoff/package_tracker)\n[![Docker Image Version](https://img.shields.io/docker/v/wolffruoff/package-tracker-scraper?label=scraper)](https://hub.docker.com/r/wolffruoff/package-tracker-scraper)\n\nA HACS custom integration that tracks shipping packages from USPS, UPS, FedEx, and SpeedX with a built-in Lovelace card.\n\n## Features\n\n- Track packages from **USPS**, **UPS**, **FedEx**, and **SpeedX**\n- Auto-detect carrier from tracking number format\n- Built-in Lovelace card with status icons and color coding\n- Add/remove packages via the UI options flow or the `add_package` service\n- Add Package Lovelace card — form card for adding packages directly from the dashboard\n- Modular carrier system — easy to extend with new carriers; the frontend dropdown and Dev Tools service definition stay in sync automatically via the scraper\n\n## Installation\n\n### HACS (Recommended)\n\n1. Open HACS in Home Assistant\n2. Go to **Integrations** → **3-dot menu** → **Custom repositories**\n3. Add this repository URL with category **Integration**\n4. Install \"Package Tracker\"\n5. Restart Home Assistant\n\n### Manual\n\n1. Copy `custom_components/package_tracker/` to your `config/custom_components/` directory\n2. Restart Home Assistant\n\n## Setup\n\nThis integration has two components: a **scraper container** that fetches tracking data, and a **HACS integration** that displays it in Home Assistant.\n\n### 1. Deploy the Scraper Container\n\nRun the scraper as a Docker container on your network (e.g. on the same host as Home Assistant):\n\n```yaml\n# docker-compose.yml\nservices:\n  scraper:\n    image: wolffruoff/package-tracker-scraper:latest\n    container_name: package-tracker-scraper\n    ports:\n      - \"8230:8230\"\n    volumes:\n      - scraper-data:/data\n    environment:\n      - PORT=8230\n      - DB_PATH=/data/package_tracker.db\n    restart: unless-stopped\n\nvolumes:\n  scraper-data:\n```\n\n```bash\ndocker compose up -d\n```\n\n### 2. Install the HACS Integration\n\nFollow the [Installation](#installation) steps above.\n\n### 3. Connect to the Scraper\n\n1. Go to **Settings** → **Devices \u0026 Services** → **Add Integration**\n2. Search for \"Package Tracker\"\n3. Enter the scraper URL (e.g. `http://localhost:8230`)\n\n### 4. Add the Dashboard Resource\n\nThe Lovelace cards are served as a static file by HA. Register the resource so dashboards can load it:\n\n1. Go to **Settings** → **Dashboards** → **3-dot menu** → **Resources**\n2. Click **Add Resource**\n3. Set the URL to `/package_tracker/package-tracker-card.js`\n4. Set the resource type to **JavaScript module**\n5. Click **Create**\n\n\u003e After a manual install the resource must be added manually. HACS installs may handle this automatically.\n\n## Adding Packages\n\n### Via the UI options flow\n\n1. Go to the Package Tracker integration\n2. Click **Configure**\n3. Select **Add a package**\n4. Enter a label, tracking number, and optionally select the carrier (auto-detected by default)\n\n### Via the `add_package` service\n\nCall `package_tracker.add_package` from Developer Tools → Services or an automation:\n\n```yaml\nservice: package_tracker.add_package\ndata:\n  tracking_number: \"92001234567890123456\"\n  label: \"Amazon Order\"\n  carrier: \"\"   # leave blank to auto-detect\n```\n\nFields: `tracking_number` (required), `label` (required), `carrier` (optional — `usps`, `ups`, `fedex`, `speedx`, or blank for auto-detect).\n\n### Via the Add Package card\n\nAdd `custom:package-tracker-add-card` to any dashboard for a form-based UI (see [Lovelace Cards](#lovelace-cards)). The carrier dropdown is populated dynamically from the scraper, so it always reflects the carriers it supports.\n\n## Lovelace Cards\n\n### Package Tracker Card\n\nDisplays all tracked packages sorted by status priority:\n\n```yaml\ntype: custom:package-tracker-card\ntitle: My Packages\nshow_delivered: true\n```\n\nThe card auto-discovers all `sensor.package_tracker_*` entities.\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `title` | string | \"Package Tracker\" | Card title |\n| `show_delivered` | boolean | true | Show delivered packages |\n\n### Add Package Card\n\nA form card for adding packages without leaving the dashboard. Supports the visual editor in the card picker.\n\n```yaml\ntype: custom:package-tracker-add-card\ntitle: Add Package\n```\n\n| Option | Type | Default | Description |\n|--------|------|---------|-------------|\n| `title` | string | \"Add Package\" | Card title |\n\n## Sensor Attributes\n\nEach tracked package creates a sensor with these attributes:\n\n- `label` — Package label\n- `carrier` — Carrier name (usps/ups/fedex/speedx)\n- `tracking_number` — Tracking number\n- `estimated_delivery` — Estimated delivery date (ISO format)\n- `last_updated` — Last successful API poll (ISO format)\n- `raw_status` — Raw status text from the carrier\n- `tracking_url` — Direct link to the carrier's tracking page\n- `events` — List of tracking events with timestamp, location, description, and status\n\n## Development / Testing\n\nFirst-time setup (installs uv, Python 3.12, and all dependencies):\n\n```bash\nmake setup\n```\n\nRun tests:\n\n```bash\nmake test           # HA integration tests\nmake test-scraper   # Scraper tests\nmake test-all       # Both\nmake coverage       # Tests with coverage\n```\n\nCI requires all tests to pass before merging.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolffruoff%2Fpackage_tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwolffruoff%2Fpackage_tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwolffruoff%2Fpackage_tracker/lists"}