@portpowered/reference-data 0.4.4 → 0.4.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (17) hide show
  1. package/generated/guides.json +5 -5
  2. package/generated/openapi.json +90 -12
  3. package/generated/public/docs/for-ai/api-catalog.md +123 -0
  4. package/generated/public/docs/for-ai/guides/authentication-and-dcr.md +7 -1
  5. package/generated/public/docs/for-ai/guides/connect-agent.md +2 -0
  6. package/generated/public/docs/for-ai/guides/index.md +2 -0
  7. package/generated/public/docs/for-ai/guides/lighting.md +18 -2
  8. package/generated/public/docs/for-ai/guides/oauth-discovery.md +2 -0
  9. package/generated/public/docs/for-ai/guides/using-the-api.md +19 -1
  10. package/generated/public/docs/for-ai/index.md +17 -9
  11. package/generated/public/docs/for-ai/operations/endpointQuery.md +52 -7
  12. package/generated/public/docs/references/authorization.json +6 -1
  13. package/generated/public/docs/references/authorization.yaml +3 -0
  14. package/generated/public/docs/references/manifest.json +162 -31
  15. package/generated/public/docs/references/openapi.yaml +91 -8
  16. package/generated/public/docs/references/schemas/EndpointQueryRequest.json +32 -4
  17. package/package.json +1 -1
package/generated/public/docs/for-ai/index.md CHANGED
@@ -1,17 +1,25 @@
1
1
  # Port OS: start here for agents
2
2
 
3
- Read [authentication and DCR](/docs/for-ai/guides/authentication-and-dcr.md), then [the quickstart](/docs/for-ai/guides/quickstart.md). Register a public client, open the user authorization URL, wait for the user to consent, verify the callback, then exchange its code with PKCE. Registration alone gives no device access. Never request the user’s Google password or reuse another client’s tokens.
3
+ ## New REST connection
4
4
 
5
- ## Documentation tree
5
+ Read [the complete authentication walkthrough](/docs/for-ai/guides/authentication-and-dcr.md), then [the REST quickstart](/docs/for-ai/guides/quickstart.md). The walkthrough includes discovery, DCR/CIMD, consent, callback, token lifecycle and permission rules. You do not need to read their separate component files again. Follow an operation or capability link from the quickstart only when you need its exact contract.
6
6
 
7
- - [All task guides](/docs/for-ai/guides/index.md)
8
- - [Scopes and permission evaluation](/docs/for-ai/guides/authorization-rules.md)
9
- - [REST operation directory](/docs/for-ai/operations/index.md)
10
- - [Small REST schema files](/docs/for-ai/schemas.md)
11
- - [Capability directory](/docs/for-ai/capability-interfaces.md)
12
- - [OpenAPI YAML](/docs/references/openapi.yaml)
7
+ Registration alone gives no device access. Wait for user consent and validate the callback before exchanging its code with PKCE. Never request the user’s Google password or reuse another client’s tokens.
8
+
9
+ ## Existing connector or MCP
10
+
11
+ Use [the shared connection guide](/docs/for-ai/guides/connect-agent.md) to select the transport and only the components your client needs. REST and MCP use different OAuth resources; choose before authorization and retain the resource through exchange and refresh.
12
+
13
+ ## Documentation tree: look up what you need
14
+
15
+ - [Task/component guide directory](/docs/for-ai/guides/index.md): alternatives, not a required reading checklist
16
+ - [Compact API catalog](/docs/for-ai/api-catalog.md): auth context and parameter/key index
17
+ - [REST operation directory](/docs/for-ai/operations/index.md): individual operations and their scopes
18
+ - [Small REST schema files](/docs/for-ai/schemas.md): linked request/response components
19
+ - [Capability directory](/docs/for-ai/capability-interfaces.md): match the discovered namespace and version
20
+ - [Authorization inventory](/docs/references/authorization.yaml): machine-readable scope/policy rules
21
+ - [Full OpenAPI YAML](/docs/references/openapi.yaml): comprehensive lookup and SDK generation; unnecessary for the quickstart
13
22
  - [Capability YAML index](/docs/references/capability-interfaces.yaml)
14
- - [Authorization inventory](/docs/references/authorization.yaml)
15
23
  - [Release manifest](/docs/references/manifest.json)
16
24
 
17
25
  These links are public UTF-8 documents. You do not need JavaScript, sign-in, or a repository checkout to read them. Device data still requires consent and resource permission.
package/generated/public/docs/for-ai/operations/endpointQuery.md CHANGED
@@ -4,7 +4,7 @@ POST `/endpoint-query`
4
4
 
5
5
 
6
6
 
7
- Query for endpoints
7
+ Return a bounded page of authorized endpoints matching the shared Query expression, including endpoints shared by other owners. Read permission is evaluated before filtering, pagination and state expansion. See the request schema for supported fields and operators. Use groupId to select members of a readable room/group, then intersect type or declared interfaces to select lights. Group predicates additionally require group:read for delegated OAuth. Repeat the complete query settings and grant when following nextToken; cursors expire after fifteen minutes. Device attributes are returned only when expanded. Report per-target command acceptance and observed state separately; querying a group does not grant permission to control its members.
8
8
 
9
9
  ## Authorization
10
10
 
@@ -19,6 +19,9 @@ security:
19
19
  - bearerAuth: []
20
20
  delegated: true
21
21
  resourcePermissionRequired: true
22
+ conditionalScopes:
23
+ groupId:
24
+ - group:read
22
25
  ```
23
26
 
24
27
  ## Complete operation contract
@@ -29,7 +32,19 @@ post:
29
32
  operationId: endpointQuery
30
33
  tags:
31
34
  - Endpoints
32
- description: Query for endpoints
35
+ description: >-
36
+ Return a bounded page of authorized endpoints matching the shared Query expression, including
37
+ endpoints shared by other owners. Read permission is evaluated before filtering, pagination and
38
+ state expansion. See the request schema for supported fields and operators. Use groupId to
39
+ select members of a readable room/group, then intersect type or declared interfaces to select
40
+ lights. Group predicates additionally require group:read for delegated OAuth. Repeat the
41
+ complete query settings and grant when following nextToken; cursors expire after fifteen
42
+ minutes. Device attributes are returned only when expanded. Report per-target command acceptance
43
+ and observed state separately; querying a group does not grant permission to control its
44
+ members.
45
+ x-portos-conditional-scopes:
46
+ groupId:
47
+ - group:read
33
48
  requestBody:
34
49
  required: true
35
50
  content:
@@ -39,8 +54,10 @@ post:
39
54
  example:
40
55
  query:
41
56
  match:
42
- key: name
43
- value: test
57
+ key: type
58
+ value: LIGHT
59
+ paginationContext:
60
+ maxResults: 10
44
61
  responses:
45
62
  '200':
46
63
  description: Endpoints retrieved successfully
@@ -50,10 +67,8 @@ post:
50
67
  $ref: /docs/references/schemas/EndpointQueryResponse.json
51
68
  example:
52
69
  results: []
53
- paginationContext:
54
- nextToken: abc123
55
70
  '400':
56
- description: Bad request - missing required parameters
71
+ description: Invalid query, unsupported expansion, or invalid/expired/mismatched cursor.
57
72
  content:
58
73
  application/json:
59
74
  schema:
@@ -72,6 +87,36 @@ post:
72
87
  message: Unauthorized - invalid or missing authentication token
73
88
  code: UNAUTHORIZED
74
89
  family: AUTHENTICATION
90
+ '403':
91
+ description: Missing conditional OAuth scope or permission to read a referenced group.
92
+ content:
93
+ application/json:
94
+ schema:
95
+ $ref: /docs/references/schemas/Error.json
96
+ example:
97
+ message: Permission to read the requested group is required.
98
+ code: FORBIDDEN
99
+ family: FORBIDDEN
100
+ '404':
101
+ description: A referenced group does not exist.
102
+ content:
103
+ application/json:
104
+ schema:
105
+ $ref: /docs/references/schemas/Error.json
106
+ example:
107
+ message: Requested group was not found.
108
+ code: NOT_FOUND
109
+ family: NOT_FOUND
110
+ '409':
111
+ description: A selected disabled endpoint cannot be forcibly refreshed.
112
+ content:
113
+ application/json:
114
+ schema:
115
+ $ref: /docs/references/schemas/Error.json
116
+ example:
117
+ message: endpoint messaging is disabled
118
+ code: ENDPOINT_DISABLED
119
+ family: CONFLICT
75
120
  '500':
76
121
  description: Internal server error
77
122
  content:
package/generated/public/docs/references/authorization.json CHANGED
@@ -160,7 +160,12 @@
160
160
  }
161
161
  ],
162
162
  "delegated": true,
163
- "resourcePermissionRequired": true
163
+ "resourcePermissionRequired": true,
164
+ "conditionalScopes": {
165
+ "groupId": [
166
+ "group:read"
167
+ ]
168
+ }
164
169
  },
165
170
  {
166
171
  "path": "/events",
package/generated/public/docs/references/authorization.yaml CHANGED
@@ -123,6 +123,9 @@ operations:
123
123
  - bearerAuth: []
124
124
  delegated: true
125
125
  resourcePermissionRequired: true
126
+ conditionalScopes:
127
+ groupId:
128
+ - group:read
126
129
  - path: /events
127
130
  runtimePath: /events
128
131
  method: POST
package/generated/public/docs/references/manifest.json CHANGED
@@ -1,13 +1,137 @@
1
1
  {
2
2
  "package": "@portpowered/reference-data",
3
3
  "goModule": "github.com/portpowered/portos-reference-data",
4
- "version": "0.4.4",
5
- "sourceCommit": "ddab20777e6044b21db0f0c1c525bf59ff4f31f0",
4
+ "version": "0.4.6",
5
+ "sourceCommit": "1a7e380ef931f684ad0c4dfb9e3d73b20a01bd69",
6
6
  "sourceInputState": "committed",
7
- "sourceInputSHA256": "8a1f7e267ecac60eaf7a4e7ded150b2ff86ac59760c11b5251b52e4a78db40ca",
7
+ "sourceInputSHA256": "373c0f48bd6955157efd5047090454fbd7efa42313debb76229b413567102c22",
8
8
  "sourceInputCount": 735,
9
- "assetSetSHA256": "d101a7e55686035b22ab0b4e5cc2839c8e9c835db31d6ef329c6e801f53c848b",
9
+ "assetSetSHA256": "c0d41f747be314cd29b19dd70b1a380818fc431b44e91cfb3bea90ebeed55efb",
10
10
  "files": [
11
+ {
12
+ "path": "/docs/for-ai/api-catalog.md",
13
+ "contentType": "text/plain; charset=utf-8",
14
+ "bytes": 21280,
15
+ "sha256": "d0ed50538f4f1ce2f7ec9d4eb17bb3d713a24252ae8af2fbf91bf447e233462d",
16
+ "links": [
17
+ "/docs/for-ai/capability-interfaces.md",
18
+ "/docs/for-ai/guides/authentication-and-dcr.md",
19
+ "/docs/for-ai/guides/authorization-rules.md",
20
+ "/docs/for-ai/guides/quickstart.md",
21
+ "/docs/for-ai/operations/addEndpointGroupMembers.md",
22
+ "/docs/for-ai/operations/authorizeDevice.md",
23
+ "/docs/for-ai/operations/beginOAuthAuthorization.md",
24
+ "/docs/for-ai/operations/completeOAuthConsent.md",
25
+ "/docs/for-ai/operations/createEndpointGroup.md",
26
+ "/docs/for-ai/operations/createFlowNode.md",
27
+ "/docs/for-ai/operations/createFlowRun.md",
28
+ "/docs/for-ai/operations/createOAuthClient.md",
29
+ "/docs/for-ai/operations/createSyntheticEvent.md",
30
+ "/docs/for-ai/operations/createToken.md",
31
+ "/docs/for-ai/operations/createView.md",
32
+ "/docs/for-ai/operations/deleteAccessControlRule.md",
33
+ "/docs/for-ai/operations/deleteAuthLink.md",
34
+ "/docs/for-ai/operations/deleteEndpoint.md",
35
+ "/docs/for-ai/operations/deleteEndpointGroup.md",
36
+ "/docs/for-ai/operations/deleteEventDeadLetter.md",
37
+ "/docs/for-ai/operations/deleteFlow.md",
38
+ "/docs/for-ai/operations/deleteFlowNode.md",
39
+ "/docs/for-ai/operations/deleteFlowRun.md",
40
+ "/docs/for-ai/operations/deleteGroupRoute.md",
41
+ "/docs/for-ai/operations/deleteOAuthClient.md",
42
+ "/docs/for-ai/operations/deletePlugin.md",
43
+ "/docs/for-ai/operations/deletePrincipal.md",
44
+ "/docs/for-ai/operations/deleteRoute.md",
45
+ "/docs/for-ai/operations/deleteSecret.md",
46
+ "/docs/for-ai/operations/deleteSimulator.md",
47
+ "/docs/for-ai/operations/deleteSubscription.md",
48
+ "/docs/for-ai/operations/deleteView.md",
49
+ "/docs/for-ai/operations/deviceAuthorize.md",
50
+ "/docs/for-ai/operations/endpointGroupsManage.md",
51
+ "/docs/for-ai/operations/endpointQuery.md",
52
+ "/docs/for-ai/operations/enumerateAuthLinks.md",
53
+ "/docs/for-ai/operations/enumerateEndpointGroups.md",
54
+ "/docs/for-ai/operations/enumerateEndpoints.md",
55
+ "/docs/for-ai/operations/enumerateEventDeadLetters.md",
56
+ "/docs/for-ai/operations/enumerateFlowNodeSpecifications.md",
57
+ "/docs/for-ai/operations/enumerateFlowNodes.md",
58
+ "/docs/for-ai/operations/enumerateGroupRelationships.md",
59
+ "/docs/for-ai/operations/enumerateGroupRoutes.md",
60
+ "/docs/for-ai/operations/enumerateOAuthClients.md",
61
+ "/docs/for-ai/operations/enumeratePlugins.md",
62
+ "/docs/for-ai/operations/enumeratePrincipals.md",
63
+ "/docs/for-ai/operations/enumerateSecrets.md",
64
+ "/docs/for-ai/operations/enumerateSimulators.md",
65
+ "/docs/for-ai/operations/enumerateSubscriptions.md",
66
+ "/docs/for-ai/operations/enumerateTokens.md",
67
+ "/docs/for-ai/operations/enumerateViews.md",
68
+ "/docs/for-ai/operations/establishAuthLink.md",
69
+ "/docs/for-ai/operations/establishPlugin.md",
70
+ "/docs/for-ai/operations/evaluateAccessControlRule.md",
71
+ "/docs/for-ai/operations/generateOAuthCode.md",
72
+ "/docs/for-ai/operations/generateToken.md",
73
+ "/docs/for-ai/operations/generateTuyaQrCode.md",
74
+ "/docs/for-ai/operations/getAccessControlRules.md",
75
+ "/docs/for-ai/operations/getEndpointGroup.md",
76
+ "/docs/for-ai/operations/getEventDeadLetter.md",
77
+ "/docs/for-ai/operations/getEventReceipt.md",
78
+ "/docs/for-ai/operations/getJWKS.md",
79
+ "/docs/for-ai/operations/getMCPOAuthProtectedResourceMetadata.md",
80
+ "/docs/for-ai/operations/getMetrics.md",
81
+ "/docs/for-ai/operations/getOAuthAuthorizationServerMetadata.md",
82
+ "/docs/for-ai/operations/getOAuthClient.md",
83
+ "/docs/for-ai/operations/getOAuthProtectedResourceMetadata.md",
84
+ "/docs/for-ai/operations/getOpenIDConfiguration.md",
85
+ "/docs/for-ai/operations/getPendingOAuthConsent.md",
86
+ "/docs/for-ai/operations/getRoutes.md",
87
+ "/docs/for-ai/operations/getSubscription.md",
88
+ "/docs/for-ai/operations/getView.md",
89
+ "/docs/for-ai/operations/handleGitHubWebhook.md",
90
+ "/docs/for-ai/operations/handleGoogleCloudSchedulerWebhook.md",
91
+ "/docs/for-ai/operations/handleOAuthCallback.md",
92
+ "/docs/for-ai/operations/handleSmartThingsWebhook.md",
93
+ "/docs/for-ai/operations/invalidateToken.md",
94
+ "/docs/for-ai/operations/modifyEndpoint.md",
95
+ "/docs/for-ai/operations/patchSubscription.md",
96
+ "/docs/for-ai/operations/ping.md",
97
+ "/docs/for-ai/operations/pluginAuthCodeExchange.md",
98
+ "/docs/for-ai/operations/pluginAuthCodeLink.md",
99
+ "/docs/for-ai/operations/pluginAuthMultifactorExchange.md",
100
+ "/docs/for-ai/operations/pushToMessageGateway.md",
101
+ "/docs/for-ai/operations/queryFlowRuns.md",
102
+ "/docs/for-ai/operations/queryFlows.md",
103
+ "/docs/for-ai/operations/raiseAnonymousPrincipal.md",
104
+ "/docs/for-ai/operations/redriveEventDeadLetter.md",
105
+ "/docs/for-ai/operations/refreshAuthLinkToken.md",
106
+ "/docs/for-ai/operations/registerDynamicOAuthClient.md",
107
+ "/docs/for-ai/operations/removeEndpointGroupMembers.md",
108
+ "/docs/for-ai/operations/requestFutureIntegration.md",
109
+ "/docs/for-ai/operations/revokeOAuthGrant.md",
110
+ "/docs/for-ai/operations/sendMessage.md",
111
+ "/docs/for-ai/operations/sendMessageLegacyAlias.md",
112
+ "/docs/for-ai/operations/setEndpointGroupName.md",
113
+ "/docs/for-ai/operations/setFlowRunStatus.md",
114
+ "/docs/for-ai/operations/synchronizeRoutes.md",
115
+ "/docs/for-ai/operations/triggerFlow.md",
116
+ "/docs/for-ai/operations/updateOAuthClient.md",
117
+ "/docs/for-ai/operations/updateView.md",
118
+ "/docs/for-ai/operations/upsertAccessControlRule.md",
119
+ "/docs/for-ai/operations/upsertAuthLink.md",
120
+ "/docs/for-ai/operations/upsertEndpoint.md",
121
+ "/docs/for-ai/operations/upsertFlow.md",
122
+ "/docs/for-ai/operations/upsertFlowRunMessage.md",
123
+ "/docs/for-ai/operations/upsertPluginRequest.md",
124
+ "/docs/for-ai/operations/upsertPrincipal.md",
125
+ "/docs/for-ai/operations/upsertRoute.md",
126
+ "/docs/for-ai/operations/upsertSecret.md",
127
+ "/docs/for-ai/operations/upsertSimulator.md",
128
+ "/docs/for-ai/operations/upsertSubscription.md",
129
+ "/docs/for-ai/operations/validateOAuthRequest.md",
130
+ "/docs/for-ai/operations/validateTuyaLoginCode.md",
131
+ "/docs/for-ai/operations/verifyDevice.md",
132
+ "/docs/references/openapi.yaml"
133
+ ]
134
+ },
11
135
  {
12
136
  "path": "/docs/for-ai/capability-interfaces.md",
13
137
  "contentType": "text/plain; charset=utf-8",
@@ -1184,8 +1308,8 @@
1184
1308
  {
1185
1309
  "path": "/docs/for-ai/guides/authentication-and-dcr.md",
1186
1310
  "contentType": "text/plain; charset=utf-8",
1187
- "bytes": 16740,
1188
- "sha256": "69ff1fda5f5443ed1fa5c21abdfa5dda5c73b1edc6e54b9f056776f881d7dc80",
1311
+ "bytes": 17581,
1312
+ "sha256": "32616ea9e28a675efe2c2dee51f149eefec2dead1af2b5275b91c3c9bae3a7be",
1189
1313
  "links": [
1190
1314
  "/docs/for-ai/guides/authorization-rules.md",
1191
1315
  "/docs/for-ai/guides/first-setup.md",
@@ -1227,15 +1351,17 @@
1227
1351
  {
1228
1352
  "path": "/docs/for-ai/guides/connect-agent.md",
1229
1353
  "contentType": "text/plain; charset=utf-8",
1230
- "bytes": 2474,
1231
- "sha256": "2ace8142f363edcf8d48039f463fd2528307ffac1c3238301d85e8955b234e6a",
1354
+ "bytes": 2919,
1355
+ "sha256": "5aa9459297c58a1b648b2385a546b25814567c4bdbaef30ab03ffe909f73d391",
1232
1356
  "links": [
1357
+ "/docs/for-ai/guides/authentication-and-dcr.md",
1233
1358
  "/docs/for-ai/guides/authorization-rules.md",
1234
1359
  "/docs/for-ai/guides/first-setup.md",
1235
1360
  "/docs/for-ai/guides/oauth-client-registration.md",
1236
1361
  "/docs/for-ai/guides/oauth-consent-and-callback.md",
1237
1362
  "/docs/for-ai/guides/oauth-discovery.md",
1238
- "/docs/for-ai/guides/oauth-token-lifecycle.md"
1363
+ "/docs/for-ai/guides/oauth-token-lifecycle.md",
1364
+ "/docs/for-ai/guides/quickstart.md"
1239
1365
  ]
1240
1366
  },
1241
1367
  {
@@ -1270,8 +1396,8 @@
1270
1396
  {
1271
1397
  "path": "/docs/for-ai/guides/index.md",
1272
1398
  "contentType": "text/plain; charset=utf-8",
1273
- "bytes": 1838,
1274
- "sha256": "becf671ec3d3e46eafd6dfe8ac99e14b780534fc435a55c1b997d5b32498cfa5",
1399
+ "bytes": 2190,
1400
+ "sha256": "936e643766ce6a3c245a03f91b8a1b74087ce4cfa237e6f94e8e0939e92a6720",
1275
1401
  "links": [
1276
1402
  "/docs/for-ai/guides/adding-devices.md",
1277
1403
  "/docs/for-ai/guides/authentication-and-dcr.md",
@@ -1301,12 +1427,14 @@
1301
1427
  {
1302
1428
  "path": "/docs/for-ai/guides/lighting.md",
1303
1429
  "contentType": "text/plain; charset=utf-8",
1304
- "bytes": 1290,
1305
- "sha256": "f393b36c9e149709185f18d4b7f2c29a6fae457d18c2d32e34c56040efb1fb3f",
1430
+ "bytes": 2462,
1431
+ "sha256": "4630b0541a7b9de1c605d4bbf9dee7946a0889ca0eb364c628a9878f868e27fe",
1306
1432
  "links": [
1307
1433
  "/docs/for-ai/capability-interfaces.md",
1308
1434
  "/docs/for-ai/guides/authorization-rules.md",
1309
- "/docs/for-ai/guides/quickstart.md"
1435
+ "/docs/for-ai/guides/managing-groups.md",
1436
+ "/docs/for-ai/guides/quickstart.md",
1437
+ "/docs/for-ai/operations/endpointQuery.md"
1310
1438
  ]
1311
1439
  },
1312
1440
  {
@@ -1366,8 +1494,8 @@
1366
1494
  {
1367
1495
  "path": "/docs/for-ai/guides/oauth-discovery.md",
1368
1496
  "contentType": "text/plain; charset=utf-8",
1369
- "bytes": 2545,
1370
- "sha256": "e04f8ab874da6c399c59c7f4618da37f99160f87c7f0adf39800486d6fb3192f",
1497
+ "bytes": 2850,
1498
+ "sha256": "588efd7396d2b5b600eb2bd085d1c947afc429fb5f383cc3093734e9ce2a27c7",
1371
1499
  "links": [
1372
1500
  "/docs/for-ai/guides/authorization-rules.md",
1373
1501
  "/docs/for-ai/guides/oauth-client-registration.md",
@@ -1452,12 +1580,14 @@
1452
1580
  {
1453
1581
  "path": "/docs/for-ai/guides/using-the-api.md",
1454
1582
  "contentType": "text/plain; charset=utf-8",
1455
- "bytes": 1490,
1456
- "sha256": "3d54f9aadddb70cfe6630f8a72cbf50f0163467768e09fc5beece88b8538e909",
1583
+ "bytes": 2995,
1584
+ "sha256": "13207d4668ca60055c5edc4ab4b9f582abdb5a676c9edaacc5c92c054672819d",
1457
1585
  "links": [
1586
+ "/docs/for-ai/api-catalog.md",
1458
1587
  "/docs/for-ai/guides/authentication-and-dcr.md",
1459
1588
  "/docs/for-ai/guides/authorization-rules.md",
1460
1589
  "/docs/for-ai/guides/lighting.md",
1590
+ "/docs/for-ai/operations/endpointQuery.md",
1461
1591
  "/docs/for-ai/operations/index.md",
1462
1592
  "/docs/references/openapi.yaml"
1463
1593
  ]
@@ -1475,12 +1605,13 @@
1475
1605
  {
1476
1606
  "path": "/docs/for-ai/index.md",
1477
1607
  "contentType": "text/plain; charset=utf-8",
1478
- "bytes": 1185,
1479
- "sha256": "ed6011cbe96c70b27fe8ec486c24beb69737ec570b14368b580ba855179e1383",
1608
+ "bytes": 2064,
1609
+ "sha256": "a34ccabe7c6f4b0b9d1b35eece14fdebbdf6ec638596232a8528d4d4714a9fa1",
1480
1610
  "links": [
1611
+ "/docs/for-ai/api-catalog.md",
1481
1612
  "/docs/for-ai/capability-interfaces.md",
1482
1613
  "/docs/for-ai/guides/authentication-and-dcr.md",
1483
- "/docs/for-ai/guides/authorization-rules.md",
1614
+ "/docs/for-ai/guides/connect-agent.md",
1484
1615
  "/docs/for-ai/guides/index.md",
1485
1616
  "/docs/for-ai/guides/quickstart.md",
1486
1617
  "/docs/for-ai/operations/index.md",
@@ -1842,8 +1973,8 @@
1842
1973
  {
1843
1974
  "path": "/docs/for-ai/operations/endpointQuery.md",
1844
1975
  "contentType": "text/plain; charset=utf-8",
1845
- "bytes": 2554,
1846
- "sha256": "aac7b487054a992fa385bef6e8df068e79789a9c8d12e08678aa196f8c76af2f",
1976
+ "bytes": 5199,
1977
+ "sha256": "85bf525fe235fafa09159bb4437fcb543a4de8c99dcec57077601b3e7af958a2",
1847
1978
  "links": [
1848
1979
  "/docs/for-ai/guides/authentication-and-dcr.md",
1849
1980
  "/docs/for-ai/schemas.md",
@@ -3978,15 +4109,15 @@
3978
4109
  {
3979
4110
  "path": "/docs/references/authorization.json",
3980
4111
  "contentType": "application/json",
3981
- "bytes": 38378,
3982
- "sha256": "459c04391581ab68829ab3db1b89a99ec1bee41948afee6c314702a27d054370",
4112
+ "bytes": 38470,
4113
+ "sha256": "d989ea6620017866d148d85cea1b23754c66132e2a91d0263d17a315b3e7066e",
3983
4114
  "links": []
3984
4115
  },
3985
4116
  {
3986
4117
  "path": "/docs/references/authorization.yaml",
3987
4118
  "contentType": "application/yaml; charset=utf-8",
3988
- "bytes": 28365,
3989
- "sha256": "00ceec4850728a5e80577a592c132d3a881686b407c3fd2784b4fba1eaf8f57f",
4119
+ "bytes": 28424,
4120
+ "sha256": "49456bdf5aabc3dfcee05bb1dece7fe89e0d727eecc58bac510943d736a7345e",
3990
4121
  "links": []
3991
4122
  },
3992
4123
  {
@@ -7350,8 +7481,8 @@
7350
7481
  {
7351
7482
  "path": "/docs/references/openapi.yaml",
7352
7483
  "contentType": "application/yaml; charset=utf-8",
7353
- "bytes": 757609,
7354
- "sha256": "a6db7cfd7943b4298c07af9dbf1078bcccc15725fa3a4e7a329f92c18e19c89c",
7484
+ "bytes": 761899,
7485
+ "sha256": "a5ae633442765553a3fc97f5a14678290d8dee6d6458cd8975236659ef5537c8",
7355
7486
  "links": []
7356
7487
  },
7357
7488
  {
@@ -8757,8 +8888,8 @@
8757
8888
  {
8758
8889
  "path": "/docs/references/schemas/EndpointQueryRequest.json",
8759
8890
  "contentType": "application/json",
8760
- "bytes": 493,
8761
- "sha256": "7f3bc6e0aeca233394416f5edbf910f2caef13ab0817ecefc5a22dffaaf81239",
8891
+ "bytes": 2558,
8892
+ "sha256": "ace0583c690fcdce12a099f8d633322922dd51c428fc310e9dd33e0789a46074",
8762
8893
  "links": []
8763
8894
  },
8764
8895
  {
package/generated/public/docs/references/openapi.yaml CHANGED
@@ -858,7 +858,19 @@ paths:
858
858
  operationId: endpointQuery
859
859
  tags:
860
860
  - Endpoints
861
- description: Query for endpoints
861
+ description: >-
862
+ Return a bounded page of authorized endpoints matching the shared Query expression,
863
+ including endpoints shared by other owners. Read permission is evaluated before filtering,
864
+ pagination and state expansion. See the request schema for supported fields and operators.
865
+ Use groupId to select members of a readable room/group, then intersect type or declared
866
+ interfaces to select lights. Group predicates additionally require group:read for delegated
867
+ OAuth. Repeat the complete query settings and grant when following nextToken; cursors expire
868
+ after fifteen minutes. Device attributes are returned only when expanded. Report per-target
869
+ command acceptance and observed state separately; querying a group does not grant permission
870
+ to control its members.
871
+ x-portos-conditional-scopes:
872
+ groupId:
873
+ - group:read
862
874
  requestBody:
863
875
  required: true
864
876
  content:
@@ -868,8 +880,10 @@ paths:
868
880
  example:
869
881
  query:
870
882
  match:
871
- key: name
872
- value: test
883
+ key: type
884
+ value: LIGHT
885
+ paginationContext:
886
+ maxResults: 10
873
887
  responses:
874
888
  '200':
875
889
  description: Endpoints retrieved successfully
@@ -879,10 +893,8 @@ paths:
879
893
  $ref: '#/components/schemas/EndpointQueryResponse'
880
894
  example:
881
895
  results: []
882
- paginationContext:
883
- nextToken: abc123
884
896
  '400':
885
- description: Bad request - missing required parameters
897
+ description: Invalid query, unsupported expansion, or invalid/expired/mismatched cursor.
886
898
  content:
887
899
  application/json:
888
900
  schema:
@@ -901,6 +913,36 @@ paths:
901
913
  message: Unauthorized - invalid or missing authentication token
902
914
  code: UNAUTHORIZED
903
915
  family: AUTHENTICATION
916
+ '403':
917
+ description: Missing conditional OAuth scope or permission to read a referenced group.
918
+ content:
919
+ application/json:
920
+ schema:
921
+ $ref: '#/components/schemas/Error'
922
+ example:
923
+ message: Permission to read the requested group is required.
924
+ code: FORBIDDEN
925
+ family: FORBIDDEN
926
+ '404':
927
+ description: A referenced group does not exist.
928
+ content:
929
+ application/json:
930
+ schema:
931
+ $ref: '#/components/schemas/Error'
932
+ example:
933
+ message: Requested group was not found.
934
+ code: NOT_FOUND
935
+ family: NOT_FOUND
936
+ '409':
937
+ description: A selected disabled endpoint cannot be forcibly refreshed.
938
+ content:
939
+ application/json:
940
+ schema:
941
+ $ref: '#/components/schemas/Error'
942
+ example:
943
+ message: endpoint messaging is disabled
944
+ code: ENDPOINT_DISABLED
945
+ family: CONFLICT
904
946
  '500':
905
947
  description: Internal server error
906
948
  content:
@@ -18543,18 +18585,59 @@ components:
18543
18585
  description: The value to match on
18544
18586
  EndpointQueryRequest:
18545
18587
  type: object
18588
+ additionalProperties: false
18546
18589
  required:
18547
18590
  - query
18548
18591
  properties:
18549
18592
  query:
18550
18593
  $ref: '#/components/schemas/Query'
18594
+ description: >-
18595
+ A bounded shared Query expression. An empty object selects unfiltered readable
18596
+ inventory. This endpoint supports match, and, or, and not. Scalar match keys are id,
18597
+ name, type, ownerId, manufacturer, model, and enablement. interfaces matches membership
18598
+ in the endpoint's declared interface names; groupId matches membership in a readable
18599
+ endpoint group. Comparisons, patterns, freeform search, unknown keys, ambiguous nodes,
18600
+ expressions deeper than eight levels, or more than 64 nodes return 400. Values are exact
18601
+ strings. Collections hide disabled endpoints unless the expression explicitly filters
18602
+ enablement. Results include readable shared endpoints, regardless of their owner. A
18603
+ groupId predicate additionally requires group:read for delegated OAuth and read
18604
+ permission on that group.
18551
18605
  paginationContext:
18552
- $ref: '#/components/schemas/PaginationContext'
18606
+ type: object
18607
+ additionalProperties: false
18608
+ properties:
18609
+ maxResults:
18610
+ type: integer
18611
+ minimum: 1
18612
+ maximum: 100
18613
+ default: 10
18614
+ description: Maximum authorized matching endpoints in this page.
18615
+ nextToken:
18616
+ type: string
18617
+ minLength: 1
18618
+ description: >-
18619
+ Opaque server-issued continuation token. Repeat the same query, page size,
18620
+ expansions, forceDeviceQuery setting, and authenticated grant. Modified, expired, or
18621
+ differently bound tokens return 400; restart without nextToken. Follow nextToken
18622
+ until absent, including empty pages.
18553
18623
  expand:
18554
18624
  type: array
18555
- description: Expansion tokens that request related or computed endpoint fields.
18625
+ uniqueItems: true
18626
+ maxItems: 1
18627
+ description: Optional reported state expansion; only interfaces.attributes is supported.
18556
18628
  items:
18557
18629
  type: string
18630
+ enum:
18631
+ - interfaces.attributes
18632
+ x-enum-exempt: Existing published REST expansion token shared with GET /endpoints.
18633
+ forceDeviceQuery:
18634
+ type: boolean
18635
+ default: false
18636
+ description: >-
18637
+ Refresh reported device attributes for the selected page. Requires expand to contain
18638
+ interfaces.attributes. An accepted command is not proof of device state; inspect the
18639
+ returned sample times and partial errors. Disabled endpoints cannot be forcibly
18640
+ refreshed.
18558
18641
  Simulator:
18559
18642
  description: Legacy string-name application/json projection; default representation remains unchanged.
18560
18643
  allOf: