track17

# track17 (17TRACK parcel tracking) This skill lets Clawdbot keep a local list of your parcels, track their state via the **17TRACK Tracking API v2.2**, and summarise changes. It stores everything in a small **SQLite DB** under your **workspace** (by default: `<workspace>/packages/track17/track17.sqlite3`). `<workspace>` is auto-detected as the parent directory of the nearest `skills/` directory that contains this skill. For example, if you install it at `/clawd/skills/track17/`, data will be stored at `/clawd/packages/track17/`. ## Requirements - `TRACK17_TOKEN` must be set (17TRACK API token; used as the `17token` header). - Python (`python3` preferred). Optional: - `TRACK17_WEBHOOK_SECRET` if you want to verify webhook signatures. - `TRACK17_DATA_DIR` to override where the DB/inbox live. - `TRACK17_WORKSPACE_DIR` to override what this tool considers the workspace directory. ## Quick start 1) Initialise storage (safe to run multiple times): ```bash python3 {baseDir}/scripts/track17.py init ``` 2) Add a package (registers it with 17TRACK and stores it locally): ```bash python3 {baseDir}/scripts/track17.py add "RR123456789CN" --label "AliExpress headphones" ``` If carrier auto-detection fails, specify a carrier code: ```bash python3 {baseDir}/scripts/track17.py add "RR123456789CN" --carrier 3011 --label "..." ``` 3) List tracked packages: ```bash python3 {baseDir}/scripts/track17.py list ``` 4) Poll for updates (recommended if you don't want webhooks): ```bash python3 {baseDir}/scripts/track17.py sync ``` 5) Show details for one package: ```bash python3 {baseDir}/scripts/track17.py status 1 # or python3 {baseDir}/scripts/track17.py status "RR123456789CN" ``` ## Webhooks (optional) 17TRACK can push updates to a webhook URL. This skill supports webhook ingestion in two ways: ### A) Run the included webhook server ```bash python3 {baseDir}/scripts/track17.py webhook-server --bind 127.0.0.1 --port 8789 ``` Then point 17TRACK's webhook URL at that server (ideally via a reverse proxy or Tailscale Funnel). ### B) Ingest webhook payloads from stdin/file ```bash cat payload.json | python3 {baseDir}/scripts/track17.py ingest-webhook # or python3 {baseDir}/scripts/track17.py ingest-webhook --file payload.json ``` If you saved webhook deliveries to the inbox directory, process them: ```bash python3 {baseDir}/scripts/track17.py process-inbox ``` ## Common actions - Stop tracking: ```bash python3 {baseDir}/scripts/track17.py stop 1 ``` - Retrack a stopped parcel: ```bash python3 {baseDir}/scripts/track17.py retrack 1 ``` - Delete a parcel from local DB (does not delete at 17TRACK unless you also call `delete-remote`): ```bash python3 {baseDir}/scripts/track17.py remove 1 ``` - Show API quota: ```bash python3 {baseDir}/scripts/track17.py quota ``` ## Operating guidance for the agent - Prefer **sync** (polling) for simplicity unless the user explicitly wants webhooks. - After adding a package, run `status` once to confirm a valid carrier/status was returned. - When summarising, prioritise: - delivered/out for delivery - exception/failed delivery - customs holds - carrier handoffs - Never echo `TRACK17_TOKEN` or `TRACK17_WEBHOOK_SECRET`.