scratch-api

A utility for interacting with the Scratch 2.0 website.

Installation

Install with npm:

npm install scratch-api

Or by cloning this repository:

git clone https://github.com/trumank/scratch-api.git

Examples

Sets the user's backpack to a single script.

var Scratch = require('scratch-api');
Scratch.UserSession.load(function(err, user) {
  if (err) return console.error(err);
  user.setBackpack([{
    type: 'script',
    name: '',
    scripts: [[['say:', 'Cheers!']]]
  }],
  function(err, res) {
    if (err) return console.error(err);
    console.log('Backpack set');
  });
});

Prints all of the cloud variables for the given project.

var Scratch = require('scratch-api');

Scratch.UserSession.load(function(err, user) {
  user.cloudSession(<project>, function(err, cloud) {
    cloud.on('set', function(name, value) {
      console.log(name, value);
    });
  });
});

See Also

This scratch-api module is setup to be easily added too and extended. If you need to make certain requests that are not present it should be easy to add them. The Scratch Wiki has some pretty extensive documentation.

If you are feeling Pythonic today, check out Dylan Beswick's very similar module for Python.

API

Scratch

• getProject
• getProjects

Scratch.UserSession

• static create
• static prompt
• static load
• verify
• getProject
• setProject
• getProjects
• getAllProjects
• getBackpack
• setBackpack
• addComment
• cloudSession

Scratch.CloudSession

• end
• get
• set
• variables
• Event: set
• Event: end

Scratch

static getProject(projectId, callback)

Retrieves a JSON object of the given Scratch project.

• projectId - The project's ID.
• callback(err, project)

static getProjects(username, callback)

Retrieves a list of all public projects belonging to given user.

• username - Username of owner
• callback(err, projects)

UserSession

static create(username, password, callback)

Creates a new Scratch session by signing in with the given username and password.

• username - The Scratch account username (not case sensitive).
• password - The Scratch account password.
• callback(err, user)

static prompt(callback)

Creates a new Scratch session by prompting for the username and password via the command line.

• callback(err, user)

static load(callback)

Attempts to create a user from a saved .scratchSession file. If one is not found, prompt is used instead and a .scratchSession file is created.

• callback(err, user)

verify(callback)

Verifies that the user session is fresh and is ready to be used.

• callback(err, valid)

getProject(projectId, callback) - alias getProject

setProject(projectId, payload, callback)

Uploads the given payload object or string to the project with the given ID. The user must own the given project or the request will fail.

• projectId - The project's ID.
• payload - A JSON object or string. If it is an object, it will be stringified before sent.
• callback(err)

getProjects(callback) - alias getProjects

getAllProject(callback)

Gets a list of all projects (shared and unshared) belonging to the user.

Note: This does not share the same format as getProjects as it uses the internal API.

• callback(err, projects)

getBackpack(callback)

Retrieves the signed in user's backpack as a JSON object.

• callback(err, payload)

setBackpack(payload, callback)

Uploads the given payload to the user's backpack.

• payload - A JSON object or a string to be uploaded.
• callback(err)

addComment(options, callback)

Comments on a project, profile, or studio.

• options - A JSON object containing options.
  • project, user, or studio: The function checks (in that order) for these values. The user must be a username to post to, and all others must be ids.
  • parent: The comment id to reply to. Optional.
  • replyto: The user id to address (@username ...). Optional.
  • content: The text of the comment to post.
• callback(err)

cloudSession(projectId, callback)

Connects to a cloud variable session for the given project.

• projectId - The project's ID.
• callback(err, cloudSession)

Scratch.CloudSession

end()

Used to disconnect from the server and end the cloud session.

get(name)

Returns the value of a cloud variable or undefined if it does not exist.

• name - The variable name including the cloud (☁) symbol.

set(name, value)

Sets the variable with the given name to the given value.

• name - The variable name including the cloud (☁) symbol.
• value - A new value.

variables

An object used as a hash table for all cloud variables. Variables can both read set directly via this object or through the corresponding get and set methods.

Event: 'set'

Emitted when a cloud variable is changed.

• name - The variable name.
• value - The variables new value.

Event: 'end'

Emitted when the server closes the connection (should never happen unless the client breaks).