twt.js

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: '[e-mail]',
});

// 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.