questionit
v1.1.2
Published
Use the QuestionIt.space API with this simple client inspirated by [twitter-lite](https://www.npmjs.com/package/twitter-lite).
Downloads
21
Readme
QuestionIt.space official client
Use the QuestionIt.space API with this simple client inspirated by twitter-lite.
This is a WIP. It should be completed later.
Getting started
You can use this package both in browser and Node.js.
Install it through NPM.
npm i questionit
Basics
See API documentation for endpoint details.
Everytime a link between a type bundled in this package and API return type is available, it will be presented into API docs.
Requesting the API
First, instantiate the default export of this package.
import QuestionIt from 'questionit';
// Instantiate the default export without any argument.
const questionit = new QuestionIt;
After, use an object method corresponding to desired HTTP method.
questionit.get(endpoint, options);
questionit.post(endpoint, options);
questionit.put(endpoint, options);
// ...
Endpoint parameter is the remaining part after https://api.questionit.space/
URL.
For example, for endpoint https://api.questionit.space/users/find
, parameter should be users/find
.
Second parameter is options. Options are params
(query or body), specific headers
, custom (or disabled) auth
token, and with_rq
option that allow returning the standard Response
object beside the API JSON response.
interface QuestionItRequestParams {
/** Specify here your query URL params or body content */
params?: URLSearchParams | Record<string, string | number | boolean> | FormData;
/** Useful if you want to set custom headers */
headers?: Record<string, string> | Headers;
/** Enable/disable auth (boolean), or force a specific Bearer token (string) */
auth?: boolean | string;
/** Enable return Response beside API response object */
with_rq?: boolean;
}
Make an unauthentificated request
import { SentUser } from 'questionit';
const user: SentUser = await questionit.get('users/id/1');
console.log(`This is user ${user.name}, @${user.slug}, whose created his account on ${user.created_at}.`);
Make an authentificated request
This kind of request requires an access token. If you don't have it yet, jump to Authentification part.
You can specify your token inside QuestionIt
constructor
const questionit = new QuestionIt('some-token-here');
or just use setAccessToken()
method.
questionit.setAccessToken('some-token-here');
Token will be automatically added to request headers.
import { SentRelationship } from 'questionit';
const relationship: SentRelationship = await questionit.get('relationships/with/2');
console.log(`You ${relationship.following ? 'follow' : 'do not follow'} user #2`);
Authentification
You can generate login tokens and get access token through this library.
Get a request token
A request token is used to ask user to connect to your app.
const token = await questionit.getRequestToken(
'app-key-here',
'redirect-url-after-confirm-or-deny' // or 'oob' for no redirection
);
const token_encoded = encodeURIComponent(token);
const url = 'https://questionit.space/appflow?token=' + token_encoded;
// Send user to {url} !
Get access token
Once user has approved the app, he will be redirected to your redirect URL (or will have an access PIN displayed).
For redirect URLs, there's formed like:
https://yoursite.com/callback?validator={validator}
.
You can extract validator
from query string, they're needed to generate access token.
import { AccessTokenResult } from 'questionit';
const result: AccessTokenResult = await questionit.getAccessToken(
'app-key-here',
// You need to have original token, it should be stored somewhere on your side.
// You can give an unique key into callback URL (like in query),
// it will be keeped.
'token-here',
'validator-or-PIN-here'
);
console.log(`Access token is ${result.token}.`);
You can now use this token with the instance.
questionit.setAccessToken(result.token);
Errors
When a non-success HTTP status code is given, the request will end in a rejected promise.
The rejected promise contain the following interface:
interface WrappedApiError {
type: 'QuestionItApiError';
response: Response;
result: QuestionItApiError;
}
try {
const res = await client.get('users');
} catch (e) {
if (QuestionIt.isApiError(e)) {
console.log(e.result);
}
}
Endpoint-based methods
This Python library binds most of the endpoints of the API to specific methods, so you don't need to handle boring things by yourself. Their usage is pretty straight-forward and don't need to be explained (the method parameters are usually whats API is taking), except for a few methods (see below).
The following methods exists:
.verifyToken
->GET auth/token/verify
.revokeToken
->DELETE auth/token
.findUsers
->GET users/find
.getUser
->GET users/id/:id
andGET users/slug/:slug
.getLogged
->GET users/logged
.setPinned
->PATCH questions/pin
.removePinned
->DELETE questions/pin
.setMutedWords
->POST users/blocked_words
.getMutedWords
->GET users/blocked_words
.ask
->POST questions
,POST questions/anonymous
andPOST polls
.waitingQuestions
->GET questions/waiting
.reply
->POST questions/answer
.removeQuestion
->DELETE questions
.removeMutedQuestions
->DELETE questions/masked
.like
->POST likes
.unlike
->DELETE likes
.likersOf
->GET likes/list/:id
.likersIdsOf
->GET likes/ids/:id
.questionsOf
->GET questions
.askedQuestionsOf
->GET questions/sent
.homeTimeline
->GET questions/timeline
.ancestorsOf
->GET questions/tree/:root
.repliesOf
->GET questions/replies/:id
.relationshipWith
->GET relationships/with/:id
.relationshipBetween
->GET relationships/between
.follow
->POST relationships/:id
.unfollow
->DELETE relationships/:id
.followers
->GET relationships/followers
.followings
->GET relationships/followings
.block
->POST blocks/:id
.unblock
->DELETE blocks/:id
.getNotifications
->GET notifications
.removeNotification
->DELETE notifications/:id
.getNotificationCount
->GET notifications/count
.notificationsAllMarkAsSeen
->POST notifications/bulk_seen
.getUser
This method can fetch an user by user ID or by slug.
It automatically choose between ID and slug regarding the given string ; if it's numeric, ID endpoint will be used.
client.getUser('2'); # calls users/id/2
client.getUser('questionitspace'); # calls users/slug/questionitspace
.ask
You can attach multiple choices "polls" directly with this method.
Just give a simple list of strings in the poll
parameter.
client.ask('Cat or dog?', '2', true, '36', ['Cats!!', 'Dogs :(']);
.reply
When you reply to a question, you can attach medias (JPEG, PNG and GIF images).
You must attach the picture in the picture
parameter of .reply
by following this example:
import fs from 'fs';
const path = 'path-to-file.ext';
client.reply(
'Yes, cats are the best.',
'32',
false,
fs.createReadStream(path),
);