npm package: @piyoraik/ffxiv-lodestone-character-lookup
Description: FFXIV Lodestone character lookup (search → character URL) and high-end achievement checks
Latest version: 1.0.9

# ffxiv-lodestone-character-lookup

FFXIV の Lodestone を使って、以下を行うための共通ライブラリです。

- `キャラクター名` と `サーバー名` から検索パラメータを作る
- キャラクター検索の先頭ヒットから「キャラクターURL（/lodestone/character/.../）」を取得する
- Lodestone からアチーブメントの達成状況と達成要件を取得する

## 動作環境

- Node.js: `>= 22`（22/24想定）
- モジュール形式: CommonJS（TypeScript からは通常の `import { ... } from ...` で利用できます）

## インストール

```sh
yarn add @piyoraik/ffxiv-lodestone-character-lookup
```

## 使い方
```ts
import {
  buildLodestoneSearchUrl,
  fetchTopCharacterResult,
  fetchAchievementDetailsByCategory,
  fetchAllAchievementDetails,
  getAllAchievementDefinitions,
  getAchievementCategoryDefinitions,
  getAchievementDefinitions,
  getAchievementCategoryId
} from "@piyoraik/ffxiv-lodestone-character-lookup";

const creator = { name: "Hoge Fuga", world: "World" };

// 1) Lodestoneの検索URLを作る
const searchUrl = buildLodestoneSearchUrl(creator);

// 2) 検索結果の状態を取得する
const searchResult = await fetchTopCharacterResult(searchUrl);
if (searchResult.status !== "ok") {
  throw new Error(`キャラクターが取得できません: ${searchResult.status}`);
}
const characterUrl = searchResult.characterUrl;

// 3) カテゴリ指定で取得する
const raids = await fetchAchievementDetailsByCategory(characterUrl, "raids");
console.log(raids);
const fieldOps = await fetchAchievementDetailsByCategory(characterUrl, "field_ops");
console.log(fieldOps);
const dungeons = await fetchAchievementDetailsByCategory(characterUrl, "dungeons");
console.log(dungeons);

// 4) 全カテゴリをまとめて取得する
const all = await fetchAllAchievementDetails(characterUrl);
console.log(all);

// 定義をまとめて取得する場合
const categories = getAchievementCategoryDefinitions();
const allAchievements = getAllAchievementDefinitions();
const raidsDefinitions = getAchievementDefinitions("raids");
const raidsCategoryId = getAchievementCategoryId("raids");
console.log(categories.length, allAchievements.length, raidsDefinitions.length, raidsCategoryId);

/*
{
  status: "ok",
  lodestone: "https://jp.finalfantasyxiv.com/lodestone/character/12345/",
  achievements: {
    raids: [
      { name: "絶バハムートを狩りし者", date: "2014/06/10", requirement: "絶バハムート討滅戦で、バハムート・プライムを討伐する" },
      { name: "万魔殿の辺獄を完全制覇せし者：ランク1", date: null, requirement: "万魔殿パンデモニウム零式：辺獄編を攻略する" }
    ]
  }
}
*/
```

## 関数一覧

| 関数 | 返り値 | 用途 |
|---|---|---|
| `buildLodestoneSearchUrl(info)` | `string` | キャラクター検索URLを生成 |
| `fetchTopCharacterResult(searchUrl)` | `Promise<{ status, characterUrl?, reason? }>` | 検索結果の状態を取得（非公開は `private`） |
| `fetchAchievementDetailsByCategory(characterUrl, category)` | `Promise<{ status, lodestone, achievements, reason? }>` | カテゴリ指定で達成状況/達成要件を取得 |
| `fetchAllAchievementDetails(characterUrl)` | `Promise<{ status, lodestone, achievements, reason? }>` | 全カテゴリの達成状況/達成要件を取得 |
| `getAchievementDefinitions(category)` | `AchievementDefinition[]` | カテゴリ指定で定義を取得 |
| `getAllAchievementDefinitions()` | `AchievementDefinition[]` | 全カテゴリの定義を取得 |
| `getAchievementCategoryDefinitions()` | `AchievementCategoryDefinition[]` | カテゴリ一覧（ID/定義）を取得 |
| `getAchievementCategoryId(category)` | `number \| undefined` | カテゴリ名からカテゴリIDを取得 |

## 対応カテゴリ一覧

| category | 説明 | categoryId |
|---|---|---|
| `raids` | レイド（高難度） | `4` |
| `field_ops` | 特殊フィールド探索 | `71` |
| `dungeons` | ダンジョン | `2` |
| `battle_general` | バトル（全般） | `1` |

## 対応アチーブメント（カテゴリ別）

このライブラリが達成判定に対応しているアチーブメントの一覧です。
アップデートごとにベストエフォートで更新し、必要であればIssueやプルリクを頂ければ優先的に対応します。
達成要件の更新には `npm run update-readme-requirements` を使用してください。

### レイド（高難度）
| 正式名 | 達成要件 |
|---|---|
| 絶バハムートを狩りし者 | 絶バハムート討滅戦で、バハムート・プライムを討伐する |
| 絶アルテマウェポンを破壊せし者 | 絶アルテマウェポン破壊作戦で、アルテマウェポンを討伐する |
| 絶アレキサンダーを破壊せし者 | 絶アレキサンダー討滅戦で、パーフェクト・アレキサンダーを討伐する |
| 絶竜詩戦争を平定せし者 | 絶竜詩戦争を平定する |
| 絶オメガ検証戦を完遂せし者 | オメガの求める検証を完遂する |
| 絶もうひとつの未来を見届けし者 | 光と闇の巫女の運命を集約させる |
| 始まりの大迷宮を制覇せし者：ランク1 | 大迷宮バハムート：邂逅編を攻略する |
| 始まりの大迷宮を制覇せし者：ランク2 | 大迷宮バハムート：邂逅編を計5回攻略する |
| 始まりの大迷宮を制覇せし者：ランク3 | 大迷宮バハムート：邂逅編を計10回攻略する |
| 第二の大迷宮を制覇せし者：ランク1 | 大迷宮バハムート：侵攻編を攻略する |
| 第二の大迷宮を制覇せし者：ランク2 | 大迷宮バハムート：侵攻編を計5回攻略する |
| 第二の大迷宮を制覇せし者：ランク3 | 大迷宮バハムート：侵攻編を計10回攻略する |
| 第二の大迷宮を制覇せし者：ランク1 | 大迷宮バハムート：侵攻編を攻略する |
| 第二の大迷宮を制覇せし者：ランク2 | 大迷宮バハムート：侵攻編を計5回攻略する |
| 第二の大迷宮を制覇せし者：ランク3 | 大迷宮バハムート：侵攻編を計10回攻略する |
| 終わりの大迷宮を制覇せし者：ランク1 | 大迷宮バハムート：真成編を攻略する |
| 終わりの大迷宮を制覇せし者：ランク2 | 大迷宮バハムート：真成編を計5回攻略する |
| 終わりの大迷宮を制覇せし者：ランク3 | 大迷宮バハムート：真成編を計10回攻略する |
| 起動せし機工城を完全制覇せし者：ランク1 | 機工城アレキサンダー零式：起動編を攻略する |
| 起動せし機工城を完全制覇せし者：ランク2 | 機工城アレキサンダー零式：起動編を計5回攻略する |
| 起動せし機工城を完全制覇せし者：ランク3 | 機工城アレキサンダー零式：起動編を計10回攻略する |
| 律動せし機工城を完全制覇せし者：ランク1 | 機工城アレキサンダー零式：律動編を攻略する |
| 律動せし機工城を完全制覇せし者：ランク2 | 機工城アレキサンダー零式：律動編を計5回攻略する |
| 律動せし機工城を完全制覇せし者：ランク3 | 機工城アレキサンダー零式：律動編を計10回攻略する |
| 天動せし機工城を完全制覇せし者：ランク1 | 機工城アレキサンダー零式：天動編を攻略する |
| 天動せし機工城を完全制覇せし者：ランク2 | 機工城アレキサンダー零式：天動編を計5回攻略する |
| 天動せし機工城を完全制覇せし者：ランク3 | 機工城アレキサンダー零式：天動編を計10回攻略する |
| 被検世界デルタを完全制覇せし者：ランク1 | 次元の狭間オメガ零式：デルタ編を攻略する |
| 被検世界デルタを完全制覇せし者：ランク2 | 次元の狭間オメガ零式：デルタ編を計5回攻略する |
| 被検世界デルタを完全制覇せし者：ランク3 | 次元の狭間オメガ零式：デルタ編を計10回攻略する |
| 被検世界シグマを完全制覇せし者：ランク1 | 次元の狭間オメガ零式：シグマ編を攻略する |
| 被検世界シグマを完全制覇せし者：ランク2 | 次元の狭間オメガ零式：シグマ編を計5回攻略する |
| 被検世界シグマを完全制覇せし者：ランク3 | 次元の狭間オメガ零式：シグマ編を計10回攻略する |
| 被検世界アルファを完全制覇せし者：ランク1 | 次元の狭間オメガ零式：アルファ編を攻略する |
| 被検世界アルファを完全制覇せし者：ランク2 | 次元の狭間オメガ零式：アルファ編を計5回攻略する |
| 被検世界アルファを完全制覇せし者：ランク3 | 次元の狭間オメガ零式：アルファ編を計10回攻略する |
| 覚醒せしエデンを完全制覇せし者：ランク1 | 希望の園エデン零式：覚醒編を攻略する |
| 覚醒せしエデンを完全制覇せし者：ランク2 | 希望の園エデン零式：覚醒編を計5回攻略する |
| 覚醒せしエデンを完全制覇せし者：ランク3 | 希望の園エデン零式：覚醒編を計10回攻略する |
| 共鳴せしエデンを完全制覇せし者：ランク1 | 希望の園エデン零式：共鳴編を攻略する |
| 共鳴せしエデンを完全制覇せし者：ランク2 | 希望の園エデン零式：共鳴編を計5回攻略する |
| 共鳴せしエデンを完全制覇せし者：ランク3 | 希望の園エデン零式：共鳴編を計10回攻略する |
| 再生せしエデンを完全制覇せし者：ランク1 | 希望の園エデン零式：再生編を攻略する |
| 再生せしエデンを完全制覇せし者：ランク2 | 希望の園エデン零式：再生編を計5回攻略する |
| 再生せしエデンを完全制覇せし者：ランク3 | 希望の園エデン零式：再生編を計10回攻略する |
| 万魔殿の辺獄を完全制覇せし者：ランク1 | 万魔殿パンデモニウム零式：辺獄編を攻略する |
| 万魔殿の辺獄を完全制覇せし者：ランク2 | 万魔殿パンデモニウム零式：辺獄編を計5回攻略する |
| 万魔殿の辺獄を完全制覇せし者：ランク3 | 万魔殿パンデモニウム零式：辺獄編を計10回攻略する |
| 万魔殿の煉獄を完全制覇せし者：ランク1 | 万魔殿パンデモニウム零式：煉獄編を攻略する |
| 万魔殿の煉獄を完全制覇せし者：ランク2 | 万魔殿パンデモニウム零式：煉獄編を計5回攻略する |
| 万魔殿の煉獄を完全制覇せし者：ランク3 | 万魔殿パンデモニウム零式：煉獄編を計10回攻略する |
| 万魔殿の天獄を完全制覇せし者：ランク1 | 万魔殿パンデモニウム零式：天獄編を攻略する |
| 万魔殿の天獄を完全制覇せし者：ランク2 | 万魔殿パンデモニウム零式：天獄編を計5回攻略する |
| 万魔殿の天獄を完全制覇せし者：ランク3 | 万魔殿パンデモニウム零式：天獄編を計10回攻略する |
| アルカディアのライトヘビー級を完全制覇せし者：ランク1 | 至天の座アルカディア零式：ライトヘビー級を攻略する |
| アルカディアのライトヘビー級を完全制覇せし者：ランク2 | 至天の座アルカディア零式：ライトヘビー級を計5回攻略する |
| アルカディアのライトヘビー級を完全制覇せし者：ランク3 | 至天の座アルカディア零式：ライトヘビー級を計10回攻略する |
| アルカディアのクルーザー級を完全制覇せし者：ランク1 | 至天の座アルカディア零式：クルーザー級を攻略する |
| アルカディアのクルーザー級を完全制覇せし者：ランク2 | 至天の座アルカディア零式：クルーザー級を計5回攻略する |
| アルカディアのクルーザー級を完全制覇せし者：ランク3 | 至天の座アルカディア零式：クルーザー級を計10回攻略する |
| アルカディアのヘビー級を完全制覇せし者：ランク1 | 至天の座アルカディア零式：ヘビー級を攻略する |
| アルカディアのヘビー級を完全制覇せし者：ランク2 | 至天の座アルカディア零式：ヘビー級を計5回攻略する |
| アルカディアのヘビー級を完全制覇せし者：ランク3 | 至天の座アルカディア零式：ヘビー級を計10回攻略する |

### 特殊フィールド探索
| 正式名 | 達成要件 |
|---|---|
| バルデシオンアーセナルの覇者：ランク1 | バルデシオンアーセナルを初めて攻略する |
| ボズヤの彗星 | 堅守彗星章、勇猛彗星章、救命彗星章を、各10個入手する |
| グンヒルド・ディルーブラムを完全制覇せし者：ランク1 | グンヒルド・ディルーブラム零式を攻略する |
| 力の塔を制覇せし者：ランク1 | 蜃気楼の島 クレセントアイルにて、フォークタワー：力の塔を初めて攻略する |

### ダンジョン
| 正式名 | 達成要件 |
|---|---|
| 語り継がれし冒険譚：ランク3 | ダンジョン、討伐・討滅戦を計10,000回攻略する |
| 孤独なる挑戦者：ランク3 | 死者の宮殿にソロでB1から突入しB200まで攻略する |
| 埋もれた財宝：ランク7 | 埋もれた財宝を30,000個発見した |
| ここ掘れワンワン：ランク2 | 埋もれた財宝を、魔土器：財宝感知もしくは魔科学器：財宝感知を使わずに100個発見した |
| 孤高なる挑戦者：ランク2 | アメノミハシラにソロで1層から突入し100層まで攻略する |
| 崇高なる挑戦者：ランク2 | オルト・エウレカにソロでB1から突入しB100まで攻略する |
| 至高なる挑戦者：ランク2 | ピルグリム・トラバースにソロで第1巡礼路から突入し第100巡礼路まで攻略する |
| 死せる巡礼路の果てへ | 詩想エミネントグリーフ討滅戦を供物を最大限捧げた状態で攻略する |
| 異聞シラディハ水道を完全制覇せし者 | 異聞シラディハ水道 零式（アナザーダンジョン）を攻略する |
| 異聞六根山を完全制覇せし者 | 異聞六根山 零式（アナザーダンジョン）を攻略する |
| 異聞アロアロ島を完全制覇せし者 | 異聞アロアロ島 零式（アナザーダンジョン）を攻略する |
| 異聞奇譚の勇傑 | アチーブメント「異聞シラディハ水道を完全制覇せし者」「異聞六根山を完全制覇せし者」「異聞アロアロ島を完全制覇せし者」をすべて達成する |

### バトル（全般）
| 正式名 | 達成要件 |
|---|---|
| 豪傑の青魔道士 | アチーブメント「大迷宮を極めし青魔道士」と「機工城を極めし青魔道士」を達成する |
| 機工城を極めし青魔道士 | アチーブメント「起動せし機工城を制覇せし青魔道士」「律動せし機工城を制覇せし青魔道士」「天動せし機工城を制覇せし青魔道士」をすべて達成する |
| 大迷宮を極めし青魔道士 | アチーブメント「始まりの大迷宮を制覇せし青魔道士」「第二の大迷宮を制覇せし青魔道士」「終わりの大迷宮を制覇せし青魔道士」をすべて達成する |

## 注意

- Lodestone検索は「先頭ヒット」を採用します（同名が複数いる場合、意図と違うキャラに当たる可能性があります）
- HTML構造（class名など）が変わるとパースが壊れます（その場合はバージョン更新で追随します）
- アチーブメントの達成要件は Lodestone から引用しています