@huynle/hub 0.11.0 → 0.11.1

package/packages/protocol/schema/api/v1/discovery.json

@@ -0,0 +1,110 @@
+{
+  "paths": {
+    "/.well-known/hub": {
+      "get": {
+        "operationId": "getHubDiscovery",
+        "tags": [
+          "discovery"
+        ],
+        "x-hub-access": "public",
+        "security": [],
+        "summary": "Discover a hub",
+        "description": "The one operation outside /api/v1: what a client reads first, before signing in, to know it talks to a hub, which version, how people sign in and whether it may go on. A client older than `minClientVersion` must not use the hub. Cached publicly for 60 seconds.",
+        "responses": {
+          "200": {
+            "description": "The hub.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HubDiscovery"
+                }
+              }
+            }
+          },
+          "default": {
+            "$ref": "#/components/responses/Error"
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "HubDiscovery": {
+        "type": "object",
+        "required": [
+          "publicURL",
+          "version",
+          "minClientVersion",
+          "auth",
+          "features"
+        ],
+        "properties": {
+          "publicURL": {
+            "type": "string",
+            "description": "The address the hub is reached at, without a trailing slash."
+          },
+          "version": {
+            "type": "string",
+            "description": "The hub's version."
+          },
+          "minClientVersion": {
+            "type": "string",
+            "description": "The oldest client version (native app, CLI) this hub serves."
+          },
+          "auth": {
+            "$ref": "#/components/schemas/HubDiscoveryAuth"
+          },
+          "features": {
+            "type": "array",
+            "description": "What the hub offers apps beyond the base API.",
+            "items": {
+              "type": "string",
+              "x-hub-known": [
+                "app-connect",
+                "app-speech",
+                "app-conversation",
+                "app-decisions"
+              ]
+            }
+          }
+        }
+      },
+      "HubDiscoveryAuth": {
+        "type": "object",
+        "required": [
+          "modes"
+        ],
+        "properties": {
+          "modes": {
+            "type": "array",
+            "description": "How a device can join: oidc, the hub's identity provider (then pairing codes work too, issued by a signed-in device); pairing, a pairing or link code.",
+            "items": {
+              "type": "string",
+              "x-hub-known": [
+                "oidc",
+                "pairing"
+              ]
+            }
+          },
+          "oidc": {
+            "$ref": "#/components/schemas/HubDiscoveryOidc"
+          }
+        }
+      },
+      "HubDiscoveryOidc": {
+        "type": "object",
+        "required": [
+          "issuer"
+        ],
+        "description": "Present when the hub signs people in with OIDC.",
+        "properties": {
+          "issuer": {
+            "type": "string",
+            "description": "The identity provider's issuer URL."
+          }
+        }
+      }
+    }
+  }
+}