From 8475e91359c4d0f1bb13de81c00b248213ef2980 Mon Sep 17 00:00:00 2001
From: Zaptoss <57064743+Zaptoss@users.noreply.github.com>
Date: Mon, 22 Jul 2024 11:22:27 +0000
Subject: [PATCH] =?UTF-8?q?Deploying=20to=20gh-pages=20from=20=20@=2037899?=
 =?UTF-8?q?1ebe24c87e7d1d4345c97e06ebc8c1c6b3f=20=F0=9F=9A=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 openapi.json | 321 +++++++++++++++++++++++++++++++++------------------
 openapi.yaml | 239 +++++++++++++++++++++++++-------------
 2 files changed, 367 insertions(+), 193 deletions(-)

diff --git a/openapi.json b/openapi.json
index aeaebe6..287e4f5 100644
--- a/openapi.json
+++ b/openapi.json
@@ -12,34 +12,43 @@
     }
   ],
   "paths": {
-    "/integrations/forms-svc/v1/form/{id}": {
-      "get": {
+    "/integrations/forms-svc/v1/form": {
+      "post": {
         "tags": [
           "User form"
         ],
-        "summary": "Get form",
-        "description": "Get user form by UUID with status.\nUser must be authorized, but `is_verified` field is not required in JWT.\n",
-        "operationId": "getForm",
-        "parameters": [
+        "summary": "Submit lightweight user answers",
+        "description": "Send user answers and return their current status.\n\nThe image is a link to s3 storage\n\nOnly a user with a confirmed passport can send the form ('verified: true' in JWT).\nThere is a configurable delay before the same user\ncan submit another form.\n",
+        "operationId": "lightweightSubmitForm",
+        "security": [
           {
-            "$ref": "#/components/parameters/pathID"
+            "BearerAuth": []
           }
         ],
+        "requestBody": {
+          "content": {
+            "application/vnd.api+json": {
+              "schema": {
+                "type": "object",
+                "required": [
+                  "data"
+                ],
+                "properties": {
+                  "data": {
+                    "$ref": "#/components/schemas/SubmitForm"
+                  }
+                }
+              }
+            }
+          }
+        },
         "responses": {
           "200": {
             "description": "Success",
             "content": {
               "application/vnd.api+json": {
                 "schema": {
-                  "type": "object",
-                  "required": [
-                    "data"
-                  ],
-                  "properties": {
-                    "data": {
-                      "$ref": "#/components/schemas/Form"
-                    }
-                  }
+                  "$ref": "#/components/schemas/FormStatus"
                 }
               }
             }
@@ -50,8 +59,15 @@
           "401": {
             "$ref": "#/components/responses/invalidAuth"
           },
-          "404": {
-            "$ref": "#/components/responses/notFound"
+          "429": {
+            "description": "It is necessary to wait some time before sending the next form",
+            "content": {
+              "application/vnd.api+json": {
+                "schema": {
+                  "$ref": "#/components/schemas/Errors"
+                }
+              }
+            }
           },
           "500": {
             "$ref": "#/components/responses/internalError"
@@ -65,13 +81,11 @@
           "User form"
         ],
         "summary": "Submit user answers",
-        "description": "Send user answers and return their current status.\n\nOnly a user with a confirmed passport can send the form.\nThere is a configurable delay before the same user\ncan submit another form.\n",
+        "description": "Send user answers and return their current status.\n\nThe image is a base64 string.\n\nOnly a user with a confirmed passport can send the form ('verified: true' in JWT).\nThere is a configurable delay before the same user\ncan submit another form.\n",
         "operationId": "submitForm",
         "security": [
           {
-            "BearerAuth": [
-              "verified: true"
-            ]
+            "BearerAuth": []
           }
         ],
         "requestBody": {
@@ -84,7 +98,7 @@
                 ],
                 "properties": {
                   "data": {
-                    "$ref": "#/components/schemas/SubmitForm"
+                    "$ref": "#/components/schemas/Form"
                   }
                 }
               }
@@ -93,7 +107,7 @@
         },
         "responses": {
           "200": {
-            "description": "Success",
+            "description": "Success. All fields except image will be returned.",
             "content": {
               "application/vnd.api+json": {
                 "schema": {
@@ -123,6 +137,110 @@
           }
         }
       }
+    },
+    "/integrations/forms-svc/v1/status/{id}": {
+      "get": {
+        "tags": [
+          "User form"
+        ],
+        "summary": "Get form status",
+        "description": "Get form status by UUID.\n",
+        "operationId": "getFormStatus",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/pathID"
+          }
+        ],
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/vnd.api+json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "data"
+                  ],
+                  "properties": {
+                    "data": {
+                      "$ref": "#/components/schemas/Form"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/invalidParameter"
+          },
+          "401": {
+            "$ref": "#/components/responses/invalidAuth"
+          },
+          "404": {
+            "$ref": "#/components/responses/notFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/internalError"
+          }
+        }
+      }
+    },
+    "/integrations/forms-svc/v1/status/last": {
+      "get": {
+        "tags": [
+          "User form"
+        ],
+        "summary": "Get last form status",
+        "description": "Get last form status filled out by the user nullifier.\n",
+        "operationId": "getLastFormStatus",
+        "parameters": [
+          {
+            "$ref": "#/components/parameters/pathNullifier"
+          }
+        ],
+        "security": [
+          {
+            "BearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success",
+            "content": {
+              "application/vnd.api+json": {
+                "schema": {
+                  "type": "object",
+                  "required": [
+                    "data"
+                  ],
+                  "properties": {
+                    "data": {
+                      "$ref": "#/components/schemas/FormStatus"
+                    }
+                  }
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/invalidParameter"
+          },
+          "401": {
+            "$ref": "#/components/responses/invalidAuth"
+          },
+          "404": {
+            "$ref": "#/components/responses/notFound"
+          },
+          "500": {
+            "$ref": "#/components/responses/internalError"
+          }
+        }
+      }
     }
   },
   "components": {
@@ -186,7 +304,6 @@
               "attributes": {
                 "type": "object",
                 "required": [
-                  "status",
                   "name",
                   "surname",
                   "id_num",
@@ -209,50 +326,63 @@
                       "accepted",
                       "processed"
                     ],
-                    "description": "Accepted - the data was saved by the service for further processing\nProcessed - the data is processed and stored\n"
+                    "description": "Accepted - the data was saved by the service for further processing\nProcessed - the data is processed and stored\nRead-only.\n"
                   },
                   "name": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "Hilary"
                   },
                   "surname": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "Cabe"
                   },
                   "id_num": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "3736297649"
                   },
                   "birthday": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "27/6/1988"
                   },
                   "citizen": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "Georgian"
                   },
                   "visited": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "18/07/2024"
                   },
                   "purpose": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "Make documents"
                   },
                   "country": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "Georgia"
                   },
                   "city": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "Kutaisi"
                   },
                   "address": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "Central street, 1"
                   },
                   "postal": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "21626"
                   },
                   "phone": {
-                    "type": "string"
+                    "type": "string",
+                    "example": "+13165282105"
                   },
                   "email": {
-                    "type": "string"
+                    "type": "cabehilary88@gmail.com"
                   },
                   "image": {
                     "type": "string",
-                    "description": "base64 encoded image with max size 4 MB"
+                    "description": "base64 encoded image with max size 4 MB or\nURL for S3 storage with image up to 4 mb\n",
+                    "example": "https://geoforms.nyc3.digitaloceanspaces.com/awesome_phono.jpg"
                   }
                 }
               }
@@ -263,7 +393,6 @@
       "FormKey": {
         "type": "object",
         "required": [
-          "id",
           "type"
         ],
         "properties": {
@@ -274,19 +403,19 @@
           "type": {
             "type": "string",
             "enum": [
-              "form"
+              "form",
+              "submit_form"
             ]
           }
         }
       },
-      "SubmitForm": {
+      "FormStatus": {
         "allOf": [
           {
-            "$ref": "#/components/schemas/SubmitFormKey"
+            "$ref": "#/components/schemas/FormStatusKey"
           },
           {
             "type": "object",
-            "x-go-is-request": true,
             "required": [
               "attributes"
             ],
@@ -294,64 +423,43 @@
               "attributes": {
                 "type": "object",
                 "required": [
-                  "name",
-                  "surname",
-                  "id_num",
-                  "birthday",
-                  "citizen",
-                  "visited",
-                  "purpose",
-                  "country",
-                  "city",
-                  "address",
-                  "postal",
-                  "phone",
-                  "email",
-                  "image"
+                  "status",
+                  "created_at",
+                  "next_form_at",
+                  "until_next_form"
                 ],
                 "properties": {
-                  "name": {
-                    "type": "string"
-                  },
-                  "surname": {
-                    "type": "string"
-                  },
-                  "id_num": {
-                    "type": "string"
-                  },
-                  "birthday": {
-                    "type": "string"
-                  },
-                  "citizen": {
-                    "type": "string"
-                  },
-                  "visited": {
-                    "type": "string"
-                  },
-                  "purpose": {
-                    "type": "string"
-                  },
-                  "country": {
-                    "type": "string"
-                  },
-                  "city": {
-                    "type": "string"
-                  },
-                  "address": {
-                    "type": "string"
+                  "status": {
+                    "type": "string",
+                    "enum": [
+                      "accepted",
+                      "processed"
+                    ],
+                    "description": "Accepted - the data was saved by the service for further processing\nProcessed - the data is processed and stored\n"
                   },
-                  "postal": {
-                    "type": "string"
+                  "created_at": {
+                    "type": "integer",
+                    "format": "int64",
+                    "example": 1721392530,
+                    "description": "Form submission time. Unix time."
                   },
-                  "phone": {
-                    "type": "string"
+                  "processed_at": {
+                    "type": "integer",
+                    "format": "int64",
+                    "example": 1721392530,
+                    "description": "Form processing time. Absent if the status is accepted. Unix time."
                   },
-                  "email": {
-                    "type": "string"
+                  "next_form_at": {
+                    "type": "integer",
+                    "format": "int64",
+                    "example": 1721392530,
+                    "description": "Time of the next possible form submission. Unix time."
                   },
-                  "image": {
-                    "type": "string",
-                    "description": "base64 encoded image with max size 4 MB"
+                  "until_next_form": {
+                    "type": "integer",
+                    "format": "int64",
+                    "example": 120,
+                    "description": "Time until the next form submission in seconds."
                   }
                 }
               }
@@ -359,23 +467,16 @@
           }
         ]
       },
-      "SubmitFormKey": {
+      "FormStatusKey": {
         "type": "object",
         "required": [
-          "id",
           "type"
         ],
         "properties": {
-          "id": {
-            "type": "string",
-            "example": "0x123...abc",
-            "pattern": "^0x[0-9a-fA-F]{64}$",
-            "description": "User nullifier 32 bytes"
-          },
           "type": {
             "type": "string",
             "enum": [
-              "submit_form"
+              "form_status"
             ]
           }
         }
@@ -471,11 +572,9 @@
     },
     "securitySchemes": {
       "BearerAuth": {
-        "BearerAuth": {
-          "type": "http",
-          "scheme": "bearer",
-          "bearerFormat": "JWT"
-        }
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "JWT"
       }
     }
   }
diff --git a/openapi.yaml b/openapi.yaml
index 5236f44..2407b9b 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -7,35 +7,49 @@ servers:
   - url: 'https://api.demo.tokend.io'
     description: TokenD Developer Environment
 paths:
-  '/integrations/forms-svc/v1/form/{id}':
-    get:
+  /integrations/forms-svc/v1/form:
+    post:
       tags:
         - User form
-      summary: Get form
+      summary: Submit lightweight user answers
       description: |
-        Get user form by UUID with status.
-        User must be authorized, but `is_verified` field is not required in JWT.
-      operationId: getForm
-      parameters:
-        - $ref: '#/components/parameters/pathID'
+        Send user answers and return their current status.
+
+        The image is a link to s3 storage
+
+        Only a user with a confirmed passport can send the form ('verified: true' in JWT).
+        There is a configurable delay before the same user
+        can submit another form.
+      operationId: lightweightSubmitForm
+      security:
+        - BearerAuth: []
+      requestBody:
+        content:
+          application/vnd.api+json:
+            schema:
+              type: object
+              required:
+                - data
+              properties:
+                data:
+                  $ref: '#/components/schemas/SubmitForm'
       responses:
         '200':
           description: Success
           content:
             application/vnd.api+json:
               schema:
-                type: object
-                required:
-                  - data
-                properties:
-                  data:
-                    $ref: '#/components/schemas/Form'
+                $ref: '#/components/schemas/FormStatus'
         '400':
           $ref: '#/components/responses/invalidParameter'
         '401':
           $ref: '#/components/responses/invalidAuth'
-        '404':
-          $ref: '#/components/responses/notFound'
+        '429':
+          description: It is necessary to wait some time before sending the next form
+          content:
+            application/vnd.api+json:
+              schema:
+                $ref: '#/components/schemas/Errors'
         '500':
           $ref: '#/components/responses/internalError'
   /integrations/forms-svc/v1/form/submit:
@@ -46,13 +60,14 @@ paths:
       description: |
         Send user answers and return their current status.
 
-        Only a user with a confirmed passport can send the form.
+        The image is a base64 string.
+
+        Only a user with a confirmed passport can send the form ('verified: true' in JWT).
         There is a configurable delay before the same user
         can submit another form.
       operationId: submitForm
       security:
-        - BearerAuth:
-            - 'verified: true'
+        - BearerAuth: []
       requestBody:
         content:
           application/vnd.api+json:
@@ -62,10 +77,10 @@ paths:
                 - data
               properties:
                 data:
-                  $ref: '#/components/schemas/SubmitForm'
+                  $ref: '#/components/schemas/Form'
       responses:
         '200':
-          description: Success
+          description: Success. All fields except image will be returned.
           content:
             application/vnd.api+json:
               schema:
@@ -82,6 +97,70 @@ paths:
                 $ref: '#/components/schemas/Errors'
         '500':
           $ref: '#/components/responses/internalError'
+  '/integrations/forms-svc/v1/status/{id}':
+    get:
+      tags:
+        - User form
+      summary: Get form status
+      description: |
+        Get form status by UUID.
+      operationId: getFormStatus
+      parameters:
+        - $ref: '#/components/parameters/pathID'
+      security:
+        - BearerAuth: []
+      responses:
+        '200':
+          description: Success
+          content:
+            application/vnd.api+json:
+              schema:
+                type: object
+                required:
+                  - data
+                properties:
+                  data:
+                    $ref: '#/components/schemas/Form'
+        '400':
+          $ref: '#/components/responses/invalidParameter'
+        '401':
+          $ref: '#/components/responses/invalidAuth'
+        '404':
+          $ref: '#/components/responses/notFound'
+        '500':
+          $ref: '#/components/responses/internalError'
+  /integrations/forms-svc/v1/status/last:
+    get:
+      tags:
+        - User form
+      summary: Get last form status
+      description: |
+        Get last form status filled out by the user nullifier.
+      operationId: getLastFormStatus
+      parameters:
+        - $ref: '#/components/parameters/pathNullifier'
+      security:
+        - BearerAuth: []
+      responses:
+        '200':
+          description: Success
+          content:
+            application/vnd.api+json:
+              schema:
+                type: object
+                required:
+                  - data
+                properties:
+                  data:
+                    $ref: '#/components/schemas/FormStatus'
+        '400':
+          $ref: '#/components/responses/invalidParameter'
+        '401':
+          $ref: '#/components/responses/invalidAuth'
+        '404':
+          $ref: '#/components/responses/notFound'
+        '500':
+          $ref: '#/components/responses/internalError'
 components:
   schemas:
     Errors:
@@ -128,7 +207,6 @@ components:
             attributes:
               type: object
               required:
-                - status
                 - name
                 - surname
                 - id_num
@@ -152,39 +230,54 @@ components:
                   description: |
                     Accepted - the data was saved by the service for further processing
                     Processed - the data is processed and stored
+                    Read-only.
                 name:
                   type: string
+                  example: Hilary
                 surname:
                   type: string
+                  example: Cabe
                 id_num:
                   type: string
+                  example: '3736297649'
                 birthday:
                   type: string
+                  example: 27/6/1988
                 citizen:
                   type: string
+                  example: Georgian
                 visited:
                   type: string
+                  example: 18/07/2024
                 purpose:
                   type: string
+                  example: Make documents
                 country:
                   type: string
+                  example: Georgia
                 city:
                   type: string
+                  example: Kutaisi
                 address:
                   type: string
+                  example: 'Central street, 1'
                 postal:
                   type: string
+                  example: '21626'
                 phone:
                   type: string
+                  example: '+13165282105'
                 email:
-                  type: string
+                  type: cabehilary88@gmail.com
                 image:
                   type: string
-                  description: base64 encoded image with max size 4 MB
+                  description: |
+                    base64 encoded image with max size 4 MB or
+                    URL for S3 storage with image up to 4 mb
+                  example: 'https://geoforms.nyc3.digitaloceanspaces.com/awesome_phono.jpg'
     FormKey:
       type: object
       required:
-        - id
         - type
       properties:
         id:
@@ -194,76 +287,59 @@ components:
           type: string
           enum:
             - form
-    SubmitForm:
+            - submit_form
+    FormStatus:
       allOf:
-        - $ref: '#/components/schemas/SubmitFormKey'
+        - $ref: '#/components/schemas/FormStatusKey'
         - type: object
-          x-go-is-request: true
           required:
             - attributes
           properties:
             attributes:
               type: object
               required:
-                - name
-                - surname
-                - id_num
-                - birthday
-                - citizen
-                - visited
-                - purpose
-                - country
-                - city
-                - address
-                - postal
-                - phone
-                - email
-                - image
+                - status
+                - created_at
+                - next_form_at
+                - until_next_form
               properties:
-                name:
-                  type: string
-                surname:
-                  type: string
-                id_num:
-                  type: string
-                birthday:
-                  type: string
-                citizen:
-                  type: string
-                visited:
-                  type: string
-                purpose:
-                  type: string
-                country:
-                  type: string
-                city:
-                  type: string
-                address:
-                  type: string
-                postal:
-                  type: string
-                phone:
-                  type: string
-                email:
-                  type: string
-                image:
+                status:
                   type: string
-                  description: base64 encoded image with max size 4 MB
-    SubmitFormKey:
+                  enum:
+                    - accepted
+                    - processed
+                  description: |
+                    Accepted - the data was saved by the service for further processing
+                    Processed - the data is processed and stored
+                created_at:
+                  type: integer
+                  format: int64
+                  example: 1721392530
+                  description: Form submission time. Unix time.
+                processed_at:
+                  type: integer
+                  format: int64
+                  example: 1721392530
+                  description: Form processing time. Absent if the status is accepted. Unix time.
+                next_form_at:
+                  type: integer
+                  format: int64
+                  example: 1721392530
+                  description: Time of the next possible form submission. Unix time.
+                until_next_form:
+                  type: integer
+                  format: int64
+                  example: 120
+                  description: Time until the next form submission in seconds.
+    FormStatusKey:
       type: object
       required:
-        - id
         - type
       properties:
-        id:
-          type: string
-          example: 0x123...abc
-          pattern: '^0x[0-9a-fA-F]{64}$'
-          description: User nullifier 32 bytes
         type:
           type: string
           enum:
-            - submit_form
+            - form_status
   responses:
     internalError:
       description: Internal server error
@@ -327,7 +403,6 @@ components:
         description: 'Order of records on the page. If sortingParam is not specified, order of records is by default sorted by ID.'
   securitySchemes:
     BearerAuth:
-      BearerAuth:
-        type: http
-        scheme: bearer
-        bearerFormat: JWT
+      type: http
+      scheme: bearer
+      bearerFormat: JWT