errorgamer2000 / scratch3-api

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

scratch3-api's Issues

Does this project no longer work?

Hello! I noticed this same problem with the og project. I was wondering if the apis no longer works as when I debug the json returns from the requests, I get a "too many requests" or an html file with labels that say too many requests. Big fan of this project tho! If there are any fixes at all, please let me know!

CloudSession doesn't work

I am trying to create a CloudSession, but there is an error talking about this being undefined.
Error:

        this.send("handshake", {});
             ^

TypeError: Cannot read properties of undefined (reading 'send')
    at sendHandshake (D:\Skretchero-tekst\node_modules\scratch3-api\dist\cloudsession.js:127:14)
    at WebSocket.<anonymous> (D:\Skretchero-tekst\node_modules\scratch3-api\dist\cloudsession.js:47:13)
    at WebSocket.emit (node:events:402:35)
    at WebSocket.setSocket (D:\Skretchero-tekst\node_modules\ws\lib\websocket.js:225:10)
    at ClientRequest.<anonymous> (D:\Skretchero-tekst\node_modules\ws\lib\websocket.js:810:15)
    at ClientRequest.emit (node:events:390:28)
    at TLSSocket.socketOnData (node:_http_client:527:11)
    at TLSSocket.emit (node:events:390:28)
    at addChunk (node:internal/streams/readable:315:12)
    at readableAddChunk (node:internal/streams/readable:289:9)

Code:

const Scratch = require('scratch3-api');
const { username, password } = require('./config.json');

async function main() {
	let session = await Scratch.UserSession.create(username, password);
	let cloud = await session.cloudSession(60*****78);
	/*cloud.on('set', (name, value) => {
		console.log(name, value);
	})*/
}

main();

Add Support For Getting Messages

I feel like the title is self explanatory, please add support for getting messages starting at an index, and you can pass in a length, and return an array of messages. Not just unread messages, all messages.

Babel deps

AFAIK, all of the babel deps should be in devDependencies

Updated TurboWarp cloud variable guidelines

Hello, I have put some updated guidelines for TurboWarp cloud variable bot developers over here: https://docs.turbowarp.org/cloud-variables#advanced

Most notably we would like cloud variable libraries and bots to each be setting a unique User-Agent header. I don't know enough about your library to know how many of those guidelines will affect you.