eve-esi-types 3.2.0 → 3.2.2

package/CHANGELOG.md

@@ -2,18 +2,33 @@
 
 All notable changes to this project will be documented in this file.
 
-## [3.2.0] - 2025-4-17
+## [3.2.2] - 2025-04-21
 
-### Added
-- New experimental utility type `InferNextEndpoint` (beta).
+### 🚜 Refactor
+
+- *(types)* Make `NoContentResponse` a branded type
+- Move experimental types to experimental-esi-types.d.ts
+
+### ⚙️ Miscellaneous Tasks
 
-### Changed
-- Until now, DTS files were written for each method and endpoint,  
-  but from this version, DTS files are written collectively by "tag".
+- Bump version to v3.2.2
+
+## [3.2.1] - 2025-04-19
+
+### 🐛 Bug Fixes
+
+- Package.json "files"
+
+### 🚜 Refactor
+
+- *(types)* Consolidate redundant type definitions
+- *(types)* Improve clarity and validation in endpoint utility types
+
+### ⚙️ Miscellaneous Tasks
 
-### Maintenance
-- Confirmed removal of the unused "opportunities" ESI endpoint, as per official deprecation notice.
+- *(release)* V3.2.1
 
+## [3.2.0] - 2025-04-16
 
 ### ⚙️ Miscellaneous Tasks
 
@@ -142,7 +157,10 @@ All notable changes to this project will be documented in this file.
 
 ### ⚙️ Miscellaneous Tasks
 
+- Jsdoc etc
+- Move files
 - Jsdoc of `initOptions`, refactor `injectESIRequestBody`
+- Jsdoc
 - ESITagsWithMethodList -> ESITagMethodMapping
 - Apply `Object.freeze` to result of `injectESIRequestBody`
 - *(release)* V2.3.4 release
@@ -180,3 +198,4 @@ All notable changes to this project will be documented in this file.
 
 - Remove non-functional bookmarks endpoints in ESI
 
+<!-- generated by git-cliff -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eve-esi-types",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "description": "Extracted the main type of ESI. use for ESI request response types (version 2 only)",
   "main": "v2/index.d.ts",
   "scripts": {

package/v2/esi-tagged-types.d.ts

@@ -9,7 +9,7 @@
  * THIS DTS IS AUTO GENERATED, DO NOT EDIT
  * 
  * @file eve-esi-types/v2/esi-tagged-types.d.ts
- * @summary This file is auto-generated and defines version 3.2.0 of the EVE Online ESI response types.
+ * @summary This file is auto-generated and defines version 3.2.2 of the EVE Online ESI response types.
  */
 import type { TESIResponseOKMap } from "./index.d.ts";
 export type * from "./index.d.ts";

package/v2/experimental-esi-types.d.ts

@@ -0,0 +1,287 @@
+/*!
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+//  Copyright (C) 2025 jeffy-g <hirotom1107@gmail.com>
+//  Released under the MIT license
+//  https://opensource.org/licenses/mit-license.php
+// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
+*/
+/**
+ * THIS DTS IS AUTO GENERATED, DO NOT EDIT
+ * 
+ * @file eve-esi-types/v2/experimental-esi-types.d.ts
+ * @summary This file is auto-generated and defines version 3.2.2 of the EVE Online ESI response types.
+ */
+import type { _ESIResponseType, PickPathParameters, UnionToTuple, Split } from "./index.d.ts";
+
+/**
+ * Infers the response result type of an ESI endpoint based on a union of HTTP method and endpoint.
+ * 
+ * This utility type takes an endpoint union (`EPU`) in the format `${TESIEntryMethod}:${ESIEndpointAll}`
+ * and infers the response result type from the corresponding ESI response map.
+ * 
+ * @template EPU - A union of HTTP method and endpoint in the format `${TESIEntryMethod}:${ESIEndpointAll}`.
+ * 
+ * @remarks
+ * This type uses advanced TypeScript features such as template literal types and conditional types
+ * to infer the response result type of a given ESI endpoint.
+ * 
+ * @example
+ * ``` ts
+ * type ResponseResult = InferESIResponseResultFromUnion<"get:/characters/{character_id}/">;
+ * // Result: The inferred response result type for the given method and endpoint.
+ * ```
+ */
+export type InferESIResponseResultFromUnion<
+  EP extends unknown
+  // EP extends ESIEndpointUnions
+> = EP extends `${infer M}:${infer EPRest}`
+  /* ctt
+  ? M extends TESIEntryMethod
+    ? EPRest extends ESIEndpointOf<M>
+      ? _ESIResponseType<M, EPRest> extends { result: infer U }
+        ? U : never
+      : never
+    : never
+  : never;
+  /*/
+  ? EPRest extends (
+      M extends TESIEntryMethod ? ESIEndpointOf<M> : never
+    )
+    ? _ESIResponseType<M, EPRest> extends { result: infer U }
+      ? U : never
+    : never
+  : never;
+  //*/
+
+// - - - - - - - - - - - - - - - - - - - - - - - - - -
+//                    Next Endpoint
+// - - - - - - - - - - - - - - - - - - - - - - - - - -
+/**
+ * @experimental
+ * 
+ * Resolves the next applicable ESI endpoint based on the current endpoint and its response type.
+ * 
+ * This utility type determines which endpoints can be chained after the current endpoint (`EP`),
+ * based on the response type (`BaseResut`) and the URL pattern of potential next endpoints.
+ * 
+ * @template M - The HTTP method type (e.g., "get", "post", etc.), which must extend `TESIEntryMethod`.
+ * @template EP - The current ESI endpoint under inspection; it extends `ESIEndpointOf<M>`.
+ * @template BaseResut - Defaults to `InferESIResponseResult<M, EP>`; it is the inferred response result of the endpoint.
+ * @template Endpoints - Defaults to `ESIEndpointOf<M>`; represents the union of all endpoints for method `M` to be considered as potential next endpoints.
+ * 
+ * @remarks
+ * This type uses advanced TypeScript features such as conditional types, template literal types, and type inference
+ * to perform endpoint validation and chaining.
+ * 
+ * @example
+ * ```ts
+ * type NextEndpoint = ResolveNextEndpoint<"get", "/universe/graphics/">;
+ * // Result: Union of endpoints like "/universe/graphics/{graphic_id}/" if they match the template and response type constraint.
+ * ```
+ */
+export type ResolveNextEndpoint<
+  M extends TESIEntryMethod,
+  EP extends Exclude<ESIEndpointOf<M>, symbol> = Exclude<ESIEndpointOf<M>, symbol>,
+  BaseResut extends InferESIResponseResult<M, EP> = InferESIResponseResult<M, EP>,
+  // Endpoints extends ESIEndpointAll = ESIEndpointAll,
+  Endpoints extends ESIEndpointOf<M> = ESIEndpointOf<M>,
+> = {
+  [NextEP in Endpoints]: NextEP extends `${EP}${string}{${string}}/${string}`
+    ? ValidateNextEndpoint<BaseResut, NextEP> extends 1
+      ? NextEP : never
+      // ? [EP, NextEP, BaseResut] : never
+    : never;
+}[Endpoints];
+
+/**
+ * Resolves the next applicable ESI endpoint based on a union of HTTP method and endpoint.
+ * 
+ * This utility type determines which endpoints can be chained after the current endpoint (`EP`),
+ * based on the response type (`BaseResut`) and the URL pattern of potential next endpoints.
+ * 
+ * @template EPU - A union of HTTP method and endpoint in the format `${TESIEntryMethod}:${ESIEndpointAll}`.
+ * @template M - The HTTP method extracted from `EPU`.
+ * @template EP - The current endpoint extracted from `EPU`.
+ * @template BaseResut - The inferred response result of the endpoint.
+ * @template Endpoints - The union of all endpoints for the given method.
+ * 
+ * @remarks
+ * This type uses advanced TypeScript features such as conditional types and template literal types
+ * to infer the next valid endpoint based on the current endpoint and its response type.
+ * 
+ * @example
+ * ``` ts
+ * type NextEndpoint = ResolveNextEndpointFromUnion<"get:/universe/graphics/">;
+ * // Result: Union of endpoints like "/universe/graphics/{graphic_id}/" if they match the template and response type constraint.
+ * ```
+ */
+export type ResolveNextEndpointFromUnion<
+  EPU extends ESIEndpointUnions,
+  SplitM_EP = Split<EPU>,
+  M extends TESIEntryMethod = SplitM_EP[0],
+  EP extends Exclude<ESIEndpointOf<M>, symbol> = SplitM_EP[1],
+  BaseResut extends InferESIResponseResult<M, EP> = InferESIResponseResult<M, EP>,
+  Endpoints extends ESIEndpointOf<M> = ESIEndpointOf<M>,
+> = {
+  [NextEP in Endpoints]: NextEP extends `${EP}${string}{${string}}/${string}`
+    ? ValidateNextEndpoint<BaseResut, NextEP> extends 1
+      ? NextEP : never
+      // ? [EP, NextEP, BaseResut] : never
+    : never;
+}[Endpoints];
+
+/**
+ * Validates whether a given endpoint can be the next endpoint in a chain based on the response type of the current endpoint.
+ * 
+ * This utility type checks if the response type (`Entry`) of the current endpoint satisfies the requirements
+ * for the next endpoint (`NextEP`), such as having the necessary path parameters.
+ * 
+ * @template BaseResut - The response type of the current endpoint (e.g., `number[]` or an array of objects).
+ * @template NextEP - The next endpoint to validate.
+ * @template Debug - Optional debug flag; if set to `1`, additional debug information is returned.
+ * 
+ * @remarks
+ * This type assumes that if the response type is `number[]`, the next endpoint is always valid. For object arrays,
+ * it checks if the required path parameters can be inferred from the response type.
+ * 
+ * ```ts
+ * type IsValid = ValidateNextEndpoint<GetCharactersCharacterIdMailOk, "/characters/{character_id}/mail/{mail_id}/">;
+ * // or
+ * type IsValid = ValidateNextEndpoint<GetCharactersCharacterIdMail_200Ok[], "/characters/{character_id}/mail/{mail_id}/">;
+ * // Result: 1 if valid, 0 otherwise.
+ * ```
+ */
+export type ValidateNextEndpoint<
+  BaseResut extends unknown, // number[] or SomeType[]
+  NextEP extends string,
+  Debug = 0,
+> = 
+  // If it is simply a number[], it is unconditionally assumed that there is a next endpoint.
+  BaseResut extends number[] ? 1 : ValidateEndpointParamsInArray<BaseResut, NextEP, Debug>;
+
+/**
+ * Validates whether the elements of an object array satisfy the path parameter requirements
+ * for a given endpoint.
+ * 
+ * @template BaseResut - The response type of the current endpoint (e.g., an array of objects).
+ * @template NextEP - The next endpoint to validate.
+ * @template Debug - Optional debug flag; if set to `1`, additional debug information is returned.
+ * @template PathParams - Defaults to `UnionToTuple<PickPathParameters<NextEP>>`; represents the path parameters of the next endpoint.
+ * 
+ * @remarks
+ * This type assumes that if the response type is an array of objects, it checks whether the required
+ * path parameters can be inferred from the properties of the objects in the array.
+ * 
+ * @example
+ * ```ts
+ * type IsValid = ValidateEndpointParamsInArray<GetCharactersCharacterIdMailOk, "/characters/{character_id}/mail/{mail_id}/">;
+ * // or
+ * type IsValid = ValidateEndpointParamsInArray<GetCharactersCharacterIdMail_200Ok[], "/characters/{character_id}/mail/{mail_id}/">;
+ * // Result: 1 if valid, 0 otherwise.
+ * ```
+ */
+type ValidateEndpointParamsInArray<
+  BaseResut extends unknown, // SomeType[]
+  NextEP extends string,
+  Debug = 0,
+  PathParams = UnionToTuple<PickPathParameters<NextEP>>,
+> = BaseResut extends (infer O)[]
+  ? NonNullable<O[PathParams[1]]> extends number
+    ? Debug extends 1 // development
+      ? [O, PathParams] : 1
+    : 0
+  : 0;
+
+/**
+ * `ResolveNextEndpointLoos` is a utility type that infers the next endpoint based on the current endpoint and method.
+ * 
+ * DONE: 2025/4/11 15:45:01 
+ * ``` jsonc
+ * // Infer the next parameterized endpoint to request from the EP
+ * // Does not validate the EP result, just infers the next endpoint to request
+ * ```
+ * 
+ * @template M - The HTTP method to use for the request.
+ * @template EP - The endpoint from which the next parameterized endpoint to request is inferred.
+ * @template Endpoints - The possible endpoints for the given method.
+ * 
+ * ```ts
+ * type NextEndpoint = ResolveNextEndpointLoos<"get", "/markets/groups/">;
+ * // Result: "/markets/groups/{market_group_id}/"
+ * ```
+ * @remarks
+ * This type is useful for chaining requests or determining the next endpoint to call based on the current endpoint.
+ * It does not validate the response type of the endpoint, only the URL pattern.
+ */
+export type ResolveNextEndpointLoos<
+  M extends TESIEntryMethod,
+//* ctt
+  // DEVNOTE: As it turns out, the behavior of this utility type is broken unless you use the "skipLibCheck=true".
+  EP extends ESIEndpointOf<M> = ESIEndpointOf<M>,
+  Endpoints extends ESIEndpointOf<M> = ESIEndpointOf<M>,
+/*/
+  // This fix is required for skipLibCheck=false
+  EP extends Exclude<ESIEndpointOf<M>, symbol> = Exclude<ESIEndpointOf<M>, symbol>,
+  Endpoints extends Exclude<ESIEndpointOf<M>, symbol> = Exclude<ESIEndpointOf<M>, symbol>,
+//*/
+> = {
+  [NextEP in Endpoints]: NextEP extends `${EP}{${string}}${string}` ? NextEP : never
+}[Endpoints];
+
+/**
+ * @see For the meaning of this type of comment trick, see {@link ResolveNextEndpointLoos} line comment.
+ */
+export type ESIEndpointUnions = {
+  [M in TESIEntryMethod]: `${M}:${
+    //* ctt
+    ESIEndpointOf<M>
+    /*/
+    Exclude<ESIEndpointOf<M>, symbol>
+    //*/
+  }`;
+}[TESIEntryMethod];
+
+
+// - - - - - - - - - - - - - - - - - - - - - - - - - -
+//                  Filter Endpoint
+// - - - - - - - - - - - - - - - - - - - - - - - - - -
+/**
+ * Filters ESI endpoints based on the response type.
+ * 
+ * This utility type iterates over all ESI endpoint unions (`ESIEndpointUnions`) and checks
+ * if the inferred response type (`InferESIResponseResultEX<EPU>`) matches the specified type `T`.
+ * If it matches, the endpoint is included; otherwise, it is excluded.
+ * 
+ * @template T - The response type to filter endpoints by.
+ * 
+ * @example
+ * ``` ts
+ * type NumberEndpoints = FilterEndpointUnionsByResponse<number>;
+ * // Result: Union of endpoints whose response type is `number`.
+ * ```
+ */
+export type FilterEndpointUnionsByResponse<T> = {
+  [EPU in ESIEndpointUnions]: InferESIResponseResultFromUnion<EPU> extends T ? EPU : never;
+}[ESIEndpointUnions];
+
+/**
+ * Extracts valid next ESI endpoints from a filtered list of endpoints.
+ * 
+ * This utility type iterates over a list of filtered endpoints (`EPUs`) and applies
+ * `ResolveNextEndpoint2` to determine if the endpoint is valid. If valid, the endpoint
+ * is included in the result; otherwise, it is excluded.
+ * 
+ * @template EPUs - The list of filtered endpoints to process.
+ * 
+ * @example
+ * ``` ts
+ * type ValidEndpoints = ExtractValidNextEndpoints<FilterEndpointsByResponse<number[]>>;
+ * // Result: Union of valid next endpoints.
+ * ```
+ */
+export type ExtractValidNextEndpoints<
+  T = number[], EPUs = FilterEndpointUnionsByResponse<T>
+> = {
+    [EPU in EPUs]: ResolveNextEndpointFromUnion<EPU>;
+    // [EPU in EPUs]: ResolveNextEndpointFromUnion<EPU> extends never ? never : EPU;
+}[EPUs];

package/v2/globals/character.d.ts

@@ -760,10 +760,11 @@ interface GetCharactersCharacterIdPortraitOk {
 /*!
  * ESI endpoint: get:/characters/{character_id}/roles/
  */
+
 /**
  * role string
  */
-type GetCharactersCharacterIdRolesRole =
+type __CharacterRole =
   | "Account_Take_1"
   | "Account_Take_2"
   | "Account_Take_3"
@@ -818,213 +819,46 @@ type GetCharactersCharacterIdRolesRole =
   | "Starbase_Fuel_Technician"
   | "Station_Manager"
   | "Trader";
+
 /**
  * roles array
  *
  * @maxItems 100
  */
-type GetCharactersCharacterIdRolesRoles = GetCharactersCharacterIdRolesRole[];
-/**
- * roles_at_base string
- */
-type GetCharactersCharacterIdRolesRolesAtBaseRolesAtBase =
-  | "Account_Take_1"
-  | "Account_Take_2"
-  | "Account_Take_3"
-  | "Account_Take_4"
-  | "Account_Take_5"
-  | "Account_Take_6"
-  | "Account_Take_7"
-  | "Accountant"
-  | "Auditor"
-  | "Brand_Manager"
-  | "Communications_Officer"
-  | "Config_Equipment"
-  | "Config_Starbase_Equipment"
-  | "Container_Take_1"
-  | "Container_Take_2"
-  | "Container_Take_3"
-  | "Container_Take_4"
-  | "Container_Take_5"
-  | "Container_Take_6"
-  | "Container_Take_7"
-  | "Contract_Manager"
-  | "Deliveries_Container_Take"
-  | "Deliveries_Query"
-  | "Deliveries_Take"
-  | "Diplomat"
-  | "Director"
-  | "Factory_Manager"
-  | "Fitting_Manager"
-  | "Hangar_Query_1"
-  | "Hangar_Query_2"
-  | "Hangar_Query_3"
-  | "Hangar_Query_4"
-  | "Hangar_Query_5"
-  | "Hangar_Query_6"
-  | "Hangar_Query_7"
-  | "Hangar_Take_1"
-  | "Hangar_Take_2"
-  | "Hangar_Take_3"
-  | "Hangar_Take_4"
-  | "Hangar_Take_5"
-  | "Hangar_Take_6"
-  | "Hangar_Take_7"
-  | "Junior_Accountant"
-  | "Personnel_Manager"
-  | "Project_Manager"
-  | "Rent_Factory_Facility"
-  | "Rent_Office"
-  | "Rent_Research_Facility"
-  | "Security_Officer"
-  | "Skill_Plan_Manager"
-  | "Starbase_Defense_Operator"
-  | "Starbase_Fuel_Technician"
-  | "Station_Manager"
-  | "Trader";
-/**
- * roles_at_base array
- *
- * @maxItems 100
- */
-type GetCharactersCharacterIdRolesRolesAtBase = GetCharactersCharacterIdRolesRolesAtBaseRolesAtBase[];
-/**
- * roles_at_hq string
- */
-type GetCharactersCharacterIdRolesRolesAtHqRolesAtHq =
-  | "Account_Take_1"
-  | "Account_Take_2"
-  | "Account_Take_3"
-  | "Account_Take_4"
-  | "Account_Take_5"
-  | "Account_Take_6"
-  | "Account_Take_7"
-  | "Accountant"
-  | "Auditor"
-  | "Brand_Manager"
-  | "Communications_Officer"
-  | "Config_Equipment"
-  | "Config_Starbase_Equipment"
-  | "Container_Take_1"
-  | "Container_Take_2"
-  | "Container_Take_3"
-  | "Container_Take_4"
-  | "Container_Take_5"
-  | "Container_Take_6"
-  | "Container_Take_7"
-  | "Contract_Manager"
-  | "Deliveries_Container_Take"
-  | "Deliveries_Query"
-  | "Deliveries_Take"
-  | "Diplomat"
-  | "Director"
-  | "Factory_Manager"
-  | "Fitting_Manager"
-  | "Hangar_Query_1"
-  | "Hangar_Query_2"
-  | "Hangar_Query_3"
-  | "Hangar_Query_4"
-  | "Hangar_Query_5"
-  | "Hangar_Query_6"
-  | "Hangar_Query_7"
-  | "Hangar_Take_1"
-  | "Hangar_Take_2"
-  | "Hangar_Take_3"
-  | "Hangar_Take_4"
-  | "Hangar_Take_5"
-  | "Hangar_Take_6"
-  | "Hangar_Take_7"
-  | "Junior_Accountant"
-  | "Personnel_Manager"
-  | "Project_Manager"
-  | "Rent_Factory_Facility"
-  | "Rent_Office"
-  | "Rent_Research_Facility"
-  | "Security_Officer"
-  | "Skill_Plan_Manager"
-  | "Starbase_Defense_Operator"
-  | "Starbase_Fuel_Technician"
-  | "Station_Manager"
-  | "Trader";
-/**
- * roles_at_hq array
- *
- * @maxItems 100
- */
-type GetCharactersCharacterIdRolesRolesAtHq = GetCharactersCharacterIdRolesRolesAtHqRolesAtHq[];
-/**
- * roles_at_other string
- */
-type GetCharactersCharacterIdRolesRolesAtOtherRolesAtOther =
-  | "Account_Take_1"
-  | "Account_Take_2"
-  | "Account_Take_3"
-  | "Account_Take_4"
-  | "Account_Take_5"
-  | "Account_Take_6"
-  | "Account_Take_7"
-  | "Accountant"
-  | "Auditor"
-  | "Brand_Manager"
-  | "Communications_Officer"
-  | "Config_Equipment"
-  | "Config_Starbase_Equipment"
-  | "Container_Take_1"
-  | "Container_Take_2"
-  | "Container_Take_3"
-  | "Container_Take_4"
-  | "Container_Take_5"
-  | "Container_Take_6"
-  | "Container_Take_7"
-  | "Contract_Manager"
-  | "Deliveries_Container_Take"
-  | "Deliveries_Query"
-  | "Deliveries_Take"
-  | "Diplomat"
-  | "Director"
-  | "Factory_Manager"
-  | "Fitting_Manager"
-  | "Hangar_Query_1"
-  | "Hangar_Query_2"
-  | "Hangar_Query_3"
-  | "Hangar_Query_4"
-  | "Hangar_Query_5"
-  | "Hangar_Query_6"
-  | "Hangar_Query_7"
-  | "Hangar_Take_1"
-  | "Hangar_Take_2"
-  | "Hangar_Take_3"
-  | "Hangar_Take_4"
-  | "Hangar_Take_5"
-  | "Hangar_Take_6"
-  | "Hangar_Take_7"
-  | "Junior_Accountant"
-  | "Personnel_Manager"
-  | "Project_Manager"
-  | "Rent_Factory_Facility"
-  | "Rent_Office"
-  | "Rent_Research_Facility"
-  | "Security_Officer"
-  | "Skill_Plan_Manager"
-  | "Starbase_Defense_Operator"
-  | "Starbase_Fuel_Technician"
-  | "Station_Manager"
-  | "Trader";
-/**
- * roles_at_other array
- *
- * @maxItems 100
- */
-type GetCharactersCharacterIdRolesRolesAtOther = GetCharactersCharacterIdRolesRolesAtOtherRolesAtOther[];
+type CharacterRoleArray = __CharacterRole[];
 
 /**
  * 200 ok object
  */
 interface GetCharactersCharacterIdRolesOk {
-  roles?: GetCharactersCharacterIdRolesRoles;
-  roles_at_base?: GetCharactersCharacterIdRolesRolesAtBase;
-  roles_at_hq?: GetCharactersCharacterIdRolesRolesAtHq;
-  roles_at_other?: GetCharactersCharacterIdRolesRolesAtOther;
+  /**
+   * roles array
+   *
+   * @maxItems 100
+   */
+  roles?: CharacterRoleArray;
+
+  /**
+   * roles_at_base array
+   *
+   * @maxItems 100
+   */
+  roles_at_base?: CharacterRoleArray;
+
+  /**
+   * roles_at_hq array
+   *
+   * @maxItems 100
+   */
+  roles_at_hq?: CharacterRoleArray;
+
+  /**
+   * roles_at_other array
+   *
+   * @maxItems 100
+   */
+  roles_at_other?: CharacterRoleArray;
+
   [k: string]: unknown | undefined;
 }