Scripts API

Description: Returns a paginated list of scripts with optional filtering and sorting. Authentication is optional.

Query Parameters:

• search — free-text search string.
• tags — tag to filter by; repeatable to filter on multiple tags.
• sort — latest (default) or popular.
• page — page number (defaults to 1).
• limit — results per page (defaults to 10).
• favourites — set to trueto limit to the current user's favourited scripts.
• authorid— filter to scripts owned by a specific user id. Use this to list a user's scripts.

Response:

{
  "results": [ /* array of script objects */ ],
  "pagination": {
    "total": 0,
    "page": 1,
    "limit": 10,
    "pages": 0
  },
  "filters": {
    "tags": [ "string" ]
  }
}

Example:

// Search popular scripts tagged "fps" and "team"
fetch('/api/scripts?search=arena&tags=fps&tags=team&sort=popular&page=1&limit=10')
  .then(response => response.json())
  .then(data => console.log(data.results, data.pagination))
  .catch(error => console.error('Error:', error));

Description: Creates a new script owned by the authenticated user. Requires a session.

Request Body:

{
  "name": "string",
  "description": "string",
  "content": "string",
  "tags": [ "string" ],          // optional
  "visibility": "public",        // optional: "public" | "private"
  "notes": "string"              // optional
}

Response: the created script object.

Example:

fetch('/api/scripts', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    name: 'My First Game',
    description: 'A simple deathmatch mode',
    content: 'program { type "game"; name "My First Game"; }',
    tags: ['deathmatch'],
    visibility: 'public'
  })
})
  .then(response => response.json())
  .then(script => console.log('Created', script))
  .catch(error => console.error('Error:', error));

Description: Retrieves a single script by its id. No authentication required.

Path Parameters:

• id — the script id (a MongoDB ObjectId).

Response: the script object, or a 404 if not found.

Example:

const id = '64f0c0ffee0000000000abcd';

fetch(`/api/scripts/${id}`)
  .then(response => response.json())
  .then(script => console.log(script))
  .catch(error => console.error('Error:', error));

Description:Updates an existing script. Requires a session, and the authenticated user must be the script's owner.

Request Body: (all fields optional)

{
  "name": "string",
  "description": "string",
  "content": "string",
  "visibility": "private",       // "public" | "private"
  "tags": [ "string" ],
  "notes": "string"
}

Response: the updated script object.

Example:

const id = '64f0c0ffee0000000000abcd';

fetch(`/api/scripts/${id}`, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/json' },
  credentials: 'include',
  body: JSON.stringify({
    description: 'Updated description',
    visibility: 'private'
  })
})
  .then(response => response.json())
  .then(script => console.log('Updated', script))
  .catch(error => console.error('Error:', error));

Description:Deletes a script. Requires a session, and the authenticated user must be the script's owner.

Response:

{
  "success": true
}

Example:

const id = '64f0c0ffee0000000000abcd';

fetch(`/api/scripts/${id}`, {
  method: 'DELETE',
  credentials: 'include'
})
  .then(response => response.json())
  .then(data => console.log(data.success))
  .catch(error => console.error('Error:', error));

Description:Compiles the script's current version and returns the resulting binary (a compiled .bin file) as application/octet-stream. Public scripts are available to anyone; private scripts are only downloadable by their owner.

Response: binary file stream with a Content-Disposition: attachment header.

Example:

const id = '64f0c0ffee0000000000abcd';

fetch(`/api/scripts/${id}/download`, { credentials: 'include' })
  .then(response => response.blob())
  .then(blob => {
    const url = URL.createObjectURL(blob);
    // ...trigger a download from the object URL
  })
  .catch(error => console.error('Error:', error));

Description:Increments the script's download counter. Public scripts can be counted by anyone; private scripts only by their owner.

Response:

{
  "success": true,
  "downloads": 0,
  "message": "string"
}

Example:

const id = '64f0c0ffee0000000000abcd';

fetch(`/api/scripts/${id}/download`, {
  method: 'POST',
  credentials: 'include'
})
  .then(response => response.json())
  .then(data => console.log('Total downloads:', data.downloads))
  .catch(error => console.error('Error:', error));

Description: Toggles whether the authenticated user has favourited the script. Requires a session.

Response:

{
  "success": true,
  "isFavourite": true,
  "likes": 0
}

Example:

const id = '64f0c0ffee0000000000abcd';

fetch(`/api/scripts/${id}/favourite`, {
  method: 'POST',
  credentials: 'include'
})
  .then(response => response.json())
  .then(data => console.log('Favourited:', data.isFavourite, 'Likes:', data.likes))
  .catch(error => console.error('Error:', error));