{"skill":{"slug":"track17","displayName":"17track package tracking","summary":"Track parcels via the 17TRACK API (local SQLite DB, polling + optional webhook ingestion)","description":"---\nname: track17\ndescription: Track parcels via the 17TRACK API (local SQLite DB, polling + optional webhook ingestion)\nuser-invocable: true\nmetadata: {\"clawdbot\":{\"emoji\":\"📦\",\"requires\":{\"anyBins\":[\"python3\",\"python\"],\"env\":[\"TRACK17_TOKEN\"]},\"primaryEnv\":\"TRACK17_TOKEN\"}}\n---\n\n# track17 (17TRACK parcel tracking)\n\nThis skill lets Clawdbot keep a local list of your parcels, track their state via the **17TRACK Tracking API v2.2**, and summarise changes.\n\nIt stores everything in a small **SQLite DB** under your **workspace** (by default: `<workspace>/packages/track17/track17.sqlite3`).\n\n`<workspace>` is auto-detected as the parent directory of the nearest `skills/` directory that contains this skill.\nFor example, if you install it at `/clawd/skills/track17/`, data will be stored at `/clawd/packages/track17/`.\n\n## Requirements\n\n- `TRACK17_TOKEN` must be set (17TRACK API token; used as the `17token` header).\n- Python (`python3` preferred).\n\nOptional:\n- `TRACK17_WEBHOOK_SECRET` if you want to verify webhook signatures.\n- `TRACK17_DATA_DIR` to override where the DB/inbox live.\n- `TRACK17_WORKSPACE_DIR` to override what this tool considers the workspace directory.\n\n## Quick start\n\n1) Initialise storage (safe to run multiple times):\n\n```bash\npython3 {baseDir}/scripts/track17.py init\n```\n\n2) Add a package (registers it with 17TRACK and stores it locally):\n\n```bash\npython3 {baseDir}/scripts/track17.py add \"RR123456789CN\" --label \"AliExpress headphones\"\n```\n\nIf carrier auto-detection fails, specify a carrier code:\n\n```bash\npython3 {baseDir}/scripts/track17.py add \"RR123456789CN\" --carrier 3011 --label \"...\"\n```\n\n3) List tracked packages:\n\n```bash\npython3 {baseDir}/scripts/track17.py list\n```\n\n4) Poll for updates (recommended if you don't want webhooks):\n\n```bash\npython3 {baseDir}/scripts/track17.py sync\n```\n\n5) Show details for one package:\n\n```bash\npython3 {baseDir}/scripts/track17.py status 1\n# or\npython3 {baseDir}/scripts/track17.py status \"RR123456789CN\"\n```\n\n## Webhooks (optional)\n\n17TRACK can push updates to a webhook URL. This skill supports webhook ingestion in two ways:\n\n### A) Run the included webhook server\n\n```bash\npython3 {baseDir}/scripts/track17.py webhook-server --bind 127.0.0.1 --port 8789\n```\n\nThen point 17TRACK's webhook URL at that server (ideally via a reverse proxy or Tailscale Funnel).\n\n### B) Ingest webhook payloads from stdin/file\n\n```bash\ncat payload.json | python3 {baseDir}/scripts/track17.py ingest-webhook\n# or\npython3 {baseDir}/scripts/track17.py ingest-webhook --file payload.json\n```\n\nIf you saved webhook deliveries to the inbox directory, process them:\n\n```bash\npython3 {baseDir}/scripts/track17.py process-inbox\n```\n\n## Common actions\n\n- Stop tracking:\n\n```bash\npython3 {baseDir}/scripts/track17.py stop 1\n```\n\n- Retrack a stopped parcel:\n\n```bash\npython3 {baseDir}/scripts/track17.py retrack 1\n```\n\n- Delete a parcel from local DB (does not delete at 17TRACK unless you also call `delete-remote`):\n\n```bash\npython3 {baseDir}/scripts/track17.py remove 1\n```\n\n- Show API quota:\n\n```bash\npython3 {baseDir}/scripts/track17.py quota\n```\n\n## Operating guidance for the agent\n\n- Prefer **sync** (polling) for simplicity unless the user explicitly wants webhooks.\n- After adding a package, run `status` once to confirm a valid carrier/status was returned.\n- When summarising, prioritise:\n  - delivered/out for delivery\n  - exception/failed delivery\n  - customs holds\n  - carrier handoffs\n- Never echo `TRACK17_TOKEN` or `TRACK17_WEBHOOK_SECRET`.\n","topics":["Sqlite","Webhook"],"tags":{"latest":"0.1.0"},"stats":{"comments":0,"downloads":2515,"installsAllTime":95,"installsCurrent":8,"stars":4,"versions":1},"createdAt":1768655113826,"updatedAt":1778485733200},"latestVersion":{"version":"0.1.0","createdAt":1768655113826,"changelog":"Initial release of track17: parcel tracking via 17TRACK API with local database.\n\n- Track packages and their status via the 17TRACK API.\n- Stores all package data locally in a SQLite database within the workspace.\n- Supports both periodic polling (sync) and optional webhook ingestion for updates.\n- CLI for adding, listing, syncing, and managing parcels.\n- Optional webhook server and ingestion utilities included.\n- API credentials required via environment variables; flexible data directory configuration.","license":null},"metadata":{"setup":[{"key":"TRACK17_TOKEN","required":true}],"os":null,"systems":null},"owner":{"handle":"tristanmanchester","userId":"s17c3xv8wvvzzbj84z9vcj498n83gnkp","displayName":"Tristan Manchester","image":"https://avatars.githubusercontent.com/u/108270628?v=4"},"moderation":null}