@fleetless/contracts 6.1.0-next.1 → 6.1.0-next.2

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

@@ -9,7 +9,8 @@
         "plus",
         "pro",
         "enterprise"
-      ]
+      ],
+      "description": "The plan."
     },
     "name": {
       "type": "string",
@@ -29,7 +30,8 @@
             {
               "type": "null"
             }
-          ]
+          ],
+          "description": "Developers, owners included, plus pending team invitations."
         },
         "robots": {
           "anyOf": [
@@ -41,7 +43,8 @@
             {
               "type": "null"
             }
-          ]
+          ],
+          "description": "Robots in the org."
         },
         "apps": {
           "anyOf": [
@@ -53,7 +56,8 @@
             {
               "type": "null"
             }
-          ]
+          ],
+          "description": "Apps in the org."
         },
         "app_users": {
           "anyOf": [
@@ -65,7 +69,8 @@
             {
               "type": "null"
             }
-          ]
+          ],
+          "description": "App users across every app of the org, plus pending app-user invitations."
         },
         "live_video_ms_per_month": {
           "anyOf": [
@@ -77,7 +82,8 @@
             {
               "type": "null"
             }
-          ]
+          ],
+          "description": "Live video watched by app users in one UTC calendar month, in milliseconds, across the org. Console sessions do not count."
         },
         "asset_bytes_per_robot": {
           "anyOf": [
@@ -89,7 +95,8 @@
             {
               "type": "null"
             }
-          ]
+          ],
+          "description": "Asset storage per robot, in bytes (decimal: 1 GB = 1,000,000,000). The org stores up to robots × this value in total."
         },
         "history_days": {
           "anyOf": [
@@ -101,7 +108,8 @@
             {
               "type": "null"
             }
-          ]
+          ],
+          "description": "Days the org's robot history is kept."
         },
         "audit_days": {
           "anyOf": [
@@ -113,7 +121,8 @@
             {
               "type": "null"
             }
-          ]
+          ],
+          "description": "Days the org's audit log is kept."
         }
       },
       "required": [
@@ -126,31 +135,39 @@
         "history_days",
         "audit_days"
       ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "What the plan allows. `null` means by contract."
     },
     "features": {
       "type": "object",
       "properties": {
         "app_mcp": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "An app's own MCP endpoint, for its app users."
         },
         "two_factor": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Two-factor sign-in for developers."
         },
         "require_two_factor": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "An owner may require two-factor sign-in for every developer of the org."
         },
         "app_oidc": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "An app may let its users sign in through an OpenID Connect identity provider."
         },
         "hosted_logo": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "An app's hosted pages show its logo and accent colour, not only its name."
         },
         "audit_export": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "The audit log can be exported as CSV."
         },
         "addons": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Add-ons can be bought on top of the plan."
         }
       },
       "required": [
@@ -162,7 +179,8 @@
         "audit_export",
         "addons"
       ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "What the plan unlocks."
     },
     "prices": {
       "anyOf": [
@@ -172,22 +190,26 @@
             "eur_month": {
               "type": "integer",
               "minimum": 0,
-              "maximum": 9007199254740991
+              "maximum": 9007199254740991,
+              "description": "Per month in euro cents, excluding VAT."
             },
             "usd_month": {
               "type": "integer",
               "minimum": 0,
-              "maximum": 9007199254740991
+              "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
+              "maximum": 9007199254740991,
+              "description": "Per year in euro cents, excluding VAT: twelve months less 15 %."
             },
             "usd_year": {
               "type": "integer",
               "minimum": 0,
-              "maximum": 9007199254740991
+              "maximum": 9007199254740991,
+              "description": "Per year in US dollar cents, excluding VAT: the yearly euro price × 1.15, rounded up to a whole dollar."
             }
           },
           "required": [
@@ -211,7 +233,8 @@
         "email",
         "priority",
         "named_contact"
-      ]
+      ],
+      "description": "The support that comes with the plan."
     }
   },
   "required": [

package/artifacts/schema/plan-change-keep.schema.json

@@ -8,7 +8,8 @@
         "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 robots that stay, by id. Every other robot is deleted when the change takes effect."
     },
     "apps": {
       "type": "array",
@@ -16,7 +17,8 @@
         "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 apps that stay, by id. Every other app is deleted when the change takes effect."
     },
     "app_users": {
       "type": "array",
@@ -24,7 +26,8 @@
         "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 app users that stay, by id, across every app. Every other app user is deleted when the change takes effect."
     },
     "developers": {
       "type": "array",
@@ -32,7 +35,8 @@
         "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 developers that stay, by user id, owners never among them: every owner stays. Every other developer is removed from the org when the change takes effect."
     }
   },
   "required": [

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

@@ -9,7 +9,8 @@
         "plus",
         "pro",
         "enterprise"
-      ]
+      ],
+      "description": "The lower plan to move to; `basic` cancels."
     },
     "keep": {
       "anyOf": [
@@ -22,7 +23,8 @@
                 "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 robots that stay, by id. Every other robot is deleted when the change takes effect."
             },
             "apps": {
               "type": "array",
@@ -30,7 +32,8 @@
                 "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 apps that stay, by id. Every other app is deleted when the change takes effect."
             },
             "app_users": {
               "type": "array",
@@ -38,7 +41,8 @@
                 "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 app users that stay, by id, across every app. Every other app user is deleted when the change takes effect."
             },
             "developers": {
               "type": "array",
@@ -46,7 +50,8 @@
                 "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 developers that stay, by user id, owners never among them: every owner stays. Every other developer is removed from the org when the change takes effect."
             }
           },
           "required": [
@@ -60,7 +65,8 @@
         {
           "type": "null"
         }
-      ]
+      ],
+      "description": "What stays. `null` when the org already fits the target plan, so nothing is deleted."
     }
   },
   "required": [

package/artifacts/schema/plan-features.schema.json

@@ -3,25 +3,32 @@
   "type": "object",
   "properties": {
     "app_mcp": {
-      "type": "boolean"
+      "type": "boolean",
+      "description": "An app's own MCP endpoint, for its app users."
     },
     "two_factor": {
-      "type": "boolean"
+      "type": "boolean",
+      "description": "Two-factor sign-in for developers."
     },
     "require_two_factor": {
-      "type": "boolean"
+      "type": "boolean",
+      "description": "An owner may require two-factor sign-in for every developer of the org."
     },
     "app_oidc": {
-      "type": "boolean"
+      "type": "boolean",
+      "description": "An app may let its users sign in through an OpenID Connect identity provider."
     },
     "hosted_logo": {
-      "type": "boolean"
+      "type": "boolean",
+      "description": "An app's hosted pages show its logo and accent colour, not only its name."
     },
     "audit_export": {
-      "type": "boolean"
+      "type": "boolean",
+      "description": "The audit log can be exported as CSV."
     },
     "addons": {
-      "type": "boolean"
+      "type": "boolean",
+      "description": "Add-ons can be bought on top of the plan."
     }
   },
   "required": [

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

@@ -11,17 +11,20 @@
         "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
+      "maximum": 9007199254740991,
+      "description": "How much of the limit the org uses now."
     },
     "max": {
       "type": "integer",
       "minimum": 0,
-      "maximum": 9007199254740991
+      "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",
@@ -30,7 +33,8 @@
         "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",
@@ -49,7 +53,8 @@
             {
               "type": "null"
             }
-          ]
+          ],
+          "description": "The cheapest higher plan that raises this limit, or `null` when none does."
         },
         "addon": {
           "anyOf": [
@@ -66,14 +71,16 @@
             {
               "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
+      "additionalProperties": false,
+      "description": "What would lift the limit."
     }
   },
   "required": [

package/artifacts/schema/plan-limits.schema.json

@@ -12,7 +12,8 @@
         {
           "type": "null"
         }
-      ]
+      ],
+      "description": "Developers, owners included, plus pending team invitations."
     },
     "robots": {
       "anyOf": [
@@ -24,7 +25,8 @@
         {
           "type": "null"
         }
-      ]
+      ],
+      "description": "Robots in the org."
     },
     "apps": {
       "anyOf": [
@@ -36,7 +38,8 @@
         {
           "type": "null"
         }
-      ]
+      ],
+      "description": "Apps in the org."
     },
     "app_users": {
       "anyOf": [
@@ -48,7 +51,8 @@
         {
           "type": "null"
         }
-      ]
+      ],
+      "description": "App users across every app of the org, plus pending app-user invitations."
     },
     "live_video_ms_per_month": {
       "anyOf": [
@@ -60,7 +64,8 @@
         {
           "type": "null"
         }
-      ]
+      ],
+      "description": "Live video watched by app users in one UTC calendar month, in milliseconds, across the org. Console sessions do not count."
     },
     "asset_bytes_per_robot": {
       "anyOf": [
@@ -72,7 +77,8 @@
         {
           "type": "null"
         }
-      ]
+      ],
+      "description": "Asset storage per robot, in bytes (decimal: 1 GB = 1,000,000,000). The org stores up to robots × this value in total."
     },
     "history_days": {
       "anyOf": [
@@ -84,7 +90,8 @@
         {
           "type": "null"
         }
-      ]
+      ],
+      "description": "Days the org's robot history is kept."
     },
     "audit_days": {
       "anyOf": [
@@ -96,7 +103,8 @@
         {
           "type": "null"
         }
-      ]
+      ],
+      "description": "Days the org's audit log is kept."
     }
   },
   "required": [

package/artifacts/schema/plan-overrides.schema.json

@@ -3,6 +3,7 @@
   "type": "object",
   "properties": {
     "seats": {
+      "description": "Replaces the plan's `seats`. `null` clears the override.",
       "anyOf": [
         {
           "type": "integer",
@@ -15,6 +16,7 @@
       ]
     },
     "robots": {
+      "description": "Replaces the plan's `robots`. `null` clears the override.",
       "anyOf": [
         {
           "type": "integer",
@@ -27,6 +29,7 @@
       ]
     },
     "apps": {
+      "description": "Replaces the plan's `apps`. `null` clears the override.",
       "anyOf": [
         {
           "type": "integer",
@@ -39,6 +42,7 @@
       ]
     },
     "app_users": {
+      "description": "Replaces the plan's `app_users`. `null` clears the override.",
       "anyOf": [
         {
           "type": "integer",
@@ -51,6 +55,7 @@
       ]
     },
     "live_video_ms_per_month": {
+      "description": "Replaces the plan's `live_video_ms_per_month`. `null` clears the override.",
       "anyOf": [
         {
           "type": "integer",
@@ -63,6 +68,7 @@
       ]
     },
     "asset_bytes_per_robot": {
+      "description": "Replaces the plan's `asset_bytes_per_robot`. `null` clears the override.",
       "anyOf": [
         {
           "type": "integer",
@@ -75,6 +81,7 @@
       ]
     },
     "history_days": {
+      "description": "Replaces the plan's `history_days`. `null` clears the override.",
       "anyOf": [
         {
           "type": "integer",
@@ -87,6 +94,7 @@
       ]
     },
     "audit_days": {
+      "description": "Replaces the plan's `audit_days`. `null` clears the override.",
       "anyOf": [
         {
           "type": "integer",

package/artifacts/schema/plan-prices.schema.json

@@ -5,22 +5,26 @@
     "eur_month": {
       "type": "integer",
       "minimum": 0,
-      "maximum": 9007199254740991
+      "maximum": 9007199254740991,
+      "description": "Per month in euro cents, excluding VAT."
     },
     "usd_month": {
       "type": "integer",
       "minimum": 0,
-      "maximum": 9007199254740991
+      "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
+      "maximum": 9007199254740991,
+      "description": "Per year in euro cents, excluding VAT: twelve months less 15 %."
     },
     "usd_year": {
       "type": "integer",
       "minimum": 0,
-      "maximum": 9007199254740991
+      "maximum": 9007199254740991,
+      "description": "Per year in US dollar cents, excluding VAT: the yearly euro price × 1.15, rounded up to a whole dollar."
     }
   },
   "required": [

package/artifacts/schema/plan-required-details.schema.json

@@ -12,7 +12,8 @@
         "hosted_logo",
         "audit_export",
         "addons"
-      ]
+      ],
+      "description": "The feature the action needs."
     },
     "plan": {
       "type": "string",
@@ -21,7 +22,8 @@
         "plus",
         "pro",
         "enterprise"
-      ]
+      ],
+      "description": "The org's current plan."
     },
     "required_plan": {
       "type": "string",
@@ -30,7 +32,8 @@
         "plus",
         "pro",
         "enterprise"
-      ]
+      ],
+      "description": "The cheapest plan that has the feature."
     }
   },
   "required": [

package/dist/errors.js

@@ -79,14 +79,20 @@ export const invalidCodeDetails = z.object({
  * that cannot buy add-ons has nothing in that field.
  */
 export const planLimitDetails = z.object({
-    limit: planLimitKey.exclude(['history_days', 'audit_days']),
-    used: z.number().int().nonnegative(),
-    max: z.number().int().nonnegative(),
-    plan: planId,
-    lifted_by: z.object({
-        plan: planId.nullable(),
-        addon: addonKey.nullable(),
+    limit: planLimitKey.exclude(['history_days', 'audit_days']).meta({ description: 'The limit the action would exceed.' }),
+    used: z.number().int().nonnegative().meta({ description: 'How much of the limit the org uses now.' }),
+    max: z.number().int().nonnegative().meta({
+        description: 'The limit. For `asset_bytes_per_robot`, the org\'s whole pool: robots × the plan\'s bytes per robot.',
     }),
+    plan: planId.meta({ description: 'The plan whose limit refused: the target plan while a move to a lower plan is pending.' }),
+    lifted_by: z
+        .object({
+        plan: planId.nullable().meta({ description: 'The cheapest higher plan that raises this limit, or `null` when none does.' }),
+        addon: addonKey.nullable().meta({
+            description: 'The add-on that raises this limit, when the org\'s plan can buy add-ons; otherwise `null`.',
+        }),
+    })
+        .meta({ description: 'What would lift the limit.' }),
 });
 /**
  * `planLimitDetails` plus the three numbers `assetStoreRefusedDetails`
@@ -119,13 +125,15 @@ export const assetPlanLimitDetails = planLimitDetails.extend({
 });
 /** The `details` of a `403 plan_required` refusal: the feature, the org's own plan, and the cheapest plan that has it (`requiredPlanFor`). */
 export const planRequiredDetails = z.object({
-    feature: planFeature,
-    plan: planId,
-    required_plan: planId,
+    feature: planFeature.meta({ description: 'The feature the action needs.' }),
+    plan: planId.meta({ description: 'The org\'s current plan.' }),
+    required_plan: planId.meta({ description: 'The cheapest plan that has the feature.' }),
 });
 /** The `details` of a `403 org_locked` refusal: why the org is locked, matching `orgLock.reason`. */
 export const orgLockedDetails = z.object({
-    reason: z.enum(['payment', 'migration']),
+    reason: z.enum(['payment', 'migration']).meta({
+        description: '`payment`: a payment is missing. `migration`: the org did not choose what stays when the beta ended.',
+    }),
 });
 /**
  * The codes in use today. The wire deliberately allows any string — this
@@ -958,8 +966,8 @@ export const ERROR_CODES = [
     // 2026-10-02 — plans (#103).
     /**
      * `409`: the action would push the org past one of its plan's limits —
-     * a seat, a robot, an app, an app user, this month's live video, or a
-     * robot's asset storage. Answered **before anything is written**, so a
+     * a seat, a robot, an app, an app user, this month's live video, or the
+     * org's asset storage pool (its robots × the plan's bytes per robot). Answered **before anything is written**, so a
      * refused create or invite never leaves a half-made row behind. `details`
      * is `planLimitDetails` (or `assetPlanLimitDetails` for an asset-storage
      * refusal): which limit, how much is used, the ceiling, the plan that
@@ -970,19 +978,21 @@ export const ERROR_CODES = [
      */
     'plan_limit',
     /**
-     * `403`: the feature the caller reached for is not on the org's plan — a
-     * two-factor requirement, an app's OIDC federation, a hosted logo, the
-     * audit export, or add-ons themselves. `details` is `planRequiredDetails`:
+     * `403`: the feature the caller reached for is not on the org's plan — an
+     * app's MCP endpoint, two-factor for a developer, a two-factor requirement
+     * for the org, an app's OIDC federation, a hosted logo, the audit export,
+     * or add-ons themselves. `details` is `planRequiredDetails`:
      * the feature, the org's own plan, and the cheapest plan that has it, so
      * the console can offer the upgrade in the same breath as the refusal.
      */
     'plan_required',
     /**
-     * `403`: the org is locked and may only move to Basic. `details` is
-     * `orgLockedDetails`, naming why — a failed payment, or the platform's own
-     * move off the beta. Distinct from `plan_required`, which is about a
-     * feature the plan never had; this is about an org that is not allowed to
-     * spend on any plan right now.
+     * `403`: the org is locked. Every sign-in and every token refresh is
+     * refused, except an owner's, so an owner can still sign in and settle
+     * it; the sign-in pages render this refusal. A bridge's `hello` is
+     * refused with this code as well. Nothing is deleted while an org is
+     * locked. `details` is `orgLockedDetails`, naming why — a missing
+     * payment, or the platform's own move off the beta.
      */
     'org_locked',
 ];