twt.js v0.0.3
twt.js
Wrapper library for Twtxt.net API written in TypeScript.
Available as Node.js module and a browser library.
Prerequisites
- Server: Node.js 10.x or newer (latest LTS recommended);
- Browser: any web browser that supports Fetch API and Promises. Support for Internet Explorer 11 and below can be achieved with relevant polyfills - see polyfill.io and / or caniuse.com for more information.
Install
npm install twt.js
Manual build
git clone https://github.com/jointwt/twt.js
cd twt.js
npm install
npm run build
Browser module
If you want to use twt.js in a web browser, the quickest way to start is using a pre-built version of Twt.js via unpkg.com:
<script src='https://unpkg.com/twt.js@latest/dist/web/twt.min.js'></script>
Quick start
Instantiate TwtJS
class with URL of the pod you want to work with:
const twt = new TwtJS({
url: 'https://twtxt.net',
});
For endpoints that require authentication, use authenticate
with account credentials to obtain API token.
await twt.authenticate({
username: 'sample_username',
password: 'sample_password',
});
or, if you want to use API token in your application, you can save it as a variable. Note that once you call authenticate
twt.js stores the token and uses it internally for authentication whenever needed.
const token = await twt.authenticate({
username: 'sample_username',
password: 'sample_password',
});
Now you can use all methods available with TwtJS
class:
const data = await twtAPI.getTimeline({ page: 1 });
// do something with data
console.log(data);
Responses
Twt.js always returns JSON objects formatted in the following way:
{
status: 200, // HTTP response code or -1 for non-HTTP / network errors
ok: true // or false
statusText: 'OK' // Response status or error message
data: {} // returned data or empty object if no data is returned from the API
}
Available methods
All methods are asynchronous.
ping()
Requires authentication: no
Tests the liveness of the selected pod.
const data = await twt.ping();
// do something with data
register({ username: string, password: string, email: string })
Requires authentication: no
Creates a new account.
const data = await twt.register({
username: 'foo'
password: 'password',
email: 'email@example.org',
});
// do something with data
authenticate({ username: string, password: string })
Requires authentication: no
Performs API authentication and stores obtained API token in the Twt.js object.
Returns an object containing access token.
const data = await twt.authenticate({
username: 'foo'
password: 'password',
});
// do something with data
post({ text: string, postas: string })
Requires authentication: yes
Posts a new twt.
const data = await twt.post({
text: 'Twt content',
post_as: 'user_or_feed',
});
// do something with data
getTimeline({ page: number })
Requires authentication: yes
Retrieves contents of the currently authenticated user's timeline.
const data = await twt.getTimeline({
page: 1,
});
// do something with data
getDiscover({ page: number })
Requires authentication: no
Retrieves contents of the pod's timeline of all users.
const data = await twt.getDiscover({
page: 1,
});
// do something with data
follow({ page: number })
Requires authentication: yes
Follows a new user or feed.
const data = await twt.follow({
nick: 'foo',
url: 'https://twtxt.net/user/foo/twtxt.txt'
});
// do something with data
More information
- twt.js-example - sample Node server based on Express.js demonstrating all features of twt.js
Contributing
Found a bug? Got a question? Need a new feature? Please file a new issue or submit a pull request. Thanks in advance!
Please see the Contributing Guidelines.
License
Licensed under MIT License. See LICENSE for more information.