Kinsome Collector

Click collector, a part of kinsome project

API

Collector is designed to work in concert with the central Kinsome app.

Kinsome collector API:

GET /api/v1/status

Returns json with current app status and some info. Can be used to determine if collector is alive.

{
    // Perhaps matches key in master DB?
    "id": "c1",
    
    // Collector version
    "version": "0.11.4",
    
    // Uptime in ms 
    "uptime": 16536,
    
    // Current configuration revision
    // If this is null, it means the collector doesn't have configuration and should be configured
    "configurationRevision": 1
}

Perhaps also the size of db, disk space and general health info. TBD

GET /api/v1/configuration

POST /api/v1/configuration

Collector configuration that should be provided by the master.

{
    // An easy way to determine if config has changed
    "revision": 1,

    // All that collector needs to reach master
    "masterUrl": "http://123.12.13.124:12345/test",

    // Where to send clicks for which we don't have a record
    "fallbackUrl": "http://www.kinsome.com/about_us.php"
}

PUT /api/v1/offers/:id

An array of offers that are merged with the existing offers in local DB. Offers are overwritten if already exist.

{
    // Offer id. The active part of the url that is shared. Eg: hhtp://c1.kinsome.com/Xqy
    id: "Xqy",
    
    // Where we redirect clicks after we process them
    "url": "http://www.client.com/offer", 
    
    // How many clicks before we call back
    "credit": 10.0,      
    
    // Module which will handle the link. Can be hardcoded ATM
    "processor": "v1",
    
    // What happens when the credit runs out. If null, we just keep redirecting to the main redirect url 
    "expiredUrl": null,
    //"expiredUrl": "http://www.kinsome.com/expired.php"     
}

DELETE /api/v1/offers/:id

Delete offer from collector DB.

GET /api/v1/offers

If needed, can be used to dump the list of all the offers, for debugging or emergency purposes (TBD)

Kinsome central API that the collector will use:

PATCH /api/v1/offers/:id

Once credit runs out, here is where collector sends the offer object. We don't need to send the entire offer object (bandwidth saving measure). Just the id and credit. Credit COULD go below zero in certain conditions, in which case central should act accordingly (reduce credit for the specified ammount).

    {
        id: "Xqy",
        "credit": 0.0
    }

Installation

1. node.js

The project requires node.js. Naive case:

sudo apt-get install node

Alternatively, local install:

NODE_VERSION="0.10.33"
mkdir -p ~/local/bin
cd ~/local
wget http://nodejs.org/dist/v${NODE_VERSION}/node-v${NODE_VERSION}.tar.gz
tar xvfz node-v${NODE_VERSION}.tar.gz
cd node-v${NODE_VERSION}
./configure --prefix=~/local
make
make install

if ! grep 'export PATH="$HOME/local/bin' ~/.bashrc > /dev/null ; then
    echo 'export PATH="$HOME/local/bin:$PATH"' >> ~/.bashrc
fi

Then restart terminal (or source ~/.bashrc)

Afterwards:

npm install -g mocha

2. redis

TODO

3. C-Code gitlab

Generate ~/.ssh/id_rsa.pub if you don't have it. ssh-keygen -t rsa
Copy the content to clipboard
Go to https://gitlab.c-code.com/ and paste the key under your account there
Add to ~/.ssh/config:

Host gitlab.c-code.com
port 59418
User my.name
Hostname gitlab.c-code.com

4. Project

Create a sutiable directory. Eg:

mkdir -p ~/dev/kinsome/collector
cd ~/dev/kinsome/collector

Download the project

git clone [email protected]:kinsome_collector.git main
cd main

Download dependencies

npm install

Run tests

./test-all.sh

Start the collector

node app.js

panta82/gist:03ab8d2583459b9f6a05