@piyoraik/ffxiv-lodestone-character-lookup 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -6
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,15 @@
|
|
|
1
1
|
# @piyoraik/ffxiv-lodestone-character-lookup
|
|
2
2
|
|
|
3
|
-
FFXIV の Lodestone
|
|
3
|
+
FFXIV の Lodestone を使って、以下を行うための共通ライブラリです。
|
|
4
|
+
|
|
5
|
+
- `募集者: キャラクター名 @ サーバー名` をパースして検索パラメータを作る
|
|
6
|
+
- キャラクター検索の先頭ヒットから「キャラクターURL（/lodestone/character/.../）」を取得する
|
|
7
|
+
- キャラクターの「アチーブメント（カテゴリ4）」ページから、高難度（絶/零式）の達成状況を判定する
|
|
8
|
+
|
|
9
|
+
## 動作環境
|
|
10
|
+
|
|
11
|
+
- Node.js: `>= 22`（22/24想定）
|
|
12
|
+
- モジュール形式: CommonJS（TypeScript からは通常の `import { ... } from ...` で利用できます）
|
|
4
13
|
|
|
5
14
|
## インストール
|
|
6
15
|
|
|
@@ -8,7 +17,7 @@ FFXIV の Lodestone（キャラクター検索→キャラクターURL取得・
|
|
|
8
17
|
yarn add @piyoraik/ffxiv-lodestone-character-lookup
|
|
9
18
|
```
|
|
10
19
|
|
|
11
|
-
##
|
|
20
|
+
## 最短の使い方（募集者 → Lodestone URL → クリア判定）
|
|
12
21
|
|
|
13
22
|
```ts
|
|
14
23
|
import {
|
|
@@ -20,17 +29,90 @@ import {
|
|
|
20
29
|
parseUltimateClearsFromAchievementHtml
|
|
21
30
|
} from "@piyoraik/ffxiv-lodestone-character-lookup";
|
|
22
31
|
|
|
23
|
-
|
|
24
|
-
|
|
32
|
+
// 例: xivpf などの「募集者」表示に合わせた形式
|
|
33
|
+
const creator = parseCreator("Hoge Fuga @ World");
|
|
34
|
+
if (!creator) throw new Error("募集者の形式が不正です");
|
|
25
35
|
|
|
36
|
+
// 1) Lodestoneの検索URLを作る
|
|
26
37
|
const searchUrl = buildLodestoneSearchUrl(creator);
|
|
38
|
+
|
|
39
|
+
// 2) 検索の先頭ヒットからキャラクターURLを取る
|
|
27
40
|
const characterUrl = await fetchTopCharacterUrl(searchUrl);
|
|
28
|
-
if (!characterUrl) throw new Error("
|
|
41
|
+
if (!characterUrl) throw new Error("キャラクターが見つかりませんでした");
|
|
29
42
|
|
|
43
|
+
// 3) アチーブメントページ（カテゴリ4）のURLを作る
|
|
30
44
|
const achievementUrl = buildAchievementCategoryUrl(characterUrl);
|
|
31
|
-
if (!achievementUrl) throw new Error("
|
|
45
|
+
if (!achievementUrl) throw new Error("アチーブURLの生成に失敗しました");
|
|
32
46
|
|
|
47
|
+
// 4) HTMLを取得して達成状況を判定
|
|
33
48
|
const html = await fetchAchievementCategoryHtml(achievementUrl);
|
|
34
49
|
const result = parseUltimateClearsFromAchievementHtml(html);
|
|
35
50
|
console.log(result);
|
|
36
51
|
```
|
|
52
|
+
|
|
53
|
+
## 公開API（関数の挙動）
|
|
54
|
+
|
|
55
|
+
### `parseCreator(creator: string): { name: string; world: string } | undefined`
|
|
56
|
+
|
|
57
|
+
`募集者: キャラクター名 @ サーバー名` 形式の文字列から、`name` と `world` を抽出します。
|
|
58
|
+
|
|
59
|
+
- 入力例: `"Hoge Fuga @ World"`
|
|
60
|
+
- 出力例: `{ name: "Hoge Fuga", world: "World" }`
|
|
61
|
+
- 形式が不正な場合は `undefined` を返します（`@` がない、名前/ワールドが空、など）
|
|
62
|
+
|
|
63
|
+
### `buildLodestoneSearchUrl(info: { name: string; world: string }): string`
|
|
64
|
+
|
|
65
|
+
Lodestone のキャラクター検索URLを生成します。
|
|
66
|
+
|
|
67
|
+
- `q`（キャラクター名）と `worldname`（サーバー名）を指定し、その他は Lodestone のフォーム送信に近い値を付与します
|
|
68
|
+
- 返り値はURL文字列です（`https://jp.finalfantasyxiv.com/lodestone/character/?...`）
|
|
69
|
+
|
|
70
|
+
### `fetchTopCharacterUrl(searchUrl: string): Promise<string | undefined>`
|
|
71
|
+
|
|
72
|
+
`buildLodestoneSearchUrl` で作ったURLにアクセスし、検索結果の先頭に表示されるキャラクターURLを返します。
|
|
73
|
+
|
|
74
|
+
- 返り値例: `https://jp.finalfantasyxiv.com/lodestone/character/1234567/`
|
|
75
|
+
- 先頭ヒットが見つからない場合は `undefined`
|
|
76
|
+
- 取得は `axios` で行い、`timeout: 30_000` を設定しています
|
|
77
|
+
|
|
78
|
+
内部では、検索結果HTMLから `a.entry__link` の先頭を見ています。
|
|
79
|
+
|
|
80
|
+
### `buildAchievementCategoryUrl(characterUrl: string): string | undefined`
|
|
81
|
+
|
|
82
|
+
キャラクターURL（`.../lodestone/character/<id>/`）から、アチーブページ（カテゴリ4）のURLを生成します。
|
|
83
|
+
|
|
84
|
+
- 生成例: `https://jp.finalfantasyxiv.com/lodestone/character/1234567/achievement/category/4/#anchor_achievement`
|
|
85
|
+
- `characterUrl` からIDが抽出できない場合は `undefined`
|
|
86
|
+
|
|
87
|
+
※ 互換用に `buildHighEndAchievementCategoryUrl` も同様のURLを返します。
|
|
88
|
+
|
|
89
|
+
### `fetchAchievementCategoryHtml(url: string): Promise<string>`
|
|
90
|
+
|
|
91
|
+
アチーブメント一覧ページ（カテゴリ4）のHTMLを取得します。
|
|
92
|
+
|
|
93
|
+
- 取得は `axios` で行い、`timeout: 30_000` を設定しています
|
|
94
|
+
|
|
95
|
+
### `parseUltimateClearsFromAchievementHtml(html: string): { status: "ok" | "private_or_unavailable"; clears: string[] }`
|
|
96
|
+
|
|
97
|
+
アチーブメント一覧HTMLから、定義済みの高難度（絶/零式）アチーブの「達成済み」を抽出します。
|
|
98
|
+
|
|
99
|
+
- 判定: 対象アチーブの項目に日付（`time.entry__activity__time`）が存在するか
|
|
100
|
+
- `clears` は「正式名」の配列です（例: `"絶オメガ検証戦を完遂せし者"`）
|
|
101
|
+
- `status` は次の意味です
|
|
102
|
+
- `"ok"`: 対象アチーブの項目がページ内に存在した
|
|
103
|
+
- `"private_or_unavailable"`: 対象項目が1つも見つからない（非公開などで一覧自体が出ていないケースを想定）
|
|
104
|
+
|
|
105
|
+
※ 互換用に `parseHighEndClearsFromAchievementHtml` も同じ結果を返します。
|
|
106
|
+
|
|
107
|
+
### `getHighEndAchievements() / getHighEndAchievementShortMap() / getHighEndAchievementGroupMap()`
|
|
108
|
+
|
|
109
|
+
ライブラリ同梱の高難度アチーブ定義（絶/零式）を返します。
|
|
110
|
+
|
|
111
|
+
- `getHighEndAchievements()` は `{ name, short, group }[]` を返します
|
|
112
|
+
- `getHighEndAchievementShortMap()` は `正式名 -> 略称` の `Map` を返します
|
|
113
|
+
- `getHighEndAchievementGroupMap()` は `正式名 -> "ultimate" | "savage"` の `Map` を返します
|
|
114
|
+
|
|
115
|
+
## 注意
|
|
116
|
+
|
|
117
|
+
- Lodestone検索は「先頭ヒット」を採用します（同名が複数いる場合、意図と違うキャラに当たる可能性があります）
|
|
118
|
+
- HTML構造（class名など）が変わるとパースが壊れます（その場合はバージョン更新で追随します）
|
package/package.json
CHANGED