seventeen-track

seventeen-track

track packages with 17track.net

This repository provides an unofficial SDK for interacting with 17track.net from Node.js, web, and Google Apps Scripts. This project is not affiliated with 17track and may break in the future as the API evolves.

Usage Example

Below is a basic usage example:

import { Client } from "seventeen-track";

const client = new Client();

// Log in with your credentials.
const loggedIn = await client.profile.login(
  "[e-mail]",
  "your-password"
);
if (!loggedIn) {
  console.error("Login failed");
  return;
}
console.log(`Logged in as: ${client.profile.accountId}`);

// Fetch summary data.
const summary = await client.profile.summary();
console.log("Summary:", summary);

// Retrieve packages.
const packages = await client.profile.packages();
console.log("Packages:", packages);

API

login(email: string, password: string): Promise<boolean>

Logs in a user with their credentials and stores the account ID if successful.

packages(packageState?: number | string, showArchived?: boolean, tz?: string): Promise<Package[]>

Retrieves a list of packages, allowing optional filtering by state and archived status.

summary(showArchived?: boolean): Promise<Record<string, number>>

Fetches aggregate summary information about packages, optionally including archived ones.

addPackage(trackingNumber: string, friendlyName?: string): Promise<void>

Adds a package by its tracking number and sets a friendly name if provided.

setFriendlyName(internalId: string, friendlyName: string): Promise<void>

Updates the friendly name for a package identified by its internal ID.

archivePackage(trackingNumber: string): Promise<void>

Archives a package based on its tracking number.

deletePackage(trackingNumber: string): Promise<void>

Deletes a package using its tracking number.

Package

A package object contains the following properties:

Field	Type	Description
id	string	Unique identifier for the package.
destinationCountry	number	Code for the destination country.
friendlyName	string	User-friendly name for the package.
infoText	string	Additional information about the package status.
location	string	Current location of the package.
timestamp	string	Timestamp of the current status.
tz	string	Timezone of the timestamp.
originCountry	number	Code for the origin country.
packageType	number	Identifier for the type of package.
status	number	Numeric status code of the package.
trackingNumber	string	Tracking number for the package.

Supported Environments

This library is designed to work in both Node.js / web environments that support native fetch and in Google Apps Script (GAS), which uses UrlFetchApp.fetch.

In GAS, the library can be especially useful to fetch tracking numbers directly from Gmail emails and add them to 17track via the API.

Building for Google Apps Script

To build for GAS, run:

npm run build-gas

This command uses Rollup (with ts2gas) to convert the TypeScript files to GAS-compatible JavaScript. The output file (index.gs) is placed in the dist-gas folder.

For more information about targeting GAS, see here.

Deploying to GAS

To use the library in your GAS project, simply copy the index.gs file from the dist-gas folder into your GAS project.

For more details on integrating libraries in GAS, refer to the Google Apps Script Libraries documentation.

Development

Running Tests

To run the test suite, execute the following command:

The tests use the tsx framework and will run any integration tests available in the test directory.

Debug Logs

For verbose debug information during development, use the NODE_DEBUG environment variable:

NODE_DEBUG=seventeen-track npm test

This will enable logging for the seventeen-track debug namespace.

Local Environment

For local development, create a .env file at the project root with your test credentials:

TEST_USER_EMAIL=[e-mail]
TEST_USER_PASSWORD=your_password

Acknowledgments

This project was inspired by pyseventeentrack.

License

This project is licensed under the MIT License.