teksavvy-js v1.0.0

teksavvy-js

A JS wrapper for the Teksavvy API

Why?

Teksavvy is one of the few ISPs offering a public API that can be used to query usage data. However, no official documentation seems to exist online for it, making the use of the API a bit of a pain. This API wrapper seeks to solve the issue of having to chase scarce and user-contributed API documentation to build software on top of the Teksavvy API.

The main source of truth on the API at the moment is this short document found on DSLReport.

Getting started

To use this wrapper, you will need to generate an API key for your Teksavvy account. This can be done through the customer portal.

Wrapper setup

constructor(apiKey [, options = {}])

The apiKey needs to be supplied, omitting it will raise a MissingAPIKeyError and prevent any requests from being sent.

The options are described below:

Usage

The API methods will return Promises that can be handled however you want using the then and catch functions.

API methods

usageRecords([operators = {}])

See the Query Operators section for details on how to use the operators parameter.

Output format

{
  date: ...,
  download: {
    onPeak: ...,
    offPeak: ...,
  },
  upload: {
    onPeak: ...,
    offPeak: ...,
  },
}

usageSummaries([operators = {}])

See the Query Operators section for details on how to use the operators parameter.

{
  start: ...,
  end: ...,
  isCurrent: ...,
  download: {
    onPeak: ...,
    offPeak: ...,
  },
  upload: {
    onPeak: ...,
    offPeak: ...,
  },
}

Rate limiting

The API wrapper includes a rate limiting feature which can be set using the rateLimit option. The rate limit is based on the number of requests per minute allowed to go through.

Any request that would exceed the preset per-minute request limit will throw a RateLimitExceededError and will not be sent nor queued.

By default, the rate limit is set to 30, as it is the limit set by the Teksavvy API documentation.

Query operators

The wrapper supports OData query operators that are accepted by the Teksavvy API. You can use them by passing an object to the usageSummaries and usageRecords functions.

$orderby support

Teksavvy doesn't seem to allow the use of $orderby with any useful keys, the wrapper allows the requests to be sent anyway while the situation is figured out.

Filter query objects

The current format of filter query parameters is an array of objects containing a key corresponding to one of the elements of the formatted result object, a reference value and a comparison operator compare.

[
  {
    key: ...,
    value: ...,
    compare: ...,
  },
  ...
]