@fleetless/contracts 1.0.0

package/artifacts/schema/publisher-config.schema.json

@@ -0,0 +1,285 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "topic": {
+      "type": "string",
+      "maxLength": 255,
+      "pattern": "^\\/[A-Za-z_][A-Za-z0-9_]*(?:\\/[A-Za-z_][A-Za-z0-9_]*)*$",
+      "description": "The ROS topic the message is published onto, as an absolute graph name. **No client ever names a topic**: a caller addresses this entry by its slug, so the topics an app can write to are exactly the ones written in this file.",
+      "patternErrorMessage": "A ROS graph name is absolute: it begins with a slash, and each segment after a slash starts with a letter or an underscore and continues with letters, digits and underscores — `/camera/image_raw`. A relative name, a trailing slash, a dash or a dot is refused.",
+      "examples": [
+        "/cmd_vel"
+      ]
+    },
+    "type": {
+      "type": "string",
+      "maxLength": 255,
+      "pattern": "^[a-z][a-z0-9_]*\\/(?:msg|srv|action)\\/[A-Za-z][A-Za-z0-9]*$",
+      "description": "The message type of `topic`, spelled the way ROS 2 spells it, with the `msg` segment. It fixes the shape that `message` and `failsafe.message` must both fill, which is why one publisher carries one type and a second type needs a second publisher.",
+      "patternErrorMessage": "A ROS 2 type name has three segments: the package, then `msg`, `srv` or `action`, then the type — `sensor_msgs/msg/BatteryState`, `std_srvs/srv/Trigger`, `nav2_msgs/action/NavigateToPose`. The middle segment is the one usually left out. The package is lower-case with underscores; the type itself is letters and digits, conventionally CamelCase.",
+      "examples": [
+        "geometry_msgs/msg/Twist"
+      ]
+    },
+    "message": {
+      "description": "The message as it will be sent, written out in full: literals are fixed, `${name}` is a hole a caller fills, and a field written `0.0` is one no client can change. Directly after `message:` a `${name}` standing alone names a shared message instead; anywhere inside a body it is a parameter. `null` is refused **at every depth** — omitting a key is the only spelling of \"not set\"."
+    },
+    "parameters": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "minLength": 2,
+        "maxLength": 63,
+        "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$",
+        "patternErrorMessage": "A name is lower-case: it starts with a letter, continues with letters and digits, and joins further words with a single underscore — `battery_voltage`. Capitals, dashes, dots, spaces, a leading digit and a doubled or trailing underscore are all refused."
+      },
+      "additionalProperties": {
+        "type": "object",
+        "properties": {
+          "type": {
+            "type": "string",
+            "enum": [
+              "bool",
+              "byte",
+              "char",
+              "int8",
+              "uint8",
+              "int16",
+              "uint16",
+              "int32",
+              "uint32",
+              "int64",
+              "uint64",
+              "float32",
+              "float64",
+              "string",
+              "wstring"
+            ],
+            "description": "The ROS 2 primitive a value of this parameter must be, spelled the way ROS 2 spells it — `float64`, not `double`. It **decides which other constraints are allowed at all**: `min_value` and `max_value` need a numeric type, `regex` needs a string one, and a constraint on the wrong type is refused rather than quietly ignored.",
+            "enumDescriptions": [
+              "A `true`/`false` flag. The one type that takes no constraint at all: no bounds, no `regex`, no `enum`.",
+              "One raw octet, `0` to `255`, carrying no character meaning. It counts as an integer here, so bounds and an `enum` apply to it.",
+              "A single-octet character code, `0` to `255`. ROS 2 keeps it apart from `byte` although the width is the same, and it travels as a number rather than as a one-character string.",
+              "A whole number from `-128` to `127`.",
+              "A whole number from `0` to `255`.",
+              "A whole number from `-32768` to `32767`.",
+              "A whole number from `0` to `65535`.",
+              "A whole number from `-2147483648` to `2147483647` — the usual choice for a count or an index.",
+              "A whole number from `0` to `4294967295`.",
+              "A whole number from `-9223372036854775808` to `9223372036854775807`.",
+              "A whole number from `0` to `18446744073709551615`.",
+              "A single-precision number, roughly seven significant digits.",
+              "A double-precision number, roughly fifteen significant digits. This is what other languages call `double`; ROS 2 spells it `float64` and so does this field.",
+              "Text, carried as UTF-8. One of the two types a `regex` may constrain.",
+              "Text as wide characters, and rare — nearly every ROS 2 interface uses `string`. It takes a `regex` on the same terms."
+            ]
+          },
+          "default": {
+            "anyOf": [
+              {
+                "type": "number"
+              },
+              {
+                "type": "string"
+              },
+              {
+                "type": "boolean"
+              }
+            ],
+            "description": "The value used when a caller omits this parameter: **without a `default` the parameter is required**, because the message cannot be built without it. It must itself satisfy `min_value`, `max_value`, `enum` and `regex` — a default the constraints reject is refused here rather than becoming the one value that reaches the robot unchecked."
+          },
+          "min_value": {
+            "type": "number",
+            "description": "The lowest value a caller may send; numeric types only. It is **enforced in the cloud, before anything reaches the robot** — this is where a speed limit actually holds, rather than in the app that is supposed to respect it.",
+            "examples": [
+              -0.5
+            ]
+          },
+          "max_value": {
+            "type": "number",
+            "description": "The highest value a caller may send; numeric types only, and it may not sit below `min_value`. A reversed pair is refused at parse time, because nothing downstream catches it and every call would then fail against a bound no value can satisfy.",
+            "examples": [
+              0.5
+            ]
+          },
+          "enum": {
+            "minItems": 1,
+            "type": "array",
+            "items": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "number"
+                }
+              ]
+            },
+            "description": "The complete set of values a caller may send. Integer and string types only — **never a float**, because equality on floating point is unreliable and an enumerated float list is a trap that only shows up in operation. Every entry must match `type`, and a `default` must be one of them."
+          },
+          "regex": {
+            "type": "string",
+            "minLength": 1,
+            "description": "A pattern the value must match; string types only. It is compiled as a JavaScript regular expression and is **not anchored**, so `[a-z]+` accepts any value that merely contains a lowercase run — a pattern meant to cover the whole value writes its own `^` and `$`.",
+            "examples": [
+              "^[a-z_]+$"
+            ]
+          },
+          "description": {
+            "description": "What this parameter means, in the developer's own words, and documentation only — the robot does nothing with it. It travels into the input schema `robot_describe` publishes for this call, beside the bounds, so `type` and the range say what the value *is* and this is the only place that says what it *does*.",
+            "examples": [
+              "What a caller is choosing when they set this."
+            ],
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 500
+          }
+        },
+        "required": [
+          "type"
+        ],
+        "additionalProperties": false,
+        "defaultSnippets": [
+          {
+            "label": "a parameter, with its bounds",
+            "description": "One hole a caller fills: what type it is, what values it may take, and what it means. Without a `default` it is required, and the bounds are enforced in the cloud before anything reaches the robot.",
+            "body": {
+              "type": "${2:float64}",
+              "min_value": -0.5,
+              "max_value": 0.5,
+              "description": "${3:What a caller is choosing when they set this.}"
+            }
+          }
+        ]
+      },
+      "description": "The holes in this entry's `message` that a caller fills, keyed by **parameter name** rather than by field path — so the name survives the field moving inside the message, and a caller sends something that means what it says. Every declared parameter must appear somewhere in the message and every `${name}` in the message must be declared; either half alone is an error.",
+      "defaultSnippets": [
+        {
+          "label": "a parameter, with its bounds",
+          "description": "One hole a caller fills: what type it is, what values it may take, and what it means. Without a `default` it is required, and the bounds are enforced in the cloud before anything reaches the robot.",
+          "body": {
+            "${1:speed}": {
+              "type": "${2:float64}",
+              "min_value": -0.5,
+              "max_value": 0.5,
+              "description": "${3:What a caller is choosing when they set this.}"
+            }
+          }
+        }
+      ]
+    },
+    "failsafe": {
+      "type": "object",
+      "properties": {
+        "timeout_ms": {
+          "type": "integer",
+          "exclusiveMinimum": 0,
+          "maximum": 60000,
+          "description": "How long the bridge waits for the client's next send before sending the failsafe message itself, in milliseconds. The deadline runs **on the robot**, so it still fires when the link to the cloud is what failed — which is the case it exists for.",
+          "examples": [
+            500,
+            1000
+          ]
+        },
+        "message": {
+          "description": "What the bridge sends once `timeout_ms` runs out — for a drive command, a zero twist. It must be safe in **every** state, because it is sent precisely when nobody is watching any more, and it may hold no placeholder: there is no caller left to fill one."
+        }
+      },
+      "required": [
+        "timeout_ms",
+        "message"
+      ],
+      "additionalProperties": false,
+      "description": "What the bridge sends **by itself** once a client stops sending, and how long it waits first. This is the format's safety story in one field: a client that crashes, loses its connection or whose operator closes the window does not leave a robot driving. The message may hold no placeholder, inline or through a shared message — there is nobody left to fill one.",
+      "defaultSnippets": [
+        {
+          "label": "a deadline, and the message it sends",
+          "description": "Half a second of silence and then a zero twist. The deadline runs on the robot, so it still fires when the link to the cloud is what failed — which is the case it exists for.",
+          "body": {
+            "timeout_ms": 500,
+            "message": {
+              "linear": {
+                "x": 0
+              },
+              "angular": {
+                "z": 0
+              }
+            }
+          }
+        }
+      ]
+    },
+    "quiet_timeout_ms": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 600000,
+      "description": "How long this publisher must stay silent before a **different** user may send to it. Whoever sends holds it implicitly exclusive, with no session and no lock, so this one number is the whole handover policy: too short and two operators fight over one robot, too long and a crashed client blocks it for everyone.",
+      "examples": [
+        2000
+      ]
+    },
+    "description": {
+      "description": "What sending to this publisher does, in the developer's own words. It is documentation for the console and for MCP clients — the robot does nothing with it — and as for actions and services, the publisher is offered whether or not one is written, with `description: null` when it is not. A caller sends here repeatedly and continuously rather than once, which is why this kind alone carries `failsafe` and `quiet_timeout_ms`.",
+      "examples": [
+        "Velocity command. If sending stops, the robot stops."
+      ],
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 2000
+    }
+  },
+  "required": [
+    "topic",
+    "type",
+    "message",
+    "failsafe",
+    "quiet_timeout_ms"
+  ],
+  "additionalProperties": false,
+  "defaultSnippets": [
+    {
+      "label": "a publisher, with its parameters and its failsafe",
+      "description": "A topic clients may send to: what is fixed, what a caller fills, and what the bridge sends by itself once the caller falls silent.",
+      "body": {
+        "topic": "${2:/cmd_vel}",
+        "type": "${3:geometry_msgs/msg/Twist}",
+        "message": {
+          "linear": {
+            "x": "\\${speed}"
+          },
+          "angular": {
+            "z": "\\${turn}"
+          }
+        },
+        "parameters": {
+          "speed": {
+            "type": "float64",
+            "min_value": -0.5,
+            "max_value": 0.5,
+            "default": 0
+          },
+          "turn": {
+            "type": "float64",
+            "min_value": -0.5,
+            "max_value": 0.5,
+            "default": 0
+          }
+        },
+        "failsafe": {
+          "timeout_ms": 500,
+          "message": {
+            "linear": {
+              "x": 0
+            },
+            "angular": {
+              "z": 0
+            }
+          }
+        },
+        "quiet_timeout_ms": 2000,
+        "description": "${4:Velocity command. If sending stops, the robot stops.}"
+      }
+    }
+  ]
+}

package/artifacts/schema/put-app-auth-config-request.schema.json

@@ -0,0 +1,93 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "self_registration": {
+      "type": "boolean",
+      "description": "Whether a stranger may create an account in this app. Off refuses `POST /api/client/register` with `403 registration_closed`, and refuses an unknown identity at an OIDC callback with the same reasoning — one switch for one decision, whichever door the person arrives at."
+    },
+    "allowed_domains": {
+      "maxItems": 50,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 253,
+        "pattern": "^(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\\.)+[a-z]{2,63}$"
+      },
+      "description": "The email domains self-registration accepts, lowercase. An empty list means no domain restriction, not \"nobody\" — the switch above is what closes the door. **An invitation always bypasses this**, by password and through a provider alike."
+    },
+    "allowed_origins": {
+      "maxItems": 20,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "maxLength": 200
+      },
+      "description": "The origins the client auth API answers CORS for, and the only origins an OIDC `redirect_uri` may name. Bare origins: scheme, host and port, with no path — a browser sends nothing longer, so an entry carrying one could never match."
+    },
+    "mcp_enabled": {
+      "type": "boolean",
+      "description": "Whether this app serves an MCP endpoint at `/mcp/<identifier>`. Off refuses the whole OAuth surface for the app, not merely the tool calls, and is re-read on every request rather than cached off a token."
+    },
+    "invite_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 500
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The page in the developer's app that accepts an invitation, with `{token}` where the token goes. `null` when unconfigured, and then an invitation still issues but `send_mail` is refused with `409 target_state_conflict` — there would be nowhere for the link to point."
+    },
+    "verify_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 500
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The page that confirms a new address, with `{token}` where the token goes. Self-registration needs it: without a page to send people to, a registration would leave an account nobody can activate."
+    },
+    "reset_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 500
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The page that takes a new password, with `{token}` where the token goes."
+    },
+    "mcp_login_url": {
+      "anyOf": [
+        {
+          "type": "string",
+          "maxLength": 500
+        },
+        {
+          "type": "null"
+        }
+      ],
+      "description": "The page an MCP authorization redirects to, with `{interaction}` where the interaction id goes. Not a token: the id names a pending request the server already holds, and the app authenticates the user itself before approving it."
+    }
+  },
+  "required": [
+    "self_registration",
+    "allowed_domains",
+    "allowed_origins",
+    "mcp_enabled",
+    "invite_url",
+    "verify_url",
+    "reset_url",
+    "mcp_login_url"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/put-app-mail-template-request.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "subject": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200,
+      "description": "The subject line, a Liquid template. Bounded because a subject is rendered into a header."
+    },
+    "text": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 20000,
+      "description": "The plain-text body, a Liquid template. Required even when an HTML part is given: a mail with no text part is unreadable to a client that refuses HTML."
+    },
+    "html": {
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100000
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "subject",
+    "text"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/put-config-draft-request.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "source": {
+      "type": "string",
+      "maxLength": 1000000
+    }
+  },
+  "required": [
+    "source"
+  ]
+}

package/artifacts/schema/put-datapoint-display-request.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "y_min": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "y_max": {
+      "anyOf": [
+        {
+          "type": "number"
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "y_min",
+    "y_max"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/put-robot-details-request.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "details": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+      },
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "string",
+            "maxLength": 4096
+          },
+          {
+            "type": "number"
+          },
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "array",
+            "items": {}
+          },
+          {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {}
+          }
+        ]
+      }
+    }
+  },
+  "required": [
+    "details"
+  ]
+}

package/artifacts/schema/put-robot-details-response.schema.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "details": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9_-]{0,63}$"
+      },
+      "additionalProperties": {
+        "anyOf": [
+          {
+            "type": "string",
+            "maxLength": 4096
+          },
+          {
+            "type": "number"
+          },
+          {
+            "type": "boolean"
+          },
+          {
+            "type": "array",
+            "items": {}
+          },
+          {
+            "type": "object",
+            "propertyNames": {
+              "type": "string"
+            },
+            "additionalProperties": {}
+          }
+        ]
+      },
+      "description": "The stored `robot_details` document, which is the one that was just sent — this route **replaces** the document rather than merging into it. Keys are the developer's own, lowercase and at most 64 characters; a value is a string of at most 4096 characters, a number, a boolean, an array or an object."
+    }
+  },
+  "required": [
+    "details"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/rate-limit-details.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "retry_after_ms": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    }
+  },
+  "required": [
+    "retry_after_ms"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/refresh-request.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "refresh_token": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "refresh_token"
+  ]
+}

package/artifacts/schema/release-live-query.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "session_id": {
+      "description": "The one hold to release, as the live session returned it. Absent releases **all** of this identity's holds on this camera — the blunt form, still needed by a client that has lost its id or is going away, and the one that strands the identity's other tabs.",
+      "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)$"
+    }
+  },
+  "additionalProperties": false
+}

package/artifacts/schema/rename-slug-request.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "from": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 63,
+      "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+    },
+    "to": {
+      "type": "string",
+      "minLength": 2,
+      "maxLength": 63,
+      "pattern": "^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$"
+    }
+  },
+  "required": [
+    "from",
+    "to"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/rename-slug-response.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "rewritten_grants": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 9007199254740991
+    },
+    "history_moved": {
+      "type": "boolean"
+    },
+    "requires_publish": {
+      "type": "boolean",
+      "const": true
+    }
+  },
+  "required": [
+    "rewritten_grants",
+    "history_moved",
+    "requires_publish"
+  ],
+  "additionalProperties": false
+}