@fleetless/contracts 6.0.0 → 6.1.0-next.2

package/artifacts/routes.json

@@ -6368,6 +6368,107 @@
       "transport": "http",
       "notes": "The message is stored before any mail is tried, so `202` means it is kept whatever `mail` says: `sent`, `failed`, or `not_configured` when this cloud has no feedback address. At most 10 messages per developer per hour; the 11th answers `429 rate_limited` with `retry_after_ms`. Replies come by mail, to the sender's address."
     },
+    {
+      "method": "GET",
+      "path": "/api/org/plan",
+      "section": "org",
+      "summary": "Reads the org's plan: its limits, its usage against them, its add-ons and any change already queued.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": false,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": "org-plan",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked"
+      ],
+      "transport": "http",
+      "notes": "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."
+    },
+    {
+      "method": "PUT",
+      "path": "/api/org/plan/change",
+      "section": "org",
+      "summary": "Moves the org's plan down — a lower plan or a cancellation to Basic — queuing the change rather than applying it at once.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 200,
+      "params": [],
+      "query": null,
+      "request": "plan-change-request",
+      "response": "org-plan",
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "validation_error",
+        "plan_limit",
+        "target_state_conflict"
+      ],
+      "transport": "http",
+      "notes": "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."
+    },
+    {
+      "method": "DELETE",
+      "path": "/api/org/plan/change",
+      "section": "org",
+      "summary": "Withdraws a plan change that was queued but has not taken effect yet.",
+      "audience": "developer",
+      "auth": "developer",
+      "rateLimited": false,
+      "ownerTier": true,
+      "status": 204,
+      "params": [],
+      "query": null,
+      "request": null,
+      "response": null,
+      "errors": [
+        "unauthorized",
+        "token_expired",
+        "token_revoked",
+        "tier_required",
+        "not_found"
+      ],
+      "transport": "http",
+      "notes": "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."
+    },
+    {
+      "method": "PATCH",
+      "path": "/api/admin/orgs/:id/plan",
+      "section": "org",
+      "summary": "Changes an org's plan, add-ons, limit overrides, currency or billing period as the operator.",
+      "audience": "internal",
+      "auth": "ops",
+      "rateLimited": true,
+      "ownerTier": false,
+      "status": 200,
+      "params": [
+        {
+          "name": "id",
+          "description": "The org's uuid, whose plan, add-ons or overrides the operator is changing."
+        }
+      ],
+      "query": null,
+      "request": "admin-plan-change-request",
+      "response": "org-plan",
+      "errors": [
+        "unauthorized",
+        "not_found",
+        "validation_error",
+        "plan_limit",
+        "rate_limited"
+      ],
+      "transport": "http",
+      "notes": "Every public host answers `404 not_found` for every `/api/admin/*` path — this route is reachable only on the cloud's private address — and that same address answers `404` here too while `OPS_API_TOKEN` is not configured, so a door with no key behind it reads exactly like one nobody opened. An unknown `:id` is the same `404`. Applies at once, never queued as a `pending_change`, and only when the org's current usage fits the result: `409 plan_limit` when a lower plan, a lowered override or a removed add-on would leave the org over a limit — the operator never deletes an org's things, only the owner's own choice does. On success it also withdraws any `pending_change`, ends a beta org's wait for the switch and lifts a lock. Audited as `org.plan_changed` with the `fleetless` actor, never a developer's — the row names what an operator did, not who in the org asked for it."
+    },
     {
       "method": "POST",
       "path": "/api/bridge/assets",

package/artifacts/schema/addon-catalogue-entry.schema.json

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "key": {
+      "type": "string",
+      "enum": [
+        "seats",
+        "robots",
+        "apps",
+        "app_user_packs",
+        "live_video_packs"
+      ],
+      "description": "The add-on."
+    },
+    "raises": {
+      "type": "string",
+      "enum": [
+        "seats",
+        "robots",
+        "apps",
+        "app_users",
+        "live_video_ms_per_month",
+        "asset_bytes_per_robot",
+        "history_days",
+        "audit_days"
+      ],
+      "description": "The plan limit this add-on raises."
+    },
+    "per_unit": {
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "description": "How much one unit of this add-on raises `raises` by."
+    },
+    "prices": {
+      "type": "object",
+      "properties": {
+        "eur_month": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "Per month in euro cents, excluding VAT."
+        },
+        "usd_month": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "Per month in US dollar cents, excluding VAT: the euro price × 1.15, rounded up to a whole dollar."
+        },
+        "eur_year": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "Per year in euro cents, excluding VAT: twelve months less 15 %."
+        },
+        "usd_year": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991,
+          "description": "Per year in US dollar cents, excluding VAT: the yearly euro price × 1.15, rounded up to a whole dollar."
+        }
+      },
+      "required": [
+        "eur_month",
+        "usd_month",
+        "eur_year",
+        "usd_year"
+      ],
+      "additionalProperties": false,
+      "description": "The price of one unit."
+    }
+  },
+  "required": [
+    "key",
+    "raises",
+    "per_unit",
+    "prices"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/addon-key.schema.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "string",
+  "enum": [
+    "seats",
+    "robots",
+    "apps",
+    "app_user_packs",
+    "live_video_packs"
+  ]
+}

package/artifacts/schema/admin-plan-change-request.schema.json

@@ -0,0 +1,189 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "plan": {
+      "type": "string",
+      "enum": [
+        "basic",
+        "plus",
+        "pro",
+        "enterprise"
+      ],
+      "description": "The plan the org is on after this request."
+    },
+    "addons": {
+      "description": "Add-on counts to set. Counts not named stay as they are.",
+      "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."
+        }
+      },
+      "additionalProperties": false
+    },
+    "overrides": {
+      "description": "Limits to override. `null` clears an override.",
+      "type": "object",
+      "properties": {
+        "seats": {
+          "description": "Replaces the plan's `seats`. `null` clears the override.",
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "robots": {
+          "description": "Replaces the plan's `robots`. `null` clears the override.",
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "apps": {
+          "description": "Replaces the plan's `apps`. `null` clears the override.",
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "app_users": {
+          "description": "Replaces the plan's `app_users`. `null` clears the override.",
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "live_video_ms_per_month": {
+          "description": "Replaces the plan's `live_video_ms_per_month`. `null` clears the override.",
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "asset_bytes_per_robot": {
+          "description": "Replaces the plan's `asset_bytes_per_robot`. `null` clears the override.",
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "history_days": {
+          "description": "Replaces the plan's `history_days`. `null` clears the override.",
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "audit_days": {
+          "description": "Replaces the plan's `audit_days`. `null` clears the override.",
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "currency": {
+      "description": "The currency the org is billed in.",
+      "type": "string",
+      "enum": [
+        "eur",
+        "usd"
+      ]
+    },
+    "period_ends_at": {
+      "description": "The end of the org's billing period. `null` falls back to the end of the current UTC month.",
+      "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"
+        }
+      ]
+    }
+  },
+  "required": [
+    "plan"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/asset-plan-limit-details.schema.json

@@ -0,0 +1,115 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "limit": {
+      "type": "string",
+      "enum": [
+        "seats",
+        "robots",
+        "apps",
+        "app_users",
+        "live_video_ms_per_month",
+        "asset_bytes_per_robot"
+      ],
+      "description": "The limit the action would exceed."
+    },
+    "used": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "How much of the limit the org uses now."
+    },
+    "max": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "The limit. For `asset_bytes_per_robot`, the org's whole pool: robots × the plan's bytes per robot."
+    },
+    "plan": {
+      "type": "string",
+      "enum": [
+        "basic",
+        "plus",
+        "pro",
+        "enterprise"
+      ],
+      "description": "The plan whose limit refused: the target plan while a move to a lower plan is pending."
+    },
+    "lifted_by": {
+      "type": "object",
+      "properties": {
+        "plan": {
+          "anyOf": [
+            {
+              "type": "string",
+              "enum": [
+                "basic",
+                "plus",
+                "pro",
+                "enterprise"
+              ]
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The cheapest higher plan that raises this limit, or `null` when none does."
+        },
+        "addon": {
+          "anyOf": [
+            {
+              "type": "string",
+              "enum": [
+                "seats",
+                "robots",
+                "apps",
+                "app_user_packs",
+                "live_video_packs"
+              ]
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "The add-on that raises this limit, when the org's plan can buy add-ons; otherwise `null`."
+        }
+      },
+      "required": [
+        "plan",
+        "addon"
+      ],
+      "additionalProperties": false,
+      "description": "What would lift the limit."
+    },
+    "store_bytes": {
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "description": "The org's asset pool, in bytes: `robots × asset_bytes_per_robot`."
+    },
+    "used_bytes": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991,
+      "description": "Bytes the org's assets occupy, across every robot, before this upload."
+    },
+    "size_bytes": {
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991,
+      "description": "The refused upload, in bytes."
+    }
+  },
+  "required": [
+    "limit",
+    "used",
+    "max",
+    "plan",
+    "lifted_by",
+    "store_bytes",
+    "used_bytes",
+    "size_bytes"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/audit-actor.schema.json

@@ -9,7 +9,8 @@
         "end_user",
         "app_user",
         "server_key",
-        "bridge"
+        "bridge",
+        "fleetless"
       ]
     },
     "id": {

package/artifacts/schema/audit-event.schema.json

@@ -32,7 +32,8 @@
             "end_user",
             "app_user",
             "server_key",
-            "bridge"
+            "bridge",
+            "fleetless"
           ]
         },
         "id": {

package/artifacts/schema/audit-list-response.schema.json

@@ -37,7 +37,8 @@
                   "end_user",
                   "app_user",
                   "server_key",
-                  "bridge"
+                  "bridge",
+                  "fleetless"
                 ]
               },
               "id": {

package/artifacts/schema/org-addons.schema.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "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
+}

package/artifacts/schema/org-lock.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "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
+}

package/artifacts/schema/org-locked-details.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "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."
+    }
+  },
+  "required": [
+    "reason"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/org-plan-usage.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "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
+}