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

package/dist/plans.d.ts

@@ -5,8 +5,8 @@ import { z } from 'zod';
  *
  * Four plans, cheapest first: `basic` (free), `plus`, `pro` and
  * `enterprise` (sold by contract, never self-service — its limits and
- * features are the catalogue's ceiling, not a priced row). Add-ons exist on
- * `pro` only; see `ADDONS` and the `addons` feature.
+ * features are the catalogue's ceiling, not a priced row). Add-ons are
+ * bought on a plan with the `addons` feature; see `ADDONS`.
  */
 export declare const planId: z.ZodEnum<{
     basic: "basic";
@@ -55,7 +55,7 @@ export type PlanLimits = z.infer<typeof planLimits>;
  * may force it org-wide), `app_oidc` (an app may federate sign-in to an
  * external IdP), `hosted_logo` (a custom logo on the app's hosted pages),
  * `audit_export` (the audit log's CSV export) and `addons` (whether add-ons
- * may be bought at all — `pro` only).
+ * may be bought at all — `pro` and `enterprise`).
  */
 export declare const planFeature: z.ZodEnum<{
     require_two_factor: "require_two_factor";
@@ -134,9 +134,8 @@ export declare const planCatalogueEntry: z.ZodObject<{
 export type PlanCatalogueEntry = z.infer<typeof planCatalogueEntry>;
 /**
  * What can be bought on top of a plan, each raising exactly one
- * `planLimitKey` by `per_unit`. Exist on `pro` only: on any other plan an
- * org's add-on counts are zero, and a plan change away from `pro` resets
- * them to zero (the add-ons feature gate, `planFeature.addons`).
+ * `planLimitKey` by `per_unit`. Only a plan with the `addons` feature may
+ * buy them (`planFeature.addons`: `pro` and `enterprise`).
  */
 export declare const addonKey: z.ZodEnum<{
     apps: "apps";
@@ -217,12 +216,6 @@ export declare const planCurrency: z.ZodEnum<{
     usd: "usd";
 }>;
 export type PlanCurrency = z.infer<typeof planCurrency>;
-/**
- * How many units of each add-on an org has bought. Meaningful on `pro` only
- * — see `planFeature.addons` — and zero on every other plan: a plan change
- * away from `pro` resets every count here to zero rather than leaving them
- * stored and merely unread.
- */
 export declare const orgAddons: z.ZodObject<{
     seats: z.ZodNumber;
     robots: z.ZodNumber;
@@ -231,17 +224,6 @@ export declare const orgAddons: z.ZodObject<{
     live_video_packs: z.ZodNumber;
 }, z.core.$strip>;
 export type OrgAddons = z.infer<typeof orgAddons>;
-/**
- * What the org is using right now, counted the way each limit refuses
- * against: `seats` is developers, owners included, plus pending team
- * invitations; `app_users` is app users of every app plus pending app-user
- * invitations; `live_video_ms_this_month` is this UTC calendar month's
- * app-attributed live video only — a console session never counts and is
- * never ended for it; `asset_bytes` is the sum of every robot's stored
- * assets across the whole org. Read fresh on every call, the same discipline
- * `GET /api/org/quotas` already keeps, so a number here is never one call
- * behind the limit it is compared against.
- */
 export declare const orgPlanUsage: z.ZodObject<{
     seats: z.ZodNumber;
     robots: z.ZodNumber;
@@ -328,10 +310,11 @@ export declare const pendingPlanChange: z.ZodObject<{
 }, z.core.$strip>;
 export type PendingPlanChange = z.infer<typeof pendingPlanChange>;
 /**
- * An org restricted, while locked, to moving straight to Basic — narrower
- * still than the already-downward-only `PUT /api/org/plan/change`. `payment`
- * is a failed charge; `migration` is the platform's own move off the beta.
- * Either way the only plan a developer may choose while locked is Basic —
+ * An org that is locked: every sign-in and token refresh except an owner's
+ * answers `403 org_locked`, and its bridges are refused; nothing is
+ * deleted. `payment` is a missing payment; `migration` is the platform's
+ * own move off the beta. Either way the only plan an owner may choose
+ * while locked is Basic —
  * see `target_state_conflict` with rule `locked_basic_only` on
  * `PUT /api/org/plan/change`; a choice made while locked takes effect at
  * once rather than waiting for the billing period to turn over.
@@ -482,12 +465,11 @@ export declare const planOverrides: z.ZodObject<{
 }, z.core.$strict>;
 export type PlanOverrides = z.infer<typeof planOverrides>;
 /**
- * What the operator sends on `PATCH /api/admin/orgs/:id/plan`. Every field
- * is optional because this one route carries every shape of change an
- * operator makes to an org's plan — switching it, adding or removing
- * add-ons, overriding a limit, changing the billing currency, or moving the
- * period boundary — and a request that touched all of them at once would be
- * no easier to audit than four small ones in its place. `addons` is a
+ * What the operator sends on `PATCH /api/admin/orgs/:id/plan`. `plan` is
+ * required: every request names the plan the org ends up on, even when only
+ * an add-on, an override, the currency or the period end changes. Every
+ * other field is optional, so one route carries every shape of change an
+ * operator makes to an org's plan. `addons` is a
  * partial `orgAddons`: only the counts named change, the rest are left as
  * they are. `overrides` follows `planOverrides`: a key present with `null`
  * clears that override.

package/dist/plans.js

@@ -5,8 +5,8 @@ import { z } from 'zod';
  *
  * Four plans, cheapest first: `basic` (free), `plus`, `pro` and
  * `enterprise` (sold by contract, never self-service — its limits and
- * features are the catalogue's ceiling, not a priced row). Add-ons exist on
- * `pro` only; see `ADDONS` and the `addons` feature.
+ * features are the catalogue's ceiling, not a priced row). Add-ons are
+ * bought on a plan with the `addons` feature; see `ADDONS`.
  */
 export const planId = z.enum(['basic', 'plus', 'pro', 'enterprise']);
 /**
@@ -34,14 +34,18 @@ export const planLimitKey = z.enum([
 /** `null` = by contract (Enterprise) or unlimited; see `orgPlan.limits`. */
 const limit = z.number().int().positive().nullable();
 export const planLimits = z.object({
-    seats: limit,
-    robots: limit,
-    apps: limit,
-    app_users: limit,
-    live_video_ms_per_month: limit,
-    asset_bytes_per_robot: limit,
-    history_days: limit,
-    audit_days: limit,
+    seats: limit.meta({ description: 'Developers, owners included, plus pending team invitations.' }),
+    robots: limit.meta({ description: 'Robots in the org.' }),
+    apps: limit.meta({ description: 'Apps in the org.' }),
+    app_users: limit.meta({ description: 'App users across every app of the org, plus pending app-user invitations.' }),
+    live_video_ms_per_month: limit.meta({
+        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: limit.meta({
+        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: limit.meta({ description: 'Days the org\'s robot history is kept.' }),
+    audit_days: limit.meta({ description: 'Days the org\'s audit log is kept.' }),
 });
 /**
  * What a plan unlocks beyond a number: `app_mcp` (the app's MCP server),
@@ -49,39 +53,47 @@ export const planLimits = z.object({
  * may force it org-wide), `app_oidc` (an app may federate sign-in to an
  * external IdP), `hosted_logo` (a custom logo on the app's hosted pages),
  * `audit_export` (the audit log's CSV export) and `addons` (whether add-ons
- * may be bought at all — `pro` only).
+ * may be bought at all — `pro` and `enterprise`).
  */
 export const planFeature = z.enum(['app_mcp', 'two_factor', 'require_two_factor', 'app_oidc', 'hosted_logo', 'audit_export', 'addons']);
-export const planFeatures = z.object(Object.fromEntries(planFeature.options.map((f) => [f, z.boolean()])));
+const FEATURE_DESCRIPTIONS = {
+    app_mcp: 'An app\'s own MCP endpoint, for its app users.',
+    two_factor: 'Two-factor sign-in for developers.',
+    require_two_factor: 'An owner may require two-factor sign-in for every developer of the org.',
+    app_oidc: 'An app may let its users sign in through an OpenID Connect identity provider.',
+    hosted_logo: 'An app\'s hosted pages show its logo and accent colour, not only its name.',
+    audit_export: 'The audit log can be exported as CSV.',
+    addons: 'Add-ons can be bought on top of the plan.',
+};
+export const planFeatures = z.object(Object.fromEntries(planFeature.options.map((f) => [f, z.boolean().meta({ description: FEATURE_DESCRIPTIONS[f] })])));
 /** Integer cents, excluding VAT. */
 const cents = z.number().int().nonnegative();
 export const planPrices = z.object({
-    eur_month: cents,
-    usd_month: cents,
-    eur_year: cents,
-    usd_year: cents,
+    eur_month: cents.meta({ description: 'Per month in euro cents, excluding VAT.' }),
+    usd_month: cents.meta({ description: 'Per month in US dollar cents, excluding VAT: the euro price × 1.15, rounded up to a whole dollar.' }),
+    eur_year: cents.meta({ description: 'Per year in euro cents, excluding VAT: twelve months less 15 %.' }),
+    usd_year: cents.meta({ description: 'Per year in US dollar cents, excluding VAT: the yearly euro price × 1.15, rounded up to a whole dollar.' }),
 });
 export const planSupport = z.enum(['community', 'email', 'priority', 'named_contact']);
 export const planCatalogueEntry = z.object({
-    id: planId,
+    id: planId.meta({ description: 'The plan.' }),
     name: z.string().min(1).meta({ description: 'The plan\'s display name: Basic, Plus, Pro or Enterprise.' }),
-    limits: planLimits,
-    features: planFeatures,
+    limits: planLimits.meta({ description: 'What the plan allows. `null` means by contract.' }),
+    features: planFeatures.meta({ description: 'What the plan unlocks.' }),
     prices: planPrices.nullable().meta({ description: '`null` for Enterprise: sold by contract, on request.' }),
-    support: planSupport,
+    support: planSupport.meta({ description: 'The support that comes with the plan.' }),
 });
 /**
  * What can be bought on top of a plan, each raising exactly one
- * `planLimitKey` by `per_unit`. Exist on `pro` only: on any other plan an
- * org's add-on counts are zero, and a plan change away from `pro` resets
- * them to zero (the add-ons feature gate, `planFeature.addons`).
+ * `planLimitKey` by `per_unit`. Only a plan with the `addons` feature may
+ * buy them (`planFeature.addons`: `pro` and `enterprise`).
  */
 export const addonKey = z.enum(['seats', 'robots', 'apps', 'app_user_packs', 'live_video_packs']);
 export const addonCatalogueEntry = z.object({
-    key: addonKey,
+    key: addonKey.meta({ description: 'The add-on.' }),
     raises: planLimitKey.meta({ description: 'The plan limit this add-on raises.' }),
     per_unit: z.number().int().positive().meta({ description: 'How much one unit of this add-on raises `raises` by.' }),
-    prices: planPrices,
+    prices: planPrices.meta({ description: 'The price of one unit.' }),
 });
 /**
  * **No floating-point money, anywhere.** `eurCents * 1.15` would introduce
@@ -273,17 +285,17 @@ export function nextPlanRaising(plan, key) {
 /** What an org is billed in. The catalogue's prices are fixed in both; this picks which one an invoice reads in. */
 export const planCurrency = z.enum(['eur', 'usd']);
 /**
- * How many units of each add-on an org has bought. Meaningful on `pro` only
- * — see `planFeature.addons` — and zero on every other plan: a plan change
- * away from `pro` resets every count here to zero rather than leaving them
- * stored and merely unread.
+ * How many units of each add-on an org has bought. Only a plan with the
+ * `addons` feature may buy them (see `planFeature.addons`); `orgPlan.limits`
+ * already includes what they add.
  */
+const addonCount = z.number().int().nonnegative();
 export const orgAddons = z.object({
-    seats: z.number().int().nonnegative(),
-    robots: z.number().int().nonnegative(),
-    apps: z.number().int().nonnegative(),
-    app_user_packs: z.number().int().nonnegative(),
-    live_video_packs: z.number().int().nonnegative(),
+    seats: addonCount.meta({ description: 'Extra developer seats, one each.' }),
+    robots: addonCount.meta({ description: 'Extra robots, one each.' }),
+    apps: addonCount.meta({ description: 'Extra apps, one each.' }),
+    app_user_packs: addonCount.meta({ description: 'Packs of five extra app users.' }),
+    live_video_packs: addonCount.meta({ description: 'Packs of 250 extra hours of app-user live video per month.' }),
 });
 /**
  * What the org is using right now, counted the way each limit refuses
@@ -296,13 +308,16 @@ export const orgAddons = z.object({
  * `GET /api/org/quotas` already keeps, so a number here is never one call
  * behind the limit it is compared against.
  */
+const usageCount = z.number().int().nonnegative();
 export const orgPlanUsage = z.object({
-    seats: z.number().int().nonnegative(),
-    robots: z.number().int().nonnegative(),
-    apps: z.number().int().nonnegative(),
-    app_users: z.number().int().nonnegative(),
-    live_video_ms_this_month: z.number().int().nonnegative(),
-    asset_bytes: z.number().int().nonnegative(),
+    seats: usageCount.meta({ description: 'Developers, owners included, plus pending team invitations.' }),
+    robots: usageCount.meta({ description: 'Robots in the org.' }),
+    apps: usageCount.meta({ description: 'Apps in the org.' }),
+    app_users: usageCount.meta({ description: 'App users across every app, plus pending app-user invitations.' }),
+    live_video_ms_this_month: usageCount.meta({
+        description: 'Live video watched by app users in the current UTC calendar month, in milliseconds. Console sessions do not count.',
+    }),
+    asset_bytes: usageCount.meta({ description: 'Bytes the assets of every robot of the org occupy, together.' }),
 });
 /**
  * What a downward plan change keeps, by id, when the target plan cannot hold
@@ -315,10 +330,15 @@ export const orgPlanUsage = z.object({
  * all — is refused at the door rather than silently ignored.
  */
 export const planChangeKeep = z.object({
-    robots: z.array(z.uuid()),
-    apps: z.array(z.uuid()),
-    app_users: z.array(z.uuid()),
-    developers: z.array(z.uuid()),
+    robots: z.array(z.uuid()).meta({ description: 'The robots that stay, by id. Every other robot is deleted when the change takes effect.' }),
+    apps: z.array(z.uuid()).meta({ description: 'The apps that stay, by id. Every other app is deleted when the change takes effect.' }),
+    app_users: z.array(z.uuid()).meta({
+        description: 'The app users that stay, by id, across every app. Every other app user is deleted when the change takes effect.',
+    }),
+    developers: z.array(z.uuid()).meta({
+        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.',
+    }),
 }).strict();
 /**
  * Why a change is pending. `downgrade` and `cancel` (to Basic) are a
@@ -349,26 +369,35 @@ export const planChangeReason = z.enum(['downgrade', 'cancel', 'migration', 'loc
  * lands.
  */
 export const pendingPlanChange = z.object({
-    target_plan: planId,
-    reason: planChangeReason,
-    effective_at: z.iso.datetime().nullable(),
-    keep: planChangeKeep.nullable(),
-    history_days_after: z.number().int().positive(),
-    chosen_by: z.uuid(),
-    chosen_at: z.iso.datetime(),
+    target_plan: planId.meta({ description: 'The plan the org moves to.' }),
+    reason: planChangeReason.meta({ description: 'Why the change is pending: `downgrade`, `cancel`, `migration` or `lock`.' }),
+    effective_at: z.iso.datetime().nullable().meta({
+        description: 'When the change takes effect. `null` only for a move off the beta whose date is not set yet.',
+    }),
+    keep: planChangeKeep.nullable().meta({
+        description: 'What stays. `null` when the org already fits the target plan and nothing is deleted.',
+    }),
+    history_days_after: z.number().int().positive().meta({
+        description: 'Days of history and audit log the org keeps on the target plan.',
+    }),
+    chosen_by: z.uuid().meta({ description: 'The user id of the owner who chose the change, or the nil UUID when Fleetless queued it.' }),
+    chosen_at: z.iso.datetime().meta({ description: 'When the change was chosen.' }),
 });
 /**
- * An org restricted, while locked, to moving straight to Basic — narrower
- * still than the already-downward-only `PUT /api/org/plan/change`. `payment`
- * is a failed charge; `migration` is the platform's own move off the beta.
- * Either way the only plan a developer may choose while locked is Basic —
+ * An org that is locked: every sign-in and token refresh except an owner's
+ * answers `403 org_locked`, and its bridges are refused; nothing is
+ * deleted. `payment` is a missing payment; `migration` is the platform's
+ * own move off the beta. Either way the only plan an owner may choose
+ * while locked is Basic —
  * see `target_state_conflict` with rule `locked_basic_only` on
  * `PUT /api/org/plan/change`; a choice made while locked takes effect at
  * once rather than waiting for the billing period to turn over.
  */
 export const orgLock = z.object({
-    reason: z.enum(['payment', 'migration']),
-    since: z.iso.datetime(),
+    reason: z.enum(['payment', 'migration']).meta({
+        description: '`payment`: a payment is missing. `migration`: the org did not choose what stays when the beta ended.',
+    }),
+    since: z.iso.datetime().meta({ description: 'When the org was locked.' }),
 });
 /**
  * **The one read everything about an org's plan comes from**: the console's
@@ -381,23 +410,33 @@ export const orgLock = z.object({
  * it still has to choose one.
  */
 export const orgPlan = z.object({
-    plan: planId,
-    currency: planCurrency,
+    plan: planId.meta({ description: 'The org\'s current plan.' }),
+    currency: planCurrency.meta({ description: 'The currency the org\'s prices are shown and billed in.' }),
     period_ends_at: z.iso.datetime().meta({
         description: "The end of the organization's current billing period; while no payment period exists yet, the end of the current UTC calendar " +
             'month. A pending downward plan change normally takes effect at this exact instant — except one chosen while the org was locked, ' +
             "which lands at once, and the platform's own move off the beta, which lands at its switch date instead.",
     }),
-    addons: orgAddons,
-    limits: planLimits,
-    features: planFeatures,
-    usage: orgPlanUsage,
-    pending_change: pendingPlanChange.nullable(),
-    lock: orgLock.nullable(),
-    switch: z.object({
-        at: z.iso.datetime().nullable(),
-        needs_choice: z.boolean(),
-    }).nullable(),
+    addons: orgAddons.meta({ description: 'The add-ons the org has bought. All zero on a plan without the `addons` feature.' }),
+    limits: planLimits.meta({
+        description: 'The org\'s effective limits: the plan\'s, raised by its add-ons, or an operator\'s override in their place. `null` means ' +
+            'unlimited for a count, and 90 days for `history_days` and `audit_days`.',
+    }),
+    features: planFeatures.meta({ description: 'What the org\'s plan unlocks.' }),
+    usage: orgPlanUsage.meta({ description: 'What the org uses now, counted the way each limit counts it.' }),
+    pending_change: pendingPlanChange.nullable().meta({ description: 'A move to a lower plan that has not taken effect yet, or `null`.' }),
+    lock: orgLock.nullable().meta({ description: 'Why and since when the org is locked, or `null` when it is not.' }),
+    switch: z
+        .object({
+        at: z.iso.datetime().nullable().meta({
+            description: 'When the org moves from the beta onto its plan. `null` while the date is not set.',
+        }),
+        needs_choice: z.boolean().meta({
+            description: 'Whether the org uses more than Basic allows, so an owner has to choose what stays before `at`.',
+        }),
+    })
+        .nullable()
+        .meta({ description: 'Set only while the org is still on the beta; `null` for every other org.' }),
 });
 /**
  * What a developer may ask for on `PUT /api/org/plan/change` — **a downward
@@ -410,8 +449,10 @@ export const orgPlan = z.object({
  * typo that `.strict()` would otherwise swallow in silence.
  */
 export const planChangeRequest = z.object({
-    target_plan: planId,
-    keep: planChangeKeep.nullable(),
+    target_plan: planId.meta({ description: 'The lower plan to move to; `basic` cancels.' }),
+    keep: planChangeKeep.nullable().meta({
+        description: 'What stays. `null` when the org already fits the target plan, so nothing is deleted.',
+    }),
 }).strict();
 /**
  * An operator's per-org replacement for one or more catalogue limits —
@@ -421,22 +462,26 @@ export const planChangeRequest = z.object({
  * plan's own number, which is why every value is nullable as well as
  * optional — omitted and `null` are two different instructions.
  */
-export const planOverrides = z.object(Object.fromEntries(planLimitKey.options.map((k) => [k, limit.optional()]))).strict();
+export const planOverrides = z.object(Object.fromEntries(planLimitKey.options.map((k) => [
+    k,
+    limit.optional().meta({ description: `Replaces the plan's \`${k}\`. \`null\` clears the override.` }),
+]))).strict();
 /**
- * What the operator sends on `PATCH /api/admin/orgs/:id/plan`. Every field
- * is optional because this one route carries every shape of change an
- * operator makes to an org's plan — switching it, adding or removing
- * add-ons, overriding a limit, changing the billing currency, or moving the
- * period boundary — and a request that touched all of them at once would be
- * no easier to audit than four small ones in its place. `addons` is a
+ * What the operator sends on `PATCH /api/admin/orgs/:id/plan`. `plan` is
+ * required: every request names the plan the org ends up on, even when only
+ * an add-on, an override, the currency or the period end changes. Every
+ * other field is optional, so one route carries every shape of change an
+ * operator makes to an org's plan. `addons` is a
  * partial `orgAddons`: only the counts named change, the rest are left as
  * they are. `overrides` follows `planOverrides`: a key present with `null`
  * clears that override.
  */
 export const adminPlanChangeRequest = z.object({
-    plan: planId,
-    addons: orgAddons.partial().strict().optional(),
-    overrides: planOverrides.optional(),
-    currency: planCurrency.optional(),
-    period_ends_at: z.iso.datetime().nullable().optional(),
+    plan: planId.meta({ description: 'The plan the org is on after this request.' }),
+    addons: orgAddons.partial().strict().optional().meta({ description: 'Add-on counts to set. Counts not named stay as they are.' }),
+    overrides: planOverrides.optional().meta({ description: 'Limits to override. `null` clears an override.' }),
+    currency: planCurrency.optional().meta({ description: 'The currency the org is billed in.' }),
+    period_ends_at: z.iso.datetime().nullable().optional().meta({
+        description: 'The end of the org\'s billing period. `null` falls back to the end of the current UTC month.',
+    }),
 }).strict();

package/dist/routes.js

@@ -2840,10 +2840,11 @@ export const ROUTES = [
         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.',
+            'reads exactly like one nobody opened. An unknown `:id` is the same `404`. Applies at once, never queued as a `pending_change`, ' +
+            'and only when the org\'s current usage fits the result: `409 plan_limit` when a lower plan, a lowered override or a removed add-on ' +
+            'would leave the org over a limit — the operator never deletes an org\'s things, only the owner\'s own choice does. On success it ' +
+            'also withdraws any `pending_change`, ends a beta org\'s wait for the switch and lifts a lock. Audited as `org.plan_changed` with ' +
+            'the `fleetless` actor, never a developer\'s — the row names what an operator did, not who in the org asked for it.',
     },
     /* ------------------------------------------------- assets (robot upload) */
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fleetless/contracts",
-  "version": "6.1.0-next.1",
+  "version": "6.1.0-next.2",
   "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",