millas 0.2.13 → 0.2.14

package/src/docs/SchemaInferrer.js

@@ -0,0 +1,131 @@
+'use strict';
+
+/**
+ * SchemaInferrer
+ *
+ * Reads a shape's "in" / "query" schema (BaseValidator instances) and
+ * maps them to ApiField objects for the docs panel.
+ *
+ * This is the bridge between the validation layer and the docs layer.
+ * Developers write their shape once — SchemaInferrer makes sure the
+ * docs panel reflects it accurately.
+ *
+ * ── Mapping ───────────────────────────────────────────────────────────────────
+ *
+ *   StringValidator              → ApiField.text()
+ *   StringValidator + .email()   → ApiField.email()
+ *   StringValidator + .url()     → ApiField.url()
+ *   StringValidator + .uuid()    → ApiField.uuid()
+ *   StringValidator + .phone()   → ApiField.phone()
+ *   StringValidator + .oneOf()   → ApiField.select([...])
+ *   EmailValidator               → ApiField.email()
+ *   NumberValidator              → ApiField.number()
+ *   NumberValidator + .integer() → ApiField.integer()
+ *   BooleanValidator             → ApiField.boolean()
+ *   ArrayValidator               → ApiField.array()
+ *   DateValidator                → ApiField.date()
+ *   FileValidator                → ApiField.file()
+ *   ObjectValidator              → ApiField.json()
+ *
+ * All validators:
+ *   ._required  → ApiField.required() / .nullable()
+ *   ._example   → ApiField.example(value)
+ *   ._describe  → ApiField.description(text)
+ *   ._minLen / ._minVal → ApiField.min(n)
+ *   ._maxLen / ._maxVal → ApiField.max(n)
+ */
+
+'use strict';
+
+const {
+  StringValidator,
+  EmailValidator,
+  NumberValidator,
+  BooleanValidator,
+  ArrayValidator,
+  DateValidator,
+  ObjectValidator,
+  FileValidator,
+  BaseValidator,
+} = require('../validation/types');
+
+/**
+ * Infer an ApiField-compatible JSON descriptor from a BaseValidator instance.
+ * Returns a plain object matching ApiField.toJSON() shape.
+ *
+ * @param {string}        fieldName
+ * @param {BaseValidator} validator
+ * @returns {object}  ApiField-compatible JSON
+ */
+function inferField(fieldName, validator) {
+  if (!(validator instanceof BaseValidator)) return null;
+
+  // Determine the ApiField type
+  let type = 'string';
+
+  if (validator instanceof EmailValidator) {
+    type = 'email';
+  } else if (validator instanceof StringValidator) {
+    if (validator._emailCheck) type = 'email';
+    else if (validator._urlCheck)  type = 'url';
+    else if (validator._uuidCheck) type = 'uuid';
+    else if (validator._phoneCheck) type = 'phone';
+    else if (validator._oneOfVals)  type = 'select';
+    else type = 'string';
+  } else if (validator instanceof NumberValidator) {
+    type = validator._isInt ? 'integer' : 'number';
+  } else if (validator instanceof BooleanValidator) {
+    type = 'boolean';
+  } else if (validator instanceof ArrayValidator) {
+    type = 'array';
+  } else if (validator instanceof DateValidator) {
+    type = 'date';
+  } else if (validator instanceof ObjectValidator) {
+    type = 'json';
+  } else if (validator instanceof FileValidator) {
+    type = 'file';
+  }
+
+  // Build enum for select fields
+  let enumVals = null;
+  if (type === 'select' && validator._oneOfVals) {
+    enumVals = validator._oneOfVals.map(v => ({ value: String(v), label: String(v) }));
+  }
+
+  // Determine min/max from the validator instance properties
+  const minVal = validator._minLen ?? validator._minVal ?? null;
+  const maxVal = validator._maxLen ?? validator._maxVal ?? null;
+
+  return {
+    name:        fieldName,
+    type,
+    required:    validator._required  || false,
+    nullable:    validator._nullable  || false,
+    example:     validator._example !== undefined ? validator._example : undefined,
+    description: validator._describe  || validator._label || null,
+    default:     validator._defaultValue !== undefined ? validator._defaultValue : undefined,
+    enum:        enumVals,
+    min:         minVal,
+    max:         maxVal,
+    format:      null,
+  };
+}
+
+/**
+ * Infer an entire schema map (from shape.in or shape.query) into an
+ * object of ApiField-compatible JSON descriptors.
+ *
+ * @param {object} schema  — { fieldName: BaseValidator, ... }
+ * @returns {object}       — { fieldName: ApiFieldJSON, ... }
+ */
+function inferFields(schema) {
+  if (!schema || typeof schema !== 'object') return {};
+  const out = {};
+  for (const [name, validator] of Object.entries(schema)) {
+    const field = inferField(name, validator);
+    if (field) out[name] = field;
+  }
+  return out;
+}
+
+module.exports = { inferField, inferFields };

package/src/docs/handlers/ApiHandler.js

@@ -0,0 +1,305 @@
+'use strict';
+
+const https  = require('https');
+const http   = require('http');
+const { URL } = require('url');
+
+/**
+ * ApiHandler
+ *
+ * Internal JSON API used by the client-side docs app.
+ *
+ *   GET  /_api/manifest          → full docs manifest (groups + endpoints)
+ *   POST /_api/try               → proxy a real API request
+ *   GET  /_api/export/postman    → Postman collection JSON
+ *   GET  /_api/export/openapi    → OpenAPI 3.0 JSON
+ */
+class ApiHandler {
+  constructor(docs) {
+    this._docs = docs;
+  }
+
+  manifest(req, res) {
+    try {
+      const manifest = this._docs.buildManifest();
+      res.json({ ok: true, data: manifest });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  }
+
+  /**
+   * Proxy a real request from the browser.
+   *
+   * Request body:
+   *   {
+   *     method:   'GET' | 'POST' | ...,
+   *     url:      'http://localhost:3000/api/v1/users',
+   *     headers:  { 'Authorization': 'Bearer ...' },
+   *     body:     { ... },      // JSON body for POST/PATCH/PUT
+   *     encoding: 'json' | 'form' | 'multipart'
+   *   }
+   *
+   * For multipart: body is forwarded as application/x-www-form-urlencoded
+   * (file contents are not proxied — the browser sends field values only).
+   * Full file upload proxying requires the client to send a FormData blob,
+   * which is handled separately via the browser fetch direct path.
+   */
+  async tryRequest(req, res) {
+    const { method, url, headers = {}, body, encoding } = req.body || {};
+
+    if (!url) {
+      return res.status(400).json({ ok: false, error: 'url is required' });
+    }
+
+    const start = Date.now();
+
+    try {
+      const parsed = new URL(url);
+      const lib    = parsed.protocol === 'https:' ? https : http;
+      const verb   = (method || 'GET').toUpperCase();
+      const hasBody = body && verb !== 'GET' && verb !== 'DELETE';
+
+      let bodyStr       = null;
+      let contentType   = 'application/json';
+
+      if (hasBody) {
+        if (encoding === 'form' || encoding === 'multipart') {
+          // Send as URL-encoded form (file fields are omitted — browser must handle uploads directly)
+          const formParts = Object.entries(body)
+            .filter(([, v]) => v !== undefined && v !== null && v !== '')
+            .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+          bodyStr     = formParts.join('&');
+          contentType = 'application/x-www-form-urlencoded';
+        } else {
+          bodyStr     = JSON.stringify(body);
+          contentType = 'application/json';
+        }
+      }
+
+      const options = {
+        hostname: parsed.hostname,
+        port:     parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+        path:     parsed.pathname + parsed.search,
+        method:   verb,
+        headers: {
+          'Content-Type': contentType,
+          'Accept':       'application/json',
+          ...headers,
+          ...(bodyStr ? { 'Content-Length': Buffer.byteLength(bodyStr) } : {}),
+        },
+      };
+
+      const result = await new Promise((resolve, reject) => {
+        const reqOut = lib.request(options, (incoming) => {
+          let data = '';
+          incoming.on('data', chunk => { data += chunk; });
+          incoming.on('end', () => {
+            resolve({
+              status:  incoming.statusCode,
+              headers: incoming.headers,
+              body:    data,
+            });
+          });
+        });
+        reqOut.on('error', reject);
+        if (bodyStr) reqOut.write(bodyStr);
+        reqOut.end();
+      });
+
+      let parsedBody = result.body;
+      try { parsedBody = JSON.parse(result.body); } catch {}
+
+      res.json({
+        ok:      true,
+        status:  result.status,
+        headers: result.headers,
+        body:    parsedBody,
+        time:    Date.now() - start,
+      });
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message, time: Date.now() - start });
+    }
+  }
+
+  exportPostman(req, res) {
+    try {
+      const manifest  = this._docs.buildManifest();
+      const baseUrl   = (req.query.baseUrl || 'http://localhost:3000').replace(/\/$/, '');
+      const collection = _toPostman(manifest, baseUrl);
+      res.setHeader('Content-Disposition', 'attachment; filename="api-collection.json"');
+      res.json(collection);
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  }
+
+  exportOpenApi(req, res) {
+    try {
+      const manifest = this._docs.buildManifest();
+      const baseUrl  = req.query.baseUrl || 'http://localhost:3000';
+      const spec     = _toOpenApi(manifest, baseUrl);
+      res.setHeader('Content-Disposition', 'attachment; filename="openapi.json"');
+      res.json(spec);
+    } catch (err) {
+      res.status(500).json({ ok: false, error: err.message });
+    }
+  }
+}
+
+// ── Export helpers ─────────────────────────────────────────────────────────────
+
+function _toPostman(manifest, baseUrl) {
+  const items = [];
+
+  for (const group of manifest.groups) {
+    const groupItems = group.endpoints.map(ep => {
+      // Path params
+      const url = (baseUrl + ep.path).replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, '{{$1}}');
+
+      const item = {
+        name: ep.label,
+        request: {
+          method: ep.verb.toUpperCase(),
+          header: [
+            { key: 'Content-Type', value: 'application/json' },
+            ...(ep.auth ? [{ key: 'Authorization', value: 'Bearer {{token}}' }] : []),
+          ],
+          url: { raw: url, host: [url] },
+        },
+      };
+
+      if (ep.body && Object.keys(ep.body).length && ep.verb !== 'get') {
+        const example = {};
+        for (const [k, f] of Object.entries(ep.body)) {
+          example[k] = f.example !== undefined ? f.example : _typeDefault(f.type);
+        }
+        item.request.body = {
+          mode: 'raw',
+          raw:  JSON.stringify(example, null, 2),
+          options: { raw: { language: 'json' } },
+        };
+      }
+
+      return item;
+    });
+
+    items.push({
+      name: group.label,
+      item: groupItems,
+    });
+  }
+
+  return {
+    info: {
+      name:   manifest.title,
+      schema: 'https://schema.getpostman.com/json/collection/v2.1.0/collection.json',
+    },
+    item: items,
+    variable: [
+      { key: 'baseUrl', value: baseUrl },
+      { key: 'token',   value: '' },
+    ],
+  };
+}
+
+function _toOpenApi(manifest, baseUrl) {
+  const paths = {};
+
+  for (const group of manifest.groups) {
+    for (const ep of group.endpoints) {
+      const oaPath = ep.path.replace(/:([a-zA-Z_][a-zA-Z0-9_]*)/g, '{$1}');
+      if (!paths[oaPath]) paths[oaPath] = {};
+
+      const operation = {
+        summary:     ep.label,
+        description: ep.description || '',
+        tags:        [group.label],
+        parameters:  [],
+        responses:   {},
+      };
+
+      // Path params
+      for (const pName of (ep.pathParams || [])) {
+        const pDef = ep.params?.[pName] || {};
+        operation.parameters.push({
+          name: pName, in: 'path', required: true,
+          schema:   { type: pDef.type || 'string' },
+          example:  pDef.example,
+          description: pDef.description || '',
+        });
+      }
+
+      // Query params
+      for (const [qName, qDef] of Object.entries(ep.query || {})) {
+        operation.parameters.push({
+          name: qName, in: 'query', required: qDef.required || false,
+          schema:  { type: qDef.type || 'string' },
+          example: qDef.example,
+          description: qDef.description || '',
+        });
+      }
+
+      // Auth
+      if (ep.auth) {
+        operation.security = [{ bearerAuth: [] }];
+      }
+
+      // Request body
+      if (ep.body && Object.keys(ep.body).length && ep.verb !== 'get') {
+        const props = {}, required = [];
+        for (const [fName, fDef] of Object.entries(ep.body)) {
+          props[fName] = { type: fDef.type || 'string', example: fDef.example, description: fDef.description || '' };
+          if (fDef.required) required.push(fName);
+        }
+        operation.requestBody = {
+          content: {
+            'application/json': {
+              schema: { type: 'object', properties: props, ...(required.length ? { required } : {}) },
+            },
+          },
+        };
+      }
+
+      // Responses
+      if (ep.responses?.length) {
+        for (const r of ep.responses) {
+          operation.responses[String(r.status)] = {
+            description: r.description || _statusText(r.status),
+            content: r.example ? {
+              'application/json': { example: r.example },
+            } : undefined,
+          };
+        }
+      } else {
+        operation.responses['200'] = { description: 'OK' };
+      }
+
+      paths[oaPath][ep.verb] = operation;
+    }
+  }
+
+  return {
+    openapi: '3.0.3',
+    info:    { title: manifest.title, version: '1.0.0' },
+    servers: [{ url: baseUrl }],
+    components: {
+      securitySchemes: {
+        bearerAuth: { type: 'http', scheme: 'bearer', bearerFormat: 'JWT' },
+      },
+    },
+    paths,
+  };
+}
+
+function _typeDefault(type) {
+  const m = { string: '', email: 'user@example.com', password: 'secret', number: 0, integer: 0, boolean: false, array: [], json: {} };
+  return m[type] ?? '';
+}
+
+function _statusText(s) {
+  const t = { 200:'OK',201:'Created',204:'No Content',400:'Bad Request',401:'Unauthorized',403:'Forbidden',404:'Not Found',422:'Unprocessable Entity',500:'Server Error' };
+  return t[s] || 'Response';
+}
+
+module.exports = ApiHandler;

package/src/docs/handlers/PageHandler.js

@@ -0,0 +1,47 @@
+'use strict';
+
+/**
+ * PageHandler
+ *
+ * Serves the single-page docs app shell.
+ * All content is loaded client-side via /_api/manifest.
+ */
+class PageHandler {
+  constructor(docs) {
+    this._docs = docs;
+  }
+
+  index(req, res) {
+    const cfg        = this._docs._config;
+    const adminPrefix = cfg.adminPrefix || '/admin';
+    res.send(_shell(cfg.title, cfg.prefix, adminPrefix));
+  }
+}
+
+function _shell(title, prefix, adminPrefix) {
+  // Bootstrap Icons is served from the admin's local vendor directory —
+  // no CDN, no CSP violation. Both admin and docs are framework internals
+  // so sharing the vendor path is intentional and safe.
+  const biCss = `${adminPrefix}/static/vendor/bi/bootstrap-icons.min.css`;
+
+  // __DOCS_PREFIX__ is passed via a data attribute on #app instead of an
+  // inline <script> block — avoids the script-src 'unsafe-inline' CSP error.
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>${title}</title>
+  <link rel="stylesheet" href="${prefix}/static/docs.css?v=5" />
+  <link rel="stylesheet" href="${biCss}" />
+</head>
+<body>
+  <div id="app" data-prefix="${prefix}" data-admin-prefix="${adminPrefix}"></div>
+  <!-- ui.js from admin — Portal, Modal, Drawer, Toast, Confirm, Tooltip, Dropdown -->
+  <script src="${adminPrefix}/static/ui.js"></script>
+  <script src="${prefix}/static/docs.js?v=10"></script>
+</body>
+</html>`;
+}
+
+module.exports = PageHandler;

package/src/docs/index.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const Docs                 = require('./Docs');
+const DocsServiceProvider  = require('./DocsServiceProvider');
+const { ApiResource, ApiEndpoint, ApiField } = require('./resources/ApiResource');
+
+module.exports = {
+  Docs,
+  DocsServiceProvider,
+  ApiResource,
+  ApiEndpoint,
+  ApiField,
+};