track17 – OpenClaw Skill

---

name: track17 description: Track parcels via the 17TRACK API (local SQLite DB, polling + optional webhook ingestion) user-invocable: true metadata: {"clawdbot":{"emoji":"📦","requires":{"anyBins":["python3","python"],"env":["TRACK17_TOKEN"]},"primaryEnv":"TRACK17_TOKEN"}}

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):

python3 {baseDir}/scripts/track17.py init

2. Add a package (registers it with 17TRACK and stores it locally):

python3 {baseDir}/scripts/track17.py add "RR123456789CN" --label "AliExpress headphones"

If carrier auto-detection fails, specify a carrier code:

python3 {baseDir}/scripts/track17.py add "RR123456789CN" --carrier 3011 --label "..."

3. List tracked packages:

python3 {baseDir}/scripts/track17.py list

4. Poll for updates (recommended if you don't want webhooks):

python3 {baseDir}/scripts/track17.py sync

5. Show details for one package:

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

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

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:

python3 {baseDir}/scripts/track17.py process-inbox

Common actions

• Stop tracking:

python3 {baseDir}/scripts/track17.py stop 1

• Retrack a stopped parcel:

python3 {baseDir}/scripts/track17.py retrack 1

• Delete a parcel from local DB (does not delete at 17TRACK unless you also call delete-remote):

python3 {baseDir}/scripts/track17.py remove 1

• Show API quota:

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.

track17 (17TRACK) Clawdbot skill

This folder is a self-contained Clawdbot skill that lets your assistant track parcels using the 17TRACK Tracking API v2.2.

It includes:

• SKILL.md — the skill prompt/instructions Clawdbot loads.
• scripts/track17.py — a dependency-free Python CLI that:
  • stores packages in a local SQLite DB,
  • registers tracking numbers with 17TRACK,
  • polls status (sync),
  • ingests webhooks (ingest-webhook, process-inbox),
  • optionally runs an HTTP webhook receiver (webhook-server).

Where data is stored

By default (workspace-local):

• <workspace>/packages/track17/track17.sqlite3
• <workspace>/packages/track17/inbox/ (raw webhook payloads)

Where <workspace> is auto-detected as the parent directory of the nearest skills/ directory that contains this skill. So if the skill is installed at /clawd/skills/track17/, data will be stored at /clawd/packages/track17/.

Override with:

• TRACK17_DATA_DIR=/some/path (data will be stored directly in that directory)
• TRACK17_WORKSPACE_DIR=/some/workspace (data will be stored under /some/workspace/packages/track17/)

Configure the API token

This skill declares metadata.clawdbot.primaryEnv = TRACK17_TOKEN, so you can configure it in your Clawdbot config as:

{
  "skills": {
    "entries": {
      "track17": {
        "enabled": true,
        "apiKey": "YOUR_17TRACK_TOKEN"
      }
    }
  }
}

(Or set TRACK17_TOKEN in your shell/service env.)

Basic usage (manual)

python3 skills/track17/scripts/track17.py init
python3 skills/track17/scripts/track17.py add RR123456789CN --label "New headphones"
python3 skills/track17/scripts/track17.py list
python3 skills/track17/scripts/track17.py sync
python3 skills/track17/scripts/track17.py status 1 --refresh

Webhooks (optional)

If you prefer push updates:

1. Run the webhook receiver:

python3 skills/track17/scripts/track17.py webhook-server --bind 127.0.0.1 --port 8789

2. Configure the webhook URL in your 17TRACK dashboard.

3. Periodically process the inbox:

python3 skills/track17/scripts/track17.py process-inbox

If you set a webhook signing key, export it as:

export TRACK17_WEBHOOK_SECRET='...'

The tool will verify signatures when it has both the secret and a signature header.

Notes

• The code uses only the standard library (no pip install required).
• 17TRACK rate limits apply (docs mention 3 requests/second); the script batches up to 40 packages per API call.