# scratch-api > An API to interact with the Scratch 2.0 website Latest version **1.1.12** (published 2021-06-23) · MIT license · 0 weekly downloads ## Install ```sh npm install scratch-api pnpm add scratch-api yarn add scratch-api bun add scratch-api ``` ## Health **Score 20/100 (F)** — status: abandoned. Positive: has types; no vulnerabilities. Warnings: low downloads; no esm support. Negative: abandoned; low maintenance score. ## Facts | | | |---|---| | Version | 1.1.12 | | Published | 2021-06-23 | | First published | 2015-04-23 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | bundled | | Module format | CommonJS | | Dependencies | 2 | | Unpacked size | 27.2 KB | | Known vulnerabilities | 0 | | Install scripts | no | | GitHub stars | 95 | | Author | Truman Kilen | | Maintainers | trumank | ## Links - npm: https://www.npmjs.com/package/scratch-api - Repository: https://github.com/trumank/scratch-api - Issues: https://github.com/trumank/scratch-api/issues - npm.io page: https://npm.io/package/scratch-api ## Dependencies (2) - [ws](https://npm.io/package/ws.md) ^7.0.1 - [prompt](https://npm.io/package/prompt.md) ^1.1.0 ## Recent versions - 1.1.12 (latest) — 2021-06-23 - 1.1.11 — 2019-12-01 - 1.1.10 — 2019-12-01 - 1.1.9 — 2019-06-30 - 1.1.8 — 2017-11-10 - 1.1.7 — 2017-09-12 - 1.1.6 — 2017-02-04 - 1.1.5 — 2016-04-30 - 1.1.4 — 2016-04-29 - 1.1.3 — 2016-04-07 - 1.1.2 — 2015-12-22 - 1.1.1 — 2015-12-22 - 1.1.0 — 2015-10-30 - 1.0.3 — 2015-07-28 - 1.0.0 — 2015-04-23 ## README # scratch-api A utility for interacting with the Scratch 2.0 website. ## Installation Install with npm: ```sh npm install scratch-api ``` Or by cloning this repository: ```sh git clone https://github.com/trumank/scratch-api.git ``` ## Examples Sets the user's backpack to a single script. ```javascript 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. ```javascript var Scratch = require('scratch-api'); Scratch.UserSession.load(function(err, user) { user.cloudSession(, 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](http://wiki.scratch.mit.edu/wiki/Scratch_API_(2.0)) has some pretty extensive documentation. If you are feeling Pythonic today, check out Dylan Beswick's very similar [module for Python](https://github.com/Dylan5797/scratchapi). ## API ### Scratch * [`getProject`](#getProject) * [`getProjects`](#getProjects) ### Scratch.UserSession * [`static create`](#UserSession.create) * [`static prompt`](#UserSession.prompt) * [`static load`](#UserSession.load) * [`verify`](#UserSession.verify) * [`getProject`](#UserSession.getProject) * [`setProject`](#UserSession.setProject) * [`getProjects`](#UserSession.getProjects) * [`getAllProjects`](#UserSession.getAllProjects) * [`getBackpack`](#UserSession.getBackpack) * [`setBackpack`](#UserSession.setBackpack) * [`addComment`](#UserSession.addComment) * [`cloudSession`](#UserSession.cloudSession) ### Scratch.CloudSession * [`end`](#CloudSession.end) * [`get`](#CloudSession.get) * [`set`](#CloudSession.set) * [`variables`](#CloudSession.variables) * [`Event: set`](#CloudSession._set) * [`Event: end`](#CloudSession._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`](#UserSession.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`](#CloudSession.get) and [`set`](#CloudSession.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). --- _Source: https://npm.io/package/scratch-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._