All plugins

parcel-deliveries

Track package deliveries with the Parcel app (parcelapp.net). List what's on the way, add tracking numbers and look up carrier codes, with a built-in guard for Parcel's strict rate limits. Disclosure — sends tracking numbers, descriptions and optional postcode/order email to api.parcel.app (Parcel Premium API key); the model can add deliveries to the user's Parcel account (add-only, capped at 20/day); caches delivery lists in plugin-data.

promptclickrunToolsv0.1.0Updated 1 month ago

About

Track package deliveries with the Parcel app (parcelapp.net). List what's on the way, add tracking numbers and look up carrier codes, with a built-in guard for Parcel's strict rate limits. Disclosure — sends tracking numbers, descriptions and optional postcode/order email to api.parcel.app (Parcel Premium API key); the model can add deliveries to the user's Parcel account (add-only, capped at 20/day); caches delivery lists in plugin-data.

Parcel for Hermes

Track package deliveries from Parcel in Hermes Agent. Ask "what's arriving today?" or "track this UPS number", and Hermes reads from or adds to your Parcel account.

Unofficial. It isn't affiliated with or endorsed by Parcel. It uses Parcel's public external API.

What you get

ToolWhat it does
parcel_deliveriesLists active (or recent) deliveries: status, expected date and latest tracking event. It can filter to one tracking number and include the full event history.
parcel_add_deliveryAdds a tracking number to Parcel.
parcel_carriersLooks up Parcel carrier codes by name (for example "amazon" gives amzlus). Needs no key and spends no requests.

You also get a /parcel slash command (/parcel recent includes delivered packages) and a bundled skill, parcel-deliveries:deliveries, that tells the agent how to answer delivery questions.

Requirements

  • Parcel Premium. The API is a Premium feature.
  • An API key from web.parcelapp.net, saved as PARCEL_API_KEY. hermes plugins install prompts for it.
  • Hermes 0.21.2 or later. No Python dependencies; it uses only the standard library.

Install

hermes plugins install promptclickrun/hermes-parcel
hermes plugins enable parcel-deliveries

The tools show up in your next session.

Rate limits, and how the plugin respects them

Parcel's limits are strict: 20 reads an hour and 20 adds a day, and failed adds count too. Its deliveries endpoint also returns Parcel's server-side cache, so polling it harder never gets you fresher tracking.

To stay inside those limits, the plugin:

  • caches reads for 10 minutes, so the agent re-asking in one conversation costs nothing;
  • keeps a local count and refuses the 21st request instead of letting Parcel reject it;
  • when the limit is used up or Parcel is down, returns the last list marked stale;
  • checks adds locally before sending: known carrier code, postcode or email where the carrier needs one, a sane tracking number, and not already tracked. A typo doesn't burn a daily add.

The local count only covers this Hermes host. Other apps using the same key (Home Assistant, for example) share Parcel's limit.

Don't schedule frequent polling. A daily "what's arriving" cron job is fine. One every five minutes will hit the hourly limit.

Privacy and behaviour disclosure

  • Network: it calls https://api.parcel.app/external/ only: deliveries/ (GET), add-delivery/ (POST), and supported_carriers.json (GET, sent without your key). Redirects are refused so the key can't be forwarded anywhere else.
  • Credentials: it reads PARCEL_API_KEY through Hermes' secret lookup. It never writes, logs or returns the key.
  • Stored data: <HERMES_HOME>/plugin-data/parcel-deliveries/state.json (mode 0600) holds the last delivery lists (descriptions, tracking numbers, events), the carrier list, and request timestamps for the rate count. Delete the file at any time to clear it.
  • Writes to your Parcel account happen only through parcel_add_delivery. There's no edit or delete; Parcel's API doesn't offer them.
  • No shell commands, no background processes, no telemetry, no self-updating.

Development

python -m unittest discover -s tests
hermes plugins validate . --install-deps
hermes plugins doctor . --ci

The tests use a fake transport and never touch the network.

License

Apache-2.0

README from the reviewed commit 9641b40; it updates when the author re-pins.

More by promptclickrun

2 plugins by promptclickrun in the catalog.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section