enyo/node-tvdb

A node library for thetvdb.com

We have stopped working on this library. Please use the great alternative edwellbrook/node-tvdb instead.

---

TheTVDB.com Node library Version 0.0.13

It's a wrapper for thetvdbs XML API, written in CoffeeScript for node. You won't be in contact with any XML if you use this library.

The library isn't finished yet. I'll update this README as I get along so you'll know what to expect.

You can check out thetvdbs programmers API to know what this library will be wrapping.

This project uses semantic versioning and uses this tag script to tag the versions.

I use the great mocha testing framework with the (also great) should assertion library for testing.
If you contribute to this project, please write a test, and make sure all existing tests pass.

Usage

First off, get an API key from thetvdb. Withouth an API key you won't be able to do anything with this library.

All code samples are presented in both, Javascript and CoffeScript.

Include and configure the library

// JS
var TVDB = require("tvdb")
  , tvdb = new TVDB({ apiKey: "YOUR_KEY" });

# Coffee
TVDB = require("tvdb")
tvdb = new TVDB apiKey: "YOUR_KEY"

Possible configuration options are:

• apiKey {String}
• language {String} (optional) Default: "en". Use getLanguages() if you want another language.
• initialHost {String} (optional) Default: "thetvdb.com"
• port {Number} (optional) Default: 80

Get available languages

// JS
tvdb.getLanguages(function(err, languages) {
  if (err) return;
  // Handle languages.
};

# Coffee
tvdb.getLanguages (err, languages) ->
  if err? then return
  # Handle languages

TVDB uses "en" (english) as default when it fetches data. If you want another language, use this function, get the language you want (or let the user decide which language s/he wants) and use the abbreviation as new language.

To set the language as new default, simply call:

// JS
tvdb.setLanguage(language.abbreviation);

# Coffee
tvdb.setLanguage language.abbreviation

Get a list of mirrors

// JS
tvdb.getMirrors(function(err, mirrors) {
  if (err) return;
  // Handle mirrors.
});

# Coffee
tvdb.getMirrors (err, mirrors) ->
  if err? then return
  # Handle mirrors

Mirrors is an Array containing objects that are formatted like this:

{ id: "1", url: "http://thetvdb.com", types: [ "xml", "banner", "zip" ] }

types contains at least one of "xml", "banner" and "zip".

Get server time

// JS
tvdb.getServerTime(function(err, time) {
  if (err) return;
  // Handle time.
};

// Coffee
tvdb.getServerTime (err, time) ->
  if err? then return
  # Handle time

time is an integer.

Find a TV Show

// JS
tvdb.findTvShow("Mad Men", function(err, tvShows) {
  if (err) return;
  // Handle tvShows.
};

# Coffee
tvdb.findTvShow "Mad Men", (err, tvShows) ->
  if err? then return
  # Handle tvShows

tvShows is an array of tvShow objects which contain following obligatory values:

• id {String}
• language {String}
• name {String}

and following optional values:

• firstAired {Date}
• imdbId {String}
• zap2itId {String}
• banner {String}
• overview {String}

node-tvdb's Issues

Close project in favour of edwellbrook/node-tvdb

Does not work with node v0.7.6

This is probably just a npm issue.

How to get seasons/episodes information?

Hi,

I was checking this out:
http://thetvdb.com/wiki/index.php?title=Programmers_API

Step 4: Get base information for each series
a. Retrieve <mirrorpath_zip>/api/<apikey>/series/<seriesid>/all/<language>.zip and extract <language>.xml and banners.xml.
b. Process the XML data in <language>.xml and store all <Series> data.
c. Download each series banner in banners.xml and prompt the user to see which they want to keep.
Note: Make sure you record <id> from each series, since it's returned in updates as <Series>.

Step 5: Get base information for each episode
a. Use <language>.xml from step 3 to find and store the data associated with your episode.
b. Use <filename> from results in step 5a to download the episode image from <mirrorpath_banners>/banners/<filename>.
Note: Make sure you record <id> from each episode, since it's returned in updates as <Episode>.

Is there any helper methods or something to deal with that part? How am I supposed to get seasons and episodes information using node-tvdb? Any example anywhere I could take a look at?

Thanks!

A couple questions

1. Is https://github.com/enyo/node-tvdb/blob/develop/test.js used anywhere any more?
2. https://github.com/enyo/node-tvdb/blob/develop/CONTRIBUTING.md#coffeescript says you shouldn't commit JS, not sure if I'm misinterpreting and you just mean there shouldn't be any JS only PRs or if no JS should ever be commited (ie you shouldn't compile index.coffee and commit the index.js WITH everything else)?
3. The custom formatting of the fields of episodes and show, shouldn't you pass along all the info? There are some keys you don't format so they don't reach the callback. A good solution might be to have an option to skip formatting or just adding all the keys to the keyMapping object. Could someone clarify why there isn't a formatActor and a formatBanner? Do they not need any formatting, because if they do a more consistent solution might be to separate the formatting into functions like you did with episode and show.
4. Would you accept a PR to add promises as an alternative to callbacks? I'm not sure if it would fit into the module or if it should be up to the user (of the module) to promisify it. But if you do think it might fit into the module itself, it should be rather easy to do.
5. Not a question, more of an observation: the readme needs to be updated in a few places like https://github.com/enyo/node-tvdb/tree/develop#find-a-tv-show the number of optional values has increased and some function don't seem to be listed in the readme at all.

Thank you for your time, please correct me if I'm wrong on anything.

xml2js v0.2 new defaults break module

With xml2js v0.2 new parser defaults were introduced which break the module.

"...
In 0.2 we changed some defaults to parse the XML in a more universal and sane way. So we disabled normalize and trim so xml2js does not cut out any text content. You can reenable this at will of course. A more important change is that we return the root tag in the resulting JavaScript structure via the explicitRoot setting, so you need to access the first element. This is useful for anybody who wants to know what the root node is and preserves more information. The last major change was to enable explicitArray, so everytime it is possible that one might embed more than one sub-tag into a tag, xml2js >= 0.2 returns an array even if the array just includes one element. This is useful when dealing with APIs that return variable amounts of subtags.
..."

see https://github.com/Leonidas-from-XIV/node-xml2js

This can easily be fixed by setting the options explicitly in the xmlParser member:

    xmlParser = new (require("xml2js")).Parser({
        trim:true,  // Remove whitespaces
        normalize:true, // Remove whitespaces
        explicitArray:false, // do not parse all fields to an array
        explicitRoot:false // we do not need the root element
    });

Encoding issues for getInfo and language french

When I try the getInfo function with the lang param at "fr", I get encoding issues.
Example: for id 72546, I get:

{
  "tvShow": {
    "id": "72546",
    "genre": "|Crime|Drama|",
    "language": "fr",
    "name": "Les Experts",
    "firstAired": "2000-10-06T00:00:00.000Z",
    "imdbId": "tt0247082",
    "zap2itId": "EP00380341",
    "banner": "graphical/72546-g13.jpg",
    "overview": "Gil Grissom et toute son  équipe de brillants enquêteurs nous emmène au cœur des rues et des alentours de la ville du péché LAS VEGAS, en quête de vérité et de justice. Grâce aux nouvelles technologies mais aussi de leurs connaissances et de leur talent d'enquêteurs hors norme, ils élucident les enquêtes les plus difficiles."
  },
  "episodes": [...]
}

I think it comes from the node-zip library.
I'm working on the issue on my own, using adm-zip instead of node-zip, but if you can fix it quickly it would allow me to concentrate my efforts on other things :-)

Adding additional maintainer

@logomaster256 , if you are still working on the project and motivated, I would add you as an admin for the repo. I currently don't have enough time to maintain it, and your changes look great.