@portpowered/reference-data 0.4.3 → 0.4.4

package/README.md

@@ -1,6 +1,6 @@
 ---
 author: Port OS Team
-last modified: 2026, october, 7
+last modified: 2026, october, 9
 ---
 
 # Port OS reference data

package/generated/guides.json

@@ -104,7 +104,7 @@
   {
     "id": "quickstart",
     "title": "Verify the connection and control one light",
-    "content": "# Verify the connection and control one light\n\nFirst complete [OAuth setup](/docs/for-ai/guides/authentication-and-dcr.md). Keep the discovered API issuer and credentials in client configuration.\n\n1. GET /endpoints?owner=~caller&maxResults=25 with Authorization: Bearer <access_token>. Read [enumerateEndpoints](/docs/for-ai/operations/enumerateEndpoints.md) for the exact pagination and response fields. A filter such as owner is required. Follow the returned continuation metadata until the authorized enumeration is complete. An empty list means valid access with no visible devices; guide the user to [add devices](/docs/for-ai/guides/adding-devices.md).\n2. Select one light by full endpoint ID and group/room context. If the target is ambiguous, ask the user before acting.\n3. Inspect its declared capability namespace and version. A light declaring power 1.0 uses the [power guide](/docs/for-ai/capability-interfaces/power/1.0.md) and [turn-on payload schema](/docs/references/capability-interfaces/power/1.0/messages/turn-on.yaml). For other versions or capabilities, follow [the capability directory](/docs/for-ai/capability-interfaces.md).\n4. With the user's intended action, POST /messages. Read [sendMessage](/docs/for-ai/operations/sendMessage.md) and its linked request schema. Use the endpoint ID and message version you discovered, not the illustrative ID below.\n\n```json\n{\"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\":{}}}\n```\n\nThe response's messageId identifies dispatch. It is not proof of physical state. Do not cut JSON with head -c. GET /endpoints?id=<URL-encoded-endpoint-id>&expand=interfaces.attributes&forceDeviceAttributeQuery=true to request permitted device-backed state. Inspect attributes and partial errors. Check sampledAt against the command time and the capability version. sampledAt is the source-reported time, not the fetch time; an absent timestamp means freshness is unknown. Use [enumerateEndpoints and its linked components](/docs/for-ai/operations/enumerateEndpoints.md) for exact response shapes. Report returned device state separately from dispatch acceptance. Stale/unavailable state means unknown, and user confirmation may be necessary for a physical device.\n\nFor first setup, test one explicitly selected safe light. Do not turn off all homes as a connectivity check. See [lighting](/docs/for-ai/guides/lighting.md), [first setup](/docs/for-ai/guides/first-setup.md) and [authorization rules](/docs/for-ai/guides/authorization-rules.md).\n",
+    "content": "# Verify the connection and control one light\n\nFirst complete [OAuth setup](/docs/for-ai/guides/authentication-and-dcr.md). Keep the discovered API issuer and credentials in client configuration.\n\n1. GET /endpoints?owner=~caller&maxResults=25 with Authorization: Bearer <access_token>. Read [enumerateEndpoints](/docs/for-ai/operations/enumerateEndpoints.md) for the exact pagination and response fields. A filter such as owner is required. Follow the returned continuation metadata until the authorized enumeration is complete. An empty list means valid access with no visible devices; guide the user to [add devices](/docs/for-ai/guides/adding-devices.md).\n2. Select one light by full endpoint ID and group/room context. If the target is ambiguous, ask the user before acting.\n3. Inspect its declared capability namespace and version. A light declaring power 1.0 uses the [power guide](/docs/for-ai/capability-interfaces/power/1.0.md) and [turn-on payload schema](/docs/references/capability-interfaces/power/1.0/messages/turn-on.yaml). For other versions or capabilities, follow [the capability directory](/docs/for-ai/capability-interfaces.md).\n4. With the user's intended action, POST /messages with Authorization: Bearer <access_token> and Content-Type: application/json. Send the request object below as the JSON body, without a surrounding `body` field or a JSON string. Read [sendMessage](/docs/for-ai/operations/sendMessage.md) and its linked request schema. Use the endpoint ID and message version you discovered, not the illustrative ID below.\n\n```json\n{\"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\":{}}}\n```\n\nHTTP 200 acknowledges acceptance. An asynchronous request can return `{\"messageId\":\"\"}` without a `message`; the empty ID is valid and does not provide a durable receipt or retry deduplication. When a unary response message is present, `messageId` identifies that response. Neither response proves physical state. After a lost response, treat the outcome as unknown and inspect state before deciding whether another action is safe.\n\nDo not cut JSON with head -c. GET /endpoints?id=<URL-encoded-endpoint-id>&expand=interfaces.attributes&forceDeviceAttributeQuery=true to request permitted device-backed state. Inspect attributes and partial errors. Check sampledAt against the command time and the capability version. sampledAt is the source-reported time, not the fetch time; an absent timestamp means freshness is unknown. Use [enumerateEndpoints and its linked components](/docs/for-ai/operations/enumerateEndpoints.md) for exact response shapes. Report returned device state separately from dispatch acceptance. Stale/unavailable state means unknown, and user confirmation may be necessary for a physical device.\n\nFor first setup, test one explicitly selected safe light. Do not turn off all homes as a connectivity check. See [lighting](/docs/for-ai/guides/lighting.md), [first setup](/docs/for-ai/guides/first-setup.md) and [authorization rules](/docs/for-ai/guides/authorization-rules.md).\n",
     "setupPrompt": null
   },
   {

package/generated/openapi.json

@@ -9826,14 +9826,14 @@
         },
         "responses": {
           "200": {
-            "description": "Message sent successfully",
+            "description": "Request accepted; an asynchronous acknowledgment may have an empty messageId and no message. Verify device state separately.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateMessageResponse"
                 },
                 "example": {
-                  "messageId": "example-dispatch-id"
+                  "messageId": ""
                 }
               }
             }
@@ -10106,14 +10106,14 @@
         },
         "responses": {
           "200": {
-            "description": "Message sent successfully",
+            "description": "Request accepted; an asynchronous acknowledgment may have an empty messageId and no message. Verify device state separately.",
             "content": {
               "application/json": {
                 "schema": {
                   "$ref": "#/components/schemas/CreateMessageResponse"
                 },
                 "example": {
-                  "messageId": "example-dispatch-id"
+                  "messageId": ""
                 }
               }
             }
@@ -26762,7 +26762,7 @@
         "properties": {
           "messageId": {
             "type": "string",
-            "description": "The ID of the created message"
+            "description": "Identifies the unary response message when one is returned. An accepted asynchronous request can return an empty string with no message. This field does not provide a durable dispatch receipt, retry deduplication or proof of observed device state."
           },
           "message": {
             "$ref": "#/components/schemas/Message",

package/generated/public/docs/for-ai/guides/quickstart.md

@@ -5,12 +5,14 @@ First complete [OAuth setup](/docs/for-ai/guides/authentication-and-dcr.md). Kee
 1. GET /endpoints?owner=~caller&maxResults=25 with Authorization: Bearer <access_token>. Read [enumerateEndpoints](/docs/for-ai/operations/enumerateEndpoints.md) for the exact pagination and response fields. A filter such as owner is required. Follow the returned continuation metadata until the authorized enumeration is complete. An empty list means valid access with no visible devices; guide the user to [add devices](/docs/for-ai/guides/adding-devices.md).
 2. Select one light by full endpoint ID and group/room context. If the target is ambiguous, ask the user before acting.
 3. Inspect its declared capability namespace and version. A light declaring power 1.0 uses the [power guide](/docs/for-ai/capability-interfaces/power/1.0.md) and [turn-on payload schema](/docs/references/capability-interfaces/power/1.0/messages/turn-on.yaml). For other versions or capabilities, follow [the capability directory](/docs/for-ai/capability-interfaces.md).
-4. With the user's intended action, POST /messages. Read [sendMessage](/docs/for-ai/operations/sendMessage.md) and its linked request schema. Use the endpoint ID and message version you discovered, not the illustrative ID below.
+4. With the user's intended action, POST /messages with Authorization: Bearer <access_token> and Content-Type: application/json. Send the request object below as the JSON body, without a surrounding `body` field or a JSON string. Read [sendMessage](/docs/for-ai/operations/sendMessage.md) and its linked request schema. Use the endpoint ID and message version you discovered, not the illustrative ID below.
 
 ```json
 {"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":{}}}
 ```
 
-The response's messageId identifies dispatch. It is not proof of physical state. Do not cut JSON with head -c. GET /endpoints?id=<URL-encoded-endpoint-id>&expand=interfaces.attributes&forceDeviceAttributeQuery=true to request permitted device-backed state. Inspect attributes and partial errors. Check sampledAt against the command time and the capability version. sampledAt is the source-reported time, not the fetch time; an absent timestamp means freshness is unknown. Use [enumerateEndpoints and its linked components](/docs/for-ai/operations/enumerateEndpoints.md) for exact response shapes. Report returned device state separately from dispatch acceptance. Stale/unavailable state means unknown, and user confirmation may be necessary for a physical device.
+HTTP 200 acknowledges acceptance. An asynchronous request can return `{"messageId":""}` without a `message`; the empty ID is valid and does not provide a durable receipt or retry deduplication. When a unary response message is present, `messageId` identifies that response. Neither response proves physical state. After a lost response, treat the outcome as unknown and inspect state before deciding whether another action is safe.
+
+Do not cut JSON with head -c. GET /endpoints?id=<URL-encoded-endpoint-id>&expand=interfaces.attributes&forceDeviceAttributeQuery=true to request permitted device-backed state. Inspect attributes and partial errors. Check sampledAt against the command time and the capability version. sampledAt is the source-reported time, not the fetch time; an absent timestamp means freshness is unknown. Use [enumerateEndpoints and its linked components](/docs/for-ai/operations/enumerateEndpoints.md) for exact response shapes. Report returned device state separately from dispatch acceptance. Stale/unavailable state means unknown, and user confirmation may be necessary for a physical device.
 
 For first setup, test one explicitly selected safe light. Do not turn off all homes as a connectivity check. See [lighting](/docs/for-ai/guides/lighting.md), [first setup](/docs/for-ai/guides/first-setup.md) and [authorization rules](/docs/for-ai/guides/authorization-rules.md).

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

@@ -114,13 +114,15 @@ post:
             body: {}
   responses:
     '200':
-      description: Message sent successfully
+      description: >-
+        Request accepted; an asynchronous acknowledgment may have an empty messageId and no message.
+        Verify device state separately.
       content:
         application/json:
           schema:
             $ref: /docs/references/schemas/CreateMessageResponse.json
           example:
-            messageId: example-dispatch-id
+            messageId: ''
     '400':
       description: Invalid request payload or plugin dispatch request error
       content:

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

@@ -114,13 +114,15 @@ post:
             body: {}
   responses:
     '200':
-      description: Message sent successfully
+      description: >-
+        Request accepted; an asynchronous acknowledgment may have an empty messageId and no message.
+        Verify device state separately.
       content:
         application/json:
           schema:
             $ref: /docs/references/schemas/CreateMessageResponse.json
           example:
-            messageId: example-dispatch-id
+            messageId: ''
     '400':
       description: Invalid request payload or plugin dispatch request error
       content:

package/generated/public/docs/references/manifest.json

@@ -1,12 +1,12 @@
 {
   "package": "@portpowered/reference-data",
   "goModule": "github.com/portpowered/portos-reference-data",
-  "version": "0.4.3",
-  "sourceCommit": "eecb0269b4626c38f646c4ed03b55a793c511bbd",
+  "version": "0.4.4",
+  "sourceCommit": "ddab20777e6044b21db0f0c1c525bf59ff4f31f0",
   "sourceInputState": "committed",
-  "sourceInputSHA256": "19728ad478ab3d79f8f50f3d816de492ad6dd9f3361a2a1cd097448b5264b260",
+  "sourceInputSHA256": "8a1f7e267ecac60eaf7a4e7ded150b2ff86ac59760c11b5251b52e4a78db40ca",
   "sourceInputCount": 735,
-  "assetSetSHA256": "47173fdb53c1c85580bf61d001555c969acf468d8dd1ffe33dfc84de92f6eaec",
+  "assetSetSHA256": "d101a7e55686035b22ab0b4e5cc2839c8e9c835db31d6ef329c6e801f53c848b",
   "files": [
     {
       "path": "/docs/for-ai/capability-interfaces.md",
@@ -1401,8 +1401,8 @@
     {
       "path": "/docs/for-ai/guides/quickstart.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 2650,
-      "sha256": "34606cd8f50344acfbc3becd901518e2b83e2b0b2666d4ce59579b7d6d564058",
+      "bytes": 3180,
+      "sha256": "a230400fa9f48bd5b629bad119bf079cbdf2faabee6270137ae0e9b2fa0b0fce",
       "links": [
         "/docs/for-ai/capability-interfaces.md",
         "/docs/for-ai/capability-interfaces/power/1.0.md",
@@ -2649,8 +2649,8 @@
     {
       "path": "/docs/for-ai/operations/sendMessage.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 9642,
-      "sha256": "11f1a2ba1c1e57b0cf283564d210057545fe22b83eb1fba8baf562ee1be351c2",
+      "bytes": 9743,
+      "sha256": "e9c1092a4809c9298d03d3bf0baec094125ea2f28ce2eddea031d2d8252e4f6d",
       "links": [
         "/docs/for-ai/guides/authentication-and-dcr.md",
         "/docs/for-ai/schemas.md",
@@ -2662,8 +2662,8 @@
     {
       "path": "/docs/for-ai/operations/sendMessageLegacyAlias.md",
       "contentType": "text/plain; charset=utf-8",
-      "bytes": 9913,
-      "sha256": "d2be61f7dc58f08addaf59ae65317eb121cb003ac91a9cea20280b05ea769baa",
+      "bytes": 10014,
+      "sha256": "0194b7b87f6ead4e405250f0e3710d89447e7d56e0df8efad9b57f800bf9a8af",
       "links": [
         "/docs/for-ai/guides/authentication-and-dcr.md",
         "/docs/for-ai/schemas.md",
@@ -7350,8 +7350,8 @@
     {
       "path": "/docs/references/openapi.yaml",
       "contentType": "application/yaml; charset=utf-8",
-      "bytes": 757134,
-      "sha256": "35386f69ebbd31904ad9d63fbf5aecbea8648f0f6ff2925e1653ff60c3fd9387",
+      "bytes": 757609,
+      "sha256": "a6db7cfd7943b4298c07af9dbf1078bcccc15725fa3a4e7a329f92c18e19c89c",
       "links": []
     },
     {
@@ -8407,8 +8407,8 @@
     {
       "path": "/docs/references/schemas/CreateMessageResponse.json",
       "contentType": "application/json",
-      "bytes": 580,
-      "sha256": "c75f34dcf1e8efdcceb0f584d12e25159ee65165cb2ccfff7d8331a18d69d7a2",
+      "bytes": 798,
+      "sha256": "d97a132f4abb5f70006e0f1340dd04a8d76e954c19b5bb557e86360a68071be5",
       "links": []
     },
     {

package/generated/public/docs/references/openapi.yaml

@@ -7136,13 +7136,15 @@ paths:
                 body: {}
       responses:
         '200':
-          description: Message sent successfully
+          description: >-
+            Request accepted; an asynchronous acknowledgment may have an empty messageId and no
+            message. Verify device state separately.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/CreateMessageResponse'
               example:
-                messageId: example-dispatch-id
+                messageId: ''
         '400':
           description: Invalid request payload or plugin dispatch request error
           content:
@@ -7366,13 +7368,15 @@ paths:
                 body: {}
       responses:
         '200':
-          description: Message sent successfully
+          description: >-
+            Request accepted; an asynchronous acknowledgment may have an empty messageId and no
+            message. Verify device state separately.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/CreateMessageResponse'
               example:
-                messageId: example-dispatch-id
+                messageId: ''
         '400':
           description: Invalid request payload or plugin dispatch request error
           content:
@@ -20851,7 +20855,10 @@ components:
       properties:
         messageId:
           type: string
-          description: The ID of the created message
+          description: >-
+            Identifies the unary response message when one is returned. An accepted asynchronous
+            request can return an empty string with no message. This field does not provide a
+            durable dispatch receipt, retry deduplication or proof of observed device state.
         message:
           $ref: '#/components/schemas/Message'
           description: >-

package/generated/public/docs/references/schemas/CreateMessageResponse.json

@@ -7,7 +7,7 @@
   "properties": {
     "messageId": {
       "type": "string",
-      "description": "The ID of the created message"
+      "description": "Identifies the unary response message when one is returned. An accepted asynchronous request can return an empty string with no message. This field does not provide a durable dispatch receipt, retry deduplication or proof of observed device state."
     },
     "message": {
       "$ref": "/docs/references/schemas/Message.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@portpowered/reference-data",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "private": false,
   "publishConfig": { "access": "public" },
   "repository": { "type": "git", "url": "https://github.com/portpowered/portos-reference-data.git" },