eve-esi-types 2.1.2 → 2.2.0

package/README.md

@@ -6,7 +6,7 @@ Extracted the main type of ESI. Used for ESI request response types.
 > This package is configured to use version 2 only.
 
   + If you need to use version 1, please refer to the following link:  
-    [eve-esi-types v1](https://github.com/jeffy-g/eve-esi-types/tree/v1.1.0)
+    [eve-esi-types v1](https://github.com/jeffy-g/eve-esi-types/tree/version-1.x)
 
 
 > Sample code is provided -> [`v2.mjs`](./v2.mjs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-esi-types",
-  "version": "2.1.2",
+  "version": "2.2.0",
   "description": "Extracted the main type of ESI. use for ESI request response types (version 2 only)",
   "main": "v2/index.d.ts",
   "scripts": {
@@ -14,6 +14,8 @@
     "v2",
     "v2.mjs",
     "v2.d.mts",
+    "rq-util.mjs",
+    "rq-util.d.mts",
     "LICENSE",
     "*.md",
     "package.json",

package/rq-util.d.mts

@@ -0,0 +1,84 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file rq-util.d.mts
+ */
+/**
+ * this always `https://esi.evetech.net`
+ */
+export declare const BASE = "https://esi.evetech.net";
+export type Truthy = string | number | boolean;
+/**
+ * __{Header}.{Payload}.{Signature}__
+ */
+export type TAcccessToken = `${string}.${string}.${string}`;
+export 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;
+    auth?: true;
+};
+/**
+ * simple named error class.
+ */
+export declare class ESIRequesError extends Error {
+}
+/**
+ * throws when x-esi-error-limit-remain header value is "0". (http status: 420)
+ */
+export declare class ESIErrorLimitReachedError extends ESIRequesError {
+    constructor();
+    valueOf(): number;
+}
+/**
+ * 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
+ * @param {(minus?: number) => void=} increment
+ */
+export declare const fetchP: <T extends unknown>(endpointUrl: string, rqopt: RequestInit, qs: Record<string, any>, pc: number, increment?: (minus?: Truthy) => void) => Promise<T | 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.
+ */
+export declare const replaceCbt: (endpoint: string, ids: number[]) => string;
+/**
+ *
+ * @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>`
+ */
+export declare const curl: (endp: string) => string;

package/rq-util.mjs

@@ -0,0 +1,107 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * @file rq-util.d.mts
+ */
+// - - - - - - - - - - - - - - - - - - - -
+//           constants, types
+// - - - - - - - - - - - - - - - - - - - -
+// shorthands
+const log = console.log;
+const isArray = Array.isArray;
+/**
+ * enable/disable console.log
+ */
+let LOG = false;
+/**
+ * this always `https://esi.evetech.net`
+ */
+export const BASE = "https://esi.evetech.net";
+/**
+ * simple named error class.
+ */
+export class ESIRequesError extends Error {
+}
+/**
+ * throws when x-esi-error-limit-remain header value is "0". (http status: 420)
+ */
+export class ESIErrorLimitReachedError extends ESIRequesError {
+    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
+ * @param {(minus?: number) => void=} increment
+ */
+export const fetchP = async (endpointUrl, rqopt, qs, pc, increment = () => { }) => {
+    const rqs = [];
+    const rqp = new URLSearchParams(qs);
+    for (let i = 2; i <= pc;) {
+        rqp.set("page", (i++) + "");
+        increment();
+        rqs.push(fetch(`${endpointUrl}?${rqp + ""}`, rqopt).then(res => res.json()).catch(reason => {
+            console.warn(reason);
+            return [];
+        }).finally(() => {
+            increment(1);
+        }));
+    }
+    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.
+ */
+export 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>`
+ */
+export const curl = (endp) => {
+    endp = endp.replace(/^\/+|\/+$/g, "");
+    return `${BASE}/latest/${endp}/`;
+};

package/v2/get_alliances_alliance_id_contacts_labels_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /alliances/{alliance_id}/contacts/labels/
+ * ESI endpoint: get:/alliances/{alliance_id}/contacts/labels/
  */
 /**
  * 200 ok array

package/v2/get_alliances_alliance_id_contacts_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /alliances/{alliance_id}/contacts/
+ * ESI endpoint: get:/alliances/{alliance_id}/contacts/
  */
 /**
  * contact_type string

package/v2/get_alliances_alliance_id_corporations_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /alliances/{alliance_id}/corporations/
+ * ESI endpoint: get:/alliances/{alliance_id}/corporations/
  */
 /**
  * 200 ok array

package/v2/get_alliances_alliance_id_icons_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /alliances/{alliance_id}/icons/
+ * ESI endpoint: get:/alliances/{alliance_id}/icons/
  */
 
 /**

package/v2/get_alliances_alliance_id_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /alliances/{alliance_id}/
+ * ESI endpoint: get:/alliances/{alliance_id}/
  */
 
 /**

package/v2/get_alliances_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /alliances/
+ * ESI endpoint: get:/alliances/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_agents_research_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/agents_research/
+ * ESI endpoint: get:/characters/{character_id}/agents_research/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_assets_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/assets/
+ * ESI endpoint: get:/characters/{character_id}/assets/
  */
 /**
  * location_flag string

package/v2/get_characters_character_id_attributes_ok.d.ts

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

package/v2/get_characters_character_id_blueprints_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/blueprints/
+ * ESI endpoint: get:/characters/{character_id}/blueprints/
  */
 /**
  * Type of the location_id

package/v2/get_characters_character_id_bookmarks_folders_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/bookmarks/folders/
+ * ESI endpoint: get:/characters/{character_id}/bookmarks/folders/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_bookmarks_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/bookmarks/
+ * ESI endpoint: get:/characters/{character_id}/bookmarks/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_calendar_event_id_attendees_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/calendar/{event_id}/attendees/
+ * ESI endpoint: get:/characters/{character_id}/calendar/{event_id}/attendees/
  */
 /**
  * event_response string

package/v2/get_characters_character_id_calendar_event_id_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/calendar/{event_id}/
+ * ESI endpoint: get:/characters/{character_id}/calendar/{event_id}/
  */
 /**
  * owner_type string

package/v2/get_characters_character_id_calendar_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/calendar/
+ * ESI endpoint: get:/characters/{character_id}/calendar/
  */
 /**
  * event_response string

package/v2/get_characters_character_id_clones_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/clones/
+ * ESI endpoint: get:/characters/{character_id}/clones/
  */
 /**
  * location_type string

package/v2/get_characters_character_id_contacts_labels_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/contacts/labels/
+ * ESI endpoint: get:/characters/{character_id}/contacts/labels/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_contacts_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/contacts/
+ * ESI endpoint: get:/characters/{character_id}/contacts/
  */
 /**
  * contact_type string

package/v2/get_characters_character_id_contracts_contract_id_bids_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/contracts/{contract_id}/bids/
+ * ESI endpoint: get:/characters/{character_id}/contracts/{contract_id}/bids/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_contracts_contract_id_items_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/contracts/{contract_id}/items/
+ * ESI endpoint: get:/characters/{character_id}/contracts/{contract_id}/items/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_contracts_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/contracts/
+ * ESI endpoint: get:/characters/{character_id}/contracts/
  */
 /**
  * To whom the contract is available

package/v2/get_characters_character_id_corporationhistory_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/corporationhistory/
+ * ESI endpoint: get:/characters/{character_id}/corporationhistory/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_fatigue_ok.d.ts

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

package/v2/get_characters_character_id_fittings_ok.d.ts

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

package/v2/get_characters_character_id_fleet_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/fleet/
+ * ESI endpoint: get:/characters/{character_id}/fleet/
  */
 /**
  * Member’s role in fleet

package/v2/get_characters_character_id_fw_stats_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/fw/stats/
+ * ESI endpoint: get:/characters/{character_id}/fw/stats/
  */
 
 /**

package/v2/get_characters_character_id_implants_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/implants/
+ * ESI endpoint: get:/characters/{character_id}/implants/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_industry_jobs_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/industry/jobs/
+ * ESI endpoint: get:/characters/{character_id}/industry/jobs/
  */
 /**
  * status string

package/v2/get_characters_character_id_killmails_recent_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/killmails/recent/
+ * ESI endpoint: get:/characters/{character_id}/killmails/recent/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_location_ok.d.ts

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

package/v2/get_characters_character_id_loyalty_points_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/loyalty/points/
+ * ESI endpoint: get:/characters/{character_id}/loyalty/points/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_mail_labels_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/mail/labels/
+ * ESI endpoint: get:/characters/{character_id}/mail/labels/
  */
 /**
  * color string

package/v2/get_characters_character_id_mail_lists_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/mail/lists/
+ * ESI endpoint: get:/characters/{character_id}/mail/lists/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_mail_mail_id_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/mail/{mail_id}/
+ * ESI endpoint: get:/characters/{character_id}/mail/{mail_id}/
  */
 /**
  * recipient_type string

package/v2/get_characters_character_id_mail_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/mail/
+ * ESI endpoint: get:/characters/{character_id}/mail/
  */
 /**
  * recipient_type string

package/v2/get_characters_character_id_medals_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/medals/
+ * ESI endpoint: get:/characters/{character_id}/medals/
  */
 /**
  * graphics array

package/v2/get_characters_character_id_mining_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/mining/
+ * ESI endpoint: get:/characters/{character_id}/mining/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_notifications_contacts_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/notifications/contacts/
+ * ESI endpoint: get:/characters/{character_id}/notifications/contacts/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_notifications_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/notifications/
+ * ESI endpoint: get:/characters/{character_id}/notifications/
  */
 /**
  * sender_type string

package/v2/get_characters_character_id_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/
+ * ESI endpoint: get:/characters/{character_id}/
  */
 /**
  * gender string

package/v2/get_characters_character_id_online_ok.d.ts

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

package/v2/get_characters_character_id_opportunities_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/opportunities/
+ * ESI endpoint: get:/characters/{character_id}/opportunities/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_orders_history_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/orders/history/
+ * ESI endpoint: get:/characters/{character_id}/orders/history/
  */
 /**
  * Valid order range, numbers are ranges in jumps

package/v2/get_characters_character_id_orders_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/orders/
+ * ESI endpoint: get:/characters/{character_id}/orders/
  */
 /**
  * Valid order range, numbers are ranges in jumps

package/v2/get_characters_character_id_planets_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/planets/
+ * ESI endpoint: get:/characters/{character_id}/planets/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_planets_planet_id_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/planets/{planet_id}/
+ * ESI endpoint: get:/characters/{character_id}/planets/{planet_id}/
  */
 /**
  * links array

package/v2/get_characters_character_id_portrait_ok.d.ts

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

package/v2/get_characters_character_id_roles_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/roles/
+ * ESI endpoint: get:/characters/{character_id}/roles/
  */
 /**
  * role string

package/v2/get_characters_character_id_search_ok.d.ts

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

package/v2/get_characters_character_id_ship_ok.d.ts

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

package/v2/get_characters_character_id_skillqueue_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/skillqueue/
+ * ESI endpoint: get:/characters/{character_id}/skillqueue/
  */
 /**
  * 200 ok array

package/v2/get_characters_character_id_skills_ok.d.ts

@@ -1,5 +1,5 @@
 /*!
- * ESI endpoint: /characters/{character_id}/skills/
+ * ESI endpoint: get:/characters/{character_id}/skills/
  */
 /**
  * skills array