Skip to content

Commit

Permalink
readme
Browse files Browse the repository at this point in the history
  • Loading branch information
Michel Legnered committed Feb 14, 2012
1 parent d5650af commit 84ebbb4
Show file tree
Hide file tree
Showing 3 changed files with 54 additions and 115 deletions.
158 changes: 46 additions & 112 deletions README.md
View file
Expand Up @@ -6,15 +6,42 @@ NodeJS module for the Flattr API
Under heavy development. Give me a couple of more days and this one will become
completed.

Status:
flattr.flattrs OK
flattr.things FAIL
flattr.users FAIL
flattr.activities TODO
flattr.categories TODO
flattr.languages TODO

# Get Started

Require the flattr module:
var flattr = require('flattr');


flattr.request_token(code, function (token) {
flattr.users.get_auth(token, function (user_data) {
List an authenticated users flattrs:
// First get your auth code by visiting:
// https://flattr.com/oauth/authorize?response_type=code&client_id=<app_key>
//
var app = {
client_id: '<app_key>',
client_secret: '<app_secret>',
// Must match your apps callback url:
redirect_uri: 'http://localhost:8080/flattr'
};

flattr.request_token(app, code, function (token) {
flattr.flattrs.list_auth(token, function (flattrs_list) {
// do something
});
});

List a users (flattr) three latest flattrs:
flattr.flattrs.list('flattr', {count: 3}, function (flattrs) {
// do something
});

# API

## Flattrs
Expand All @@ -25,93 +52,36 @@ http://developers.flattr.net/api/resources/flattrs/

var flattrs = require('flattr').flattrs;

### flattrs.list(user, [count], [page], callback)
### flattrs.list(user, [obj], callback)

List a users flattrs. `count` default to **30** and tells Flattr number of records
to retrieve, `page` defaults to **1**.
List a users flattrs. `params.count` default to **30** and tells Flattr number of records
to retrieve, `obj.page` defaults to **1**.

flattrs.list('flattr_user', 5, function (data, headers) {
flattrs.list('flattr_user', {count: 5}, function (data) {
console.log(data);
});

### flattrs.list_auth([count], [page], callback)

List the authenticated users flattrs.

### flattrs.thing(id, callback)
### flattrs.list_auth(token, [obj], callback)

Flattr a thing with id of `id`.
List an authenticated users flattrs. `params.count` default to **30** and tells Flattr number of records
to retrieve, `obj.page` defaults to **1**.

flattrs.id(423405, function (data, headers) {
flattrs.list_auth(token, function (data) {
console.log(data);
});

### flattrs.url(url, user, [params], callback)

Flattr an URL. `params` holds an object with optional query parameters for the
auto-submit url.

var params = {
title: 'Optional title',
description: 'Description of your thing',
// https://api.flattr.com/rest/v2/languages.txt
language: 'en_GB',
tags: 'yoga, top10, poses',
// 1 to hide from public listings
hidden: 1,
// https://api.flattr.com/rest/v2/categories.txt
category: 'text'
};

// With or without http/https is accepted.
flattrs.url('womenshealthmag.com/yoga/top-10-yoga-poses-for-men', 'flattr_user', params,
function (data, headers) {
console.log(data);
}
);

## Things

A resource to list, add, update and search for things.

http://developers.flattr.net/api/resources/things/

### flattrs.thing(token, id, callback)

var things = require('flattr').things;

### things.list(user, [count], [page], callback)

List a users things. `count` is the number of records to retrieve, `page` is
page of results.

things.list('flattr', function (data, headers) {
console.log(data);
});

### things.list_auth([count], [page], callback)

List things from the authenticated user.

### things.get(id, callback)

Get a thing.
Flattr a thing with id of `id`.

things.get(423405, function (data, headers) {
flattrs.id(token, 423405, function (data) {
console.log(data);
});

### things.exists(url, callback)

Check if a thing exists by its URL.

things.exists(url, function (data, headers) {
console.log(data);
}):

### things.create(url, [params], callback)
### flattrs.url(token, url, user, [obj], callback)

Create/submit a new thing. Authorization is required.
Flattr an URL. `obj` holds optional query parameters for the auto-submit url.

// Optional parameters
var params = {
title: 'Optional title',
description: 'Description of your thing',
Expand All @@ -125,47 +95,11 @@ Create/submit a new thing. Authorization is required.
};

// With or without http/https is accepted.
things.create('womenshealthmag.com/yoga/top-10-yoga-poses-for-men', params,
function (data, headers) {
flattrs.url(token, 'womenshealthmag.com/yoga/top-10-yoga-poses-for-men', 'flattr_user', params,
function (data) {
console.log(data);
}
);

### things.update(id, [params], callback)

Update a thing. Authorization is required.

things.update(45325, {title: 'Relax man'}, function (data, head) {
console.log(data);
});

### things.del(id, callback)

Deletes a thing. Authorization is required.

things.del(543213, function (data, head) {
console.log(data);
});

### things.search(params, callback)

Search for things. For the `params` argument use one or several of the
following parameters:

* query - string Free text search string
* tags - string Filter by tags, separate with ,
* language - string Filter by language
* category - string Filter by category
* user - string Filter by username
* page - integer The result page to show
* count - integer Number of items per page


things.search({query: 'charity', category: 'trees'}, function (results, head) {
// Results contains search results.
console.log(results);
});


# Licence
Copyright (C) 2012 Humanity
Expand Down
9 changes: 7 additions & 2 deletions flattr.js
View file
Expand Up @@ -137,11 +137,16 @@ function Flattrs () {
});
};

//
// TODO: Check how this one works. What happens if one submits an url
// to flattr without the user_id param?
//
// Flattr an URL
// Params is also available if you auto-submit an url.
//
// token - access token
// url - URL of the thing
// user - user owning the thing
// params (optional) -
// title - Title of your your thing.
// description - Description for your thing.
Expand All @@ -155,7 +160,7 @@ function Flattrs () {
//
// callback - callback function
//
self.url = function (token, url, params, callback) {
self.url = function (token, url, user, params, callback) {

var query_str = '';

Expand All @@ -177,7 +182,7 @@ function Flattrs () {
},

data = {
"url": 'http://flattr.com/submit/auto?url='+
"url": 'http://flattr.com/submit/auto?user_id='+user+'&url='+
encodeURIComponent(checkurl(url))+query_str
};

Expand Down
2 changes: 1 addition & 1 deletion tests/server.js
View file
Expand Up @@ -75,7 +75,7 @@ function runtests(req, res) {
title: 'node-flattr: NodeJS module for the flattr API.',
tags: 'nodejs, module, api, flattr'
};
flattr.flattrs.url(token, 'https://github.com/antics/node-flattr', params, function (data) {
flattr.flattrs.url(token, 'https://github.com/antics/node-flattr', 'antics', params, function (data) {
done(res, {
resource: 'flattrs.url',
message: data.error ? data.error_description : data.description,
Expand Down

0 comments on commit 84ebbb4

Please sign in to comment.