@portpowered/reference-data 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,113 @@
+# registerDynamicOAuthClient
+
+POST `/oauth/register`
+
+Register a public OAuth client
+
+RFC 7591 anonymous public-client registration. No Google session is required.
+This registration gives no user or resource permissions. Public clients must
+use PKCE S256, resource-bound authorization_code flow and explicit user consent.
+Client name, software_id and client_uri are unverified claims, not proof of Muse
+or any other product. Untrusted software_statement is rejected.
+Remote callbacks require HTTPS. HTTP is allowed for localhost or literal
+loopback IPs only, and local callbacks cannot be mixed with remote callbacks.
+SHA-256 of canonical client_name, sorted redirect_uris, sorted grant_types,
+sorted response_types and token_endpoint_auth_method identifies a registration.
+A repeated fingerprint returns the original client_id and accepted metadata,
+including its original scopes; it never overwrites metadata or expands scopes.
+Reused registrations do not consume new-registration quota.
+Unknown metadata extensions are ignored as required by RFC 7591.
+The deployment enforces rolling registration and retained-client quotas.
+
+
+## Authorization
+
+```yaml
+path: /oauth/register
+runtimePath: /oauth/register
+method: POST
+operationId: registerDynamicOAuthClient
+security: []
+delegated: false
+resourcePermissionRequired: false
+```
+
+## Complete operation contract
+
+```yaml
+path: /oauth/register
+post:
+  operationId: registerDynamicOAuthClient
+  tags:
+    - Auth
+  summary: Register a public OAuth client
+  security: []
+  x-portos-delegated: false
+  x-portos-resource-permission: false
+  description: |
+    RFC 7591 anonymous public-client registration. No Google session is required.
+    This registration gives no user or resource permissions. Public clients must
+    use PKCE S256, resource-bound authorization_code flow and explicit user consent.
+    Client name, software_id and client_uri are unverified claims, not proof of Muse
+    or any other product. Untrusted software_statement is rejected.
+    Remote callbacks require HTTPS. HTTP is allowed for localhost or literal
+    loopback IPs only, and local callbacks cannot be mixed with remote callbacks.
+    SHA-256 of canonical client_name, sorted redirect_uris, sorted grant_types,
+    sorted response_types and token_endpoint_auth_method identifies a registration.
+    A repeated fingerprint returns the original client_id and accepted metadata,
+    including its original scopes; it never overwrites metadata or expands scopes.
+    Reused registrations do not consume new-registration quota.
+    Unknown metadata extensions are ignored as required by RFC 7591.
+    The deployment enforces rolling registration and retained-client quotas.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/DynamicClientMetadata'
+        example:
+          client_name: My agent
+          redirect_uris:
+            - http://127.0.0.1:8765/callback
+          token_endpoint_auth_method: none
+          grant_types:
+            - authorization_code
+            - refresh_token
+          scope: endpoint:read message:send
+  responses:
+    '201':
+      description: Public client created; no client_secret is issued.
+      content:
+        application/json:
+          schema:
+            allOf:
+              - $ref: '#/components/schemas/DynamicClientMetadata'
+              - type: object
+                required:
+                  - client_id
+                  - client_id_issued_at
+                properties:
+                  client_id:
+                    type: string
+                  client_id_issued_at:
+                    type: integer
+                    format: int64
+    '400':
+      description: Invalid metadata, redirect URI, or unapproved software statement.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/OAuthProtocolError'
+    '415':
+      description: Use application/json.
+    '429':
+      description: Registration quota reached. Wait before retrying; do not loop.
+      headers:
+        Retry-After:
+          schema:
+            type: integer
+    '503':
+      description: Registration storage unavailable.
+```
+
+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/removeEndpointGroupMembers.md

@@ -0,0 +1,147 @@
+# removeEndpointGroupMembers
+
+POST `/{namespace}/{principalType}/{principalId}/endpoint-groups/{groupId}/remove-members`
+
+Remove members from an endpoint group
+
+Removes one or more endpoint members from an existing endpoint group
+
+## Authorization
+
+```yaml
+path: >-
+  /{namespace}/{principalType}/{principalId}/endpoint-groups/{groupId}/remove-members
+runtimePath: >-
+  /{namespace}/{principalType}/{principalId}/endpoint-groups/{groupId}/remove-members
+method: POST
+operationId: removeEndpointGroupMembers
+security:
+  - oauth2:
+      - group:manage
+  - bearerAuth: []
+delegated: true
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /{namespace}/{principalType}/{principalId}/endpoint-groups/{groupId}/remove-members
+post:
+  operationId: removeEndpointGroupMembers
+  tags:
+    - Endpoint Groups
+  summary: Remove members from an endpoint group
+  description: Removes one or more endpoint members from an existing 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/RemoveEndpointGroupMembersRequest'
+  responses:
+    '202':
+      description: Members removal 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/requestFutureIntegration.md

@@ -0,0 +1,95 @@
+# requestFutureIntegration
+
+POST `/integration-requests`
+
+Join a future integration waitlist
+
+Records explicit consent to receive updates for the selected future device or AI integration. Adds the subscriber to the provider group without removing existing groups or reactivating unsubscribed contacts.
+
+## Authorization
+
+```yaml
+path: /integration-requests
+runtimePath: /integration-requests
+method: POST
+operationId: requestFutureIntegration
+security: []
+delegated: false
+resourcePermissionRequired: false
+```
+
+## Complete operation contract
+
+```yaml
+path: /integration-requests
+post:
+  operationId: requestFutureIntegration
+  tags:
+    - Plugins
+  summary: Join a future integration waitlist
+  description: >-
+    Records explicit consent to receive updates for the selected future device or AI integration.
+    Adds the subscriber to the provider group without removing existing groups or reactivating
+    unsubscribed contacts.
+  security: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        example:
+          email: person@example.test
+          pluginId: port1/systems/zero/plugins/715b7b85-311f-4851-8430-88bbac6dd3e7
+          consent: true
+        schema:
+          $ref: '#/components/schemas/IntegrationRequest'
+  responses:
+    '201':
+      description: Request saved
+      content:
+        application/json:
+          example:
+            status: requested
+          schema:
+            type: object
+            required:
+              - status
+            properties:
+              status:
+                type: string
+                enum:
+                  - requested
+    '400':
+      description: Invalid email, consent, or future plugin identifier
+      content:
+        application/json:
+          example:
+            message: Invalid email, consent, or future plugin identifier
+            type: BAD_REQUEST
+            family: BAD_REQUEST
+          schema:
+            $ref: '#/components/schemas/Error'
+    '429':
+      description: Too many requests; retry after the Retry-After interval
+      content:
+        application/json:
+          example:
+            message: Too many requests; retry after the Retry-After interval
+            type: TOO_MANY_REQUESTS
+            family: TOO_MANY_REQUESTS
+          schema:
+            $ref: '#/components/schemas/Error'
+    '500':
+      description: Waitlist temporarily unavailable; the client may retry
+      content:
+        application/json:
+          example:
+            message: Waitlist temporarily unavailable; the client may retry
+            type: INTERNAL_SERVER_ERROR
+            family: INTERNAL_SERVER_ERROR
+          schema:
+            $ref: '#/components/schemas/Error'
+  x-portos-delegated: false
+  x-portos-resource-permission: false
+```
+
+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/revokeOAuthGrant.md

@@ -0,0 +1,59 @@
+# revokeOAuthGrant
+
+POST `/auth/revoke`
+
+Revoke a delegated REST or MCP grant
+
+Possession of the matching refresh token proves revocation authority. The endpoint invalidates the grant family; it does not delete the client or other users' grants.
+
+## Authorization
+
+```yaml
+path: /auth/revoke
+runtimePath: /auth/revoke
+method: POST
+operationId: revokeOAuthGrant
+security: []
+delegated: false
+resourcePermissionRequired: false
+```
+
+## Complete operation contract
+
+```yaml
+path: /auth/revoke
+post:
+  operationId: revokeOAuthGrant
+  tags:
+    - Auth
+  summary: Revoke a delegated REST or MCP grant
+  security: []
+  x-portos-delegated: false
+  x-portos-resource-permission: false
+  description: >-
+    Possession of the matching refresh token proves revocation authority. The endpoint invalidates
+    the grant family; it does not delete the client or other users' grants.
+  requestBody:
+    required: true
+    content:
+      application/x-www-form-urlencoded:
+        schema:
+          type: object
+          required:
+            - token
+            - client_id
+          properties:
+            token:
+              type: string
+            client_id:
+              type: string
+  responses:
+    '200':
+      description: Grant revoked or token was already invalid.
+    '400':
+      description: Invalid request or client mismatch.
+    '503':
+      description: Revocation storage unavailable; do not claim success.
+```
+
+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/sendMessage.md

@@ -0,0 +1,279 @@
+# sendMessage
+
+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
+runtimePath: /messages
+method: POST
+operationId: sendMessage
+security:
+  - oauth2:
+      - message:send
+  - bearerAuth: []
+delegated: true
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /messages
+post:
+  operationId: sendMessage
+  tags:
+    - Messages
+  description: >
+    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).