UnityClaw Global Express Tracking
Query one shipment and save the complete service response as express-tracking.json.
Agent Workflow
1. Collect tracking input
Require one tracking number. Accept an optional recipient mobile number or suffix when the carrier requires it. Preserve letters, numbers, and punctuation supplied in the tracking number; trim surrounding whitespace without guessing a carrier or rewriting the identifier.
2. Execute the query
Run scripts/generate.js with --json and an explicit --output-dir. Quote the tracking number and mobile value. Use canonical --express-no; legacy --expressNo remains accepted.
Query once and allow the CLI to retry transient failures. Do not submit duplicate concurrent requests for the same shipment.
3. Preserve returned status
Use data as the raw service response. Preserve express, status, last, detail, updated, and any extra returned fields. Do not map status values to a different status system, infer a carrier from the number, or invent missing events.
Tracking information is a time-dependent snapshot. A missing update does not prove the parcel is lost, and an arrival scan does not necessarily mean delivery to the recipient.
4. Validate and deliver
Accept completion only when success is true, the returned object has at least one populated field, and resultPath points to a non-empty express-tracking.json. Inspect warnings when status or event details are missing.
Present the carrier/channel, current service status, latest update, and update time when available. Include the local JSON file for the complete response.
5. Handle failures
Retry only when error.retryable is true. If a carrier requires a mobile value, request it after the service indicates that requirement. For an unknown number or empty history, report the returned state instead of manufacturing progress.
Configuration
Set the fixed UNITYCLAW_KEY environment variable. The runtime installation declaration installs @unityclaw/sdk; for manual execution, run npm install @unityclaw/sdk if needed.
Usage
node scripts/generate.js --express-no "YT123456789CN"
node scripts/generate.js --express-no "SF1234567890" --mobile "1234" --json --output-dir ./tasks
Parameters
| Parameter | Short | Required | Default | Description |
|---|---|---|---|---|
--express-no |
-e |
Yes | - | Tracking number |
--expressNo |
- | No | - | Legacy alias for --express-no |
--mobile |
-m |
No | - | Recipient mobile number or carrier-required suffix |
--output-dir |
- | No | ./tasks |
Task output directory, resolved absolutely |
--timeout |
- | No | 900000 |
Timeout from 1,000 to 3,600,000 milliseconds |
--retries |
- | No | 1 |
Transient retry count from 0 to 3 |
--json |
- | No | false |
Emit one machine-readable JSON object |
--help |
-h |
No | - | Show help |
Known Fields
| Raw key | Meaning |
|---|---|
express |
Carrier or delivery channel returned by the service |
status |
Current raw shipment status |
last |
Latest tracking update |
detail |
Tracking details or history |
updated |
Service-provided update time |
Extra fields are preserved.
Output Contract
With --json, success contains task metadata, resultPath, resultBytes, expressNo, raw data, ordered fields, and warnings. Failure contains a stable error code, message, retryability, attempts, and available task information.
Resource Index
- Run
scripts/generate.jsfor global shipment tracking.
