@fleetless/contracts 6.0.0 → 6.1.0-next.1

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: an operator's plan, add-on or override change is never queued as a `pending_change`, unlike a developer's own downgrade. `409 plan_limit` when a lowered override or a removed add-on would leave the org's current usage over its new ceiling. Every change here is audited 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,75 @@
+{
+  "$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"
+      ]
+    },
+    "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
+        },
+        "usd_month": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "eur_year": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "usd_year": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        }
+      },
+      "required": [
+        "eur_month",
+        "usd_month",
+        "eur_year",
+        "usd_year"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "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,171 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "plan": {
+      "type": "string",
+      "enum": [
+        "basic",
+        "plus",
+        "pro",
+        "enterprise"
+      ]
+    },
+    "addons": {
+      "type": "object",
+      "properties": {
+        "seats": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "robots": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "apps": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "app_user_packs": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        },
+        "live_video_packs": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 9007199254740991
+        }
+      },
+      "additionalProperties": false
+    },
+    "overrides": {
+      "type": "object",
+      "properties": {
+        "seats": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "robots": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "apps": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "app_users": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "live_video_ms_per_month": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "asset_bytes_per_robot": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "history_days": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "audit_days": {
+          "anyOf": [
+            {
+              "type": "integer",
+              "exclusiveMinimum": 0,
+              "maximum": 9007199254740991
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "currency": {
+      "type": "string",
+      "enum": [
+        "eur",
+        "usd"
+      ]
+    },
+    "period_ends_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"
+        }
+      ]
+    }
+  },
+  "required": [
+    "plan"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,108 @@
+{
+  "$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"
+      ]
+    },
+    "used": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "max": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "plan": {
+      "type": "string",
+      "enum": [
+        "basic",
+        "plus",
+        "pro",
+        "enterprise"
+      ]
+    },
+    "lifted_by": {
+      "type": "object",
+      "properties": {
+        "plan": {
+          "anyOf": [
+            {
+              "type": "string",
+              "enum": [
+                "basic",
+                "plus",
+                "pro",
+                "enterprise"
+              ]
+            },
+            {
+              "type": "null"
+            }
+          ]
+        },
+        "addon": {
+          "anyOf": [
+            {
+              "type": "string",
+              "enum": [
+                "seats",
+                "robots",
+                "apps",
+                "app_user_packs",
+                "live_video_packs"
+              ]
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "required": [
+        "plan",
+        "addon"
+      ],
+      "additionalProperties": false
+    },
+    "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,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "seats": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "robots": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "apps": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "app_user_packs": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "live_video_packs": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    }
+  },
+  "required": [
+    "seats",
+    "robots",
+    "apps",
+    "app_user_packs",
+    "live_video_packs"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "reason": {
+      "type": "string",
+      "enum": [
+        "payment",
+        "migration"
+      ]
+    },
+    "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))$"
+    }
+  },
+  "required": [
+    "reason",
+    "since"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "reason": {
+      "type": "string",
+      "enum": [
+        "payment",
+        "migration"
+      ]
+    }
+  },
+  "required": [
+    "reason"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "seats": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "robots": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "apps": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "app_users": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "live_video_ms_this_month": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "asset_bytes": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    }
+  },
+  "required": [
+    "seats",
+    "robots",
+    "apps",
+    "app_users",
+    "live_video_ms_this_month",
+    "asset_bytes"
+  ],
+  "additionalProperties": false
+}