@mhome/app-facade-protocol 1.0.0

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) MHOME AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,11 @@
+# mhome-app-facade-api
+
+Canonical public protocol shared by MeowLink clients, MeowCore, the CLI,
+Agents, and cloud adapters.
+
+Every `/app/*` request uses the strict `FacadeCall` envelope. Invocation
+metadata lives in `control`; the domain request lives in `input`. The crate
+owns public targets, request/response/event schemas, and stable operation
+identity. Core-to-Node routes and provider runtime models belong to
+`mhome-core-api` instead.
+

package/fixtures/actor-link-claim-confirm.request.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/actor/link-claim/confirm","direction":"request","body":{"provider":"telegram","placement":"local","challengeId":"challenge_01"}}

package/fixtures/actor-link-claim-confirm.response.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/actor/link-claim/confirm","direction":"response","body":{"claim":{"challengeId":"challenge_01","provider":"telegram","placement":"local","accountId":"bot_a","target":{"audience":"shared","surfaceId":"mg:telegram:bot_a:family"},"expiresAtMs":1720000300000,"lifecycle":{"state":"completed","candidate":{"actor":{"provider":"telegram","accountId":"bot_a","externalUserId":"tg_42","displayName":"Alice"},"address":{"provider":"telegram","accountId":"bot_a","conversationId":"family","audience":"shared"},"eventId":"update_99"},"linkId":"link_42"}}}}

package/fixtures/actor-link-claim-event.response.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/actor/link-claim/changed","direction":"response","body":{"claim":{"challengeId":"challenge_01","provider":"telegram","placement":"local","accountId":"bot_a","target":{"audience":"shared","surfaceId":"mg:telegram:bot_a:family"},"expiresAtMs":1720000300000,"lifecycle":{"state":"awaiting_confirmation","candidate":{"actor":{"provider":"telegram","accountId":"bot_a","externalUserId":"tg_42","displayName":"Alice"},"address":{"provider":"telegram","accountId":"bot_a","conversationId":"family","audience":"shared"},"eventId":"update_99"}}}}}

package/fixtures/actor-link-claim-status.request.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/actor/link-claim/status","direction":"request","body":{"provider":"telegram","placement":"local","challengeId":"challenge_01"}}

package/fixtures/actor-link-claim-status.response.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/actor/link-claim/status","direction":"response","body":{"claim":{"challengeId":"challenge_01","provider":"telegram","placement":"local","accountId":"bot_a","target":{"audience":"shared","surfaceId":"mg:telegram:bot_a:family"},"expiresAtMs":1720000300000,"lifecycle":{"state":"awaiting_confirmation","candidate":{"actor":{"provider":"telegram","accountId":"bot_a","externalUserId":"tg_42","displayName":"Alice"},"address":{"provider":"telegram","accountId":"bot_a","conversationId":"family","audience":"shared"},"eventId":"update_99"}}}}}

package/fixtures/actor-link-code-create.request.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/actor/link-code/create","direction":"request","body":{"provider":"telegram","placement":"local","accountId":"bot_a","target":{"audience":"shared","surfaceId":"mg:telegram:bot_a:family"}}}

package/fixtures/actor-link-code-create.response.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/actor/link-code/create","direction":"response","body":{"challenge":{"challengeId":"challenge_01","code":"P4V8N6","command":"/link P4V8N6","target":{"audience":"shared","surfaceId":"mg:telegram:bot_a:family"},"expiresAtMs":1720000300000}}}

package/fixtures/actor-link-delete.request.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/actor/link/delete","direction":"request","body":{"provider":"telegram","placement":"local","linkId":"link_a"}}

package/fixtures/actor-link-delete.response.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/actor/link/delete","direction":"response","body":{"success":true}}

package/fixtures/actor-link-list.request.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/actor/link/list","direction":"request","body":{"provider":"telegram","placement":"local","accountId":"bot_a"}}

package/fixtures/actor-link-list.response.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/actor/link/list","direction":"response","body":{"links":[{"linkId":"link_a","provider":"telegram","placement":"local","accountId":"bot_a","externalUserId":"user_42","displayName":"Alice","createdAtMs":1720000000000,"updatedAtMs":1720000000000}]}}

package/fixtures/invalid/mismatched-direction.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/shared-account-grant/create",
+  "direction": "response",
+  "body": { "provider": "telegram", "placement": "local", "accountId": "123456" }
+}

package/fixtures/invalid/missing-required-extension.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/provider-account/test",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local" }
+}

package/fixtures/invalid/unknown-request-field.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/provider-account/list",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local", "unexpected": true }
+}

package/fixtures/provider-account-delete.request.json

@@ -0,0 +1,9 @@
+{
+  "target": "/app/messaging/provider-account/delete",
+  "direction": "request",
+  "body": {
+    "provider": "telegram",
+    "placement": "local",
+    "accountId": "123456"
+  }
+}

package/fixtures/provider-account-delete.response.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/provider-account/delete",
+  "direction": "response",
+  "body": { "success": true }
+}

package/fixtures/provider-account-list.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/provider-account/list",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local" }
+}

package/fixtures/provider-account-list.response.json

@@ -0,0 +1,21 @@
+{
+  "target": "/app/messaging/provider-account/list",
+  "direction": "response",
+  "body": {
+    "accounts": [
+      {
+        "provider": "telegram",
+        "placement": "local",
+        "accountId": "123456",
+        "ownership": "user",
+        "displayName": "Home bot",
+        "enabled": true,
+        "status": "connected",
+        "providerData": {
+          "botUsername": "home_bot",
+          "transport": "long_polling"
+        }
+      }
+    ]
+  }
+}

package/fixtures/provider-account-status.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/provider-account/status",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local" }
+}

package/fixtures/provider-account-status.response.json

@@ -0,0 +1,12 @@
+{
+  "target": "/app/messaging/provider-account/status",
+  "direction": "response",
+  "body": {
+    "status": {
+      "provider": "telegram",
+      "placement": "local",
+      "enabled": true,
+      "providerData": { "connected": 1 }
+    }
+  }
+}

package/fixtures/provider-account-test.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/provider-account/test",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local", "data": { "botToken": "secret" } }
+}

package/fixtures/provider-account-test.response.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/provider-account/test",
+  "direction": "response",
+  "body": { "result": { "reachable": true } }
+}

package/fixtures/provider-account-update.request.json

@@ -0,0 +1,10 @@
+{
+  "target": "/app/messaging/provider-account/update",
+  "direction": "request",
+  "body": {
+    "provider": "telegram",
+    "placement": "local",
+    "accountId": "123456",
+    "data": { "enabled": true }
+  }
+}

package/fixtures/provider-account-update.response.json

@@ -0,0 +1,15 @@
+{
+  "target": "/app/messaging/provider-account/update",
+  "direction": "response",
+  "body": {
+    "account": {
+      "provider": "telegram",
+      "placement": "local",
+      "accountId": "123456",
+      "ownership": "user",
+      "enabled": true,
+      "status": "connected",
+      "providerData": {}
+    }
+  }
+}

package/fixtures/provider-list.request.json

@@ -0,0 +1,14 @@
+{
+  "target": "/app/messaging/provider/list",
+  "direction": "request",
+  "body": {
+    "placement": "cloud",
+    "frontendProviders": [
+      {
+        "provider": "telegram",
+        "deprecated": false,
+        "supportedPlacements": ["cloud", "local"]
+      }
+    ]
+  }
+}

package/fixtures/provider-list.response.json

@@ -0,0 +1,35 @@
+{
+  "target": "/app/messaging/provider/list",
+  "direction": "response",
+  "body": {
+    "providers": [
+      {
+        "provider": "telegram",
+        "displayName": "Telegram",
+        "placement": "cloud",
+        "deprecated": false,
+        "available": true,
+        "setupFlow": "pairing_code",
+        "audiences": ["personal", "shared"],
+        "inboundCapabilities": ["text", "audio", "action"],
+        "outboundCapabilities": ["text", "markdown", "action"],
+        "deliveryMode": "unrestricted",
+        "projections": {
+          "notification": { "supported": true },
+          "dialog": { "supported": true }
+        },
+        "managementOperations": [
+          "provider_account.list",
+          "provider_account.status",
+          "route.list",
+          "route.update",
+          "route.delete",
+          "setup.options",
+          "setup.start",
+          "setup.status"
+        ],
+        "providerData": {}
+      }
+    ]
+  }
+}

package/fixtures/route-delete.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/route/delete",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "cloud", "routeId": "route-1" }
+}

package/fixtures/route-delete.response.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/route/delete",
+  "direction": "response",
+  "body": { "success": true }
+}

package/fixtures/route-list.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/route/list",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "cloud", "audience": "personal" }
+}

package/fixtures/route-list.response.json

@@ -0,0 +1,55 @@
+{
+  "target": "/app/messaging/route/list",
+  "direction": "response",
+  "body": {
+    "routes": [
+      {
+        "provider": "telegram",
+        "placement": "cloud",
+        "routeId": "route-1",
+        "accountId": "official-bot",
+        "conversationId": "chat-1",
+        "audience": "personal",
+        "externalActorId": "user-1",
+        "tenantId": "tenant-1",
+        "userId": "mhome-user-1",
+        "scopeId": "scope-1",
+        "displayName": "Telegram",
+        "enabled": true,
+        "projections": {
+          "notification": {
+            "enabled": true,
+            "levels": ["alert", "notify"]
+          },
+          "dialog": {
+            "enabled": true
+          }
+        },
+        "providerData": {}
+      },
+      {
+        "provider": "feishu",
+        "placement": "local",
+        "routeId": "route-2",
+        "accountId": "app-1",
+        "conversationId": "chat-2",
+        "audience": "shared",
+        "tenantId": "tenant-1",
+        "scopeId": "scope-2",
+        "boundByUserId": "mhome-user-1",
+        "displayName": "Project room",
+        "enabled": true,
+        "projections": {
+          "notification": {
+            "enabled": false,
+            "levels": []
+          },
+          "dialog": {
+            "enabled": false
+          }
+        },
+        "providerData": {}
+      }
+    ]
+  }
+}

package/fixtures/route-update.request.json

@@ -0,0 +1,21 @@
+{
+  "target": "/app/messaging/route/update",
+  "direction": "request",
+  "body": {
+    "audience": "personal",
+    "provider": "telegram",
+    "placement": "cloud",
+    "routeId": "route-1",
+    "scopeId": "scope-1",
+    "enabled": false,
+    "projections": {
+      "notification": {
+        "enabled": true,
+        "levels": ["alert", "notify"]
+      },
+      "dialog": {
+        "enabled": true
+      }
+    }
+  }
+}

package/fixtures/route-update.response.json

@@ -0,0 +1,29 @@
+{
+  "target": "/app/messaging/route/update",
+  "direction": "response",
+  "body": {
+    "route": {
+      "provider": "telegram",
+      "placement": "cloud",
+      "routeId": "route-1",
+      "accountId": "official-bot",
+      "conversationId": "chat-1",
+      "audience": "personal",
+      "externalActorId": "user-1",
+      "tenantId": "tenant-1",
+      "userId": "mhome-user-1",
+      "scopeId": "scope-1",
+      "enabled": false,
+      "projections": {
+        "notification": {
+          "enabled": true,
+          "levels": ["alert", "notify"]
+        },
+        "dialog": {
+          "enabled": true
+        }
+      },
+      "providerData": {}
+    }
+  }
+}

package/fixtures/setup-options.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/setup/options",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local" }
+}

package/fixtures/setup-options.response.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/setup/options",
+  "direction": "response",
+  "body": { "options": { "tokenRequired": true } }
+}

package/fixtures/setup-start.request.json

@@ -0,0 +1,9 @@
+{
+  "target": "/app/messaging/setup/start",
+  "direction": "request",
+  "body": {
+    "provider": "telegram",
+    "placement": "local",
+    "data": { "botToken": "secret" }
+  }
+}

package/fixtures/setup-start.response.json

@@ -0,0 +1,12 @@
+{
+  "target": "/app/messaging/setup/start",
+  "direction": "response",
+  "body": {
+    "setup": {
+      "setupId": "setup-1",
+      "status": "action_required",
+      "expiresAtMs": 1893456000000,
+      "providerData": { "pairingCode": "ABCD" }
+    }
+  }
+}

package/fixtures/setup-status.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/setup/status",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local", "setupId": "setup-1" }
+}

package/fixtures/setup-status.response.json

@@ -0,0 +1,14 @@
+{
+  "target": "/app/messaging/setup/status",
+  "direction": "response",
+  "body": {
+    "setup": {
+      "setupId": "setup-1",
+      "status": "complete",
+      "providerData": {},
+      "accountId": "official-bot",
+      "routeId": "route-1",
+      "message": "Connected"
+    }
+  }
+}

package/fixtures/shared-account-grant-create.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/shared-account-grant/create",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local", "accountId": "123456" }
+}

package/fixtures/shared-account-grant-create.response.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/shared-account-grant/create",
+  "direction": "response",
+  "body": { "success": true }
+}

package/fixtures/shared-account-grant-delete.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/shared-account-grant/delete",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local", "accountId": "123456" }
+}

package/fixtures/shared-account-grant-delete.response.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/shared-account-grant/delete",
+  "direction": "response",
+  "body": { "success": true }
+}

package/fixtures/shared-account-grant-list.request.json

@@ -0,0 +1,5 @@
+{
+  "target": "/app/messaging/shared-account-grant/list",
+  "direction": "request",
+  "body": { "provider": "telegram", "placement": "local", "accountId": "123456" }
+}

package/fixtures/shared-account-grant-list.response.json

@@ -0,0 +1,9 @@
+{
+  "target": "/app/messaging/shared-account-grant/list",
+  "direction": "response",
+  "body": {
+    "grants": [
+      { "provider": "telegram", "placement": "local", "accountId": "123456", "tenantId": "tenant-1", "scopeId": "scope-1", "grantedByUserId": "user-1", "createdAtMs": 1787961600000, "updatedAtMs": 1787961600000 }
+    ]
+  }
+}

package/fixtures/surface-bind-code-create.request.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/surface/bind-code/create","direction":"request","body":{"provider":"feishu","placement":"local","surfaceId":"cs1:mg:feishu:Y2xpX2E:Y2hhdF9h","scopeId":"scope_a"}}

package/fixtures/surface-bind-code-create.response.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/surface/bind-code/create","direction":"response","body":{"challenge":{"code":"M7K9Q2","command":"/bind M7K9Q2","expiresAtMs":1720000300000}}}

package/fixtures/surface-dismiss.request.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/surface/dismiss","direction":"request","body":{"provider":"feishu","placement":"local","surfaceId":"cs1:mg:feishu:Y2xpX2E:Y2hhdF9h"}}

package/fixtures/surface-dismiss.response.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/surface/dismiss","direction":"response","body":{"success":true}}

package/fixtures/surface-list.request.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/surface/list","direction":"request","body":{"provider":"feishu","placement":"local","state":"pending"}}

package/fixtures/surface-list.response.json

@@ -0,0 +1 @@
+{"target":"/app/messaging/surface/list","direction":"response","body":{"surfaces":[{"provider":"feishu","placement":"local","accountId":"cli_a","surfaceId":"cs1:mg:feishu:Y2xpX2E:Y2hhdF9h","displayName":"Project room","state":"pending","firstSeenAtMs":1720000000000,"lastSeenAtMs":1720000001000}]}}

package/manifest/app-facade.v1.json

@@ -0,0 +1,32 @@
+{
+  "manifest": "mhome.app-facade.v1",
+  "contractVersion": "1.0.0",
+  "callSchema": "schema/facade-call.v1.schema.json",
+  "domains": {
+    "messaging": {
+      "targets": "manifest/targets.v1.json"
+    },
+    "plugin": {
+      "extensionVersion": "v1",
+      "targetPrefix": "/app/plugin",
+      "exactRequestTargets": [
+        "/app/plugin/installed/list",
+        "/app/plugin/detail/get",
+        "/app/plugin/candidate/list",
+        "/app/plugin/add/start",
+        "/app/plugin/add/status",
+        "/app/plugin/add/cancel",
+        "/app/plugin/remove",
+        "/app/plugin/profile/update"
+      ],
+      "eventTargets": ["/app/plugin/settings/changed"],
+      "extensionFamily": "/app/plugin/{nodeType}/{route...}",
+      "extensionPriority": "after_exact"
+    },
+    "runtime": {
+      "requestTargets": ["/app/runtime/status/list"],
+      "eventTargets": ["/app/runtime/status/changed"],
+      "authority": "host"
+    }
+  }
+}

package/manifest/targets.v1.json

@@ -0,0 +1,57 @@
+{
+  "manifest": "mhome.messaging.targets.v1",
+  "contractVersion": "1.0.0",
+  "requestTargets": [
+    "/app/messaging/provider/list",
+    "/app/messaging/provider-account/list",
+    "/app/messaging/provider-account/update",
+    "/app/messaging/provider-account/delete",
+    "/app/messaging/provider-account/test",
+    "/app/messaging/provider-account/status",
+    "/app/messaging/shared-account-grant/create",
+    "/app/messaging/shared-account-grant/delete",
+    "/app/messaging/shared-account-grant/list",
+    "/app/messaging/route/list",
+    "/app/messaging/route/update",
+    "/app/messaging/route/delete",
+    "/app/messaging/setup/options",
+    "/app/messaging/setup/start",
+    "/app/messaging/setup/status",
+    "/app/messaging/surface/list",
+    "/app/messaging/surface/dismiss",
+    "/app/messaging/surface/bind-code/create",
+    "/app/messaging/actor/link-code/create",
+    "/app/messaging/actor/link-claim/status",
+    "/app/messaging/actor/link-claim/confirm",
+    "/app/messaging/actor/link/list",
+    "/app/messaging/actor/link/delete"
+  ],
+  "responseTargets": [
+    "/app/messaging/provider/list",
+    "/app/messaging/provider-account/list",
+    "/app/messaging/provider-account/update",
+    "/app/messaging/provider-account/delete",
+    "/app/messaging/provider-account/test",
+    "/app/messaging/provider-account/status",
+    "/app/messaging/shared-account-grant/create",
+    "/app/messaging/shared-account-grant/delete",
+    "/app/messaging/shared-account-grant/list",
+    "/app/messaging/route/list",
+    "/app/messaging/route/update",
+    "/app/messaging/route/delete",
+    "/app/messaging/setup/options",
+    "/app/messaging/setup/start",
+    "/app/messaging/setup/status",
+    "/app/messaging/surface/list",
+    "/app/messaging/surface/dismiss",
+    "/app/messaging/surface/bind-code/create",
+    "/app/messaging/actor/link-code/create",
+    "/app/messaging/actor/link-claim/status",
+    "/app/messaging/actor/link-claim/confirm",
+    "/app/messaging/actor/link/list",
+    "/app/messaging/actor/link/delete"
+  ],
+  "eventTargets": [
+    "/app/messaging/actor/link-claim/changed"
+  ]
+}