https://github.com/anatelli10/ts-shipment-tracking

📦 Unified shipment tracking data from FedEx, UPS, and USPS APIs.
https://github.com/anatelli10/ts-shipment-tracking

fedex package-tracking shipment-tracking ups usps

Last synced: about 2 months ago
JSON representation

📦 Unified shipment tracking data from FedEx, UPS, and USPS APIs.

• Host: GitHub
• URL: https://github.com/anatelli10/ts-shipment-tracking
• Owner: anatelli10
• License: mit
• Created: 2021-08-11T22:21:21.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2024-10-02T23:34:03.000Z (3 months ago)
• Last Synced: 2024-10-02T23:40:09.979Z (3 months ago)
• Topics: fedex, package-tracking, shipment-tracking, ups, usps
• Language: TypeScript
• Homepage:
• Size: 192 KB
• Stars: 2
• Watchers: 1
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        


  
ts-shipment-tracking


  


    Unified shipment tracking data from FedEx, UPS, and USPS APIs.

  


## API Versions

_FedEx:_ Track API 1.0.0 (https://apis.fedex.com/track/v1)

_UPS:_ Track API v1 (https://onlinetools.ups.com/api/track/v1)

_USPS:_ Package Tracking and Notification 3.2.1 (https://api.usps.com/tracking/v3/tracking)

## Installation

```sh

$ npm install ts-shipment-tracking

```

## Usage

Courier API credentials are stored using dotenv. If you do not have dotenv installed:

```sh

$ npm install dotenv

```

Copy the contents of [.env.template](.env.template) into your `.env` file and fill it out.

Example input:

```ts

import "dotenv/config";

import { track, TrackingInfo } from "ts-shipment-tracking";

(async () => {

  // With automatic courier detection

  try {

    const tragnostic: TrackingInfo = await track("");

    console.log(tragnostic);

  } catch (err) {

    console.log((err as Error).message);

  }

  // With explicitly specified courier

  try {

    const tracking: TrackingInfo = await track(

      "",

      // Supports autocomplete!

      { courierCode: "ups" }

    );

    console.log(tracking);

  } catch (err) {

    console.log((err as Error).message);

  }

})();

```

Example output:

```jsonc

{

  events: [

    {

      status: 'IN_TRANSIT',

      label: 'Arrived at FedEx location',

      location: 'LEBANON TN US 37090',

      time: 1616823540000

    },

    // ...

  ],

  estimatedDeliveryTime: 1616996340000

}

```

All statuses:

```ts

export enum TrackingStatus {

  LABEL_CREATED = "LABEL_CREATED",

  IN_TRANSIT = "IN_TRANSIT",

  OUT_FOR_DELIVERY = "OUT_FOR_DELIVERY",

  DELIVERY_ATTEMPTED = "DELIVERY_ATTEMPTED",

  RETURNED_TO_SENDER = "RETURNED_TO_SENDER",

  EXCEPTION = "EXCEPTION",

  DELIVERED = "DELIVERED",

}

```

API environment is determined by `process.env.NODE_ENV` ("development" or "production"). It can be overridden like so: 

```ts

await track("", { env: myProductionFlag ? "production" : "development" });

```

## Acknowledgements

Thanks to @rjbrooksjr's [TS Tracking Number](https://github.com/rjbrooksjr/ts-tracking-number) module being used for tracking number validation and courier detection.

Thanks to @hautelook's [Shipment Tracking](https://github.com/hautelook/shipment-tracking) repo used as a reference for some gaps in courier status codes as well as inspiration for architecture.