This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.

Some API methods also support authenticating on a per-application level.
This is useful for getting data that are not directly related to a specific
Twitter user, but generic to the Twitter ecosystem (such as search/tweets).

To obtain an app-only bearer token, call the appropriate API:

cb.__call(

"oauth2_token",

{},

function(reply){

var bearer_token = reply.access_token;

}

);

I strongly recommend that you store the obtained bearer token in your database.
There is no need to re-obtain the token with each page load, as it becomes invalid
only when you call the oauth2/invalidate_token method.

If you already have your token, tell Codebird to use it:

cb.setBearerToken("YOURBEARERTOKEN");

In this case, you don't need to set the consumer key and secret.
For sending an API request with app-only auth, see the ‘Usage examples’ section.

Normally, browsers only allow requests being sent to addresses that are on
the same base domain. This is a security feature called the “same-origin
policy.” However, this policy is in your way when you try to access the
(remote) Twitter API domain and its methods.

With Codebird, don’t worry about this. We automatically send cross-domain
requests using a secured proxy that sends back the required headers to the
user’s browser.

This CORS proxy is using an encrypted SSL connection.
We do not record data sent to or from the Twitter API.
Using Codebird’s CORS proxy is subject to the Acceptable use policy.

If your JavaScript environment is not restricted under the same-origin policy
(for example in node.js), direct connections to the Twitter API are established
automatically, instead of contacting the CORS proxy.

When the user returns from the authentication screen, you need to trade
the obtained request token for an access token, using the OAuth verifier.
As discussed in the section ‘Usage example,’ you use a call to
oauth/access_token to do that.

The API reply to this method call tells you details about the user that just logged in.
These details contain the user ID and the screen name.

Take a look at the returned data as follows:

{

oauth_token:"14648265-rPn8EJwfB**********************",

oauth_token_secret:"agvf3L3**************************",

user_id:14648265,

screen_name:"jublonet",

httpstatus:200

}

If you need to get more details, such as the user’s latest tweet,
you should fetch the complete User Entity. The simplest way to get the
user entity of the currently authenticated user is to use the
account/verify_credentials API method. In Codebird, it works like this:

cb.__call(

"account_verifyCredentials",

{},

function(reply){

console.log(reply);

}

);

I suggest to cache the User Entity after obtaining it, as the
account/verify_credentials method is rate-limited by 15 calls per 15 minutes.

The Twitter REST API utilizes a technique called ‘cursoring’ to paginate
large result sets. Cursoring separates results into pages of no more than
5000 results at a time, and provides a means to move backwards and
forwards through these pages.

Here is how you can walk through cursored results with Codebird.

Get the first result set of a cursored method:

cb.__call(

"followers_list",

{},

function(result1){

// ...

}

);

To navigate forth, take the next_cursor_str:

var nextCursor = result1.next_cursor_str;

If nextCursor is not 0, use this cursor to request the next result page:

if(nextCursor >0){

cb.__call(

"followers_list",

{cursor: nextCursor},

function(result2){

// ...

}

);

}

To navigate back instead of forth, use the field resultX.previous_cursor_str
instead of next_cursor_str.

It might make sense to use the cursors in a loop. Watch out, though,
not to send more than the allowed number of requests to followers/list
per rate-limit timeframe, or else you will hit your rate-limit.

Codebird supports xAuth just like every other authentication used at Twitter.
Remember that your application needs to be whitelisted to be able to use xAuth.

Here’s an example:

cb.__call(

"oauth_accessToken",

{

"x_auth_username":"username",

"x_auth_password":"4h3_p4$$w0rd",

"x_auth_mode":"client_auth"

},

function(reply){

console.log(reply);

// ...

}

);

If everything went fine, you will get an object like this:

{

"oauth_token":"14648265-ABLfBFlE*********************************",

"oauth_token_secret":"9yTBY3pEfj*********************************",

"user_id":"14648265",

"screen_name":"jublonet",

"x_auth_expires":"0",

"httpstatus":200

}

Are you getting a strange error message, an empty error, or status "0"?
If the user is enrolled in login verification, the server will return a
HTTP 401 error with a custom body (that may be filtered by your browser).

Besides the well-documented official methods, the Twitter API also contains
undocumented additional methods. They are used by official Twitter clients,
such as Twitter for iPhone and Twitter for Mac.

Access to these methods is restricted: Only white-listed applications
(consumer keys) may access undocumented methods. Codebird supports accessing
internal methods, but that will only work if you provide a white-listed API key.
By reason, the API keys and secrets for official Twitter clients are not
provided within this package, since they should have been kept a secret.

If you provide Codebird with the Twitter for iPhone consumer key and secret,
the following example will get the latest events that happened with you: