eve-esi-types 3.2.4 → 3.2.7

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.2.7] - 2025-04-28
+
+### 🚜 Refactor
+
+- Add ESIEntryParamKeys, ESIEntryExtraKeys & ResolveEndpointRequest types
+
+### ⚙️ Miscellaneous Tasks
+
+- Update CHANGELOG.md
+- Update JSDoc (rename EPX to EPO and add acronym definition)
+- Update CHANGELOG.md
+- Bump version to v3.2.7
+
+## [3.2.6] - 2025-04-24
+
+### 🐛 Bug Fixes
+
+- `normalizeOptions` bug
+
+### ⚙️ Miscellaneous Tasks
+
+- Update CHANGELOG.md
+- Update "main" field in package.json to point to dist folder
+- Bump version to v3.2.6
+
+## [3.2.5] - 2025-04-24
+
+### 💼 Other
+
+- Refactor v2/experimental-esi-types.d.ts
+
+### ⚙️ Miscellaneous Tasks
+
+- Update CHANGELOG.md
+- Relocate v2 files to dist/v2 directory
+- Update import paths to reflect new structure
+- Update jsconfig.json for improved path resolution
+- Bump version to v3.2.5
+
 ## [3.2.4] - 2025-04-22
 
 ### 🚜 Refactor

package/README.md

@@ -1,105 +1,129 @@
+
 # eve-esi-types
-Extracted main types of ESI. Used for ESI request response types.
+Extracted main types of ESI (EVE Swagger Interface). This package is designed to handle ESI request and response types effectively.
 
-## Usage
+---
+
+## Table of Contents
+1. [Overview](#overview)
+2. [Installation](#installation)
+3. [Usage](#usage)
+4. [API Overview](#api-overview)
+5. [Version Highlights](#version-highlights)
+    - [v3.2.7](#v327)
+    - [v3.0.0](#v300)
+    - [v2.3.0](#v230)
+6. [References](#references)
 
-> 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/version-1.x)
+## Overview
+`eve-esi-types` helps developers interact with the EVE Online ESI API while leveraging strong TypeScript typings.
 
-> Sample code is provided -> [`request-v3.mjs`](./request-v3.mjs)
+This package ensures type safety for ESI request parameters, response handling, and authentication requirements.
 
-```shell
-$ node request-v3.mjs
+---
+
+## Installation
+
+```bash
+npm install eve-esi-types
 ```
 
-## API
+---
+
+## Usage
 
-> 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, what query parameters are required,  
-> and whether OAuth authentication is necessary (`auth: true`).
+This package is configured to **use ESI version 2 by default**.  
+If you need to work with version 1, refer to the [v1 branch](https://github.com/jeffy-g/eve-esi-types/tree/version-1.x).
 
-```ts
-// This function signature has been removed in version 3.x
-// export declare function fire<
-//     M extends TESIEntryMethod,
-//     EP extends keyof TESIResponseOKMap[M],
-//     P2 extends IfParameterizedPath<EP, Opt>,
-//     Opt extends IdentifyParameters<TESIResponseOKMap[M][EP], ESIRequestOptions>,
-//     R extends InferESIResponseResult<M, EP>
-// >(mthd: M, endp: EP, pathParams?: P2, opt?: Opt): Promise<R>;
+### Example Usage
+A sample script, [`request-v3.mjs`](./request-v3.mjs), is provided.
+
+```bash
+node request-v3.mjs
 ```
 
-## New Features in v2.3.0
+---
 
-### ESI Tagged Types
+## API Overview
 
-> Introduced intuitive ESI request handling using "tags" from the EVE Swagger JSON.
+The core export of this package is the `TESIRequestFunctionSignature2` type. It specifies the required endpoint,
 
-### ~~injectESIRequestBody~~
+HTTP method, query parameters, OAuth requirement, and response type for ESI requests.
 
-> Utilized ~~`injectESIRequestBody`~~ to generate ESI request API objects with narrowed endpoints by accessing camel-cased "tags".
+### Main Function Signature
 
 ```ts
-import * as taggedApi from "eve-esi-types/lib/tagged-request-api.mjs";
-
-// `injectESIRequestBody` has been removed in version 3.x
-// const esiRequest = taggedApi.injectESIRequestBody(...);
-// const ret = await esiRequest.universe.get("/universe/structures/", { query: { filter: "market" }});
+type TESIRequestFunctionSignature2<ActualOpt extends Record<string, unknown>> = <
+  Mtd extends TESIEntryMethod,
+  REP extends ReplacePathParams<ESIEndpointOf<Mtd>> | ESIEndpointOf<Mtd>,
+  EPO extends ResolvedEndpoint<Mtd, REP>,
+  Params extends ResolveEndpointParameters<Mtd, REP, EPO, ActualOpt>,
+  Opt extends Params["finalOptions"]
+>(
+  method: Mtd,
+  endpoint: REP,
+  ...options: Params["optionIsRequire"] extends 1 ? [Opt] : [Opt?]
+) => Promise<Params["result"]>;
 ```
 
-+ or
+### Authentication via Environment Variable (v3.2.7+)
 
-```ts
-// Minimal default ESI request body implementation
-import { esi } from "eve-esi-types/lib/tagged-request-api.mjs";
+You can enable authenticated requests by setting the environment variable `OAUTH_TOKEN` (for testing):
 
-const ret = await esi.universe.get("/universe/structures/", { query: { filter: "market" }});
+```bash
+export OAUTH_TOKEN=<Your Access Token>
 ```
 
-## New Features in v3.0.0
+---
+
+## Version Highlights
+
+### v3.2.7  
+- Added support for specifying the `OAUTH_TOKEN` environment variable.  
+- Allows authenticated tests to run successfully by providing an OAuth access token.
 
-### `TESIRequestFunctionSignature` has been renamed to `TESIRequestFunctionSignature2` and the generic parameters have been changed.
+---
 
-> `RealEP` and `EP` help maintain endpoint inference.  
-> With `RealEP`, TypeScript inference partially lists the possible endpoints while allowing for path parameter replacement.
+### v3.0.0
+- Renamed `TESIRequestFunctionSignature` to `TESIRequestFunctionSignature2`.
+- Improved endpoint inference (`RealEP` and `EP`) for better TypeScript type safety.
 
+#### New API Example
+Reusable, narrowing-focused API request using `decoreateESIRequestBody`:
 
 ```ts
-type TESIRequestFunctionSignature2<ActualOpt> = <
-  M extends TESIEntryMethod,
-  RealEP extends ReplacePathParams<keyof TESIResponseOKMap[M] & string> | keyof TESIResponseOKMap[M],
-  EP extends InferEndpointOrigin<RealEP, keyof TESIResponseOKMap[M]> extends never ? RealEP : InferEndpointOrigin<RealEP, keyof TESIResponseOKMap[M]>,
-  // If RealEP points to an endpoint origin (not a replaced endpoint), the path parameter is required
-  PathParams extends RealEP extends EP ? IfNeedPathParams<EP> : TPathParamsNever,
-  Opt extends IdentifyParameters<TESIResponseOKMap[M][EP], ActualOpt & PathParams>,
-  R extends InferESIResponseResult<M, EP>
->(method: M, endpoint: RealEP, options?: Opt) => Promise<R>;
+import * as taggedApi from "eve-esi-types/lib/tagged-request-api.mjs";
+
+const esiRequest = taggedApi.decoreateESIRequestBody(...);
+const response = await esiRequest.universe.get("/universe/structures/", { query: { filter: "market" } });
 ```
 
-+ NOTE: Accordingly, the generic parameters for other request function signatures have also been changed, with "2" appended to their names.
+#### Other Renamed Signatures
+- `IESIRequestFunction -> IESIRequestFunction2`
+- `TESIRequestFunctionMethods -> TESIRequestFunctionMethods2`
 
-  + `IESIRequestFunction` -> `IESIRequestFunction2`
-  + `TESIRequestFunctionMethods` -> `TESIRequestFunctionMethods2`
-  + `TESIRequestFunctionEachMethod` -> `TESIRequestFunctionEachMethod2`
-  + etc. Also, `v2/esi-tagged-types.d.ts` too
+---
 
-### decoreateESIRequestBody
+### v2.3.0
+- Introduced intuitive ESI request handling via **ESI Tagged Types**.
+- Deprecated `injectESIRequestBody` in favor of `decoreateESIRequestBody` in later versions.
 
-> Utilized `decoreateESIRequestBody` to generate ESI request API objects with narrowed endpoints by accessing camel-cased "tags".
+Minimal default implementation:
 
 ```ts
-import * as taggedApi from "eve-esi-types/lib/tagged-request-api.mjs";
-
-const esiRequest = taggedApi.decoreateESIRequestBody(...);
-const ret = await esiRequest.universe.get("/universe/structures/", { query: { filter: "market" }});
+import { esi } from "eve-esi-types/lib/tagged-request-api.mjs";
+const response = await esi.universe.get("/universe/structures/", { query: { filter: "market" } });
 ```
 
+---
 
 ## References
 
-- [`ESI Types Utility Definitions`](./docs/v3/esi-types-util3.md)
+- [ESI Types Utility Definitions](./docs/v3/esi-types-util3.md)
+- [ESI Tagged Types Utility Definitions](./docs/esi-tagged-types.md)
+
+---
 
-- [`ESI Tagged Types Utility Definitions`](./docs/esi-tagged-types.md)
+Have questions or issues? Feel free to explore the [GitHub repository](https://github.com/jeffy-g/eve-esi-types) or open an issue!

package/{v2 → dist/v2}/esi-tagged-types.d.ts

@@ -9,15 +9,15 @@
  * 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.4 of the EVE Online ESI response types.
+ * @summary This file is auto-generated and defines version 3.2.7 of the EVE Online ESI response types.
  */
-import type { TESIResponseOKMap } from "./index.d.ts";
+import type { TESIResponseOKMap, ResolveEndpointParameters } from "./index.d.ts";
 export type * from "./index.d.ts";
 
 /**
  * Converts a string to lower camel case.
  * 
- * @template S - The string to convert.
+ * @template S The string to convert.
  * @example
  * // returns "assets"
  * LCamelCase<"Assets">
@@ -46,7 +46,7 @@ declare type InferSomethingBy<Tag, AsType extends InferSomethingByBrand = InferS
 // - - - - - - - - - - - - - - - - - - - - - - - - - -
 /**
  * Maps HTTP methods to their corresponding tags.
- * @template M - The HTTP method.
+ * @template M The HTTP method.
  * @date 2025/2/28
  */
 export declare type ESITags = InferSomethingBy<never, InferSomethingByTags>;
@@ -61,7 +61,7 @@ export declare type LESITags = LCamelCase<ESITags>;
 /**
  * Infers the HTTP method based on the provided tag.
  * 
- * @template Tag - The tag to infer the method for.
+ * @template Tag The tag to infer the method for.
  * @date 2025/2/28
  */
 export declare type InferMethod<Tag> = InferSomethingBy<Tag>;
@@ -80,16 +80,13 @@ type XPlanetary = InferMethod<"Planetary Interaction">;
  * 
  *  + Customed InferEndpointOrigin
  * 
- * @template RealEP - The real endpoint type.
- * @template Endpoints - The possible endpoints.
- * 
- * @typeParam RealEP - The type of the real endpoint.
- * @typeParam Endpoints - The type of the possible endpoints.
+ * @template RealEP The type of the real endpoint.
+ * @template Endpoints The type of the possible endpoints.
  * 
  * @returns The inferred endpoint origin.
  */
 type _InferEndpointOrigin<
-  RealEP extends unknown, Endpoints extends string | number | symbol
+  RealEP extends unknown, Endpoints extends PropertyKey
 > = {
   [EP in Endpoints]: RealEP extends ReplacePathParams<EP>
     ? EP : never;
@@ -97,38 +94,75 @@ type _InferEndpointOrigin<
 
 /**
  * Creates a function type for making requests to tagged endpoints.
- * 
- * @template M - The HTTP method.
- * @template Tag - The tag associated with the endpoint.
- * @template ActualOpt - The actual options for the request.
- * @template EndPoints - The possible endpoints.
- * @template REP - The real endpoint path.
- * @template EPX - The inferred endpoint origin.
- * @template PPM - The path parameters.
- * @template Opt - The request options.
- * @template Ret - The response type.
- * @template HasOpt - Indicates if the endpoint has required parameters.
- * 
- * @param endpoint - The endpoint path.
- * @param options - An optional object containing additional options for the request. If the endpoint has required parameters, this parameter must be provided.
- * @returns A promise that resolves to the response.
- * 
+ *
+ * This utility type defines a function signature for interacting with ESI endpoints
+ * that are associated with specific tags and HTTP methods. It ensures type safety
+ * by inferring the required parameters, options, and response types for the given endpoint.
+ *
+ * @template M - The HTTP method (e.g., "get", "post").
+ * @template Tag - The tag associated with the endpoint (e.g., "Assets", "Skills").
+ * @template ActualOpt - A record type representing additional options for the request.
+ * @template EndPoints - The possible endpoints associated with the tag and method.
+ *
+ * @param endpoint - The endpoint path, which can be parameterized or resolved.
+ * @param options - An optional object containing additional options for the request.
+ *                  If the endpoint has required parameters, this parameter must be provided.
+ * @returns A promise that resolves to the response type of the endpoint.
+ *
  * @remarks
- * The `...options: HasOpt extends 1 ? [Opt] : [Opt?]` parameter is defined this way to enforce that if the endpoint has required parameters,  
- * the `options` parameter must be provided. If there are no required parameters, the `options` parameter is optional.
+ * - The `...options: Params["optionIsRequire"] extends 1 ? [Opt] : [Opt?]` parameter ensures
+ *   that if the endpoint has required parameters, the `options` parameter must be provided.
+ *   If there are no required parameters, the `options` parameter is optional.
+ * - This type leverages `ResolveEndpointParameters` to infer the required options and response type.
+ *
+ * @example
+ * ```ts
+ * // Example: Making a request to the "Assets" tag with the "get" method
+ * type AssetsRequest = TaggedEndpointRequestFunction2<"get", "Assets", ESIRequestOptions>;
+ * const fetchAssets: AssetsRequest = async (endpoint, ...options) => {
+ *   // Implementation here
+ *   throw new Error();
+ * };
+ * fetchAssets("/characters/{character_id}/assets/", {
+ *     pathParams: 12345,
+ *     auth: true,
+ *     token: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
+ * }).then(response => {
+ *     console.log(response);
+ * });
+ * ```
+ *
+ * @see {@link ResolveEndpointParameters}
+ * @see {@link SelectEndpointByTag}
+ * @see {@link InferESIResponseResult}
  */
+/* ctt
 export declare type TaggedEndpointRequestFunction2<
   M extends TESIEntryMethod, Tag extends ESITags,
   ActualOpt extends Record<string, unknown> = {},
   EndPoints extends SelectEndpointByTag<Tag, M> = SelectEndpointByTag<Tag, M>,
 > = <
     REP extends ReplacePathParams<EndPoints> | EndPoints,
-    EPX extends _InferEndpointOrigin<REP, EndPoints> extends never ? REP: _InferEndpointOrigin<REP, EndPoints>,
-    PPM extends InferPathParams<REP, EPX>,
-    Opt extends IdentifyParameters<M, EPX, ActualOpt, PPM>,
-    Ret extends InferESIResponseResult<M, EPX>,
-    HasOpt = HasRequireParams<M, EPX, PPM>,
+    EPO extends _InferEndpointOrigin<REP, EndPoints> extends never ? REP: _InferEndpointOrigin<REP, EndPoints>,
+    PPM extends InferPathParams<REP, EPO>,
+    Opt extends IdentifyParameters<M, EPO, ActualOpt, PPM>,
+    Ret extends InferESIResponseResult<M, EPO>,
+    HasOpt = HasRequireParams<M, EPO, PPM>,
 >(endpoint: REP, ...options: HasOpt extends 1 ? [Opt] : [Opt?]) => Promise<Ret>;
+/*/
+export declare type TaggedEndpointRequestFunction2<
+  M extends TESIEntryMethod, Tag extends ESITags,
+  ActualOpt extends Record<string, unknown> = {},
+  EndPoints extends SelectEndpointByTag<Tag, M> = SelectEndpointByTag<Tag, M>,
+> = <
+    REP extends ReplacePathParams<EndPoints> | EndPoints,
+    EPO extends _InferEndpointOrigin<REP, EndPoints> extends never ? REP: _InferEndpointOrigin<REP, EndPoints>,
+    // @ts-expect-error TODO: 2025/4/28 TS2344: Type 'EPO' does not satisfy the constraint 'ResolvedEndpoint<M, REP>'
+    Params extends ResolveEndpointParameters<M, REP, EPO, ActualOpt>,
+    Opt extends Params["finalOptions"],
+    Ret extends Params["result"],
+  >(endpoint: REP, ...options: Params["optionIsRequire"] extends 1 ? [Opt] : [Opt?]) => Promise<Ret>;
+//*/
 
 
 // - - - - - - - - - - - - - - - - - - - - - - - - - -
@@ -137,8 +171,8 @@ export declare type TaggedEndpointRequestFunction2<
 /**
  * Maps tags to their corresponding endpoint request functions.
  * 
- * @template Tag - The tag to map.
- * @template ActualOpt - The actual options for the request.
+ * @template Tag The tag to map.
+ * @template ActualOpt The actual options for the request.
  * @date 2025/2/28
  */
 export declare type ESITaggedEndpointRequest2<Tag extends ESITags, ActualOpt extends Record<string, unknown> = {}> = {
@@ -153,19 +187,18 @@ export declare type ESITaggedEndpointRequest2<Tag extends ESITags, ActualOpt ext
 /**
  * Selects an endpoint by tag and method.
  * 
- * @template Tag - The tag associated with the endpoint.
- * @template M - The HTTP method.
- * @template EP - The endpoint path.
+ * @template Tag The tag associated with the endpoint.
+ * @template M The HTTP method.
  * @date 2025/2/28
  */
 export declare type SelectEndpointByTag<
   Tag extends ESITags, M extends TESIEntryMethod
 > = {
-  [EP in keyof TESIResponseOKMap[M]]: TESIResponseOKMap[M][EP] extends { tag: infer ActualTag }
+  [EP in ESIEndpointOf<M>]: TESIResponseOKMap[M][EP] extends { tag: infer ActualTag }
     ? ActualTag extends Tag
       ? EP : never
     : never;
-}[keyof TESIResponseOKMap[M]];
+}[ESIEndpointOf<M>];
 /* ctt
 type XAssetsEndpointGet = SelectEndpointByTag<"Assets", "get">;
 type XAssetsEndpointPost = SelectEndpointByTag<"Assets", "post">;
@@ -175,7 +208,7 @@ type XAssetsEndpointPost = SelectEndpointByTag<"Assets", "post">;
 /**
  * Maps lower camel case tags to their corresponding endpoint request functions.
  * 
- * @template ActualOpt - The actual options for the request.
+ * @template ActualOpt The actual options for the request.
  * @date 2025/3/12
  */
 export declare type TaggedESIRequestMap2<ActualOpt extends Record<string, unknown> = {}> = {
@@ -189,9 +222,9 @@ export declare type TaggedESIRequestMap2<ActualOpt extends Record<string, unknow
  * const esiRq: TaggedESIRequestMapPartial2<"factionWarfare" | "wallet">;
  * ```
  * 
- * @template Props - The properties to require in the partial map.
+ * @template LowerTags The properties to require in the partial map.
  * @date 2025/2/28
  */
-export declare type TaggedESIRequestMapPartial2<Props extends LCamelCase<ESITags>> = RequireThese<Partial<TaggedESIRequestMap2>, Props>;
+export declare type TaggedESIRequestMapPartial2<LowerTags extends LCamelCase<ESITags>> = RequireThese<Partial<TaggedESIRequestMap2>, LowerTags>;
 
 export as namespace XESI;