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...

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

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

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

## Basic usage (manual)

```bash
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:

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