eve-esi-types 1.0.0 → 1.1.0

package/README.md

@@ -1,2 +1,38 @@
-# eve-esi-types
-Extracted the main type of ESI. use for ESI request response types
+# eve-esi-types (version 1)
+
+Extracted the main type of ESI. Used for ESI request response types.
+
++ Version 1 makes it somewhat easier to handle types,
+
+  but as a trade-off, it does not support query parameter completion etc.
+
+## Usage
+
+> This package is configured to use version 1 only.
+
+  + If you need to use version 2, please refer to the following link:  
+    [eve-esi-types v2](https://github.com/jeffy-g/eve-esi-types)
+
+
+> Sample code is provided -> [`esi-request.mjs`](./esi-request.mjs)
+
+```shell
+$ node esi-request.mjs
+```
+## API
+
+> The following function signature allows you to benefit from `eve-esi-types`.  
+> By specifying the method (`get`, `post`, `put`, `delete`) for each `endpoint`,  
+> you can determine the result type of the ESI request.
+
+```ts
+// function signature
+export async function fire<
+    M extends TRequestMethod,
+    EP extends keyof TESIResponseOKMap[M],
+    Opt extends number | number[] | ESIRequestOptions,
+    R extends TESIResponseOKMap[M][EP]
+>(
+    mthd: M, endp: EP, pathParams?: Opt, opt?: ESIRequestOptions
+): Promise<R>;
+```

package/esi-request.d.mts

@@ -0,0 +1,58 @@
+/*!
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+  Released under the MIT license
+  https://opensource.org/licenses/mit-license.php
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+import type { TESIResponseOKMap } from "./src";
+type TRequestMethod = "get" | "post" | "put" | "delete";
+/**
+ * __{Header}.{Payload}.{Signature}__
+ */
+type TAcccessToken = `${string}.${string}.${string}`;
+type ESIRequestOptions = {
+    /**
+     * query params for ESI request.
+     */
+    query?: Record<string, any>;
+    /**
+     * will need it for `POST` request etc.
+     */
+    body?: any;
+    /**
+     * if want response data with ignore error then can be set to `true`.
+     */
+    ignoreError?: boolean;
+    /**
+     * cancel request immediately
+     */
+    cancelable?: AbortController;
+    /**
+     * Can be an empty object if no authentication is required.description
+     */
+    token?: TAcccessToken;
+};
+/**
+ * fire ESI request
+ * @template {"get" | "post" | "put" | "delete"} M
+ * @template {keyof TESIResponseOKMap[M]} EP
+ * @template {number | number[] | ESIRequestOptions} Opt
+ * @template {TESIResponseOKMap[M][EP]} R
+ *
+ * @param {M} mthd
+ * @param {EP} endp - The endpoint to request.
+ * @param {Opt} [pathParams] - Optional path parameters.
+ * @param {ESIRequestOptions} [opt] - default is empty object {}. `body` is json string
+ * @returns {Promise<R>} - The response from the endpoint.
+ * @throws
+ * @async
+ */
+export declare function fire<
+    M extends TRequestMethod,
+    EP extends keyof TESIResponseOKMap[M],
+    Opt extends number | number[] | ESIRequestOptions,
+    R extends TESIResponseOKMap[M][EP]
+>(
+    mthd: M, endp: EP, pathParams?: Opt, opt?: ESIRequestOptions
+): Promise<R>;

package/esi-request.mjs

@@ -0,0 +1,284 @@
+// import type { TESIResponseOKMap } from "eve-esi-types";
+// - - - - - - - - - - - - - - - - - - - -
+//           constants, types
+// - - - - - - - - - - - - - - - - - - - -
+// shorthands
+const log = console.log;
+const isArray = Array.isArray;
+/**
+ * enable/disable console.log
+ */
+let LOG = false;
+/**
+ * this always `https://esi.evetech.net`
+ */
+const BASE = "https://esi.evetech.net";
+/**
+ * @typedef {import("./src").TESIResponseOKMap} TESIResponseOKMap
+ * @typedef {`${string}.${string}.${string}`} TAcccessToken __{Header}.{Payload}.{Signature}__
+ */
+/**
+ * @typedef ESIRequestOptions
+ * @prop {Record<string, any>} [query] query params for ESI request.
+ * @prop {any} [body] will need it for `POST` request etc.
+ * @prop {boolean} [ignoreError]  if want response data with ignore error then can be set to `true`.
+ * @prop {AbortController} [cancelable] cancel request immediately
+ * @prop {TAcccessToken} [token] Can be an empty object if no authentication is required.description
+ */
+// - - - - - - - - - - - - - - - - - - - -
+//        module vars, functions
+// - - - - - - - - - - - - - - - - - - - -
+/**
+ * Get the number of currently executing ESI requests
+ */
+let ax = 0;
+/**
+ * simple named error class.
+ */
+class ESIRequesError extends Error {
+}
+/**
+ * throws when x-esi-error-limit-remain header value is "0". (http status: 420)
+ */
+class ESIErrorLimitReachedError extends Error {
+    constructor() {
+        super("Cannot continue ESI request because 'x-esi-error-limit-remain' is zero!");
+    }
+    valueOf() {
+        return 420;
+    }
+}
+/**
+ * fetch the extra pages
+ *
+ *   + if the `x-pages` header property ware more than 1
+ *
+ * @param {string} endpointUrl
+ * @param {RequestInit} rqopt request options
+ * @param {Record<string, any>} qs queries
+ * @param {number} pc pageCount
+ */
+const fetchP = async (endpointUrl, rqopt, qs, pc) => {
+    const rqs = [];
+    const rqp = new URLSearchParams(qs);
+    for (let i = 2; i <= pc;) {
+        rqp.set("page", (i++) + "");
+        ax++;
+        rqs.push(fetch(`${endpointUrl}?${rqp + ""}`, rqopt).then(res => res.json()).catch(reason => {
+            console.warn(reason);
+            return [];
+        }).finally(() => {
+            ax--;
+        }));
+    }
+    return Promise.all(rqs).then(jsons => {
+        // DEVNOTE: let check the page 2, type is array?
+        if (isArray(jsons[0])) {
+            let combined = [];
+            for (let i = 0, end = jsons.length; i < end;) {
+                combined = combined.concat(jsons[i++]);
+            }
+            return combined;
+        }
+        LOG && log("> > > pages result are object < < < --", jsons);
+        return null;
+    });
+};
+/** ### replace (C)urly (B)races (T)oken
+ *
+ * @example
+ * "/characters/{character_id}/skills"
+ * // ->
+ * "/characters/<char.character_id>/skills"
+ *
+ * @param {string} endpoint e.g - "/characters/{character_id}/"
+ * @param {number[]} ids
+ * @returns fragment of qualified endpoint uri or null.
+ */
+const replaceCbt = (endpoint, ids) => {
+    const re = /{([\w]+)}/g;
+    /** @type {RegExpExecArray?} */
+    let m;
+    let idx = 0;
+    while (m = re.exec(endpoint)) {
+        endpoint = endpoint.replace(m[0], ids[idx++] + "");
+    }
+    return endpoint;
+};
+/**
+ *
+ * @param {string} endp this means endpoint url fragment like `/characters/{character_id}/` or `/characters/{character_id}/agents_research/`
+ *   + The version parameter can be omitted by using `<version>/<endpoint>`
+ */
+const curl = (endp) => {
+    endp = endp.replace(/^\/+|\/+$/g, "");
+    return `${BASE}/latest/${endp}/`;
+};
+// - - - - - - - - - - - - - - - - - - - -
+//            main functions
+// - - - - - - - - - - - - - - - - - - - -
+/**
+ * fire ESI request
+ * @template {"get" | "post" | "put" | "delete"} M
+ * @template {keyof TESIResponseOKMap[M]} EP
+ * @template {number | number[] | ESIRequestOptions} Opt
+ * @template {TESIResponseOKMap[M][EP]} R
+ *
+ * @param {M} mthd
+ * @param {EP} endp - The endpoint to request.
+ * @param {Opt} [pathParams] - Optional path parameters.
+ * @param {ESIRequestOptions} [opt] - default is empty object {}. `body` is json string
+ * @returns {Promise<R>} - The response from the endpoint.
+ * @throws
+ * @async
+ */
+export async function fire(mthd, endp, pathParams, opt = {}) {
+    if (typeof pathParams === "number") {
+        // @ts-expect-error 
+        pathParams = [pathParams];
+    }
+    if (isArray(pathParams)) {
+        // @ts-ignore actualy endp is string
+        endp = replaceCbt(endp, pathParams);
+    }
+    else {
+        // When only options are provided
+        opt = /** @type {ESIRequestOptions} */ (pathParams) || opt;
+    }
+    /** @type {RequestInit} */
+    const rqopt = {
+        method: mthd,
+        mode: "cors",
+        cache: "no-cache",
+        signal: opt.cancelable?.signal,
+        headers: {}
+    };
+    const qss = {
+    // language: "en",
+    };
+    if (opt.query) {
+        // Object.assign(queries, options.queries); Object.assign is too slow
+        const oqs = opt.query;
+        for (const k of Object.keys(oqs)) {
+            qss[k] = oqs[k];
+        }
+    }
+    // DEVNOTE: when datasource is not empty string. (e.g - "singularity"
+    // in this case must specify datasource.
+    // disabled since `REMOVING DATASOURCE SINGULARITY`
+    // if (opt.datasource === "singularity") {
+    //     opt.datasource = "tranquility";
+    // }
+    if (opt.token) {
+        // @ts-ignore The header is indeed an object
+        rqopt.headers.authorization = `Bearer ${opt.token}`;
+    }
+    if (opt.body) { // means "POST" method etc
+        // @ts-ignore The header is indeed an object
+        rqopt.headers["content-type"] = "application/json";
+        rqopt.body = JSON.stringify(opt.body);
+    }
+    // @ts-ignore actualy endp is string
+    const endpointUrl = curl(endp);
+    ax++;
+    try {
+        // @ts-ignore A silly type error will appear, but ignore it.
+        const res = await fetch(`${endpointUrl}?${new URLSearchParams(qss) + ""}`, rqopt).finally(() => {
+            ax--;
+        });
+        const stat = res.status;
+        if (!res.ok && !opt.ignoreError) {
+            if (stat === 420) {
+                opt.cancelable && opt.cancelable.abort();
+                throw new ESIErrorLimitReachedError();
+            }
+            else {
+                // @ts-ignore actualy endp is string
+                throw new ESIRequesError(`maybe network disconneted or otherwise request data are invalid. (endpoint=${endp}, http status=${stat})`);
+            }
+        }
+        else {
+            // DEVNOTE: - 204 No Content
+            if (stat === 204) {
+                // this result is empty, decided to return status code.
+                return /** @type {R} */ ({ status: stat });
+            }
+            /** @type {R} */
+            const data = await res.json();
+            if (opt.ignoreError) {
+                // meaning `forceJson`?
+                return data;
+            }
+            // - - - - x-pages response.
+            // +undefined is NaN
+            // @ts-ignore becouse +null is 0
+            const pc = +res.headers.get("x-pages");
+            // has remaining pages? NaN > 1 === false !isNaN(pageCount)
+            if (pc > 1) {
+                LOG && log('found "x-pages" header, pages: %d', pc);
+                const remData = await fetchP(endpointUrl, rqopt, qss, pc);
+                // finally, decide product data.
+                if (isArray(data) && isArray(remData)) {
+                    // DEVNOTE: 2019/7/23 15:01:48 - types
+                    return /** @type {R} */ (data.concat(remData));
+                }
+                else {
+                    // @ts-ignore TODO: fix type
+                    remData && Object.assign(data, remData);
+                }
+            }
+            return data;
+        }
+    }
+    catch (e) {
+        // @ts-ignore actualy endp is string
+        throw new ESIRequesError(`unknown error occurred, message: ${e.message}, endpoint=${endp}`);
+    }
+}
+// It should complete correctly.
+async function getEVEStatus() {
+    try {
+        const ok = await fire("get", "/characters/{character_id}/ship/", 994562, {
+            // This token is completely random, but a simple check can be done with type TAcccessToken
+            token: "eyJhbGciOiJIjoiSldUIn0.YDbHqu0xPwtK5eTER7aPl8I0oYC.YDbHqu0xPwtK5eTER7aPl8I0oYC"
+        });
+        // query patameter `filter` is optional
+        // Version 1 makes it somewhat easier to handle types,
+        // but as a trade-off, it does not support query parameter completion.
+        await fire("get", "/universe/structures/", {
+            query: {
+                filter: "market"
+            }
+        });
+        // in this case, "categories" and "search" is required
+        await fire("get", "/characters/{character_id}/search/", 994562, {
+            query: {
+                categories: ["agent"],
+                search: "ok"
+            },
+            token: "eyJhbGciOiJIjoiSldUIn0.YDbHqu0xPwtK5eTER7aPl8I0oYC.YDbHqu0xPwtK5eTER7aPl8I0oYC"
+        });
+        // in this case, "order_type" is required
+        await fire("get", "/markets/{region_id}/orders/", 994562, {
+            query: {
+                order_type: "all"
+            },
+        });
+        // TODO: want TypeScript semantics to throw an error because there is a required query parameter, but it's not possible
+        await fire("get", "/characters/{character_id}/search/");
+        console.log(ok);
+    }
+    catch (error) {
+        console.error("Failed to get character ship -", error);
+    }
+    return fire("get", "/status/");
+}
+// type following and run
+// node esi-request.mjs
+// or yarn test
+getEVEStatus().then(eveStatus => console.log(eveStatus));
+// {
+//     "players": 16503,
+//     "server_version": "2794925",
+//     "start_time": "2025-01-21T11:02:34Z"
+// }

package/package.json

@@ -1,15 +1,24 @@
 {
   "name": "eve-esi-types",
-  "version": "1.0.0",
-  "description": "Extracted the main type of ESI. use for ESI request response types",
+  "version": "1.1.0",
+  "description": "Extracted the main type of ESI. use for ESI request response types (version 1 only)",
   "main": "src/index.d.ts",
   "scripts": {
-    "test": "echo ok?"
+    "test": "node esi-request.mjs"
   },
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com/jeffy-g/eve-esi-types.git"
   },
+  "files": [
+    "src",
+    "esi-request.mjs",
+    "esi-request.d.mts",
+    "LICENSE",
+    "*.md",
+    "package.json",
+    "tsconfig.json"
+  ],
   "keywords": [
     "eve",
     "esi",

package/src/get_alliances_alliance_id_contacts_labels_ok.d.ts

@@ -1,15 +1,6 @@
-/**
+/*!
  * ESI endpoint: /alliances/{alliance_id}/contacts/labels/
  */
-
-/**
- * label_id integer
- */
-type GetAlliancesAllianceIdContactsLabelsLabelId = number;
-/**
- * label_name string
- */
-type GetAlliancesAllianceIdContactsLabelsLabelName = string;
 /**
  * 200 ok array
  *
@@ -21,7 +12,13 @@ type GetAlliancesAllianceIdContactsLabelsOk = GetAlliancesAllianceIdContactsLabe
  * 200 ok object
  */
 interface GetAlliancesAllianceIdContactsLabels_200Ok {
-  label_id: GetAlliancesAllianceIdContactsLabelsLabelId;
-  label_name: GetAlliancesAllianceIdContactsLabelsLabelName;
+  /**
+   * label_id integer
+   */
+  label_id: number;
+  /**
+   * label_name string
+   */
+  label_name: string;
   [k: string]: unknown | undefined;
 }

package/src/get_alliances_alliance_id_contacts_ok.d.ts

@@ -1,29 +1,10 @@
-/**
+/*!
  * ESI endpoint: /alliances/{alliance_id}/contacts/
  */
-
-/**
- * contact_id integer
- */
-type GetAlliancesAllianceIdContactsContactId = number;
 /**
  * contact_type string
  */
 type GetAlliancesAllianceIdContactsContactType = "character" | "corporation" | "alliance" | "faction";
-/**
- * Label IDs applied to the contact
- */
-type GetAlliancesAllianceIdContactsLabelId = number;
-/**
- * label_ids array
- *
- * @maxItems 63
- */
-type GetAlliancesAllianceIdContactsLabelIds = GetAlliancesAllianceIdContactsLabelId[];
-/**
- * Standing of the contact
- */
-type GetAlliancesAllianceIdContactsStanding = number;
 /**
  * 200 ok array
  *
@@ -35,9 +16,20 @@ type GetAlliancesAllianceIdContactsOk = GetAlliancesAllianceIdContacts_200Ok[];
  * 200 ok object
  */
 interface GetAlliancesAllianceIdContacts_200Ok {
-  contact_id: GetAlliancesAllianceIdContactsContactId;
+  /**
+   * contact_id integer
+   */
+  contact_id: number;
   contact_type: GetAlliancesAllianceIdContactsContactType;
-  label_ids?: GetAlliancesAllianceIdContactsLabelIds;
-  standing: GetAlliancesAllianceIdContactsStanding;
+  /**
+   * label_ids array
+   *
+   * @maxItems 63
+   */
+  label_ids?: number[];
+  /**
+   * Standing of the contact
+   */
+  standing: number;
   [k: string]: unknown | undefined;
 }

package/src/get_alliances_alliance_id_corporations_ok.d.ts

@@ -1,14 +1,9 @@
-/**
+/*!
  * ESI endpoint: /alliances/{alliance_id}/corporations/
  */
-
-/**
- * 200 ok integer
- */
-type GetAlliancesAllianceIdCorporations_200Ok = number;
 /**
  * 200 ok array
  *
  * @maxItems 1000
  */
-type GetAlliancesAllianceIdCorporationsOk = GetAlliancesAllianceIdCorporations_200Ok[];
+type GetAlliancesAllianceIdCorporationsOk = number[];

package/src/get_alliances_alliance_id_icons_ok.d.ts

@@ -1,21 +1,18 @@
-/**
+/*!
  * ESI endpoint: /alliances/{alliance_id}/icons/
  */
 
-/**
- * px128x128 string
- */
-type GetAlliancesAllianceIdIconsPx128X128 = string;
-/**
- * px64x64 string
- */
-type GetAlliancesAllianceIdIconsPx64X64 = string;
-
 /**
  * 200 ok object
  */
 interface GetAlliancesAllianceIdIconsOk {
-  px128x128?: GetAlliancesAllianceIdIconsPx128X128;
-  px64x64?: GetAlliancesAllianceIdIconsPx64X64;
+  /**
+   * px128x128 string
+   */
+  px128x128?: string;
+  /**
+   * px64x64 string
+   */
+  px64x64?: string;
   [k: string]: unknown | undefined;
 }

package/src/get_alliances_alliance_id_ok.d.ts

@@ -1,46 +1,38 @@
-/**
+/*!
  * ESI endpoint: /alliances/{alliance_id}/
  */
 
-/**
- * ID of the corporation that created the alliance
- */
-type GetAlliancesAllianceIdCreatorCorporationId = number;
-/**
- * ID of the character that created the alliance
- */
-type GetAlliancesAllianceIdCreatorId = number;
-/**
- * date_founded string
- */
-type GetAlliancesAllianceIdDateFounded = string;
-/**
- * the executor corporation ID, if this alliance is not closed
- */
-type GetAlliancesAllianceIdExecutorCorporationId = number;
-/**
- * Faction ID this alliance is fighting for, if this alliance is enlisted in factional warfare
- */
-type GetAlliancesAllianceIdFactionId = number;
-/**
- * the full name of the alliance
- */
-type GetAlliancesAllianceIdName = string;
-/**
- * the short name of the alliance
- */
-type GetAlliancesAllianceIdTicker = string;
-
 /**
  * 200 ok object
  */
 interface GetAlliancesAllianceIdOk {
-  creator_corporation_id: GetAlliancesAllianceIdCreatorCorporationId;
-  creator_id: GetAlliancesAllianceIdCreatorId;
-  date_founded: GetAlliancesAllianceIdDateFounded;
-  executor_corporation_id?: GetAlliancesAllianceIdExecutorCorporationId;
-  faction_id?: GetAlliancesAllianceIdFactionId;
-  name: GetAlliancesAllianceIdName;
-  ticker: GetAlliancesAllianceIdTicker;
+  /**
+   * ID of the corporation that created the alliance
+   */
+  creator_corporation_id: number;
+  /**
+   * ID of the character that created the alliance
+   */
+  creator_id: number;
+  /**
+   * date_founded string
+   */
+  date_founded: string;
+  /**
+   * the executor corporation ID, if this alliance is not closed
+   */
+  executor_corporation_id?: number;
+  /**
+   * Faction ID this alliance is fighting for, if this alliance is enlisted in factional warfare
+   */
+  faction_id?: number;
+  /**
+   * the full name of the alliance
+   */
+  name: string;
+  /**
+   * the short name of the alliance
+   */
+  ticker: string;
   [k: string]: unknown | undefined;
 }

package/src/get_alliances_ok.d.ts

@@ -1,14 +1,9 @@
-/**
+/*!
  * ESI endpoint: /alliances/
  */
-
-/**
- * 200 ok integer
- */
-type GetAlliances_200Ok = number;
 /**
  * 200 ok array
  *
  * @maxItems 5000
  */
-type GetAlliancesOk = GetAlliances_200Ok[];
+type GetAlliancesOk = number[];