Add usage and schema report specifications to docs (#135)

* Add usage and schema report specifications to docs

* Add Lighthouse GraphQL Hive

packages/web/docs/pages/features/monitoring.mdx

@@ -179,3 +179,9 @@ const server = new ApolloServer({
 Once this is done, and you start collecting the analytics as relevant you will be able to find all the analytics collected in the Operations Dashboard as seen below which you can then drill into
 
 ![Monitoring view](../../public/monitoring-view.png)
+
+## 3rd-party integrations
+
+Here's a list of community-supported integrations:
+
+- [(php) Lighthouse GraphQL Hive](https://github.com/stayallive/lighthouse-graphql-hive)

packages/web/docs/pages/meta.json

@@ -1,4 +1,6 @@
 {
   "index": "Introduction",
-  "get-started": "Get Started"
+  "get-started": "Get Started",
+  "features": "Features",
+  "specs": "Specifications"
 }

packages/web/docs/pages/specs/integrations.md

@@ -0,0 +1,5 @@
+# Integrations
+
+Writing a third-party integration? We'd love to hear about it and help you!
+
+Contact us at [contact@the-guild.dev](mailto:contact@the-guild.dev) or using the chat available in the bottom right corner of the page.

packages/web/docs/pages/specs/meta.json

@@ -0,0 +1,5 @@
+{
+  "integrations": "Integrations",
+  "usage-reports": "Usage Reports",
+  "schema-reports": "Schema Reports"
+}

packages/web/docs/pages/specs/schema-reports.md

@@ -0,0 +1,75 @@
+# Schema reports
+
+Technical details about the schema reports.
+
+| Name     | Value                                                   |
+| -------- | ------------------------------------------------------- |
+| Endpoint | `https://app.graphql-hive.com/registry`                 |
+| Header   | `X-API-Token: token-here`                               |
+| Method   | `POST`                                                  |
+| Body     | GraphQL Request - `{ query, operationName, variables }` |
+
+```graphql
+input SchemaPublishInput {
+  """
+  Name of the service (applicable only for Federation and Stitching)
+  """
+  service: ID
+  """
+  An url of the service (applicable only for Federation and Stitching)
+  """
+  url: String
+  """
+  Schema definitions
+  """
+  sdl: String!
+  """
+  Author of the changes
+  """
+  author: String!
+  """
+  Unique identifier of the changes
+  """
+  commit: String!
+  """
+  GraphQL Hive prevents from publishing breaking changes or broken schemas by default, use this flag to override this behavior.
+  """
+  force: Boolean
+}
+
+mutation schemaPublish($input: SchemaPublishInput!) {
+  schemaPublish(input: $input) {
+    __typename
+    ... on SchemaPublishSuccess {
+      initial
+      valid
+      changes {
+        nodes {
+          message
+          criticality
+        }
+        total
+      }
+    }
+    ... on SchemaPublishError {
+      valid
+      changes {
+        nodes {
+          message
+          criticality
+        }
+        total
+      }
+      errors {
+        nodes {
+          message
+        }
+        total
+      }
+    }
+    ... on SchemaPublishMissingServiceError {
+      message
+    }
+  }
+}
+```

packages/web/docs/pages/specs/usage-reports.md

@@ -0,0 +1,260 @@
+# Usage reports
+
+The official JavaScript Hive Client (`@graphql-hive/client`) collects executed operations and sends them in batches (as a single report, when a buffer is full or every few seconds) over HTTP.
+
+> It's recommended to send a report for more than 1 operation.
+> The maximum payload size is 1 MB.
+
+| Name     | Value                                |
+| -------- | ------------------------------------ |
+| Endpoint | `https://app.graphql-hive.com/usage` |
+| Header   | `X-API-Token: token-here`            |
+| Method   | `POST`                               |
+
+**Data structure**
+
+<details>
+  <summary>TypeScript schema</summary>
+
+```typescript
+export interface Report {
+  /**
+   * Number of collected operations
+   */
+  size: number
+  map: OperationMap
+  operations: Operation[]
+}
+
+export interface OperationMap {
+  [key: string]: OperationMapRecord
+}
+
+export interface OperationMapRecord {
+  /**
+   * Operation's body
+   * e.g. query me { me { id name } }
+   */
+  operation: string
+  /**
+   * Name of the operation ('me')
+   */
+  operationName?: string
+  /**
+   * Schema coordinates (['Query', 'Query.me', 'User', 'User.id', 'User.name'])
+   */
+  fields: string[]
+}
+
+export interface Operation {
+  /**
+   * The key of the operation in the operation map
+   */
+  operationMapKey: string
+  /**
+   * A number representing the milliseconds elapsed since the UNIX epoch.
+   */
+  timestamp: number
+  execution: Execution
+  metadata?: Metadata
+}
+
+export interface Execution {
+  /**
+   * true - successful operation
+   * false - failed operation
+   */
+  ok: boolean
+  /**
+   * Duration of the entire operation in nanoseconds
+   */
+  duration: number
+  /**
+   * Total number of GraphQL errors
+   */
+  errorsTotal: number
+}
+
+export interface Metadata {
+  client?: Client
+}
+
+export interface Client {
+  name?: string
+  version?: string
+}
+```
+
+</details>
+
+<details>
+  <summary>JSON Schema</summary>
+
+```json
+{
+  "$ref": "#/definitions/Report",
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "definitions": {
+    "Client": {
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "version": {
+          "type": "string"
+        }
+      },
+      "type": "object"
+    },
+    "Execution": {
+      "additionalProperties": false,
+      "properties": {
+        "duration": {
+          "description": "Duration of the entire operation in nanoseconds",
+          "type": "number"
+        },
+        "errorsTotal": {
+          "description": "Total number of GraphQL errors",
+          "type": "number"
+        },
+        "ok": {
+          "description": "true - successful operation false - failed operation",
+          "type": "boolean"
+        }
+      },
+      "required": ["ok", "duration", "errorsTotal"],
+      "type": "object"
+    },
+    "Metadata": {
+      "additionalProperties": false,
+      "properties": {
+        "client": {
+          "$ref": "#/definitions/Client"
+        }
+      },
+      "type": "object"
+    },
+    "Operation": {
+      "additionalProperties": false,
+      "properties": {
+        "execution": {
+          "$ref": "#/definitions/Execution"
+        },
+        "metadata": {
+          "$ref": "#/definitions/Metadata"
+        },
+        "operationMapKey": {
+          "description": "The key of the operation in the operation map",
+          "type": "string"
+        },
+        "timestamp": {
+          "description": "A number representing the milliseconds elapsed since the UNIX epoch.",
+          "type": "number"
+        }
+      },
+      "required": ["operationMapKey", "timestamp", "execution"],
+      "type": "object"
+    },
+    "OperationMap": {
+      "additionalProperties": {
+        "$ref": "#/definitions/OperationMapRecord"
+      },
+      "type": "object"
+    },
+    "OperationMapRecord": {
+      "additionalProperties": false,
+      "properties": {
+        "fields": {
+          "description": "Schema coordinates (['Query', 'Query.me', 'User', 'User.id', 'User.name'])",
+          "items": {
+            "type": "string"
+          },
+          "type": "array"
+        },
+        "operation": {
+          "description": "Operation's body e.g. query me { me { id name } }",
+          "type": "string"
+        },
+        "operationName": {
+          "description": "Name of the operation ('me')",
+          "type": "string"
+        }
+      },
+      "required": ["operation", "fields"],
+      "type": "object"
+    },
+    "Report": {
+      "additionalProperties": false,
+      "properties": {
+        "map": {
+          "$ref": "#/definitions/OperationMap"
+        },
+        "operations": {
+          "items": {
+            "$ref": "#/definitions/Operation"
+          },
+          "type": "array"
+        },
+        "size": {
+          "description": "Number of collected operations",
+          "type": "number"
+        }
+      },
+      "required": ["size", "map", "operations"],
+      "type": "object"
+    }
+  }
+}
+```
+
+</details>
+
+**Example**
+
+```json
+{
+  "size": 3,
+  "map": {
+    "c3b6d9b0": {
+      "operationName": "me",
+      "operation": "query me { me { id name } }",
+      "fields": ["Query", "Query.me", "User", "User.id", "User.name"]
+    },
+    "762a45e3": {
+      "operationName": "users",
+      "operation": "query users { users { id } }",
+      "fields": ["Query", "Query.users", "User", "User.id"]
+    }
+  },
+  "operations": [
+    {
+      "operationMapKey": "c3b6d9b0", // points to the 'me' query
+      "timestamp": 1655112281535,
+      "execution": {
+        "ok": true,
+        "duration": 150000000, // 150ms in nanoseconds
+        "errorsTotal": 0
+      }
+    },
+    {
+      "operationMapKey": "c3b6d9b0", // points to the 'me' query
+      "timestamp": 1655112327589,
+      "execution": {
+        "ok": false, // failed operation
+        "duration": 150000000, // 150ms in nanoseconds
+        "errorsTotal": 1 // 1 GraphQL error
+      }
+    },
+    {
+      "operationMapKey": "762a45e3", // points to the 'users' query
+      "timestamp": 1655112327589,
+      "execution": {
+        "ok": true,
+        "duration": 150000000, // 150ms in nanoseconds
+        "errorsTotal": 0
+      }
+    }
+  ]
+}
+```