Merge pull request #26 from carlomorgenstern/master

rework/enhancement

create-ilvl-filter.js

@@ -0,0 +1,33 @@
+const fetch = require('node-fetch');
+
+const itemUICategory = [
+  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20,
+  21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40,
+  41, 42, 43, 84, 87, 88, 89, 96, 97, 98, 99, 105, 106, 107,
+];
+
+// Returns a list of item IDs that, when equipped, increase the iLvl by 1
+async function createIlvlFilter(xivApiKey = undefined) {
+  const itemIds = [];
+
+  // Fetch for each category one after another to prevent rate limiting
+  // This should only by needed on startup, so a longer caching time is ok
+  for (const category of itemUICategory) {
+    const url = new URL('https://xivapi.com/search');
+    url.searchParams.set('indexes', 'item');
+    url.searchParams.set('filters', `IsIndisposable=1,ItemUICategoryTargetID=${category}`);
+    if (typeof xivApiKey === 'string' && xivApiKey !== '') url.searchParams.set('private_key', xivApiKey);
+
+    const response = await fetch(url.toString());
+    const data = await response.json();
+
+    if (data != null && Array.isArray(data.Results)) {
+      for (const item of data.Results) {
+        itemIds.push(item.ID);
+      }
+    }
+  }
+  return itemIds;
+}
+
+module.exports = createIlvlFilter

createilvlfilter.js

@@ -1,27 +0,0 @@
-const fetch = require("node-fetch");
-
-const itemUICategory = [
-  1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 84, 87, 88, 89, 96, 97, 98, 99,
-  105, 106, 107,
-];
-
-async function createilvlfilter() {
-  let results = [];
-  for (const category of itemUICategory) {
-    let url = `https://xivapi.com/search?indexes=item&filters=IsIndisposable=1,ItemUICategoryTargetID=${category}`;
-    const response = await fetch(url);
-    const data = response.json();
-    data.then((payload) => {
-      if (payload.Pagination.Results === 0) {
-        return;
-      }
-      for (const item of payload.Results) {
-        let part = item.ID
-        results.push(part);
-      }
-    });
-  }
-  return results;
-}
-
-module.exports = createilvlfilter

gh-pages.js

@@ -1,6 +1,3 @@
-const ghpages = require("gh-pages");
-ghpages.publish("docs/", (err) => {
-    if (err) {
-        console.error(err);
-    }
-});
+const ghpages = require('gh-pages');
+
+ghpages.publish('docs/', error => { if (error) console.error(error) });

index.js

@@ -1,152 +1,150 @@
-const fetch = require("node-fetch");
-const express = require('express');
-const app = express();
-const port = process.env.PORT || 5000;
-
-const { CardCreator } = require('./create-card');
-
-const creator = new CardCreator();
-
-// node cachemanager
-var cacheManager = require('cache-manager');
-// storage for the cachemanager
-var fsStore = require('cache-manager-fs-binary');
-// initialize caching on disk
-var diskCache = cacheManager.caching({
-    store: fsStore,
-    options: {
-        reviveBuffers: true,
-        binaryAsStream: false,
-        ttl: 60 * 60 * 4 /* seconds */,
-        maxsize: 1000 * 1000 * 1000 /* max size in bytes on disk */,
-        path: 'diskcache',
-        preventfill: true
-    }
-});
-
-async function getCharIdByName(world, name, retries = 1) {
-    if (retries === -1) return undefined;
-
-    const response = await fetch(`https://xivapi.com/character/search?name=${name}&server=${world}`);
-    const data = await response.json();
-
-    if (data.Results[0] === undefined)
-        return getCharIdByName(world, name, --retries);
-
-    return data.Results[0].ID;
-}
-
-app.get('/prepare/id/:charaId', async (req, res) => {
-    var cacheKey = `img:${req.params.charaId}`;
-    var ttl = 60 * 60 * 4; // 4 hours
-
-    diskCache.wrap(cacheKey,
-        // called if the cache misses in order to generate the value to cache
-        function (cb) {
-            creator.ensureInit().then(() => creator.createCard(req.params.charaId), (reason) => cb('Init failed: ' + reason, null)).then(image => cb(null, {
-                binary: {
-                    image: image,
-                }
-            })).catch((reason) => cb('createCard failed: ' + reason, null));
-        },
-        // Options, see node-cache-manager for more examples
-        { ttl: ttl },
-        function (err, result) {
-            if (err !== null) {
-                console.error(err);
-                res.status(500).send({status: "error", reason: err});
-                return;
-            }
-
-            res.status(200).send({status: "ok", url: `/characters/id/${req.params.charaId}.png`});
-        }
-    );
-})
-
-app.get('/prepare/name/:world/:charName', async (req, res) => {
-    var id = await getCharIdByName(req.params.world, req.params.charName);
-
-    if (id === undefined) {
-        res.status(404).send({status: "error", reason: "Character not found."});
-        return;
-    }
-
-    res.redirect(`/prepare/id/${id}`);
-})
-
-app.get('/characters/id/:charaId.png', async (req, res) => {
-    var cacheKey = `img:${req.params.charaId}`;
-    var ttl = 60 * 60 * 4; // 4 hours
-
-    diskCache.wrap(cacheKey,
-        // called if the cache misses in order to generate the value to cache
-        function (cb) {
-            creator.ensureInit().then(() => creator.createCard(req.params.charaId), (reason) => cb('Init failed: ' + reason, null)).then(image => cb(null, {
-                binary: {
-                    image: image,
-                }
-            })).catch((reason) => cb('createCard failed: ' + reason, null));
-        },
-        // Options, see node-cache-manager for more examples
-        { ttl: ttl },
-        function (err, result) {
-            if (err !== null) {
-                console.error(err);
-                res.status(500).send({status: "error", reason: err});
-                return;
-            }
-
-            var image = result.binary.image;
-
-            res.writeHead(200, {
-                'Content-Type': 'image/png',
-                'Content-Length': image.length,
-                'Cache-Control': 'public, max-age=14400'
-            });
-
-            res.end(image, 'binary');
-
-            var usedStreams = ['image'];
-            // you have to do the work to close the unused files
-            // to prevent file descriptors leak
-            for (var key in result.binary) {
-                if (!result.binary.hasOwnProperty(key)) continue;
-                if (usedStreams.indexOf(key) < 0
-                    && result.binary[key] instanceof Stream.Readable) {
-                    if (typeof result.binary[key].close === 'function') {
-                        result.binary[key].close(); // close the stream (fs has it)
-                    } else {
-                        result.binary[key].resume(); // resume to the end and close
-                    }
-                }
-            }
-        }
-    );
-})
-
-app.get('/characters/id/:charaId', async (req, res) => {
-    res.redirect(`/characters/id/${req.params.charaId}.png`);
-})
-
-app.get('/characters/name/:world/:charName.png', async (req, res) => {
-    var id = await getCharIdByName(req.params.world, req.params.charName);
-
-    if (id === undefined) {
-        res.status(404).send({status: "error", reason: "Character not found."});
-        return;
-    }
-
-    res.redirect(`/characters/id/${id}.png`);
-})
-
-app.get('/characters/name/:world/:charName', async (req, res) => {
-    res.redirect(`/characters/name/${req.params.world}/${req.params.charName}.png`);
-})
-
-app.get('/', async (req, res) => {
-    res.redirect('https://github.com/ArcaneDisgea/XIV-Character-Cards');
-})
-
-app.listen(port, () => {
-    console.log(`Listening at http://localhost:${port}`)
-})
+const cacheManager = require('cache-manager');
+const express = require('express');
+const fetch = require('node-fetch');
+const fsStore = require('cache-manager-fs-binary');
+const rateLimit = require("express-rate-limit");
+
+const { CardCreator } = require('./create-card');
+
+const port = process.env.PORT || 5000;
+const xivApiKey = typeof process.env.XIV_API_KEY === 'string' && process.env.XIV_API_KEY !== '' ? process.env.XIV_API_KEY : undefined;
+const supportedLanguages = ['en', 'ja', 'de', 'fr'];
+
+const app = express();
+const creator = new CardCreator(xivApiKey);
+
+// Initialize caching on disk
+const diskCache = cacheManager.caching({
+  store: fsStore,
+  options: {
+    reviveBuffers: true,
+    binaryAsStream: false,
+    ttl: 14400, // s = 4h
+    maxsize: 1000000000, // bytes = 1 GB
+    path: 'diskcache',
+    preventfill: true,
+  }
+});
+
+// Rate limit all requests that result in XIV API calls
+const limiter = rateLimit({
+  windowMs: 1000, // ms = 1s
+  max: 20, // default XIV API request limit
+  keyGenerator: () => 'global',
+});
+
+async function getCharacterIdByName(world, name, retries = 1) {
+  if (retries === -1) return undefined;
+
+  const searchUrl = new URL('https://xivapi.com/character/search');
+  searchUrl.searchParams.set('name', name)
+  searchUrl.searchParams.set('server', world)
+  if (xivApiKey != null) searchUrl.searchParams.set('private_key', xivApiKey)
+
+  const response = await fetch(searchUrl.toString());
+  const data = await response.json();
+
+  if (data.Results[0] === undefined) return getCharacterIdByName(world, name, --retries);
+
+  return data.Results[0].ID;
+}
+
+async function cacheCreateCard(characterId, customImage, language) {
+  const cacheKey = `img:${characterId}:${customImage}:${language}`;
+
+  return diskCache.wrap(cacheKey, async () => {
+    await creator.ensureInit().catch(error => { throw new Error(`Init failed with: ${error}`) });
+    const image = await creator.createCard(characterId, customImage, language).catch(error => { throw new Error(`Create card failed with: ${error}`) });
+
+    return {
+      binary: {
+        image,
+      },
+    };
+  });
+}
+
+function getOriginalQueryString(req) {
+  const url = new URL(req.originalUrl, 'http://example.org');
+  return url.search;
+}
+
+app.get('/prepare/id/:characterId', limiter, (req, res, next) => {
+  const language = typeof req.query.lang === 'string' && supportedLanguages.includes(req.query.lang) ? req.query.lang : supportedLanguages[0];
+
+  cacheCreateCard(req.params.characterId, null, language)
+    .then(() => {
+      res.status(200).json({
+        status: 'ok',
+        url: `/characters/id/${req.params.characterId}.png`,
+      });
+    })
+    .catch(next);
+});
+
+app.get('/prepare/name/:world/:characterName', limiter, (req, res, next) => {
+  getCharacterIdByName(req.params.world, req.params.characterName)
+    .then(characterId => {
+      if (characterId == null) {
+        res.status(404).send({ status: 'error', reason: 'Character not found.' });
+      } else {
+        res.redirect(`/prepare/id/${characterId}${getOriginalQueryString(req)}`);
+      }
+    })
+    .catch(next);
+});
+
+app.get('/characters/id/:characterId.png', limiter, (req, res, next) => {
+  const language = typeof req.query.lang === 'string' && supportedLanguages.includes(req.query.lang) ? req.query.lang : supportedLanguages[0];
+
+  cacheCreateCard(req.params.characterId, null, language)
+    .then(result => {
+      const image = result.binary.image;
+
+      res.writeHead(200, {
+        'Cache-Control': 'public, max-age=14400',
+        'Content-Length': Buffer.byteLength(image),
+        'Content-Type': 'image/png',
+      });
+
+      res.end(image, 'binary');
+    })
+    .catch(next);
+});
+
+app.get('/characters/id/:characterId', (req, res) => {
+  res.redirect(`/characters/id/${req.params.characterId}.png${getOriginalQueryString(req)}`);
+});
+
+app.get('/characters/name/:world/:characterName.png', limiter, (req, res, next) => {
+  getCharacterIdByName(req.params.world, req.params.characterName)
+    .then(characterId => {
+      if (characterId == null) {
+        res.status(404).send({ status: 'error', reason: 'Character not found.' });
+      } else {
+        res.redirect(`/characters/id/${characterId}${getOriginalQueryString(req)}`);
+      }
+    })
+    .catch(next);
+});
+
+app.get('/characters/name/:world/:characterName', (req, res) => {
+  res.redirect(`/characters/name/${req.params.world}/${req.params.characterName}.png${getOriginalQueryString(req)}`);
+});
+
+app.get('/', async (req, res) => {
+  res.redirect('https://github.com/xivapi/XIV-Character-Cards');
+});
+
+app.use((error, req, res, next) => {
+  console.error(error);
+  res.status(500).json({
+    status: 'error',
+    reason: error instanceof Error ? error.stack : String(error),
+  });
+});
+
+app.listen(port, () => {
+  console.log(`Listening at http://localhost:${port}`);
+  creator.ensureInit().then(() => console.log('CardCreator initialization complete'));
+});

package.json

@@ -1,7 +1,7 @@
 {
   "name": "xiv-character-cards",
   "description": "API to create fancy cards for FFXIV characters based on their Lodestone data, hosted at https://ffxiv-character-cards.herokuapp.com.",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "main": "create-card.js",
   "repository": "https://github.com/xivapi/XIV-Character-Cards.git",
   "license": "AGPL-3.0-only",
@@ -16,15 +16,16 @@
     "docs:deploy": "npm run docs:generate && node gh-pages.js"
   },
   "dependencies": {
-    "cache-manager-fs": "^1.0.8",
+    "cache-manager": "^3.4.4",
     "cache-manager-fs-binary": "^1.0.4",
-    "canvas": "^2.6.1",
+    "canvas": "^2.8.0",
     "express": "^4.17.1",
-    "node-fetch": "^2.6.1"
+    "express-rate-limit": "^5.5.0",
+    "node-fetch": "^2.6.5"
   },
   "devDependencies": {
-    "gh-pages": "^3.2.0",
+    "gh-pages": "^3.2.3",
     "jsdoc": "^3.6.7",
-    "nodemon": "^2.0.7"
+    "nodemon": "^2.0.14"
   }
 }

readme.md

@@ -1,78 +1,76 @@
 # XIV Character Cards
+
 ![npm Version](https://img.shields.io/npm/v/xiv-character-cards)
 [![Documentation](https://img.shields.io/badge/docs-JSDoc-orange)](https://xivapi.github.io/XIV-Character-Cards/)
 
-API to create fancy cards for FFXIV characters based on their Lodestone data, hosted at https://ffxiv-character-cards.herokuapp.com.
+Library and API to create fancy cards for FFXIV characters based on their Lodestone data, powered by [xivapi.com](https://xivapi.com/) and hosted at [https://ffxiv-character-cards.herokuapp.com](https://ffxiv-character-cards.herokuapp.com).
 
 ![Demo image](https://ffxiv-character-cards.herokuapp.com/characters/id/9575452.png)
 
-## Endpoints
+## API
 
-### Getting images
+All API calls support the `lang` query parameter to create a character card with information in the specified language. The supported languages are the same as [xivapi.com](https://xivapi.com/docs/Common-Features#language), which are English (en), Japanese (ja), German (de) and French (fr).
 
-``https://ffxiv-character-cards.herokuapp.com/characters/id/<LODESTONE ID>.png``
-<br>Get the PNG for a character by its Lodestone ID.
+E.g. a request for a german character card would look like this: ``https://ffxiv-character-cards.herokuapp.com/characters/id/<LODESTONE ID>.png?lang=de``
+
+### Getting a card for a character by its Lodestone ID
+
+``GET https://ffxiv-character-cards.herokuapp.com/characters/id/<LODESTONE ID>.png``
+
+### Getting card for a character by its world and name
+
+``GET https://ffxiv-character-cards.herokuapp.com/characters/name/<WORLD>/<CHARACTER NAME>.png``
+<br>**Note:** This is considerably slower than the creation by ID, since the character has to be looked up in the Lodestone first.
 
 <br>
 
-``https://ffxiv-character-cards.herokuapp.com/characters/name/<WORLD>/<CHARACTER NAME>.png``
-<br>Get the PNG for a character by its world and name.
-
-### Requesting images to be cached
-If you are using this API together with an application that requires the API to respond very quickly, like Discord, you need to ask it to "prepare" the image for a character beforehand.
-
-``https://ffxiv-character-cards.herokuapp.com/prepare/id/<LODESTONE ID>``
-<br>Request a character image to be cached by its Lodestone ID.
-
-<br>
-
-``https://ffxiv-character-cards.herokuapp.com/prepare/name/<WORLD>/<CHARACTER NAME>``
-<br>Request a character image to be cached by its world and name.
-
-The API will reply with its status, and in case of success, the URL to the final image.
+If you are using this API together with an application that requires the API to respond very quickly, like Discord, you may need to ask it to "prepare" the card image for a character beforehand. The API will reply with its status, and in case of success, the URL to the final image.
 ``{"status":"ok","url":"/characters/id/123456789.png"}``
 
-## Using in your application
+### Requesting a card to be cached for a character by its Lodestone ID
 
-```
+``GET https://ffxiv-character-cards.herokuapp.com/prepare/id/<LODESTONE ID>``
+
+### Requesting a card to be cached for a character by its world and name
+
+``GET https://ffxiv-character-cards.herokuapp.com/prepare/name/<WORLD>/<CHARACTER NAME>``
+
+## Library
+
+To use the card creator as a library in your Node.JS application, first install it as a dependency with:
+
+```sh
 yarn add xiv-character-cards
 # or
 npm i xiv-character-cards
 ```
 
-You will receive a PNG-buffer for you to use in your bot or application.<br>Check ``index.js`` for other usage examples.
+You can then instantiate the class `CardCreator` from the library, call the asynchronous `insureInit()` function to make sure all resources are loaded and then use the asynchronous `createCard()` function with your characters Lodestone ID. You will receive a promise that resolves to a `Buffer` of the PNG image of your card, that you can use in your bot or application.
 
-### Example
+Check the [library documentation](https://xivapi.github.io/XIV-Character-Cards/) for more details.
+
+> **Note:** The API server is not published as an NPM package, so if you want to host it yourself, clone the [Github repository](https://github.com/xivapi/XIV-Character-Cards) and put the Express.JS webserver defined in the `index.js` file behind a reverse proxy.
+
+### Library example
 
 ```js
 const { CardCreator } = require("xiv-character-cards");
-const fs = require("fs");
+const { writeFileSync } = require("fs");
 
-const card = new CardCreator();
-const lodestoneid = "13821878";
+const creator = new CardCreator();
+const lodestoneId = "13821878";
 
-function example(cb) {
-  card.ensureInit()
-    .then(
-      () => card.createCard(lodestoneid),
-      (reason) => cb("Init failed: " + reason, null)
-    )
-    .then((image) =>
-      cb(null, {
-        binary: {
-          image: image,
-        },
-      })
-    )
-    .catch((reason) => cb("createCard failed: " + reason, null));
+async function example() {
+  await creator.ensureInit();
+  return creator.createCard(lodestoneId);
 }
 
-example((err, response) => {
-  const buffer = response.binary.image;
-  fs.writeFileSync(`./${lodestoneid}.png`, response.binary.image, (err) => {
-    if (err) {
-      console.log(err);
-    }
+example()
+  .then(card => {
+    writeFileSync(`./${lodestoneId}.png`, card);
+  })
+  .catch(error => {
+    console.error('Creator initialization or card creation failed!');
+    console.error(error);
   });
-});
 ```