@portpowered/reference-data 0.0.0-stage → 0.4.1

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

@@ -0,0 +1,148 @@
+# enumerateEventDeadLetters
+
+GET `/event-dead-letters`
+
+List authorized redacted event dead letters
+
+Tenant/operator scope; unresolved provider diagnostics require provider operator authorization. Uses opaque cursors.
+
+Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.
+
+## Authorization
+
+```yaml
+path: /event-dead-letters
+runtimePath: /event-dead-letters
+method: GET
+operationId: enumerateEventDeadLetters
+security:
+  - bearerAuth: []
+delegated: false
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /event-dead-letters
+get:
+  operationId: enumerateEventDeadLetters
+  tags:
+    - Events
+  summary: List authorized redacted event dead letters
+  security:
+    - bearerAuth: []
+  description: >-
+    Tenant/operator scope; unresolved provider diagnostics require provider operator authorization.
+    Uses opaque cursors.
+
+
+    Requires a signed user/session or the existing authenticated client flow. The anonymous DCR
+    delegated device profile cannot invoke this operation.
+  parameters:
+    - name: nextToken
+      in: query
+      required: false
+      schema:
+        type: string
+    - name: maxResults
+      in: query
+      required: false
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 1000
+    - name: query
+      in: query
+      required: false
+      description: >-
+        Shared Port OS Query encoded as JSON. Evaluated only over authorized redacted diagnostic
+        fields.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Query'
+    - name: expand
+      in: query
+      required: false
+      description: >-
+        Expansion tokens. This projection has no expandable relationships; omit or supply an empty
+        array. Non-empty tokens are rejected.
+      schema:
+        type: array
+        maxItems: 0
+        items:
+          type: string
+      style: form
+      explode: false
+      example: []
+  responses:
+    '200':
+      description: List authorized redacted event dead letters
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/EventDeadLetterQueryResponse'
+          example:
+            results: []
+            errors: []
+    '400':
+      description: Invalid request; stable code identifies the validation failure.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Invalid request; stable code identifies the validation failure.
+            type: BAD_REQUEST
+            family: BAD_REQUEST
+            code: event_request_failed
+    '401':
+      description: Authentication required.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Authentication required.
+            type: UNAUTHORIZED
+            family: UNAUTHORIZED
+            code: event_request_failed
+    '403':
+      description: Resource authorization denied.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Resource authorization denied.
+            type: FORBIDDEN
+            family: FORBIDDEN
+            code: event_request_failed
+    '404':
+      description: Resource inaccessible, missing or past retention.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Resource inaccessible, missing or past retention.
+            type: NOT_FOUND
+            family: NOT_FOUND
+            code: event_request_failed
+    '500':
+      description: Internal failure.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Internal failure.
+            type: INTERNAL
+            family: INTERNAL_SERVER_ERROR
+            code: event_request_failed
+  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/enumerateFlowNodeSpecifications.md

@@ -0,0 +1,122 @@
+# enumerateFlowNodeSpecifications
+
+GET `/flow-node-specifications`
+
+List flow node specifications
+
+Lists all available flow node specifications for the authenticated user.
+
+Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.
+
+## Authorization
+
+```yaml
+path: /flow-node-specifications
+runtimePath: /flow-node-specifications
+method: GET
+operationId: enumerateFlowNodeSpecifications
+security:
+  - bearerAuth: []
+delegated: false
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /flow-node-specifications
+get:
+  operationId: enumerateFlowNodeSpecifications
+  tags:
+    - Flow Node Specifications
+  summary: List flow node specifications
+  description: >-
+    Lists all available flow node specifications for the authenticated user.
+
+
+    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: nextToken
+      in: query
+      description: The next token to get the next page of results
+      required: false
+      schema:
+        type: string
+      examples:
+        next-token:
+          value: '123'
+    - name: maxResults
+      in: query
+      description: The maximum number of results to return
+      required: false
+      schema:
+        type: integer
+      examples:
+        max-results:
+          value: 10
+    - name: expand
+      in: query
+      description: Expansion tokens that request related or computed fields for each result.
+      required: false
+      schema:
+        type: array
+        items:
+          type: string
+      style: form
+      explode: false
+      examples:
+        include-related:
+          value:
+            - metadata
+  responses:
+    '200':
+      description: Flow node specifications retrieved successfully
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/EnumerateFlowNodeSpecificationsResponse'
+          example:
+            results: []
+            paginationContext:
+              nextToken: abc123
+    '400':
+      description: Bad request - missing required parameters
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Bad request - missing required parameters
+            type: BAD_REQUEST
+            family: BAD_REQUEST
+            code: bad-request
+    '401':
+      description: Unauthorized - invalid or missing authentication token
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Unauthorized - invalid or missing authentication token
+            type: UNAUTHORIZED
+            family: AUTHENTICATION
+            code: unauthorized
+    '500':
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Internal server error
+            type: INTERNAL_SERVER_ERROR
+            family: INTERNAL_SERVER_ERROR
+            code: internal-server-error
+  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/enumerateFlowNodes.md

@@ -0,0 +1,128 @@
+# enumerateFlowNodes
+
+GET `/flow-nodes`
+
+List all flow nodes
+
+Enumerates all flow nodes for the authenticated user.
+
+
+Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.
+
+## Authorization
+
+```yaml
+path: /flow-nodes
+runtimePath: /flow-nodes
+method: GET
+operationId: enumerateFlowNodes
+security:
+  - bearerAuth: []
+delegated: false
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /flow-nodes
+get:
+  tags:
+    - Flow Nodes
+  operationId: enumerateFlowNodes
+  summary: List all flow nodes
+  description: >-
+    Enumerates all flow nodes for the authenticated user.
+
+
+
+    Requires a signed user/session or the existing authenticated client flow. The anonymous DCR
+    delegated device profile cannot invoke this operation.
+  security:
+    - bearerAuth: []
+  responses:
+    '200':
+      description: Flow nodes retrieved successfully.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              results:
+                type: array
+                items:
+                  $ref: '#/components/schemas/FlowNode'
+              paginationContext:
+                $ref: '#/components/schemas/PaginationContext'
+              errors:
+                type: array
+                description: Partial query errors collected while returning available results.
+                items:
+                  $ref: '#/components/schemas/Error'
+          example:
+            key: value
+    '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
+    '500':
+      description: Internal server error.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Internal server error
+            type: INTERNAL
+  parameters:
+    - name: expand
+      in: query
+      description: Expansion tokens that request related or computed fields for each result.
+      required: false
+      schema:
+        type: array
+        items:
+          type: string
+      style: form
+      explode: false
+      examples:
+        include-related:
+          value:
+            - metadata
+    - name: nextToken
+      in: query
+      description: Opaque cursor token returned by a previous query response.
+      required: false
+      schema:
+        type: string
+      examples:
+        next-page:
+          value: abc123
+    - name: maxResults
+      in: query
+      description: Maximum number of results to return.
+      required: false
+      schema:
+        type: integer
+      examples:
+        page-size:
+          value: 50
+  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/enumerateGroupRelationships.md

@@ -0,0 +1,177 @@
+# enumerateGroupRelationships
+
+GET `/group-relationships`
+
+List group relationships
+
+Read-only enumeration of provider-reported relationships (`IS_PART_OF`, `CAN_CONTROL`, `LOCATED_IN`) between routes and group routes the caller is authorized to read. Relationships are managed by plugin discovery only. Optionally filter by a group, route or group route, or endpoint.
+
+
+## Authorization
+
+```yaml
+path: /group-relationships
+runtimePath: /group-relationships
+method: GET
+operationId: enumerateGroupRelationships
+security:
+  - oauth2:
+      - group:read
+  - bearerAuth: []
+delegated: true
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /group-relationships
+get:
+  tags:
+    - Endpoint Group Routes
+  operationId: enumerateGroupRelationships
+  summary: List group relationships
+  description: >
+    Read-only enumeration of provider-reported relationships (`IS_PART_OF`, `CAN_CONTROL`,
+    `LOCATED_IN`) between routes and group routes the caller is authorized to read. Relationships
+    are managed by plugin discovery only. Optionally filter by a group, route or group route, or
+    endpoint.
+  security:
+    - oauth2:
+        - group:read
+    - bearerAuth: []
+  parameters:
+    - name: owner
+      in: query
+      description: The owner of the relationships to get. Use '~caller' for the authenticated user
+      required: true
+      schema:
+        type: string
+      examples:
+        check-token:
+          value: ~caller
+    - name: groupId
+      in: query
+      description: Only relationships with a vertex in this endpoint group (redirects are followed)
+      required: false
+      schema:
+        type: string
+      examples:
+        group:
+          value: port1/principals/user123/endpoint-groups/kitchen
+    - name: routeId
+      in: query
+      description: Only relationships with this route or group route ID as a vertex
+      required: false
+      schema:
+        type: string
+      examples:
+        route:
+          value: port1/principals/user123/group-routes/abc
+    - name: endpointId
+      in: query
+      description: Only relationships whose route vertex belongs to this endpoint
+      required: false
+      schema:
+        type: string
+      examples:
+        endpoint:
+          value: port1/principals/user123/endpoints/robot
+    - name: nextToken
+      in: query
+      description: The next token to get the next page of results
+      required: false
+      schema:
+        type: string
+      examples:
+        next-token:
+          value: '123'
+    - name: maxResults
+      in: query
+      description: The maximum number of results to return
+      required: false
+      schema:
+        type: integer
+      examples:
+        max-results:
+          value: 10
+    - name: expand
+      in: query
+      description: Expansion tokens that request related or computed fields for each result.
+      required: false
+      schema:
+        type: array
+        items:
+          type: string
+      style: form
+      explode: false
+      examples:
+        include-related:
+          value:
+            - metadata
+  responses:
+    '200':
+      description: Group relationships retrieved successfully
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/EnumerateGroupRelationshipsResponse'
+          example:
+            results:
+              - id: port1/principals/user123/group-relationships/rel-1
+                ownerId: port1/principals/user123
+                type: CAN_CONTROL
+                source:
+                  routeId: port1/principals/user123/routes/robot
+                  endpointId: port1/principals/user123/endpoints/robot
+                target:
+                  groupRouteId: port1/principals/user123/group-routes/room-18
+                  groupId: port1/principals/user123/endpoint-groups/kitchen
+                interfaces:
+                  - name: port1/systems/zero/capability-interfaces/robotic-vacuum-cleaner
+                    version: '1.0'
+                    messages:
+                      - clean-room
+            paginationContext:
+              nextToken: abc123
+    '400':
+      description: Bad request - missing or invalid parameters
+      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
+    '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/enumerateGroupRoutes.md

@@ -0,0 +1,137 @@
+# enumerateGroupRoutes
+
+GET `/group-routes`
+
+List group routes
+
+API to enumerate the group routes that a principal has permissions to.
+
+
+## Authorization
+
+```yaml
+path: /group-routes
+runtimePath: /group-routes
+method: GET
+operationId: enumerateGroupRoutes
+security:
+  - oauth2:
+      - group:read
+  - bearerAuth: []
+delegated: true
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /group-routes
+get:
+  tags:
+    - Endpoint Group Routes
+  operationId: enumerateGroupRoutes
+  summary: List group routes
+  description: |
+    API to enumerate the group routes that a principal has permissions to.
+  security:
+    - oauth2:
+        - group:read
+    - bearerAuth: []
+  parameters:
+    - name: owner
+      in: query
+      description: >-
+        The owner of the group routes to get. Use '~caller' to get group routes for the
+        authenticated user
+      required: true
+      schema:
+        type: string
+      examples:
+        check-token:
+          value: ~caller
+        check-id:
+          value: port1/user/alice/user/alice
+    - name: nextToken
+      in: query
+      description: The next token to get the next page of results
+      required: false
+      schema:
+        type: string
+      examples:
+        next-token:
+          value: '123'
+    - name: maxResults
+      in: query
+      description: The maximum number of results to return
+      required: false
+      schema:
+        type: integer
+      examples:
+        max-results:
+          value: 10
+    - name: expand
+      in: query
+      description: Expansion tokens that request related or computed fields for each result.
+      required: false
+      schema:
+        type: array
+        items:
+          type: string
+      style: form
+      explode: false
+      examples:
+        include-related:
+          value:
+            - metadata
+  responses:
+    '200':
+      description: Group routes retrieved successfully
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/EnumerateGroupRoutesResponse'
+          example:
+            results: []
+            paginationContext:
+              nextToken: abc123
+    '400':
+      description: Bad request - missing required parameters
+      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
+    '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).