@mhome/app-facade-protocol 1.111.0 → 1.112.1

package/contract/billing-v1.md

@@ -1,6 +1,6 @@
-# Billing reads v1
+# Billing v1
 
-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.
+All three read 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.
 
 | Target | Input | Business output |
 | --- | --- | --- |
@@ -10,4 +10,42 @@ All three App Facades run in the cloud under UserRead, using the authenticated u
 
 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.
 
+## Account units and plan codes
+
+`totalBalance` is the period's credit allowance, not the remaining balance. The
+remaining credits are `totalBalance - usedAutomation - usedChat - usedIntegration`.
+These four summary fields and daily `rows[].credits` are raw account credit units:
+**100 credits = 1 product token displayed by the App**. For example, `100000`
+credits is 1000 product tokens; 100 used credits is 1 used product token. These
+product tokens are not an LLM's input/output tokens. Keep the wire values intact;
+convert only when explaining the product-token amounts to a user.
+
+The current tier codes are `E` (Internal), `T` (shown as Free), `V0` (Free), `V1`
+(Go), and `V2` (Plus). `currentTier` describes the current plan; `refreshTier`
+describes the plan at the next refresh. Either field and
+`stripeSubscriptionStatus` can be null; null means unavailable/absent, not a
+confirmed Free plan or active subscription. `nextRefreshTimestamp` is Unix
+milliseconds. Product names such as `plus` are not tier codes.
+
+Payment `amount` uses Stripe invoice/refund minor units for the returned
+`currency`, independently of account credits. Preserve the refund sign. Follow
+[Stripe's currency rules](https://docs.stripe.com/currencies), including zero-
+decimal currencies and the ISK/UGX two-decimal API exceptions; do not assume USD
+or divide all amounts by 100.
+
 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`.
+
+## Subscription commands
+
+These cloud-only UserWrite Facades use the authenticated user's account without an active Space. Input cannot select another user. The current UI exposes these commands on Web/desktop, with confirmation before submission; native mobile keeps its existing hidden purchase controls. Agent/MCP tool catalogs and delegated execution do not expose these commands.
+
+| Target | Input | Business output |
+| --- | --- | --- |
+| `/app/billing/subscription/checkout/create` | `{productId}` | `{url}` for navigation to Stripe Checkout |
+| `/app/billing/subscription/cancel` | `{}` | Subscription state; cancellation takes effect at period end |
+| `/app/billing/subscription/resume` | `{}` | Subscription state; automatic renewal restored |
+| `/app/billing/subscription/change` | `{productId}` | Subscription state; upgrades start immediately, downgrades start next period, choosing the current tier removes a pending change |
+
+Product IDs retain the existing case-insensitive `go`/`plus` and legacy `pro`/`max` aliases. Subscription output contains `currentTier`, `cancelAtPeriodEnd`, `currentPeriodEndTimestamp`, `scheduledTier` and `scheduledTierStartTimestamp`; timestamps are Unix milliseconds. The standard Facade envelope carries success/failure, without a second business `success` flag. Full and Essential project the same command result without additional reads.
+
+The UI does not automatically replay writes on reconnect or timeout. Checkout keeps its persistent attempt, frozen parameters, Stripe idempotency key and recoverable session URL. Once accepted, Checkout continues after caller disconnect; a lost response does not prove payment creation failed. Existing subscription management, proration and reconciliation stay owned by the Stripe manager. Stripe SDK calls, hosted Checkout navigation and signed `POST /webhook/stripe` delivery remain HTTP(S); the retired `/api/v1/payment/stripe/*` user command controllers are not webhook endpoints.

package/fixtures/billing.conformance.json

@@ -1,13 +1,13 @@
 {
   "summary": {
     "userId": "fictional-user",
-    "currentTier": "plus",
-    "refreshTier": "plus",
+    "currentTier": "V2",
+    "refreshTier": "V2",
     "stripeSubscriptionStatus": "active",
-    "totalBalance": 1000,
-    "usedAutomation": 10,
-    "usedChat": 20,
-    "usedIntegration": 30,
+    "totalBalance": 300000,
+    "usedAutomation": 100,
+    "usedChat": 200,
+    "usedIntegration": 300,
     "nextRefreshTimestamp": 1796083200000
   },
   "payments": {
@@ -69,5 +69,61 @@
         "fromDate": 42
       }
     ]
+  },
+  "productInput": {
+    "valid": [
+      {
+        "productId": "go"
+      },
+      {
+        "productId": "plus"
+      },
+      {
+        "productId": "pro"
+      },
+      {
+        "productId": "max"
+      },
+      {
+        "productId": "Go"
+      },
+      {
+        "productId": "PLUS"
+      }
+    ],
+    "invalid": [
+      {},
+      null,
+      {
+        "productId": null
+      },
+      {
+        "productId": 42
+      },
+      {
+        "productId": ""
+      },
+      {
+        "productId": "free"
+      },
+      {
+        "productId": "go",
+        "userId": "other"
+      },
+      {
+        "productId": "go",
+        "scopeId": "home"
+      }
+    ]
+  },
+  "checkout": {
+    "url": "https://checkout.stripe.com/c/pay/cs_test_fictional"
+  },
+  "subscription": {
+    "currentTier": "V2",
+    "cancelAtPeriodEnd": false,
+    "currentPeriodEndTimestamp": 1796083200000,
+    "scheduledTier": "V1",
+    "scheduledTierStartTimestamp": 1796083200000
   }
 }

package/fixtures/routing/cases.json

@@ -990,5 +990,133 @@
     "hubReady": false,
     "cloudReady": false,
     "entry": "unavailable"
+  },
+  {
+    "target": "/app/billing/subscription/checkout/create",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/billing/subscription/checkout/create",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": false,
+    "entry": "unavailable"
+  },
+  {
+    "target": "/app/billing/subscription/checkout/create",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/billing/subscription/checkout/create",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": false,
+    "entry": "unavailable"
+  },
+  {
+    "target": "/app/billing/subscription/cancel",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/billing/subscription/cancel",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": false,
+    "entry": "unavailable"
+  },
+  {
+    "target": "/app/billing/subscription/cancel",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/billing/subscription/cancel",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": false,
+    "entry": "unavailable"
+  },
+  {
+    "target": "/app/billing/subscription/resume",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/billing/subscription/resume",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": false,
+    "entry": "unavailable"
+  },
+  {
+    "target": "/app/billing/subscription/resume",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/billing/subscription/resume",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": false,
+    "entry": "unavailable"
+  },
+  {
+    "target": "/app/billing/subscription/change",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/billing/subscription/change",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": true,
+    "cloudReady": false,
+    "entry": "unavailable"
+  },
+  {
+    "target": "/app/billing/subscription/change",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": true,
+    "entry": "cloud"
+  },
+  {
+    "target": "/app/billing/subscription/change",
+    "execution": "cloud",
+    "placement": null,
+    "hubReady": false,
+    "cloudReady": false,
+    "entry": "unavailable"
   }
 ]

package/manifest/app-facade.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.app-facade.v1",
-  "contractVersion": "1.111.0",
+  "contractVersion": "1.112.1",
   "callSchema": "schema/facade-call.v1.schema.json",
   "routing": "manifest/routing.v1.json",
   "routingSchema": "schema/routing.v1.schema.json",
@@ -406,7 +406,11 @@
       "requestTargets": [
         "/app/billing/summary/get",
         "/app/billing/payment/list",
-        "/app/billing/credit/usage"
+        "/app/billing/credit/usage",
+        "/app/billing/subscription/checkout/create",
+        "/app/billing/subscription/cancel",
+        "/app/billing/subscription/resume",
+        "/app/billing/subscription/change"
       ]
     }
   },

package/manifest/authorization.v1.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.111.0",
+  "contractVersion": "1.112.1",
   "operations": {
     "/app/agent/context/get": "spaceRead",
     "/app/agent/credit/usage": "spaceRead",
@@ -355,7 +355,11 @@
     "/pod/talk/request/get": "spaceRead",
     "/pod/talk/speech/prepare": "spaceWrite",
     "/pod/talk/turn/submit": "spaceWrite",
-    "/pod/talk/view/get": "spaceRead"
+    "/pod/talk/view/get": "spaceRead",
+    "/app/billing/subscription/checkout/create": "userWrite",
+    "/app/billing/subscription/cancel": "userWrite",
+    "/app/billing/subscription/resume": "userWrite",
+    "/app/billing/subscription/change": "userWrite"
   },
   "nodePrefix": "/app/plugin/",
   "serviceOperations": [

package/manifest/host-provision-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.host-provision.targets.v1",
-  "contractVersion": "1.111.0",
+  "contractVersion": "1.112.1",
   "contract": "contract/host-provisioning-v1.md",
   "localTargets": [
     "/local/host/provision/start",

package/manifest/hub-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.hub.targets.v1",
-  "contractVersion": "1.111.0",
+  "contractVersion": "1.112.1",
   "appTargets": [
     "/app/hub/get",
     "/app/hub/remove",

package/manifest/pod-targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.pod.targets.v1",
-  "contractVersion": "1.111.0",
+  "contractVersion": "1.112.1",
   "contract": "contract/pod-commissioning-v1.md",
   "localTargets": [
     "/local/pod/discovery/start",

package/manifest/routing.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.app-facade.routing.v1",
-  "contractVersion": "1.111.0",
+  "contractVersion": "1.112.1",
   "targetPrefix": "/app/",
   "default": {
     "execution": "scopeMode"
@@ -41,7 +41,11 @@
       "/app/nfc/sources/list",
       "/app/billing/summary/get",
       "/app/billing/payment/list",
-      "/app/billing/credit/usage"
+      "/app/billing/credit/usage",
+      "/app/billing/subscription/checkout/create",
+      "/app/billing/subscription/cancel",
+      "/app/billing/subscription/resume",
+      "/app/billing/subscription/change"
     ],
     "scopeModeTargets": [
       "/app/artifact/resolve",

package/manifest/targets.v1.json

@@ -1,6 +1,6 @@
 {
   "manifest": "mhome.messaging.targets.v1",
-  "contractVersion": "1.111.0",
+  "contractVersion": "1.112.1",
   "requestTargets": [
     "/app/messaging/provider/list",
     "/app/messaging/provider-account/list",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mhome/app-facade-protocol",
-  "version": "1.111.0",
+  "version": "1.112.1",
   "description": "Build-time protocol artifacts for mhome.app-facade",
   "license": "MIT",
   "repository": {

package/protocol.json

@@ -1,6 +1,6 @@
 {
   "protocol": "mhome.app-facade",
-  "contractVersion": "1.111.0",
+  "contractVersion": "1.112.1",
   "manifest": "manifest/app-facade.v1.json",
   "schemas": {
     "storage": "schema/storage.v1.schema.json",

package/schema/billing.v1.schema.json

@@ -170,6 +170,66 @@
         "trackedFrom",
         "rows"
       ]
+    },
+    "productInput": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "productId": {
+          "type": "string",
+          "pattern": "^([gG][oO]|[pP][rR][oO]|[pP][lL][uU][sS]|[mM][aA][xX])$"
+        }
+      },
+      "required": [
+        "productId"
+      ]
+    },
+    "checkout": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "url": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "url"
+      ]
+    },
+    "subscription": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "currentTier": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "cancelAtPeriodEnd": {
+          "type": "boolean"
+        },
+        "currentPeriodEndTimestamp": {
+          "type": "integer"
+        },
+        "scheduledTier": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "scheduledTierStartTimestamp": {
+          "type": "integer"
+        }
+      },
+      "required": [
+        "currentTier",
+        "cancelAtPeriodEnd",
+        "currentPeriodEndTimestamp",
+        "scheduledTier",
+        "scheduledTierStartTimestamp"
+      ]
     }
   }
 }