@library-pals/isbn 0.0.0

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,30 @@
+name: Publish npm package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm test
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          registry-url: https://registry.npmjs.org/
+      - run: npm ci
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

package/.github/workflows/test.yml

@@ -0,0 +1,14 @@
+name: Test
+
+on: push
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npm test
+        env:
+          CI: true

package/README.md

@@ -0,0 +1,151 @@
+# @library-pals/isbn
+
+An npm module that given an ISBN will return the book's metadata using the
+following providers:
+
+- [Google Books API](https://developers.google.com/books/)
+- [Open Library Books API](https://openlibrary.org/dev/docs/api/books)
+- [WorldCat xISBN API](http://xisbn.worldcat.org/xisbnadmin/doc/api.htm)
+- [ISBNdb API](https://isbndb.com/apidocs/v2) using API key in the environment
+  variable `ISBNDB_API_KEY`
+
+## Acknowledgements
+
+This repository is a fork of
+[node-isbn by Guido García <@palmerabollo>](https://github.com/palmerabollo/node-isbn).
+
+## Installation
+
+```bash
+npm install @library-pals/isbn
+```
+
+Supports Node.js versions 20.x and greater.
+
+## Examples
+
+```javascript
+import isbn from "@library-pals/isbn";
+
+try {
+  const book = await isbn.resolve("9780374104092");
+  console.log("Book found %j", book);
+} catch (err) {
+  console.log("Book not found", err);
+}
+```
+
+### Setting a timeout
+
+```javascript
+import isbn from "@library-pals/isbn";
+
+try {
+  const book = await isbn.resolve("9780374104092", { timeout: 15000 });
+  console.log("Book found %j", book);
+} catch (err) {
+  console.log("Book not found", err);
+}
+```
+
+### Response
+
+Response follows the same schema, but some fields could depend on the service
+that was used to find the book. In general, Google Books API returns more
+information.
+
+```json
+{
+  "title": "Annihilation",
+  "subtitle": "A Novel",
+  "authors": ["Jeff VanderMeer"],
+  "publisher": "Macmillan",
+  "publishedDate": "2014-02-04",
+  "description": "Describes the 12th expedition to “Area X,” a region cut off from the continent for decades, by a group of intrepid women scientists who try to ignore the high mortality rates of those on the previous 11 missions. Original. 75,000 first printing.",
+  "industryIdentifiers": [
+    { "type": "ISBN_13", "identifier": "9780374104092" },
+    { "type": "ISBN_10", "identifier": "0374104093" }
+  ],
+  "readingModes": { "text": false, "image": false },
+  "pageCount": 209,
+  "printType": "BOOK",
+  "categories": ["Fiction"],
+  "averageRating": 5,
+  "ratingsCount": 1,
+  "maturityRating": "NOT_MATURE",
+  "allowAnonLogging": false,
+  "contentVersion": "0.5.1.0.preview.0",
+  "panelizationSummary": {
+    "containsEpubBubbles": false,
+    "containsImageBubbles": false
+  },
+  "imageLinks": {
+    "smallThumbnail": "http://books.google.com/books/content?id=2cl7AgAAQBAJ&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api",
+    "thumbnail": "http://books.google.com/books/content?id=2cl7AgAAQBAJ&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api"
+  },
+  "language": "en",
+  "previewLink": "http://books.google.com/books?id=2cl7AgAAQBAJ&printsec=frontcover&dq=isbn:9780374104092&hl=&cd=1&source=gbs_api",
+  "infoLink": "http://books.google.com/books?id=2cl7AgAAQBAJ&dq=isbn:9780374104092&hl=&source=gbs_api",
+  "canonicalVolumeLink": "https://books.google.com/books/about/Annihilation.html?hl=&id=2cl7AgAAQBAJ"
+}
+```
+
+### Setting backend providers
+
+You can optionally specify the providers that you want to use, in the order you
+need them to be invoked.
+
+```javascript
+import isbn from "@library-pals/isbn";
+
+// This request will search first in the Open Library API and then in the Google Books API
+isbn.provider(["openlibrary", "google"]);
+
+try {
+  const book = await isbn.resolve("9780374104092");
+  console.log("Book isbn:" + input + " found %j", book);
+} catch (err) {
+  console.log("Book isbn:" + input + " not found", err);
+}
+```
+
+```javascript
+import isbn from "@library-pals/isbn";
+
+// This request will search ONLY in the Google Books API
+isbn.provider( "google"]);
+
+try {
+  const book = await isbn.resolve("9780374104092");
+  console.log("Book isbn:" + input + " found %j", book);
+} catch (err) {
+  console.log("Book isbn:" + input + " not found", err);
+}
+```
+
+If you do not like using strings to specify the providers, you could grab the
+providers from `isbn.PROVIDER_NAMES` constant that the library provides!
+
+```javascript
+import isbn from "@library-pals/isbn";
+
+// This request will search ONLY in the Google Books API
+isbn.provider([isbn.PROVIDER_NAMES.GOOGLE]);
+
+try {
+  const book = await isbn.resolve("9780374104092");
+  console.log("Book isbn:" + input + " found %j", book);
+} catch (err) {
+  console.log("Book isbn:" + input + " not found", err);
+}
+```
+
+## License
+
+**AGPL v3.0 LICENSE** http://www.gnu.org/licenses/agpl-3.0.html
+
+See also
+[Google Books API Terms of Service](https://developers.google.com/books/terms),
+[Open Library Licensing](https://openlibrary.org/developers/licensing),
+[WorldCat xISBN Terms of Service](http://www.oclc.org/worldcat/community/terms.en.html),
+[ISBNdb Terms and Conditions](https://isbndb.com/terms-and-conditions).

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@library-pals/isbn",
+  "version": "0.0.0",
+  "description": "Find books by ISBN",
+  "main": "src/index.js",
+  "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "bin": {
+    "isbn": "./src/cli.js"
+  },
+  "scripts": {
+    "lint": "eslint .",
+    "pretest": "npm run lint",
+    "test": "mocha test/spec",
+    "testDebug": "mocha --inspect-brk test/spec"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/library-pals/isbn.git"
+  },
+  "keywords": [
+    "isbn",
+    "book",
+    "google",
+    "openlibrary",
+    "api",
+    "worldcat",
+    "isbndb"
+  ],
+  "author": "Katy DeCorah <@katydecorah>",
+  "license": "AGPL-3.0-or-later",
+  "devDependencies": {
+    "@eslint/js": "^9.2.0",
+    "@types/nock": "^11.1.0",
+    "eslint": "^9.2.0",
+    "eslint-plugin-jsdoc": "^48.2.3",
+    "eslint-plugin-unicorn": "^52.0.0",
+    "globals": "^15.1.0",
+    "meow": "^13.2.0",
+    "mocha": "^10.4.0",
+    "nock": "^13.5.4"
+  },
+  "dependencies": {
+    "axios": "^1.6.8"
+  },
+  "bugs": {
+    "url": "https://github.com/palmerabollo/node-isbn/issues"
+  },
+  "homepage": "https://github.com/palmerabollo/node-isbn#readme",
+  "directories": {
+    "example": "examples",
+    "test": "test"
+  }
+}

package/src/cli.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import meow from "meow";
+import isbn from "./index.js";
+
+const cli = meow(
+  `
+  Usage
+    $ isbn <input>
+
+  Options
+    --isbn, -i  The ISBN for the book
+
+  Examples
+    $ isbn 9780374104092
+
+  This script will resolve the provided ISBN to a book. The ISBN must be a valid ISBN-10 or ISBN-13.
+`,
+  {
+    importMeta: import.meta,
+    flags: {
+      isbn: {
+        type: "string",
+        shortFlag: "i",
+        isRequired: true,
+      },
+    },
+  }
+);
+
+if (!/^(\d{10}|\d{13})$/.test(cli.flags.isbn)) {
+  console.error("Invalid ISBN. Please provide a valid ISBN-10 or ISBN-13.");
+  process.exit(1);
+}
+
+try {
+  const book = await isbn.resolve(cli.flags.isbn);
+  console.log(book);
+} catch (error) {
+  console.error("An error occurred while trying to resolve the ISBN:", error);
+  process.exit(1);
+}

package/src/index.js

@@ -0,0 +1,93 @@
+import {
+  PROVIDER_NAMES,
+  DEFAULT_PROVIDERS,
+  PROVIDER_RESOLVERS,
+} from "./provider-resolvers.js";
+
+/**
+ * Represents an ISBN (International Standard Book Number) utility class.
+ * Provides methods for configuring providers, retrieving book information, and resolving ISBNs.
+ */
+class Isbn {
+  constructor() {
+    this.PROVIDER_NAMES = PROVIDER_NAMES;
+
+    this._resetProviders();
+  }
+
+  /**
+   * Resets the providers to the default set of providers.
+   */
+  _resetProviders() {
+    this._providers = DEFAULT_PROVIDERS;
+  }
+
+  /**
+   * Sets the providers for the ISBN lookup.
+   * @param {string[]} providers - An array of provider names.
+   * @returns {object} - The current instance of the ISBN lookup.
+   * @throws {TypeError} - If `providers` is not an array.
+   * @throws {Error} - If any of the provided providers are not supported.
+   */
+  provider(providers) {
+    if (!Array.isArray(providers)) {
+      throw new TypeError("`providers` must be an array.");
+    }
+
+    if (providers.length === 0) {
+      return this;
+    }
+
+    const unsupportedProviders = providers.filter(
+      (p) => !DEFAULT_PROVIDERS.includes(p)
+    );
+    if (unsupportedProviders.length > 0) {
+      throw new Error(
+        `Unsupported providers: ${unsupportedProviders.join(", ")}`
+      );
+    }
+
+    this._providers = [...new Set(providers)];
+    return this;
+  }
+
+  /**
+   * Retrieves book information from a list of providers using the given ISBN.
+   * @param {Array<string>} providers - The list of providers to retrieve book information from.
+   * @param {string} isbn - The ISBN of the book.
+   * @param {object} options - Additional options for retrieving book information.
+   * @returns {Promise<object>} A promise that resolves to the book information.
+   * @throws {Error} If none of the providers are able to retrieve the book information.
+   */
+  async _getBookInfo(providers, isbn, options) {
+    for (const provider of providers) {
+      try {
+        return await PROVIDER_RESOLVERS[provider](isbn, options);
+      } catch {
+        // console.debug(`Unable to reach ${provider}. Trying the next one...`);
+      }
+    }
+    // If none of the providers worked, we throw an error.
+    throw new Error("All providers failed.");
+  }
+
+  /**
+   * Resolves the book information for the given ISBN.
+   * @param {string} isbn - The ISBN of the book.
+   * @param {object} options - The options for the request.
+   * @returns {Promise<object>} - A Promise that resolves to the book information.
+   * @throws {Error} - If an error occurs while resolving the book information.
+   */
+  async resolve(isbn, options = {}) {
+    try {
+      const book = await this._getBookInfo(this._providers, isbn, options);
+      this._resetProviders();
+      return book;
+    } catch (error) {
+      this._resetProviders();
+      throw error;
+    }
+  }
+}
+
+export default new Isbn();

package/src/provider-resolvers.js

@@ -0,0 +1,41 @@
+import { resolveGoogle } from "./providers/google.js";
+import { resolveOpenLibrary } from "./providers/open-library.js";
+import { resolveWorldcat } from "./providers/worldcat.js";
+import { resolveIsbnDb } from "./providers/isbndb.js";
+
+export const defaultOptions = {
+  poll: {
+    maxSockets: 500,
+  },
+  timeout: 5000,
+};
+
+export const GOOGLE_BOOKS_API_BASE = "https://www.googleapis.com";
+export const GOOGLE_BOOKS_API_BOOK = "/books/v1/volumes";
+
+export const OPENLIBRARY_API_BASE = "https://openlibrary.org";
+export const OPENLIBRARY_API_BOOK = "/api/books";
+
+export const WORLDCAT_API_BASE = "http://xisbn.worldcat.org";
+export const WORLDCAT_API_BOOK = "/webservices/xid/isbn";
+
+export const ISBNDB_API_BASE = "https://api2.isbndb.com";
+export const ISBNDB_API_BOOK = "/book";
+export const PROVIDER_NAMES = {
+  GOOGLE: "google",
+  OPENLIBRARY: "openlibrary",
+  WORLDCAT: "worldcat",
+  ISBNDB: "isbndb",
+};
+export const DEFAULT_PROVIDERS = [
+  PROVIDER_NAMES.GOOGLE,
+  PROVIDER_NAMES.OPENLIBRARY,
+  PROVIDER_NAMES.WORLDCAT,
+  PROVIDER_NAMES.ISBNDB,
+];
+export const PROVIDER_RESOLVERS = {
+  [PROVIDER_NAMES.GOOGLE]: resolveGoogle,
+  [PROVIDER_NAMES.OPENLIBRARY]: resolveOpenLibrary,
+  [PROVIDER_NAMES.WORLDCAT]: resolveWorldcat,
+  [PROVIDER_NAMES.ISBNDB]: resolveIsbnDb,
+};

package/src/providers/google.js

@@ -0,0 +1,36 @@
+import axios from "axios";
+import {
+  defaultOptions,
+  GOOGLE_BOOKS_API_BASE,
+  GOOGLE_BOOKS_API_BOOK,
+} from "../provider-resolvers.js";
+
+/**
+ * Resolves book information from Google Books API using the provided ISBN.
+ * @param {string} isbn - The ISBN of the book.
+ * @param {object} options - Additional options for the API request.
+ * @returns {Promise<object>} The book information retrieved from the API.
+ * @throws {Error} If the API response code is not 200, or if no books are found with the provided ISBN, or if no volume information is found for the book.
+ */
+export async function resolveGoogle(isbn, options) {
+  const requestOptions = {
+    ...defaultOptions,
+    ...options,
+    url: `${GOOGLE_BOOKS_API_BASE}${GOOGLE_BOOKS_API_BOOK}?q=isbn:${isbn}`,
+  };
+
+  const { status, data } = await axios.request(requestOptions);
+  if (status !== 200) {
+    throw new Error(`wrong response code: ${status}`);
+  }
+  const books = data;
+  if (!books.totalItems) {
+    throw new Error(`no books found with isbn: ${isbn}`);
+  }
+  // In very rare circumstances books.items[0] is undefined (see #2)
+  if (!books.items || books.items.length === 0) {
+    throw new Error(`no volume info found for book with isbn: ${isbn}`);
+  }
+  const book = books.items[0].volumeInfo;
+  return book;
+}

package/src/providers/isbndb.js

@@ -0,0 +1,60 @@
+import axios from "axios";
+import {
+  defaultOptions,
+  ISBNDB_API_BASE,
+  ISBNDB_API_BOOK,
+} from "../provider-resolvers.js";
+
+/**
+ * Resolves the ISBN using the ISBNdb API.
+ * @param {string} isbn - The ISBN to resolve.
+ * @param {object} options - Additional options for the request.
+ * @returns {Promise<object>} - A promise that resolves to the standardized book data.
+ * @throws {Error} - If the response code is not 200 or if no books are found with the given ISBN.
+ */
+export async function resolveIsbnDb(isbn, options) {
+  const requestOptions = {
+    ...defaultOptions,
+    ...options,
+    url: `${ISBNDB_API_BASE}${ISBNDB_API_BOOK}/${isbn}`,
+    headers: { Authorization: process.env.ISBNDB_API_KEY || "" },
+  };
+
+  const { status, data } = await axios.request(requestOptions);
+  if (status !== 200) {
+    throw new Error(
+      `Wrong response code: ${status}. Response data: ${JSON.stringify(data)}`
+    );
+  }
+  const books = data;
+  if (!books.book) {
+    throw new Error(`No books found with ISBN: ${isbn}`);
+  }
+  return standardize(books.book);
+}
+
+/**
+ * Standardizes a book object by transforming its properties into a consistent format.
+ * @param {object} book - The book object to be standardized.
+ * @returns {object} - The standardized book object.
+ */
+function standardize(book) {
+  return {
+    title: book.title_long,
+    publishedDate: book.date_published,
+    authors: book.authors,
+    description: book.overview,
+    industryIdentifiers: [book.isbn, book.isbn13, book.dewey_decimal].filter(
+      Boolean
+    ),
+    pageCount: book.pages,
+    printType: "BOOK",
+    categories: book.subjects,
+    imageLinks: {
+      smallThumbnail: book.image,
+      thumbnail: book.image,
+    },
+    publisher: book.publisher,
+    language: book.language,
+  };
+}

package/src/providers/open-library.js

@@ -0,0 +1,72 @@
+import axios from "axios";
+import {
+  defaultOptions,
+  OPENLIBRARY_API_BASE,
+  OPENLIBRARY_API_BOOK,
+} from "../provider-resolvers.js";
+
+/**
+ * Resolves a book from the Open Library API using the provided ISBN.
+ * @param {string} isbn - The ISBN of the book.
+ * @param {object} options - Additional options for the request.
+ * @returns {Promise<object>} A promise that resolves to the standardized book object.
+ * @throws {Error} If the response code is not 200 or if no books are found with the provided ISBN.
+ */
+export async function resolveOpenLibrary(isbn, options) {
+  const requestOptions = {
+    ...defaultOptions,
+    ...options,
+    url: `${OPENLIBRARY_API_BASE}${OPENLIBRARY_API_BOOK}?bibkeys=ISBN:${isbn}&format=json&jscmd=details`,
+  };
+
+  const { status, data } = await axios.request(requestOptions);
+  if (status !== 200) {
+    throw new Error(
+      `Wrong response code: ${status}. Response data: ${JSON.stringify(data)}`
+    );
+  }
+  const books = data;
+  const book = books[`ISBN:${isbn}`];
+  if (!book) {
+    throw new Error(`No books found with ISBN: ${isbn}`);
+  }
+  return standardize(book);
+}
+
+const LANGUAGE_MAP = {
+  "/languages/eng": "en",
+  "/languages/spa": "es",
+  "/languages/fre": "fr",
+};
+
+/**
+ * Standardizes a book object by extracting relevant information from the provided book object.
+ * @param {object} book - The book object to be standardized.
+ * @returns {object} - The standardized book object.
+ */
+function standardize(book) {
+  const standardBook = {
+    title: book.details.title,
+    publishedDate: book.details.publish_date,
+    authors: book.details.authors
+      ? book.details.authors.map(({ name }) => name)
+      : [],
+    description: book.details.subtitle,
+    industryIdentifiers: [],
+    pageCount: book.details.number_of_pages,
+    printType: "BOOK",
+    categories: [],
+    imageLinks: {
+      smallThumbnail: book.thumbnail_url,
+      thumbnail: book.thumbnail_url,
+    },
+    previewLink: book.preview_url,
+    infoLink: book.info_url,
+    publisher: book.details.publishers ? book.details.publishers[0] : "",
+    language: book.details.languages
+      ? LANGUAGE_MAP[book.details.languages[0].key] || "unknown"
+      : "unknown",
+  };
+
+  return standardBook;
+}

package/src/providers/worldcat.js

@@ -0,0 +1,63 @@
+import axios from "axios";
+import {
+  defaultOptions,
+  WORLDCAT_API_BASE,
+  WORLDCAT_API_BOOK,
+} from "../provider-resolvers.js";
+
+/**
+ * Resolves a book using the Worldcat API based on the provided ISBN.
+ * @param {string} isbn - The ISBN of the book to resolve.
+ * @param {object} options - Additional options for the request.
+ * @returns {Promise<object>} A promise that resolves to the standardized book object.
+ * @throws {Error} If the response code is not 200 or if no books are found with the provided ISBN.
+ */
+export async function resolveWorldcat(isbn, options) {
+  const requestOptions = {
+    ...defaultOptions,
+    ...options,
+    url: `${WORLDCAT_API_BASE}${WORLDCAT_API_BOOK}/${isbn}?method=getMetadata&fl=*&format=json`,
+  };
+
+  const { status, data } = await axios.request(requestOptions);
+  if (status !== 200) {
+    throw new Error(
+      `Wrong response code: ${status}. Response data: ${JSON.stringify(data)}`
+    );
+  }
+  const books = data;
+  if (books.stat !== "ok") {
+    throw new Error(`No books found with ISBN: ${isbn}`);
+  }
+  const [book] = books.list;
+  return standardize(book);
+}
+
+const LANGUAGE_MAP = {
+  eng: "en",
+  spa: "es",
+  fre: "fr",
+};
+
+/**
+ * Standardizes a book object by extracting relevant information from the provided book object.
+ * @param {object} book - The book object to be standardized.
+ * @returns {object} - The standardized book object.
+ */
+function standardize(book) {
+  const standardBook = {
+    title: book.title,
+    publishedDate: book.year,
+    authors: book.author ? [book.author] : [],
+    description: null,
+    industryIdentifiers: [],
+    pageCount: null,
+    printType: "BOOK",
+    categories: [],
+    imageLinks: {},
+    publisher: book.publisher,
+    language: LANGUAGE_MAP[book.lang] || "unknown",
+  };
+
+  return standardBook;
+}