npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

comic-vine-sdk

v1.2.8

Published

A JS/TS client for the Comic Vine API

Downloads

21

Readme

Comic Vine SDK

The Comic Vine SDK provides convenient access to the Comic Vine API from applications written in JavaScript/TypeScript. The API provides full access to the structured-wiki content.

Table of Contents

Installation

Install the package with:

npm install comic-vine-sdk
# or
yarn add comic-vine-sdk

TypeScript Typings

There's a good change you may find an issue with the typings in the API response objects. They were generated using sample data from the API, if you find a problem open an issue detailing the problem along with the request details so I can add that request to the sample dataset. While you wait for it to be fixed add // @ts-expect-error above the line causing the problem. This will allow you to compile in the meantime but will flag when the problem has been fixed.

Roadmap

  • Expandable responses

  • Cached responses

  • Rate limiting

Comic Vine Resources

Comic Vine resources list

The library exposes an object for each Comic Vine resource, the object names are singular and expose a retrieve method that maps to the singular resource and a list method that maps to the plural resource.

The following table lists the resources that have been implemented and how the retrieve and list methods map to the API. Most resources are a direct mapping but object has been mapped to thing, this is due to object being a reserved word in JS and thing matches the Comic Vine wiki.

| Library resource object | Retrieve Method API Resource | List Method API Resource | | ----------------------- | ------------------------------------- | ----------------------------------------- | | character | character | characters | | concept | concept | concepts | | episode | episode | episodes | | issue | issue | issues | | location | location | locations | | movie | movie | movies | | origin | origin | origins | | person | person | people | | power | power | powers | | promo | promo | promos | | publisher | publisher | publishers | | series | series | series_list | | storyArc | story_arc | story_arcs | | team | team | teams | | thing | object | objects | | video | video | videos | | videoCategory | video_category | video_categories | | videoType | video_type | video_types | | volume | volume | volumes |

Usage/Examples

Initialization

The package needs to be configured with your API key, Grab an API key. Require it with the key's value:

const ComicVine = require('comic-vine-sdk');
const comicVine = new ComicVine('your-api-key-here');

comicVine.publisher
  .retrieve(1859)
  .then((customer) => console.log(customer.id))
  .catch((error) => console.error(error));

Or using ES modules and async/await:

import ComicVine from 'comic-vine-sdk';
const comicVine = new ComicVine('your-api-key-here');

(async () => {
  try {
    const publisher = await comicVine.publisher.retrieve(1859);
    console.log(publisher.name);
  } catch (error) {
    console.error(error);
  }
})();

Options

The second parameter of the constructor accepts options to configure the library

new ComicVine('your-api-key-here', options);

baseUrl

Type: string | undefined

Default: https://comicvine.gamespot.com/api/

If using this package in node this should not need set, the default value will work.

If using the package in a web browser then The Comic Vine API does not allow cross-origin requests. This option could be used to proxy the request assuming you have some safe way for the web client to fetch your api key, you don't want to send the api key to the browser in your JS bundle.

import ComicVine from 'comic-vine-sdk';

// This is just an example, to try it out you would
// have to visit (https://cors-anywhere.herokuapp.com)
// to request temporary access.
const comicVine = new ComicVine('your-api-key-here', {
  baseUrl: 'https://cors-anywhere.herokuapp.com/https://www.comicvine.com/api/',
});

(async () => {
  try {
    const publisher = await comicVine.publisher.retrieve(1859);
    console.log(publisher.name);
  } catch (error) {
    console.error(error);
  }
})();

Fetch a single resource

All resources have a retrieve method, the following example retrieves a publisher

import ComicVine from 'comic-vine-sdk';
const comicVine = new ComicVine('your-api-key-here');

(async () => {
  try {
    const publisher = await comicVine.publisher.retrieve(1859);
    console.log(publisher.name);
  } catch (error) {
    console.error(error);
  }
})();

Fetch a resource list

All resources have a retrieve method, the following example retrieves a list of publishers

import ComicVine from 'comic-vine-sdk';
const comicVine = new ComicVine('your-api-key-here');

(async () => {
  try {
    const publishers = await comicVine.publisher.list();
    console.log(publishers.data);
  } catch (error) {
    console.error(error);
  }
})();

Limit the fields in the response payload

When making a request it's likely that only certain properties are required. Both the retrieve and list methods accept options as the second parameter. This can be used to specify the field list.

When using TypeScript this is type safe, the return type is narrowed to the field list so that intellisense only displays the properties available in the response.

import ComicVine from 'comic-vine-sdk';
const comicVine = new ComicVine('your-api-key-here');

(async () => {
  try {
    const issue = await comicVine.issue.retrieve(id, {
      fieldList: ['id', 'name', 'description'],
    });

    // The id property is in the fieldList and will be available
    console.log(issue.id);

    // In JS dateAdded will be undefined at runtime
    // in TS the compiler will produce an error because it wasn't in the fieldList
    console.log(issue.dateAdded);

    // An object containing the id, name and description properties
    console.log(issue);
  } catch (error) {
    console.error(error);
  }
})();

Pagination

The Comic Vine API provides offset based pagination, this is done by providing a limit and offset in the request. The limit is the number of items to be returned in one page and the offset is the number of items to skip.

To fetch a page with 50 results and then move to the next page:

import ComicVine from 'comic-vine-sdk';
const comicVine = new ComicVine('your-api-key-here');

(async () => {
  try {
    const limit: 50;
    const filter: { name: 'The Boys' },

    // Retrieve the first 50 issues of The Boys (Page 1)
    const issuesPage1 = await comicVine.issue.list({ limit, filter });
    console.log(`Total issues: ${issuesPage1.data.length}`);
    console.log(issuesPage1.data.map(issue => issue.name).join(', '));

    // Retrieve the next 50 issues of The Boys (Page 2)
    const issuesPage2 = await comicVine.issue.list({ limit, filter, offset: 50 });
    console.log(`Total issues: ${issuesPage2.data.length}`);
    console.log(issuesPage2.data.map(issue => issue.name).join(', '));
  } catch (error) {
    console.error(error);
  }
})();

Auto Pagination

This feature allows calling any list method on a resource with for await...of rather than having to track the offset for making subsequent requests.

It will make the first request and return an item from that response on each iteration, when there are no more items to return it will automatically fetch the next page from the API. This will continue until all pages have been retrieved.

import ComicVine from 'comic-vine-sdk';
const comicVine = new ComicVine('your-api-key-here');

(async () => {
  try {
    const listOptions = {
      filter: { name: 'The Boys' },
      limit: 50,
    };

    let issueNames = [];
    for await (const issue of comicVine.issue.list(listOptions)) {
      issueName.push(issue.name);
    }

    console.log(`Total issues: ${issueNames.length}`);
    console.log(issueNames);
  } catch (error) {
    console.error(error);
  }
})();

Run Locally

Clone the project

  git clone https://github.com/AllyMurray/comic-vine.git

Go to the project directory

  cd comic-vine

Install dependencies

  npm install

Run the tests

  npm run test

Authors