Scpper.js

NodeJS API wrapper for ScpperDB API

What the fuck is this ?

The SCP Foundation is a fictional organization that is the subject of a web-based collaborative writing project of the same name. The stories generated by the project describe the exploits of the Foundation, supposedly responsible for containing individuals, entities, locations, and objects that violate natural law (referred to as SCPs).

This module has been built to communicate and retrieve information from the Scpper project, which is the centralization of data and page's statistics From all branches of the Foundation.

Documentation

Create an instance of Scpper

You create an instance of Scpper by calling new Scpper() and passing in a configuration object

const api = new Scpper({ site: 'en' })

You must pass a valid abbreviation to "site" otherwise, an exception will be throw. Scpper class also accepts as property limit, which defines how many items the API should return for queries, and baseUrl if you want to use your own Scpper installation.

The Scpper class also accepts as second parameter an Axios configuration object(optional).

Calling the Scpper API

You can now call it like this:

api.getPage('1956234')
api.getUser('966960')

getPage and getUser accept 1 parameter:

id - string - the id of the requested ressource, wikidot user ID or user page ID (required)

api.findPages('scp-002')

findPages accept 2 parameters:

search - the name of the page you are looking for in ScpperDB (required)

options - Object (optional)

• site - Overwrite site property for this request (optional)
• limit - Overwrite limit property for this request (optional)
• random - boolean - indicating whether resulting list of pages should be randomized (optional)

api.findUsers('Anqxyr')

findUsers accept 2 parameters:

search - the name of the user you are looking for in ScpperDB (required)

options - Object (optional)

• site - Overwrite site property for this request (optional)
• limit - Overwrite limit property for this request (optional)

api.findTag('+keter')
// or
api.findTag(['-keter', '+euclide'])

tag - string or array - the tag search you want to perform (required)

options - Object (optional)

• site - Overwrite site property for this request (optional)
• limit - Overwrite limit property for this request (optional)
• method - ("and"|"or") - How to combine provided tags for the query (optional)
• random - boolean - indicating whether resulting list of pages should be randomized (optional)

The list of tags (array) must be prefixed with "+" or "-" "+" indicates that pages containing this tag must be included in the query "-" indicates that pages containing this tag must be excluded from the query Each tag MUST be prefixed by only ONE of those options.

You can also change "site" property, which is the abbreviation of the site whose data you want to use with a valid initial, otherwise, it will throw an error.

api.site = 'fr'

api.site = 'ca'
// Error: ca is not a valid wiki site

Response

The responses are promise-based, so you you'll need to handle things in a .then() function or await if you use ES7.

api
  .findPages('173')
  .then(i => console.log(i))
  .catch(console.log)

// or if you are more ES7

try {
  const result = await api.findPages('173')
  console.log(result.data)
} catch (err) {
  // See constant below
  console.log(err)
}

To see in detail what each method returns, see this page.

The promised is resolved if no error has occurred (see below).

Constant        VALUE               Status Code   Explanation
----------------------------------------------------------------------------------------
NONE             null               200-299       No problems. The promise is resolved.
CLIENT_ERROR     'CLIENT_ERROR'     400-499       Any non-specific 400 series error.
SERVER_ERROR     'SERVER_ERROR'     500-599       Any 500 series error.
TIMEOUT_ERROR    'TIMEOUT_ERROR'    ---           Server didn't respond in time.
CONNECTION_ERROR 'CONNECTION_ERROR' ---           Server not available, bad dns.
NETWORK_ERROR    'NETWORK_ERROR'    ---           Network not available.
CANCEL_ERROR     'CANCEL_ERROR'     ---           Request has been cancelled. Only possible if `cancelToken` is provided in config, see axios `Cancellation`.

A response will always have these 2 properties:

ok      - Boolean - True is the status code is in the 200's; false otherwise.
problem - String  - One of 6 different values (see problem codes)

If the response don't have ok true, the promise will be rejected.

If the request made it to the server and got a response of any kind, response will also have these properties:

data     - Object - this is probably the thing you're after, with the response of the Scpper.
status   - Number - the HTTP response code
headers  - Object - the HTTP response headers
config   - Object - the `axios` config object used to make the request
duration - Number - the number of milliseconds it took to run this request

From api-sauce

---

List of available sites (API names in quotes) from ScpperDB:

• SCP Foundation: "en"
• Russian branch: "ru"
• Korean branch: "ko"
• Japanese branch: "ja"
• French branch: "fr"
• Spanish branch: "es"
• Thai branch: "th"
• Polish branch: "pl"
• German branch: "de"
• Chinese branch: "cn"
• Italian branch: "it"
• International Archive: "int"

SCP Foundation and all related works were created by SCP creative community and are available under CC BY-SA 3.0 license.

Thanks

Thanks to FiftyNine for the API and for his infinite patience during our exchanges !

Thanks also to all my friends of the french Foundation branch, and for the unconditional love of Boule De Neige <3