@fleetless/contracts 1.0.0

package/artifacts/schema/parameter-invalid-details.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "violations": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "field": {
+            "type": "string",
+            "minLength": 1
+          },
+          "rule": {
+            "type": "string",
+            "minLength": 1
+          },
+          "message": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "field",
+          "rule",
+          "message"
+        ],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "violations"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/parameter-spec.schema.json

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

package/artifacts/schema/parameter-violation.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "field": {
+      "type": "string",
+      "minLength": 1
+    },
+    "rule": {
+      "type": "string",
+      "minLength": 1
+    },
+    "message": {
+      "type": "string",
+      "minLength": 1
+    }
+  },
+  "required": [
+    "field",
+    "rule",
+    "message"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/password-change-request.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "current_password": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The password in use right now. It is required even though the session already proves identity: it is what makes a stolen *session* insufficient to take the *account*."
+    },
+    "new_password": {
+      "type": "string",
+      "minLength": 12,
+      "maxLength": 256,
+      "description": "The replacement password. Every other session is revoked when it is accepted, while the session that made the change survives — logging somebody out of the tab they just used is indistinguishable from the change having failed."
+    }
+  },
+  "required": [
+    "current_password",
+    "new_password"
+  ]
+}

package/artifacts/schema/password-reset-confirm.schema.json

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

package/artifacts/schema/password-reset-request.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "email": {
+      "type": "string",
+      "format": "email",
+      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
+    }
+  },
+  "required": [
+    "email"
+  ]
+}

package/artifacts/schema/patch-app-oidc-provider-request.schema.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "description": "A new display name for the provider.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80
+    },
+    "issuer": {
+      "description": "A new issuer URL. Changing it re-runs discovery; identities linked under the old one keep their `(provider, subject)` key.",
+      "type": "string",
+      "maxLength": 500,
+      "format": "uri"
+    },
+    "client_id": {
+      "description": "A new client id.",
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 200
+    },
+    "client_secret": {
+      "description": "A replacement client secret. **Absent means keep the stored one**, so a routine edit need not put the secret back on the wire; it is never echoed back by any route.",
+      "type": "string",
+      "minLength": 16,
+      "maxLength": 500
+    },
+    "scopes": {
+      "description": "A replacement scope list. A replace, not a merge.",
+      "minItems": 1,
+      "maxItems": 20,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 60
+      }
+    },
+    "link_verified_emails": {
+      "description": "Whether a federated login may join an existing app user by verified address.",
+      "type": "boolean"
+    },
+    "enabled": {
+      "description": "Turn the provider off or back on without deleting it or its linked identities.",
+      "type": "boolean"
+    }
+  },
+  "additionalProperties": false
+}

package/artifacts/schema/patch-app-user-request.schema.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "display_name": {
+      "description": "The user's display name. Absent leaves it alone; an explicit `null` clears it.",
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "role_id": {
+      "description": "The role the user holds from now on. A role belonging to another app is `404 not_found`, the same refusal a role that never existed gets; re-roling closes the user's live subscriptions.",
+      "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)$"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "active",
+        "blocked"
+      ],
+      "description": "Block the account or let it back in. **`pending_verification` cannot be set here**: it is reached only by self-registration and left only by spending the mailed verification token, so a developer setting it would strand the account in a state nothing re-mails them out of."
+    }
+  },
+  "additionalProperties": false
+}

package/artifacts/schema/patch-auth-me-request.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "display_name": {
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "required": [
+    "display_name"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/patch-fleetless-user-request.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "display_name": {
+      "description": "The member's display name. Absent leaves it alone; an explicit `null` clears it.",
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120
+        },
+        {
+          "type": "null"
+        }
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/artifacts/schema/patch-org-request.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 120
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/patch-org-response.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "org": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "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 organisation. Every developer route is scoped to the caller's org already, so a client rarely has to send this anywhere."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120,
+          "description": "The organisation's display name. Free text, changed through `PATCH /api/org`."
+        },
+        "created_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 organisation was created, as an ISO 8601 timestamp."
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "created_at"
+      ],
+      "additionalProperties": false,
+      "description": "The organisation as it now stands, after the patch was applied. The whole resource comes back, not only the fields that changed."
+    }
+  },
+  "required": [
+    "org"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/patch-robot-request.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 63
+    }
+  },
+  "required": [
+    "name"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/patch-robot-response.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "robot": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "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 robot, and what every robot-scoped route takes as its `:id`."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 63,
+          "description": "The robot's display name, at most 63 characters. Free text, changed through `PATCH /api/robots/:id`."
+        },
+        "created_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 robot was created, as an ISO 8601 timestamp."
+        }
+      },
+      "required": [
+        "id",
+        "name",
+        "created_at"
+      ],
+      "additionalProperties": false,
+      "description": "The robot as it now stands, after the patch was applied. The whole resource comes back, not only the fields that changed."
+    }
+  },
+  "required": [
+    "robot"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/pending-team-invite-list-response.schema.json

@@ -0,0 +1,52 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "invitations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": {
+            "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 invitation, as revoked and re-issued by the team."
+          },
+          "email": {
+            "type": "string",
+            "format": "email",
+            "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
+            "description": "The address the invitation was addressed to."
+          },
+          "tier": {
+            "type": "string",
+            "enum": [
+              "owner",
+              "developer"
+            ],
+            "description": "The tier the invitee would hold. Visible so an owner can spot an owner-tier invitation they did not authorise."
+          },
+          "expires_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 token stops working."
+          }
+        },
+        "required": [
+          "id",
+          "email",
+          "tier",
+          "expires_at"
+        ],
+        "additionalProperties": false
+      },
+      "description": "Pending invitations only. An accepted invitation is history, not something to revoke."
+    }
+  },
+  "required": [
+    "invitations"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/pending-team-invite.schema.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "id": {
+      "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 invitation, as revoked and re-issued by the team."
+    },
+    "email": {
+      "type": "string",
+      "format": "email",
+      "pattern": "^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$",
+      "description": "The address the invitation was addressed to."
+    },
+    "tier": {
+      "type": "string",
+      "enum": [
+        "owner",
+        "developer"
+      ],
+      "description": "The tier the invitee would hold. Visible so an owner can spot an owner-tier invitation they did not authorise."
+    },
+    "expires_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 token stops working."
+    }
+  },
+  "required": [
+    "id",
+    "email",
+    "tier",
+    "expires_at"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/protected-resource-metadata.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "resource": {
+      "type": "string",
+      "format": "uri",
+      "description": "The resource identifier this document describes, per RFC 9728. A token whose audience names something else is rejected here rather than merely noted."
+    },
+    "authorization_servers": {
+      "minItems": 1,
+      "type": "array",
+      "items": {
+        "type": "string",
+        "format": "uri"
+      },
+      "description": "The authorization servers that may issue tokens for this resource. There is always at least one."
+    },
+    "bearer_methods_supported": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "const": "header"
+      },
+      "description": "How a token may be presented: in the `Authorization` header only, never in a query parameter or a form field."
+    },
+    "scopes_supported": {
+      "description": "The scopes this resource understands, where it publishes a list.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "required": [
+    "resource",
+    "authorization_servers",
+    "bearer_methods_supported"
+  ],
+  "additionalProperties": false
+}

package/artifacts/schema/publish-config-response.schema.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "version": {
+      "type": "integer",
+      "exclusiveMinimum": 0,
+      "maximum": 9007199254740991
+    },
+    "published_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))$"
+    }
+  },
+  "required": [
+    "version",
+    "published_at"
+  ],
+  "additionalProperties": false
+}

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

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "message": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string"
+      },
+      "additionalProperties": {},
+      "description": "The values to publish, keyed by the **parameter names** the publisher declares — the same flat form an invoke takes for `params`. They are checked against the declared bounds in the cloud before anything reaches the robot, and a slug another caller is still holding is refused with the remaining wait."
+    }
+  },
+  "required": [
+    "message"
+  ]
+}