listener-rss/README.md

# listener rss

A lightweight library to make simple actions with a RSS feed.

# USAGE

## Punctual usage

You can parse RSS from a URL with some custom data.  
An example :

```js
const ListenerModule = require("ListenerRSS");
const ListenerRss = ListenerModule.ListenerRss;

const listener = new ListenerRss("my-test-service", "fake.rss.service");

// make a request to the adr 'fake.rss.service'
myListener.fetchRSS().then((obj, err) => {
  // some act
});
```

## Recurrent usage

You can parse RSS from a URL each n times.  
An example :

```js
const ListenerModule = require("ListenerRSS");
const ListenerRss = ListenerModule.ListenerRss;

const listener = new ListenerRss("my-test-service", "fake.rss.service", 5 * 60);

const callback_fun_update = (obj) => {
  // some act
};
const callback_fun_new_entries = (obj) => {
  // some act
};

listener.on("update", callback_fun);
listener.on("newEntries", callback_fun);

listener.start();

/*...*/

listener.stop();
```

# Documentation

## ListenerRSSInfo

An interface to structure listener's data.

### Constructor
- name : the service name
- address : the service address
- [optional] timeloop : time to wait between 2 request in seconds (default 5 minutes)
- [optional] customfields : to notice field who's custom to the service (default blank)
  [cf annexe CustomFields](#customfields)

## ListenerRSS

### Constructor

`constructor(listenerRSSInfo)`

- listenerRSSInfo : object from the ListenerRSSInfo's class.

### fetchRSS()

This function allows to make a request to the rss service.

#### Return

Return a promise object who's resolved like `resolve: (value: result_fetch) => void))` where `result_fetch` is a json
object who's contain the data. [cf Annexe Output](#output)

#### Issues

Reject the promise if the server can't be resolved.

### start()

This function will call the `update` event to each success update, the 
`update_err` event to each fail update, and the `newEntries` event for
each update who contains a new item.

#### Events

Each event take one arg into the callback function.

```js
const callback_fun = (obj) => {
// some act
};
const callback_fun_err = (err) => {
// some act
};
const callback_fun_new_entries = (newEntries) => {
// some act
};

listener.on("update", callback_fun);
listener.on("update_err", callback_fun_err);
listener.on("newEntries", callback_fun_new_entries);
```

#### update
It used a callback who receive the received object entirely inside an object.
#### update_err
It used a callback who receive an error object.
#### newEntries
It used a callback who receive only new entries inside an array.

### stop()

This function will stop the execution of the callbackFun each time loop.

# Annexe

## CustomFields

This parameter permit to specify some custom fields who's present in the service but not in the RFC.
For example the YouTube RSS api give some data into the `<media:group>` field. So you can give this info with this :

```js
[["media:group", "media:group"]];
```

You can also rename the field with the left part :

```js
[["my_custom_media_group_name", "media:group"]];
```

In adition you can rename child element into custom field like this :

```js
[
  ["media:group", "media:group"],
  ["description", ["media:group", "media:description"]],
  ["icon", ["media:group", "media:thumbnail"]],
];
```

In this case it's useless to specify the parent field, so you can just omit the first line :

```js
[
  ["description", ["media:group", "media:description"]],
  ["icon", ["media:group", "media:thumbnail"]],
];
```

## Output

Here an example of what type of json object is output during a fetch :

```json
{
  "feedUrl": "fake.rrs.service",
  "title": "myFakeApiTitle",
  "description": "My Fake api desc",
  "link": "fake.rrs.service",
  "items": [
    {
      "title": "My last item",
      "link": "fake.rrs.service/item1",
      "pubDate": "Thu, 12 Nov 2015 21:16:39 +0000",
      "creator": "someone",
      "content": "<a href=\"http://example.com\">this is a link</a> &amp; <b>this is bold text</b>",
      "contentSnippet": "this is a link & this is bold text",
      "guid": "fake.rrs.service/item1",
      "categories": [
        "test",
        "npm",
        "fakeInfos",
      ],
      "isoDate": "2015-11-12T21:16:39.000Z"
    },
    /*Some Others items*/
  ]
}
```