Add trackByTrackingNumber method (v0.5.0)

.github/workflows/test.yml

@@ -30,6 +30,8 @@ jobs:
         FEDEX_API_KEY: ${{ secrets.FEDEX_API_KEY }}
         FEDEX_SECRET_KEY: ${{ secrets.FEDEX_SECRET_KEY }}
         FEDEX_SMART_POST_HUB_ID: ${{ secrets.FEDEX_SMART_POST_HUB_ID }}
+        FEDEX_TRACK_API_KEY: ${{ secrets.FEDEX_TRACK_API_KEY }}
+        FEDEX_TRACK_SECRET_KEY: ${{ secrets.FEDEX_TRACK_SECRET_KEY }}
         FEDEX_URL: ${{ secrets.FEDEX_URL }}
       run: |
         node --test --test-force-exit --experimental-test-coverage --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=lcov.info

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.5.0
+
+- Add `trackByTrackingNumber(trackRequest, options)` — calls the FedEx Track API (`POST /track/v1/trackingnumbers`). Same passthrough pattern as the other methods: caller supplies the full request body, the package forwards it verbatim. Supports `options.customer_transaction_id` and `options.timeout`. Non-2xx responses and 200-with-`errors[]` envelopes both reject with `HttpError`.
+
 ## 0.4.0
 
 - Add `groundEndOfDayClose(closeRequest, options)` — calls the FedEx Ground End of Day Close API (`PUT /ship/v1/endofday/`). Same passthrough pattern as the other methods: caller supplies the full request body, the package forwards it verbatim. Supports `options.customer_transaction_id` and `options.timeout`. Non-2xx responses and 200-with-`errors[]` envelopes both reject with `HttpError`.

README.md

@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@stores.com/fedex)](https://www.npmjs.com/package/@stores.com/fedex)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
-FedEx REST API client for Address Validation, Ground End of Day Close, OAuth tokens, Rates and Transit Times, Shipment Cancellation, and Shipment Creation.
+FedEx REST API client for Address Validation, Ground End of Day Close, OAuth tokens, Rates and Transit Times, Shipment Cancellation, Shipment Creation, and Tracking.
 
 ## Installation
 
@@ -181,6 +181,30 @@ console.log(detail.totalNetCharge);
 
 Non-2xx responses reject with `HttpError`. If FedEx returns a 200 response carrying a non-empty `errors[]` envelope, the call rejects with an `HttpError` whose message is every `message` joined by `; ` and whose `.json` is the full response body (with the `errors[]` array, codes, and any other fields).
 
+### trackByTrackingNumber(trackRequest, options)
+
+Track a FedEx shipment via the Track API. The caller supplies the full request body — `includeDetailedScans`, `trackingInfo` — and the package forwards it verbatim.
+
+See: https://developer.fedex.com/api/en-us/catalog/track/v1/docs.html
+
+```javascript
+const json = await fedEx.trackByTrackingNumber({
+    includeDetailedScans: true,
+    trackingInfo: [{
+        trackingNumberInfo: {
+            trackingNumber: '794644790138'
+        }
+    }]
+});
+
+const trackResult = json.output.completeTrackResults[0].trackResults[0];
+
+console.log(trackResult.latestStatusDetail.statusByLocale);
+// 'Delivered'
+```
+
+Non-2xx responses reject with `HttpError`. If FedEx returns a 200 response carrying a non-empty `errors[]` envelope, the call rejects with an `HttpError` whose message is every `message` joined by `; ` and whose `.json` is the full response body (with the `errors[]` array, codes, and any other fields).
+
 ### validateAddress(addressValidationRequest, options)
 
 Validate and resolve addresses using the FedEx Address Validation API. The caller supplies the full request body — `addressesToValidate` and optionally `inEffectAsOfTimestamp` — and the package forwards it verbatim.

index.js

@@ -230,6 +230,51 @@ function FedEx(args) {
         return json;
     };
 
+    /**
+     * Track a FedEx shipment via the Track API. The caller supplies the full request
+     * body — `includeDetailedScans`, `trackingInfo` — and the package forwards it
+     * verbatim.
+     *
+     * @param {object} trackRequest - Full Track by Tracking Number request body.
+     * @param {object} [options]
+     * @param {string} [options.customer_transaction_id] - Sent as the `x-customer-transaction-id`
+     *   request header. FedEx echoes this back so callers can correlate requests with responses.
+     * @param {number} [options.timeout=30000] - Request timeout in milliseconds.
+     * @returns {Promise<object>} The parsed response body, including `output.completeTrackResults[]`.
+     * @see https://developer.fedex.com/api/en-us/catalog/track/v1/docs.html
+     */
+    this.trackByTrackingNumber = async (trackRequest, options = {}) => {
+        const accessToken = await this.getAccessToken();
+
+        const headers = {
+            Authorization: `Bearer ${accessToken.access_token}`,
+            'Content-Type': 'application/json'
+        };
+
+        if (options.customer_transaction_id) {
+            headers['x-customer-transaction-id'] = options.customer_transaction_id;
+        }
+
+        const response = await fetch(`${_options.url}/track/v1/trackingnumbers`, {
+            body: JSON.stringify(trackRequest),
+            headers,
+            method: 'POST',
+            signal: AbortSignal.timeout(options.timeout || 30000)
+        });
+
+        if (!response.ok) {
+            throw await HttpError.from(response);
+        }
+
+        const json = await response.json();
+
+        if (json.errors?.length) {
+            throw await HttpError.from(response);
+        }
+
+        return json;
+    };
+
     /**
      * Call the FedEx Address Validation API. The caller supplies the full request body
      * — `addressesToValidate` and optionally `inEffectAsOfTimestamp` — and the package

package.json

@@ -3,7 +3,7 @@
         "@stores.com/http-error": "~1.1.0",
         "memory-cache": "~0.2.0"
     },
-    "description": "FedEx REST API client for address validation, ground end of day close, OAuth tokens, rate quotes, shipment cancellation, and shipment creation.",
+    "description": "FedEx REST API client for address validation, ground end of day close, OAuth tokens, rate quotes, shipment cancellation, shipment creation, and tracking.",
     "devDependencies": {
         "@eslint/js": "*",
         "async": "~3.2.0",
@@ -18,7 +18,9 @@
         "logistics",
         "rates",
         "ship",
-        "shipping"
+        "shipping",
+        "track",
+        "tracking"
     ],
     "license": "MIT",
     "name": "@stores.com/fedex",
@@ -34,5 +36,5 @@
         "test": "node --test --test-force-exit --test-reporter=spec",
         "test:only": "node --test --test-force-exit --test-only --test-reporter=spec"
     },
-    "version": "0.4.0"
+    "version": "0.5.0"
 }