eve-esi-types 1.0.1 → 1.1.0

package/README.md

@@ -1,12 +1,38 @@
-# eve-esi-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
 
-> Sample code is provided -> [`esi-request.mjs`](./esi-request.mjs)
+> 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

@@ -15,14 +15,15 @@ let LOG = false;
 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>} [queries] query params for ESI request.
+ * @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 {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
  */
 // - - - - - - - - - - - - - - - - - - - -
 //        module vars, functions
@@ -120,11 +121,12 @@ const curl = (endp) => {
  * 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 {number | number[] | ESIRequestOptions} [pathParams] - Optional path parameters.
+ * @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
@@ -132,7 +134,8 @@ const curl = (endp) => {
  */
 export async function fire(mthd, endp, pathParams, opt = {}) {
     if (typeof pathParams === "number") {
-        pathParams = /** @type {number[]} */ ([pathParams]);
+        // @ts-expect-error 
+        pathParams = [pathParams];
     }
     if (isArray(pathParams)) {
         // @ts-ignore actualy endp is string
@@ -153,9 +156,9 @@ export async function fire(mthd, endp, pathParams, opt = {}) {
     const qss = {
     // language: "en",
     };
-    if (opt.queries) {
+    if (opt.query) {
         // Object.assign(queries, options.queries); Object.assign is too slow
-        const oqs = opt.queries;
+        const oqs = opt.query;
         for (const k of Object.keys(oqs)) {
             qss[k] = oqs[k];
         }
@@ -234,12 +237,45 @@ export async function fire(mthd, endp, pathParams, opt = {}) {
 }
 // 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
-// tsc
-// then run
 // node esi-request.mjs
+// or yarn test
 getEVEStatus().then(eveStatus => console.log(eveStatus));
 // {
 //     "players": 16503,

package/package.json

@@ -1,15 +1,24 @@
 {
   "name": "eve-esi-types",
-  "version": "1.0.1",
-  "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[];

package/src/get_characters_character_id_agents_research_ok.d.ts

@@ -1,27 +1,6 @@
-/**
+/*!
  * ESI endpoint: /characters/{character_id}/agents_research/
  */
-
-/**
- * agent_id integer
- */
-type GetCharactersCharacterIdAgentsResearchAgentId = number;
-/**
- * points_per_day number
- */
-type GetCharactersCharacterIdAgentsResearchPointsPerDay = number;
-/**
- * remainder_points number
- */
-type GetCharactersCharacterIdAgentsResearchRemainderPoints = number;
-/**
- * skill_type_id integer
- */
-type GetCharactersCharacterIdAgentsResearchSkillTypeId = number;
-/**
- * started_at string
- */
-type GetCharactersCharacterIdAgentsResearchStartedAt = string;
 /**
  * 200 ok array
  *
@@ -33,10 +12,22 @@ type GetCharactersCharacterIdAgentsResearchOk = GetCharactersCharacterIdAgentsRe
  * 200 ok object
  */
 interface GetCharactersCharacterIdAgentsResearch_200Ok {
-  agent_id: GetCharactersCharacterIdAgentsResearchAgentId;
-  points_per_day: GetCharactersCharacterIdAgentsResearchPointsPerDay;
-  remainder_points: GetCharactersCharacterIdAgentsResearchRemainderPoints;
-  skill_type_id: GetCharactersCharacterIdAgentsResearchSkillTypeId;
-  started_at: GetCharactersCharacterIdAgentsResearchStartedAt;
+  /**
+   * agent_id integer
+   */
+  agent_id: number;
+  /**
+   * points_per_day number
+   */
+  points_per_day: number;
+  /**
+   * remainder_points number
+   */
+  remainder_points: number;
+  skill_type_id: number;
+  /**
+   * started_at string
+   */
+  started_at: string;
   [k: string]: unknown | undefined;
 }

package/src/get_characters_character_id_assets_ok.d.ts

@@ -1,19 +1,6 @@
-/**
+/*!
  * ESI endpoint: /characters/{character_id}/assets/
  */
-
-/**
- * is_blueprint_copy boolean
- */
-type GetCharactersCharacterIdAssetsIsBlueprintCopy = boolean;
-/**
- * is_singleton boolean
- */
-type GetCharactersCharacterIdAssetsIsSingleton = boolean;
-/**
- * item_id integer
- */
-type GetCharactersCharacterIdAssetsItemId = number;
 /**
  * location_flag string
  */
@@ -105,22 +92,10 @@ type GetCharactersCharacterIdAssetsLocationFlag =
   | "SubSystemSlot7"
   | "Unlocked"
   | "Wardrobe";
-/**
- * location_id integer
- */
-type GetCharactersCharacterIdAssetsLocationId = number;
 /**
  * location_type string
  */
 type GetCharactersCharacterIdAssetsLocationType = "station" | "solar_system" | "item" | "other";
-/**
- * quantity integer
- */
-type GetCharactersCharacterIdAssetsQuantity = number;
-/**
- * type_id integer
- */
-type GetCharactersCharacterIdAssetsTypeId = number;
 /**
  * 200 ok array
  *
@@ -132,13 +107,28 @@ type GetCharactersCharacterIdAssetsOk = GetCharactersCharacterIdAssets_200Ok[];
  * 200 ok object
  */
 interface GetCharactersCharacterIdAssets_200Ok {
-  is_blueprint_copy?: GetCharactersCharacterIdAssetsIsBlueprintCopy;
-  is_singleton: GetCharactersCharacterIdAssetsIsSingleton;
-  item_id: GetCharactersCharacterIdAssetsItemId;
+  /**
+   * is_blueprint_copy boolean
+   */
+  is_blueprint_copy?: boolean;
+  /**
+   * is_singleton boolean
+   */
+  is_singleton: boolean;
+  /**
+   * item_id integer
+   */
+  item_id: number;
   location_flag: GetCharactersCharacterIdAssetsLocationFlag;
-  location_id: GetCharactersCharacterIdAssetsLocationId;
+  /**
+   * location_id integer
+   */
+  location_id: number;
   location_type: GetCharactersCharacterIdAssetsLocationType;
-  quantity: GetCharactersCharacterIdAssetsQuantity;
-  type_id: GetCharactersCharacterIdAssetsTypeId;
+  /**
+   * quantity integer
+   */
+  quantity: number;
+  type_id: number;
   [k: string]: unknown | undefined;
 }

package/src/get_characters_character_id_attributes_ok.d.ts

@@ -1,51 +1,42 @@
-/**
+/*!
  * ESI endpoint: /characters/{character_id}/attributes/
  */
 
-/**
- * Neural remapping cooldown after a character uses remap accrued over time
- */
-type GetCharactersCharacterIdAttributesAccruedRemapCooldownDate = string;
-/**
- * Number of available bonus character neural remaps
- */
-type GetCharactersCharacterIdAttributesBonusRemaps = number;
-/**
- * charisma integer
- */
-type GetCharactersCharacterIdAttributesCharisma = number;
-/**
- * intelligence integer
- */
-type GetCharactersCharacterIdAttributesIntelligence = number;
-/**
- * Datetime of last neural remap, including usage of bonus remaps
- */
-type GetCharactersCharacterIdAttributesLastRemapDate = string;
-/**
- * memory integer
- */
-type GetCharactersCharacterIdAttributesMemory = number;
-/**
- * perception integer
- */
-type GetCharactersCharacterIdAttributesPerception = number;
-/**
- * willpower integer
- */
-type GetCharactersCharacterIdAttributesWillpower = number;
-
 /**
  * 200 ok object
  */
 interface GetCharactersCharacterIdAttributesOk {
-  accrued_remap_cooldown_date?: GetCharactersCharacterIdAttributesAccruedRemapCooldownDate;
-  bonus_remaps?: GetCharactersCharacterIdAttributesBonusRemaps;
-  charisma: GetCharactersCharacterIdAttributesCharisma;
-  intelligence: GetCharactersCharacterIdAttributesIntelligence;
-  last_remap_date?: GetCharactersCharacterIdAttributesLastRemapDate;
-  memory: GetCharactersCharacterIdAttributesMemory;
-  perception: GetCharactersCharacterIdAttributesPerception;
-  willpower: GetCharactersCharacterIdAttributesWillpower;
+  /**
+   * Neural remapping cooldown after a character uses remap accrued over time
+   */
+  accrued_remap_cooldown_date?: string;
+  /**
+   * Number of available bonus character neural remaps
+   */
+  bonus_remaps?: number;
+  /**
+   * charisma integer
+   */
+  charisma: number;
+  /**
+   * intelligence integer
+   */
+  intelligence: number;
+  /**
+   * Datetime of last neural remap, including usage of bonus remaps
+   */
+  last_remap_date?: string;
+  /**
+   * memory integer
+   */
+  memory: number;
+  /**
+   * perception integer
+   */
+  perception: number;
+  /**
+   * willpower integer
+   */
+  willpower: number;
   [k: string]: unknown | undefined;
 }