improve error handling, add request body validation

ts-connector-sdk/package.json

@@ -2,7 +2,7 @@
   "name": "ts-connector-sdk",
   "version": "1.0.0",
   "description": "",
-  "main": "index.js",
+  "main": "src/index.js",
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1",
     "generate-types": "ts-node generate-types.ts"
@@ -11,6 +11,7 @@
   "author": "",
   "license": "ISC",
   "dependencies": {
+    "@json-schema-tools/meta-schema": "^1.7.0",
     "@types/node": "^20.6.0",
     "commander": "^11.0.0",
     "fastify": "^4.23.2",

ts-connector-sdk/schemas/CapabilitiesResponse.schema.json

@@ -0,0 +1,73 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Capabilities Response",
+  "type": "object",
+  "required": [
+    "capabilities",
+    "versions"
+  ],
+  "properties": {
+    "capabilities": {
+      "$ref": "#/definitions/Capabilities"
+    },
+    "versions": {
+      "type": "string"
+    }
+  },
+  "definitions": {
+    "Capabilities": {
+      "title": "Capabilities",
+      "description": "Describes the features of the specification which a data connector implements.",
+      "type": "object",
+      "properties": {
+        "explain": true,
+        "mutations": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/MutationCapabilities"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "query": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/QueryCapabilities"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "relationships": true
+      }
+    },
+    "MutationCapabilities": {
+      "title": "Mutation Capabilities",
+      "type": "object",
+      "properties": {
+        "nested_inserts": {
+          "description": "Whether or not nested inserts to related collections are supported"
+        },
+        "returning": true
+      }
+    },
+    "QueryCapabilities": {
+      "title": "Query Capabilities",
+      "type": "object",
+      "properties": {
+        "foreach": {
+          "description": "Does the agent support foreach queries, i.e. queries with variables"
+        },
+        "order_by_aggregate": {
+          "description": "Does the agent support ordering by an aggregated array relationship?"
+        },
+        "relation_comparisons": {
+          "description": "Does the agent support comparisons that involve related collections (ie. joins)?"
+        }
+      }
+    }
+  }
+}

ts-connector-sdk/schemas/ErrorResponse.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Error Response",
+  "type": "object",
+  "required": [
+    "details",
+    "message"
+  ],
+  "properties": {
+    "details": {
+      "description": "Any additional structured information about the error"
+    },
+    "message": {
+      "description": "A human-readable summary of the error",
+      "type": "string"
+    }
+  }
+}

ts-connector-sdk/schemas/ExplainResponse.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Explain Response",
+  "type": "object",
+  "required": [
+    "details"
+  ],
+  "properties": {
+    "details": {
+      "description": "A list of human-readable key-value pairs describing a query execution plan. For example, a connector for a relational database might return the generated SQL and/or the output of the `EXPLAIN` command. An API-based connector might encode a list of statically-known API calls which would be made.",
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    }
+  }
+}