@timmsy/riftjs 1.5.0 → 2.0.2

package/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish package
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://registry.npmjs.org
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests
+        run: npm test
+
+      - name: Validate tag matches package version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION="$(node -p "require('./package.json').version")"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "Tag version v$TAG_VERSION does not match package.json version $PKG_VERSION"
+            exit 1
+          fi
+
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish to GitHub Packages
+        run: |
+          echo "@timmsy:registry=https://npm.pkg.github.com" >> "$NPM_CONFIG_USERCONFIG"
+          echo "//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}" >> "$NPM_CONFIG_USERCONFIG"
+          npm publish --registry=https://npm.pkg.github.com
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 James Timms
+Copyright (c) 2026 James Timms
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -20,7 +20,7 @@ RiftJS simplifies interaction with the Riot Games API and DataDragon static data
 
 Install RiftJS via npm:
 
-```
+```bash
 npm install @timmsy/riftjs
 ```
 
@@ -33,18 +33,23 @@ You’ll also need a Riot Games API key from [developer.riotgames.com](https://d
 
 2. **Configure Environment**:
    Create a `.env` file in your project root with your API key and region:
-   ```
+
+   ```env
    RIOT_API_KEY=RGAPI-your-api-key-here
    REGION=EUW1
+   TEST_RIOT_ID=YourRiotName
+   TEST_TAG_LINE=EUW
    ```
+
    - Replace `RGAPI-your-api-key-here` with your API key.
    - Use a short region code (e.g., `EUW1`, `NA1`). See [Region Mapping](#region-mapping) for details.
+   - `TEST_RIOT_ID` and `TEST_TAG_LINE` are used by the endpoint test script.
 
 ## Usage
 
 Here’s a basic example to get started:
 
-```
+```js
 const { RiotAPI, DataDragon } = require('@timmsy/riftjs');
 
 // Initialize RiotAPI
@@ -92,22 +97,45 @@ fetchStaticData();
 ## API Reference
 
 ### RiotAPI
+
 - `getAccountByRiotId(riotId, [tagLine], [region])`: Fetch account by Riot ID (e.g., `Timmsy#BRUV`).
 - `getSummonerByPuuid(puuid, [region])`: Get summoner data by PUUID.
 - `getMatchlistByPuuid(puuid, [options], [region])`: Get match history (options: `{ start, count }`).
-- `getMatchById(matchId, [region])`: Get match details.
+- `getMatchById(matchId, [region])`: Get full match payload (`metadata` + `info`) by match ID.
+- `getMatchTimelineById(matchId, [region])`: Get timeline payload by match ID.
+- `getMatchlistByPuuidAll(puuid, [options], [region], [pacing])`: Fetch all match IDs in pages of 100.
+- `getMatchesWithDetailsByPuuid(puuid, [options], [region], [pacing])`: Fetch all match IDs and their match payloads.
+
+`options` supports Riot Match-V5 query params:
+- `startTime` (epoch seconds)
+- `endTime` (epoch seconds)
+- `queue` (int)
+- `type` (string)
+- `start` (int, default `0`)
+- `count` (int, `0-100`, single-page method only)
+
+`pacing` helps respect rate limits on multi-request methods:
+- `getMatchlistByPuuidAll`: `{ delayMs, maxMatches }`
+- `getMatchesWithDetailsByPuuid`: `{ pageDelayMs, detailDelayMs, maxMatches }`
 
 ### DataDragon
+
 - `getChampions()`: Fetch all champion data.
 - `getItems()`: Fetch all item data.
+- `new DataDragon()` resolves the latest Data Dragon patch automatically.
+- `new DataDragon('x.y.z')` pins requests to an explicit patch version.
 
 ## Region Mapping
 
 RiftJS uses a region map to route requests correctly:
+
 - **Platform Routing** (e.g., Summoner V4):
+
   - `EUW1` → `euw1.api.riotgames.com`
   - `NA1` → `na1.api.riotgames.com`
+
 - **Shard Routing** (e.g., Account V1, Match V5):
+
   - `EUW1` → `europe.api.riotgames.com`
   - `NA1` → `americas.api.riotgames.com`
 
@@ -129,17 +157,29 @@ Supported regions: `BR1`, `EUN1`, `EUW1`, `JP1`, `KR`, `LA1`, `LA2`, `NA1`, `OC1
 ## Development
 
 To contribute or run locally:
+
 1. Clone the repo:
-   ```
+
+   ```bash
    git clone https://github.com/timmsy1998/RiftJS.git
    cd RiftJS
    ```
+
 2. Install dependencies:
-   ```
+
+   ```bash
    npm install
    ```
+
 3. Create a `.env` file (see [Setup](#setup)).
-4. Test with `node test.js` (requires a valid API key).
+4. Run endpoint checks:
+
+   ```bash
+   npm test
+   ```
+
+   - Riot API calls run when `TEST_RIOT_ID` is set.
+   - Data Dragon calls always run.
 
 ## License
 
@@ -149,4 +189,4 @@ MIT License © 2025 James Timms. See [LICENSE](LICENSE) for details.
 
 - **npm Registry**: [https://www.npmjs.com/package/@timmsy/riftjs](https://www.npmjs.com/package/@timmsy/riftjs)
 - **GitHub Repository**: [https://github.com/timmsy1998/RiftJS](https://github.com/timmsy1998/RiftJS)
-- **Riot Developer Portal**: [https://developer.riotgames.com/](https://developer.riotgames.com/)
+- **Riot Developer Portal**: [https://developer.riotgames.com/](https://developer.riotgames.com/)

package/endpoints/datadragon.js

@@ -1,29 +1,40 @@
 const axios = require('axios');
 
-module.exports = (baseURL) => ({
-    /**
-     * Get all champion data.
-     * @returns {Promise<object>} Champion data.
-     */
-    async getChampions() {
-        try {
-            const response = await axios.get(`${baseURL}/champion.json`);
-            return response.data;
-        } catch (error) {
-            throw new Error(`DataDragon error: ${error.message}`);
+module.exports = (baseURLOrResolver) => {
+    const resolveBaseURL = async () => {
+        if (typeof baseURLOrResolver === 'function') {
+            return baseURLOrResolver();
         }
-    },
+        return baseURLOrResolver;
+    };
 
-    /**
-     * Get all item data.
-     * @returns {Promise<object>} Item data.
-     */
-    async getItems() {
-        try {
-            const response = await axios.get(`${baseURL}/item.json`);
-            return response.data;
-        } catch (error) {
-            throw new Error(`DataDragon error: ${error.message}`);
-        }
-    },
-});
+    return {
+        /**
+         * Fetch champion metadata for the configured Data Dragon version/locale.
+         * @returns {Promise<object>} Champion data.
+         */
+        async getChampions() {
+            try {
+                const baseURL = await resolveBaseURL();
+                const response = await axios.get(`${baseURL}/champion.json`);
+                return response.data;
+            } catch (error) {
+                throw new Error(`DataDragon error: ${error.message}`);
+            }
+        },
+
+        /**
+         * Fetch item metadata for the configured Data Dragon version/locale.
+         * @returns {Promise<object>} Item data.
+         */
+        async getItems() {
+            try {
+                const baseURL = await resolveBaseURL();
+                const response = await axios.get(`${baseURL}/item.json`);
+                return response.data;
+            } catch (error) {
+                throw new Error(`DataDragon error: ${error.message}`);
+            }
+        },
+    };
+};

package/endpoints/riot.js

@@ -1,10 +1,12 @@
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
 module.exports = (client, defaultRegion, regionMap) => ({
     /**
-     * Get account info by Riot ID (gameName and tagLine).
+     * Fetch account data by Riot ID.
      * @param {string} riotId - Riot ID (e.g., "Timmsy#BRUV" or "Timmsy", "BRUV").
      * @param {string} [tagLine] - Optional tagLine if not included in riotId.
-     * @param {string} [region] - Short region (defaults to constructor region).
-     * @returns {Promise<object>} Account data including puuid.
+     * @param {string} [region] - Region code used to resolve shard routing.
+     * @returns {Promise<object>} Account payload including `puuid`.
      */
     async getAccountByRiotId(riotId, tagLine = null, region = defaultRegion) {
         let gameName, tag;
@@ -27,10 +29,10 @@ module.exports = (client, defaultRegion, regionMap) => ({
     },
 
     /**
-     * Get summoner data by PUUID.
+     * Fetch Summoner-V4 data for a player's PUUID.
      * @param {string} puuid - Encrypted PUUID.
-     * @param {string} [region] - Short region (defaults to constructor region).
-     * @returns {Promise<object>} Summoner data.
+     * @param {string} [region] - Region code used to resolve platform routing.
+     * @returns {Promise<object>} Summoner payload.
      */
     async getSummonerByPuuid(puuid, region = defaultRegion) {
         const platform = regionMap[region].platform;
@@ -45,10 +47,10 @@ module.exports = (client, defaultRegion, regionMap) => ({
     },
 
     /**
-     * Get match history by PUUID.
-     * @param {string} puuid - Summoner's PUUID.
-     * @param {object} [options] - Query options (e.g., start, count).
-     * @param {string} [region] - Short region (defaults to constructor region).
+     * Fetch match IDs for a PUUID from Match-V5.
+     * @param {string} puuid - Player PUUID.
+     * @param {object} [options] - Query params such as `start` and `count`.
+     * @param {string} [region] - Region code used to resolve shard routing.
      * @returns {Promise<string[]>} Array of match IDs.
      */
     async getMatchlistByPuuid(puuid, options = {}, region = defaultRegion) {
@@ -65,10 +67,10 @@ module.exports = (client, defaultRegion, regionMap) => ({
     },
 
     /**
-     * Get match details by match ID.
+     * Fetch full match details by match ID.
      * @param {string} matchId - Match ID (e.g., "EUW1_1234567890").
-     * @param {string} [region] - Short region (defaults to constructor region).
-     * @returns {Promise<object>} Match data.
+     * @param {string} [region] - Region code used to resolve shard routing.
+     * @returns {Promise<object>} Match payload.
      */
     async getMatchById(matchId, region = defaultRegion) {
         const shard = regionMap[region].shard;
@@ -81,4 +83,94 @@ module.exports = (client, defaultRegion, regionMap) => ({
             throw this._handleError(error);
         }
     },
-});
+
+    /**
+     * Fetch match timeline data by match ID.
+     * @param {string} matchId - Match ID (e.g., "EUW1_1234567890").
+     * @param {string} [region] - Region code used to resolve shard routing.
+     * @returns {Promise<object>} Match timeline payload.
+     */
+    async getMatchTimelineById(matchId, region = defaultRegion) {
+        const shard = regionMap[region].shard;
+        try {
+            const response = await client.get(`/lol/match/v5/matches/${matchId}/timeline`, {
+                baseURL: `https://${shard}`,
+            });
+            return response.data;
+        } catch (error) {
+            throw this._handleError(error);
+        }
+    },
+
+    /**
+     * Fetch all match IDs for a PUUID using Riot's max page size (100).
+     * @param {string} puuid - Player PUUID.
+     * @param {object} [options] - Riot filters: startTime, endTime, queue, type, start.
+     * @param {string} [region] - Region code used to resolve shard routing.
+     * @param {object} [pacing] - Pacing controls.
+     * @param {number} [pacing.delayMs=1250] - Delay between page requests.
+     * @param {number|null} [pacing.maxMatches=null] - Optional cap on total IDs returned.
+     * @returns {Promise<string[]>} All matched IDs.
+     */
+    async getMatchlistByPuuidAll(puuid, options = {}, region = defaultRegion, pacing = {}) {
+        const baseStart = Number.isInteger(options.start) ? options.start : 0;
+        const pageDelayMs = Number.isInteger(pacing.delayMs) ? pacing.delayMs : 1250;
+        const maxMatches = Number.isInteger(pacing.maxMatches) && pacing.maxMatches >= 0 ? pacing.maxMatches : null;
+        const filters = {
+            startTime: options.startTime,
+            endTime: options.endTime,
+            queue: options.queue,
+            type: options.type,
+        };
+
+        let start = baseStart;
+        const allMatchIds = [];
+
+        while (true) {
+            const remaining = maxMatches === null ? 100 : Math.min(100, maxMatches - allMatchIds.length);
+            if (remaining <= 0) break;
+
+            const page = await this.getMatchlistByPuuid(puuid, { ...filters, start, count: remaining }, region);
+            allMatchIds.push(...page);
+
+            if (page.length < remaining) break;
+            start += page.length;
+            if (pageDelayMs > 0) await sleep(pageDelayMs);
+        }
+
+        return allMatchIds;
+    },
+
+    /**
+     * Fetch match IDs and full match payloads for each ID.
+     * @param {string} puuid - Player PUUID.
+     * @param {object} [options] - Riot filters: startTime, endTime, queue, type, start.
+     * @param {string} [region] - Region code used to resolve shard routing.
+     * @param {object} [pacing] - Pacing controls.
+     * @param {number} [pacing.pageDelayMs=1250] - Delay between matchlist page requests.
+     * @param {number} [pacing.detailDelayMs=1250] - Delay between match detail requests.
+     * @param {number|null} [pacing.maxMatches=null] - Optional cap on total matches fetched.
+     * @returns {Promise<{matchIds: string[], matches: object[]}>} IDs and full match payloads.
+     */
+    async getMatchesWithDetailsByPuuid(puuid, options = {}, region = defaultRegion, pacing = {}) {
+        const pageDelayMs = Number.isInteger(pacing.pageDelayMs) ? pacing.pageDelayMs : 1250;
+        const detailDelayMs = Number.isInteger(pacing.detailDelayMs) ? pacing.detailDelayMs : 1250;
+        const maxMatches = Number.isInteger(pacing.maxMatches) && pacing.maxMatches >= 0 ? pacing.maxMatches : null;
+        const matchIds = await this.getMatchlistByPuuidAll(
+            puuid,
+            options,
+            region,
+            { delayMs: pageDelayMs, maxMatches }
+        );
+        const matches = [];
+
+        for (let i = 0; i < matchIds.length; i += 1) {
+            matches.push(await this.getMatchById(matchIds[i], region));
+            if (detailDelayMs > 0 && i < matchIds.length - 1) {
+                await sleep(detailDelayMs);
+            }
+        }
+
+        return { matchIds, matches };
+    },
+});

package/index.js

@@ -3,9 +3,8 @@ const axios = require('axios');
 const riotEndpoints = require('./endpoints/riot');
 const dataDragonEndpoints = require('./endpoints/datadragon');
 
-// Region mapping: short region to shard
+// Maps region codes to the platform and routing shard hosts required by Riot APIs.
 const regionMap = {
-    // Platform Routing (short regions)
     BR1: { platform: 'br1.api.riotgames.com', shard: 'americas.api.riotgames.com' },
     EUN1: { platform: 'eun1.api.riotgames.com', shard: 'europe.api.riotgames.com' },
     EUW1: { platform: 'euw1.api.riotgames.com', shard: 'europe.api.riotgames.com' },
@@ -24,9 +23,6 @@ const regionMap = {
     VN2: { platform: 'vn2.api.riotgames.com', shard: 'sea.api.riotgames.com' },
 };
 
-/**
- * RiotAPI class for interacting with Riot Games API endpoints.
- */
 class RiotAPI {
     constructor() {
         this.apiKey = process.env.RIOT_API_KEY;
@@ -36,14 +32,11 @@ class RiotAPI {
         this.client = axios.create({
             headers: { 'X-Riot-Token': this.apiKey },
         });
-        // Attach RiotAPI endpoints with region map
+        // Attach endpoint methods with a shared axios client and region configuration.
         Object.assign(this, riotEndpoints(this.client, this.region, regionMap));
     }
 
-    /**
-     * Handle axios errors and provide meaningful messages.
-     * @private
-     */
+    // Normalize axios errors to stable Error messages for consumers.
     _handleError(error) {
         if (error.response) {
             const { status, data } = error.response;
@@ -55,17 +48,41 @@ class RiotAPI {
     }
 }
 
-/**
- * DataDragon class for accessing static game data.
- */
 class DataDragon {
-    constructor(version = '14.19.1', locale = 'en_US') {
+    constructor(version = null, locale = 'en_US') {
         this.version = version;
         this.locale = locale;
-        this.baseURL = `https://ddragon.leagueoflegends.com/cdn/${this.version}/data/${this.locale}`;
-        // Attach DataDragon endpoints
-        Object.assign(this, dataDragonEndpoints(this.baseURL));
+        this.baseURL = null;
+        this._baseURLPromise = null;
+
+        // Attach static-data endpoint methods that resolve the latest version when needed.
+        Object.assign(this, dataDragonEndpoints(() => this._resolveBaseURL()));
+    }
+
+    async _resolveBaseURL() {
+        if (this.baseURL) return this.baseURL;
+        if (this._baseURLPromise) return this._baseURLPromise;
+
+        this._baseURLPromise = (async () => {
+            if (!this.version) {
+                const response = await axios.get('https://ddragon.leagueoflegends.com/api/versions.json');
+                const latestVersion = Array.isArray(response.data) ? response.data[0] : null;
+                if (!latestVersion) {
+                    throw new Error('Could not resolve latest Data Dragon version');
+                }
+                this.version = latestVersion;
+            }
+
+            this.baseURL = `https://ddragon.leagueoflegends.com/cdn/${this.version}/data/${this.locale}`;
+            return this.baseURL;
+        })();
+
+        try {
+            return await this._baseURLPromise;
+        } finally {
+            this._baseURLPromise = null;
+        }
     }
 }
 
-module.exports = { RiotAPI, DataDragon };
+module.exports = { RiotAPI, DataDragon };

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@timmsy/riftjs",
-  "version": "1.5.0",
+  "version": "2.0.2",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "npm run test:endpoints",
+    "test:endpoints": "node test-endpoints.js"
   },
   "dependencies": {
     "axios": "^1.7.7",
@@ -28,4 +29,4 @@
     "type": "git",
     "url": "git+https://github.com/timmsy1998/RiftJS.git"
   }
-}
+}

package/test-endpoints.js

@@ -0,0 +1,65 @@
+require('dotenv').config();
+const { RiotAPI, DataDragon } = require('./index');
+
+async function run() {
+    const riotId = process.env.TEST_RIOT_ID;
+    const tagLine = process.env.TEST_TAG_LINE;
+    const dd = new DataDragon();
+
+    if (process.env.RIOT_API_KEY && riotId) {
+        const riot = new RiotAPI();
+        const account = await riot.getAccountByRiotId(riotId, tagLine);
+        console.log('[PASS] getAccountByRiotId:', account.puuid);
+
+        const summoner = await riot.getSummonerByPuuid(account.puuid);
+        console.log('[PASS] getSummonerByPuuid:', {
+            puuid: summoner.puuid,
+            summonerLevel: summoner.summonerLevel,
+        });
+
+        const matchIds = await riot.getMatchlistByPuuid(account.puuid, { start: 0, count: 3 });
+        console.log('[PASS] getMatchlistByPuuid:', matchIds.length, 'match ids');
+
+        if (matchIds.length > 0) {
+            const match = await riot.getMatchById(matchIds[0]);
+            console.log('[PASS] getMatchById:', match.metadata.matchId);
+
+            const timeline = await riot.getMatchTimelineById(matchIds[0]);
+            console.log('[PASS] getMatchTimelineById:', timeline.metadata.matchId);
+
+            const allMatchIds = await riot.getMatchlistByPuuidAll(
+                account.puuid,
+                { start: 0 },
+                undefined,
+                { maxMatches: 2, delayMs: 0 }
+            );
+            console.log('[PASS] getMatchlistByPuuidAll:', allMatchIds.length, 'match ids');
+
+            const withDetails = await riot.getMatchesWithDetailsByPuuid(
+                account.puuid,
+                { start: 0 },
+                undefined,
+                { maxMatches: 2, pageDelayMs: 0, detailDelayMs: 0 }
+            );
+            console.log('[PASS] getMatchesWithDetailsByPuuid:', withDetails.matches.length, 'matches');
+        } else {
+            console.log('[SKIP] Match-by-id/timeline/all/details checks: no matches returned');
+        }
+    } else if (process.env.RIOT_API_KEY) {
+        console.log('[SKIP] Riot endpoints: set TEST_RIOT_ID (and TEST_TAG_LINE if needed)');
+    } else {
+        console.log('[SKIP] Riot endpoints: set RIOT_API_KEY and TEST_RIOT_ID');
+    }
+
+    const champions = await dd.getChampions();
+    console.log('[PASS] getChampions:', Object.keys(champions.data || {}).length, 'champions');
+    console.log('[INFO] DataDragon version:', dd.version);
+
+    const items = await dd.getItems();
+    console.log('[PASS] getItems:', Object.keys(items.data || {}).length, 'items');
+}
+
+run().catch((error) => {
+    console.error('[FAIL]', error.message);
+    process.exitCode = 1;
+});