Skip to content

nexensys/scratch3-api

Repository files navigation

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 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