chore: add user-agent, additional sheets & improve docs (#46)

* chore(biomejs): improve config and enable for vscode

* chore(vscode): add organizeImports action to code actions on save

* chore: add std-env dependency, update types, and improve request handling

* chore: refine request parameters handling and cleanup undefined values

* chore: add actions and emotes sheets to XIVAPI and update tests for achievements

* chore: rename verify-publish job to publish in CI workflow

* chore: update README for clarity, improve usage examples, and enhance documentation

* chore: improve example section formatting in README

* chore: add output example for search sheets in README

* chore: add Code of Conduct and contributing guidelines to improve community standards and documentation

Author: miichom

.github/workflows/ci-verify.yml

@@ -27,7 +27,7 @@ jobs:
         uses: davelosert/vitest-coverage-report-action@v2
         with:
           threshold-icons: "{0: '🔴', 80: '🟠', 90: '🟢'}"
-  verify-publish:
+  publish:
     runs-on: ubuntu-latest
     needs: test
     permissions:

.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+  "editor.codeActionsOnSave": {
+    "source.action.useSortedPackageJson.biome": "explicit",
+    "source.organizeImports.biome": "explicit",
+    "source.fixAll.biome": "explicit"
+  }
+}

CODE_OF_CONDUCT.md

@@ -0,0 +1,34 @@
+# Contributor Covenant Code of Conduct
+
+Our goal is to foster a respectful, welcoming, and collaborative space across every project in this monorepo. Everyone involved shares the responsibility of keeping participation positive and free from harassment.
+
+## Our Standards
+
+We encourage behaviors that help build a healthy and productive community:
+
+- Using welcoming and inclusive language
+- Respecting differing viewpoints and experiences
+- Offering and receiving constructive feedback gracefully
+- Showing empathy and kindness toward others
+- Collaborating in ways that support the long‑term health of the project
+
+## Unacceptable Behavior
+
+The following behaviors are not acceptable in any project within this monorepo:
+
+- Harassment, discrimination, or exclusion based on personal characteristics
+- Personal attacks, insults, or trolling
+- Public or private harassment of any kind
+- Deliberate intimidation or threats
+- Disruptive behavior that interferes with constructive collaboration
+
+## Enforcement
+
+If you observe or experience behavior that violates this Code of Conduct, please contact the maintainers through the repository’s issue tracker or by opening a private security advisory.
+
+All reports will be handled confidentially.  
+Maintainers are responsible for reviewing incidents, determining appropriate actions, and enforcing this Code of Conduct fairly and consistently across the monorepo.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/) version 2.1.

CONTRIBUTING

@@ -0,0 +1,44 @@
+# Contributing to xivapi-js
+
+Thanks for your interest in contributing! We welcome contributions of all kinds, including bug fixes, new features, documentation improvements, and — eventually — translations.
+
+## How to Contribute
+
+1. **Fork** the repository.
+2. **Create a feature branch**, for example:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+3. Make your changes, following the style and structure of the project or package you are modifying.
+4. Add tests or verify that your changes work as expected.
+5. Commit your work using clear, descriptive commit messages.
+6. Push your branch:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+7. Open a Pull Request.
+   In your PR description, include:
+
+- What you changed
+- Why you changed it
+- Any related issues or context
+
+## Reporting Issues
+
+Before opening a new issue:
+
+- Check existing issues to avoid duplicates.
+- Provide a clear description of the problem or feature request.
+- For bugs, include steps to reproduce, expected vs. actual behavior, and any relevant logs or screenshots.
+- For feature requests, explain the problem the feature solves and any alternatives you’ve considered.
+
+## Code Style & Tests
+
+- Follow the existing coding conventions (formatting, naming, structure).
+- Update or add tests when appropriate.
+- Ensure all tests pass before submitting your PR (if a test suite is available).
+- Keep changes focused—smaller, well‑scoped PRs are easier to review and merge.
+
+## Community Code of Conduct
+
+By contributing to this monorepo, you agree to follow our [Code of Conduct](./CODE_OF_CONDUCT.md).

README.md

@@ -13,12 +13,12 @@ If you need help or run into any issues, please [open an issue](https://github.c
 ## Installation
 
 ```bash
-npm install @xivapi/js@latest    # or use yarn, pnpm, or bun
+npm install @xivapi/js
 ```
 
-## Usage Examples
+Supports Node, Bun, Deno, and modern bundlers.
 
-#### 1. Importing and Initialization
+## Quick Start
 
 ```js
 import xivapi from "@xivapi/js";
@@ -34,29 +34,24 @@ const xivCustom = new xivapi({
 });
 ```
 
-#### 2. Get an Item
+## Examples
+
+#### Get an Item
 
 ```js
-// Fetch the Gil item (item ID 1)
 const item = await xiv.items.get(1);
-
-console.log(item.fields.Name); // "Gil" (or equivalent in your language)
+console.log(item.fields.Name); // "Gil"
 ```
 
-#### 3. Search Example
+#### Search sheets
 
 ```js
-// Find all items named "gil"
-const params = {
-  query: 'Name~"gil"',
-  sheets: "Item",
-};
-
+const params = { query: 'Name~"gil"', sheets: "Item" };
 const { results } = await xiv.search(params);
 console.log(results[0]);
 
 /*
-Output example:
+Output:
 {
   "score": 1,
   "sheet": "Item",
@@ -74,17 +69,17 @@ Output example:
 */
 ```
 
-#### 4. Using Raw XIVAPI v2 Endpoints
+#### Using raw XIVAPI v2 endpoints
 
 ```js
-// Fetch a raw asset file (e.g. icon image)
+// Fetch an asset (e.g., icon)
 const assets = await xiv.data.assets();
 const asset = await assets.get({
   path: "ui/icon/051000/051474_hr1.tex",
   format: "png", // jpg or webp also supported
 });
 
-// List all quests
+// List all rows from the "Quest" sheet
 const sheets = await xiv.data.sheets();
 const quests = await sheets.list("Quest");
 console.log(quests);
@@ -96,17 +91,8 @@ console.log(versions[0]); // e.g. "7.0"
 
 ## Contributing
 
-We welcome all contributions! Whether you'd like to report a bug, suggest a feature, improve the documentation, or submit a pull request, your help is appreciated.
-
-To get started, clone the repository with: `git clone https://github.com/xivapi/xivapi-js.git`
-
-Before opening a pull request, please:
-
-- Make sure your code passes linting and all current tests (`npm run lint && npm test`).
-- Clearly explain your changes and reference any relevant issues in your PR description.
-
-If you have questions, suggestions, or want to discuss changes before contributing, feel free to open an issue!
+Contributions, bug reports, and feature requests are welcome! See [`CONTRIBUTING`](CONTRIBUTING) for guidelines on how to get started.
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License. See [`LICENSE`](LICENSE) for details.

biome.json

@@ -47,6 +47,12 @@
   },
   "assist": {
     "enabled": true,
-    "actions": { "source": { "organizeImports": "on" } }
+    "actions": {
+      "source": {
+        "preset": "recommended",
+        "organizeImports": "on",
+        "useSortedPackageJson": "on"
+      }
+    }
   }
 }

package-lock.json

@@ -2,24 +2,37 @@
   "name": "@xivapi/js",
   "version": "1.0.5",
   "description": "A Node.JS wrapper for xivapi.com",
+  "keywords": ["xivapi", "ffxiv"],
+  "homepage": "https://github.com/xivapi/xivapi-js",
+  "bugs": {
+    "url": "https://github.com/xivapi/xivapi-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xivapi/xivapi-js.git"
+  },
   "license": "MIT",
   "author": "Kai <mail@kai.moe> (https://kai.moe/)",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "files": ["dist"],
   "scripts": {
     "build": "tsdown",
-    "test": "vitest --coverage",
+    "format": "biome format --write",
     "lint": "biome check --write",
     "lint:check": "biome check",
-    "format": "biome format --write"
+    "test": "vitest --coverage"
+  },
+  "dependencies": {
+    "std-env": "^4.1.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.1",
     "@eslint/js": "^10.0.1",
     "@tsconfig/node22": "^22.0.5",
-    "@types/node": "^26.0.0",
+    "@types/node": "^26.0.1",
     "@vitest/coverage-v8": "^4.1.9",
     "eslint": "^10.5.0",
     "eslint-config-prettier": "^10.1.8",
@@ -32,16 +45,6 @@
     "typescript-eslint": "^8.61.1",
     "vitest": "^4.1.9"
   },
-  "homepage": "https://github.com/xivapi/xivapi-js#readme",
-  "bugs": {
-    "url": "https://github.com/xivapi/xivapi-js/issues"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/xivapi/xivapi-js.git"
-  },
-  "keywords": ["xivapi", "ffxiv"],
-  "files": ["dist"],
   "engines": {
     "node": ">=20.0.0"
   }

package.json

@@ -1,31 +1,32 @@
 import { Assets } from "./lib/assets.js";
 import { Sheet, Sheets } from "./lib/sheets.js";
 import { Versions } from "./lib/versions.js";
-import * as Models from "./models.js";
+import type * as Models from "./models.d.ts";
 import { CustomError, request } from "./utils.js";
 
 export default class XIVAPI {
-  public readonly options: XIVAPIOptions;
-
   public readonly achievements: Sheet<"Achievement">;
+  public readonly actions: Sheet<"Action">;
+  public readonly emotes: Sheet<"Emote">;
+  public readonly items: Sheet<"Item">;
   public readonly minions: Sheet<"Companion">;
   public readonly mounts: Sheet<"Mount">;
-  public readonly items: Sheet<"Item">;
+  public readonly options: XIVAPIOptions;
 
   /**
    * Raw endpoints for the API. Please consider using the typed endpoints instead.
    * @see https://v2.xivapi.com/api/docs
-   * @since 0.5.0
+   * @since 1.0.0
    */
   public readonly data = {
     /**
      * @see https://v2.xivapi.com/api/docs#tag/sheets
-     * @since 0.5.0
+     * @since 1.0.0
      */
     sheets: () => new Sheets(this.options),
     /**
      * @see https://v2.xivapi.com/api/docs#tag/versions
-     * @since 0.5.0
+     * @since 1.0.0
      */
     versions: () =>
       new Versions()
@@ -35,7 +36,7 @@ export default class XIVAPI {
         ),
     /**
      * @see https://v2.xivapi.com/api/docs#tag/assets
-     * @since 0.5.0
+     * @since 1.0.0
      */
     assets: () => new Assets(),
   };
@@ -44,7 +45,7 @@ export default class XIVAPI {
    * A wrapper for the XIVAPI v2 API.
    * @param {XIVAPIOptions} [options] The client options to fetch with.
    * @see https://v2.xivapi.com/api/docs
-   * @since 0.5.0
+   * @since 1.0.0
    */
   constructor(
     options: XIVAPIOptions = {
@@ -54,10 +55,11 @@ export default class XIVAPI {
     }
   ) {
     this.achievements = new Sheet("Achievement", options);
+    this.actions = new Sheet("Action", options);
+    this.emotes = new Sheet("Emote", options);
+    this.items = new Sheet("Item", options);
     this.minions = new Sheet("Companion", options);
     this.mounts = new Sheet("Mount", options);
-    this.items = new Sheet("Item", options);
-
     this.options = options;
   }
 
@@ -66,12 +68,13 @@ export default class XIVAPI {
    * @param {SearchParams} params Query paramters accepted by the search endpoint.
    * @returns {Promise<Models.SearchResponse>} Response structure for the search endpoint.
    * @see https://v2.xivapi.com/api/docs#tag/search/get/search
-   * @since 0.5.0
+   * @since 1.0.0
    */
   public async search(params: SearchParams): Promise<Models.SearchResponse> {
     const { data, errors } = await request({
       path: "/search",
       params: params as Record<string, unknown>,
+      options: this.options
     });
     if (errors) throw new CustomError(errors[0].message);
     return data as Models.SearchResponse;
@@ -103,4 +106,4 @@ export type SearchParams = Models.SearchQuery &
   Models.VersionQuery &
   Models.RowReaderQuery & { verbose?: boolean };
 
-export { Models, XIVAPI };
+export { type Models, XIVAPI };