rocket-launch-live-client 1.0.3 → 2.0.0

package/README.md

@@ -3,6 +3,7 @@
 ## Table of Contents
 
 - [Requirements](#reqs)
+- [Install](#install)
 - [Simple Usage](#simple)
 - [Client Configuration](#config)
 - [Endpoints](#endpoints)
@@ -15,33 +16,46 @@
   - [Tags](#tags)
   - [Vehicles](#vehicles)
 - [Watcher](#watcher)
-  - [Methods and Properties](#watcher_props)
   - [Options](#watcher_options)
+  - [Methods and Properties](#watcher_props)
   - [Events](#watcher_events)
 
-This package is a fully-typed, promise-based, zero-dependency Node.JS JavaScript/TypeScript library for interacting with the [RocketLaunch.Live](https://www.rocketlaunch.live) API.
+This package is a fully-typed, promise-based, zero-dependency Node.js JavaScript/TypeScript library for interacting with the [RocketLaunch.Live](https://www.rocketlaunch.live) API.
 
 <a name="reqs"></a>
 
 ## Requirements
 
-This package is tested on and supports Node 14.18 or higher. It is fully CommonJS/ESM compatible and has Typescript support built in.
+This package requires Node **20.19.0** or higher. It ships as an ESM-only package with built-in TypeScript types.
+
+Use `import` as the primary entry path. On supported Node versions, `require()` also works via Node's [`require(esm)`](https://nodejs.org/api/modules.md#loading-ecmascript-modules-using-require) support.
+
+Package entry points:
+
+| Import | Purpose |
+| --- | --- |
+| `rocket-launch-live-client` | REST client (`rllc`, types) |
+| `rocket-launch-live-client/watcher` | Launch Watcher (`watch`, `RLLWatcher`) |
+
+<a name="install"></a>
+
+## Install
+
+```bash
+npm install rocket-launch-live-client
+```
 
 <a name="simple"></a>
 
 ## Simple usage
 
 ```js
-// Import package
 import { rllc } from "rocket-launch-live-client";
 
-// Get API Your Key
-const RLL_API_KEY = process.env.RLL_API_KEY;
+const API_KEY = process.env.RLL_API_KEY;
 
-// Create client
-const client = rllc(RLL_API_KEY);
+const client = rllc(API_KEY);
 
-// Call endpoints
 const launches = await client.launches();
 ```
 
@@ -51,19 +65,27 @@ const launches = await client.launches();
 
 RLL Clients require an API key as the first parameter, and will throw if one is not present.
 
-The client can be configured with an optional second parameter using the following keys:
+The client can be configured with an optional second parameter:
 
 ```js
 const options = {
   // Defaults to false.
-  // API Key is normally passed in the Authorization Bearer header
-  // Set to true to pass your API key as a query parameter instead (not recommended)
+  // API Key is normally passed in the Authorization Bearer header.
+  // Set to true to pass your API key as a query parameter instead (not recommended).
   keyInQueryParams: true,
+  // Defaults to 30000 (30 seconds).
+  // Abort in-flight HTTP requests that exceed this duration.
+  timeoutMs: 15000,
+  // Defaults to 10 MiB (10485760 bytes).
+  // Reject responses whose decompressed body exceeds this size (also stops gzip bombs).
+  maxResponseBytes: 5 * 1024 * 1024,
 };
 
-const client = rllc(RLL_API_KEY, options);
+const client = rllc(API_KEY, options);
 ```
 
+Requests send `Accept-Encoding: gzip` and transparently decode gzip responses from the API.
+
 <a name="endpoints"></a>
 
 ## Endpoints
@@ -89,13 +111,13 @@ const response = await client.launches({ page: 2 });
 // Also accepts page number as a number-parseable string like "2"
 ```
 
-For complete API Documentation on parameters, be sure to visit [RocketLaunch.Live](https://www.rocketlaunch.live/api)
+For complete API documentation on parameters, visit [RocketLaunch.Live](https://www.rocketlaunch.live/api).
 
 <a name="types"></a>
 
 ### Response Types
 
-All entity response types are browseable in the [GitHub Repository](https://github.com/mendahu/rocket-launch-live-client/tree/main/src/types).
+Entity response types are exported from the package (`RLLEntity`, `RLLResponse`, `RLLError`, `RLLQueryConfig`, and others) and are browseable in the [GitHub repository](https://github.com/mendahu/rocket-launch-live-client/tree/main/src/types).
 
 <a name="companies"></a>
 
@@ -110,9 +132,12 @@ Optional search parameters:
 ```js
 const options = {
   // Company numeric id
-  // Also accepts number parseable strings like "1"
+  // Also accepts number-parseable strings like "1"
   id: 1,
 
+  // Page number of results
+  page: 1,
+
   // Company name
   name: "SpaceX",
 
@@ -138,9 +163,12 @@ Optional search parameters:
 ```js
 const options = {
   // Launch numeric id
-  // Also accepts number parseable strings like "1"
+  // Also accepts number-parseable strings like "1"
   id: 1,
 
+  // Page number of results
+  page: 1,
+
   // COSPAR
   // Format YYYY-NNN
   cospar_id: "2022-123",
@@ -162,23 +190,23 @@ const options = {
   modified_since: new Date("2023-01-31T06:00:00Z"),
 
   // Launch location id
-  // Also accepts number parseable strings like "1"
+  // Also accepts number-parseable strings like "1"
   location_id: 1,
 
   // Launch pad id
-  // Also accepts number parseable strings like "1"
+  // Also accepts number-parseable strings like "1"
   pad_id: 1,
 
   // Launch provider id
-  // Also accepts number parseable strings like "1"
+  // Also accepts number-parseable strings like "1"
   provider_id: 1,
 
   // Launch tag id
-  // Also accepts number parseable strings like "1"
+  // Also accepts number-parseable strings like "1"
   tag_id: 1,
 
   // Launch vehicle id
-  // Also accepts number parseable strings like "1"
+  // Also accepts number-parseable strings like "1"
   vehicle_id: 1,
 
   // US State
@@ -198,8 +226,8 @@ const options = {
 
   // Limit amount of launches returned
   // Must be between 1 and 25
-  // Also accepts number parseable strings like "10"
-  // Note: this param is safely ignored when using in conjuction with a Watcher (see below)
+  // Also accepts number-parseable strings like "10"
+  // Note: this param is ignored when using the Watcher (see below)
   limit: 10,
 
   // Sort order (by date) of results
@@ -222,9 +250,12 @@ Optional search parameters:
 ```js
 const options = {
   // Location numeric id
-  // Also accepts number parseable strings like "1"
+  // Also accepts number-parseable strings like "1"
   id: 1,
 
+  // Page number of results
+  page: 1,
+
   // Location name
   name: "Cape Canaveral",
 
@@ -251,9 +282,12 @@ Optional search parameters:
 ```js
 const options = {
   // Mission numeric id
-  // Also accepts number parseable strings like "1"
+  // Also accepts number-parseable strings like "1"
   id: 1,
 
+  // Page number of results
+  page: 1,
+
   // Mission name
   name: "Juno",
 };
@@ -272,9 +306,12 @@ Optional search parameters:
 ```js
 const options = {
   // Pad numeric id
-  // Also accepts number parseable strings like "1"
+  // Also accepts number-parseable strings like "1"
   id: 1,
 
+  // Page number of results
+  page: 1,
+
   // Pad name
   name: "SpaceX",
 
@@ -301,9 +338,12 @@ Optional search parameters:
 ```js
 const options = {
   // Tag numeric id
-  // Also accepts number parseable strings like "1"
+  // Also accepts number-parseable strings like "1"
   id: 1,
 
+  // Page number of results
+  page: 1,
+
   // Tag text
   text: "Crewed",
 };
@@ -322,9 +362,12 @@ Optional search parameters:
 ```js
 const options = {
   // Vehicle numeric id
-  // Also accepts number parseable strings like "1"
+  // Also accepts number-parseable strings like "1"
   id: 1,
 
+  // Page number of results
+  page: 1,
+
   // Vehicle name
   name: "Atlas V",
 };
@@ -334,12 +377,17 @@ const options = {
 
 ## Watcher
 
-The `rocket-launch-live-client` has the ability to monitor the `launches` endpoint on a regular basis and return changes as they happen live.
+The Watcher monitors the `launches` endpoint on a regular basis and emits changes as they happen. Import it from the `./watcher` subpath so applications that only need the REST client do not load Watcher code.
 
 ```js
+import { rllc } from "rocket-launch-live-client";
+import { watch } from "rocket-launch-live-client/watcher";
+
+const client = rllc(process.env.RLL_API_KEY);
+
 // Instantiate a new watcher
 // See below for options
-const watcher = client.watch(5, options);
+const watcher = watch(client, 5, options);
 
 // Define event handlers
 watcher.on("new", (newLaunch) => {
@@ -353,32 +401,35 @@ watcher.start();
 watcher.stop();
 ```
 
-<a name="watcher_props"></a>
+You can also import the `RLLWatcher` class from the same subpath if you need the type or class directly.
 
 <a name="watcher_options"></a>
 
 ### Watcher Options
 
-A new watcher takes up to two arguments:
+`watch()` takes up to three arguments:
 
-1. Interval - (optional) (default: 5) - a duration, in minutes, between calls to the API. Adjust this based on the frequency you wish to stay up to date. To avoid needlessly querying the API, this client will now allow any option less than 1 minute.
-2. Query Options - (optional) - The exact same query options that can be submitted to the [`launches`](#launches) endpoint. _NOTE:_ the "limit" param is ignored on the `watcher`.
+1. Client - (required) - an `RLLClient` instance from `rllc()`
+2. Interval - (optional) (default: 5) - a duration, in minutes, between calls to the API. Adjust this based on the frequency you wish to stay up to date. To avoid needlessly querying the API, this client will not allow any option less than 1 minute.
+3. Query Options - (optional) - The exact same query options that can be submitted to the [`launches`](#launches) endpoint. _NOTE:_ the `limit` and `page` params are ignored on the Watcher (it always builds the cache from page 1 across all matching pages).
 
-Query options cannot be altered on a running watcher. In order to change your search conditions, you'll need to stop the watcher and start a new one.
+On start, the Watcher pages through every matching result to build an in-memory cache, then polls with `modified_since` on the configured interval. Query options cannot be altered on a running watcher — stop it and create a new one to change search conditions.
+
+<a name="watcher_props"></a>
 
 ### Watcher Methods and Properties
 
 #### Start
 
-Begin watching the `launches` endpoint using the interval and query options provided during watcher instantiation.
+Begin watching the `launches` endpoint using the interval and query options provided during watcher instantiation. Calling `start()` again while already running is a no-op.
 
 ```js
 watcher.start();
 ```
 
-#### End
+#### Stop
 
-Stop watching the `launches` endpoint.
+Stop watching the `launches` endpoint. Clears the interval timer so polling ends. You can call `start()` again afterward to rebuild the cache and resume.
 
 ```js
 watcher.stop();
@@ -401,7 +452,7 @@ Access the launches data cache. The data is stored in a [JavaScript Map](https:/
 ```js
 watcher.launches; // Map of all launches in cache
 watcher.launches.size // Count of launches in cache
-watcher.launches.get(1) // Get launch with launch_id of 1
+watcher.launches.get(1) // Get launch with launch id of 1
 watcher.launches.forEach((launch, launchId) => /* Do something to each launch */ )
 ```
 
@@ -411,10 +462,12 @@ Note: We recommend not altering the `launches` cache directly (such as by using
 
 ### Watcher Events
 
-Watcher events are triggered when the client recieves a response to a query to `launches` using the `modified_since` parameter. The client will compare the changes to a cached version of the launch and trigger the appropriate event.
+Watcher events are triggered when the client receives a response to a query to `launches` using the `modified_since` parameter. The client will compare the changes to a cached version of the launch and trigger the appropriate event.
 
 If there are multiple changes on a single API call, the appropriate events will be triggered more than once, so have your callbacks handle a single event.
 
+Interval ticks that fire while a previous poll is still in flight are skipped, so slow or multi-page polls do not stack concurrent requests.
+
 <a name="watcher_events_new"></a>
 
 #### New
@@ -455,15 +508,15 @@ watcher.on("error", (err) => {
 });
 ```
 
-The `err` object will have the following shape, and is accessible via TypeScript as `RLLError`:
+The `err` object has the following shape, and is accessible via TypeScript as `RLLError`:
 
-```js
-const err = {
-  error: "Error title";
-  statusCode: 404; // HTTP status code or null if no response
-  message: "Could not find this resource"; //  Custom error string from RLLC
-  server_response: { } // error passed through from server, can be null if no response
-}
+```ts
+type RLLError = {
+  error: string;
+  statusCode: number | null; // HTTP status code, or null if no response
+  message: string; // Custom error string from RLLC
+  server_response: string | null; // Server body, or null if no response
+};
 ```
 
 #### Ready
@@ -478,7 +531,7 @@ watcher.on("ready", (launches) => {
 
 #### Initialization Errors
 
-The watcher has experienced a problem setting up its initial cache and is has not started monitoring.
+The watcher experienced a problem setting up its initial cache and has not started monitoring.
 
 ```js
 watcher.on("init_error", (err) => {
@@ -486,20 +539,11 @@ watcher.on("init_error", (err) => {
 });
 ```
 
-The `err` object will have the following shape, and is accessible via TypeScript as `RLLError`:
-
-```js
-const err = {
-  error: "Error title";
-  statusCode: 404; // HTTP status code or null if no response
-  message: "Could not find this resource"; //  Custom error string from RLLC
-  server_response: { } // error passed through from server, can be null if no response
-}
-```
+The `err` object is the same `RLLError` shape as the `error` event above.
 
 #### Call
 
-The watcher also emits a `call` event every time it makes a request, passing in the query parameters it used in the Node URLSearchParams format. Use this to monitor or diagnose how often the API is being queried.
+The watcher also emits a `call` event every time it makes a request, passing in the query parameters it used in the Node `URLSearchParams` format. Use this to monitor or diagnose how often the API is being queried.
 
 ```js
 watcher.on("call", (params) => {

package/lib/{esm/types/Client.d.ts → Client.d.ts}

@@ -1,5 +1,4 @@
 import { RLLClientOptions, RLLEntity, RLLQueryConfig, RLLResponse } from "./types/application.js";
-import { RLLWatcher } from "./Watcher.js";
 /**
  * Class representing a RocketLaunch.Live client
  * @class
@@ -13,6 +12,8 @@ export declare class RLLClient {
      * @param {string} apiKey - Your RocketLaunch.Live API Key
      * @param {Object} [options] - Optional Client Configuration options
      * @param {boolean} options.keyInQueryParams - Set to true to send your API Key via Query parameters instead of Authorization Header (not recommended)
+     * @param {number} options.timeoutMs - HTTP request timeout in milliseconds (default 30000)
+     * @param {number} options.maxResponseBytes - Max decompressed response body size in bytes (default 10 MiB)
      *
      */
     constructor(apiKey: string, options?: RLLClientOptions);
@@ -30,16 +31,13 @@ export declare class RLLClient {
      */
     private query;
     /**
-     * Instantiate a new RLL Watcher which will continually query the API for changes to the launches endpoint
+     * Execute a launches query with pre-built search params.
+     * Prefer {@link RLLClient.launches} for normal use; this exists for the
+     * `rocket-launch-live-client/watcher` subpath.
      *
      * @public
-     *
-     * @param {number} interval - Interval in minutes to query the API for changes. Defaults to 5 minutes, cannot be less than 1 minute
-     * @param {RLLQueryConfig.Launches} options - Query options, same as calling the launches method
-     *
-     * @returns {RLLWatcher}
      */
-    watch(interval?: number | string, options?: RLLQueryConfig.Launches): RLLWatcher;
+    queryLaunches(params: URLSearchParams): Promise<RLLResponse<RLLEntity.Launch[]>>;
     /**
      * Fetch launch companies
      *

package/lib/Client.js

@@ -0,0 +1,61 @@
+import { RLLEndPoint, } from "./types/application.js";
+import { fetcher, DEFAULT_REQUEST_TIMEOUT_MS, DEFAULT_MAX_RESPONSE_BYTES, } from "./fetcher.js";
+import { apiKeyValidator, optionsValidator, queryOptionsValidator, } from "./utils.js";
+export class RLLClient {
+    apiKey;
+    config = {
+        keyInQueryParams: false,
+        timeoutMs: DEFAULT_REQUEST_TIMEOUT_MS,
+        maxResponseBytes: DEFAULT_MAX_RESPONSE_BYTES,
+    };
+    constructor(apiKey, options) {
+        this.apiKey = apiKeyValidator(apiKey);
+        if (!options) {
+            return;
+        }
+        optionsValidator(options);
+        if (options.keyInQueryParams) {
+            this.config.keyInQueryParams = options.keyInQueryParams;
+        }
+        if (options.timeoutMs !== undefined) {
+            this.config.timeoutMs = options.timeoutMs;
+        }
+        if (options.maxResponseBytes !== undefined) {
+            this.config.maxResponseBytes = options.maxResponseBytes;
+        }
+    }
+    query(endpoint, params) {
+        return fetcher(this.apiKey, endpoint, params, this.config.keyInQueryParams, this.config.timeoutMs, this.config.maxResponseBytes);
+    }
+    queryLaunches(params) {
+        return this.query(RLLEndPoint.LAUNCHES, params);
+    }
+    companies(options) {
+        const params = queryOptionsValidator(RLLEndPoint.COMPANIES, options);
+        return this.query(RLLEndPoint.COMPANIES, params);
+    }
+    launches(options) {
+        const params = queryOptionsValidator(RLLEndPoint.LAUNCHES, options);
+        return this.query(RLLEndPoint.LAUNCHES, params);
+    }
+    locations(options) {
+        const params = queryOptionsValidator(RLLEndPoint.LOCATIONS, options);
+        return this.query(RLLEndPoint.LOCATIONS, params);
+    }
+    missions(options) {
+        const params = queryOptionsValidator(RLLEndPoint.MISSIONS, options);
+        return this.query(RLLEndPoint.MISSIONS, params);
+    }
+    pads(options) {
+        const params = queryOptionsValidator(RLLEndPoint.PADS, options);
+        return this.query(RLLEndPoint.PADS, params);
+    }
+    tags(options) {
+        const params = queryOptionsValidator(RLLEndPoint.TAGS, options);
+        return this.query(RLLEndPoint.TAGS, params);
+    }
+    vehicles(options) {
+        const params = queryOptionsValidator(RLLEndPoint.VEHICLES, options);
+        return this.query(RLLEndPoint.VEHICLES, params);
+    }
+}

package/lib/fetcher.d.ts

@@ -0,0 +1,5 @@
+/** Default HTTP request timeout (30 seconds). */
+export declare const DEFAULT_REQUEST_TIMEOUT_MS = 30000;
+/** Default max decompressed response body size (10 MiB). */
+export declare const DEFAULT_MAX_RESPONSE_BYTES: number;
+export declare const fetcher: <T>(apiKey: string, endpoint: string, params: URLSearchParams, keyInQueryParams: boolean, timeoutMs?: number, maxResponseBytes?: number) => Promise<T>;

package/lib/fetcher.js

@@ -0,0 +1,146 @@
+import https from "node:https";
+import { createGunzip } from "node:zlib";
+const BASE_URL = "https://fdo.rocketlaunch.live";
+export const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+export const DEFAULT_MAX_RESPONSE_BYTES = 10 * 1024 * 1024;
+const RESPONSE_TOO_LARGE = "ERR_RESPONSE_TOO_LARGE";
+export const fetcher = (apiKey, endpoint, params, keyInQueryParams, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS, maxResponseBytes = DEFAULT_MAX_RESPONSE_BYTES) => {
+    const url = new URL("json/" + endpoint, BASE_URL);
+    const headers = {
+        "accept-encoding": "gzip",
+    };
+    if (keyInQueryParams) {
+        params.set("key", apiKey);
+    }
+    else {
+        headers.authorization = `Bearer ${apiKey}`;
+    }
+    params.forEach((v, k) => url.searchParams.set(k, v));
+    return query(url, headers, timeoutMs, maxResponseBytes);
+};
+const readResponseBody = (res, maxBytes) => {
+    return new Promise((resolve, reject) => {
+        const encoding = res.headers["content-encoding"];
+        const isGzip = encoding === "gzip" || encoding === "x-gzip";
+        const contentLength = Number(res.headers["content-length"]);
+        if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+            res.destroy();
+            const err = new Error(`RLLC response exceeded the ${maxBytes}-byte size limit.`);
+            err.code = RESPONSE_TOO_LARGE;
+            reject(err);
+            return;
+        }
+        const stream = isGzip ? res.pipe(createGunzip()) : res;
+        const chunks = [];
+        let total = 0;
+        let settled = false;
+        const fail = (err) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            stream.destroy();
+            res.destroy();
+            reject(err);
+        };
+        stream.on("data", (chunk) => {
+            total += chunk.length;
+            if (total > maxBytes) {
+                const err = new Error(`RLLC response exceeded the ${maxBytes}-byte size limit.`);
+                err.code = RESPONSE_TOO_LARGE;
+                fail(err);
+                return;
+            }
+            chunks.push(chunk);
+        });
+        stream.on("error", (err) => {
+            fail(err);
+        });
+        stream.on("end", () => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            resolve(Buffer.concat(chunks).toString());
+        });
+    });
+};
+const query = (url, headers, timeoutMs, maxResponseBytes) => {
+    return new Promise((resolve, reject) => {
+        const controller = new AbortController();
+        let settled = false;
+        const finish = (action) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            clearTimeout(timeout);
+            action();
+        };
+        const timeout = setTimeout(() => {
+            controller.abort();
+        }, timeoutMs);
+        const req = https.get(url, { headers, signal: controller.signal }, (res) => {
+            readResponseBody(res, maxResponseBytes)
+                .then((response) => {
+                let server_response;
+                try {
+                    server_response = JSON.parse(response);
+                }
+                catch {
+                    server_response = response;
+                }
+                if (res.statusCode === 200) {
+                    finish(() => resolve(server_response));
+                }
+                else {
+                    const error = {
+                        error: "API Call Failed",
+                        statusCode: res.statusCode ?? null,
+                        message: "RLLC recieved a response from the server but it did not complete as expected.",
+                        server_response,
+                    };
+                    finish(() => reject(error));
+                }
+            })
+                .catch((err) => {
+                if (err?.code === RESPONSE_TOO_LARGE) {
+                    const error = {
+                        error: "Response too large",
+                        statusCode: res.statusCode ?? null,
+                        message: err.message,
+                        server_response: null,
+                    };
+                    finish(() => reject(error));
+                    return;
+                }
+                const error = {
+                    error: "Unknown error",
+                    statusCode: null,
+                    message: "RLLC recieved an unknown error. This usually means that the HTTP request did not complete",
+                    server_response: null,
+                };
+                finish(() => reject(error));
+            });
+        });
+        req.on("error", () => {
+            if (controller.signal.aborted) {
+                const error = {
+                    error: "Timeout",
+                    statusCode: null,
+                    message: `RLLC request timed out after ${timeoutMs}ms.`,
+                    server_response: null,
+                };
+                finish(() => reject(error));
+                return;
+            }
+            const error = {
+                error: "Unknown error",
+                statusCode: null,
+                message: "RLLC recieved an unknown error. This usually means that the HTTP request did not complete",
+                server_response: null,
+            };
+            finish(() => reject(error));
+        });
+    });
+};

package/lib/{cjs/types/index.d.ts → index.d.ts}

@@ -3,7 +3,6 @@ import { RLLClientOptions } from "./types/application.js";
 export { RLLEndPoint, RLLResponse, RLLClientOptions, RLLQueryConfig, RLLEntity, RLLError, } from "./types/application.js";
 export { ISO3166Alpha2 } from "./types/standards.js";
 export { RLLClient } from "./Client.js";
-export { RLLWatcher } from "./Watcher.js";
 /**
  * Generate a RocketLaunch.Live client
  *

package/lib/index.js

@@ -0,0 +1,4 @@
+import { RLLClient } from "./Client.js";
+export { RLLEndPoint, RLLEntity, } from "./types/application.js";
+export { RLLClient } from "./Client.js";
+export const rllc = (apiKey, options) => new RLLClient(apiKey, options);