@fleetless/contracts 6.0.0 → 6.1.0-next.2

package/artifacts/openapi.json

@@ -9450,6 +9450,121 @@
           }
         }
       }
+    },
+    "/api/org/plan": {
+      "get": {
+        "operationId": "get_api_org_plan",
+        "summary": "Reads the org's plan: its limits, its usage against them, its add-ons and any change already queued.",
+        "tags": [
+          "org"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          }
+        ],
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/org-plan"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "The one read the console's Plan & billing page, its usage and limit gauges, and every upgrade prompt and feature gate draw from — nothing else computes `limits` or `usage` on its own. `limits` is already the effective ceiling, the catalogue row raised by `addons` or replaced by an operator's override, so a consumer never recomputes it from the catalogue. `usage` is counted fresh on every call, never cached. `switch` is present only for an organization still on the beta that has not yet landed on a priced plan."
+      }
+    },
+    "/api/org/plan/change": {
+      "put": {
+        "operationId": "put_api_org_plan_change",
+        "summary": "Moves the org's plan down — a lower plan or a cancellation to Basic — queuing the change rather than applying it at once.",
+        "tags": [
+          "org"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          }
+        ],
+        "parameters": [],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/org-plan"
+                }
+              }
+            }
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `tier_required`, `validation_error`, `plan_limit`, `target_state_conflict`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "Owner tier, and **downward only**: this route moves the org to a lower plan or cancels it outright to Basic. It never moves the org up — until payment exists, an upgrade or an add-on is not this route's job at all, and is handled today as a Feedback request that Fleetless then applies through the admin route. `409 target_state_conflict` names `target_plan` with rule `not_lower` when the chosen plan is not below the org's current one; with rule `locked_basic_only` when the org is locked (`orgLock`) and the chosen plan is anything but Basic; and with rule `migration_basic_only` when the org is still on the beta, awaiting the switch to priced plans, and the chosen plan is anything but Basic — that choice is exactly what the org lands on at the switch. An owner is never named in `keep` and always stays, but still counts against the target plan's `seats`; `409 plan_limit` names `seats` when the owners alone already exceed it, and names whichever other limit `keep` still exceeds otherwise. `keep` is `null` when the org's current usage already fits the target plan outright and nothing is deleted; named, it lists exactly the robots, apps, app users and developers that stay. The choice is stored as `pending_change` and takes effect at `period_ends_at` — **everything of the chosen kind not named in `keep` is deleted at that instant, never before** — except a choice made while the org is locked, which takes effect at once, and a beta org's choice, which takes effect at the switch date instead. Anything created while the choice is pending is checked against the target plan too and, when it passes, is folded into `keep`, so exactly what the confirmation counted is what is actually deleted. A later `PUT` replaces a still-pending choice outright.",
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/plan-change-request"
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "operationId": "delete_api_org_plan_change",
+        "summary": "Withdraws a plan change that was queued but has not taken effect yet.",
+        "tags": [
+          "org"
+        ],
+        "security": [
+          {
+            "developerSession": []
+          }
+        ],
+        "parameters": [],
+        "responses": {
+          "204": {
+            "description": "Success."
+          },
+          "default": {
+            "description": "An error envelope. Codes this route is known to answer: `unauthorized`, `token_expired`, `token_revoked`, `tier_required`, `not_found`.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/api-error"
+                }
+              }
+            }
+          }
+        },
+        "description": "Owner tier. `404 not_found` when the org has no `pending_change` to withdraw. The org stays on its current plan, unchanged, as if the choice had never been made; a developer who wants a different one sends a new `PUT`, which would have replaced this one outright anyway."
+      }
     }
   },
   "components": {
@@ -11390,7 +11505,8 @@
                         "end_user",
                         "app_user",
                         "server_key",
-                        "bridge"
+                        "bridge",
+                        "fleetless"
                       ]
                     },
                     "id": {
@@ -17837,6 +17953,505 @@
         ],
         "additionalProperties": false
       },
+      "org-plan": {
+        "type": "object",
+        "properties": {
+          "plan": {
+            "type": "string",
+            "enum": [
+              "basic",
+              "plus",
+              "pro",
+              "enterprise"
+            ],
+            "description": "The org's current plan."
+          },
+          "currency": {
+            "type": "string",
+            "enum": [
+              "eur",
+              "usd"
+            ],
+            "description": "The currency the org's prices are shown and billed in."
+          },
+          "period_ends_at": {
+            "type": "string",
+            "format": "date-time",
+            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
+            "description": "The end of the organization's current billing period; while no payment period exists yet, the end of the current UTC calendar month. A pending downward plan change normally takes effect at this exact instant — except one chosen while the org was locked, which lands at once, and the platform's own move off the beta, which lands at its switch date instead."
+          },
+          "addons": {
+            "type": "object",
+            "properties": {
+              "seats": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Extra developer seats, one each."
+              },
+              "robots": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Extra robots, one each."
+              },
+              "apps": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Extra apps, one each."
+              },
+              "app_user_packs": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Packs of five extra app users."
+              },
+              "live_video_packs": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Packs of 250 extra hours of app-user live video per month."
+              }
+            },
+            "required": [
+              "seats",
+              "robots",
+              "apps",
+              "app_user_packs",
+              "live_video_packs"
+            ],
+            "additionalProperties": false,
+            "description": "The add-ons the org has bought. All zero on a plan without the `addons` feature."
+          },
+          "limits": {
+            "type": "object",
+            "properties": {
+              "seats": {
+                "anyOf": [
+                  {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Developers, owners included, plus pending team invitations."
+              },
+              "robots": {
+                "anyOf": [
+                  {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Robots in the org."
+              },
+              "apps": {
+                "anyOf": [
+                  {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Apps in the org."
+              },
+              "app_users": {
+                "anyOf": [
+                  {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "App users across every app of the org, plus pending app-user invitations."
+              },
+              "live_video_ms_per_month": {
+                "anyOf": [
+                  {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Live video watched by app users in one UTC calendar month, in milliseconds, across the org. Console sessions do not count."
+              },
+              "asset_bytes_per_robot": {
+                "anyOf": [
+                  {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Asset storage per robot, in bytes (decimal: 1 GB = 1,000,000,000). The org stores up to robots × this value in total."
+              },
+              "history_days": {
+                "anyOf": [
+                  {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Days the org's robot history is kept."
+              },
+              "audit_days": {
+                "anyOf": [
+                  {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "description": "Days the org's audit log is kept."
+              }
+            },
+            "required": [
+              "seats",
+              "robots",
+              "apps",
+              "app_users",
+              "live_video_ms_per_month",
+              "asset_bytes_per_robot",
+              "history_days",
+              "audit_days"
+            ],
+            "additionalProperties": false,
+            "description": "The org's effective limits: the plan's, raised by its add-ons, or an operator's override in their place. `null` means unlimited for a count, and 90 days for `history_days` and `audit_days`."
+          },
+          "features": {
+            "type": "object",
+            "properties": {
+              "app_mcp": {
+                "type": "boolean",
+                "description": "An app's own MCP endpoint, for its app users."
+              },
+              "two_factor": {
+                "type": "boolean",
+                "description": "Two-factor sign-in for developers."
+              },
+              "require_two_factor": {
+                "type": "boolean",
+                "description": "An owner may require two-factor sign-in for every developer of the org."
+              },
+              "app_oidc": {
+                "type": "boolean",
+                "description": "An app may let its users sign in through an OpenID Connect identity provider."
+              },
+              "hosted_logo": {
+                "type": "boolean",
+                "description": "An app's hosted pages show its logo and accent colour, not only its name."
+              },
+              "audit_export": {
+                "type": "boolean",
+                "description": "The audit log can be exported as CSV."
+              },
+              "addons": {
+                "type": "boolean",
+                "description": "Add-ons can be bought on top of the plan."
+              }
+            },
+            "required": [
+              "app_mcp",
+              "two_factor",
+              "require_two_factor",
+              "app_oidc",
+              "hosted_logo",
+              "audit_export",
+              "addons"
+            ],
+            "additionalProperties": false,
+            "description": "What the org's plan unlocks."
+          },
+          "usage": {
+            "type": "object",
+            "properties": {
+              "seats": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Developers, owners included, plus pending team invitations."
+              },
+              "robots": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Robots in the org."
+              },
+              "apps": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Apps in the org."
+              },
+              "app_users": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "App users across every app, plus pending app-user invitations."
+              },
+              "live_video_ms_this_month": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Live video watched by app users in the current UTC calendar month, in milliseconds. Console sessions do not count."
+              },
+              "asset_bytes": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991,
+                "description": "Bytes the assets of every robot of the org occupy, together."
+              }
+            },
+            "required": [
+              "seats",
+              "robots",
+              "apps",
+              "app_users",
+              "live_video_ms_this_month",
+              "asset_bytes"
+            ],
+            "additionalProperties": false,
+            "description": "What the org uses now, counted the way each limit counts it."
+          },
+          "pending_change": {
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "target_plan": {
+                    "type": "string",
+                    "enum": [
+                      "basic",
+                      "plus",
+                      "pro",
+                      "enterprise"
+                    ],
+                    "description": "The plan the org moves to."
+                  },
+                  "reason": {
+                    "type": "string",
+                    "enum": [
+                      "downgrade",
+                      "cancel",
+                      "migration",
+                      "lock"
+                    ],
+                    "description": "Why the change is pending: `downgrade`, `cancel`, `migration` or `lock`."
+                  },
+                  "effective_at": {
+                    "anyOf": [
+                      {
+                        "type": "string",
+                        "format": "date-time",
+                        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "When the change takes effect. `null` only for a move off the beta whose date is not set yet."
+                  },
+                  "keep": {
+                    "anyOf": [
+                      {
+                        "type": "object",
+                        "properties": {
+                          "robots": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "format": "uuid",
+                              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+                            },
+                            "description": "The robots that stay, by id. Every other robot is deleted when the change takes effect."
+                          },
+                          "apps": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "format": "uuid",
+                              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+                            },
+                            "description": "The apps that stay, by id. Every other app is deleted when the change takes effect."
+                          },
+                          "app_users": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "format": "uuid",
+                              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+                            },
+                            "description": "The app users that stay, by id, across every app. Every other app user is deleted when the change takes effect."
+                          },
+                          "developers": {
+                            "type": "array",
+                            "items": {
+                              "type": "string",
+                              "format": "uuid",
+                              "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+                            },
+                            "description": "The developers that stay, by user id, owners never among them: every owner stays. Every other developer is removed from the org when the change takes effect."
+                          }
+                        },
+                        "required": [
+                          "robots",
+                          "apps",
+                          "app_users",
+                          "developers"
+                        ],
+                        "additionalProperties": false
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "What stays. `null` when the org already fits the target plan and nothing is deleted."
+                  },
+                  "history_days_after": {
+                    "type": "integer",
+                    "exclusiveMinimum": 0,
+                    "maximum": 9007199254740991,
+                    "description": "Days of history and audit log the org keeps on the target plan."
+                  },
+                  "chosen_by": {
+                    "type": "string",
+                    "format": "uuid",
+                    "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$",
+                    "description": "The user id of the owner who chose the change, or the nil UUID when Fleetless queued it."
+                  },
+                  "chosen_at": {
+                    "type": "string",
+                    "format": "date-time",
+                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
+                    "description": "When the change was chosen."
+                  }
+                },
+                "required": [
+                  "target_plan",
+                  "reason",
+                  "effective_at",
+                  "keep",
+                  "history_days_after",
+                  "chosen_by",
+                  "chosen_at"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "A move to a lower plan that has not taken effect yet, or `null`."
+          },
+          "lock": {
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "reason": {
+                    "type": "string",
+                    "enum": [
+                      "payment",
+                      "migration"
+                    ],
+                    "description": "`payment`: a payment is missing. `migration`: the org did not choose what stays when the beta ended."
+                  },
+                  "since": {
+                    "type": "string",
+                    "format": "date-time",
+                    "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$",
+                    "description": "When the org was locked."
+                  }
+                },
+                "required": [
+                  "reason",
+                  "since"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Why and since when the org is locked, or `null` when it is not."
+          },
+          "switch": {
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "at": {
+                    "anyOf": [
+                      {
+                        "type": "string",
+                        "format": "date-time",
+                        "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
+                      },
+                      {
+                        "type": "null"
+                      }
+                    ],
+                    "description": "When the org moves from the beta onto its plan. `null` while the date is not set."
+                  },
+                  "needs_choice": {
+                    "type": "boolean",
+                    "description": "Whether the org uses more than Basic allows, so an owner has to choose what stays before `at`."
+                  }
+                },
+                "required": [
+                  "at",
+                  "needs_choice"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "Set only while the org is still on the beta; `null` for every other org."
+          }
+        },
+        "required": [
+          "plan",
+          "currency",
+          "period_ends_at",
+          "addons",
+          "limits",
+          "features",
+          "usage",
+          "pending_change",
+          "lock",
+          "switch"
+        ],
+        "additionalProperties": false
+      },
       "org-quota-usage": {
         "type": "object",
         "properties": {
@@ -18309,6 +18924,82 @@
         ],
         "additionalProperties": false
       },
+      "plan-change-request": {
+        "type": "object",
+        "properties": {
+          "target_plan": {
+            "type": "string",
+            "enum": [
+              "basic",
+              "plus",
+              "pro",
+              "enterprise"
+            ],
+            "description": "The lower plan to move to; `basic` cancels."
+          },
+          "keep": {
+            "anyOf": [
+              {
+                "type": "object",
+                "properties": {
+                  "robots": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "format": "uuid",
+                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+                    },
+                    "description": "The robots that stay, by id. Every other robot is deleted when the change takes effect."
+                  },
+                  "apps": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "format": "uuid",
+                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+                    },
+                    "description": "The apps that stay, by id. Every other app is deleted when the change takes effect."
+                  },
+                  "app_users": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "format": "uuid",
+                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+                    },
+                    "description": "The app users that stay, by id, across every app. Every other app user is deleted when the change takes effect."
+                  },
+                  "developers": {
+                    "type": "array",
+                    "items": {
+                      "type": "string",
+                      "format": "uuid",
+                      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
+                    },
+                    "description": "The developers that stay, by user id, owners never among them: every owner stays. Every other developer is removed from the org when the change takes effect."
+                  }
+                },
+                "required": [
+                  "robots",
+                  "apps",
+                  "app_users",
+                  "developers"
+                ],
+                "additionalProperties": false
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "What stays. `null` when the org already fits the target plan, so nothing is deleted."
+          }
+        },
+        "required": [
+          "target_plan",
+          "keep"
+        ],
+        "additionalProperties": false
+      },
       "protected-resource-metadata": {
         "type": "object",
         "properties": {