@portpowered/reference-data 0.0.0-stage → 0.4.0

package/generated/public/docs/for-ai/operations/sendMessageLegacyAlias.md

@@ -0,0 +1,279 @@
+# sendMessageLegacyAlias
+
+POST `/messages/send`
+
+
+
+Compatibility alias for POST /messages. Sends a message to a recipient.
+
+Plugin-originated dispatch errors use the canonical plugin dispatch error
+contract: `type`, `family`, `code`, `message`, and optional typed `details`.
+Fire-and-forget requests can only return plugin errors detected before the
+request is accepted. Synchronous requests can also map a correlated
+`portos/errorResponse` plugin response into the HTTP error statuses below.
+
+Plugin dispatch error status mapping:
+
+| Plugin error family | Representative types | HTTP status |
+| --- | --- | --- |
+| `REQUEST_INVALID` | `INVALID_DIRECTIVE`, `INVALID_VALUE` | `400` |
+| `REQUEST_INVALID` | `VALUE_OUT_OF_RANGE` | `422` |
+| `AUTHENTICATION` | `AUTHORIZATION_CREDENTIAL_INVALID`, `AUTHORIZATION_CREDENTIAL_EXPIRED` | `401` |
+| `PERMISSION` | `INSUFFICIENT_PERMISSIONS`, `CLOUD_CONTROL_DISABLED` | `403` |
+| `ENDPOINT_NOT_FOUND` | no such endpoint or route | `404` |
+| `ENDPOINT_STATE_CONFLICT` | `ENDPOINT_BUSY`, `NOT_SUPPORTED_IN_CURRENT_MODE` | `409` |
+| `ENDPOINT_UNAVAILABLE` | `ENDPOINT_UNREACHABLE`, `ENDPOINT_LOW_POWER` | `423` |
+| `RATE_LIMIT` | `RATE_LIMIT_EXCEEDED` | `429` |
+| `PROVIDER_BAD_RESPONSE` | `PROVIDER_INTERNAL_ERROR` | `502` |
+| `PROVIDER_UNAVAILABLE` | `BRIDGE_UNREACHABLE`, `PROVIDER_SERVICE_UNAVAILABLE` | `503` |
+| `PROVIDER_TIMEOUT` | `PROVIDER_TIMEOUT` | `504` |
+
+
+## Authorization
+
+```yaml
+path: /messages/send
+runtimePath: /messages/send
+method: POST
+operationId: sendMessageLegacyAlias
+security:
+  - oauth2:
+      - message:send
+  - bearerAuth: []
+delegated: true
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /messages/send
+post:
+  operationId: sendMessageLegacyAlias
+  tags:
+    - Messages
+  description: >
+    Compatibility alias for POST /messages. Sends a message to a recipient.
+
+
+    Plugin-originated dispatch errors use the canonical plugin dispatch error
+
+    contract: `type`, `family`, `code`, `message`, and optional typed `details`.
+
+    Fire-and-forget requests can only return plugin errors detected before the
+
+    request is accepted. Synchronous requests can also map a correlated
+
+    `portos/errorResponse` plugin response into the HTTP error statuses below.
+
+
+    Plugin dispatch error status mapping:
+
+
+    | Plugin error family | Representative types | HTTP status |
+
+    | --- | --- | --- |
+
+    | `REQUEST_INVALID` | `INVALID_DIRECTIVE`, `INVALID_VALUE` | `400` |
+
+    | `REQUEST_INVALID` | `VALUE_OUT_OF_RANGE` | `422` |
+
+    | `AUTHENTICATION` | `AUTHORIZATION_CREDENTIAL_INVALID`, `AUTHORIZATION_CREDENTIAL_EXPIRED` |
+    `401` |
+
+    | `PERMISSION` | `INSUFFICIENT_PERMISSIONS`, `CLOUD_CONTROL_DISABLED` | `403` |
+
+    | `ENDPOINT_NOT_FOUND` | no such endpoint or route | `404` |
+
+    | `ENDPOINT_STATE_CONFLICT` | `ENDPOINT_BUSY`, `NOT_SUPPORTED_IN_CURRENT_MODE` | `409` |
+
+    | `ENDPOINT_UNAVAILABLE` | `ENDPOINT_UNREACHABLE`, `ENDPOINT_LOW_POWER` | `423` |
+
+    | `RATE_LIMIT` | `RATE_LIMIT_EXCEEDED` | `429` |
+
+    | `PROVIDER_BAD_RESPONSE` | `PROVIDER_INTERNAL_ERROR` | `502` |
+
+    | `PROVIDER_UNAVAILABLE` | `BRIDGE_UNREACHABLE`, `PROVIDER_SERVICE_UNAVAILABLE` | `503` |
+
+    | `PROVIDER_TIMEOUT` | `PROVIDER_TIMEOUT` | `504` |
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/CreateMessageRequest'
+        example:
+          target:
+            type: ENDPOINT
+            id: port1/principals/example/endpoints/example-light
+          message:
+            header:
+              namespace: port1/systems/zero/capability-interfaces/power
+              name: turn-on
+              version: '1.0'
+            body: {}
+  responses:
+    '200':
+      description: Message sent successfully
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/CreateMessageResponse'
+          example:
+            messageId: example-dispatch-id
+    '400':
+      description: Invalid request payload or plugin dispatch request error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            type: INVALID_VALUE
+            family: REQUEST_INVALID
+            code: provider-invalid-speed
+            message: Fan speed must be one of the supported values.
+            details:
+              parameter: speed
+              actual: storm
+    '401':
+      description: Plugin authorization credential is invalid or expired
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            type: AUTHORIZATION_CREDENTIAL_EXPIRED
+            family: AUTHENTICATION
+            code: provider-token-expired
+            message: The provider authorization has expired. Re-link the plugin.
+    '403':
+      description: Plugin provider denied the requested operation
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            type: INSUFFICIENT_PERMISSIONS
+            family: PERMISSION
+            code: provider-scope-missing
+            message: The linked account does not grant permission for this device.
+    '404':
+      description: Target endpoint or plugin route was not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            type: NOT_FOUND
+            family: NOT_FOUND
+            code: message-not-found
+            message: The linked account does not grant permission for this device.
+    '409':
+      description: Endpoint state conflicts with the requested message
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            type: NOT_SUPPORTED_IN_CURRENT_MODE
+            family: ENDPOINT_STATE_CONFLICT
+            code: device-mode-conflict
+            message: The command is not supported while the endpoint is in eco mode.
+            details:
+              currentMode: eco
+    '422':
+      description: Plugin rejected a semantically invalid message value
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            type: VALUE_OUT_OF_RANGE
+            family: REQUEST_INVALID
+            code: brightness-out-of-range
+            message: Brightness must be between 1 and 100.
+            details:
+              parameter: brightness
+              minimum: 1
+              maximum: 100
+              actual: '150'
+    '423':
+      description: Endpoint is unavailable, unreachable, locked, or low power
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            type: ENDPOINT_UNREACHABLE
+            family: ENDPOINT_UNAVAILABLE
+            code: device-offline
+            message: The device is not reachable.
+            details:
+              pluginId: port1.plugin.hue
+              pluginRouteId: hue-device-42
+    '429':
+      description: Plugin provider rate limit exceeded
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            type: RATE_LIMIT_EXCEEDED
+            family: RATE_LIMIT
+            code: provider-rate-limit
+            message: The provider rate limit was exceeded.
+            details:
+              retryAfterSeconds: 60
+    '500':
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            type: INTERNAL_SERVER_ERROR
+            family: INTERNAL_SERVER_ERROR
+            code: internal-server-error
+            message: The server failed
+    '502':
+      description: Plugin provider returned an invalid or internal error response
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            type: PROVIDER_INTERNAL_ERROR
+            family: PROVIDER_BAD_RESPONSE
+            code: provider-internal-error
+            message: The provider failed while handling the command.
+    '503':
+      description: Plugin provider or bridge is unavailable
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            type: PROVIDER_SERVICE_UNAVAILABLE
+            family: PROVIDER_UNAVAILABLE
+            code: vendor-outage
+            message: The provider service is temporarily unavailable.
+    '504':
+      description: Plugin provider timed out
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            type: PROVIDER_TIMEOUT
+            family: PROVIDER_TIMEOUT
+            code: provider-timeout
+            message: The provider did not respond before the timeout.
+  x-portos-delegated: true
+  x-portos-resource-permission: true
+  security:
+    - oauth2:
+        - message:send
+    - bearerAuth: []
+```
+
+Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

package/generated/public/docs/for-ai/operations/setEndpointGroupName.md

@@ -0,0 +1,145 @@
+# setEndpointGroupName
+
+POST `/{namespace}/{principalType}/{principalId}/endpoint-groups/{groupId}/set-name`
+
+Set endpoint group name
+
+Sets the name of an endpoint group
+
+## Authorization
+
+```yaml
+path: /{namespace}/{principalType}/{principalId}/endpoint-groups/{groupId}/set-name
+runtimePath: /{namespace}/{principalType}/{principalId}/endpoint-groups/{groupId}/set-name
+method: POST
+operationId: setEndpointGroupName
+security:
+  - oauth2:
+      - group:manage
+  - bearerAuth: []
+delegated: true
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /{namespace}/{principalType}/{principalId}/endpoint-groups/{groupId}/set-name
+post:
+  operationId: setEndpointGroupName
+  tags:
+    - Endpoint Groups
+  summary: Set endpoint group name
+  description: Sets the name of an endpoint group
+  security:
+    - oauth2:
+        - group:manage
+    - bearerAuth: []
+  parameters:
+    - name: namespace
+      in: path
+      required: true
+      schema:
+        type: string
+      description: The namespace of the principal
+    - name: principalType
+      in: path
+      required: true
+      schema:
+        type: string
+      description: The type of principal
+    - name: principalId
+      in: path
+      required: true
+      schema:
+        type: string
+      description: The ID of the principal
+    - name: groupId
+      in: path
+      required: true
+      schema:
+        type: string
+      description: The ID of the endpoint group
+    - $ref: '#/components/parameters/IfMatch'
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/SetEndpointGroupNameRequest'
+  responses:
+    '202':
+      description: Endpoint group name update accepted
+      headers:
+        ETag:
+          $ref: '#/components/headers/ETag'
+    '400':
+      description: Invalid request payload
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Invalid request payload
+            type: BAD_REQUEST
+    '401':
+      description: Unauthorized - invalid or missing authentication token
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Authentication required
+            type: UNAUTHORIZED
+    '403':
+      description: Forbidden - insufficient permissions
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Insufficient permissions
+            type: FORBIDDEN
+    '404':
+      description: Endpoint group not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Resource not found
+            type: NOT_FOUND
+    '412':
+      description: The If-Match etag does not match the current group version; re-read the group and retry
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: group etag does not match; re-read the group and retry
+            type: PRECONDITION_FAILED
+            family: PRECONDITION_FAILED
+    '428':
+      description: The If-Match header is missing
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: If-Match header is required; send the group's etag
+            type: PRECONDITION_REQUIRED
+            family: PRECONDITION_REQUIRED
+    '500':
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Internal server error
+            type: INTERNAL
+  x-portos-delegated: true
+  x-portos-resource-permission: true
+```
+
+Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

package/generated/public/docs/for-ai/operations/setFlowRunStatus.md

@@ -0,0 +1,121 @@
+# setFlowRunStatus
+
+POST `/{namespace}/{principalType}/{principalId}/flows/{flowId}/runs/{runId}/set-status`
+
+Set flow run status
+
+Sets the status of a flow run. This is an asynchronous operation — the server accepts the request and processes the status change.
+
+
+Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.
+
+## Authorization
+
+```yaml
+path: >-
+  /{namespace}/{principalType}/{principalId}/flows/{flowId}/runs/{runId}/set-status
+runtimePath: >-
+  /{namespace}/{principalType}/{principalId}/flows/{flowId}/runs/{runId}/set-status
+method: POST
+operationId: setFlowRunStatus
+security:
+  - bearerAuth: []
+delegated: false
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /{namespace}/{principalType}/{principalId}/flows/{flowId}/runs/{runId}/set-status
+post:
+  tags:
+    - FlowRuns
+  operationId: setFlowRunStatus
+  summary: Set flow run status
+  description: >-
+    Sets the status of a flow run. This is an asynchronous operation — the server accepts the
+    request and processes the status change.
+
+
+
+    Requires a signed user/session or the existing authenticated client flow. The anonymous DCR
+    delegated device profile cannot invoke this operation.
+  security:
+    - bearerAuth: []
+  parameters:
+    - name: namespace
+      in: path
+      required: true
+      schema:
+        type: string
+      description: The namespace of the principal that the flow belongs to.
+    - name: principalType
+      in: path
+      required: true
+      schema:
+        type: string
+      description: The type of principal that the flow belongs to.
+    - name: principalId
+      in: path
+      required: true
+      schema:
+        type: string
+      description: The ID of the principal that the flow belongs to.
+    - name: flowId
+      in: path
+      required: true
+      schema:
+        type: string
+      description: The ID of the flow that the run belongs to.
+    - name: runId
+      in: path
+      required: true
+      schema:
+        type: string
+      description: The ID of the flow run to set the status of.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/SetFlowRunStatusRequest'
+        example:
+          id: port1/principals/user123/resources/abc-123
+  responses:
+    '202':
+      description: >-
+        Accepted — status change request received. The flow run lifecycle will be updated
+        accordingly.
+    '400':
+      description: Bad request — invalid request payload.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Invalid request payload
+            type: BAD_REQUEST
+    '401':
+      description: Unauthorized — invalid or missing authentication token.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Authentication required
+            type: UNAUTHORIZED
+    '403':
+      description: Forbidden — insufficient permissions.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Insufficient permissions
+            type: FORBIDDEN
+  x-portos-delegated: false
+  x-portos-resource-permission: true
+```
+
+Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

package/generated/public/docs/for-ai/operations/synchronizeRoutes.md

@@ -0,0 +1,141 @@
+# synchronizeRoutes
+
+POST `/discovery`
+
+Synchronize Plugin Routes via Discovery
+
+Triggers route synchronization for a plugin. When a plugin connected to Port OS wants to report the routes available on it, it dispatches a discovery payload. The server reconciles the reported routes with its internal state. For newly persisted synchronized routes, the server can assign a backend-generated, owner-scoped Port OS route `id`; a client-supplied route `id` in the discovery payload is advisory and is not the stable lookup surface for plugin capability parity. Consumers that need to match synchronized plugin or fixture routes after enumeration should use `associatedPluginRouteId`, which preserves the plugin-owned route identity.
+
+Every route and group-route interface must name a capability interface and exact version from the capability-interface library, its `configuration` must conform to that interface's configuration schema (an omitted configuration is validated as an empty object), and any declared attribute must exist on the interface with a value that conforms to its attribute schema. Any nonconforming item rejects the whole request with 400; `errors` lists every rejected item keyed by `pluginRouteId`. Nothing is persisted.
+
+Group routes and relationships are keyed by plugin-owned identity within the plugin and auth link and are created or updated, never removed because they are omitted. A `pluginRouteId` must be unique across routes and group routes (`PLUGIN_ROUTE_ID_CONFLICT`). Group-route members and relationship vertices must resolve to routes or group routes of the same plugin and auth link, committed or in the same request (`UNRESOLVED_REFERENCE`). `IS_PART_OF` joins two group routes and is acyclic (`RELATIONSHIP_CYCLE`) with at most one parent per group route (`MULTIPLE_PARENTS`); `CAN_CONTROL` and `LOCATED_IN` join a route to a group route; self-edges and other shapes are `INVALID_RELATIONSHIP`. Only `CAN_CONTROL` carries `interfaces`, which must name interfaces and inbound messages the source route declares (`MESSAGE_UNSUPPORTED`). Relationship items are keyed by `relationshipExternalId`. A newly reported group route creates its own endpoint group named after it; rediscovery keeps group IDs, merges and user renames.
+
+
+Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.
+
+## Authorization
+
+```yaml
+path: /discovery
+runtimePath: /discovery
+method: POST
+operationId: synchronizeRoutes
+security:
+  - bearerAuth: []
+delegated: false
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /discovery
+post:
+  tags:
+    - Routes
+  summary: Synchronize Plugin Routes via Discovery
+  operationId: synchronizeRoutes
+  description: >-
+    Triggers route synchronization for a plugin. When a plugin connected to Port OS wants to report
+    the routes available on it, it dispatches a discovery payload. The server reconciles the
+    reported routes with its internal state. For newly persisted synchronized routes, the server can
+    assign a backend-generated, owner-scoped Port OS route `id`; a client-supplied route `id` in the
+    discovery payload is advisory and is not the stable lookup surface for plugin capability parity.
+    Consumers that need to match synchronized plugin or fixture routes after enumeration should use
+    `associatedPluginRouteId`, which preserves the plugin-owned route identity.
+
+
+    Every route and group-route interface must name a capability interface and exact version from
+    the capability-interface library, its `configuration` must conform to that interface's
+    configuration schema (an omitted configuration is validated as an empty object), and any
+    declared attribute must exist on the interface with a value that conforms to its attribute
+    schema. Any nonconforming item rejects the whole request with 400; `errors` lists every rejected
+    item keyed by `pluginRouteId`. Nothing is persisted.
+
+
+    Group routes and relationships are keyed by plugin-owned identity within the plugin and auth
+    link and are created or updated, never removed because they are omitted. A `pluginRouteId` must
+    be unique across routes and group routes (`PLUGIN_ROUTE_ID_CONFLICT`). Group-route members and
+    relationship vertices must resolve to routes or group routes of the same plugin and auth link,
+    committed or in the same request (`UNRESOLVED_REFERENCE`). `IS_PART_OF` joins two group routes
+    and is acyclic (`RELATIONSHIP_CYCLE`) with at most one parent per group route
+    (`MULTIPLE_PARENTS`); `CAN_CONTROL` and `LOCATED_IN` join a route to a group route; self-edges
+    and other shapes are `INVALID_RELATIONSHIP`. Only `CAN_CONTROL` carries `interfaces`, which must
+    name interfaces and inbound messages the source route declares (`MESSAGE_UNSUPPORTED`).
+    Relationship items are keyed by `relationshipExternalId`. A newly reported group route creates
+    its own endpoint group named after it; rediscovery keeps group IDs, merges and user renames.
+
+
+
+    Requires a signed user/session or the existing authenticated client flow. The anonymous DCR
+    delegated device profile cannot invoke this operation.
+  security:
+    - bearerAuth: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/SynchronizationRequest'
+  responses:
+    '200':
+      description: Routes synchronized successfully
+    '400':
+      description: >-
+        Bad request — invalid payload, or one or more routes or group routes do not conform to the
+        capability-interface library
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: >-
+              discovery rejected: 1 route does not conform to the capability-interface library;
+              nothing was synchronized
+            type: BAD_REQUEST
+            family: BAD_REQUEST
+            errors:
+              - pluginRouteId: robot-1
+                interface: port1/systems/zero/capability-interfaces/robotic-vacuum-cleaner
+                version: '1.0'
+                code: INVALID_CONFIGURATION
+                family: BAD_REQUEST
+                status: 400
+                message: >-
+                  configuration for
+                  port1/systems/zero/capability-interfaces/robotic-vacuum-cleaner/1.0 does not
+                  conform to its schema: field 'supportsRoomCleaning': Invalid type. Expected:
+                  boolean, given: string. The plugin must send configuration conforming to
+                  port1/systems/zero/capability-interfaces/robotic-vacuum-cleaner/1.0.
+    '401':
+      description: Unauthorized — missing or invalid bearer token
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Authentication required
+            type: UNAUTHORIZED
+    '403':
+      description: Forbidden — insufficient permissions
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Insufficient permissions
+            type: FORBIDDEN
+    '500':
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Internal server error
+            type: INTERNAL
+  x-portos-delegated: false
+  x-portos-resource-permission: true
+```
+
+Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).