rocket-launch-live-client 0.1.0

package/src/Client.ts

@@ -0,0 +1,262 @@
+import {
+  RLLClientOptions,
+  RLLEndPoint,
+  RLLEntity,
+  RLLQueryConfig,
+  RLLResponse,
+} from "./types/application";
+import { fetcher } from "./fetcher";
+import {
+  apiKeyValidator,
+  optionsValidator,
+  queryOptionsValidator,
+} from "./utils";
+
+class RLLClient {
+  private apiKey: string;
+  private config = {
+    keyInQueryParams: false,
+  };
+
+  constructor(apiKey: string, options?: RLLClientOptions) {
+    // Validate API Key is a valid UUID format
+    // Constructor throws if not
+    apiKeyValidator(apiKey);
+    this.apiKey = apiKey;
+
+    if (!options) {
+      return;
+    }
+
+    // Validate Options with warnings or throws
+    optionsValidator(options);
+
+    if (options.keyInQueryParams) {
+      this.config.keyInQueryParams = options.keyInQueryParams;
+    }
+  }
+
+  /**
+   * Used internally to make API query
+   *
+   * @private
+   *
+   * @template T
+   *
+   * @param {string} endpoint - API endpoint (ie. "/launches")
+   * @param {URLSearchParams} params - API Search Params
+   *
+   * @returns {Promise<T>}
+   */
+  private query<T>(endpoint: string, params: URLSearchParams): Promise<T> {
+    return fetcher<T>(
+      this.apiKey,
+      endpoint,
+      params,
+      this.config.keyInQueryParams
+    );
+  }
+
+  /**
+   * Fetch launch companies
+   *
+   * @public
+   * @function
+   *
+   * @param {Object} [options] - Launch Company Search Options
+   * @param {number | string} options.id - Company id
+   * @param {number | string} options.page - Page number of results
+   * @param {number | string} options.name - Company name
+   * @param {ISO3166Alpha2.CountryCode} options.country_code - ISO 3166 Alpha 2 Country Code
+   * @param {boolean} options.inactive - Company inactive status
+   *
+   * @returns {Promise<RLLResponse<RLLEntity.Company[]>>} Array of companies wrapped in a standard RLL Response
+   *
+   * @example
+   *
+   * const response = client.companies({ country_code: "US" })
+   */
+  public companies(
+    options?: RLLQueryConfig.Companies
+  ): Promise<RLLResponse<RLLEntity.Company[]>> {
+    return queryOptionsValidator(RLLEndPoint.COMPANIES, options).then(
+      (params) =>
+        this.query<RLLResponse<RLLEntity.Company[]>>(
+          RLLEndPoint.COMPANIES,
+          params
+        )
+    );
+  }
+
+  /**
+   * Fetch launches
+   *
+   * @public
+   * @function
+   *
+   * @param {Object} [options] - Launch Search Options
+   * @param {number | string} options.id - Launch id
+   * @param {number | string} options.page - Page number of results
+   * @param {string} options.cospar_id - Launch COSPAR ID (ie. 2022-123)
+   * @param {Date | string} options.before_date - Only return launches before this date
+   * @param {Date | string} options.after_date - Only return launches after this date
+   * @param {Date | string} options.modified_since - Only return launches with API changes after this date
+   * @param {number | string} options.location_id - Launches from this Location
+   * @param {number | string} options.pad_id - Launches from this Pad
+   * @param {number | string} options.provider_id - Launches from this Company
+   * @param {number | string} options.tag_id - Launches with this Tag
+   * @param {number | string} options.vehicle_id - Launches on this Vehicle
+   * @param {ISO3166Alpha2.StateCodeUS} options.state_abbr - ISO 3166 Alpha 2 US State Code
+   * @param {ISO3166Alpha2.CountryCode} options.country_code - ISO 3166 Alpha 2 Country Code
+   * @param {number | string} options.search - Launches matching this search string
+   * @param {number | string} options.slug - Launches matching this unique slug
+   *
+   * @returns {Promise<RLLResponse<RLLEntity.Launch[]>>} Array of companies wrapped in a standard RLL Response
+   *
+   * @example
+   *
+   * const response = client.launches({ after_date: new Date("2022-10-10") })
+   */
+  public launches(
+    options?: RLLQueryConfig.Launches
+  ): Promise<RLLResponse<RLLEntity.Launch[]>> {
+    return queryOptionsValidator(RLLEndPoint.LAUNCHES, options).then((params) =>
+      this.query<RLLResponse<RLLEntity.Launch[]>>(RLLEndPoint.LAUNCHES, params)
+    );
+  }
+
+  /**
+   * Fetch launch locations
+   *
+   * @public
+   * @function
+   *
+   * @param {Object} [options] - Launch Location Search Options
+   * @param {number | string} options.id - Location id
+   * @param {number | string} options.page - Page number of results
+   * @param {number | string} options.name - Location name
+   * @param {ISO3166Alpha2.StateCodeUS} options.state_abbr - ISO 3166 Alpha 2 US State Code
+   * @param {ISO3166Alpha2.CountryCode} options.country_code - ISO 3166 Alpha 2 Country Code
+   *
+   * @returns {Promise<RLLResponse<RLLEntity.Location[]>>} Array of companies wrapped in a standard RLL Response
+   *
+   * @example
+   *
+   * const response = client.locations({ country_code: "US" })
+   */
+  public locations(
+    options?: RLLQueryConfig.Locations
+  ): Promise<RLLResponse<RLLEntity.Location[]>> {
+    return queryOptionsValidator(RLLEndPoint.LOCATIONS, options).then(
+      (params) =>
+        this.query<RLLResponse<RLLEntity.Location[]>>(
+          RLLEndPoint.LOCATIONS,
+          params
+        )
+    );
+  }
+
+  /**
+   * Fetch launch Missions
+   *
+   * @public
+   * @function
+   *
+   * @param {Object} [options] - Launch Mission Search Options
+   * @param {number | string} options.id - Mission id
+   * @param {number | string} options.page - Page number of results
+   * @param {number | string} options.name - Mission name
+   *
+   * @returns {Promise<RLLResponse<RLLEntity.Mission[]>>} Array of companies wrapped in a standard RLL Response
+   *
+   * @example
+   *
+   * const response = client.missions({ name: "Mars 2020" })
+   */
+  public missions(
+    options?: RLLQueryConfig.Missions
+  ): Promise<RLLResponse<RLLEntity.Mission[]>> {
+    return queryOptionsValidator(RLLEndPoint.MISSIONS, options).then((params) =>
+      this.query<RLLResponse<RLLEntity.Mission[]>>(RLLEndPoint.MISSIONS, params)
+    );
+  }
+
+  /**
+   * Fetch launch pads
+   *
+   * @public
+   * @function
+   *
+   * @param {Object} [options] - Launch Pad Search Options
+   * @param {number | string} options.id - Pad id
+   * @param {number | string} options.page - Page number of results
+   * @param {number | string} options.name - Pad name
+   * @param {ISO3166Alpha2.StateCodeUS} options.state_abbr - ISO 3166 Alpha 2 US State Code
+   * @param {ISO3166Alpha2.CountryCode} options.country_code - ISO 3166 Alpha 2 Country Code
+   *
+   * @returns {Promise<RLLResponse<RLLEntity.Pad[]>>} Array of companies wrapped in a standard RLL Response
+   *
+   * @example
+   *
+   * const response = client.pads({ country_code: "US" })
+   */
+  public pads(
+    options?: RLLQueryConfig.Pads
+  ): Promise<RLLResponse<RLLEntity.Pad[]>> {
+    return queryOptionsValidator(RLLEndPoint.PADS, options).then((params) =>
+      this.query<RLLResponse<RLLEntity.Pad[]>>(RLLEndPoint.PADS, params)
+    );
+  }
+
+  /**
+   * Fetch launch tags
+   *
+   * @public
+   * @function
+   *
+   * @param {Object} [options] - Launch Tag Search Options
+   * @param {number | string} options.id - Tag id
+   * @param {number | string} options.page - Page number of results
+   * @param {number | string} options.text - Tag text
+   *
+   * @returns {Promise<RLLResponse<RLLEntity.Tag[]>>} Array of companies wrapped in a standard RLL Response
+   *
+   * @example
+   *
+   * const response = client.tags({ text: "Crewed" })
+   */
+  public tags(
+    options?: RLLQueryConfig.Tags
+  ): Promise<RLLResponse<RLLEntity.Tag[]>> {
+    return queryOptionsValidator(RLLEndPoint.TAGS, options).then((params) =>
+      this.query<RLLResponse<RLLEntity.Tag[]>>(RLLEndPoint.TAGS, params)
+    );
+  }
+
+  /**
+   * Fetch launch Vehicles
+   *
+   * @public
+   * @function
+   *
+   * @param {Object} [options] - Launch Vehicles Search Options
+   * @param {number | string} options.id - Vehicle id
+   * @param {number | string} options.page - Page number of results
+   * @param {number | string} options.name - Vehicle name
+   *
+   * @returns {Promise<RLLResponse<RLLEntity.Vehicle[]>>} Array of companies wrapped in a standard RLL Response
+   *
+   * @example
+   *
+   * const response = client.vehicles({ name: "Falcon 9" })
+   */
+  public vehicles(
+    options?: RLLQueryConfig.Vehicles
+  ): Promise<RLLResponse<RLLEntity.Vehicle[]>> {
+    return queryOptionsValidator(RLLEndPoint.VEHICLES, options).then((params) =>
+      this.query<RLLResponse<RLLEntity.Vehicle[]>>(RLLEndPoint.VEHICLES, params)
+    );
+  }
+}
+
+export default RLLClient;

package/src/fetcher.ts

@@ -0,0 +1,50 @@
+const https = require("node:https");
+
+const BASE_URL = "https://fdo.rocketlaunch.live";
+
+export const fetcher = <T>(
+  apiKey: string,
+  endpoint: string,
+  params: URLSearchParams,
+  keyInQueryParams: boolean
+): Promise<T> => {
+  const url = new URL("json/" + endpoint, BASE_URL);
+  let headers: HeadersInit | undefined;
+
+  if (keyInQueryParams) {
+    params.set("key", apiKey);
+  } else {
+    headers = { authorization: `Bearer ${apiKey}` };
+  }
+
+  params.forEach((v, k) => url.searchParams.set(k, v));
+
+  return query<T>(url, headers);
+};
+
+const query = <T>(url: URL, headers?: HeadersInit): Promise<T> => {
+  return new Promise((resolve, reject) => {
+    const req = https.get(url, { headers }, (res) => {
+      let data = [];
+
+      res.on("data", (chunk) => data.push(chunk));
+
+      res.on("end", () => {
+        if (res.statusCode === 200) {
+          const response = Buffer.concat(data).toString();
+          resolve(JSON.parse(response));
+        } else if (res.statusCode === 404) {
+          reject({
+            error: "Resource not found",
+            statusCode: 404,
+            message:
+              "The server returned a 404 Not Found response. Check that your API key is valid, and that you are not requesting a page number beyond the available results.",
+          });
+        } else {
+          reject(res);
+        }
+      });
+    });
+    req.on("error", reject);
+  });
+};

package/src/index.ts

@@ -0,0 +1,29 @@
+import RLLClient from "./Client";
+import { RLLClientOptions } from "./types/application";
+
+/**
+ * Generate a RocketLaunch.Live client
+ *
+ * @public
+ * @function
+ *
+ * @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)
+ *
+ * @returns {RLLCLient}
+ *
+ * @example
+ *
+ * const MY_KEY = process.env.ROCKETLAUNCH_LIVE_API_KEY
+ *
+ * const client = clientGenerator(MY_KEY, { keyInQueryParams: true })
+ */
+const clientGenerator = (
+  apiKey: string,
+  options?: RLLClientOptions
+): RLLClient => {
+  return new RLLClient(apiKey, options);
+};
+
+export default clientGenerator;

package/src/types/application.ts

@@ -0,0 +1,193 @@
+import { ISO3166Alpha2 } from "./standards";
+
+export enum RLLEndPoint {
+  COMPANIES = "companies",
+  LAUNCHES = "launches",
+  LOCATIONS = "locations",
+  MISSIONS = "missions",
+  PADS = "pads",
+  TAGS = "tags",
+  VEHICLES = "vehicles",
+}
+
+interface RLLRecord {
+  id: number;
+}
+
+export namespace RLLEntity {
+  interface Country {
+    name: string;
+    code: ISO3166Alpha2.CountryCode;
+  }
+
+  interface State {
+    name: string;
+    abbr: ISO3166Alpha2.StateCodeUS;
+  }
+
+  export interface Company extends RLLRecord {
+    country: Country;
+    inactive: boolean | null;
+  }
+
+  enum LaunchResult {
+    NOT_SET = -1,
+    FAILURE = 0,
+    SUCCESS = 1,
+    PARTIAL_FAILURE = 2,
+    IN_FLIGHT_ABORT_CREWED = 3,
+  }
+
+  interface Media extends RLLRecord {
+    media_url: string | null;
+    youtube_vidid: string | null;
+    featured: boolean;
+    ldfeatured: boolean;
+    approved: boolean;
+  }
+
+  export interface Launch extends RLLRecord {
+    name: string;
+    cospar_id: string;
+    sort_date: string;
+    provider: Omit<Company, "inactive" | "country">;
+    vehicle: Omit<Vehicle, "company_id" | "company">;
+    pad: Omit<Pad, "full_name">;
+    missions: Omit<Mission, "launch_id">[];
+    mission_description: string | null;
+    launch_description: string;
+    win_open: string | null;
+    t0: string | null;
+    win_close: string | null;
+    est_date: {
+      month: number | null;
+      day: number | null;
+      year: number | null;
+      quarter: number | null;
+    };
+    date_str: string;
+    tags: Omit<Tag, "slug">[];
+    slug: string;
+    weather_summary: string | null;
+    weather_temp: number | null;
+    weather_icon: string | null;
+    weather_updated: string | null;
+    quicktext: string;
+    media?: Media[];
+    result: LaunchResult;
+    suborbital: boolean;
+    modified: string;
+  }
+
+  export interface Location extends RLLRecord {
+    name: string;
+    latitute: string; // original API had a typo which was preserved for backwards compatibility
+    latitude: string;
+    longitude: string;
+    state: State | null;
+    statename?: string | null;
+    country: Country;
+    pads: Omit<Pad, "location" | "country" | "state">[];
+    utc_offset: number;
+  }
+
+  export interface Mission extends RLLRecord {
+    name: string;
+    description: string | null;
+    launch_id: number;
+    company: Omit<Company, "slug" | "inactive" | "country">;
+  }
+
+  export interface Pad extends RLLRecord {
+    name: string;
+    full_name: string;
+    location: Omit<Location, "pads" | "utc_offset" | "latitute">;
+  }
+
+  export interface Tag extends RLLRecord {
+    text: string;
+    slug: string;
+  }
+
+  export interface Vehicle extends RLLRecord {
+    name: string;
+    company_id?: number;
+    company: Omit<Company, "slug" | "inactive" | "country">;
+  }
+}
+
+interface RLLBaseQueryConfig {
+  id?: number | string;
+  page?: number | string;
+}
+
+export namespace RLLQueryConfig {
+  export interface Companies extends RLLBaseQueryConfig {
+    name?: string | number;
+    country_code?: ISO3166Alpha2.CountryCode;
+    inactive?: boolean;
+  }
+
+  export interface Launches extends RLLBaseQueryConfig {
+    cospar_id?: string;
+    after_date?: Date | string;
+    before_date?: Date | string;
+    modified_since?: Date | string;
+    location_id?: number | string;
+    pad_id?: number | string;
+    provider_id?: number | string;
+    tag_id?: number | string;
+    vehicle_id?: number | string;
+    state_abbr?: ISO3166Alpha2.StateCodeUS;
+    country_code?: ISO3166Alpha2.CountryCode;
+    search?: string | number;
+    slug?: string | number;
+  }
+
+  export interface Locations extends RLLBaseQueryConfig {
+    name?: string | number;
+    state_abbr?: ISO3166Alpha2.StateCodeUS;
+    country_code?: ISO3166Alpha2.CountryCode;
+  }
+
+  export interface Missions extends RLLBaseQueryConfig {
+    name?: string | number;
+  }
+
+  export interface Pads extends RLLBaseQueryConfig {
+    name?: string | number;
+    state_abbr?: ISO3166Alpha2.StateCodeUS;
+    country_code?: ISO3166Alpha2.CountryCode;
+  }
+
+  export interface Tags extends RLLBaseQueryConfig {
+    text?: string | number;
+  }
+
+  export interface Vehicles extends RLLBaseQueryConfig {
+    name?: string | number;
+  }
+
+  export interface All
+    extends Companies,
+      Launches,
+      Locations,
+      Missions,
+      Pads,
+      Tags,
+      Vehicles {}
+}
+
+export type RLLClientOptions = {
+  keyInQueryParams?: boolean;
+};
+
+export type RLLResponse<T> = {
+  errors?: string[];
+  valid_auth: boolean;
+  count: number;
+  limit: number;
+  total: number;
+  last_page: number;
+  result: T;
+};