eve-esi-types 2.2.0 → 2.2.1

package/minimal-rq.d.mts

@@ -0,0 +1,26 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+import * as util from "./rq-util.mjs";
+/**
+ * @typedef {import("./v2").TESIResponseOKMap} TESIResponseOKMap
+ * @typedef {import("./rq-util.mjs").ESIRequestOptions} ESIRequestOptions
+ */
+/** #### Sample of `TESIRequestFunctionSignature`
+ *
+ * + This is a minimal implementation using `TESIRequestFunctionSignature`.
+ *   If the response contains "page", only the first page can be retrieved.
+ *
+ * @type {TESIRequestFunctionSignature<ESIRequestOptions>}
+ * @param method - The HTTP method to use for the request
+ * @param endpoint - The Path of the ESI endpoint to send the request to
+ * @param pathParams - An object of parameters to include in the request
+ * @param options - An object of options to include in the request
+ * @returns A Promise object containing the response data
+ * @throws {ESIRequesError}
+ */
+export declare const request: TESIRequestFunctionSignature<util.ESIRequestOptions>;

package/minimal-rq.mjs

@@ -0,0 +1,78 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/// <reference types="./v2"/>
+// - - - - - - - - - - - - - - - - - - - -
+//               imports
+// - - - - - - - - - - - - - - - - - - - -
+import * as util from "./rq-util.mjs";
+// - - - - - - - - - - - - - - - - - - - -
+//           constants, types
+// - - - - - - - - - - - - - - - - - - - -
+// shorthands
+const log = console.log;
+const DEBUG = util.isDebug();
+/**
+ * @typedef {import("./v2").TESIResponseOKMap} TESIResponseOKMap
+ * @typedef {import("./rq-util.mjs").ESIRequestOptions} ESIRequestOptions
+ */
+// - - - - - - - - - - - - - - - - - - - -
+//            main functions
+// - - - - - - - - - - - - - - - - - - - -
+// node scripts/minimal-rq.mjs
+/** #### Sample of `TESIRequestFunctionSignature`
+ *
+ * + This is a minimal implementation using `TESIRequestFunctionSignature`.
+ *   If the response contains "page", only the first page can be retrieved.
+ *
+ * @type {TESIRequestFunctionSignature<ESIRequestOptions>}
+ * @param method - The HTTP method to use for the request
+ * @param endpoint - The Path of the ESI endpoint to send the request to
+ * @param pathParams - An object of parameters to include in the request
+ * @param options - An object of options to include in the request
+ * @returns A Promise object containing the response data
+ * @throws {ESIRequesError}
+ */
+export const request = (method, endpoint, pathParams, opt) => {
+    if (typeof pathParams === "number") {
+        // @ts-ignore 
+        pathParams = [pathParams];
+    }
+    if (Array.isArray(pathParams)) {
+        // @ts-ignore actualy endp is string
+        endpoint = util.replaceCbt(endpoint, pathParams);
+    }
+    // When only options are provided
+    // @ts-ignore
+    const actualOpt = /** @type {ESIRequestOptions} */ (opt || pathParams || {});
+    const { rqopt, qss } = util.initOptions(method, actualOpt);
+    // @ts-ignore actualy endp is string
+    const endpointUrl = util.curl(endpoint);
+    const url = `${endpointUrl}?${new URLSearchParams(qss) + ""}`;
+    DEBUG && log(url);
+    return fetch(url, rqopt).then(res => res.json()).catch(reason => {
+        throw new util.ESIRequesError(reason.message ? reason.message : reason);
+    });
+};
+// It should complete correctly.
+/**
+ * @param {TESIRequestFunctionSignature<ESIRequestOptions>} fn
+ */
+async function getEVEStatus(fn) {
+    const sdeVersion = await util.getSDEVersion();
+    log(`sdeVersion: ${sdeVersion}`.blue);
+    await util.fireRequestsDoesNotRequireAuth(fn);
+    return fn("get", "/status/");
+}
+// type following and run
+// node minimal-rq.mjs
+getEVEStatus(request).then(eveStatus => log(eveStatus));
+// {
+//     "players": 16503,
+//     "server_version": "2794925",
+//     "start_time": "2025-01-21T11:02:34Z"
+// }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-esi-types",
-  "version": "2.2.0",
+  "version": "2.2.1",
   "description": "Extracted the main type of ESI. use for ESI request response types (version 2 only)",
   "main": "v2/index.d.ts",
   "scripts": {
@@ -12,10 +12,10 @@
   },
   "files": [
     "v2",
+    "*.d.mts",
     "v2.mjs",
-    "v2.d.mts",
     "rq-util.mjs",
-    "rq-util.d.mts",
+    "minimal-rq.mjs",
     "LICENSE",
     "*.md",
     "package.json",
@@ -35,5 +35,8 @@
   "bugs": {
     "url": "https://github.com/jeffy-g/eve-esi-types/issues"
   },
-  "homepage": "https://github.com/jeffy-g/eve-esi-types#readme"
+  "homepage": "https://github.com/jeffy-g/eve-esi-types#readme",
+  "devDependencies": {
+    "colors": "^1.4.0"
+  }
 }

package/rq-util.d.mts

@@ -5,9 +5,7 @@
 //  https://opensource.org/licenses/mit-license.php
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
-/**
- * @file rq-util.d.mts
- */
+import "colors";
 /**
  * this always `https://esi.evetech.net`
  */
@@ -38,6 +36,13 @@ export type ESIRequestOptions = {
      * Can be an empty object if no authentication is required.description
      */
     token?: TAcccessToken;
+    /**
+     * whether an authorization header is required
+     *
+     *   + When using the `Web Fetch API`, avoid extra `OPTIONS` requests and reduce extra http requests
+     *
+     * @date 2020/1/23
+     */
     auth?: true;
 };
 /**
@@ -52,6 +57,19 @@ export declare class ESIErrorLimitReachedError extends ESIRequesError {
     constructor();
     valueOf(): number;
 }
+/**
+ * @typedef {import("./rq-util.mjs").ESIRequestOptions} ESIRequestOptions
+ */
+export declare const isDebug: () => boolean;
+/**
+ * @param method
+ * @param opt
+ * @returns
+ */
+export declare const initOptions: (method: string, opt: ESIRequestOptions) => {
+    rqopt: RequestInit;
+    qss: Record<string, string>;
+};
 /**
  * fetch the extra pages
  *
@@ -82,3 +100,15 @@ export declare const replaceCbt: (endpoint: string, ids: number[]) => string;
  *   + The version parameter can be omitted by using `<version>/<endpoint>`
  */
 export declare const curl: (endp: string) => string;
+/**
+ * @date 2020/03/31
+ * @version 2.0 fix version date string problem (v1.0
+ * @type {() => Promise<string>}
+ */
+export declare function getSDEVersion(): Promise<string>;
+/**
+ * #### Fire a request that does not require authentication.
+ *
+ * @param {TESIRequestFunctionSignature<ESIRequestOptions>} fn
+ */
+export declare function fireRequestsDoesNotRequireAuth(fn: TESIRequestFunctionSignature<ESIRequestOptions>): Promise<void>;

package/rq-util.mjs

@@ -5,9 +5,10 @@
 //  https://opensource.org/licenses/mit-license.php
 // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
 */
-/**
- * @file rq-util.d.mts
- */
+// - - - - - - - - - - - - - - - - - - - -
+//               imports
+// - - - - - - - - - - - - - - - - - - - -
+import "colors";
 // - - - - - - - - - - - - - - - - - - - -
 //           constants, types
 // - - - - - - - - - - - - - - - - - - - -
@@ -38,6 +39,49 @@ export class ESIErrorLimitReachedError extends ESIRequesError {
         return 420;
     }
 }
+/**
+ * @typedef {import("./rq-util.mjs").ESIRequestOptions} ESIRequestOptions
+ */
+// - - - - - - - - - - - - - - - - - - - -
+//            utility functions
+// - - - - - - - - - - - - - - - - - - - -
+export const isDebug = () => {
+    return process.argv.includes("-debug");
+};
+/**
+ * @param method
+ * @param opt
+ * @returns
+ */
+export const initOptions = (method, opt) => {
+    /** @type {RequestInit} */
+    const rqopt = {
+        method,
+        mode: "cors",
+        cache: "no-cache",
+        // @ts-ignore 
+        signal: opt.cancelable?.signal,
+        headers: {}
+    };
+    const qss = {
+        language: "en",
+    };
+    if (opt.query) {
+        // Object.assign(query, options.query); Object.assign is too slow
+        const oqs = opt.query;
+        Object.keys(oqs).forEach(k => qss[k] = oqs[k]);
+    }
+    if (opt.auth) {
+        // @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);
+    }
+    return { rqopt, qss };
+};
 /**
  * fetch the extra pages
  *
@@ -105,3 +149,114 @@ export const curl = (endp) => {
     endp = endp.replace(/^\/+|\/+$/g, "");
     return `${BASE}/latest/${endp}/`;
 };
+/**
+ * @date 2020/03/31
+ * @version 2.0 fix version date string problem (v1.0
+ * @type {() => Promise<string>}
+ */
+export async function getSDEVersion() {
+    const sdeZipUrl = "https://eve-static-data-export.s3-eu-west-1.amazonaws.com/tranquility/sde.zip";
+    const date = await fetch(sdeZipUrl, { method: "head", mode: "cors" }).then((/** @type {Response} */ res) => res.headers.get("last-modified")).catch(reason => {
+        console.log(reason);
+        return new Date();
+    });
+    if (date) {
+        const YMD = new Date(date).toLocaleString(void 0, {
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            // DEVNOTE: 191215 - "-" character appeared in node v13.3.0 (maybe
+        }).replace(/(-|\/|:| )/g, (match, $1) => {
+            switch ($1) {
+                case "-":
+                case "/":
+                case ":": return "";
+                case " ": return "@";
+            }
+            return match;
+        });
+        return `sde-${YMD}-TRANQUILITY`;
+    }
+    else {
+        return "sde-202Xxxxx-TRANQUILITY";
+    }
+}
+// It should complete correctly.
+/**
+ * #### Fire a request that does not require authentication.
+ *
+ * @param {TESIRequestFunctionSignature<ESIRequestOptions>} fn
+ */
+export async function fireRequestsDoesNotRequireAuth(fn) {
+    const clog = console.log.bind(console, '- - -> Get the character data of "CCP Zoetrope"'.magenta);
+    const rlog = console.log.bind(console, '- - -> Run ESI request'.cyan);
+    try {
+        // - - - - - - - - - - - -
+        //       Character
+        // - - - - - - - - - - - -
+        // Here, I borrow data from "CCP Zoetrope".
+        clog();
+        await fn("get", "/characters/{character_id}/", 2112625428).then(log);
+        clog('(portrait)');
+        await fn("get", "/characters/{character_id}/portrait/", 2112625428).then(log);
+        clog('(affiliation)');
+        const affiliation = await fn("post", "/characters/affiliation/", { body: [2112625428] });
+        log(affiliation);
+        clog('(corporation)');
+        await fn("get", "/corporations/{corporation_id}/", affiliation[0].corporation_id).then(log);
+        rlog("get:/incursions/".green);
+        await fn("get", "/incursions/").then(log);
+        // - - - - - - - - - - - -
+        //     Miscellaneous
+        // - - - - - - - - - - - -
+        rlog("post:/universe/ids/".green);
+        const ids = await fn("post", "/universe/ids/", { body: ["the forge", "plex"] });
+        log(ids);
+        rlog(`get:/markets/${ids?.regions?.[0].id}/orders/?type_id=${ids?.inventory_types?.[0].id}, item PLEX`.green);
+        const orders = await fn("get", "/markets/{region_id}/orders/", ids?.regions?.[0].id, {
+            query: {
+                // page: 1,
+                order_type: "sell",
+                type_id: ids?.inventory_types?.[0].id
+            }
+        });
+        log(orders.sort((a, b) => a.price - b.price).slice(0, 5));
+        rlog("get:/universe/structures/?filter=market".green);
+        // query patameter `filter` is optional
+        const structures = await fn("get", "/universe/structures/", {
+            query: {
+                filter: "market"
+            }
+        });
+        log(`/universe/structures/[0]=${structures[0]}, length=${structures.length}`);
+        // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
+        //  The following is code to observe the behavior of completion by generics.
+        //  Authentication is required, so an error will occur.
+        // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
+        let ok = await fn("get", "/characters/{character_id}/ship/", 994562, {
+            auth: true,
+            ignoreError: true,
+            token: "token.token.token"
+        });
+        // in this case, "categories" and "search" is required
+        await fn("get", "/characters/{character_id}/search/", 994562, {
+            query: {
+                categories: ["agent"],
+                search: "ok"
+            },
+            auth: true
+        });
+        // in this case, "order_type" is required
+        await fn("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 fn("get", "/characters/{character_id}/search/");
+        log(ok);
+    }
+    catch (e) {
+        console.error("Failed to request -", e);
+    }
+}

package/tsconfig.json

@@ -4,6 +4,7 @@
     "skipDefaultLibCheck": true,
     "skipLibCheck": true,
     "declaration": true,
+    // "declarationDir": "./dts",
     "outDir": ".", 
     "target": "esnext",
     "module": "esnext",
@@ -13,11 +14,11 @@
     "strict": true,
     "moduleResolution": "node",
     "rootDirs": [
-      "./"
+      "./scripts"
     ]
   },
   "include": [
-    "./*.mts"
+    "./scripts/*.mts"
   ],
   "exclude": []
 }

package/v2/index.d.ts

@@ -9,7 +9,7 @@
  * THIS TSD IS AUTO GENERATED, DO NOT EDIT
  * 
  * @file eve-esi-types/v2/index.d.ts
- * @summary This file is auto-generated and defines version 2.2.0 of the EVE Online ESI response types.
+ * @summary This file is auto-generated and defines version 2.2.1 of the EVE Online ESI response types.
  */
 import "./get_alliances_ok.d.ts";
 import "./get_alliances_alliance_id_ok.d.ts";
@@ -205,6 +205,30 @@ type RequireThese<T, K extends keyof T> = T & Required<Pick<T, K>>;
 
 declare global {
 
+  /**
+   * ### ESI request function all in one signature
+   * 
+   * TESIRequestFunctionSignature is a type that defines the signature of an ESI request function.
+   * 
+   * This function sends a request to a specified endpoint and returns a response.
+   * 
+   * @template ActualOpt - The actual type of the option.  
+   *   Required parameters inferred by typescript are merged.
+   * @template M - The HTTP method to use for the request
+   * @template EP - The Path of the ESI endpoint to send the request to
+   * @template P2 - Parameters to include in the request
+   * @template Opt - Options to include in the request  
+   *   If there is a required parameter, its type will be merged with `ActualOpt`
+   * @template R - The response type
+   */
+  type TESIRequestFunctionSignature<ActualOpt> = <
+    M extends TESIEntryMethod,
+    EP extends keyof TESIResponseOKMap[M],
+    P2 extends IsParameterizedPath<EP, number | number[], Opt>,
+    Opt extends IdentifyParameters<TESIResponseOKMap[M][EP], ActualOpt>,
+    R extends InferESIResponseResult<M, EP>
+  >(method: M, endpoint: EP, pathParams?: P2, options?: Opt) => Promise<R>;
+
   /**
    * is parameterized path
    */

package/v2.mjs

@@ -1,5 +1,5 @@
 // import type { TESIResponseOKMap } from "eve-esi-types";
-import { curl, replaceCbt, fetchP, ESIRequesError, ESIErrorLimitReachedError } from "./rq-util.mjs";
+import { curl, fetchP, replaceCbt, getSDEVersion, ESIRequesError, initOptions, isDebug, ESIErrorLimitReachedError, fireRequestsDoesNotRequireAuth } from "./rq-util.mjs";
 // - - - - - - - - - - - - - - - - - - - -
 //           constants, types
 // - - - - - - - - - - - - - - - - - - - -
@@ -9,19 +9,10 @@ const isArray = Array.isArray;
 /**
  * enable/disable console.log
  */
-let LOG = false;
+let LOG = isDebug();
 /**
  * @typedef {import("./v2").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 {true=} [auth] Can be an empty object if no authentication is required.description
- * @prop {TAcccessToken} [token] Can be an empty object if no authentication is required.description
- * @prop {boolean} [ignoreError]  if want response data with ignore error then can be set to `true`.
- * @prop {AbortController} [cancelable] cancel request immediately
+ * @typedef {import("./rq-util.mjs").ESIRequestOptions} ESIRequestOptions
  */
 // - - - - - - - - - - - - - - - - - - - -
 //        module vars, functions
@@ -34,39 +25,6 @@ const incrementAx = (minus) => minus ? ax-- : ax++;
 // - - - - - - - - - - - - - - - - - - - -
 //            main functions
 // - - - - - - - - - - - - - - - - - - - -
-// It should complete correctly.
-async function getEVEStatus() {
-    try {
-        const ok = await fire("get", "/characters/{character_id}/ship/", 994562, { auth: true });
-        // query patameter `filter` is optional
-        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"
-            },
-            auth: true
-        });
-        // 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/");
-}
 /**
  * fire ESI request
  * @template {TESIEntryMethod} M
@@ -95,63 +53,32 @@ export async function fire(mthd, endp, pathParams, opt) {
     // When only options are provided
     /** @type {Opt} */
     // @ts-ignore
-    const actualOpt = pathParams || opt || {};
-    /** @type {RequestInit} */
-    const rqopt = {
-        method: mthd,
-        mode: "cors",
-        cache: "no-cache",
-        // @ts-ignore 
-        signal: actualOpt.cancelable?.signal,
-        headers: {}
-    };
-    const qss = {
-        language: "en",
-    };
-    if (actualOpt.query) {
-        // Object.assign(queries, options.queries); Object.assign is too slow
-        const oqs = actualOpt.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 (actualOpt.datasource === "singularity") {
-    //     actualOpt.datasource = "tranquility";
-    // }
-    if (actualOpt.auth) {
-        // @ts-ignore The header is indeed an object
-        rqopt.headers.authorization = `Bearer ${actualOpt.token}`;
-    }
-    if (actualOpt.body) { // means "POST" method etc
-        // @ts-ignore The header is indeed an object
-        rqopt.headers["content-type"] = "application/json";
-        rqopt.body = JSON.stringify(actualOpt.body);
-    }
+    const actualOpt = opt || pathParams || {};
+    const { rqopt, qss } = initOptions(mthd, actualOpt);
     // @ts-ignore actualy endp is string
     const endpointUrl = curl(endp);
+    const url = `${endpointUrl}?${new URLSearchParams(qss) + ""}`;
+    LOG && log(url);
     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;
+        const res = await fetch(url, rqopt).finally(() => ax--);
+        const { status } = res;
         if (!res.ok && !actualOpt.ignoreError) {
-            if (stat === 420) {
+            if (status === 420) {
                 actualOpt.cancelable && actualOpt.cancelable.abort();
                 throw new ESIErrorLimitReachedError();
             }
             else {
                 // console.log(res);
-                throw new ESIRequesError(`${res.statusText} (status=${stat})`);
+                throw new ESIRequesError(`${res.statusText} (status=${status})`);
             }
         }
         else {
             // DEVNOTE: - 204 No Content
-            if (stat === 204) {
+            if (status === 204) {
                 // this result is empty, decided to return status code.
-                return /** @type {R} */ ({ status: stat });
+                return /** @type {R} */ ({ status });
             }
             /** @type {R} */
             const data = await res.json();
@@ -185,10 +112,21 @@ export async function fire(mthd, endp, pathParams, opt) {
         throw new ESIRequesError(`message: ${e.message}, endpoint=${endp}`);
     }
 }
+// It should complete correctly.
+/**
+ * @param {TESIRequestFunctionSignature<ESIRequestOptions>} fn
+ */
+async function getEVEStatus(fn) {
+    const sdeVersion = await getSDEVersion();
+    log(`sdeVersion: ${sdeVersion}`.blue);
+    await fireRequestsDoesNotRequireAuth(fn);
+    return fn("get", "/status/");
+}
 // type following and run
+// bun scripts/v2.mts
 // node v2.mjs
-// or yarn test:v2
-getEVEStatus().then(eveStatus => console.log(eveStatus));
+// or yarn test
+getEVEStatus(fire).then(eveStatus => console.log(eveStatus));
 // {
 //     "players": 16503,
 //     "server_version": "2794925",