ha-parcel-aggregator

KO | EN

gitlite — search

#nlp #svg #postgresql #database #generative-ai #animation #tailwindcss #editor #list #reactjs

ha-parcel-aggregator

(★ 9)

Roll up every ha-parcel-integrations carrier into one set of Home Assistant sensors and events

File Explorer

ZIP Download

- - bug_report.yml
  - config.yml
  - feature_request.yml
- - auto-assign.yml
  - release.yml
  - validate.yml
- suite.json
- - __init__.py
  - assist.py
  - calendar.py
  - config_flow.py
  - const.py
  - coordinator.py
  - diagnostics.py
  - icons.json
  - intent.py
  - llm.py
  - manifest.json
  - sensor.py
  - strings.json
- - add_delivery_to_calendar.yaml
  - announce_next_delivery_window.yaml
  - daily_morning_summary.yaml
  - notify_per_carrier.yaml
  - notify_specific_carrier_only.yaml
  - notify_when_any_at_pickup_point.yaml
  - notify_when_any_delivery_time_changes.yaml
  - notify_when_any_out_for_delivery.yaml
  - notify_when_any_outgoing_delivered.yaml
  - notify_when_any_parcel_registered.yaml
- - by_carrier_breakdown.yaml
  - next_delivery_card.yaml
  - unified_active_parcels_grid.yaml
- README.md
- __init__.py
- conftest.py
- test_assist.py
- test_calendar.py
- test_config_flow.py
- test_coordinator.py
- test_diagnostics.py
- test_event_reemit.py
- test_init.py
- test_intent.py
- test_llm.py
- test_repair_issue.py
- test_sensor.py
- test_translations.py
.gitignore
CLAUDE.md
hacs.json
LICENSE
pytest.ini
README.md
requirements-dev.txt
ruff.toml

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

# Project Badges

Release Visit
Downloads Visit
HACS Visit
License Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> 💬 Questions or feedback? Join the discussion on the [Home Assistant community](https://community.home-assistant.io/t/packages-postnl-dhl-nl-dpd-and-gls-parcel-integration/112433/).

A Home Assistant custom integration that rolls up parcel counts, next-delivery timestamps, and parcel-event notifications from every installed [ha-parcel-integrations](https://github.com/ha-parcel-integrations) carrier into a single set of sensors and a single unified event stream.

## Contents

- [Use cases](#use-cases)
- [How it works](#how-it-works)
- [Supported sources](#supported-sources)
- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
- [Options](#options)
- [Removal](#removal)
- [Sensors](#sensors)
- [Parcel status reference](#parcel-status-reference)
- [Events](#events)
- [Assist / voice support](#assist--voice-support)
- [Examples](#examples)
- [Known limitations](#known-limitations)
- [Disclaimer](#disclaimer)
- [Contributing](#contributing)
- [License](#license)

## Use cases

- A single dashboard card that shows how many parcels you expect today across every carrier without juggling per-carrier sensors.
- Carrier-agnostic automations — write one trigger like *"when any parcel is out for delivery"* instead of three per-carrier copies.
- Automations like *"announce when a parcel is awaiting pickup at a service point"* or *"remind me an hour before the earliest delivery"* that you write once and they cover every carrier.
- A unified parcel list you can iterate over in templates or custom cards.

## How it works

The aggregator does **not** talk to any carrier API itself. It reads the sensors and events the per-carrier integrations already publish and exposes:

- Summed count sensors with a per-carrier breakdown on the attributes
- A unified `parcel_aggregator_parcel_*` event stream so one automation can react to any carrier

Carriers you have not installed are silently skipped. If you add a carrier integration later, the aggregator picks up its sensors automatically — no reload needed.

## Supported sources

The aggregator reads every carrier integration in the
[**ha-parcel-integrations**](https://github.com/ha-parcel-integrations) family —
see the [carrier list](https://ha-parcel-integrations.github.io/carriers/) for the
current, authoritative list. Any supported carrier you have installed is picked up
automatically; carriers you have not installed are silently skipped. New carriers
work without an update here.

## Requirements

- At least one of the supported carrier integrations installed and authenticated

## Installation

### HACS (recommended)

1. Open HACS → **Integrations** → ⋮ → **Custom repositories**
2. Add this repository URL and select category **Integration**
3. Search for **Parcel Aggregator** and install it
4. Restart Home Assistant

### Manual

1. Copy the `parcel_aggregator` folder into your `config/custom_components/` directory
2. Restart Home Assistant

## Configuration

1. Go to **Settings → Devices & Services → Add Integration**
2. Search for **Parcel Aggregator**
3. The entry is created immediately — no credentials needed

The aggregator discovers source entities at setup time and keeps watching the entity registry, so carrier integrations you add or remove later are picked up automatically.

## Options

This integration has no configurable options. It auto-discovers carrier source sensors (also when a carrier is installed later) and listens for state-change events from them.

## Removal

Standard HA removal applies: **Settings → Devices & Services → Parcel Aggregator → ⋮ → Delete**. No external cleanup is needed; deleting the config entry stops the state-change subscriptions and the event re-emit. The per-carrier integrations are not affected.

## Sensors

| Entity | Description |
|--------|-------------|
| `sensor.parcel_aggregator_incoming_parcels` | Sum of active incoming parcels across all carriers; merged parcel list on the `parcels` attribute |
| `sensor.parcel_aggregator_outgoing_parcels` | Sum of active outgoing parcels across all carriers; merged list on the `parcels` attribute |
| `sensor.parcel_aggregator_delivered_parcels` | Sum of recently delivered incoming parcels across all carriers (uses each carrier's own filter window); merged list on `parcels` |
| `sensor.parcel_aggregator_outgoing_delivered_parcels` | Sum of recently delivered outgoing parcels across all carriers; merged list on `parcels` |
| `sensor.parcel_aggregator_awaiting_pickup` | Sum of active incoming parcels destined for a pickup point (ServicePoint / PostNL Point / ParcelShop); merged list on `parcels` |
| `sensor.parcel_aggregator_next_delivery` | Earliest expected delivery datetime across all carriers; the matching parcel on the `parcel` attribute |

Every sensor exposes a `by_carrier` attribute with the per-carrier breakdown — handy for dashboard cards like "5 incoming (2 DHL · 3 PostNL)".

### Unified parcel shape

The `parcels` attribute on each summary sensor contains every parcel from every installed carrier in the carrier-agnostic shape:

| Key | Type | Meaning |
|---|---|---|
| `carrier` | string | The source carrier's display name (e.g. `"DHL"`, `"PostNL"`, …) — one value per installed carrier |
| `barcode` | string | Parcel tracking number |
| `sender` | string \| null | Sender name (e.g. webshop) |
| `receiver` | string \| null | Recipient name |
| `status` | `ParcelStatus` | Canonical status — see the [status reference](#parcel-status-reference) |
| `raw_status` | string \| null | Original carrier-specific status string |
| `delivered` | bool | Whether the parcel has been delivered |
| `delivered_at` | ISO 8601 \| null | Delivery moment, if known |
| `planned_from` | ISO 8601 \| null | Expected delivery window start |
| `planned_to` | ISO 8601 \| null | Expected delivery window end |
| `pickup` | bool | Destined for a pickup point rather than a home address |
| `pickup_point` | string \| null | ServicePoint / Point / ParcelShop name when `pickup` is true |
| `url` | string \| null | Deep link to the parcel's tracking page |
| `weight` | float \| null | Parcel weight in kilograms. May be `null` depending on what the carrier exposes. |
| `dimensions` | dict \| null | Parcel dimensions in centimeters: `{length, width, height, text}` where `text` is a pre-formatted `"L x W x H cm"` string. May be `null` depending on the carrier. |
| `history` | list \| null | Ordered status timeline (oldest → newest), each entry `{timestamp, status, raw_status}`. `null` unless the source carrier integration has its **Parcel history** option enabled — it is opt-in and off by default on each carrier. |

The carrier-specific `raw` payload is omitted to keep attribute size small. Open the per-carrier sensor if you need the original payload.

## Parcel status reference

`status` on every parcel is one of the canonical `ParcelStatus` values below. Use these in your automations rather than carrier-specific raw strings — the raw value stays available on `raw_status` for power users.

| `status` | Meaning |
|---|---|
| `registered` | Carrier knows about the label but the parcel is not yet in transit |
| `in_transit` | Picked up; somewhere in the carrier's network |
| `out_for_delivery` | On the delivery vehicle today |
| `at_pickup_point` | Arrived at the chosen ServicePoint / PostNL Point / ParcelShop, ready to be collected |
| `delivered` | Handed over to the recipient, mailbox, neighbour, or picked up |
| `returning` | Failed delivery, on the way back to the sender |
| `problem` | Carrier reports an exception, intervention, or other issue |
| `unknown` | Raw status/category the carrier integration has not mapped yet |

Each carrier has its own raw-status mapping — see the per-carrier READMEs.

## Events

Unified events on the HA event bus let one automation react to changes from any carrier.

| Event | When | Payload |
|---|---|---|
| `parcel_aggregator_parcel_registered` | A carrier announces a new parcel | The full parcel dict (see the table above) |
| `parcel_aggregator_parcel_status_changed` | A known parcel's `status` value changes, except the final hop to delivered | Same payload plus `old_status` and `new_status` |
| `parcel_aggregator_parcel_delivered` | An incoming parcel is delivered | The full parcel dict |
| `parcel_aggregator_parcel_delivery_time_changed` | A known parcel's expected delivery time changes to a new value | Same payload plus `old_planned_from`, `new_planned_from`, `old_planned_to`, `new_planned_to` |
| `parcel_aggregator_outgoing_parcel_status_changed` | A known **outgoing** parcel (something you sent) changes status, except the final hop to delivered | Same payload plus `old_status` and `new_status` |
| `parcel_aggregator_outgoing_parcel_delivered` | An outgoing parcel reaches the recipient | The full parcel dict |

See [`examples/automations/`](examples/automations/) for ready-to-paste carrier-agnostic event automations.

## Assist / voice support

Asking Assist "which packages do I receive today" reads back the bucket sensor's bare *state* ("You will receive 1 package today"). A follow-up like "what is it?" used to get a generic non-answer, because the carrier/sender/status/expected-time details live in the `parcels` attribute, which Assist doesn't read out on its own. Parcel Aggregator ships a dedicated `ParcelAggregatorGetDetails` intent that answers with the full breakdown instead, e.g. *"You have 1 incoming parcel: a PostNL parcel from Bol.com, expected today between 14:00 and 16:00."* It covers the `incoming`, `delivered` and `awaiting_pickup` buckets, and only answers for a bucket whose sensor is exposed to the calling assistant.

`incoming` holds every active parcel, not just today's — a parcel arriving next week shows up here too. Rather than filtering (which would silently drop parcels that don't have a known ETA yet), each parcel's timing is always spelled out relative to today: *"expected today between 14:00 and 16:00"*, *"expected tomorrow around 09:00"*, or *"expected on Thursday around 10:00"* for anything further out.

**Languages**: 30 in total — see [`assist_strings/`](custom_components/parcel_aggregator/assist_strings/) for the full list, matching every language already used somewhere in the [ha-parcel-integrations](https://github.com/ha-parcel-integrations) suite plus the languages of Shopee Xpress's markets. This is a private file format rather than Home Assistant's own `strings.json`/`translations/` system, since hassfest validates those against a fixed schema that has no room for a custom "assist" category. Adding another language is a translation-file contribution, not a code change. Beyond en/nl these are machine-translated starting points, not reviewed by native speakers — corrections welcome.

How you trigger it depends on your Assist agent:

- **LLM-based Assist agent** (OpenAI, Google Generative AI, a local LLM, …): nothing to configure. The integration registers an LLM tool automatically once a bucket sensor is exposed, so a natural follow-up question like "what is it?" just works. Requires Home Assistant 2026.8 or newer — on older cores this tool is silently unavailable, with no impact on the rest of the integration.
- **Built-in (free, local) Assist agent**: this agent matches fixed sentence patterns, which a custom integration cannot register on your behalf. Copy [`examples/custom_sentences/en/parcel_aggregator.yaml`](examples/custom_sentences/en/parcel_aggregator.yaml) (or the [Dutch version](examples/custom_sentences/nl/parcel_aggregator.yaml)) into `config/custom_sentences/<language>/`, then restart Home Assistant or reload custom sentences from **Developer Tools → YAML**. Feel free to add your own phrasings — the shipped list is a starting point, not exhaustive.

## Examples

Ready-to-paste carrier-agnostic automations live in [`examples/`](examples/).

### Community Lovelace cards

Third-party cards that work with these sensors:

- [jonisnet/hki-parcels-card](https://github.com/jonisnet/hki-parcels-card)
- [klaptafel/ha-package-tracker-card](https://github.com/klaptafel/ha-package-tracker-card)

## Known limitations

- The `next_delivery` timestamp is only as precise as the underlying carrier exposes. DPD gives a day window (midnight to midnight) until Follow My Parcel fires shortly before delivery — then it narrows to an hour window. Use it for "today/tomorrow" alerts rather than counting on precise hour windows being available all day.
- The `awaiting_pickup` sensor counts every parcel destined for a pickup point, including ones that are still en route. DHL exposes a distinct `at_pickup_point` status on the parcel dict for parcels that have *actually arrived* at the pickup point — DPD's API does not surface this signal yet. The sensor stays on the lowest-common-denominator semantics for now.

## Disclaimer

This is an independent, community-built project with no affiliation, endorsement, or connection to any parcel carrier or its subsidiaries.

## Contributing

Pull requests and issues are welcome. Please open an issue before submitting a large change.

## License

MIT

ha-parcel-aggregator

Owner Repos

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

ha-parcel-aggregator

Owner Repos

File Explorer

# Use via CDN

# Project Badges

Was this content helpful?

Recent Feedback

Download README