@mhome/app-facade-protocol 1.109.2 → 1.111.0

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.
@@ -0,0 +1,13 @@
1
+ # Billing reads v1
2
+
3
+ All three App Facades run in the cloud under UserRead, using the authenticated user's identity. They accept no userId, tenantId or Space selector. A Space/background principal cannot read an owner's private account. These reads do not require an active Space.
4
+
5
+ | Target | Input | Business output |
6
+ | --- | --- | --- |
7
+ | `/app/billing/summary/get` | `{}` | Current plan, subscription status, balance and used credits (`Summary`) |
8
+ | `/app/billing/payment/list` | `{}` | `{payments}` ordered newest first; signed currency minor units and Unix milliseconds |
9
+ | `/app/billing/credit/usage` | `{fromDate?,toDate?}` | Personal payer's UTC daily credits by source, including tracking coverage |
10
+
11
+ Summary retains the existing consistent plan/balance read; it does not query payments or daily history. Payment list retains successful invoices and refunds. Daily usage defaults to the 30 days ending today in UTC, permits ordered ranges of at most 366 inclusive days, and clamps the start to tracking availability. Errors are not replaced with zero usage. The existing `/app/agent/credit/usage` is Space-wide and remains distinct.
12
+
13
+ Full returns the business DTO. Essential encodes the same DTO as YAML without extra reads. UI, Agent, MCP and CLI use these same targets and identity rules. Schemas and fictional examples are in `schema/billing.v1.schema.json` and `fixtures/billing.conformance.json`.
@@ -0,0 +1,73 @@
1
+ {
2
+ "summary": {
3
+ "userId": "fictional-user",
4
+ "currentTier": "plus",
5
+ "refreshTier": "plus",
6
+ "stripeSubscriptionStatus": "active",
7
+ "totalBalance": 1000,
8
+ "usedAutomation": 10,
9
+ "usedChat": 20,
10
+ "usedIntegration": 30,
11
+ "nextRefreshTimestamp": 1796083200000
12
+ },
13
+ "payments": {
14
+ "payments": [
15
+ {
16
+ "description": "Fictional refund",
17
+ "amount": -500,
18
+ "currency": "usd",
19
+ "timestamp": 1794009600000
20
+ }
21
+ ]
22
+ },
23
+ "creditUsage": {
24
+ "audience": "personal",
25
+ "timezone": "UTC",
26
+ "fromDate": "2026-11-01",
27
+ "toDate": "2026-11-07",
28
+ "trackedFrom": "2026-11-01T00:00:00Z",
29
+ "rows": [
30
+ {
31
+ "date": "2026-11-07",
32
+ "source": "agent",
33
+ "credits": 20
34
+ }
35
+ ]
36
+ },
37
+ "emptyInput": {
38
+ "valid": [
39
+ {}
40
+ ],
41
+ "invalid": [
42
+ {
43
+ "userId": "other"
44
+ },
45
+ {
46
+ "spaceId": "home"
47
+ },
48
+ {
49
+ "fromDate": "2026-11-01"
50
+ }
51
+ ]
52
+ },
53
+ "usageInput": {
54
+ "valid": [
55
+ {},
56
+ {
57
+ "fromDate": "2026-11-01",
58
+ "toDate": "2026-11-07"
59
+ }
60
+ ],
61
+ "invalid": [
62
+ {
63
+ "userId": "other"
64
+ },
65
+ {
66
+ "scopeId": "home"
67
+ },
68
+ {
69
+ "fromDate": 42
70
+ }
71
+ ]
72
+ }
73
+ }
@@ -894,5 +894,101 @@
894
894
  "hubReady": false,
895
895
  "cloudReady": false,
896
896
  "entry": "unavailable"
897
+ },
898
+ {
899
+ "target": "/app/billing/summary/get",
900
+ "execution": "cloud",
901
+ "placement": null,
902
+ "hubReady": true,
903
+ "cloudReady": true,
904
+ "entry": "cloud"
905
+ },
906
+ {
907
+ "target": "/app/billing/summary/get",
908
+ "execution": "cloud",
909
+ "placement": null,
910
+ "hubReady": true,
911
+ "cloudReady": false,
912
+ "entry": "unavailable"
913
+ },
914
+ {
915
+ "target": "/app/billing/summary/get",
916
+ "execution": "cloud",
917
+ "placement": null,
918
+ "hubReady": false,
919
+ "cloudReady": true,
920
+ "entry": "cloud"
921
+ },
922
+ {
923
+ "target": "/app/billing/summary/get",
924
+ "execution": "cloud",
925
+ "placement": null,
926
+ "hubReady": false,
927
+ "cloudReady": false,
928
+ "entry": "unavailable"
929
+ },
930
+ {
931
+ "target": "/app/billing/payment/list",
932
+ "execution": "cloud",
933
+ "placement": null,
934
+ "hubReady": true,
935
+ "cloudReady": true,
936
+ "entry": "cloud"
937
+ },
938
+ {
939
+ "target": "/app/billing/payment/list",
940
+ "execution": "cloud",
941
+ "placement": null,
942
+ "hubReady": true,
943
+ "cloudReady": false,
944
+ "entry": "unavailable"
945
+ },
946
+ {
947
+ "target": "/app/billing/payment/list",
948
+ "execution": "cloud",
949
+ "placement": null,
950
+ "hubReady": false,
951
+ "cloudReady": true,
952
+ "entry": "cloud"
953
+ },
954
+ {
955
+ "target": "/app/billing/payment/list",
956
+ "execution": "cloud",
957
+ "placement": null,
958
+ "hubReady": false,
959
+ "cloudReady": false,
960
+ "entry": "unavailable"
961
+ },
962
+ {
963
+ "target": "/app/billing/credit/usage",
964
+ "execution": "cloud",
965
+ "placement": null,
966
+ "hubReady": true,
967
+ "cloudReady": true,
968
+ "entry": "cloud"
969
+ },
970
+ {
971
+ "target": "/app/billing/credit/usage",
972
+ "execution": "cloud",
973
+ "placement": null,
974
+ "hubReady": true,
975
+ "cloudReady": false,
976
+ "entry": "unavailable"
977
+ },
978
+ {
979
+ "target": "/app/billing/credit/usage",
980
+ "execution": "cloud",
981
+ "placement": null,
982
+ "hubReady": false,
983
+ "cloudReady": true,
984
+ "entry": "cloud"
985
+ },
986
+ {
987
+ "target": "/app/billing/credit/usage",
988
+ "execution": "cloud",
989
+ "placement": null,
990
+ "hubReady": false,
991
+ "cloudReady": false,
992
+ "entry": "unavailable"
897
993
  }
898
994
  ]
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "manifest": "mhome.app-facade.v1",
3
- "contractVersion": "1.109.2",
3
+ "contractVersion": "1.111.0",
4
4
  "callSchema": "schema/facade-call.v1.schema.json",
5
5
  "routing": "manifest/routing.v1.json",
6
6
  "routingSchema": "schema/routing.v1.schema.json",
@@ -399,6 +399,15 @@
399
399
  "/app/widget/button/trigger",
400
400
  "/app/widget/delete"
401
401
  ]
402
+ },
403
+ "billing": {
404
+ "contract": "contract/billing-v1.md",
405
+ "schema": "schema/billing.v1.schema.json",
406
+ "requestTargets": [
407
+ "/app/billing/summary/get",
408
+ "/app/billing/payment/list",
409
+ "/app/billing/credit/usage"
410
+ ]
402
411
  }
403
412
  },
404
413
  "authorization": "manifest/authorization.v1.json",
@@ -1,5 +1,5 @@
1
1
  {
2
- "contractVersion": "1.109.2",
2
+ "contractVersion": "1.111.0",
3
3
  "operations": {
4
4
  "/app/agent/context/get": "spaceRead",
5
5
  "/app/agent/credit/usage": "spaceRead",
@@ -46,6 +46,9 @@
46
46
  "/app/automation/status": "spaceRead",
47
47
  "/app/automation/stop": "spaceWrite",
48
48
  "/app/automation/verify": "spaceWrite",
49
+ "/app/billing/credit/usage": "userRead",
50
+ "/app/billing/payment/list": "userRead",
51
+ "/app/billing/summary/get": "userRead",
49
52
  "/app/capability/invoke": "spaceWrite",
50
53
  "/app/capability/invoke/json": "spaceWrite",
51
54
  "/app/client/appearance/report": "spaceRead",
@@ -88,7 +91,6 @@
88
91
  "/app/entity/detail/get": "spaceRead",
89
92
  "/app/entity/history/list": "spaceRead",
90
93
  "/app/entity/list": "spaceRead",
91
- "/app/presentation/entity/get": "spaceRead",
92
94
  "/app/graph/relations/get": "spaceRead",
93
95
  "/app/group/create": "spaceWrite",
94
96
  "/app/group/delete": "spaceWrite",
@@ -115,8 +117,6 @@
115
117
  "/app/hub/remove": "spaceManage",
116
118
  "/app/hub/restart": "spaceManage",
117
119
  "/app/hub/status": "spaceRead",
118
- "/app/inspire/search": "spaceRead",
119
- "/app/inspire/verify": "spaceWrite",
120
120
  "/app/integration/capability/detail/get": "spaceRead",
121
121
  "/app/integration/connect": "spaceWrite",
122
122
  "/app/integration/detail/batch": "spaceRead",
@@ -129,7 +129,6 @@
129
129
  "/app/integration/installed/list": "spaceRead",
130
130
  "/app/integration/list": "spaceRead",
131
131
  "/app/integration/official/list": "spaceRead",
132
- "/app/presentation/integration/get": "spaceRead",
133
132
  "/app/integration/preview/apply": "spaceWrite",
134
133
  "/app/integration/preview/status": "spaceRead",
135
134
  "/app/integration/scope/list": "spaceRead",
@@ -230,6 +229,9 @@
230
229
  "/app/presentation/automation/placements/get": "spaceRead",
231
230
  "/app/presentation/automation/share": "spaceWrite",
232
231
  "/app/presentation/automation/summaries/get": "spaceRead",
232
+ "/app/presentation/entity/get": "spaceRead",
233
+ "/app/presentation/entity/meta/get": "spaceRead",
234
+ "/app/presentation/integration/get": "spaceRead",
233
235
  "/app/presentation/reference/item/list": "spaceRead",
234
236
  "/app/presentation/reference/type/list": "spaceRead",
235
237
  "/app/presentation/space/get": "spaceRead",
@@ -324,20 +326,13 @@
324
326
  "/chat/thread/load": "spaceRead",
325
327
  "/chat/thread/rotate": "spaceWrite",
326
328
  "/chat/turn/submit": "spaceWrite",
327
- "/core/restart": "spaceManage",
328
329
  "/identity/node/instance/list": "spaceManage",
329
330
  "/identity/node/issue": "spaceManage",
330
331
  "/identity/node/list": "spaceManage",
331
332
  "/identity/node/onboarding/start": "spaceManage",
332
333
  "/identity/node/revoke": "spaceManage",
333
334
  "/integration/composite/refresh": "spaceWrite",
334
- "/integration/disconnect": "spaceWrite",
335
- "/integration/entity/getHistory": "spaceRead",
336
- "/integration/install": "spaceWrite",
337
- "/integration/model/get": "spaceRead",
338
335
  "/integration/providerEnv/refresh": "spaceWrite",
339
- "/integration/uninstall": "spaceWrite",
340
- "/kg/entityAutomationRelation/get": "spaceRead",
341
336
  "/llm/asr/transcribe": "spaceWrite",
342
337
  "/llm/capabilities": "spaceRead",
343
338
  "/llm/decision/decide": "spaceWrite",
@@ -360,26 +355,7 @@
360
355
  "/pod/talk/request/get": "spaceRead",
361
356
  "/pod/talk/speech/prepare": "spaceWrite",
362
357
  "/pod/talk/turn/submit": "spaceWrite",
363
- "/pod/talk/view/get": "spaceRead",
364
- "/schedule/list": "spaceRead",
365
- "/twin/batchDisable": "spaceWrite",
366
- "/twin/batchGetLatest": "spaceRead",
367
- "/twin/batchUpsert": "spaceWrite",
368
- "/twin/getHistory": "spaceRead",
369
- "/ui/canvas/delete": "spaceWrite",
370
- "/ui/canvas/getContent": "spaceRead",
371
- "/ui/canvas/list": "spaceRead",
372
- "/ui/canvas/reorder": "spaceWrite",
373
- "/ui/canvas/save": "spaceWrite",
374
- "/ui/card/batchDelete": "spaceWrite",
375
- "/ui/card/batchMove": "spaceWrite",
376
- "/ui/card/copy": "spaceWrite",
377
- "/ui/card/delete": "spaceWrite",
378
- "/ui/card/layout/organize": "spaceWrite",
379
- "/ui/card/layout/update": "spaceWrite",
380
- "/ui/card/move": "spaceWrite",
381
- "/ui/card/update": "spaceWrite",
382
- "/app/presentation/entity/meta/get": "spaceRead"
358
+ "/pod/talk/view/get": "spaceRead"
383
359
  },
384
360
  "nodePrefix": "/app/plugin/",
385
361
  "serviceOperations": [
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "manifest": "mhome.host-provision.targets.v1",
3
- "contractVersion": "1.109.2",
3
+ "contractVersion": "1.111.0",
4
4
  "contract": "contract/host-provisioning-v1.md",
5
5
  "localTargets": [
6
6
  "/local/host/provision/start",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "manifest": "mhome.hub.targets.v1",
3
- "contractVersion": "1.109.2",
3
+ "contractVersion": "1.111.0",
4
4
  "appTargets": [
5
5
  "/app/hub/get",
6
6
  "/app/hub/remove",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "manifest": "mhome.pod.targets.v1",
3
- "contractVersion": "1.109.2",
3
+ "contractVersion": "1.111.0",
4
4
  "contract": "contract/pod-commissioning-v1.md",
5
5
  "localTargets": [
6
6
  "/local/pod/discovery/start",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "manifest": "mhome.app-facade.routing.v1",
3
- "contractVersion": "1.109.2",
3
+ "contractVersion": "1.111.0",
4
4
  "targetPrefix": "/app/",
5
5
  "default": {
6
6
  "execution": "scopeMode"
@@ -10,7 +10,6 @@
10
10
  "rules": {
11
11
  "cloudPrefixes": [
12
12
  "/app/space/",
13
- "/app/inspire/",
14
13
  "/app/user/",
15
14
  "/app/ui/customize/cards/catalog/"
16
15
  ],
@@ -39,7 +38,10 @@
39
38
  "/app/presentation/space/list",
40
39
  "/app/presentation/space/get",
41
40
  "/app/resource/transfer/prepare",
42
- "/app/nfc/sources/list"
41
+ "/app/nfc/sources/list",
42
+ "/app/billing/summary/get",
43
+ "/app/billing/payment/list",
44
+ "/app/billing/credit/usage"
43
45
  ],
44
46
  "scopeModeTargets": [
45
47
  "/app/artifact/resolve",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "manifest": "mhome.messaging.targets.v1",
3
- "contractVersion": "1.109.2",
3
+ "contractVersion": "1.111.0",
4
4
  "requestTargets": [
5
5
  "/app/messaging/provider/list",
6
6
  "/app/messaging/provider-account/list",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mhome/app-facade-protocol",
3
- "version": "1.109.2",
3
+ "version": "1.111.0",
4
4
  "description": "Build-time protocol artifacts for mhome.app-facade",
5
5
  "license": "MIT",
6
6
  "repository": {
package/protocol.json CHANGED
@@ -1,10 +1,11 @@
1
1
  {
2
2
  "protocol": "mhome.app-facade",
3
- "contractVersion": "1.109.2",
3
+ "contractVersion": "1.111.0",
4
4
  "manifest": "manifest/app-facade.v1.json",
5
5
  "schemas": {
6
6
  "storage": "schema/storage.v1.schema.json",
7
7
  "nowAttention": "schema/now-attention.v1.schema.json",
8
+ "billing": "schema/billing.v1.schema.json",
8
9
  "pluginInstall": "schema/plugin-install.v1.schema.json",
9
10
  "hostAuthorization": "schema/host-authorization.v1.schema.json",
10
11
  "hostAccess": "schema/host-access.v1.schema.json",
@@ -35,6 +36,7 @@
35
36
  "fixtures": {
36
37
  "attention": "fixtures/attention/conformance.json",
37
38
  "agentLlm": "fixtures/agent-llm.conformance.json",
39
+ "billing": "fixtures/billing.conformance.json",
38
40
  "entityPresentation": "fixtures/entity-presentation.conformance.json",
39
41
  "integrationPresentation": "fixtures/integration-presentation.conformance.json",
40
42
  "group": "fixtures/group.conformance.json",
@@ -0,0 +1,175 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "$id": "https://meowlink.app/protocol/billing.v1.schema.json",
4
+ "$defs": {
5
+ "emptyInput": {
6
+ "type": "object",
7
+ "additionalProperties": false,
8
+ "properties": {},
9
+ "required": []
10
+ },
11
+ "usageInput": {
12
+ "type": "object",
13
+ "additionalProperties": false,
14
+ "properties": {
15
+ "fromDate": {
16
+ "type": [
17
+ "string",
18
+ "null"
19
+ ]
20
+ },
21
+ "toDate": {
22
+ "type": [
23
+ "string",
24
+ "null"
25
+ ]
26
+ }
27
+ },
28
+ "required": []
29
+ },
30
+ "summary": {
31
+ "type": "object",
32
+ "additionalProperties": false,
33
+ "properties": {
34
+ "userId": {
35
+ "type": "string"
36
+ },
37
+ "currentTier": {
38
+ "type": [
39
+ "string",
40
+ "null"
41
+ ]
42
+ },
43
+ "refreshTier": {
44
+ "type": [
45
+ "string",
46
+ "null"
47
+ ]
48
+ },
49
+ "stripeSubscriptionStatus": {
50
+ "type": [
51
+ "string",
52
+ "null"
53
+ ]
54
+ },
55
+ "totalBalance": {
56
+ "type": "integer"
57
+ },
58
+ "usedAutomation": {
59
+ "type": "integer"
60
+ },
61
+ "usedChat": {
62
+ "type": "integer"
63
+ },
64
+ "usedIntegration": {
65
+ "type": "integer"
66
+ },
67
+ "nextRefreshTimestamp": {
68
+ "type": "integer"
69
+ }
70
+ },
71
+ "required": [
72
+ "userId",
73
+ "currentTier",
74
+ "refreshTier",
75
+ "stripeSubscriptionStatus",
76
+ "totalBalance",
77
+ "usedAutomation",
78
+ "usedChat",
79
+ "usedIntegration",
80
+ "nextRefreshTimestamp"
81
+ ]
82
+ },
83
+ "payments": {
84
+ "type": "object",
85
+ "additionalProperties": false,
86
+ "properties": {
87
+ "payments": {
88
+ "type": "array",
89
+ "items": {
90
+ "type": "object",
91
+ "additionalProperties": false,
92
+ "properties": {
93
+ "description": {
94
+ "type": [
95
+ "string",
96
+ "null"
97
+ ]
98
+ },
99
+ "amount": {
100
+ "type": "integer"
101
+ },
102
+ "currency": {
103
+ "type": "string"
104
+ },
105
+ "timestamp": {
106
+ "type": "integer"
107
+ }
108
+ },
109
+ "required": [
110
+ "description",
111
+ "amount",
112
+ "currency",
113
+ "timestamp"
114
+ ]
115
+ }
116
+ }
117
+ },
118
+ "required": [
119
+ "payments"
120
+ ]
121
+ },
122
+ "creditUsage": {
123
+ "type": "object",
124
+ "additionalProperties": false,
125
+ "properties": {
126
+ "audience": {
127
+ "type": "string"
128
+ },
129
+ "timezone": {
130
+ "type": "string"
131
+ },
132
+ "fromDate": {
133
+ "type": "string"
134
+ },
135
+ "toDate": {
136
+ "type": "string"
137
+ },
138
+ "trackedFrom": {
139
+ "type": "string"
140
+ },
141
+ "rows": {
142
+ "type": "array",
143
+ "items": {
144
+ "type": "object",
145
+ "additionalProperties": false,
146
+ "properties": {
147
+ "date": {
148
+ "type": "string"
149
+ },
150
+ "source": {
151
+ "type": "string"
152
+ },
153
+ "credits": {
154
+ "type": "integer"
155
+ }
156
+ },
157
+ "required": [
158
+ "date",
159
+ "source",
160
+ "credits"
161
+ ]
162
+ }
163
+ }
164
+ },
165
+ "required": [
166
+ "audience",
167
+ "timezone",
168
+ "fromDate",
169
+ "toDate",
170
+ "trackedFrom",
171
+ "rows"
172
+ ]
173
+ }
174
+ }
175
+ }