initial

2026-09-23 12:29:08 -03:00
commit f5d231ab8f
59 changed files with 16658 additions and 0 deletions
@@ -0,0 +1,109 @@
+# 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
+
+```bash
+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 — Create the file
+
+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):
+
+```javascript
+/**
+ * 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 — Register in vitruvio.json
+
+Read `vitruvio.json`, find or create the `"endpoints"` array, and add:
+
+```json
+{
+  "key": "<key>",
+  "name": "<name>",
+  "description": "<description>",
+  "language": "javascript",
+  "authMode": "<authMode>",
+  "active": true,
+  "source": "endpoints/<key>.js"
+}
+```
+
+Preserve the existing file structure and all other entries. Write the updated `vitruvio.json` back.
+
+## 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