Skill: joaoleitegmr/package-tracker (version 1.0.0)

--- name: package-tracker description: Track packages and shipments via the 17track API. Use when the user asks to track a package, check delivery status, add a tracking number, list tracked shipments, or get updates on deliveries. Supports 2000+ carriers worldwide with auto carrier detection and tracking URLs. --- # Package Tracker Track packages via the 17track universal API. Supports FedEx, UPS, DHL, CTT, China Post, Royal Mail, USPS, and 2000+ other carriers with automatic carrier detection. ## Setup Run once from the skill directory: ```bash cd /root/.openclaw/workspace/skills/package-tracker bash scripts/setup.sh ``` Then edit `scripts/.env` to add your API key: ``` SEVENTEEN_TRACK_API_KEY=your_key_here ``` Get a free key at https://admin.17track.net (100 registrations/month, unlimited status checks). ## Usage All commands run from the skill directory. Activate the venv first: ```bash cd /root/.openclaw/workspace/skills/package-tracker source scripts/venv/bin/activate ``` ### Add a Package ```bash python scripts/cli.py add "TRACKING_NUMBER" -d "Description of contents" ``` - Carrier is auto-detected from the tracking number format - Override with `-c "FedEx"` if needed - Uses 1 registration from monthly quota (100/month free) - Returns a tracking URL for the detected carrier ### Check for Updates ```bash python scripts/cli.py check ``` - Queries 17track for all active packages - Prints status changes and new tracking events - Outputs notifications to stdout for OpenClaw to relay via native messaging - gettrackinfo calls are free and unlimited ### List Packages ```bash python scripts/cli.py list # Active only python scripts/cli.py list --all # Include delivered/inactive ``` ### Package Details ```bash python scripts/cli.py details "TRACKING_NUMBER" ``` Shows full tracking history with all events, locations, and timestamps. ### Remove a Package ```bash python scripts/cli.py remove "TRACKING_NUMBER" ``` Deactivates tracking (does not delete history). ### Check API Quota ```bash python scripts/cli.py quota ``` Shows registrations used this month vs. the 100/month free limit. ## Cron Integration Set up periodic checks with cron or OpenClaw heartbeats. ### Using cron (every 3 hours) ```bash # Add to crontab: 0 */3 * * * cd /root/.openclaw/workspace/skills/package-tracker && scripts/venv/bin/python scripts/check_updates.py --quiet ``` ### Using OpenClaw heartbeat In your heartbeat logic, include: ```bash cd /root/.openclaw/workspace/skills/package-tracker source scripts/venv/bin/activate python scripts/check_updates.py ``` The check_updates.py script: - Checks all active packages for updates - Prints notifications to stdout for OpenClaw to relay - Exits 0 on success, 1 on error - Use `--quiet` to suppress output when there are no updates ## Notifications When updates are detected, the tracker outputs formatted notifications to stdout. OpenClaw reads this output and relays it via its native message tool — which works on Telegram, Signal, Discord, WhatsApp, or whatever channel the user has configured. ## Tracking URLs Every package gets a carrier-specific tracking URL: | Carrier | URL Pattern | |---------|------------| | FedEx | `fedex.com/fedextrack/?trknbr={tn}` | | UPS | `ups.com/track?tracknum={tn}` | | DHL | `dhl.com/en/express/tracking.html?AWB={tn}` | | CTT | `ctt.pt/.../objectSearch.jspx?objects={tn}` | | USPS | `tools.usps.com/go/TrackConfirmAction?tLabels={tn}` | | Fallback | `t.17track.net/en#nums={tn}` | The `get_tracking_url(tracking_number, carrier)` function in tracker.py generates these. ## Status Codes | Status | Emoji | Meaning | |--------|-------|---------| | pending | ⏳ | Just added, not yet checked | | Not Found | ❓ | 17track has no data yet | | In Transit | 🚚 | Package is moving | | Pick Up | 📬 | Ready for pickup | | Delivered | ✅ | Delivered (auto-deactivated) | | Undelivered | ⚠️ | Delivery attempt failed | | Expired | ⌛ | Tracking data expired | | Alert | 🚨 | Exception or issue | Delivered packages are automatically deactivated. ## Data Storage - **Database:** `scripts/data/tracker.db` (SQLite) - **Tables:** `packages`, `tracking_events`, `api_usage` - All data is local. Nothing is sent externally except 17track API calls. ## Environment Variables | Variable | Required | Description | |----------|----------|-------------| | `SEVENTEEN_TRACK_API_KEY` | Yes | 17track API key from admin.17track.net | ## Troubleshooting - **"API key not set"** — Edit `scripts/.env` and add your 17track key - **"Monthly limit reached"** — Free tier is 100 registrations/month. Wait or upgrade. - **No carrier detected** — Pass `-c "CarrierName"` when adding, or let 17track auto-detect (carrier code 0) ## References - `references/carriers.md` — Full list of supported carriers with patterns and URLs - `references/17track-api.md` — API endpoint reference, status codes, rate limits

path: scripts/requirements.txt
content: httpx
python-dotenv


Security scan verdicts — ClawScan: clean | static analysis:  | VirusTotal: clean | SkillSpector:  ()