> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tybritelabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracking

> Reference for the TrackingService class in the TLDP SDK.

The `TrackingService` class (accessed via `client.tracking`) answers the question "where is my parcel right now?". It offers a **public** lookup by tracking number (safe to call from a customer-facing page with a publishable key) and a **detailed events timeline** for shipments you own.

```typescript theme={null}
import { TLDP } from '@tybrite-labs/tldp-sdk';

// Public tracking can use a publishable key in the browser:
const publicClient = new TLDP({ apiKey: 'tybrite_pk_test_...' });

// Owner-level tracking needs a secret key on your backend:
const client = new TLDP({ apiKey: 'tybrite_sk_test_...' });
```

## trackShipment

Looks up a shipment by its **tracking number** and returns its current status plus, while the parcel is moving, the rider's live location.

> [!NOTE]
>
> This is a **public** endpoint — it works with a publishable key (`tybrite_pk_*`), so you can safely build a "track my order" page in the browser without exposing a secret key. It only reveals delivery-progress fields, not your full order data.

```typescript theme={null}
const status = await publicClient.tracking.trackShipment({
  trackingNumber: 'TLDP-7H3K9Q',
});

console.log(status.status);               // e.g. 'out_for_delivery'
console.log(status.estimated_delivery);
console.log(status.recipient.name, status.recipient.city);
console.log(status.courier?.name);        // null until a courier is assigned

// The scan history, oldest first.
for (const event of status.events) {
  console.log(event.timestamp, event.status, event.description, event.location);
}
```

**Returns**

| Field | Description |
| :- | :- |
| `tracking_number` | The number the shipment is tracked by. |
| `status` | The shipment's current state. |
| `estimated_delivery` | The projected delivery time, or `null` if none has been set. |
| `recipient` | `name` and `city` of the addressee — deliberately narrow, since this endpoint is public. |
| `courier` | `{ name }` of the carrier, or `null` before one is assigned. |
| `events` | Scan history, oldest first: `timestamp`, `status`, `description`, `location`. |

## getShipmentTracking

Returns the full chronological **events timeline** for a shipment you own — every status transition from booking through delivery. Use this for detailed audit views or to drive a stepper UI.

> [!NOTE]
>
> This is keyed on the shipment id rather than the tracking number, so it identifies a shipment in
> your own account and returns its complete record. Either key type can read it;
> [`trackShipment`](#trackshipment) remains the endpoint for a page shown to a recipient, since it
> needs only the tracking number and returns a narrower view.

```typescript theme={null}
const tracking = await client.tracking.getShipmentTracking({
  shipmentId: 'a1b2c3d4-0000-0000-0000-000000000000',
});

console.log(tracking.status);

// A timestamp per state, null for any the shipment has not reached.
console.log(tracking.full_timeline.picked_up_at);
console.log(tracking.full_timeline.delivered_at);
console.log(tracking.full_timeline.estimated_delivery);

for (const event of tracking.events ?? []) {
  console.log(event.created_at, event.event_type, event.description, event.location_text);
}
```

**Returns**

| Field | Description |
| :- | :- |
| `shipment_id` | The shipment queried. |
| `tracking_number` | The number the shipment is tracked by. |
| `status` | The shipment's current state. |
| `full_timeline` | One timestamp per state — `created_at`, `payment_confirmed_at`, `assigned_at`, `picked_up_at`, `in_transit_at`, `delivered_at` — plus `estimated_delivery`. A state not yet reached is `null`. |
| `events` | Every scan, oldest first, with `created_at`, `event_type`, `description`, `location_text`, `lat`, `lng` and `metadata`. |

The two views differ in shape as well as in what they expose: an event here carries
`created_at`/`event_type` and coordinates, where the public view flattens the same record to
`timestamp`/`status` and a text location.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.