enka.ts 1.0.0

package/README.md

@@ -0,0 +1,50 @@
+# enka.ts
+
+Typed Genshin Impact enka.network API wrapper that works
+
+## Features
+
+- Built-in TTL cache using Enka's response `ttl`
+- Client-side rate limiter (default: 50 requests / minute)
+- Automatic avatar resolution using https://gi.yatta.moe/api/v2/en/avatar
+- Fully typed responses
+- Typed error handling
+
+## Install
+
+```sh
+$ bun i enka.ts
+```
+
+## Usage
+
+```ts
+import { ApiError, fetchEnka } from "enka.ts";
+
+try {
+  const player = await fetchEnka("800123456");
+
+  // Or use ?info endpoint to exclude build details for faster query
+  const playerInfo = await fetchEnka("800123456", "info");
+
+  console.log(player.playerInfo.nickname);
+} catch(err) {
+  if(err instanceof ApiError) {
+    if(err.type === "uid_format") // handle invalid uid format
+    else if(err.type === "not_found") // handle user not found
+    else if(err.type === "maintenance") // handle maintenance
+    else if(err.type === "internal") // handle internal server error
+    else if(err.type === "ratelimit") // handle rate limit exceeded
+  }
+}
+```
+
+> [!NOTE]
+> Locations that normally contain `avatarId` will also include a resolved
+> `avatar` object:
+> ```ts
+> {
+>   avatarId: number;
+>   name: string;
+>   element: AvatarElement;
+> }

package/dist/index.d.ts

@@ -0,0 +1,145 @@
+declare class TTLCache {
+    private cache;
+    get<T>(key: string): T | undefined;
+    clean(): void;
+    set<T>(key: string, value: T, ttlSeconds: number): void;
+}
+
+declare namespace ApiResponse {
+    interface Root {
+        uid: string;
+        ttl: number;
+        playerInfo: PlayerInfo;
+        avatarInfoList?: AvatarInfo[];
+    }
+    interface PlayerInfo {
+        nickname: string;
+        signature: string;
+        level: number;
+        worldLevel: number;
+        namecardId: number;
+        finishAchievementNum: number;
+        towerFloorIndex: number;
+        towerLevelIndex: number;
+        showAvatarInfoList: ShowAvatarInfo[];
+        showNameCardIdList: number[];
+        profilePicture: {
+            avatarId?: number;
+            id?: number;
+            costumeId?: number;
+        };
+    }
+    interface ShowAvatarInfo {
+        avatarId: number;
+        level: number;
+        costumeId?: number;
+    }
+    interface AvatarInfo {
+        avatarId: number;
+        propMap: Record<string, PropValue>;
+        fightPropMap: Record<string, number>;
+        skillDepotId: number;
+        inherentProudSkillList?: number[];
+        talentIdList?: number[];
+        skillLevelMap?: Record<string, number>;
+        equipList?: Equip[];
+        fetterInfo?: {
+            expLevel: number;
+        };
+    }
+    interface PropValue {
+        type: number;
+        ival?: string;
+        val?: number;
+    }
+    interface Equip {
+        itemId: number;
+        reliquary?: ArtifactData;
+        weapon?: WeaponData;
+        flat: FlatData;
+    }
+    interface WeaponData {
+        level: number;
+        promoteLevel: number;
+        affixMap?: Record<string, number>;
+    }
+    interface ArtifactData {
+        level: number;
+        mainPropId: number;
+        appendPropIdList?: number[];
+    }
+    interface FlatData {
+        nameTextMapHash: number;
+        setNameTextMapHash?: number;
+        icon: string;
+        rankLevel?: number;
+        reliquaryMainstat?: {
+            mainPropId: string;
+            statValue: number;
+        };
+        reliquarySubstats?: {
+            appendPropId: string;
+            statValue: number;
+        }[];
+        weaponStats?: {
+            appendPropId: string;
+            statValue: number;
+        }[];
+    }
+}
+declare enum AvatarElement {
+    Pyro = "Fire",
+    Hydro = "Water",
+    Electro = "Electric",
+    Cryo = "Ice",
+    Dendro = "Grass",
+    Anemo = "Wind",
+    Geo = "Rock"
+}
+interface BaseAvatar {
+    avatarId: number;
+    name: string;
+    element: AvatarElement;
+}
+type ResolveAvatar<T extends {
+    avatarId: number;
+}> = Omit<T, "avatarId"> & {
+    avatar: BaseAvatar;
+};
+type ResolvedProfilePicture = Omit<ApiResponse.PlayerInfo["profilePicture"], "avatarId"> & {
+    avatar?: BaseAvatar;
+};
+type ResolvedPlayerInfo = Omit<ApiResponse.PlayerInfo, "showAvatarInfoList" | "profilePicture"> & {
+    profilePicture: ResolvedProfilePicture;
+    showAvatarInfoList: ResolveAvatar<ApiResponse.ShowAvatarInfo>[];
+};
+type ResolvedAvatarInfo = ResolveAvatar<ApiResponse.AvatarInfo>;
+type ResolvedRoot = Omit<ApiResponse.Root, "playerInfo" | "avatarInfoList"> & {
+    playerInfo: ResolvedPlayerInfo;
+    avatarInfoList?: ResolvedAvatarInfo[];
+};
+
+declare const uidRegex: RegExp;
+type Mode = "full" | "info";
+declare function fetchEnka(uid: string, mode?: Mode): Promise<ResolvedRoot>;
+
+type ApiErrorType = "uid_format" | "not_found" | "maintenance" | "internal" | "ratelimit";
+declare class ApiError extends Error {
+    type: ApiErrorType;
+    constructor(type: ApiErrorType, message?: string);
+}
+
+declare class RateLimiter {
+    private limit;
+    private mode;
+    private active;
+    private queue;
+    constructor(limit: number, interval: number, mode?: "wait" | "throw");
+    private flush;
+    fill(): void;
+    acquire(): Promise<void>;
+}
+
+declare function resolveRoot(data: ApiResponse.Root): Promise<ResolvedRoot>;
+
+export { ApiError, ApiResponse, AvatarElement, type BaseAvatar, type Mode, RateLimiter, type ResolveAvatar, type ResolvedAvatarInfo, type ResolvedPlayerInfo, type ResolvedProfilePicture, type ResolvedRoot, TTLCache, fetchEnka, resolveRoot, uidRegex };

package/dist/index.js

@@ -0,0 +1,206 @@
+// src/cache.ts
+var TTLCache = class {
+  // biome-ignore lint/suspicious/noExplicitAny: cache mapping
+  cache = /* @__PURE__ */ new Map();
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return;
+    if (Date.now() > entry.expires) {
+      this.cache.delete(key);
+      return;
+    }
+    queueMicrotask(this.clean.bind(this));
+    return entry.value;
+  }
+  clean() {
+    for (const [key, entry] of this.cache) {
+      if (Date.now() > entry.expires) {
+        this.cache.delete(key);
+        return;
+      }
+    }
+  }
+  set(key, value, ttlSeconds) {
+    this.cache.set(key, {
+      value,
+      expires: Date.now() + ttlSeconds * 1e3
+    });
+  }
+};
+
+// src/errors.ts
+var ApiError = class extends Error {
+  type;
+  constructor(type, message) {
+    if (message) super(message);
+    else
+      switch (type) {
+        case "uid_format":
+          super("Invalid UID format");
+          break;
+        case "not_found":
+          super("User not found");
+          break;
+        case "maintenance":
+          super("Enka is under maintenance");
+          break;
+        case "internal":
+          super("Internal server error");
+          break;
+        case "ratelimit":
+          super("Rate limit exceeded");
+          break;
+        default:
+          super("Unknown Error");
+      }
+    this.type = type;
+  }
+};
+
+// src/ratelimit.ts
+var RateLimiter = class {
+  constructor(limit, interval, mode = "wait") {
+    this.limit = limit;
+    this.mode = mode;
+    setInterval(() => {
+      this.active = 0;
+      this.flush();
+    }, interval);
+  }
+  active = 0;
+  queue = [];
+  flush() {
+    while (this.queue.length && this.active < this.limit) {
+      this.active++;
+      const next = this.queue.shift();
+      next();
+    }
+  }
+  fill() {
+    this.active = this.limit;
+  }
+  async acquire() {
+    if (this.active < this.limit) {
+      this.active++;
+      return;
+    }
+    if (this.mode === "throw") {
+      throw new ApiError("ratelimit", "Rate limit exceeded (Package side)");
+    }
+    await new Promise((resolve) => {
+      this.queue.push(resolve);
+    });
+  }
+};
+
+// src/types.ts
+var AvatarElement = /* @__PURE__ */ ((AvatarElement3) => {
+  AvatarElement3["Pyro"] = "Fire";
+  AvatarElement3["Hydro"] = "Water";
+  AvatarElement3["Electro"] = "Electric";
+  AvatarElement3["Cryo"] = "Ice";
+  AvatarElement3["Dendro"] = "Grass";
+  AvatarElement3["Anemo"] = "Wind";
+  AvatarElement3["Geo"] = "Rock";
+  return AvatarElement3;
+})(AvatarElement || {});
+
+// src/assets.ts
+var avatarMap = null;
+async function loadAvatars() {
+  if (avatarMap) return avatarMap;
+  const res = await fetch("https://gi.yatta.moe/api/v2/en/avatar");
+  const { data } = await res.json();
+  avatarMap = new Map(
+    Object.values(data.items).map((c) => [
+      c.id,
+      {
+        avatarId: c.id,
+        name: c.name,
+        element: c.element
+      }
+    ])
+  );
+  return avatarMap;
+}
+async function resolveAvatarId(id) {
+  const map = await loadAvatars();
+  const avatar = map.get(id);
+  if (!avatar) throw new Error(`Unknown avatar ${id}`);
+  return avatar;
+}
+
+// src/resolve.ts
+async function resolveRoot(data) {
+  const playerInfo = {
+    ...data.playerInfo,
+    profilePicture: {
+      ...data.playerInfo.profilePicture,
+      avatar: data.playerInfo.profilePicture.avatarId ? await resolveAvatarId(data.playerInfo.profilePicture.avatarId) : void 0
+    },
+    showAvatarInfoList: await Promise.all(
+      data.playerInfo.showAvatarInfoList.map(async (a) => ({
+        ...a,
+        avatar: await resolveAvatarId(a.avatarId)
+      }))
+    )
+  };
+  let avatarInfoList;
+  if (data.avatarInfoList) {
+    avatarInfoList = await Promise.all(
+      data.avatarInfoList.map(async (a) => ({
+        ...a,
+        avatar: await resolveAvatarId(a.avatarId)
+      }))
+    );
+  }
+  return {
+    ...data,
+    playerInfo,
+    avatarInfoList
+  };
+}
+
+// src/enka.ts
+var uidRegex = /^(?:[0-35-9]|18)[0-9]{8}$/;
+var cache = new TTLCache();
+var limiter = new RateLimiter(50, 6e4, "wait");
+async function fetchEnka(uid, mode = "full") {
+  if (!uidRegex.test(uid)) throw new ApiError("uid_format");
+  const key = `enka:${uid}:${mode}`;
+  const cached = cache.get(key);
+  if (cached) return cached;
+  await limiter.acquire();
+  const url = mode === "info" ? `https://enka.network/api/uid/${uid}?info` : `https://enka.network/api/uid/${uid}`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    switch (res.status) {
+      case 400:
+        throw new ApiError("uid_format");
+      case 404:
+        throw new ApiError("not_found");
+      case 424:
+        throw new ApiError("maintenance");
+      case 429:
+        throw new ApiError("ratelimit", "Rate limit exceeded (server-side)");
+      case 500:
+      case 503:
+        throw new ApiError("internal");
+      default:
+        throw new Error(`Enka request failed (${res.status})`);
+    }
+  }
+  const data = await res.json();
+  const resolved = await resolveRoot(data);
+  cache.set(key, resolved, data.ttl);
+  return resolved;
+}
+export {
+  ApiError,
+  AvatarElement,
+  RateLimiter,
+  TTLCache,
+  fetchEnka,
+  resolveRoot,
+  uidRegex
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "enka.ts",
+  "description": "Typed Genshin Impact enka.network API wrapper that works",
+  "type": "module",
+  "version": "1.0.0",
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.6",
+    "@types/bun": "latest",
+    "tsup": "^8.5.1"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "test": "bun test"
+  },
+  "keywords": [
+    "genshin",
+    "enka",
+    "genshin-impact",
+    "enka-api"
+  ],
+  "license": "MIT"
+}