jogos_matheus/.claude/skills/vitruvio-criar-endpoint/SKILL.md

name, description

name	description
vitruvio-criar-endpoint	Use when the user wants to create a new REST endpoint in a Vitruvio repository. Triggers: "create endpoint", "new endpoint", "criar endpoint", "novo endpoint", "add endpoint", "REST", "WebService", "integração", or any request to scaffold an endpoints/*.js file.

Create Vitruvio Endpoint

All messages shown to the user must be written in Portuguese.

You are creating a new REST endpoint inside a Vitruvio repository. Follow these steps in order.

Step 1 — Confirm you are inside a Vitruvio repo

ls vitruvio.json 2>/dev/null && echo "OK" || echo "NOT_A_VITRUVIO_REPO"

If NOT_A_VITRUVIO_REPO, stop and tell the user to cd into the correct repo.

Step 2 — Collect endpoint details

Ask the user (in a single message, only ask what is missing from their original request):

• Key — kebab-case unique identifier. Forms the URL path. Changing it later breaks external integrations.
• Name — human-readable label shown in the Vitruvio UI.
• Description — one sentence about what this endpoint does.
• HTTP verbs — which methods to implement: GET, POST, PUT, PATCH, DELETE. Only scaffold the ones actually needed.
• Auth mode — one of:
  • PUBLIC — no authentication (default)
  • STATIC_TOKEN — token in query param _x_token_auth or header X-WS-TOKEN-AUTH
  • VITRUVIO_WS_USER_AUTH — Vitruvio bearer token; loggedUser is available in the script
  • HTTP_BASIC_AUTH — HTTP basic auth; loggedUser is available; roles validated by Vitruvio admin

Step 3 — Scaffold and create file

vitruvio new endpoint <key> --name "<name>"

This creates endpoints/<key>.js and registers it in vitruvio.json with authMode: "PUBLIC" and active: true. Replace the generated file with the template below. If authMode is not PUBLIC, update that field in vitruvio.json.

Target path: endpoints/<key>.js

URL after deploy:

authMode	URL
PUBLIC	/api/integration/public/<key>
STATIC_TOKEN	/api/integration/tokenauth/<key>
VITRUVIO_WS_USER_AUTH	/api/integration/bearerauth/<key>
HTTP_BASIC_AUTH	/api/integration/bauth/<key>

Template (include only the requested verbs):

/**
 * Nome: <name>
 * Sigla: <key>
 * Descrição: <description>
 * Auth: <authMode>
 */
function WebService() {

  // this.onGet = function(params) { ... }   ← GET / DELETE: params has .headers and .query
  // this.onPost = function(params) { ... }  ← POST / PUT / PATCH: params also has .requestBody (string, always JSON.parse before use)

  this.onPost = function(params) {
    try {
      var body = JSON.parse(params.requestBody);
      if (!body.id) throw 'Missing required field: id';

      // implementation here

      return JSON.stringify({ success: true });
    } catch (e) {
      return JSON.stringify({ error: e.toString() });
    }
  };

}

module.exports = new WebService();

Rules (Rhino ES5 — no exceptions):

• No let, const, arrow functions, template literals, destructuring, spread, class, or import/export
• Use var everywhere
• Always JSON.parse(params.requestBody) before accessing the body — never trust it raw
• Always return strings — JSON.stringify(obj), not raw objects
• Return null or nothing for 204 No Content; return a string for 200 OK
• Remove unused verb stubs entirely — don't leave placeholder bodies
• Never concatenate user input into SQL strings; use named bind params (:paramName)
• Don't hardcode datasource names or tokens — read from vConfigService or a DB config table
• Put heavy logic in a separate script loaded via libService.loadScript, not inline in the endpoint

Step 4 — Update vitruvio.json entry

vitruvio new already added the endpoint entry. The full entry shape is:

{
  "key": "<key>",
  "name": "<name>",
  "description": "<description>",
  "language": "javascript",
  "authMode": "PUBLIC",
  "active": true,
  "source": "endpoints/<key>.js"
}

Update only what differs: set "authMode" to the correct value if not "PUBLIC"; add "description" if provided.

Step 5 — Report

Tell the user:

• File created: endpoints/<key>.js
• Registered in vitruvio.json with key <key>
• URL once deployed (based on authMode)
• Which verbs were scaffolded