eve-esi-types 3.2.6 → 3.2.8

package/lib/rq-util.mjs

@@ -27,7 +27,11 @@ let LOG = false;
  */
 export const BASE = "https://esi.evetech.net";
 /**
- * @typedef {string | number | boolean} Truthy
+ * @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.
@@ -45,20 +49,18 @@ export class ESIErrorLimitReachedError extends ESIRequestError {
         return 420;
     }
 }
-/**
- * @typedef {import("./rq-util.mjs").ESIRequestOptions} ESIRequestOptions
- */
 // - - - - - - - - - - - - - - - - - - - -
 //            utility functions
 // - - - - - - - - - - - - - - - - - - - -
 /**
  * @template T
+ * @template {Record<string, unknown>} O
  * @param {[T] | [(T | undefined)?]} opt
- * @returns {NonNullable<T>}
+ * @returns {NonNullable<T> & O}
  */
 export const normalizeOptions = (opt) => {
     //* ctt
-    return /** @type {NonNullable<T>} */ (opt.length ? (opt[0] ?? {}) : {});
+    return /** @type {NonNullable<T> & O} */ (opt.length ? (opt[0] ?? {}) : {});
     /*/
     const r = /** @type {NonNullable<T>} * /(opt.length ? (opt[0] ?? {}): {}) as NonNullable<T>;
     log(`normalizeOptions::[${JSON.stringify(r)}]`);
@@ -74,30 +76,33 @@ export const normalizeOptions = (opt) => {
  * @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 const handleSuccessResponse = async (response, endpointUrl, requestOpt, urlParams, increment = () => { }) => {
+export const handleSuccessResponse = async (response, endpointUrl, requestOpt, urlParams, progress = () => { }, allowFetchPages) => {
     // NoContentResponse
     if (response.status === 204)
         return {};
     /** @type {any} */
     const data = await response.json();
-    // - - - - x-pages response.
-    // +undefined is NaN
-    // @ts-expect-error becouse +null is 0
-    const pc = +response.headers.get("x-pages");
-    // has remaining pages? NaN > 1 === false !isNaN(pageCount)
-    if (pc > 1) {
-        LOG && log('found "x-pages" header, pages: %d', pc);
-        const remData = await fetchP(endpointUrl, requestOpt, urlParams, pc, increment);
-        // finally, decide product data.
-        if (isArray(data) && isArray(remData)) {
-            // DEVNOTE: 2019/7/23 15:01:48 - types
-            return data.concat(remData);
-        }
-        else {
-            remData && Object.assign(data, remData);
+    if (allowFetchPages) {
+        // - - - - x-pages response.
+        // +undefined is NaN
+        // @ts-expect-error becouse +null is 0
+        const pc = +response.headers.get("x-pages");
+        // has remaining pages? NaN > 1 === false !isNaN(pageCount)
+        if (pc > 1) {
+            LOG && log('found "x-pages" header, pages: %d', pc);
+            const remData = await fetchP(endpointUrl, requestOpt, urlParams, pc, progress);
+            // finally, decide product data.
+            if (isArray(data) && isArray(remData)) {
+                // DEVNOTE: 2019/7/23 15:01:48 - types
+                return data.concat(remData);
+            }
+            else {
+                remData && Object.assign(data, remData);
+            }
         }
     }
     return data;
@@ -228,6 +233,9 @@ export const initOptions = (method, opt) => {
             qss[key] = oqs[key];
     }
     if (opt.auth) {
+        if (!opt.token) {
+            throw new Error("Authentication required: missing `token`");
+        }
         // @ts-ignore The header is indeed an object
         rqopt.headers.authorization = `Bearer ${opt.token}`;
     }
@@ -247,19 +255,19 @@ export const initOptions = (method, opt) => {
  * @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 const fetchP = async (endpointUrl, rqopt, usp, pc, increment = () => { }) => {
+export const fetchP = async (endpointUrl, rqopt, usp, pc, progress = () => { }) => {
     const rqs = [];
     for (let i = 2; i <= pc;) {
         usp.set("page", (i++) + "");
-        increment();
+        progress();
         rqs.push(fetch(`${endpointUrl}?${usp + ""}`, rqopt).then(res => res.json()).catch(reason => {
             console.warn(reason);
             return [];
         }).finally(() => {
-            increment(1);
+            progress(1);
         }));
     }
     return Promise.all(rqs).then(jsons => {
@@ -276,7 +284,10 @@ export const fetchP = async (endpointUrl, rqopt, usp, pc, increment = () => { })
         return null;
     });
 };
+const CBT_RE = /{\w+}/g;
 /** ### replace (C)urly (B)races (T)oken
+ *
+ * + Replace each `{…}` placeholder in the endpoint string with the corresponding ID.
  *
  * @example
  * "/characters/{character_id}/skills"
@@ -284,24 +295,51 @@ export const fetchP = async (endpointUrl, rqopt, usp, pc, increment = () => { })
  * "/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 const replaceCbt = (endpoint, ids) => {
     let idx = 0;
-    // @ts-expect-error
-    return endpoint.replace(/{([\w]+)}/g, () => ids[idx++] + "");
+    return /** @type {T} */ (/** @type {string} */ (endpoint).replace(CBT_RE, () => String(ids[idx++])));
 };
 /**
  * @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 const curl = (endp) => {
-    // @ts-expect-error
-    return `${BASE}/latest/${endp.replace(/^\/+|\/+$/g, "")}/`;
+export const curl = (endpoint) => {
+    return `${BASE}/latest/${/** @type {string} */ (endpoint).replace(/^\/+|\/+$/g, "")}/`;
+};
+/**
+ * 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 function hasPathParams(opt) {
+    if (typeof opt !== "object" || opt === null)
+        return false;
+    return "pathParams" in opt && (typeof opt.pathParams === "number" || Array.isArray(opt.pathParams));
+}
+/**
+ *
+ * @param {string} accessToken OAuth 2.0 access token
+ * @returns {TJWTPayload}
+ */
+export const getJWTPayload = (accessToken) => {
+    // const [header, payload, sig] = accessToken.split(".");
+    // const headerJson = a2b(header); maybe always {"alg":"RS256","kid":"JWT-Signature-Key","typ":"JWT"}
+    // const sigJson = a2b(sig);
+    const json = atob(accessToken.split(".")[1]);
+    return JSON.parse(json); // as NsEVEOAuth.TJWTPayload;
 };
 /**
  * @date 2020/03/31
@@ -345,30 +383,51 @@ export function getLogger() {
  */
 /**
  * @typedef {TESIRequestFunctionSignature2<ESIRequestOptions> | TESIRequestFunctionMethods2} TPrependParams
+ * @typedef {ReturnType<typeof fireWithoutAuth>} TFireReturn
  */
 /**
  * #### Fire a request that does not require authentication.
  *
  * @type {TESIEnhancedRequestFunctionSignature<TPrependParams, ESIRequestOptions>}
  */
+// Resolved type error (ts(2322)) using the `TFireReturn` type assertion (2025/4/29)
 const fireWithoutAuth = (fn, method, endpoint, ...opt) => {
     const arg = opt.length ? opt[0] : void 0;
     if (typeof fn === "function") {
-        return fn(method, endpoint, /** @type {Parameters<typeof fn>[2]} */ (arg));
+        return /** @type {TFireReturn} */ (
+        // @ts-expect-error TODO: ts(2345) The argument type does not match the type of the specified parameter
+        fn(method, endpoint, arg));
     }
+    return /** @type {TFireReturn} */ (
     // @ts-expect-error TODO: ts(2345) The argument type does not match the type of the specified parameter
-    return fn[method](endpoint, arg);
+    fn[method](endpoint, arg));
 };
-const token = `token.token.token`;
+// /**
+//  * ```
+//  * process.env.OAUTH_TOKEN // Spedify valid OAuth token
+//  * ```
+//  * @param envName
+//  */
+// const getEnvValue = (envName: string) => process.env[envName] ?? null;
+/** @type {TAccessToken} */
+const token = /** @type {TAccessToken} */ (process.env.OAUTH_TOKEN ?? "token.token.token");
+const ID_SomeEVECharacter = (() => {
+    if (token !== "token.token.token") {
+        const payload = getJWTPayload(token);
+        return +payload.sub.split(":")[2];
+    }
+    return 9000;
+})();
 /**
  * #### Fire a request that does not require authentication.
  *
+ * + __CAVEAT:__ This function should only be used for testing.
+ *
  * @param {TPrependParams} fn
  * @returns {Promise<void>}
  */
 export async function fireRequestsDoesNotRequireAuth(fn) {
     const { clog, rlog } = getLogger();
-    const ID_SomeEVECharacter = 90000;
     const ID_CCP_Zoetrope = 2112625428;
     try {
         // - - - - - - - - - - - -
@@ -391,17 +450,21 @@ export async function fireRequestsDoesNotRequireAuth(fn) {
             rlog("get:/incursions/".green);
             await fireWithoutAuth(fn, "get", "/incursions/").then(log);
             if (is("withError")) {
+                log(`Try character ${ID_SomeEVECharacter} assets request`);
                 await fireWithoutAuth(fn, "get", "/characters/{character_id}/assets/", {
-                    auth: true,
+                    auth: true, token,
                     pathParams: ID_SomeEVECharacter,
-                    token
                 }).then(assets => {
                     log(assets.slice(0, 5));
                 });
-                await fireWithoutAuth(fn, "delete", `/characters/${1234}/fittings/${56789}/`, {
+                log(`Try character ${ID_SomeEVECharacter} fittings request`);
+                await fireWithoutAuth(fn, "get", `/characters/${ID_SomeEVECharacter}/fittings/`, {
                     auth: true,
-                    // pathParams: [1234, 56789], // ✅ At this point, the expected semantic error is successfully triggered as intended.
-                }).catch(log);
+                    // pathParams: [ID_SomeEVECharacter, 56789], // ✅ At this point, the expected semantic error is successfully triggered as intended.
+                    token
+                }).then(fittings => {
+                    log(fittings.slice(0, 5));
+                });
             }
         }
         // - - - - - - - - - - - -
@@ -434,8 +497,7 @@ export async function fireRequestsDoesNotRequireAuth(fn) {
         //  Authentication is required, so an error will occur.
         // - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
         let willFailed = await fireWithoutAuth(fn, "get", `/characters/${ID_SomeEVECharacter}/ship/`, {
-            auth: true,
-            token //: "token.token.token"
+            auth: true, token
         });
         log(`get:/characters/${ID_SomeEVECharacter}/ship/, returns:`, willFailed);
         // in this case, "categories" and "search" is required

package/minimal-rq.mjs

@@ -29,8 +29,8 @@ const log = util.getUniversalLogger("[request-mini]: ");
 const esiMethods = /** @type {TESIRequestFunctionMethods2} */ ({});
 /** @satisfies {TESIEntryMethod[]} */ (["get", "post", "put", "delete"]).forEach((method) => {
     esiMethods[method] = /** @type {TESIRequestFunctionEachMethod2<typeof method, util.ESIRequestOptions>} */ ((endpoint, opt) => {
-        // @ts-expect -error ts(2345)
-        return request2(method, endpoint, /** @type {Parameters<typeof request2>[2]} */ (opt));
+        // @ts-expect-error ts(2345)
+        return request2(method, endpoint, opt);
     });
 });
 // It should complete correctly.

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "eve-esi-types",
-  "version": "3.2.6",
+  "version": "3.2.8",
   "description": "Extracted the main type of ESI. use for ESI request response types (version 2 only)",
   "main": "dist/v2/index.d.ts",
   "scripts": {
-    "start": "tsc -p jsconfig.json",
+    "start": "tsc",
     "test": "node request-v3.mjs -debug",
     "test:mini": "node minimal-rq.mjs -debug"
   },
@@ -21,7 +21,7 @@
     "LICENSE",
     "*.md",
     "package.json",
-    "jsconfig.json"
+    "tsconfig.json"
   ],
   "keywords": [
     "api",

package/request-v3.mjs

@@ -13,7 +13,7 @@
 // - - - - - - - - - - - - - - - - - - - -
 //               imports
 // - - - - - - - - - - - - - - - - - - - -
-import { is, curl, replaceCbt, getSDEVersion, normalizeOptions, initOptions, isDebug, fireRequestsDoesNotRequireAuth, isSuccess, handleESIError, handleSuccessResponse, } from "./lib/rq-util.mjs";
+import { is, curl, replaceCbt, hasPathParams, getSDEVersion, normalizeOptions, initOptions, isDebug, fireRequestsDoesNotRequireAuth, isSuccess, handleESIError, handleSuccessResponse, } from "./lib/rq-util.mjs";
 // - - - - - - - - - - - - - - - - - - - -
 //           constants, types
 // - - - - - - - - - - - - - - - - - - - -
@@ -37,7 +37,7 @@ const LOG = isDebug();
  */
 let ax = 0;
 /** @type {function(Truthy=): number} */
-const incrementAx = (minus) => minus ? ax-- : ax++;
+const progress = (minus) => minus ? ax-- : ax++;
 /**
  * @returns Get The Current ESI request pending count.
  */
@@ -53,16 +53,12 @@ export const getRequestPending = () => ax;
  */
 export const fire = /** @type {TESIRequestFunctionSignature2<ESIRequestOptions>} */ (async (mthd, endp, ...opt) => {
     // When only options are provided
-    const actualOpt = normalizeOptions(opt);
-    /** @type {number[]=} */
-    let pathParams;
-    if (actualOpt.pathParams) {
-        pathParams = typeof actualOpt.pathParams === "number" ? [actualOpt.pathParams] : isArray(actualOpt.pathParams) ? actualOpt.pathParams : void 0;
-    }
-    if (isArray(pathParams)) {
+    const nOpt = normalizeOptions(opt);
+    if (hasPathParams(nOpt)) {
+        const pathParams = Array.isArray(nOpt.pathParams) ? nOpt.pathParams : [nOpt.pathParams];
         endp = replaceCbt(endp, pathParams);
     }
-    const { rqopt, qss } = initOptions(mthd, actualOpt);
+    const { rqopt, qss } = initOptions(mthd, nOpt);
     const endpointUrl = curl(endp);
     const up = new URLSearchParams(qss);
     const url = `${endpointUrl}${up.size ? `?${up}` : ""}`;
@@ -72,11 +68,11 @@ export const fire = /** @type {TESIRequestFunctionSignature2<ESIRequestOptions>}
         const res = await fetch(url, rqopt).finally(() => ax--);
         // The parameters are different for successful and error responses.
         if (isSuccess(res.status)) {
-            return handleSuccessResponse(res, endpointUrl, rqopt, up, incrementAx);
+            return handleSuccessResponse(res, endpointUrl, rqopt, up, progress);
         }
         // else if (isError(status)) {}
         // Actually, throw Error
-        throw await handleESIError(res, endpointUrl, actualOpt.cancelable);
+        throw await handleESIError(res, endpointUrl, nOpt.cancelable);
     }
     catch (e) {
         throw e;

package/tagged-rq.mjs

@@ -42,8 +42,9 @@ if (util.is("withError")) {
     esi.assets.get(`/characters/${ID_CCP_Zoetrope}/assets/`, {
         auth: true
     }).then(console.log).catch(console.log);
-    esi.mail.post(`/characters/${ID_CCP_Zoetrope}/mail/`, /** @satisfies {Pick<TESIResponsePostEntry<"/characters/{character_id}/mail/">, "auth" | "body">} */ ({
+    esi.mail.post("/characters/{character_id}/mail/", ({
         auth: true,
+        pathParams: ID_CCP_Zoetrope, // ✅ At this point, the expected semantic error is successfully triggered as intended.
         body: {
             subject: "test!!",
             body: "",
@@ -52,7 +53,7 @@ if (util.is("withError")) {
                 }]
         },
         // token: "s.s.s"
-    })).then(console.log).catch(console.log);
+    }) /*  satisfies Pick<TESIResponsePostEntry<"/characters/{character_id}/mail/">, "auth" | "body"> & { pathParams: number } */).then(console.log).catch(console.log);
     esi.fittings.delete("/characters/1234/fittings/56789/", {
         // pathParams: [1234, 56789], // ✅ At this point, the expected semantic error is successfully triggered as intended.
         auth: true