fowled / scratchlib

A library to interact with the Scratch API 🚀

Scratchlib

A powerful library to interact with the Scratch API 🚀

Table of contents

• About
• Installation
  • Via NPM
• How to use
• Documentation
  • Methods
  • TypeScript
  • Web
  • CORS
• Contributing
• Help

About

ScratchLib is a powerful Node.JS module to work with the Scratch API. It provides many methods and properties you never heard of, and does requests for you.

Installation

NPM

Open a terminal, and enter the following command: npm install scratchlib

How to use

Start by requiring the module.

const Scratchlib = require("scratchlib");

🎉 Congrats - you can now access to the many properties this module offers!

Documentation

In order to use a method, you must choose between creating an async function or by adding a callback with .then().

async function():

async function test() {
    try {
	let info = await ScratchLib.getStatus();
	console.log(info);
    } catch (err) {
        console.error(err);
    }
}

test();

.then() callback:

ScratchLib.getStatus().then(info => {
	console.log(info);
}).catch(err => {
	console.error(err);
});

Both equals to:

{
  version: '1d96065a1ea1d017949e2bd8e179762744d231f0',
  uptime: 1013664,
  load: [ 0.1611328125, 0.134765625, 0.09619140625 ],
  sql: { ssl: true, min: 0, max: 40 },
  cache: { connected: true, ready: true }
}

⚠️ Don't forget to catch the promise.

ScratchLib.getUserFollowers().then(info => {
	console.log(info);
}).catch(err => {
	console.error(err);
});

Output: Parameter of type string is missing!

Methods

• getFeatured() - Returns information regarding the projects currently visible on the front page of the website.
• getNews() - Returns information regarding the "Scratch News" section of the homepage.
• getProfile(username: string) - Returns information about the specified user.
• getProject(id: string) - Returns information relevant to the given project.
• getProjectsCount() - Returns the total number of shared projects on the Scratch website.
• getRoot() - The root of the api interface provides basic information regarding the API and the Scratch website.
• getStatus() - Used to return the status of the Scratch website. (really? :P)
• getUserFavorites(username: string) - Returns an array of details regarding the projects that a given user has favourited on the website.
• getUserFollowers(username: string) - Returns a list of a user's most recent followers.
• getUserFollowing(username: string) - Returns a list of the users that the specified user has most recently followed.
• getUserMessages(username: string) - This returns the number of unread messages a user currently has.
• getUserProjects(username: string) - Returns an array with information regarding the projects that a given user has shared on the Scratch website.

⚠️ The following methods are returning JSON data.

TypeScript

💡 This module can be used with TypeScript! It even provides quality types that can be auto-completed from Visual Studio Code, or any editor that supports IntelliSense/autocompletion.

Web

🌐 This library can also be used on the Web! You'll need help from browserify though.

CORS

If you use this module in the browser, you'll probably encounter a problem: CORS, which means 'Cross-origin resource sharing'.
Thanks to @locness3 (#3), this library now supports proxies.
You just have to specify a parameter, which must be equal to your proxy URL as follows: http://host:port.

ScratchLib.getFeatured("http://localhost:8080").then(info => {
	console.log(info);
}).catch(err => {
	console.error(err);
});

Contributing

You can contribute to this project by doing a PR ❤️

Help

Do you need help? Create an issue!

scratchlib's Issues

Allow setting a URL prefix

Add an option for a URL prefix to be used in the request URLs, because CORS proxies.

Browser support

Allow using this in the browser ;)