🎉 Add malli based validation and coersion subsystem

backend/resources/app/templates/api-doc-entry.tmpl

@@ -14,19 +14,27 @@
           <span>AUTH</span>
         </span>
       {% endif %}
-      
+
       {% if item.webhook %}
         <span class="tag">
           <span>WEBHOOK</span>
         </span>
       {% endif %}
+      {% if item.params-schema-js %}
+        <span class="tag">
+          <span>SC</span>
+        </span>
+      {% else %}
+        <span class="tag">
+          <span>SP</span>
+        </span>
+      {% endif %}
     </div>
   </div>
   <div class="rpc-row-detail hidden">
-    <h3>DOCSTRING:</h3>
+    <h4>DOCSTRING:</h4>
 
     <section class="padded-section">
-
       {% if item.added %}
         <p class="small"><strong>Added:</strong> on v{{item.added}}</p>
       {% endif %}
@@ -35,13 +43,18 @@
         <p class="small"><strong>Deprecated:</strong> since v{{item.deprecated}}</p>
       {% endif %}
 
+      {% if item.entrypoint %}
+        <p class="small"><strong>URI:</strong> <a href="{{item.entrypoint}}">{{item.entrypoint}}</a></p>
+      {% endif %}
+
       {% if item.docs %}
         <p class="docstring"> {{item.docs}}</p>
       {% endif %}
+
     </section>
 
     {% if item.changes %}
-      <h3>CHANGES:</h3>
+      <h4>CHANGES:</h4>
       <section class="padded-section">
 
         <ul class="changes">
@@ -52,9 +65,55 @@
       </section>
     {% endif %}
 
-    <h3>SPEC EXPLAIN:</h3>
-    <section class="padded-section">
-      <pre class="spec-explain">{{item.spec}}</pre>
-    </section>
+    {% if item.spec %}
+      <h4>PARAMS (SPEC):</h4>
+      <section class="padded-section">
+        <pre class="spec-explain">{{item.spec}}</pre>
+      </section>
+    {% endif %}
+
+    {% if param-style = "js" %}
+      {% if item.params-schema-js %}
+        <h4>PARAMS:</h4>
+        <section class="padded-section">
+          <pre class="params-schema">{{item.params-schema-js}}</pre>
+        </section>
+      {% endif %}
+
+      {% if item.result-schema-js %}
+        <h4>RESPONSE:</h4>
+        <section class="padded-section">
+          <pre class="result">{{item.result-schema-js}}</pre>
+        </section>
+      {% endif %}
+
+      {% if item.webhook-schema-js %}
+        <h4>WEBHOOK PAYLOAD:</h4>
+        <section class="padded-section">
+          <pre class="webhook">{{item.webhook-schema-js}}</pre>
+        </section>
+      {% endif %}
+    {% else %}
+      {% if item.params-schema-clj %}
+        <h4>PARAMS:</h4>
+        <section class="padded-section">
+          <pre class="params-schema">{{item.params-schema-clj}}</pre>
+        </section>
+      {% endif %}
+
+      {% if item.result-schema-clj %}
+        <h4>RESPONSE:</h4>
+        <section class="padded-section">
+          <pre class="result">{{item.result-schema-clj}}</pre>
+        </section>
+      {% endif %}
+
+      {% if item.webhook-schema-clj %}
+        <h4>WEBHOOK PAYLOAD:</h4>
+        <section class="padded-section">
+          <pre class="webhook">{{item.webhook-schema-clj}}</pre>
+        </section>
+      {% endif %}
+    {% endif %}
   </div>
 </li>

backend/resources/app/templates/api-doc.css

@@ -27,12 +27,78 @@ main {
 header {
   border-bottom: 1px solid #c0c0c0;
   display: flex;
+  flex-direction: column;
+  align-items: center;
   justify-content: center;
   width: 100%;
 }
 
-.rpc-doc-content {
+header .menu {
+  display: flex;
+  align-items: center;
+  margin-top: 5px;
+  margin-bottom: 10px;
+}
+
+header .menu nav {
+  list-style: none;
+  padding: 0px;
+  margin: 0px;
+  display: flex;
+  width: 45px;
+  justify-content: space-between;
+}
+
+header .menu nav > a {
+  list-style: none;
+  padding: 0px;
+  margin: 0px;
+  cursor: pointer;
+}
+
+header .menu nav > a.selected {
+  font-weight: 600;
+}
+
+b {
+  font-weight: 500;
+}
+
+h2 {
+  margin-top: 30px;
+}
+
+h3 {
+  font-weight: 400;
+  font-size: 11px;
   margin-top: 20px;
+  text-decoration: underline;
+}
+
+h4 {
+  font-weight: 300;
+  font-size: 11px;
+}
+
+.doc-content {
+  margin-top: 20px;
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  /* border: 1px solid red; */
+  padding: 5px;
+}
+
+.doc-content p {
+  line-height: 22px;
+  margin-bottom: 0px;
+}
+
+.doc-content h3 {
+  margin-bottom: 0px;
+}
+
+.rpc-doc-content {
   width: 100%;
   display: flex;
   flex-direction: column;
@@ -65,7 +131,7 @@ header {
 .rpc-row-info {
   cursor: pointer;
   display: flex;
-  background-color: #eeeeee;
+  background-color: #e5e5e5;
   padding: 5px 10px;
 }
 
@@ -108,6 +174,8 @@ header {
 .rpc-row-detail {
   padding: 5px 10px;
   padding-bottom: 20px;
+  border-left: 2px solid #e5e5e5;
+  border-right: 2px solid #e5e5e5;
 }
 
 .rpc-row-detail p {
@@ -143,3 +211,7 @@ header {
 p.small strong {
   font-size: 10px;
 }
+
+p.small a {
+  font-size: 10px;
+}

backend/resources/app/templates/api-doc.tmpl

@@ -20,10 +20,68 @@
     <main>
       <header>
         <h1>Penpot API Documentation (v{{version}})</h1>
+        <small class="menu">
+          [
+          <nav>
+            <a href="?type=js" {% if param-style = "js" %}class="selected"{% endif %}>JS</a>
+            <a href="?type=clj" {% if param-style = "cljs" %}class="selected"{% endif %}>CLJ</a>
+          </nav>
+          ]
+        </small>
       </header>
-      <section class="rpc-doc-content">
+      <section class="doc-content">
+        <h2>INTRODUCTION</h2>
+        <p>This documentation is intended to be a general overview of the penpot RPC API.
+          If you prefer, you can use <a href="/api/openapi.json">OpenAPI</a>
+          and/or <a href="/api/openapi">SwaggerUI</a> as alternative.</p>
 
-        <h2>RPC METHODS:</h2>
+        <h2>GENERAL NOTES</h2>
+
+        <h3>Authentication</h3>
+        <p>The penpot backend right now offerts two way for authenticate the request:
+        <b>cookies</b> (the same mechanism that we use ourselves on accessing the API from the
+        web application) and <b>access tokens</b>.</p>
+
+        <p>The cookie can be obtained using the <b>`login-with-password`</b> rpc method,
+        on successful login it sets the <b>`auth-token`</b> cookie with the session
+        token.</p>
+
+        <p>The access token can be obtained on the appropriate section on profile settings
+        and it should be provided using <b>`Authorization`</b> header with <b>`Token
+        &lt;token-string&gt;`</b> value.</p>
+
+        <h3>Content Negotiation</h3>
+        <p>The penpot API by default operates indistinctly with: <b>`application/json`</b>
+        and <b>`application/transit+json`</b> content types. You should specify the
+        desired content-type on the <b>`Accept`</b> header, the transit encoding is used
+        by default.</p>
+
+
+        <h3>Limits</h3>
+        <p>The rate limit work per user basis (this means that different api keys share
+        the same rate limit). For now the limits are not documented because we are
+        studying and analyzing the data. As a general rule, it should not be abused, if an
+        abusive use is detected, we will proceed to block the user's access to the
+        API.</p>
+
+        <h3>Webhooks</h3>
+        <p>All methods that emit webhook events are marked with flag <b>WEBHOOK</b>, the
+        data structure defined on each method represents the <i>payload</i> of the
+        event.</p>
+        <p>The webhook event structure has this aspect:</p>
+        <br/>
+
+        <pre>
+{
+  "id": "db601c95-045f-808b-8002-362f08fcb621",
+  "name": "rename-file",
+  "props": &lt;payload&gt;,
+  "profileId": "db601c95-045f-808b-8002-361312e63531"
+}
+        </pre>
+      </section>
+      <section class="rpc-doc-content">
+        <h2>RPC METHODS REFERENCE:</h2>
         <ul class="rpc-items">
           {% for item in methods %}
             {% include "app/templates/api-doc-entry.tmpl" with item=item %}

backend/resources/app/templates/error-report.v3.tmpl

@@ -0,0 +1,100 @@
+ {% extends "app/templates/base.tmpl" %}
+
+{% block title %}
+penpot - error report v2 {{id}}
+{% endblock %}
+
+{% block content %}
+<nav>
+  <div>[<a href="/dbg/error">⮜</a>]</div>
+  <div>[<a href="#message">message</a>]</div>
+  <div>[<a href="#props">props</a>]</div>
+  <div>[<a href="#context">context</a>]</div>
+  {% if params %}
+  <div>[<a href="#params">params</a>]</div>
+  {% endif %}
+  {% if data %}
+  <div>[<a href="#edata">data</a>]</div>
+  {% endif %}
+  {% if explain %}
+  <div>[<a href="#explain">explain</a>]</div>
+  {% endif %}
+  {% if value %}
+  <div>[<a href="#value">value</a>]</div>
+  {% endif %}
+  {% if trace %}
+  <div>[<a href="#trace">trace</a>]</div>
+  {% endif %}
+</nav>
+<main>
+  <div class="table">
+    <div class="table-row multiline">
+      <div id="message" class="table-key">MESSAGE: </div>
+
+      <div class="table-val">
+        <h1>{{hint}}</h1>
+      </div>
+    </div>
+
+    <div class="table-row multiline">
+      <div id="props" class="table-key">LOG PROPS: </div>
+      <div class="table-val">
+        <pre>{{props}}</pre>
+      </div>
+    </div>
+
+    <div class="table-row multiline">
+      <div id="context" class="table-key">CONTEXT: </div>
+
+      <div class="table-val">
+        <pre>{{context}}</pre>
+      </div>
+    </div>
+
+    {% if params %}
+    <div class="table-row multiline">
+      <div id="params" class="table-key">PARAMS: </div>
+      <div class="table-val">
+        <pre>{{params}}</pre>
+      </div>
+    </div>
+    {% endif %}
+
+    {% if data %}
+    <div class="table-row multiline">
+      <div id="edata" class="table-key">DATA: </div>
+      <div class="table-val">
+        <pre>{{data}}</pre>
+      </div>
+    </div>
+    {% endif %}
+
+    {% if value %}
+    <div class="table-row multiline">
+      <div id="value" class="table-key">VALIDATION VALUE: </div>
+      <div class="table-val">
+        <pre>{{value}}</pre>
+      </div>
+    </div>
+    {% endif %}
+
+    {% if explain %}
+    <div class="table-row multiline">
+      <div id="explain" class="table-key">EXPLAIN: </div>
+      <div class="table-val">
+        <pre>{{explain}}</pre>
+      </div>
+    </div>
+    {% endif %}
+
+    {% if trace %}
+    <div class="table-row multiline">
+      <div id="trace" class="table-key">TRACE:</div>
+      <div class="table-val">
+        <pre>{{trace}}</pre>
+      </div>
+    </div>
+    {% endif %}
+  </div>
+</main>
+{% endblock %}

backend/resources/app/templates/openapi.tmpl

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <meta
+    name="description"
+    content="SwaggerUI"
+  />
+  <title>PENPOT Swagger UI</title>
+  <style>{{swagger-css|safe}}</style>
+</head>
+<body>
+<div id="swagger-ui"></div>
+<script>{{swagger-js|safe}}</script>
+<script>
+  window.onload = () => {
+    window.ui = SwaggerUIBundle({
+      url: '{{public-uri}}/api/openapi.json',
+      dom_id: '#swagger-ui',      
+      presets: [
+        SwaggerUIBundle.presets.apis,
+      ],
+    });
+  };
+</script>
+</body>
+</html>