feat: add lodestone endpoints (#1)

* feat: add new columns to registry and enhance character retrieval tests

* fix: change npm to pnpm

* fix: vitest install node via pnpm

* fix: pnpm version mismatch

* deps: add @vitest/coverage-v8 for ci-vitest

* feat: add remaining selectors

* feat: ensure ESM-only and web-worker compatibility

* feat: add regex query parameters

* docs: add jsdocs for public facing endpoints

* chore: run linter

* chore: refactor examples

* chore: refactor

* chore: run linter

* chore: major refactor

* feat: add remaining endpoint tests

Author: miichom

.github/workflows/ci-vitest.yml

@@ -12,15 +12,18 @@ jobs:
         node-version: [20.x, 22.x, 24.x]
     steps:
       - uses: actions/checkout@v5
-      - name: Install node ${{ matrix.node-version }}
-        uses: actions/setup-node@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          run_install: false
+      - uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
+          cache: pnpm
       - name: Install dependencies
-        run: npm ci
+        run: pnpm install --frozen-lockfile
       - name: Run tests
-        run: npx vitest --coverage.enabled true
-      - name: "Report Coverage"
+        run: pnpm vitest --coverage.enabled true
+      - name: Report Coverage
         if: always()
         uses: davelosert/vitest-coverage-report-action@v2
         with:

.github/workflows/npm-publish.yml

@@ -10,13 +10,17 @@ jobs:
       id-token: write
     steps:
       - uses: actions/checkout@v5
-      # Setup .npmrc file to publish to npm
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9
+          run_install: false
       - uses: actions/setup-node@v4
         with:
           node-version: "20.x"
           registry-url: "https://registry.npmjs.org"
-      - run: npm ci
-      - run: npm run build
-      - run: npm publish --provenance --access public
+          cache: "pnpm"
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm build
+      - run: pnpm publish --provenance --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.prettierrc

@@ -1,6 +1,5 @@
 {
   "$schema": "https://json.schemastore.org/prettierrc",
-  "plugins": ["@trivago/prettier-plugin-sort-imports"],
   "printWidth": 100,
   "tabWidth": 2,
   "useTabs": false,
@@ -11,9 +10,5 @@
   "trailingComma": "es5",
   "bracketSpacing": true,
   "arrowParens": "always",
-  "endOfLine": "lf",
-  "importOrder": ["<BUILTIN_MODULES>", "<THIRD_PARTY_MODULES>", "^[./]"],
-  "importOrderSeparation": false,
-  "importOrderCaseInsensitive": true,
-  "importOrderSortSpecifiers": true
+  "endOfLine": "lf"
 }

README.md

@@ -1,5 +1,8 @@
 # @miichom/lodestone
 
+[![npm](https://img.shields.io/npm/v/@miichom/lodestone.svg)](https://www.npmjs.com/package/@miichom/lodestone)
+![node](https://img.shields.io/node/v/@miichom/lodestone)
+
 A **minimal, fully typed [Lodestone](https://na.finalfantasyxiv.com/lodestone/) client** for _[Final Fantasy XIV](https://www.finalfantasyxiv.com/)_, providing access to **all endpoints exposed by the Lodestone** through a consistent, schema-driven API.
 
 Designed for **server-side and worker runtimes**: [Node.js 20+](https://nodejs.org/), [Bun](https://bun.sh/), [Cloudflare Workers](https://developers.cloudflare.com/workers/), and [Web Workers](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
@@ -26,17 +29,13 @@ Most Lodestone scrapers rely on DOM emulation (e.g. [JSDOM](https://github.com/j
 npm install @miichom/lodestone
 ```
 
-## Usage
+## Example usage
 
 ```ts
 import Lodestone from "@miichom/lodestone";
 
-const ls = new Lodestone({ locale: "na" });
-```
-
-### Example: characters
+const ls = new Lodestone();
 
-```ts
 // fetch a character
 const character = await ls.character.get(12345678);
 
@@ -54,6 +53,71 @@ const results = await ls.character.find({
 
 > Additional Lodestone endpoints follow the same API pattern and are exposed through their respective namespaces.
 
+## Options
+
+The `Lodestone` constructor accepts a small set of configuration options.  
+These apply globally to all endpoints (`character`, `cwls`, `freecompany`, `linkshell`, `pvpteam`).
+
+```ts
+const ls = new Lodestone({
+  locale: "eu",
+  headers: {
+    "user-agent": "my-xiv-tool/1.0",
+  },
+});
+```
+
+### `locale?: "de" | "eu" | "fr" | "jp" | "na"`
+
+Selects which Lodestone region to target. Defaults to **`"na"`**.
+
+Each locale maps to its own Lodestone instance:
+
+- `na` → https://na.finalfantasyxiv.com/lodestone
+- `eu` → https://eu.finalfantasyxiv.com/lodestone
+- `jp` → https://jp.finalfantasyxiv.com/lodestone
+- `fr` → https://fr.finalfantasyxiv.com/lodestone
+- `de` → https://de.finalfantasyxiv.com/lodestone
+
+All requests made through the client automatically use the selected locale.
+
+### `headers?: Record<string, string>`
+
+Optional request headers applied to every Lodestone request.
+
+- Header keys are normalized to lowercase.
+- A default User‑Agent is always prepended:
+
+```
+curl/0.1.0 (+https://github.com/miichom/lodestone)
+```
+
+If you provide your own `user-agent`, it is appended:
+
+```ts
+headers: {
+  "user-agent": "my-app/1.0",
+}
+// → curl/0.1.0 (+https://github.com/miichom/lodestone) my-app/1.0
+```
+
+For more information on the `User-Agent` header, please see https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/User-Agent.
+
+> While optional, providing a custom User‑Agent is recommended for any automated or high‑volume usage.
+
+### Column options (for `get` only)
+
+Some endpoints (notably **characters**) expose additional “column” pages on Lodestone.  
+You can request them via the `columns` option:
+
+```ts
+const profile = await ls.character.get(12345678, {
+  columns: ["mount", "minion"],
+});
+```
+
+Columns are fetched lazily and merged into the returned object.
+
 ## Attribution
 
 _Final Fantasy XIV_ and all related assets, including data accessed through the [Lodestone](https://na.finalfantasyxiv.com/lodestone/), are the intellectual property of &copy; [SQUARE ENIX CO., LTD.](https://www.square-enix.com/) All rights reserved.

eslint.config.ts

@@ -1,22 +1,26 @@
 import js from "@eslint/js";
-import prettier from "eslint-config-prettier";
 import { defineConfig } from "eslint/config";
+import prettier from "eslint-config-prettier";
+import sort from "eslint-plugin-sort";
+import unicorn from "eslint-plugin-unicorn";
 import globals from "globals";
 import ts from "typescript-eslint";
 
 export default defineConfig([
   js.configs.recommended,
   ...ts.configs.recommended,
   prettier,
+  unicorn.configs.recommended,
+  sort.configs["flat/recommended"],
   { languageOptions: { globals: { ...globals.browser, ...globals.node } } },
   {
     rules: {
-      "no-console": "warn",
+      "@typescript-eslint/consistent-type-imports": "error",
       "@typescript-eslint/no-unused-vars": [
         "warn",
         { argsIgnorePattern: "^_", varsIgnorePattern: "^_" },
       ],
-      "@typescript-eslint/consistent-type-imports": "error",
+      "no-console": "warn",
     },
   },
 ]);

package.json

@@ -23,25 +23,27 @@
   "license": "MIT",
   "author": "miichom <hello@cammy.xyz> (https://cammy.xyz/)",
   "type": "module",
-  "main": "dist/index.mjs",
+  "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
     "test": "vitest",
     "build": "tsup",
     "format": "prettier --write .",
-    "lint": "eslint src --ext .ts",
+    "lint": "eslint --ext .ts",
     "prepublishOnly": "pnpm run build"
   },
   "dependencies": {
     "linkedom": "^0.18.12"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
-    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
     "@tsconfig/node20": "^20.1.8",
     "@types/node": "^25.0.9",
+    "@vitest/coverage-v8": "^4.0.18",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-sort": "^4.0.0",
+    "eslint-plugin-unicorn": "^62.0.0",
     "globals": "^17.0.0",
     "jiti": "^2.6.1",
     "prettier": "^3.8.0",