eve-esi-types 2.1.0 → 2.2.0

package/v2/post_characters_affiliation_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/affiliation/
+ * ESI endpoint: post:/characters/affiliation/
  */
 /**
  * 200 ok array

package/v2/post_characters_character_id_assets_locations_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/assets/locations/
+ * ESI endpoint: post:/characters/{character_id}/assets/locations/
  */
 /**
  * 200 ok array

package/v2/post_characters_character_id_assets_names_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/assets/names/
+ * ESI endpoint: post:/characters/{character_id}/assets/names/
  */
 /**
  * 200 ok array

package/v2/post_characters_character_id_contacts_created.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/contacts/
+ * ESI endpoint: post:/characters/{character_id}/contacts/
  */
 /**
  * 201 created array

package/v2/post_characters_character_id_cspa_created.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/cspa/
+ * ESI endpoint: post:/characters/{character_id}/cspa/
  */
 /**
  * 201 created number

package/v2/post_characters_character_id_fittings_created.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/fittings/
+ * ESI endpoint: post:/characters/{character_id}/fittings/
  */
 
 /**

package/v2/post_characters_character_id_mail_created.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/mail/
+ * ESI endpoint: post:/characters/{character_id}/mail/
  */
 /**
  * Mail ID

package/v2/post_characters_character_id_mail_labels_created.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/mail/labels/
+ * ESI endpoint: post:/characters/{character_id}/mail/labels/
  */
 /**
  * Label ID

package/v2/post_corporations_corporation_id_assets_locations_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /corporations/{corporation_id}/assets/locations/
+ * ESI endpoint: post:/corporations/{corporation_id}/assets/locations/
  */
 /**
  * 200 ok array

package/v2/post_corporations_corporation_id_assets_names_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /corporations/{corporation_id}/assets/names/
+ * ESI endpoint: post:/corporations/{corporation_id}/assets/names/
  */
 /**
  * 200 ok array

package/v2/post_fleets_fleet_id_wings_created.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /fleets/{fleet_id}/wings/
+ * ESI endpoint: post:/fleets/{fleet_id}/wings/
  */
 
 /**

package/v2/post_fleets_fleet_id_wings_wing_id_squads_created.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /fleets/{fleet_id}/wings/{wing_id}/squads/
+ * ESI endpoint: post:/fleets/{fleet_id}/wings/{wing_id}/squads/
  */
 
 /**

package/v2/post_universe_ids_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /universe/ids/
+ * ESI endpoint: post:/universe/ids/
  */
 
 /**

package/v2/post_universe_names_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /universe/names/
+ * ESI endpoint: post:/universe/names/
  */
 /**
  * category string

package/v2.d.mts

@@ -0,0 +1,32 @@
+/*!
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+  Released under the MIT license
+  https://opensource.org/licenses/mit-license.php
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+import type { TESIResponseOKMap } from "./v2";
+import { type ESIRequestOptions } from "./rq-util.mjs";
+/**
+ * fire ESI request
+ * @template {TESIEntryMethod} M
+ * @template {keyof TESIResponseOKMap[M]} EP
+ * @template {IsParameterizedPath<EP, number | number[], Opt>} P2
+ * @template {IdentifyParameters<TESIResponseOKMap[M][EP], ESIRequestOptions>} Opt
+ * @template {InferESIResponseResult<M, EP>} R
+ *
+ * @param {M} mthd
+ * @param {EP} endp - The endpoint to request.
+ * @param {Opt} [opt] - default is empty object {}. `body` is json string
+ * @param {P2} [pathParams] - Optional path parameters.
+ * @returns {Promise<R>} - The response from the endpoint.
+ * @throws
+ * @async
+ */
+export declare function fire<
+    M extends TESIEntryMethod,
+    EP extends keyof TESIResponseOKMap[M],
+    Opt extends IdentifyParameters<TESIResponseOKMap[M][EP], ESIRequestOptions>,
+    P2 extends IsParameterizedPath<EP, number | number[], Opt>,
+    R extends InferESIResponseResult<M, EP>
+>(mthd: M, endp: EP, pathParams?: P2, opt?: Opt): Promise<R>;

package/v2.mjs

@@ -1,4 +1,5 @@
 // import type { TESIResponseOKMap } from "eve-esi-types";
+import { curl, replaceCbt, fetchP, ESIRequesError, ESIErrorLimitReachedError } from "./rq-util.mjs";
 // - - - - - - - - - - - - - - - - - - - -
 //           constants, types
 // - - - - - - - - - - - - - - - - - - - -
@@ -9,19 +10,16 @@ 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("./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 {string} [token] 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
  */
@@ -32,88 +30,7 @@ const BASE = "https://esi.evetech.net";
  * 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}/`;
-};
+const incrementAx = (minus) => minus ? ax-- : ax++;
 // - - - - - - - - - - - - - - - - - - - -
 //            main functions
 // - - - - - - - - - - - - - - - - - - - -
@@ -141,6 +58,8 @@ async function getEVEStatus() {
                 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) {
@@ -158,8 +77,8 @@ async function getEVEStatus() {
  *
  * @param {M} mthd
  * @param {EP} endp - The endpoint to request.
- * @param {P2} [pathParams] - Optional path parameters.
  * @param {Opt} [opt] - default is empty object {}. `body` is json string
+ * @param {P2} [pathParams] - Optional path parameters.
  * @returns {Promise<R>} - The response from the endpoint.
  * @throws
  * @async
@@ -167,7 +86,7 @@ async function getEVEStatus() {
 export async function fire(mthd, endp, pathParams, opt) {
     if (typeof pathParams === "number") {
         // @ts-ignore 
-        pathParams = [pathParams];
+        pathParams = [pathParams]; // as unknown as P2;
     }
     if (isArray(pathParams)) {
         // @ts-ignore actualy endp is string
@@ -216,9 +135,7 @@ export async function fire(mthd, endp, pathParams, opt) {
     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 res = await fetch(`${endpointUrl}?${new URLSearchParams(qss) + ""}`, rqopt).finally(() => ax--);
         const stat = res.status;
         if (!res.ok && !actualOpt.ignoreError) {
             if (stat === 420) {
@@ -249,7 +166,7 @@ export async function fire(mthd, endp, pathParams, opt) {
             // 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);
+                const remData = await fetchP(endpointUrl, rqopt, qss, pc, incrementAx);
                 // finally, decide product data.
                 if (isArray(data) && isArray(remData)) {
                     // DEVNOTE: 2019/7/23 15:01:48 - types

package/esi-request.mjs

@@ -1,247 +0,0 @@
-// 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 ESIRequestOptions
- * @prop {Record<string, any>} [queries] 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 {string} [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 {TESIResponseOKMap[M][EP]} R
- *
- * @param {M} mthd
- * @param {EP} endp - The endpoint to request.
- * @param {number | number[] | ESIRequestOptions} [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") {
-        pathParams = /** @type {number[]} */ ([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.queries) {
-        // Object.assign(queries, options.queries); Object.assign is too slow
-        const oqs = opt.queries;
-        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() {
-    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/src/get_alliances_alliance_id_contacts_labels_ok.d.ts

@@ -1,27 +0,0 @@
-/**
- * ESI endpoint: /alliances/{alliance_id}/contacts/labels/
- */
-
-/**
- * label_id integer
- */
-type GetAlliancesAllianceIdContactsLabelsLabelId = number;
-/**
- * label_name string
- */
-type GetAlliancesAllianceIdContactsLabelsLabelName = string;
-/**
- * 200 ok array
- *
- * @maxItems 64
- */
-type GetAlliancesAllianceIdContactsLabelsOk = GetAlliancesAllianceIdContactsLabels_200Ok[];
-
-/**
- * 200 ok object
- */
-interface GetAlliancesAllianceIdContactsLabels_200Ok {
-  label_id: GetAlliancesAllianceIdContactsLabelsLabelId;
-  label_name: GetAlliancesAllianceIdContactsLabelsLabelName;
-  [k: string]: unknown | undefined;
-}

package/src/get_alliances_alliance_id_contacts_ok.d.ts

@@ -1,43 +0,0 @@
-/**
- * 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
- *
- * @maxItems 1000
- */
-type GetAlliancesAllianceIdContactsOk = GetAlliancesAllianceIdContacts_200Ok[];
-
-/**
- * 200 ok object
- */
-interface GetAlliancesAllianceIdContacts_200Ok {
-  contact_id: GetAlliancesAllianceIdContactsContactId;
-  contact_type: GetAlliancesAllianceIdContactsContactType;
-  label_ids?: GetAlliancesAllianceIdContactsLabelIds;
-  standing: GetAlliancesAllianceIdContactsStanding;
-  [k: string]: unknown | undefined;
-}

package/src/get_alliances_alliance_id_corporations_ok.d.ts

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

package/src/get_alliances_alliance_id_icons_ok.d.ts

@@ -1,21 +0,0 @@
-/**
- * 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;
-  [k: string]: unknown | undefined;
-}