isbnlab 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +140 -2
- package/dist/index.d.mts +2173 -0
- package/dist/index.d.ts +2173 -0
- package/dist/index.js +2361 -0
- package/dist/index.js.map +1 -0
- package/dist/index.mjs +2338 -0
- package/dist/index.mjs.map +1 -0
- package/package.json +63 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 RINC Productions, LLC (ISBNLab)
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,141 @@
|
|
|
1
|
-
#
|
|
1
|
+
# ISBNLab JavaScript and TypeScript client
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The official JavaScript and TypeScript client for the [ISBNLab book metadata API](https://www.isbnlab.com/api-information). Look up a book by ISBN and get its title, authors, publishers, series, BISAC genres, formats, page count, description and every other edition, from a catalog of more than 100 million editions. It also validates and converts ISBN-10, ISBN-13, EAN and Amazon ASIN.
|
|
4
|
+
|
|
5
|
+
Typed, with no runtime dependencies: it uses the built-in `fetch` of Node.js 18+, Deno, Bun and browsers. Works with `import` and `require`.
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npm install isbnlab
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## Get an API token
|
|
14
|
+
|
|
15
|
+
[Create a free ISBNLab account](https://www.isbnlab.com/register) and copy your API token from your profile. The Free plan includes 1,000 calls a day; see [pricing](https://www.isbnlab.com/pricing) for more.
|
|
16
|
+
|
|
17
|
+
## Quick start
|
|
18
|
+
|
|
19
|
+
```ts
|
|
20
|
+
import { BooksApi, Configuration } from 'isbnlab';
|
|
21
|
+
|
|
22
|
+
const config = new Configuration({ accessToken: process.env.ISBNLAB_API_TOKEN });
|
|
23
|
+
const books = new BooksApi(config);
|
|
24
|
+
|
|
25
|
+
const book = await books.getBookByIsbn('9780765302304');
|
|
26
|
+
|
|
27
|
+
console.log(book.title); // The Gathering Storm
|
|
28
|
+
console.log(book.authors?.[0]?.name); // Robert Jordan
|
|
29
|
+
console.log(book.publishDate?.getUTCFullYear());
|
|
30
|
+
|
|
31
|
+
console.log(book.otherEditionsCount, 'other editions');
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Many fields are empty for some books, so every field is optional and may be `null`.
|
|
35
|
+
|
|
36
|
+
Linked records carry ids you can look up directly (author, publisher, subject and genre lookups need a Standard or Pro plan):
|
|
37
|
+
|
|
38
|
+
```ts
|
|
39
|
+
import { AuthorsApi } from 'isbnlab';
|
|
40
|
+
|
|
41
|
+
const authorId = book.authors?.[0]?.id;
|
|
42
|
+
if (authorId != null) {
|
|
43
|
+
const author = await new AuthorsApi(config).getAuthor(String(authorId));
|
|
44
|
+
console.log(author.bio);
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Fields that depend on your plan
|
|
49
|
+
|
|
50
|
+
A book lookup lists the other editions (`otherEditions`, `previousEdition`, `nextEdition`) on the Pro plan. On the Free and Standard plans those fields are empty, `otherEditionsCount` still gives the number of other editions, and two response headers name what was left out: `X-Plan-Restricted-Fields` lists the fields and `X-Plan-Upgrade` links to the plans. `restrictedFields()` and `upgradeUrl()` read them from a `...Raw()` call:
|
|
51
|
+
|
|
52
|
+
```ts
|
|
53
|
+
import { restrictedFields, upgradeUrl } from 'isbnlab';
|
|
54
|
+
|
|
55
|
+
const response = await books.getBookByIsbnRaw({ isbn: '9780765302304' });
|
|
56
|
+
const full = await response.value();
|
|
57
|
+
|
|
58
|
+
if (restrictedFields(response).includes('otherEditions')) {
|
|
59
|
+
console.log(full.otherEditionsCount, 'other editions; see', upgradeUrl(response));
|
|
60
|
+
} else {
|
|
61
|
+
for (const edition of full.otherEditions ?? []) {
|
|
62
|
+
console.log(edition.isbn13, edition.title);
|
|
63
|
+
}
|
|
64
|
+
}
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`restrictedFields(response)` returns every field that was left out, for example `['otherEditions', 'previousEdition', 'nextEdition']`, or `[]` when the response is complete. It also accepts a fetch `Response` or `Headers`.
|
|
68
|
+
|
|
69
|
+
A cover lookup (Standard or Pro) gives each cover image's URL in `covers`, and in `sizes` the same image 200, 400 and 800 pixels wide (`w200`, `w400`, `w800`); a width is empty when that size is not available.
|
|
70
|
+
|
|
71
|
+
```ts
|
|
72
|
+
const cover = await books.getBookCoverByIsbn('9780765302304');
|
|
73
|
+
console.log(cover.sizes?.[0]?.w400); // https://covers.isbnlab.com/w400/9780765302304.jpg
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Errors
|
|
77
|
+
|
|
78
|
+
Any response other than 2xx rejects with `ResponseError`. Its `response` is the fetch `Response`, and the body's `detail` explains the reason:
|
|
79
|
+
|
|
80
|
+
```ts
|
|
81
|
+
import { ResponseError } from 'isbnlab';
|
|
82
|
+
|
|
83
|
+
try {
|
|
84
|
+
await books.getBookByIsbn('9780000000000');
|
|
85
|
+
} catch (e) {
|
|
86
|
+
if (!(e instanceof ResponseError)) throw e;
|
|
87
|
+
|
|
88
|
+
const { detail } = await e.response.json();
|
|
89
|
+
switch (e.response.status) {
|
|
90
|
+
case 404: console.log('Not in the catalog'); break;
|
|
91
|
+
case 429: console.log('Daily limit reached:', detail); break;
|
|
92
|
+
case 403: console.log('Your plan does not include this endpoint:', detail); break;
|
|
93
|
+
default: throw e;
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
A network failure rejects with `FetchError` instead.
|
|
99
|
+
|
|
100
|
+
## Keep your token out of browser code
|
|
101
|
+
|
|
102
|
+
Anyone can read a token that is shipped to the browser, so call the API from your server where you can. For tools that can't send headers, the API also accepts a URL key (it starts with `ilq_` and is created on your profile) as a query parameter: `new Configuration({ apiKey: 'ilq_...' })`. It works only for GET requests and anyone who sees the URL can use it, so treat it as visible too.
|
|
103
|
+
|
|
104
|
+
## What you can call
|
|
105
|
+
|
|
106
|
+
| Class | Method | Plan |
|
|
107
|
+
|---|---|---|
|
|
108
|
+
| `BooksApi` | `getBookByIsbn(isbn)`, `getBookByAsin(asin)`, `getBookById(id)` | Free |
|
|
109
|
+
| `IsbnApi` | `parseIsbn`, `isbn10ToIsbn13`, `isbn13ToIsbn10`, `isbnToEan`, `eanToIsbn`, `isbnToAsin`, `asinToIsbn` | Free |
|
|
110
|
+
| `BooksApi` | `getBookCoverByIsbn(isbn)`, `getBookCoverByAsin(asin)` | Standard |
|
|
111
|
+
| `AuthorsApi` | `getAuthor(id)`, `findAuthor(name)` | Standard |
|
|
112
|
+
| `PublishersApi` | `getPublisher(id)`, `findPublisher(name)`, `getPublishersByPrefix(prefix)` | Standard |
|
|
113
|
+
| `SubjectsApi` | `getSubject(id)`, `findSubject(name)` | Standard |
|
|
114
|
+
| `GenresApi` | `getGenre(id)`, `findGenre(nameOrBisacCode)` | Standard |
|
|
115
|
+
| `BooksApi` | `searchBooks(query, limit, page, maxResults)` | Pro |
|
|
116
|
+
| `BooksApi` | `getEditionsByIsbn(isbn)`, `getEditionsByAsin(asin)` | Pro |
|
|
117
|
+
|
|
118
|
+
Every method also has a `...Raw()` version that returns the full response, for example to read the rate-limit headers:
|
|
119
|
+
|
|
120
|
+
```ts
|
|
121
|
+
const response = await books.getBookByIsbnRaw({ isbn: '9780765302304' });
|
|
122
|
+
console.log(response.raw.headers.get('X-RateLimit-Remaining'));
|
|
123
|
+
const book = await response.value();
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Field-by-field documentation: [API documentation](https://www.isbnlab.com/api-information).
|
|
127
|
+
|
|
128
|
+
## Development
|
|
129
|
+
|
|
130
|
+
`src/` is generated from the API's [OpenAPI document](https://www.isbnlab.com/api/docs.jsonopenapi) with [OpenAPI Generator](https://openapi-generator.tech/), so changes to it are made in the generator and arrive with the next release; please open an issue rather than a pull request for that folder. `README.md`, `package.json`, the build configuration and `test/` are maintained by hand.
|
|
131
|
+
|
|
132
|
+
```bash
|
|
133
|
+
npm install
|
|
134
|
+
npm run typecheck
|
|
135
|
+
npm test
|
|
136
|
+
npm run build && npm run test:dist
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
## License
|
|
140
|
+
|
|
141
|
+
MIT. Maintained by [ISBNLab](https://www.isbnlab.com/), the book metadata API.
|