Script endpoints (JavaScript / TypeScript)

Write endpoints in YAML or JavaScript/TypeScript: sandboxed, with a shared global environment of reusable code.

Endpoints can be written in YAML (steps) or in JavaScript / TypeScript (code). Collections stay YAML. More languages are planned; YAML endpoints are unchanged and stay supported.

• Code endpoints. Set runtime: javascript or runtime: typescript and put the code in script. The server runs it against the same records, game values, access rules and clock that YAML endpoints use.
• A full global environment. Any endpoint can be scope: global: it gets no HTTP route and shares its exported functions, classes and constants with every other script, via import { x } from "globals/<id>" or globals.<id>.x without an import. Existing YAML workflows are callable as workflows.<name>(input).
• Sandboxed. Scripts run inside the server in an isolated interpreter with no file system, network, process or .NET access, and with per-request limits on time, statements, memory, recursion and storage operations (see Limits). One project's scripts cannot see another project's data.

Available on main now and in the next server release (0.5.5).

method: POST
runtime: javascript
scope: public
script: |
  export default function handle(req, ns) {
    if (req.player === null) ns.fail("AUTH_REQUIRED", "Sign in first.", 401);
    const player = ns.records.get("players", req.player.steamId) ?? { coins: 0 };
    return { ok: true, coins: player.coins };
  }

Starting templates for both runtimes are listed at the end of this page.

#Contract

The script exports a default function handle(req, ns). Its return value is the response body as JSON. Return plain data (objects, arrays, strings, numbers, booleans, null).

A script ends the request with an error through ns.fail. A failed request answers with its status and this body:

{ "ok": false, "error": { "code": "AUTH_REQUIRED", "message": "Sign in first." } }

The script cannot catch ns.fail. Its status must be in the 400-499 range; the default is 400.

#req

The first argument. Its type is EndpointRequest in ns.d.ts.

Check req.player before you use it. Anonymous callers have no player, and a secret-key caller has no player either, even though the server trusts that caller.

#ns

The second argument. Its type is Ns in ns.d.ts.

Writes made by a script apply when the endpoint returns normally. A request that ends with ns.fail does not keep its writes.

#Scope, imports and globals

scope says who can reach the script:

• scope: public (the default). The endpoint is a public HTTP route like any other endpoint. It can also be imported by other scripts.
• scope: global. The endpoint is never a public route. A public call answers 404 ENDPOINT_NOT_FOUND, the same as an unknown slug. Its exports are shared with other scripts.

A global endpoint exports values with export:

// endpoints/inventory.endpoint.js (scope: global)
export class Inventory {
  constructor(items) { this.items = items; }
  has(itemId) { return this.items.includes(itemId); }
}
export function check_inventory_has_item(player, itemId) {
  const record = ns.records.get("players", player.steamId);
  return Boolean(record) && (record.items ?? []).includes(itemId);
}

Other scripts use an export in one of two ways.

// 1. Import it by endpoint id.
import { Inventory } from "globals/inventory";

// 2. Read it through the globals object.
const has = globals.inventory.check_inventory_has_item(req.player, "sword");

The globals/<id> import path and globals.<id> both use the global endpoint's slug. The server checks imports when the endpoint is saved: an import cycle reports GLOBAL_CYCLE, a missing global GLOBAL_NOT_FOUND, a missing export GLOBAL_EXPORT_NOT_FOUND, and module syntax outside the forms above SCRIPT_MODULE_UNSUPPORTED.

#Legacy workflows

Workflows remain the step-based definitions that YAML endpoints use. Scripts can run them in two ways:

• ns.workflows.run("<workflow-id>", input)
• workflows.<alias>(input), where the alias is the workflow id in camelCase

A workflow's writes apply only if the workflow succeeds, as they do for YAML endpoints. Nested workflow calls stop at the workflow depth limit (see Limits).

An endpoint has either script or steps, never both. Setting both answers SCRIPT_AND_STEPS at save time.

Save-time checks (script syntax, source size and runtime) run when the owner dashboard saves an endpoint. The Sync Tool, the package sync and the management push and patch paths store the definition as received and do not run them. A script with a syntax error that arrives through those paths is stored, and its first call fails with SCRIPT_ERROR.

#TypeScript

Set runtime: typescript. The server removes the type annotations with the vendored sucrase stripper (MIT, see Third-party notice) and then runs the result as JavaScript. Nothing else is transformed.

• Types are removed, not checked. A type error does not stop the endpoint.
• Code the stripper cannot read is rejected as SCRIPT_SYNTAX, with a line and column, when the owner dashboard saves it.
• The ns.d.ts declarations give editors the types. The project typings endpoint adds the project's collections, game values, workflow aliases and global exports.

#Limits

Every scripted request is bounded. These limits are fixed in code. The only script setting is endpoints.scripts; no limit is read from server.toml.

The time and statement limits are one budget for the whole request. Module evaluation, the handler call, response serialisation and every re-run round all draw from it, and a re-run does not reset it. Memory is per engine: each round runs in its own engine, and rounds run one after another, so the peak is one engine's limit.

Promises are bounded by the same time limit: a promise that does not settle before the request's deadline fails with SCRIPT_LIMIT_EXCEEDED, so an async handler cannot hang past it. If the caller disconnects, the run is cancelled and is not reported as SCRIPT_ERROR.

Caches: the server keeps the 256 most recently used compiled JavaScript scripts and the 256 most recently used stripped TypeScript outputs in memory, and evicts the least recently used first. Each process starts with empty caches, so the first call after a restart parses or strips again.

Kill switch: the server setting endpoints.scripts (default true) turns scripted endpoints off. While it is off, every scripted endpoint answers 503 SCRIPTS_DISABLED, and YAML endpoints are unaffected. Restart the server after changing it.

#Typed error codes

ns.fail takes any code and a status from 400 to 499. The codes above are the server's own. Template codes, such as AUTH_REQUIRED or INSUFFICIENT_COINS, belong to the template and are listed with it.

#Templates

Each template ships in both runtimes. Templates are data files served as static assets. Their list is:

Files are named <template>.javascript.endpoint.yml and <template>.typescript.endpoint.yml. Served at /owner-assets/endpoint-api/templates/<file>. The shared typings are at /owner-assets/endpoint-api/ns.d.ts. A project's typings, with its own collections, game values and globals, are at GET /dashboard/projects/{id}/resources/endpoint-typings.

#File layout

Authored endpoints keep the definition and the script side by side:

Editor/Network Storage/
  endpoints/daily-reward.endpoint.yml
  endpoints/daily-reward.endpoint.js

scriptFile names the script file from the definition:

method: POST
runtime: javascript
scope: public
scriptFile: daily-reward.endpoint.js

scriptFile is an authoring reference only. The server stores the script text under script. A definition that sets scriptFile without script is rejected with SCRIPT_FILE_WITHOUT_SCRIPT. The Sync Tool does not yet read scriptFile or upload script files. Support is tracked in sbox-cool/sbox-network-storage#45. Until it lands, put the script text in script.

#Third-party notice

The TypeScript runtime bundles sucrase 3.35.1 (MIT) with its dependencies: lines-and-columns 1.2.4 (MIT), ts-interface-checker 0.1.13 (Apache-2.0) and the @jridgewell source-map packages (MIT). The bundle, the licence texts and a build script are in src/SboxNetworkStorage.Application/NetworkStorage/Endpoints/Scripting/ThirdParty/sucrase/ (see its README.md). The code runs inside the isolated script engine. It is not compiled into the server.