17track package tracking

Track parcels via the 17TRACK API (local SQLite DB, polling + optional webhook ingestion)

Security Scan

The skill appears internally consistent: it implements a 17TRACK client that reasonably needs the declared TRACK17_TOKEN and local filesystem access for a SQLite DB and inbox; nothing requested or instructed is disproportionate to parcel-tracking.

Purpose & Capability

Name/description, required env vars, and included code align: the tool talks to 17TRACK APIs, stores data in a workspace-local SQLite DB, and optionally ingests webhooks. No unrelated credentials, binaries, or installs are requested.

Instruction Scope

SKILL.md and the CLI instruct the agent to initialise a local DB, register tracking numbers, poll (sync) and optionally run or ingest webhooks. The skill auto-detects a workspace by walking the script's parent directories (or using TRACK17_WORKSPACE_DIR/CLAWDBOT_WORKSPACE_DIR) and will read/write under <workspace>/packages/track17/. This file I/O and optional webhook-server behavior is within the stated scope but worth noting: running the server or processing inbox files gives the skill permission to accept and store external payloads and to write into the workspace directory.

Install Mechanism

There is no install spec and the included Python script uses only the standard library (no external downloads or package installs). That minimizes install-time risk; the code is included with the skill rather than fetched from an arbitrary URL.

Credentials

Only TRACK17_TOKEN is required (primaryEnv). Optional envs (TRACK17_WEBHOOK_SECRET, TRACK17_DATA_DIR, TRACK17_WORKSPACE_DIR, TRACK17_LANG) are plausible and relevant. No unrelated secrets or large sets of credentials are requested.

Persistence & Privilege

The skill is not marked always:true, does not request to modify other skills, and writes only to its own workspace-local data dir by default. It can be invoked autonomously (platform default), which is expected for skills, but that is not combined with elevated platform privileges.

Assessment

This skill is coherent with its purpose, but review and small precautions before enabling are recommended: - Confirm TRACK17_TOKEN is a token you intend to give to this skill and use a token with minimal scope if possible. - Be aware the script writes a SQLite DB and raw webhook payloads under <workspace>/packages/track17/ (or TRACK17_DATA_DIR if set). If you prefer a specific location, set TRACK17_DATA_DIR or TRACK17_WORKSPACE_DIR before first use. - If you enable webhooks: prefer to run the webhook-server bound to localhost behind a reverse proxy or use a tunnelling service (as the README suggests). Do not run the webhook-server publicly without configuring TRACK17_WEBHOOK_SECRET and verifying signatures. - Inspect scripts/track17.py yourself (it’s included) before enabling; because it is executed locally, review ensures it matches your risk tolerance. - Run in a restricted environment or sandbox if you want to limit where files can be written. If you don’t need push webhooks, use the polling (sync) workflow to minimize exposed surface. If you want extra assurance, ask for a short summary of the script's network endpoints and file paths and a confirmation that it will not contact any hosts other than 17track/res.17track.net.

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.