### Installing starrail.js via npm

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Command to install the latest version of the starrail.js library using the Node Package Manager (npm). This is the standard way to add the library to a Node.js project.

```bash
npm install starrail.js@latest
```

--------------------------------

### JavaScript Extracting Skills, Traces, Eidolons

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Provides examples of helper functions used to extract detailed skill, trace, and eidolon data from a character instance.

```JavaScript
const skills = extractCharacterSkills(characterInstance); // returns SkillData[]
const traces = extractTraces(characterInstance); // returns TraceData[]
const eidolons = extractEidolons(characterInstance); // returns EidolonExport[]
```

--------------------------------

### Initializing the StarRail Client

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Demonstrates how to create a new instance of the main StarRail client class. The constructor accepts an options object to configure settings like the default language, cache directory path, and whether to log cache fetch operations.

```js
const client = new StarRail({
  defaultLanguage: 'en',
  cacheDirectory: './.cache',
  showFetchCacheLog: true
});
```

--------------------------------

### JavaScript Building a Character Instance

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Illustrates how to use the character builder pattern to create a character instance with specific level, ascension, and eidolon values, then logs its calculated stats.

```JavaScript
const characterData = client.getAllCharacters()[0];
const character = Character.builder()
  .character(characterData, true)
  .level(80)
  .ascension(6)
  .eidolons(0)
  .build(client);
console.log(character.stats);
```

--------------------------------

### Building a Character Instance

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Shows how to use the builder pattern provided by the Character class to create a character instance with specific level, ascension, and eidolon values. This allows representing a character with its calculated stats based on static data.

```js
const character = Character.builder()
  .character(characterData, true)
  .level(80)
  .ascension(6)
  .eidolons(0)
  .build(client);
```

--------------------------------

### JavaScript Fetching All Characters

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Demonstrates how to initialize the Star Rail client and retrieve a list of all available characters, then logs their English names.

```JavaScript
const client = new StarRail();
const characters = client.getAllCharacters();
console.log(characters.map(c => c.name.get('en')));
```

--------------------------------

### Fetching Player Data (JavaScript)

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Demonstrates how to use the `starrail.js` client to retrieve a player's public profile data. It shows fetching a user by their unique ID (UID) and logging the resulting user object.

```javascript
const user = await client.fetchUser(800069903);
console.log(user);
```

--------------------------------

### JavaScript Fetching Player Data

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Shows how to use the client to asynchronously fetch data for a specific player ID and log the resulting user object.

```JavaScript
const user = await client.fetchUser(800069903);
console.log(user);
```

--------------------------------

### Updating Cache Data (JavaScript)

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Illustrates the process of initializing the `starrail.js` client and updating its local cache of game assets. This ensures the client has the latest data for characters, light cones, and other game elements.

```javascript
const client = new StarRail({ showFetchCacheLog: true });
await client.cachedAssetsManager.fetchAllContents();
```

--------------------------------

### Defining Trace Data Interface (TypeScript)

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Specifies the TypeScript interface `TraceData` for representing character traces (major and minor). It details properties such as ID, name, description, unlock requirements, type, and associated stat bonuses.

```typescript
interface TraceData {
  id: number;
  name: string | null;
  description: string | null;
  iconPath: string | null;
  isUnlockedByDefault: boolean;
  ascensionRequirement: number | null;
  traceType: "Minor" | "Major";
  stats: StatBonus[];
  effectType?: string | null;
  paramList?: number[];
}
```

--------------------------------

### Extracting Character Traces (TypeScript)

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

This function iterates through a character's skill tree nodes to identify and extract trace data (both minor and major traces). It skips technique nodes, retrieves leveled node data, extracts stats and descriptions, handles different trace types (Minor/Major), and populates a list of trace data objects. It requires `Character`, `TraceData`, `SkillTreeNode`, `SkillLevel`, `StatPropertyValue`, `LeveledSkill`, `safeGetText`, `safeNumber`, `safeGetDynamicText`, and `effectTypeTranslation`.

```typescript
function extractTraces(characterInstance: Character): TraceData[] {
    const tracesOutput: TraceData[] = [];
    for (const treeNode of characterInstance.skillTreeNodes as SkillTreeNode[]) {
        // Generalized: Skip Technique node by checking skillType
        if (
            treeNode.levelUpSkills &&
            treeNode.levelUpSkills.length > 0 &&
            treeNode.levelUpSkills[0].skillType === "Maze"
        ) continue;
        if (treeNode.maxLevel === 1) {
            const skillLevel = new SkillLevel(1, 0);
            const leveledNode = treeNode.getSkillTreeNodeByLevel(skillLevel);
            if (!leveledNode) {
                continue;
            }
            const descArr = leveledNode.getFullDescription(true);
            const detail = descArr[0]?.ref;
            const traceData: Partial<TraceData> = {
                id: treeNode.id,
                name: safeGetText(treeNode.name),
                iconPath: treeNode.icon?.url,
                isUnlockedByDefault: treeNode.isUnlockedByDefault,
                ascensionRequirement: safeNumber(leveledNode._data.AvatarPromotionLimit, null),
                stats: [],
            };
            if (detail instanceof StatPropertyValue) {
                traceData.traceType = "Minor";
                traceData.stats!.push({
                    type: String(detail.type),
                    value: detail.value,
                    isPercent: detail.isPercent
                });
                traceData.description = `${safeGetText(detail.statProperty?.name)} +${detail.isPercent ? `${detail.value * 100}%` : detail.value}`;
            } else if (detail instanceof LeveledSkill || !detail) {
                traceData.traceType = "Major";
                traceData.description = safeGetDynamicText(leveledNode.description, leveledNode.paramList) || safeGetText(leveledNode.description);
                traceData.paramList = leveledNode.paramList;
                if (detail instanceof LeveledSkill) {
                    traceData.effectType = effectTypeTranslation[detail.effectType];
                    traceData.description = safeGetDynamicText(detail.description, detail.paramList) || traceData.description;
                    if (!traceData.paramList || traceData.paramList.length === 0) {
                        traceData.paramList = detail.paramList;
                    }
                }
            } else {
                continue;
            }
            if (leveledNode.stats && leveledNode.stats.length > 0) {
                for (const statPropVal of leveledNode.stats) {
                    const alreadyAdded = traceData.stats!.some(s =>
                        s.type === String(statPropVal.type) && s.value === statPropVal.value
                    );
                    if (!alreadyAdded) {
                        traceData.stats!.push({
                            type: String(statPropVal.type),
                            value: statPropVal.value,
                            isPercent: statPropVal.isPercent
                        });
                    }
                }
            }
            tracesOutput.push(traceData as TraceData);
        }
    }
    return tracesOutput;
}
```

--------------------------------

### Defining Skill Data Interface (TypeScript)

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Defines the TypeScript interface `SkillData` used to structure information about character skills in Honkai: Star Rail. It includes properties like ID, name, type, level data, and icon paths.

```typescript
interface SkillData {
  id: string;
  groupId: string;
  name: string;
  groupName: string;
  effectType: string;
  skillType: string;
  StanceDamageType: string;
  maxLevel: number;
  description: string;
  break: string;
  SPNeed: number;
  BPNeed: number;
  InitCoolDown: number;
  CoolDown: number;
  DelayRatio: number;
  SPMultipleRatio: number;
  ShowStanceList: number[];
  levels: SkillLevelData[];
  iconPath: string;
  treeNodeIconPath: string;
}
```

--------------------------------

### Defining Character Base Stats Interface (TypeScript)

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Defines the TypeScript interface `CharacterBaseStats` for structuring a character's base statistics at different ascension and level points. It includes core stats like HP, ATK, DEF, SPD, Crit Rate/Dmg, and Taunt.

```typescript
interface CharacterBaseStats {
  ascension: number;
  level: number;
  cost: { id: number; count: number }[];
  atkBase: number;
  hpBase: number;
  defBase: number;
  spdBase: number;
  critRate: number;
  critDmg: number;
  tauntBase: number;
}
```

--------------------------------

### SkillData Interface Definition

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Defines the TypeScript interface for `SkillData`, which represents the static definition of a character's skill. It includes properties like ID, name, type, cooldown, SP cost, and references to skill levels and icons.

```ts
interface SkillData {
    id: string;
    groupId: string;
    name: string;
    groupName: string;
    effectType: string;
    skillType: string;
    StanceDamageType: string;
    maxLevel: number;
    description: string;
    break: string;
    SPNeed: number;
    BPNeed: number;
    InitCoolDown: number;
    CoolDown: number;
    DelayRatio: number;
    SPMultipleRatio: number;
    ShowStanceList: number[];
    levels: SkillLevelData[];
    iconPath: string;
    treeNodeIconPath: string;
}
```

--------------------------------

### Processing Skill Levels and Data Mapping (TypeScript)

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

This snippet iterates through the maximum levels of a skill, retrieves the leveled skill data for each level, populates a 'levels' array within a skill data object, sorts the levels, and adds the complete skill data object to an output array. It handles potential missing leveled skill data.

```typescript
            break: String(refData.StanceDamageDisplay),
            SPNeed: refData.SPNeed?.Value ?? refData.SPNeed,
            BPNeed: refData.BPNeed?.Value ?? refData.BPNeed,
            InitCoolDown: refData.InitCoolDown,
            CoolDown: refData.CoolDown,
            DelayRatio: refData.DelayRatio?.Value ?? refData.DelayRatio,
            SPMultipleRatio: refData.SPMultipleRatio?.Value ?? refData.SPMultipleRatio,
            ShowStanceList: refData.ShowStanceList?.map(obj => obj.Value),
            levels: [],
            iconPath: baseSkillDefinition.skillIcon?.url,
            treeNodeIconPath: treeNode.icon?.url,
        };
        for (let currentLevelValue = 1; currentLevelValue <= baseSkillDefinition.maxLevel; currentLevelValue++) {
            const skillLevelObj: SkillLevel = new SkillLevel(currentLevelValue, 0);
            const leveledSkill: LeveledSkill = baseSkillDefinition.getSkillByLevel(skillLevelObj);
            if (!leveledSkill) {
                continue;
            }
            skillData.levels.push({
                level: leveledSkill.level.value,
                params: leveledSkill.paramList || []
            });
        }
        skillData.levels.sort((a, b) => a.level - b.level);
        skillsOutput.push(skillData);
    }
    return skillsOutput;
}
```

--------------------------------

### CharacterBaseStats Interface Definition

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Defines the TypeScript interface for `CharacterBaseStats`, outlining the properties that represent a character's base statistics at a given ascension and level, including HP, ATK, DEF, SPD, Crit Rate, Crit Damage, and Taunt.

```ts
interface CharacterBaseStats {
    ascension: number;
    level: number;
    cost: { id: number; count: number }[];
    atkBase: number;
    hpBase: number;
    defBase: number;
    spdBase: number;
    critRate: number;
    critDmg: number;
    tauntBase: number;
}
```

--------------------------------

### TypeScript Interface TraceData

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Defines the structure for trace data within the Star Rail API, including stats, unlock requirements, and type.

```TypeScript
interface StatBonus {
    type: string;
    value: number;
    isPercent: boolean;
}

interface TraceData {
    id: number;
    name: string | null;
    description: string | null;
    iconPath: string | null;
    isUnlockedByDefault: boolean;
    ascensionRequirement: number | null;
    traceType: "Minor" | "Major";
    stats: StatBonus[];
    effectType?: string | null;
    paramList?: number[];
}
```

--------------------------------

### TypeScript Type EidolonExport

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Defines the structure for exported Eidolon data, omitting certain properties and including specific details like parameter lists and skill upgrades.

```TypeScript
type EidolonExport = Omit<Eidolon, 'client' | '_data' | 'picture' | 'skillsLevelUp' | 'constructor'> & {
    paramList: number[];
    description: string | null;
    skillsLevelUp: {
        skillId: string | number;
        skillType: string;
        skillName: string;
        upgrade: number;
    }[];
};
```

--------------------------------

### SkillLevelData Interface Definition

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Defines the TypeScript interface for `SkillLevelData`, which represents the parameters and values associated with a specific level of a character's skill. It includes the level number and an array of numerical parameters.

```ts
interface SkillLevelData {
    level: number;
    params: number[];
}
```

--------------------------------

### Extracting Character Eidolon Data (TypeScript)

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

This function extracts eidolon information from a `Character` instance, handling dynamic text and skill level-up details. It maps the data to an array of `EidolonExport` objects, sorting them by rank before returning.

```typescript
function extractEidolons(characterInstance: Character): EidolonExport[] {
    const eidolonsOutput: EidolonExport[] = [];
    if (!characterInstance.characterData || !characterInstance.characterData.eidolons) return eidolonsOutput;
    const skills = characterInstance.skills || [];
    const skillMap = new Map<string | number, Skill>();
    for (const skill of skills) {
        skillMap.set(skill.id, skill);
    }
    for (const eidolon of characterInstance.characterData.eidolons as Eidolon[]) {
        const paramList = (eidolon as any)._data?.Param?.map((p: any) => p.Value) || [];
        let description: string | null = null;
        if (eidolon.description instanceof DynamicTextAssets) {
            description = safeGetDynamicText(eidolon.description, paramList);
        } else {
            description = safeGetText(eidolon.description);
        }
        const skillsLevelUpArr: {
            skillId: string | number;
            skillType: string;
            skillName: string;
            upgrade: number;
        }[] = [];
        if (eidolon.skillsLevelUp && typeof eidolon.skillsLevelUp === 'object') {
            for (const key of Object.keys(eidolon.skillsLevelUp)) {
                const skillUp = eidolon.skillsLevelUp[key];
                const skill = skillUp.skill;
                skillsLevelUpArr.push({
                    skillId: skill.id,
                    skillType: skill && skill.skillType ? (skillTypeTranslation[skill.skillType] || skill.skillType) : '',
                    skillName: skill && skill.name ? safeGetText(skill.name) : '',
                    upgrade: skillUp.levelUp
                });
            }
        }
        eidolonsOutput.push({
            id: eidolon.id,
            rank: eidolon.rank,
            icon: eidolon.icon?.url,
            name: safeGetText(eidolon.name),
            description,
            paramList,
            skillsLevelUp: skillsLevelUpArr
        });
    }
    return eidolonsOutput.sort((a, b) => a.rank - b.rank);
}
```

--------------------------------

### Defining Eidolon Export Type (TypeScript)

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Creates a TypeScript type `EidolonExport` by omitting non-serializable or circular references from the base `Eidolon` type. It includes essential data like parameter lists, descriptions, and skill level-up details for serialization.

```typescript
type EidolonExport = Omit<Eidolon, 'client' | '_data' | 'picture' | 'skillsLevelUp' | 'constructor'> & {
  paramList: number[];
  description: string | null;
  skillsLevelUp: {
    skillId: string | number;
    skillType: string;
    skillName: string;
    upgrade: number;
  }[];
};
```

--------------------------------

### Extracting Character Skills Function (TypeScript)

Source: https://github.com/foxfire1st/starrailapi-documentation/blob/master/README.md

Provides the implementation of the `extractCharacterSkills` function, which iterates through a character's skill tree nodes to collect and format skill data. It processes skill definitions, levels, and descriptions into a serializable `SkillData` array.

```typescript
function extractCharacterSkills(characterInstance: Character): SkillData[] {
    const skillsOutput: SkillData[] = [];
    for (const treeNode of characterInstance.skillTreeNodes as LeveledSkillTreeNode[]) {
        if (!treeNode.levelUpSkills || treeNode.levelUpSkills.length === 0) {
            continue;
        }
        const baseSkillDefinition: Skill = treeNode.levelUpSkills[0];
        if (!baseSkillDefinition) {
            continue;
        }
        if (!skillTypeTranslation[baseSkillDefinition.skillType]) {
            continue;
        }
        const levelOneSkillLevelObj = new SkillLevel(1, 0);
        const firstLeveledSkill = baseSkillDefinition.getSkillByLevel(levelOneSkillLevelObj);
        let rawDesc = "";
        if (firstLeveledSkill) {
            rawDesc = safeGetText(firstLeveledSkill.description);
        }
        const leveledNode: LeveledSkillTreeNode = treeNode.getSkillTreeNodeByLevel(new SkillLevel(1, 0));
        const descArr = leveledNode.getFullDescription(false);
        //@ts-ignore
        const refData = descArr[0].ref._skillsData?.[0] || {};
        const skillData: SkillData = {
            id: String(baseSkillDefinition.id),
            groupId: String(treeNode.id),
            name: safeGetText(baseSkillDefinition.name),
            groupName: safeGetText(treeNode.name),
            effectType: effectTypeTranslation[baseSkillDefinition.effectType],
            skillType: skillTypeTranslation[baseSkillDefinition.skillType],
            StanceDamageType: elementTranslation[refData.StanceDamageType] ?? refData.StanceDamageType,
            maxLevel: baseSkillDefinition.maxLevel,
            description: rawDesc,
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.