eve-esi-types 3.2.6 → 3.2.8

package/dist/v2/response-map.d.ts

@@ -9,7 +9,7 @@
  * THIS DTS IS AUTO GENERATED, DO NOT EDIT
  * 
  * @file eve-esi-types/v2/response-map.d.ts
- * @summary This file is auto-generated and defines version 3.2.5 of the EVE Online ESI response types.
+ * @summary This file is auto-generated and defines version 3.2.8 of the EVE Online ESI response types.
  */
 import "./types-index.d.ts";
 

package/dist/v2/types-index.d.ts

@@ -9,7 +9,7 @@
  * THIS DTS IS AUTO GENERATED, DO NOT EDIT
  * 
  * @file eve-esi-types/v2/types-index.d.ts
- * @summary This file is auto-generated and defines version 3.2.5 of the EVE Online ESI response types.
+ * @summary This file is auto-generated and defines version 3.2.8 of the EVE Online ESI response types.
  */
 import "./globals/alliance.d.ts";
 import "./globals/assets.d.ts";

package/dist/v2/types-util.d.ts

@@ -9,15 +9,91 @@
  * THIS DTS IS AUTO GENERATED, DO NOT EDIT
  * 
  * @file eve-esi-types/v2/types-util.d.ts
- * @summary This file is auto-generated and defines version 3.2.5 of the EVE Online ESI response types.
+ * @summary This file is auto-generated and defines version 3.2.8 of the EVE Online ESI response types.
  */
 import type { TESIResponseOKMap } from "./response-map.d.ts";
+import type { RestrictKeys, CombineIntersection } from "./index.d.ts";
+
+
+/**
+ * Defines the keys used in ESI entries for request parameters.  
+ * These keys represent the main categories of parameters that can be included in an ESI request.
+ */
+export type ESIEntryParamKeys = "auth" | "query" | "body" | "pathParams";
+/**
+ * Defines the keys that are not directly involved in ESI request parameters.  
+ * These keys represent metadata or additional information that is not part of the main request parameters.
+ */
+export type ESIEntryExtraKeys = "result" | "tag" | "cachedSeconds";
+
+/**
+ * Resolves the parameters required for making an ESI request to a specific endpoint.
+ *
+ * This type combines the user-supplied options, path parameters, and the expected response type
+ * to produce a structured result that includes:
+ * - The actual response payload type (`result`).
+ * - The final options object (`finalOptions`) that should be passed to the request.
+ * - A flag (`optionIsRequire`) indicating whether the options object is mandatory.
+ *
+ * @template Mtd - The HTTP method (e.g., "get", "post") of the request.
+ * @template REP - The endpoint path, which can be parameterized or already resolved with numbers.
+ * @template EPO - The resolved endpoint type tied to `REP`.
+ * @template Opt - A record type representing user-supplied request options.
+ * @template PathParams - A record type representing path parameters for the endpoint.
+ * @template EntryWithParams - The merged type of the response payload and path parameters.
+ * @template RequireKeys - The keys from `EntryWithParams` that represent actual request parameters.
+ *
+ * @returns An object containing:
+ * - `result`: The actual response payload type.
+ * - `finalOptions`: The exact options object to pass in (e.g., pathParams, query, body, auth).
+ * - `optionIsRequire`: A flag (`1` or `0`) indicating whether the options object is required.
+ *
+ * @example
+ * ```ts
+ * // Example endpoint: /characters/{character_id}/attributes/
+ * type ExampleOpt = { auth: true; token: "eyJhbGciOiJSUzI1NiIsI..." };
+ * type ResolvedParams = ResolveEndpointParameters<
+ *   "get", `/characters/${123345}/attributes/`, "/characters/{character_id}/attributes/",
+ *   ExampleOpt
+ * >;
+ * // Result:
+ * // { auth: true, token: "eyJhbGciOiJSUzI1NiIsI..." }
+ * ```
+ *
+ * @see {@link CombineIntersection}
+ * @see {@link RestrictKeys}
+ * @see {@link _ESIResponseType}
+ */
+export type ResolveEndpointParameters<
+  Mtd extends TESIEntryMethod,
+  // REP is either a parameterized path or already number-filled:
+  REP extends ReplacePathParams<ESIEndpointOf<Mtd>> | ESIEndpointOf<Mtd>,
+  // <— tie it directly to REP via ResolvedEndpoint:
+  EPO extends ResolvedEndpoint<Mtd, REP>,
+  // user-supplied options:
+  Opt extends Record<string, unknown>,
+
+  // now that EPO is fixed, these defaults all line up:
+  PathParams extends InferPathParams<REP, EPO> = InferPathParams<REP, EPO>,
+  EntryWithParams = _ESIResponseType<Mtd, EPO> & PathParams,
+  RequireKeys extends keyof EntryWithParams = Exclude<keyof EntryWithParams, ESIEntryExtraKeys>,
+  FinalOpt = CombineIntersection<
+    RestrictKeys<Opt, RequireKeys> & Pick<EntryWithParams, RequireKeys>
+  >
+> = {
+  // the actual `"result"` payload type
+  result: EntryWithParams extends { result: infer R } ? R : never;
+  // the exact options object you should pass in (pathParams/query/body/auth)
+  finalOptions: FinalOpt;
+  // 1 if you _must_ pass an options object, else 0
+  optionIsRequire: HasRequireParams<Mtd, EPO, PathParams>;
+};
 
 
 /**
  * Represents a function that can make ESI requests with various HTTP methods.
  *
- * @template ActualOpt - The actual type of the options.
+ * @template ActualOpt The actual type of the options.
  *
  * ```ts
  * // @ ts-expect-error
@@ -43,7 +119,7 @@ export interface IESIRequestFunction2<ActualOpt extends Record<string, unknown>>
  *  + This interface is used when you already have implementation code such as  
  *    TESIRequestFunctionSignature2 and you want to implement additional shorthand methods.
  *
- * @template ActualOpt - The actual type of the options.
+ * @template ActualOpt The actual type of the options.
  *
  * @example
  * ```ts
@@ -104,8 +180,8 @@ export declare type TPathParamsNever = { /* pathParams?: never */ };
  * This type extracts the response type from the `TESIResponseOKMap` based on the provided
  * HTTP method and endpoint.
  * 
- * @template M - The HTTP method to use for the request.
- * @template EPx - The endpoint path.  
+ * @template M The HTTP method to use for the request.
+ * @template EPx The endpoint path.  
  *  include `string` in the `EPx` constraints to avoid breaking typescript inference.
  * 
  * @example
@@ -124,7 +200,7 @@ export type _ESIResponseType<
 /**
  * Determines if the endpoint requires path parameters.
  * 
- * @template EP - The string representing the endpoint path.
+ * @template EP The string representing the endpoint path.
  * @returns {TPathParamsNever | { pathParams: IfParameterizedPath<EP> }}
  * Returns an object with `pathParams` if the endpoint requires parameters, otherwise returns `TPathParamsNever`.
  * @example
@@ -136,20 +212,54 @@ export type _ESIResponseType<
  * @see {@link IfParameterizedPath}
  * @see {@link ReplacePathParams}
  */
+//* ctt
 export type _IfNeedPathParams<
-  EP extends unknown,
-  // will be `never` when cached
-  // Parameterized extends IfParameterizedPath<EP> = IfParameterizedPath<EP>
-> = IfParameterizedPath<EP> extends never
+  EP extends PropertyKey,
+  Parameterized extends IfParameterizedPath<EP> = IfParameterizedPath<EP>
+> = Parameterized extends 0
   ? TPathParamsNever :
     EP extends ReplacePathParams<EP>
-      ? TPathParamsNever : { pathParams: IfParameterizedPath<EP> };
+      ? TPathParamsNever : { pathParams: Parameterized };
+/*/
+export type _IfNeedPathParams<
+  EP extends PropertyKey,
+  Parameterized extends IfParameterizedPath<EP> = IfParameterizedPath<EP>
+> = Parameterized extends 0
+  ? TPathParamsNever : { pathParams: Parameterized };
+//*/
+
+/**
+ * Picks the required parameters from an entry type, including additional parameters.
+ * 
+ * This type excludes the keys "result", "tag", and "cachedSeconds" from the entry type and the additional parameters,
+ * and returns the remaining keys as the required parameters.
+ * 
+ * @template M The HTTP method to use for the request.
+ * @template EPx The endpoint path.
+ * @template AdditionalParams Additional parameters to include in the check.
+ * 
+ * @example
+ * ```ts
+ * type ExampleEntry = { result: string, tag: string, cachedSeconds: number, auth: string };
+ * type RequiredParams = PickRequireParams<"get", "/example/endpoint", { auth: string }, ExampleEntry>;
+ * // Result: "auth"
+ * ```
+ * @see {@link ESIEndpointOf}
+ * @see {@link _ESIResponseType}
+ * @deprecated 2025/4/28
+ * @see Documentation of [`PickRequireParams`](https://github.com/jeffy-g/eve-esi-types/blob/master/docs/v3/pick-require-params.md)
+ */
+export type __PickRequireParams<
+  M extends TESIEntryMethod,
+  EPx extends ESIEndpointOf<M> | string,
+  AdditionalParams,
+> = Exclude<keyof (_ESIResponseType<M, EPx> & AdditionalParams), ESIEntryExtraKeys>;
 
 /**
  * Infer the result type of an ESI response based on the method and endpoint.
  * 
- * @template M - The HTTP method (e.g., "get", "post").
- * @template EP - The endpoint path.
+ * @template M The HTTP method (e.g., "get", "post").
+ * @template EP The endpoint path.
  * @deprecated 2025/3/17
  */
 export type __InferESIResponseResult<
@@ -159,13 +269,13 @@ export type __InferESIResponseResult<
 /**
  * Identifies the required parameters for a given entry type.
  *
- * @template Entry - The entry type to identify parameters for.
- * @template Opt - The type of the parameters.
+ * @template Entry The entry type to identify parameters for.
+ * @template Opt The type of the parameters.
  * @type {Opt & Pick<Entry, Exclude<keyof Entry, "result">>}
  * @deprecated 2025/3/17
  */
 export type __IdentifyParameters<
   Entry, Opt,
-  Keys = Exclude<keyof Entry, "result" | "tag" | "cachedSeconds">
+  Keys = Exclude<keyof Entry, ESIEntryExtraKeys>
   // @ts-expect-error 
 > = RequireThese<Opt, Keys> & Pick<Entry, Keys>;

package/dist/v2/util.d.ts

@@ -17,7 +17,7 @@
  * @returns {string | never} The parameter name if the path is parameterized, otherwise `never`.
  */
 //* ctt
-export type PickPathParameters<Path extends string> =
+export type PickPathParameters<Path extends PropertyKey> =
   Path extends `${string}/{${infer Param}}/${infer Rest}`
   ? Param | PickPathParameters<`/${Rest}`>
   : never;
@@ -28,6 +28,10 @@ export type PickPathParameters<Path extends string> =
     ? Param
   : never;
 //*/
+export type PathParamsToMap<EP extends PropertyKey> =
+  EP extends `${infer _Start}{${infer Param}}${infer Rest}`
+    ? { [K in Param | keyof PathParamsToMap<Rest>]: string }
+    : {};
 
 /**
  * Convert a union type to an intersection type.
@@ -36,7 +40,6 @@ export type PickPathParameters<Path extends string> =
  * @returns {I} The intersection type.
  */
 export type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
-
 /**
  * Convert a union type to a tuple.
  * 
@@ -47,6 +50,56 @@ export type UnionToTuple<T> = UnionToIntersection<
   T extends any ? () => T : never
 > extends () => infer R ? [...UnionToTuple<Exclude<T, R>>, R] : [];
 
+// - - - - - - - - - - - - - - - - - - - - - - - - - -
+//              Implemented: 2025/4/28
+// - - - - - - - - - - - - - - - - - - - - - - - - - -
+/**
+ * Extracts parameter keys from a parameterized path string as a tuple.
+ *
+ * This utility type takes a parameterized path string (e.g., `"/foo/{a}/bar/{b}/baz/"`)
+ * and extracts the parameter keys (e.g., `["a", "b"]`) as a tuple.
+ *
+ * @template Path - The parameterized path string.
+ * @returns {string[]} A tuple of parameter keys extracted from the path.
+ *
+ * @example
+ * ```ts
+ * type Params = ExtractPathParamKeys<"/foo/{a}/bar/{b}/baz/">;
+ * // Result: ["a", "b"]
+ * ```
+ */
+export type ExtractPathParamKeys<
+  P extends PropertyKey
+> = P extends `${infer _Before}{${infer Param}}${infer Rest}`
+  ? [Param, ...ExtractPathParamKeys<Rest>]
+  : [];
+
+/**
+ * Extract parameter keys from either
+ *  - a single parameterized path string, or
+ *  - an array (or readonly array) of those strings,
+ * and return them as a union.
+ *
+ * @template Path
+ *   Either a string template or an (readonly) array of string templates.
+ * @returns A union of all parameter names.
+ *
+ * @example
+ * type U1 = ExtractPathParamUnion<"/foo/{a}/bar/{b}/baz/">;
+ * // -> "a" | "b"
+ *
+ * type U2 = ExtractPathParamUnion<
+ *   ["/foo/{a}/bar/{b}/baz/", "/users/{user_id}/posts/{post_id}"]
+ * >;
+ * // -> "a" | "b" | "user_id" | "post_id"
+ */
+export type ExtractPathParamUnion<Path extends string | readonly string[]> =
+  Path extends readonly any[]
+    ? ExtractPathParamKeys<Path[number]>[number]
+    : Path extends string
+      ? ExtractPathParamKeys<Path>[number] : never;
+
+
 /**
  * #### Build an array of elements from a flattened tuple of type "1" | "2" | "3" ...
  * 
@@ -59,7 +112,6 @@ export type UnionToTuple<T> = UnionToIntersection<
  * @date 2025/2/11 18:12:02
  */
 export type InferKeysLen<T> = UnionToTuple<T>["length"];
-
 /**
  * Splits a string by a delimiter and returns a tuple of the resulting substrings.
  * @example
@@ -79,6 +131,16 @@ export type Split<S extends string, D extends string = ":"> =
 // type Test3 = Split<"hello", ",">;
 // // Expected: ['hello']
 
+/**
+ * Combines an intersection of object types into a single object type.
+ * 
+ * @template IS The intersection of object types to combine.
+ * @returns {Record<string, unknown>} A single object type with all properties from the intersection.
+ * 
+ * @example
+ * type Combined = CombineIntersection<{ a: string } & { b: number }>;
+ * // Result: { a: string; b: number }
+ */
 //* ctt
 // export type CombineIntersection<IS> = IS extends infer O ? { [K in keyof O]: O[K] } : never;
 export type CombineIntersection<IS extends Record<string, unknown>> = { [K in keyof IS]: IS[K] };

package/lib/console-util.mjs

@@ -83,7 +83,7 @@ export function getLogger(banner, logSelector = ".log-frame") {
         return console.log.bind(console, banner);
     }
     else {
-        /** @type {function(...any): void} */
+        /** @type {(...data: any[]) => void} */
         const log = (...data) => {
             let text = banner;
             for (const d of data) {

package/lib/request-api.mjs

@@ -37,16 +37,12 @@ const DEBUG = util.isDebug();
  */
 export const request2 = /** @type {IESIRequestFunction2} */ (async (method, endpoint, opt) => {
     // When only options are provided
-    const actualOpt = /** @type {NonNullable<typeof opt> & util.ESIRequestOptions} */ (opt || {});
-    /** @type {number[]=} */
-    let pathParams;
-    if (typeof actualOpt.pathParams === "number" || Array.isArray(actualOpt.pathParams)) {
-        pathParams = /** @type {number[]} */ (Array.isArray(actualOpt.pathParams) ? actualOpt.pathParams : [actualOpt.pathParams]);
-    }
-    if (Array.isArray(pathParams)) {
+    const nOpt = util.normalizeOptions([opt]);
+    if (util.hasPathParams(nOpt)) {
+        const pathParams = Array.isArray(nOpt.pathParams) ? nOpt.pathParams : [nOpt.pathParams];
         endpoint = util.replaceCbt(endpoint, pathParams);
     }
-    const { rqopt, qss } = util.initOptions(method, actualOpt);
+    const { rqopt, qss } = util.initOptions(method, nOpt);
     const endpointUrl = util.curl(endpoint);
     const up = new URLSearchParams(qss);
     const url = `${endpointUrl}${up.size ? `?${up}` : ""}`;
@@ -59,7 +55,7 @@ export const request2 = /** @type {IESIRequestFunction2} */ (async (method, endp
         }
         // else if (isError(status)) {}
         // Actually, throw Error
-        throw await util.handleESIError(res, endpointUrl, actualOpt.cancelable);
+        throw await util.handleESIError(res, endpointUrl, nOpt.cancelable);
     }
     catch (e) {
         log(e);
@@ -69,8 +65,9 @@ export const request2 = /** @type {IESIRequestFunction2} */ (async (method, endp
 // implements rest methods of `request` (IESIRequestFunction2)
 //
 /** @type {TESIEntryMethod[]} */ (["get", "post", "put", "delete"]).forEach((method) => {
-    request2[method] = /** @type {TESIRequestFunctionEachMethod2<typeof method, util.ESIRequestOptions>} */ ((endpoint, opt) => {
-        // @ts-expect- error TODO: ts(2345)
-        return request2(method, endpoint, /** @type {Parameters<typeof request2>[2]} */ (opt));
+    request2[method] = /** @type {TESIRequestFunctionEachMethod2<typeof method, util.ESIRequestOptions>} */ ((endpoint, ...opt) => {
+        // @ts-expect-error TODO: ts(2345)
+        return request2(method, endpoint, ...opt);
+        // return request2(method, endpoint, /** @type {Parameters<typeof request2>[2]} */(opt) as Parameters<typeof request2>[2]);
     });
 });

package/lib/rq-util.d.mts

@@ -27,7 +27,7 @@ export type Truthy = string | number | boolean;
 /**
  * __{Header}.{Payload}.{Signature}__
  */
-export type TAcccessToken = `${string}.${string}.${string}`;
+export type TAccessToken = `${string}.${string}.${string}`;
 export type ESIRequestOptions = {
     /**
      * query params for ESI request.
@@ -53,14 +53,45 @@ export type ESIRequestOptions = {
     /**
      * Can be an empty object if no authentication is required.description
      */
-    token?: TAcccessToken;
+    token?: TAccessToken;
     /**
      * cancel request immediately
      */
     cancelable?: AbortController;
 };
 /**
- * @typedef {string | number | boolean} Truthy
+ * type of the JWT token `payload` section
+ */
+export declare type TJWTPayload = {
+    /** scopes. */
+    scp: string[];
+    /** uuid of the token */
+    jti: string;
+    /** jwt type */
+    kid: string;
+    /** contains EVE character ID.
+     * ```
+     * "CHARACTER:EVE:<character_id>"
+     * ```
+     */
+    sub: `CHARACTER:EVE:${number}`;
+    /** Application client ID. */
+    azp: string;
+    /** EVE character name. */
+    name: string;
+    /** owner hash. */
+    owner: string;
+    /** expire date as 1/1000. (UNIX timestamp) */
+    exp: number;
+    /** issuer host name. */
+    iss: string;
+};
+/**
+ * @import * as ESIUtil from "./rq-util.mjs";
+ * @typedef {ESIUtil.Truthy} Truthy
+ * @typedef {ESIUtil.TAccessToken} TAccessToken
+ * @typedef {ESIUtil.TJWTPayload} TJWTPayload
+ * @typedef {ESIUtil.ESIRequestOptions} ESIRequestOptions
  */
 /**
  * simple named error class.
@@ -74,15 +105,13 @@ export declare class ESIErrorLimitReachedError extends ESIRequestError {
     constructor();
     valueOf(): number;
 }
-/**
- * @typedef {import("./rq-util.mjs").ESIRequestOptions} ESIRequestOptions
- */
 /**
  * @template T
+ * @template {Record<string, unknown>} O
  * @param {[T] | [(T | undefined)?]} opt
- * @returns {NonNullable<T>}
+ * @returns {NonNullable<T> & O}
  */
-export declare const normalizeOptions: <T extends unknown>(opt: [T] | [(T | undefined)?]) => NonNullable<T>;
+export declare const normalizeOptions: <T extends unknown, O extends Record<string, unknown> = ESIRequestOptions>(opt: [T] | [(T | undefined)?]) => (NonNullable<T> & O);
 /**
  * #### status: 200 | 201 | 204
  *
@@ -92,10 +121,11 @@ export declare const normalizeOptions: <T extends unknown>(opt: [T] | [(T | unde
  * @param {string} endpointUrl
  * @param {RequestInit} requestOpt
  * @param {URLSearchParams} urlParams
- * @param {(minus?: Truthy) => void=} increment
+ * @param {(minus?: Truthy) => void=} progress
+ * @param {true=} allowFetchPages 2025/4/26
  * @returns {Promise<any>}
  */
-export declare const handleSuccessResponse: (response: Response, endpointUrl: string, requestOpt: RequestInit, urlParams: URLSearchParams, increment?: (minus?: Truthy) => void) => Promise<any>;
+export declare const handleSuccessResponse: (response: Response, endpointUrl: string, requestOpt: RequestInit, urlParams: URLSearchParams, progress?: (minus?: Truthy) => void, allowFetchPages?: true) => Promise<any>;
 /**
  * @import {
  *     TESIErrorStats,
@@ -152,11 +182,13 @@ export declare const initOptions: (method: string, opt: ESIRequestOptions) => {
  * @param {RequestInit} rqopt request options
  * @param {URLSearchParams} usp queries
  * @param {number} pc pageCount
- * @param {(minus?: number) => void=} increment
+ * @param {(minus?: number) => void=} progress
  * @returns {Promise<T | null>}
  */
-export declare const fetchP: <T extends unknown>(endpointUrl: string, rqopt: RequestInit, usp: URLSearchParams, pc: number, increment?: (minus?: Truthy) => void) => Promise<T | null>;
+export declare const fetchP: <T extends unknown>(endpointUrl: string, rqopt: RequestInit, usp: URLSearchParams, pc: number, progress?: (minus?: Truthy) => void) => Promise<T | null>;
 /** ### replace (C)urly (B)races (T)oken
+ *
+ * + Replace each `{…}` placeholder in the endpoint string with the corresponding ID.
  *
  * @example
  * "/characters/{character_id}/skills"
@@ -164,18 +196,39 @@ export declare const fetchP: <T extends unknown>(endpointUrl: string, rqopt: Req
  * "/characters/<char.character_id>/skills"
  *
  * @template {unknown} T
- * @param {T} endpoint e.g - "/characters/{character_id}/"
- * @param {number[]} ids
- * @returns {T} fragment of qualified endpoint uri or null.
+ * @param {T} endpoint An endpoint template, e.g. "/characters/{character_id}/skills"
+ * @param {number[]} ids An array of numbers to fill into each placeholder, in order of appearance
+ * @returns {T} A fully-qualified endpoint string with all `{…}` tokens replaced by their IDs
  */
 export declare const replaceCbt: <T extends unknown>(endpoint: T, ids: number[]) => T;
 /**
  * @template {unknown} T
- * @param {T} endp this means endpoint url fragment like `/characters/{character_id}/` or `/characters/{character_id}/agents_research/`
+ * @param {T} endpoint this means endpoint url fragment like `/characters/{character_id}/` or `/characters/{character_id}/agents_research/`
  *   + The version parameter is forced to apply `latest`
  * @returns {string}
  */
-export declare const curl: <T extends unknown>(endp: T) => string;
+export declare const curl: <T extends unknown>(endpoint: T) => string;
+/**
+ * Type guard that checks whether the given object has a `pathParams` property
+ * of type `number` or `number[]`.
+ *
+ * @template {Record<string, unknown>} T - The type of the object being checked.
+ * @param {T} opt - The object to inspect.
+ * @returns {opt is (T & { pathParams: number | number[] })}
+ *   `true` if `opt` contains a `pathParams` property whose value is either
+ *   a single number or an array of numbers, otherwise `false`.
+ *
+ * @date 2025/4/28
+ */
+export declare function hasPathParams<T extends Record<string, unknown>>(opt: T): opt is (T & {
+    pathParams: number | number[];
+});
+/**
+ *
+ * @param {string} accessToken OAuth 2.0 access token
+ * @returns {TJWTPayload}
+ */
+export declare const getJWTPayload: (accessToken: string) => TJWTPayload;
 /**
  * @date 2020/03/31
  * @version 2.1
@@ -194,6 +247,8 @@ type TPrependParams = TESIRequestFunctionSignature2<ESIRequestOptions> | TESIReq
 /**
  * #### Fire a request that does not require authentication.
  *
+ * + __CAVEAT:__ This function should only be used for testing.
+ *
  * @param {TPrependParams} fn
  * @returns {Promise<void>}
  */