scratch3-api

Now Supporting Turbowarp!

A remake of trumank's scratch-api optimized for scratch 3.0. It not only adds to the api, but is also composed mostly of promises to prevent callback hell. So, instead of

const Scratch = require("scratch-api");

Scratch.UserSession.create("<username>", "<password>", function (err, user) {
  user.cloudSession("<project>", function (err, cloud) {
    cloud.on("set", function (name, value) {
      console.log(`${name} was set to ${value}`);
    });
  });
});

you can do

const Scratch = require("scratch3-api");

async function main() {
  let session = await Scratch.UserSession.create("<username>", "<password>");
  let cloud = await session.cloudSession("<project>");
  cloud.on("set", function (name, value) {
    console.log(`${name} was set to ${value}`);
  });
}

main();

which is a lot easier to read. If, for some reason, you like callback hell, you can just use .then().

const Scratch = require("scratch3-api");

Scratch.UserSession.create("<username>", "<password>").then(function (session) {
  session.cloudSession("<project>").then(function (cloud) {
    cloud.on("set", function (name, value) {
      console.log(`${name} was set to ${value}`);
    });
  });
});

Installation

Requires Node.js >= 10

Install with npm:

npm install scratch3-api

Or yarn:

yarn add scratch3-api

Or by cloning this repository:

git clone https://github.com/ErrorGamer2000/scratch3-api.git

Adding to your script

CommonJS

const Scratch = require("scratch3-api");
// or
const { UserSession, CloudSession, Projects, Rest } = require("scratch3-api");

ESM

import Scratch from "scratch3-api";
// or
import { UserSession, CloudSession, Projects, Rest } from "scratch3-api";

API Documentation

• UserSession
• CloudSession
• Projects
• Rest
• Other APIs
  • Project
  • Sprite
• Credits

UserSession API

The UserSession api handles the login and verification that makes the package to work. (Stored in the session variable for examples)

Methods

---

Static Methods

• create(username?: string, password?: string): Promise<UserSession>

  • Creates and loads a new UserSession with the given username and password.
  • username - The Scratch account username (not case sensitive). Optional. If not provided user will be prompted.
  • password - The Scratch account password. Optional. If not provided user will be prompted.

  let session = await Scratch.UserSession.create("<username>", "<password>");
  
  //Could also be done with
  let session = new Scratch.UserSession();
  await session.load("<username>", "<password>");

• constructor(): Usersession

  • Creates a blank, unloaded UserSession.

  let session = new Scratch.UserSession();

Instance Methods

• load(username?: string, password?: string): Promise<void>

  • Loads the UserSession instance with the given name and password.
  • username - The Scratch account username (not case sensitive). Optional. If not provided user will be prompted.
  • password - The Scratch account password.

  await session.load("<username", "<password>");

• prompt(): Promise<void>

  ⚠ Deprecated! This feature will be removed soon. Please use <UserSession>.load without parameters instead.

  • Prompts the user for their username and password then loads the UserSession.

  await session.prompt();

• verify(): Promise<boolean>

  • Validates the UserSession's login.

  const valid = await session.verify();

• comment(options: { [key: string]: string }): Promise<void>

  • Validates the UserSession's login.
  • options
    • project, user, or studio - The project, user, or studio to comment on. User must be a username and the 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.

  await session.comment({
    project: 517845853,
    content: "Commented from Node.js with scratch3-api!"
  });

• cloudSession(proj: number | string, turbowarp: boolean = false): Promise<CloudSession>

  • Create a new CloudSession for the given project with the current UserSession and connects it. - proj - The id of the project to connect to. Can be a string or number. - turbowarp - Whether or not to connect to the turbowarp cloud servers instead of the scratch

  let cloud = await session.cloudSession(60917032);

Instance Properties

• get projects: Projects - Returns a new instance of the Projects api.
• loaded: boolean - Whether or not the session has been loaded with a username and password.
• valid: boolean - Whether or not the session is valid.
• username: string | undefined - The username that the session was loaded with. Will not be defined if the load() method has not been called.
• password: string | undefined - The password that the session was loaded with. Will not be defined if the load() method has not been called.
• id: string | number - The user's id number.
• sessionId: string - The scratch session id that the user is currently logged in with.
• token: string - The session's scratch token.

CloudSession API

Extends: EventEmitter

Methods

---

Static Methods

• create(user: UserSession, proj: string | number, turbowarp: boolean = false): Promise<CloudSession>

  • Creates and loads a new CloudSession for the given project using the given UserSession.
  • user - The UserSession to create the CloudSession with. If an invalid UserSession is provided, things may break.
  • proj - The id of the project to connect to. Can be a string or number.
  • turbowarp - Whether or not to connect to the turbowarp cloud servers instead of the scratch cloud servers.

  let cloud = Scratch.CloudSession.create(session, 60917032);

• constructor(user: UserSession, proj: string | number, turbowarp: boolean = false): CloudSession

  • Creates a new CloudSession for the given project using the given UserSession.
  • user - The UserSession to create the CloudSession with. If an invalid UserSession is provided, things may break.
  • proj - The id of the project to connect to. Can be a string or number.
  • turbowarp - Whether or not to connect to the turbowarp cloud servers instead of the scratch cloud servers.

  let cloud = new Scratch.CloudSession(session, 60917032);

Instance Methods

• connect(): Promise<void>

  • Connects the CloudSession to the cloud servers.

  await cloud.connect();

• end(): void

  • Ends the connection with the cloud servers.

  cloud.end();

• get(name: string): number | string

  • Get the value of a cloud variable with the given name (including the ☁).
  • name - The name of the variable to retrieve the value of (including the ☁, see name(n)).

  let value = cloud.get("☁ variable");

• set(name: string, value: number | string): void

  • Set the cloud variable with the given name to the given value.
  • name - The name of the variable to set.
  • value - A number to set the cloud variable to.

  cloud.set("☁ variable", 1);

• name(n: string): string

  • Add the cloud symbol to the given variable name.
  • n - A name to add the cloud symbol to.

  let value = cloud.get(cloud.name("variable"));
  //☁ variable

• numerify(str: string): string

  • Turn a string into a series of numbers for transmission over the cloud servers.
  • string - The text to convert. Characters not included in the defined set will not be included.

  cloud.set(cloud.name("variable"), cloud.numerify("value"));

• stringify(number: string | number, startLetter: number = 0): string

  • Decode a string from a number generated by the numerify function.
  • number - A string or number containing the value to decode.
  • startLetter - The letter of the input number to start the decoding from.

  let decoded = cloud.stringify("321122311500", 0);

Instance Properties

• variables: { [name: string]: string | number } - An object containing the cloud variables that the CloudSession has received and their current values.
• user: UserSession - The UserSession that the CloudSession was created with.
• id: string | number - The id of the project that the CloudSession is connected to.
• usetw: boolean - Whether or not the CloudSession is connected to the Turbowarp servers.

Events

• set- A variable was changed on the cloud servers. Listener parameters: (name: string, value: string | number)
• open/reset - The websocket connection connected or reconnected to the servers.
• addvariable - A variable was set for the first time.

Projects Api

Scratch.Projects

• get(id: string | number): Promise<Project>

  • Fetch the details of the project with the given id.
  • id - The id of the project to fetch.

  let projectInfo = await Scratch.Projects.get(510186917);

• getUserProjects(username: string, limit: number = Infinity): Promise<Project[]>

  • Fetch all projects for the user with the specified username.
  • username - The username of the user to retreive the projects of.
  • limit - a number greater than 0; the number of projects to retreive.

  let userProjects = await Scratch.Projects.getUserProjects(
    "ErrorGamer2000",
    40
  );

UserSession.projects

• get(id: string | number): Promise<Project>

  • Fetch the details of the project with the given id.
  • id - The id of the project to fetch.

  let projectInfo = await session.projects.get(510186917);

• getUserProjects(limit: number = Infinity): Promise<Project[]>

  • Fetch all of the user's owned projects.
  • limit - a number greater than 0; the number of projects to retreive.

  let userProjects = await session.projects.getUserProjects(40);

Rest Api

Rest.Conference

• scheduleForDay(day: string | number, zeroIndex: boolean = true): Promise<{ [key: string]: any }>

  • Fetch the day's schedule from the Scratch Rest api.
  • day - The day of the week to retreive the schedule for.
  • zeroIndex - Whether or not day 1 should me Monday(true) or Tuesday (false);

  let schedule = await Scratch.Rest.scheduleForDay("Monday");

• detailsFor(id: number): Promise<{ [key: string]: any }>

  • Fetch the details for the conference with the given id.
  • id - The id of a Scratch conference.

  let details = await Scratch.Rest.Conference.detailsFor(id);

Rest.Users

• get(username: string): Promise<{ [key: string]: any }>

  • Fetch the details of the user with the given username.
  • username - The username of the user to retreive the details of.

  let user = Scratch.Rest.Users.get("ErrorGamer2000");

• getFollowing(username: string): Promise<{ [key: string]: any }[]>

  • Fetch the list of users that the user with the given username is following.
  • username - The username of the user to fetch the following list of.

  let following = await Scratch.Rest.Users.getFollowing("ErrorGamer2000");

• getFollowers(username: string): Promise<{ [key: string]: any }[]>

  • Fetch the list of users that follow the user with the given username.
  • username - The username of the user to fetch the follower list of.

  let followers = await Scratch.Rest.Users.getFollowers("ErrorGamer2000");

Other Rest Methods

• getHealth(): Promise<{ [key: string]: any }>

  • Retreive the Scratch server's status.

  let status = await Scratch.Rest.getHealth();

• getNews(): Promise<{ [key: string]: any }[]>

  • Retreive the Scratch news.

  let news = await Scratch.Rest.getNews();

Other APIs

Documentation in progress...

---

Contributors

• ErrorGamer2000(Creator);
• GrahamSH-LLK