@portpowered/reference-data 0.4.1 → 0.4.3

package/generated/public/docs/references/schemas/Plugin.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "oneOf": [
+    {
+      "$ref": "/docs/references/schemas/WebsocketPlugin.json"
+    },
+    {
+      "$ref": "/docs/references/schemas/HttpPlugin.json"
+    },
+    {
+      "$ref": "/docs/references/schemas/WebservicePlugin.json"
+    },
+    {
+      "$ref": "/docs/references/schemas/ApplePushNotificationPlugin.json"
+    },
+    {
+      "$ref": "/docs/references/schemas/HostedComputePlugin.json"
+    },
+    {
+      "$ref": "/docs/references/schemas/LocalPlugin.json"
+    }
+  ],
+  "discriminator": {
+    "propertyName": "type",
+    "mapping": {
+      "WEBSOCKET": "/docs/references/schemas/WebsocketPlugin.json",
+      "HTTP": "/docs/references/schemas/HttpPlugin.json",
+      "WEBSERVICE": "/docs/references/schemas/WebservicePlugin.json",
+      "APPLE_PUSH_NOTIFICATION": "/docs/references/schemas/ApplePushNotificationPlugin.json",
+      "HOSTED_COMPUTE": "/docs/references/schemas/HostedComputePlugin.json",
+      "LOCAL": "/docs/references/schemas/LocalPlugin.json"
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginAttributePayload.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "attributes"
+  ],
+  "properties": {
+    "attributes": {
+      "type": "array",
+      "items": {
+        "$ref": "/docs/references/schemas/PluginAttributeValue.json"
+      }
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginAttributeReportRequestEvent.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "description": "Event sent by a plugin to report attribute values to the attribute store.",
+  "required": [
+    "header",
+    "authentication",
+    "target",
+    "payload"
+  ],
+  "properties": {
+    "header": {
+      "allOf": [
+        {
+          "$ref": "/docs/references/schemas/EventHeader.json"
+        },
+        {
+          "type": "object",
+          "required": [
+            "namespace",
+            "name",
+            "version"
+          ],
+          "properties": {
+            "namespace": {
+              "type": "string",
+              "x-enum-exempt": "plugin event header protocol identifiers",
+              "enum": [
+                "portos.attributeStore"
+              ]
+            },
+            "name": {
+              "type": "string",
+              "x-enum-exempt": "plugin event header protocol identifiers",
+              "enum": [
+                "reportAttributes"
+              ]
+            },
+            "version": {
+              "type": "string",
+              "x-enum-exempt": "plugin event header protocol identifiers",
+              "enum": [
+                "1.0"
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "authentication": {
+      "$ref": "/docs/references/schemas/PluginAuthentication.json"
+    },
+    "target": {
+      "$ref": "/docs/references/schemas/EventTarget.json"
+    },
+    "payload": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginAttributeReportResponseEvent.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "description": "Response event returned after processing an attribute report request.",
+  "required": [
+    "header",
+    "authentication",
+    "target",
+    "payload"
+  ],
+  "properties": {
+    "header": {
+      "allOf": [
+        {
+          "$ref": "/docs/references/schemas/EventHeader.json"
+        },
+        {
+          "type": "object",
+          "required": [
+            "namespace",
+            "name",
+            "version"
+          ],
+          "properties": {
+            "namespace": {
+              "type": "string",
+              "x-enum-exempt": "plugin event header protocol identifiers",
+              "enum": [
+                "portos.attributeStore"
+              ]
+            },
+            "name": {
+              "type": "string",
+              "x-enum-exempt": "plugin event header protocol identifiers",
+              "enum": [
+                "attributesReport"
+              ]
+            },
+            "version": {
+              "type": "string",
+              "x-enum-exempt": "plugin event header protocol identifiers",
+              "enum": [
+                "1.0"
+              ]
+            }
+          }
+        }
+      ]
+    },
+    "authentication": {
+      "$ref": "/docs/references/schemas/PluginAuthentication.json"
+    },
+    "target": {
+      "$ref": "/docs/references/schemas/EventTarget.json"
+    },
+    "payload": {
+      "$ref": "/docs/references/schemas/PluginAttributePayload.json"
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginAttributeValue.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "namespace",
+    "name",
+    "version"
+  ],
+  "properties": {
+    "namespace": {
+      "type": "string"
+    },
+    "name": {
+      "type": "string"
+    },
+    "version": {
+      "type": "string"
+    },
+    "value": {
+      "type": "object",
+      "additionalProperties": true
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginAuthCodeExchangeRequest.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "pluginId",
+    "principalId",
+    "pluginAuthenticationData"
+  ],
+  "properties": {
+    "pluginId": {
+      "type": "string",
+      "description": "The ID of the plugin for which we are attempting to exchange the code for an access token for."
+    },
+    "principalId": {
+      "type": "string",
+      "description": "The ID of the principal to exchange the code for an access token for, or alternatively ~self, when the target is the current user principal."
+    },
+    "pluginAuthenticationData": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "The data to exchange the code with. This is opaque data that is bespoke to the plugin and the plugin's authentication flow."
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginAuthCodeLinkRequest.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "pluginId",
+    "principalId"
+  ],
+  "properties": {
+    "pluginId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Canonical ID of a plugin declaring code-link authentication."
+    },
+    "principalId": {
+      "type": "string",
+      "x-enum-exempt": "principal identifier alias",
+      "enum": [
+        "~self"
+      ],
+      "description": "Start linking for the authenticated Port OS principal."
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginAuthCodeLinkResponse.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "sessionId",
+    "userCode",
+    "verificationUri",
+    "expiresIn"
+  ],
+  "properties": {
+    "sessionId": {
+      "type": "string",
+      "description": "Opaque, principal-bound session ID used for plugin-auth-code-exchange. Not a vendor private code."
+    },
+    "userCode": {
+      "type": "string",
+      "description": "Public code the user enters on the vendor's verification page."
+    },
+    "verificationUri": {
+      "type": "string",
+      "format": "uri",
+      "description": "Vendor verification page where the user signs in and approves linking."
+    },
+    "expiresIn": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Session lifetime in seconds. Expired sessions require starting again."
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginAuthMultifactorExchangeRequest.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "pluginId",
+    "principalId",
+    "pluginAuthenticationData"
+  ],
+  "properties": {
+    "pluginId": {
+      "type": "string",
+      "description": "The ID of the plugin for which we are attempting to receive the multifactor code for."
+    },
+    "principalId": {
+      "type": "string",
+      "description": "The ID of the principal to setup the auth link for, or alternatively ~self, when the target is the current user principal."
+    },
+    "pluginAuthenticationData": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "The data to exchange the multifactor code with. This is opaque data that is bespoke to the plugin and the plugin's authentication flow."
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginAuthentication.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "type",
+    "value"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": [
+        "BEARER_TOKEN"
+      ]
+    },
+    "value": {
+      "type": "string",
+      "description": "The authentication token"
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginAuthorization.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "type"
+  ],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": [
+        "OAUTH",
+        "API_KEY",
+        "NONE"
+      ],
+      "description": "The type of authorization"
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginCapabilityInterface.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "name",
+    "version"
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Capability interface name"
+    },
+    "version": {
+      "type": "string",
+      "description": "Capability interface version"
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginDataType.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "string",
+  "x-enum-exempt": "identifier URL path segments",
+  "enum": [
+    "plugins",
+    "endpoints",
+    "routes",
+    "capability-interfaces",
+    "messages"
+  ],
+  "description": "Data types related to plugins and endpoints",
+  "example": "endpoints"
+}

package/generated/public/docs/references/schemas/PluginDiscoveryRelationship.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "description": "A provider-reported relationship between routes and group routes. Identity is `externalId` within the reporting plugin and auth link; resubmitting the same `externalId` updates the relationship. Omission from a later synchronization is not a deletion instruction.\n",
+  "additionalProperties": false,
+  "required": [
+    "externalId",
+    "type",
+    "source",
+    "target"
+  ],
+  "properties": {
+    "externalId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Plugin-owned stable identifier of the relationship."
+    },
+    "type": {
+      "$ref": "/docs/references/schemas/RelationshipType.json"
+    },
+    "source": {
+      "$ref": "/docs/references/schemas/PluginDiscoveryRelationshipVertex.json"
+    },
+    "target": {
+      "$ref": "/docs/references/schemas/PluginDiscoveryRelationshipVertex.json"
+    },
+    "interfaces": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Optional interface applicability; used by `CAN_CONTROL` to declare which messages the source supports on the target.",
+      "items": {
+        "$ref": "/docs/references/schemas/RelationshipInterface.json"
+      }
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginDiscoveryRelationshipVertex.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "description": "One end of a discovered relationship, addressed by plugin-owned identity within the reporting plugin and auth link. Exactly one of `pluginRouteId` (a route) or `groupPluginRouteId` (a group route) must be set.\n",
+  "additionalProperties": false,
+  "minProperties": 1,
+  "maxProperties": 1,
+  "properties": {
+    "pluginRouteId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The plugin route ID of a route reported in the same or an earlier synchronization."
+    },
+    "groupPluginRouteId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The plugin route ID of a group route reported in the same or an earlier synchronization."
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginDispatchError.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "description": "Canonical Port OS plugin dispatch error. This contract is used when a plugin reports a third-party service, bridge, or device failure during message dispatch. It is inspired by Alexa-style error responses, but the type and family values are Port OS-specific.\n",
+  "required": [
+    "type",
+    "family",
+    "code",
+    "message"
+  ],
+  "properties": {
+    "type": {
+      "$ref": "/docs/references/schemas/PluginDispatchErrorType.json"
+    },
+    "family": {
+      "$ref": "/docs/references/schemas/PluginDispatchErrorFamily.json"
+    },
+    "code": {
+      "type": "string",
+      "description": "Opaque plugin or provider debug code suitable for support.",
+      "example": "hue-bridge-timeout"
+    },
+    "message": {
+      "type": "string",
+      "description": "Human-readable explanation of the plugin dispatch failure.",
+      "example": "The living room bridge is offline."
+    },
+    "details": {
+      "$ref": "/docs/references/schemas/ErrorDetails.json"
+    }
+  },
+  "example": {
+    "type": "ENDPOINT_UNREACHABLE",
+    "family": "ENDPOINT_UNAVAILABLE",
+    "code": "device-offline",
+    "message": "The device is not reachable.",
+    "details": {
+      "endpointId": "port1:principal:example:endpoints/lamp-1",
+      "pluginId": "port1.plugin.hue",
+      "pluginRouteId": "hue-device-42"
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginDispatchErrorFamily.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "string",
+  "description": "Canonical plugin dispatch error family. The family controls the default `/messages/send` HTTP status mapping for plugin-originated failures.\n",
+  "enum": [
+    "REQUEST_INVALID",
+    "AUTHENTICATION",
+    "PERMISSION",
+    "ENDPOINT_NOT_FOUND",
+    "ENDPOINT_STATE_CONFLICT",
+    "ENDPOINT_UNAVAILABLE",
+    "RATE_LIMIT",
+    "PROVIDER_BAD_RESPONSE",
+    "PROVIDER_UNAVAILABLE",
+    "PROVIDER_TIMEOUT"
+  ]
+}

package/generated/public/docs/references/schemas/PluginDispatchErrorType.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "string",
+  "description": "Canonical machine-readable plugin dispatch error type. Plugins use these values when a third-party service, bridge, or device cannot complete a message dispatch.\n",
+  "enum": [
+    "ENDPOINT_UNREACHABLE",
+    "BRIDGE_UNREACHABLE",
+    "CLOUD_CONTROL_DISABLED",
+    "ENDPOINT_BUSY",
+    "ENDPOINT_LOW_POWER",
+    "AUTHORIZATION_CREDENTIAL_INVALID",
+    "AUTHORIZATION_CREDENTIAL_EXPIRED",
+    "INSUFFICIENT_PERMISSIONS",
+    "INVALID_DIRECTIVE",
+    "INVALID_VALUE",
+    "VALUE_OUT_OF_RANGE",
+    "NOT_SUPPORTED_IN_CURRENT_MODE",
+    "MAP_NOT_ACTIVE",
+    "RATE_LIMIT_EXCEEDED",
+    "PROVIDER_SERVICE_UNAVAILABLE",
+    "PROVIDER_TIMEOUT",
+    "PROVIDER_INTERNAL_ERROR"
+  ]
+}

package/generated/public/docs/references/schemas/PluginEntry.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "name",
+    "region",
+    "uri",
+    "type",
+    "interfaces",
+    "authorization"
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "The name of the plugin entry"
+    },
+    "region": {
+      "type": "string",
+      "description": "The region of the plugin entry"
+    },
+    "uri": {
+      "type": "string",
+      "description": "The URI endpoint for the plugin"
+    },
+    "type": {
+      "type": "string",
+      "description": "The type of the plugin entry"
+    },
+    "interfaces": {
+      "type": "array",
+      "items": {
+        "$ref": "/docs/references/schemas/ApplicationInterface.json"
+      },
+      "description": "List of interfaces supported by the plugin"
+    },
+    "authorization": {
+      "$ref": "/docs/references/schemas/PluginAuthorization.json"
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginMetadataMultifactor.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "fields": {
+      "type": "array",
+      "items": {
+        "$ref": "/docs/references/schemas/PluginMetadataMultifactorField.json"
+      },
+      "description": "List of multifactor authentication fields"
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginMetadataMultifactorField.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": [
+    "key",
+    "label",
+    "type"
+  ],
+  "properties": {
+    "key": {
+      "type": "string",
+      "description": "Field key identifier"
+    },
+    "label": {
+      "type": "string",
+      "description": "Human-readable label for the field"
+    },
+    "type": {
+      "type": "string",
+      "description": "Field input type"
+    }
+  }
+}

package/generated/public/docs/references/schemas/PluginMetadataOAuth.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "clientId": {
+      "type": "string",
+      "description": "OAuth2 client ID"
+    },
+    "clientSecret": {
+      "type": "string",
+      "description": "OAuth2 client secret. Only included when the caller explicitly requests expand=oauth.clientSecret and only for direct-variant plugins (never exposed for backend-proxy variants). Used by the website to complete PKCE token exchanges client-side."
+    },
+    "authorizeUrl": {
+      "type": "string",
+      "description": "OAuth2 authorization URL"
+    },
+    "tokenUrl": {
+      "type": "string",
+      "description": "OAuth2 token URL"
+    },
+    "scope": {
+      "type": "string",
+      "description": "OAuth2 scope"
+    },
+    "requiresCodeVerifier": {
+      "type": "boolean",
+      "description": "Whether PKCE code verifier is required"
+    },
+    "additionalAuthorizeParams": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      },
+      "description": "Additional query parameters that the website appends to the OAuth2 authorization URL when redirecting the user to the provider's consent screen (e.g., access_type=offline, prompt=consent)."
+    },
+    "oauthVariant": {
+      "type": "string",
+      "enum": [
+        "DIRECT",
+        "BACKEND_PROXY"
+      ],
+      "x-enum-varnames": [
+        "OAuthVariantDirect",
+        "OAuthVariantBackendProxy"
+      ],
+      "description": "OAuth flow variant. \"DIRECT\" means the website performs the full PKCE token exchange client-side. \"BACKEND_PROXY\" means the website sends the authorization code to the Port OS backend, which exchanges it for tokens on behalf of the user."
+    }
+  }
+}