@portpowered/reference-data 0.0.0-stage → 0.4.0

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

@@ -0,0 +1,126 @@
+# upsertFlowRunMessage
+
+POST `/{namespace}/{principalType}/{principalId}/flows/{flowId}/runs/{runId}/messages`
+
+Create a flow run message
+
+Creates a message for a specific flow run. Messages can target flow nodes or flow ports.
+
+
+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}/messages
+runtimePath: >-
+  /{namespace}/{principalType}/{principalId}/flows/{flowId}/runs/{runId}/messages
+method: POST
+operationId: upsertFlowRunMessage
+security:
+  - bearerAuth: []
+delegated: false
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /{namespace}/{principalType}/{principalId}/flows/{flowId}/runs/{runId}/messages
+post:
+  tags:
+    - FlowRuns
+  operationId: upsertFlowRunMessage
+  summary: Create a flow run message
+  description: >-
+    Creates a message for a specific flow run. Messages can target flow nodes or flow ports.
+
+
+
+    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 to create a run for.
+    - name: runId
+      in: path
+      required: true
+      schema:
+        type: string
+      description: The ID of the flow run to create a message for.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/UpsertFlowRunMessageRequest'
+        example:
+          name:
+            type: PLAIN
+            value: My Resource
+  responses:
+    '200':
+      description: OK
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/UpsertFlowRunMessageResponse'
+          example:
+            id: port1/principals/user123/resources/abc-123
+    '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/upsertPluginRequest.md

@@ -0,0 +1,67 @@
+# upsertPluginRequest
+
+POST `/plugins`
+
+
+
+Creates a new plugin
+
+Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.
+
+## Authorization
+
+```yaml
+path: /plugins
+runtimePath: /plugins
+method: POST
+operationId: upsertPluginRequest
+security:
+  - oauth2: []
+  - bearerAuth: []
+delegated: false
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /plugins
+post:
+  operationId: upsertPluginRequest
+  tags:
+    - Plugins
+  description: >-
+    Creates a new plugin
+
+
+    Requires a signed user/session or the existing authenticated client flow. The anonymous DCR
+    delegated device profile cannot invoke this operation.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/UpsertPluginRequest'
+        example:
+          name:
+            type: PLAIN
+            value: My Resource
+  responses:
+    '200':
+      description: Plugin created successfully
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/UpsertPluginResponse'
+    '400':
+      description: Invalid request payload
+    '500':
+      description: Internal server error
+  x-portos-delegated: false
+  x-portos-resource-permission: true
+  security:
+    - oauth2: []
+    - 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/upsertPrincipal.md

@@ -0,0 +1,65 @@
+# upsertPrincipal
+
+POST `/principals`
+
+
+
+Creates a new principal
+
+Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.
+
+## Authorization
+
+```yaml
+path: /principals
+runtimePath: /principals
+method: POST
+operationId: upsertPrincipal
+security:
+  - oauth2: []
+  - bearerAuth: []
+delegated: false
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /principals
+post:
+  operationId: upsertPrincipal
+  tags:
+    - Principals
+  description: >-
+    Creates a new principal
+
+
+    Requires a signed user/session or the existing authenticated client flow. The anonymous DCR
+    delegated device profile cannot invoke this operation.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/UpsertPrincipalRequest'
+  responses:
+    '200':
+      description: Principal created successfully
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/UpsertPrincipalResponse'
+          example:
+            id: port1/principals/user123/resources/abc-123
+    '400':
+      description: Invalid request payload
+    '500':
+      description: Internal server error
+  x-portos-delegated: false
+  x-portos-resource-permission: true
+  security:
+    - oauth2: []
+    - 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/upsertRoute.md

@@ -0,0 +1,54 @@
+# upsertRoute
+
+POST `/routes`
+
+
+
+Creates or updates a route
+
+## Authorization
+
+```yaml
+path: /routes
+runtimePath: /routes
+method: POST
+operationId: upsertRoute
+security:
+  - oauth2:
+      - endpoint:write
+  - bearerAuth: []
+delegated: true
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /routes
+post:
+  operationId: upsertRoute
+  tags:
+    - Routes
+  description: Creates or updates a route
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/UpsertRouteRequest'
+  responses:
+    '200':
+      description: Route upserted successfully
+    '400':
+      description: Invalid request payload
+    '500':
+      description: Internal server error
+  x-portos-delegated: true
+  x-portos-resource-permission: true
+  security:
+    - oauth2:
+        - endpoint:write
+    - 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/upsertSecret.md

@@ -0,0 +1,112 @@
+# upsertSecret
+
+POST `/secrets`
+
+
+
+Create a secret, which is a special type of data that is secured. 
+Secrets are special data that can be very dangerous to use, and so is put in a special database. 
+
+Some well known types of secrets include: 
+Random secret data, access tokens, passwords, and various others. 
+
+### Generic secrets
+If you want to keep something secret, and have it super safe, you can create a secret. 
+This secret is stored in portos with a unique resource identifier for a storage document. 
+
+For example, maybe you have client credentials or something that is a generic json blob. 
+
+i.e. https://api.portpowered.com/storage/secrets/portos1.secret.<UUID>
+
+### Tokens
+A specialized type of secret is a OAUTH token secret. This secret is often used to access plugins, so 
+there are specialized indexes to make token look up faster. 
+
+
+Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.
+
+## Authorization
+
+```yaml
+path: /secrets
+runtimePath: /secrets
+method: POST
+operationId: upsertSecret
+security:
+  - oauth2: []
+  - bearerAuth: []
+delegated: false
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /secrets
+post:
+  tags:
+    - Secrets
+  operationId: upsertSecret
+  description: >-
+    Create a secret, which is a special type of data that is secured. 
+
+    Secrets are special data that can be very dangerous to use, and so is put in a special
+    database. 
+
+
+    Some well known types of secrets include: 
+
+    Random secret data, access tokens, passwords, and various others. 
+
+
+    ### Generic secrets
+
+    If you want to keep something secret, and have it super safe, you can create a secret. 
+
+    This secret is stored in portos with a unique resource identifier for a storage document. 
+
+
+    For example, maybe you have client credentials or something that is a generic json blob. 
+
+
+    i.e. https://api.portpowered.com/storage/secrets/portos1.secret.<UUID>
+
+
+    ### Tokens
+
+    A specialized type of secret is a OAUTH token secret. This secret is often used to access
+    plugins, so 
+
+    there are specialized indexes to make token look up faster. 
+
+
+
+    Requires a signed user/session or the existing authenticated client flow. The anonymous DCR
+    delegated device profile cannot invoke this operation.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/UpsertSecretRequest'
+  responses:
+    '200':
+      description: Secret created successfully
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/UpsertSecretResponse'
+          example:
+            id: port1/principals/user123/resources/abc-123
+    '400':
+      description: Invalid request payload
+    '500':
+      description: Internal server error
+  x-portos-delegated: false
+  x-portos-resource-permission: true
+  security:
+    - oauth2: []
+    - 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/upsertSimulator.md

@@ -0,0 +1,151 @@
+# upsertSimulator
+
+POST `/endpoint-simulators`
+
+Create or update a simulator
+
+Creates a new endpoint simulator or updates an existing one. When an `id` is provided in the request body, the simulator with that ID is updated. When no `id` is provided, a new simulator is created along with its associated endpoint, auth link, and route.
+ Missing or ordinary JSON Accept selects the existing string-name projection. Explicit application/vnd.portos.simulator.v2+json selects name-value output; unsupported explicit representations fail 406. Content-Type selects request projection, independent of Accept. Legacy object names fail 400. No legacy default flip or removal is authorized.
+
+Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.
+
+## Authorization
+
+```yaml
+path: /endpoint-simulators
+runtimePath: /endpoint-simulators
+method: POST
+operationId: upsertSimulator
+security:
+  - bearerAuth: []
+delegated: false
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /endpoint-simulators
+post:
+  operationId: upsertSimulator
+  tags:
+    - Endpoint Simulators
+  summary: Create or update a simulator
+  description: >-
+    Creates a new endpoint simulator or updates an existing one. When an `id` is provided in the
+    request body, the simulator with that ID is updated. When no `id` is provided, a new simulator
+    is created along with its associated endpoint, auth link, and route.
+     Missing or ordinary JSON Accept selects the existing string-name projection. Explicit application/vnd.portos.simulator.v2+json selects name-value output; unsupported explicit representations fail 406. Content-Type selects request projection, independent of Accept. Legacy object names fail 400. No legacy default flip or removal is authorized.
+
+    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/UpsertSimulatorRequest'
+        example:
+          name: Demo front door
+          device_type: camera
+          configuration:
+            eventProfile: doorbell
+      application/vnd.portos.simulator.v2+json:
+        schema:
+          $ref: '#/components/schemas/UpsertSimulatorRequestV2'
+        example:
+          name:
+            type: PLAIN
+            value: Demo front door
+          device_type: camera
+          configuration:
+            eventProfile: doorbell
+  responses:
+    '200':
+      description: Simulator upserted successfully
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Simulator'
+        application/vnd.portos.simulator.v2+json:
+          schema:
+            $ref: '#/components/schemas/SimulatorV2'
+          example:
+            id: port1.simulator.camera-demo
+            name:
+              type: PLAIN
+              value: Front door camera
+            device_type: camera
+            configuration:
+              eventProfile: doorbell
+      headers:
+        Vary:
+          description: Response representation is selected by Accept.
+          schema:
+            type: string
+            example: Accept
+    '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
+    '406':
+      description: Unsupported explicitly requested representation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Unsupported explicitly requested representation.
+            type: BAD_REQUEST
+            family: BAD_REQUEST
+            code: event_request_failed
+    '415':
+      description: Unsupported request media type.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Unsupported request media type.
+            type: BAD_REQUEST
+            family: BAD_REQUEST
+            code: event_request_failed
+    '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).

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

@@ -0,0 +1,66 @@
+# upsertSubscription
+
+POST `/subscriptions`
+
+
+
+Used to upsert a subscription to an event stream.
+
+
+## Authorization
+
+```yaml
+path: /subscriptions
+runtimePath: /subscriptions
+method: POST
+operationId: upsertSubscription
+security:
+  - oauth2:
+      - subscription:write
+  - bearerAuth: []
+delegated: true
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /subscriptions
+post:
+  tags:
+    - Subscriptions
+  operationId: upsertSubscription
+  description: |
+    Used to upsert a subscription to an event stream.
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/UpsertSubscriptionRequest'
+        example:
+          name:
+            type: PLAIN
+            value: My Resource
+  responses:
+    '200':
+      description: OK, this confirms a subscription occurs, this is eventually consistent and is not guarantee
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/UpsertSubscriptionResponse'
+          example:
+            id: port1/principals/user123/resources/abc-123
+    '400':
+      description: Invalid request payload
+    '500':
+      description: Internal server error
+  x-portos-delegated: true
+  x-portos-resource-permission: true
+  security:
+    - oauth2:
+        - subscription:write
+    - 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/validateOAuthRequest.md

@@ -0,0 +1,64 @@
+# validateOAuthRequest
+
+POST `/oauth/validate-request`
+
+OAuth2 Validate Authorization Request
+
+This endpoint validates OAuth 2.0 authorization request parameters without creating an authorization code. It returns client information relevant for displaying on the authorization page, such as client name, Terms of Service URI, Privacy Policy URI, logo URI, and validated scopes.
+This endpoint is useful for pre-validation before user consent, allowing the frontend to display relevant client information to the user.
+
+
+## Authorization
+
+```yaml
+path: /oauth/validate-request
+runtimePath: /oauth/validate-request
+method: POST
+operationId: validateOAuthRequest
+security:
+  - bearerAuth: []
+delegated: false
+resourcePermissionRequired: false
+```
+
+## Complete operation contract
+
+```yaml
+path: /oauth/validate-request
+post:
+  operationId: validateOAuthRequest
+  tags:
+    - Internal
+  summary: OAuth2 Validate Authorization Request
+  description: >
+    This endpoint validates OAuth 2.0 authorization request parameters without creating an
+    authorization code. It returns client information relevant for displaying on the authorization
+    page, such as client name, Terms of Service URI, Privacy Policy URI, logo URI, and validated
+    scopes.
+
+    This endpoint is useful for pre-validation before user consent, allowing the frontend to display
+    relevant client information to the user.
+  security:
+    - bearerAuth: []
+  requestBody:
+    required: true
+    content:
+      application/json:
+        schema:
+          $ref: '#/components/schemas/ValidateOAuthRequestRequest'
+  responses:
+    '200':
+      description: Request validated successfully, returns client information
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/ValidateOAuthRequestResponse'
+    '400':
+      description: Invalid request (e.g., invalid client_id, redirect_uri, or scopes)
+    '500':
+      description: Internal server 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).