@fleetless/contracts 6.2.0-next.1 → 6.2.0

package/CHANGELOG.md

@@ -9,14 +9,23 @@ version.
 
 ## [Unreleased]
 
+## [6.2.0] — 2026-10-04
+
 ### Added
 
 - **`file_too_large`** (`413`): one asset file is larger than
   `ASSET_FILE_MAX_BYTES` (one gigabyte, every plan, the URDF included).
-  `details` is `fileTooLargeDetails`: `max_bytes` and `size_bytes`, which is
-  `null` when no size was announced and the body limit stopped the upload.
+  `details` is `fileTooLargeDetails`: `max_bytes` and `size_bytes`, the
+  announced size or, when none (or a false one) was announced, the bytes that
+  arrived; `null` only when the body limit stopped the upload.
   `ASSET_FILE_MAX_BYTES` is in `constants.json`. `plan_limit` and
   `quota_exceeded` on an asset upload now mean only that the store is full.
+- **`plan_limit` in `clientOidcErrorCode`.** A federated sign-in that would
+  create an app user beyond the org's plan `app_users` limit now redirects
+  with `?error=plan_limit`, so an app can tell that the plan is full.
+  `quota_exceeded` keeps one meaning there: the `max_end_users` protection
+  ceiling, which also covers orgs still on the beta. A consumer that switches
+  exhaustively over `ClientOidcErrorCode` gains one case.
 
 ### Changed
 

package/artifacts/routes.json

@@ -6494,7 +6494,7 @@
         "bad_request"
       ],
       "transport": "http",
-      "notes": "The body is the **raw file bytes**, not JSON, so it has no request schema; everything about the file — its kind, its name, its sync id and its announced size — rides in the `x-fleetless-asset-*` headers `ASSET_UPLOAD_HEADERS` names. The credential is a short-lived upload token minted by `POST /api/robots/:id/assets/sync`, verified in a `preParsing` hook so a refusal precedes the work rather than following it: a `preHandler` would already have buffered the whole file. **One file can be at most `ASSET_FILE_MAX_BYTES`**, on every plan and for every kind, the URDF included: an announced size over it answers `413 file_too_large` with `max_bytes` and `size_bytes` before a byte is buffered, and a body over the server's body limit without a truthful size answers the same code with `size_bytes: null`. Retrying does not help. A file that fits but finds the store full answers `409 plan_limit` (or `409 quota_exceeded` for an organisation still on the beta) carrying `store_bytes`, `used_bytes` and `size_bytes`, while the sync carries on with the next file. Rate limited per robot inside that same hook, which is why `rateLimited` is `false`: there is no rate-limiting preHandler registered on this route. The URDF itself is never refused for the store; only meshes and textures are charged against it."
+      "notes": "The body is the **raw file bytes**, not JSON, so it has no request schema; everything about the file — its kind, its name, its sync id and its announced size — rides in the `x-fleetless-asset-*` headers `ASSET_UPLOAD_HEADERS` names. The credential is a short-lived upload token minted by `POST /api/robots/:id/assets/sync`, verified in a `preParsing` hook so a refusal precedes the work rather than following it: a `preHandler` would already have buffered the whole file. **One file can be at most `ASSET_FILE_MAX_BYTES`**, on every plan and for every kind, the URDF included: an announced size over it answers `413 file_too_large` with `max_bytes` and `size_bytes` before a byte is buffered; without a truthful size, a body over the limit answers the same code with the bytes that arrived as `size_bytes`, or with `size_bytes: null` when it ran past the server's body limit and nobody counted the bytes. Retrying does not help. A file that fits but finds the store full answers `409 plan_limit` (or `409 quota_exceeded` for an organisation still on the beta) carrying `store_bytes`, `used_bytes` and `size_bytes`, while the sync carries on with the next file. Rate limited per robot inside that same hook, which is why `rateLimited` is `false`: there is no rate-limiting preHandler registered on this route. The URDF itself is never refused for the store; only meshes and textures are charged against it."
     },
     {
       "method": "GET",

package/artifacts/schema/file-too-large-details.schema.json

@@ -19,7 +19,7 @@
           "type": "null"
         }
       ],
-      "description": "The refused file's announced size, in bytes; `null` when no size was announced and the body limit stopped the upload."
+      "description": "The refused file's size, in bytes: the announced size, or the bytes that arrived when none (or a false one) was announced; `null` only when the body limit stopped the upload and nobody counted the bytes."
     }
   },
   "required": [

package/dist/assets.d.ts

@@ -203,8 +203,8 @@ export declare const ROBOT_ASSET_STORE_BYTES = 1000000000;
  * store says how much a robot may keep, this says how much the cloud will
  * take in one request. A file over it is refused `413 file_too_large` with
  * `fileTooLargeDetails`, before a byte is buffered when the size was
- * announced (`ASSET_UPLOAD_HEADERS.size`) and by the server's body limit when
- * it was not. That refusal is not a store or plan limit, applies to the URDF
+ * announced (`ASSET_UPLOAD_HEADERS.size`), and otherwise on the bytes that
+ * arrived, or by the server's body limit when the body ran past it. That refusal is not a store or plan limit, applies to the URDF
  * as well, and retrying does not help.
  *
  * In `constants.json` for the same reason as `ROBOT_ASSET_STORE_BYTES`.

package/dist/assets.js

@@ -258,8 +258,8 @@ export const ROBOT_ASSET_STORE_BYTES = 1_000_000_000;
  * store says how much a robot may keep, this says how much the cloud will
  * take in one request. A file over it is refused `413 file_too_large` with
  * `fileTooLargeDetails`, before a byte is buffered when the size was
- * announced (`ASSET_UPLOAD_HEADERS.size`) and by the server's body limit when
- * it was not. That refusal is not a store or plan limit, applies to the URDF
+ * announced (`ASSET_UPLOAD_HEADERS.size`), and otherwise on the bytes that
+ * arrived, or by the server's body limit when the body ran past it. That refusal is not a store or plan limit, applies to the URDF
  * as well, and retrying does not help.
  *
  * In `constants.json` for the same reason as `ROBOT_ASSET_STORE_BYTES`.

package/dist/client-auth.d.ts

@@ -373,14 +373,23 @@ export type ClientOidcExchangeRequest = z.infer<typeof clientOidcExchangeRequest
  *   `provider_misconfigured`, `provider_disabled` — the provider's or the
  *   developer's to fix, and the app can say so.
  * - `invalid_request` — the start parameters did not hold up.
- * - `quota_exceeded` — the org has as many app users as its `max_end_users`
- *   quota allows, so no account can be created for this identity. Named rather
- *   than folded into `no_access`, for `domain_not_allowed`'s reason: it is not
- *   about the person, the app can say what happened, and the remedy belongs to
- *   the developer rather than to whoever is trying to sign in. It is raised
+ * - `quota_exceeded` — the org is at the protection ceiling: it has as many
+ *   app users as its `max_end_users` quota allows, so no account can be
+ *   created for this identity. This also covers an org still on the beta,
+ *   whose plan is not enforced yet. Named rather than folded into
+ *   `no_access`, for `domain_not_allowed`'s reason: it is not about the
+ *   person, the app can say what happened, and the remedy belongs to the
+ *   developer rather than to whoever is trying to sign in. It is raised
  *   **only where an account would be created** — an identity that already has
  *   one signs in at the quota exactly as it does under it, because refusing a
  *   sign-in would turn a protection limit into an outage.
+ * - `plan_limit` — the org's plan has no room for another app user: it is at
+ *   its plan's `app_users` limit (fleetless/fleetless#103), counted across
+ *   every app of the org with pending invitations included. Checked before
+ *   the protection ceiling, and raised, like `quota_exceeded`, **only where
+ *   an account would be created**. The remedy is a higher plan or an add-on,
+ *   which is why it is not `quota_exceeded`. It is the same code the other
+ *   app-user doors answer as `409 plan_limit`.
  */
 export declare const clientOidcErrorCode: z.ZodEnum<{
     no_access: "no_access";
@@ -395,6 +404,7 @@ export declare const clientOidcErrorCode: z.ZodEnum<{
     provider_disabled: "provider_disabled";
     invalid_request: "invalid_request";
     quota_exceeded: "quota_exceeded";
+    plan_limit: "plan_limit";
 }>;
 export type ClientOidcErrorCode = z.infer<typeof clientOidcErrorCode>;
 /**

package/dist/client-auth.js

@@ -435,14 +435,23 @@ export const clientOidcExchangeRequest = z
  *   `provider_misconfigured`, `provider_disabled` — the provider's or the
  *   developer's to fix, and the app can say so.
  * - `invalid_request` — the start parameters did not hold up.
- * - `quota_exceeded` — the org has as many app users as its `max_end_users`
- *   quota allows, so no account can be created for this identity. Named rather
- *   than folded into `no_access`, for `domain_not_allowed`'s reason: it is not
- *   about the person, the app can say what happened, and the remedy belongs to
- *   the developer rather than to whoever is trying to sign in. It is raised
+ * - `quota_exceeded` — the org is at the protection ceiling: it has as many
+ *   app users as its `max_end_users` quota allows, so no account can be
+ *   created for this identity. This also covers an org still on the beta,
+ *   whose plan is not enforced yet. Named rather than folded into
+ *   `no_access`, for `domain_not_allowed`'s reason: it is not about the
+ *   person, the app can say what happened, and the remedy belongs to the
+ *   developer rather than to whoever is trying to sign in. It is raised
  *   **only where an account would be created** — an identity that already has
  *   one signs in at the quota exactly as it does under it, because refusing a
  *   sign-in would turn a protection limit into an outage.
+ * - `plan_limit` — the org's plan has no room for another app user: it is at
+ *   its plan's `app_users` limit (fleetless/fleetless#103), counted across
+ *   every app of the org with pending invitations included. Checked before
+ *   the protection ceiling, and raised, like `quota_exceeded`, **only where
+ *   an account would be created**. The remedy is a higher plan or an add-on,
+ *   which is why it is not `quota_exceeded`. It is the same code the other
+ *   app-user doors answer as `409 plan_limit`.
  */
 export const clientOidcErrorCode = z.enum([
     'no_access',
@@ -457,6 +466,7 @@ export const clientOidcErrorCode = z.enum([
     'provider_disabled',
     'invalid_request',
     'quota_exceeded',
+    'plan_limit',
 ]);
 /* ------------------------------------------------ MCP, delegated login -- */
 /**

package/dist/errors.d.ts

@@ -214,9 +214,11 @@ export type OrgLockedDetails = z.infer<typeof orgLockedDetails>;
  * fleetless/fleetless#136): one file is larger than `ASSET_FILE_MAX_BYTES`.
  * Not a store and not a plan limit — those are `409 plan_limit` and
  * `409 quota_exceeded`, and mean only "the store is full". `size_bytes` is
- * the announced size; it is `null` only when the sender announced none (or a
- * false one) and the server's body limit stopped the upload, because then
- * nobody counted the bytes.
+ * the file's size: the announced one when the refusal came before the body
+ * was read, or the bytes that arrived when no size (or a false one) was
+ * announced and the body still fit the server's body limit. It is `null` only
+ * when the body limit stopped the upload, because then nobody counted the
+ * bytes.
  */
 export declare const fileTooLargeDetails: z.ZodObject<{
     max_bytes: z.ZodNumber;

package/dist/errors.js

@@ -140,16 +140,18 @@ export const orgLockedDetails = z.object({
  * fleetless/fleetless#136): one file is larger than `ASSET_FILE_MAX_BYTES`.
  * Not a store and not a plan limit — those are `409 plan_limit` and
  * `409 quota_exceeded`, and mean only "the store is full". `size_bytes` is
- * the announced size; it is `null` only when the sender announced none (or a
- * false one) and the server's body limit stopped the upload, because then
- * nobody counted the bytes.
+ * the file's size: the announced one when the refusal came before the body
+ * was read, or the bytes that arrived when no size (or a false one) was
+ * announced and the body still fit the server's body limit. It is `null` only
+ * when the body limit stopped the upload, because then nobody counted the
+ * bytes.
  */
 export const fileTooLargeDetails = z.object({
     max_bytes: z.number().int().positive().meta({
         description: 'The most one asset file can be, in bytes: `ASSET_FILE_MAX_BYTES`, the same on every plan.',
     }),
     size_bytes: z.number().int().positive().nullable().meta({
-        description: 'The refused file\'s announced size, in bytes; `null` when no size was announced and the body limit stopped the upload.',
+        description: 'The refused file\'s size, in bytes: the announced size, or the bytes that arrived when none (or a false one) was announced; `null` only when the body limit stopped the upload and nobody counted the bytes.',
     }),
 });
 /**
@@ -992,6 +994,10 @@ export const ERROR_CODES = [
      * The existing `quota_exceeded` protection ceiling is still checked, and
      * only after this one: it exists to stop runaway consumption, not to tell
      * a developer what their plan allows.
+     *
+     * At an OIDC callback the same refusal reaches the app as the
+     * `clientOidcErrorCode` of the same name, redirected rather than answered
+     * as JSON.
      */
     'plan_limit',
     /**
@@ -1016,7 +1022,8 @@ export const ERROR_CODES = [
     /**
      * `413`: one asset file is larger than `ASSET_FILE_MAX_BYTES`. Refused on
      * the announced size before the body is read, for every kind including the
-     * URDF, or by the body limit when no size was announced. `details` is
+     * URDF, otherwise on the bytes that arrived, or by the body limit when the
+     * body ran past it. `details` is
      * `fileTooLargeDetails`. Not a store or plan limit, on any plan; retrying
      * does not help, only a smaller file does.
      */

package/dist/realtime.d.ts

@@ -260,10 +260,10 @@ export type DatapointEvent = z.infer<typeof datapointEvent>;
  */
 export declare const liveSessionEndReason: z.ZodEnum<{
     unknown: "unknown";
+    plan_limit: "plan_limit";
     publish_failed: "publish_failed";
     robot_offline: "robot_offline";
     config_changed: "config_changed";
-    plan_limit: "plan_limit";
     released_by_peer: "released_by_peer";
     revoked: "revoked";
     expired: "expired";
@@ -292,10 +292,10 @@ export declare const liveSessionEvent: z.ZodObject<{
     state: z.ZodLiteral<"ended">;
     reason: z.ZodEnum<{
         unknown: "unknown";
+        plan_limit: "plan_limit";
         publish_failed: "publish_failed";
         robot_offline: "robot_offline";
         config_changed: "config_changed";
-        plan_limit: "plan_limit";
         released_by_peer: "released_by_peer";
         revoked: "revoked";
         expired: "expired";

package/dist/routes.js

@@ -2858,7 +2858,8 @@ export const ROUTES = [
             'upload token minted by `POST /api/robots/:id/assets/sync`, verified in a `preParsing` hook so a refusal precedes the work rather than ' +
             'following it: a `preHandler` would already have buffered the whole file. **One file can be at most `ASSET_FILE_MAX_BYTES`**, on every ' +
             'plan and for every kind, the URDF included: an announced size over it answers `413 file_too_large` with `max_bytes` and `size_bytes` ' +
-            'before a byte is buffered, and a body over the server\'s body limit without a truthful size answers the same code with `size_bytes: null`. ' +
+            'before a byte is buffered; without a truthful size, a body over the limit answers the same code with the bytes that arrived as `size_bytes`, ' +
+            'or with `size_bytes: null` when it ran past the server\'s body limit and nobody counted the bytes. ' +
             'Retrying does not help. A file that fits but finds the store full answers `409 plan_limit` (or `409 quota_exceeded` for an organisation ' +
             'still on the beta) carrying `store_bytes`, `used_bytes` and `size_bytes`, while the sync carries on with the next file. Rate limited per ' +
             'robot inside that same hook, which is why `rateLimited` is `false`: there is no rate-limiting preHandler registered on this route. The ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetless/contracts",
-  "version": "6.2.0-next.1",
+  "version": "6.2.0",
   "description": "Fleetless wire contracts: the bridge-cloud protocol, the REST API schemas and the error codes, as zod schemas with generated JSON Schema and OpenAPI artifacts.",
   "license": "Apache-2.0",
   "author": "Dehne Robotik GmbH",