@fleetless/contracts 6.0.0 → 6.1.0-next.2

package/dist/plans.js

@@ -0,0 +1,487 @@
+// SPDX-License-Identifier: Apache-2.0
+import { z } from 'zod';
+/**
+ * The plan catalogue.
+ *
+ * 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 are
+ * bought on a plan with the `addons` feature; see `ADDONS`.
+ */
+export const planId = z.enum(['basic', 'plus', 'pro', 'enterprise']);
+/**
+ * Cheapest first. `requiredPlanFor` and `nextPlanRaising` both read "higher"
+ * and "lower" from this order, so a plan's position here — not its name — is
+ * what decides whether a change is an upgrade or a downgrade.
+ */
+export const PLAN_ORDER = ['basic', 'plus', 'pro', 'enterprise'];
+/**
+ * The limits a plan ties a number to. `history_days` and `audit_days` are
+ * not refused against — they size a retention window, not a quota that an
+ * action can exceed — but they share this vocabulary because they are read
+ * off the same catalogue row.
+ */
+export const planLimitKey = z.enum([
+    'seats',
+    'robots',
+    'apps',
+    'app_users',
+    'live_video_ms_per_month',
+    'asset_bytes_per_robot',
+    'history_days',
+    'audit_days',
+]);
+/** `null` = by contract (Enterprise) or unlimited; see `orgPlan.limits`. */
+const limit = z.number().int().positive().nullable();
+export const planLimits = z.object({
+    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),
+ * `two_factor` (a developer may turn it on), `require_two_factor` (an owner
+ * 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` and `enterprise`).
+ */
+export const planFeature = z.enum(['app_mcp', 'two_factor', 'require_two_factor', 'app_oidc', 'hosted_logo', 'audit_export', 'addons']);
+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.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.meta({ description: 'The plan.' }),
+    name: z.string().min(1).meta({ description: 'The plan\'s display name: Basic, Plus, Pro or Enterprise.' }),
+    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.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`. 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.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.meta({ description: 'The price of one unit.' }),
+});
+/**
+ * **No floating-point money, anywhere.** `eurCents * 1.15` would introduce
+ * the fraction of a cent that floating point cannot hold exactly, so the
+ * conversion is integer arithmetic throughout: scale by 115, add 9_999 to
+ * round the result up to the next whole 10_000 (i.e. the next whole dollar)
+ * and only then divide back down. Rounds *up*, never to nearest: a plan that
+ * reads cheaper in dollars than its true euro equivalent is the error this
+ * guards against, not the one it risks.
+ */
+export function usdCentsFromEurCents(eurCents) {
+    return Math.floor((eurCents * 115 + 9_999) / 10_000) * 100;
+}
+/** Yearly is twelve months at 15% off, rounded to the nearest cent. */
+export function yearlyEurCents(monthEurCents) {
+    return Math.round((monthEurCents * 12 * 85) / 100);
+}
+/**
+ * The catalogue writes every price through this one function, from the
+ * monthly EUR cents alone — never as the other three numbers as literals —
+ * so the USD and yearly rules can only ever be applied once, here.
+ */
+export function pricesFromEurMonth(eurMonthCents) {
+    const eurYear = yearlyEurCents(eurMonthCents);
+    return {
+        eur_month: eurMonthCents,
+        usd_month: usdCentsFromEurCents(eurMonthCents),
+        eur_year: eurYear,
+        usd_year: usdCentsFromEurCents(eurYear),
+    };
+}
+/**
+ * The catalogue, exactly as the decision table (2026-09-30) states it.
+ * Live video is in milliseconds, asset storage in decimal bytes per robot;
+ * Enterprise's limits and features are `null` / `true` throughout because
+ * they are set by contract, not read off this table.
+ */
+export const PLANS = {
+    basic: {
+        id: 'basic',
+        name: 'Basic',
+        limits: {
+            seats: 1,
+            robots: 1,
+            apps: 1,
+            app_users: 10,
+            live_video_ms_per_month: 36_000_000,
+            asset_bytes_per_robot: 1_000_000_000,
+            history_days: 7,
+            audit_days: 7,
+        },
+        features: {
+            app_mcp: false,
+            two_factor: false,
+            require_two_factor: false,
+            app_oidc: false,
+            hosted_logo: false,
+            audit_export: false,
+            addons: false,
+        },
+        prices: pricesFromEurMonth(0),
+        support: 'community',
+    },
+    plus: {
+        id: 'plus',
+        name: 'Plus',
+        limits: {
+            seats: 3,
+            robots: 3,
+            apps: 3,
+            app_users: 25,
+            live_video_ms_per_month: 360_000_000,
+            asset_bytes_per_robot: 2_000_000_000,
+            history_days: 30,
+            audit_days: 30,
+        },
+        features: {
+            app_mcp: true,
+            two_factor: true,
+            require_two_factor: false,
+            app_oidc: true,
+            hosted_logo: true,
+            audit_export: false,
+            addons: false,
+        },
+        prices: pricesFromEurMonth(2900),
+        support: 'email',
+    },
+    pro: {
+        id: 'pro',
+        name: 'Pro',
+        limits: {
+            seats: 5,
+            robots: 5,
+            apps: 5,
+            app_users: 50,
+            live_video_ms_per_month: 900_000_000,
+            asset_bytes_per_robot: 3_000_000_000,
+            history_days: 90,
+            audit_days: 90,
+        },
+        features: {
+            app_mcp: true,
+            two_factor: true,
+            require_two_factor: true,
+            app_oidc: true,
+            hosted_logo: true,
+            audit_export: true,
+            addons: true,
+        },
+        prices: pricesFromEurMonth(14900),
+        support: 'priority',
+    },
+    enterprise: {
+        id: 'enterprise',
+        name: 'Enterprise',
+        limits: {
+            seats: null,
+            robots: null,
+            apps: null,
+            app_users: null,
+            live_video_ms_per_month: null,
+            asset_bytes_per_robot: null,
+            history_days: null,
+            audit_days: null,
+        },
+        features: {
+            app_mcp: true,
+            two_factor: true,
+            require_two_factor: true,
+            app_oidc: true,
+            hosted_logo: true,
+            audit_export: true,
+            addons: true,
+        },
+        prices: null,
+        support: 'named_contact',
+    },
+};
+/**
+ * The add-on catalogue. Every price goes through `pricesFromEurMonth`, same
+ * discipline as `PLANS`.
+ */
+export const ADDONS = {
+    seats: { key: 'seats', raises: 'seats', per_unit: 1, prices: pricesFromEurMonth(900) },
+    robots: { key: 'robots', raises: 'robots', per_unit: 1, prices: pricesFromEurMonth(1900) },
+    apps: { key: 'apps', raises: 'apps', per_unit: 1, prices: pricesFromEurMonth(900) },
+    app_user_packs: { key: 'app_user_packs', raises: 'app_users', per_unit: 5, prices: pricesFromEurMonth(1000) },
+    live_video_packs: { key: 'live_video_packs', raises: 'live_video_ms_per_month', per_unit: 900_000_000, prices: pricesFromEurMonth(900) },
+};
+/** The cheapest plan that has the feature. */
+export function requiredPlanFor(feature) {
+    for (const plan of PLAN_ORDER) {
+        if (PLANS[plan].features[feature])
+            return plan;
+    }
+    // Every feature is true on `enterprise`, the last entry in `PLAN_ORDER`, so
+    // this is unreachable — kept as a defined return rather than a non-null
+    // assertion at the call site.
+    return PLAN_ORDER[PLAN_ORDER.length - 1];
+}
+/**
+ * The cheapest plan above `plan` whose catalogue limit for `key` is higher
+ * than `plan`'s own (`null` counts as higher, since it means unlimited);
+ * `null` when no plan above it raises the limit any further.
+ */
+export function nextPlanRaising(plan, key) {
+    const at = PLAN_ORDER.indexOf(plan);
+    const current = PLANS[plan].limits[key];
+    if (current === null)
+        return null; // already unlimited, nothing raises it further
+    for (let i = at + 1; i < PLAN_ORDER.length; i++) {
+        const candidate = PLAN_ORDER[i];
+        const candidateLimit = PLANS[candidate].limits[key];
+        if (candidateLimit === null || candidateLimit > current)
+            return candidate;
+    }
+    return null;
+}
+/*
+ * ---------------------------------------------------------------------------
+ * The organization's plan (2026-10-02, fleetless/fleetless#103).
+ *
+ * Everything above is the catalogue: the same four rows for every org. What
+ * follows is one org's position in it — what it bought, what it is using,
+ * and the change it has queued but not yet crossed into.
+ * ---------------------------------------------------------------------------
+ */
+/** 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. 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: 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
+ * 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.
+ */
+const usageCount = z.number().int().nonnegative();
+export const orgPlanUsage = z.object({
+    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
+ * everything the org has today. `owners` is deliberately not a field: an
+ * owner is never a candidate for deletion and always stays, so a chooser
+ * cannot even name one here — but an owner still counts against the target
+ * plan's `seats`, and if the owners alone already exceed it the change is
+ * refused `409 plan_limit` naming `seats`, before anything else about the
+ * choice is even considered. `.strict()` so an extra key — `owners` most of
+ * all — is refused at the door rather than silently ignored.
+ */
+export const planChangeKeep = z.object({
+    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
+ * developer's own choice — `PUT /api/org/plan/change` only ever moves an org
+ * down; an upgrade or an add-on needs payment this route does not collect,
+ * and today goes through a Feedback request that Fleetless applies through
+ * the admin route. `migration` is a plan the platform is moving every org on
+ * the beta through; `lock` is a change the platform queued because the org
+ * is locked (see `orgLock`) and must land on Basic.
+ */
+export const planChangeReason = z.enum(['downgrade', 'cancel', 'migration', 'lock']);
+/**
+ * A downward plan change the org has chosen, or been queued for by the
+ * platform, not yet in effect. `effective_at` is normally
+ * `orgPlan.period_ends_at`, so the org keeps full use of what it has until
+ * the billing period actually turns over — except a choice made while the
+ * org was locked, which takes effect at once, and a `migration`, which takes
+ * effect at the platform's switch date instead; it is `null` only while that
+ * date is not yet set. `keep` is `null` when the org's usage already fits
+ * the target plan outright and nothing is deleted; otherwise it is exactly
+ * what the confirmation counted — anything created while the choice is still
+ * pending is checked against the target plan too and, passing, is folded
+ * into `keep`, so what lands at `effective_at` is never a surprise. A later
+ * `PUT /api/org/plan/change` replaces a still-pending choice outright;
+ * `DELETE` withdraws it and leaves the org on its current plan.
+ * `history_days_after` is what the confirmation announces to whoever chose
+ * it, so the warning they read before confirming is the same number that
+ * lands.
+ */
+export const pendingPlanChange = z.object({
+    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 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']).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
+ * Plan & billing page, its usage and limit gauges, every upgrade prompt and
+ * every gate a feature check renders. `limits` is the *effective* ceiling —
+ * the catalogue row plus `addons`, or an operator's `overrides` in place of
+ * either — so a consumer never has to recompute it from the catalogue and
+ * the add-on counts itself. `switch` is set only for an organization still
+ * on the beta and carries the date its plan changes on its own, and whether
+ * it still has to choose one.
+ */
+export const orgPlan = z.object({
+    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.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
+ * move only**: a lower plan, or Basic as a cancellation. An upgrade or an
+ * add-on needs payment this route does not collect, and is not reachable
+ * through it at all today; it goes through a Feedback request that Fleetless
+ * applies through the admin route instead. `.strict()` for the same reason
+ * `planChangeKeep` is: a caller cannot send a field this shape does not
+ * name, `keep` included, and an owner cannot be smuggled into it through a
+ * typo that `.strict()` would otherwise swallow in silence.
+ */
+export const planChangeRequest = z.object({
+    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 —
+ * Enterprise's contracted numbers, most of all, which exist nowhere else.
+ * Every key is optional, so an operator sets only what differs from the
+ * plan; a key present with `null` clears an earlier override back to the
+ * 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().meta({ description: `Replaces the plan's \`${k}\`. \`null\` clears the override.` }),
+]))).strict();
+/**
+ * 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.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/realtime.d.ts

@@ -263,6 +263,7 @@ export declare const liveSessionEndReason: z.ZodEnum<{
     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";
@@ -294,6 +295,7 @@ export declare const liveSessionEvent: z.ZodObject<{
         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/realtime.js

@@ -292,6 +292,12 @@ export const liveSessionEndReason = z.enum([
     'expired',
     /** The robot was deleted out from under the session. */
     'robot_deleted',
+    /**
+     * The organization's live video for app users reached its plan's monthly
+     * limit (2026-10-02, fleetless/fleetless#103); `detail` carries the
+     * sentence the viewer shows.
+     */
+    'plan_limit',
     /**
      * The cloud ended it and cannot say which of the above applied. **Kept
      * deliberately**: a channel that cannot say "I do not know" will say

package/dist/routes.d.ts

@@ -30,7 +30,11 @@ import type { ZodType } from 'zod';
 import type { ErrorCode } from './errors.js';
 export type RouteMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
 export type RouteAudience = 'developer' | 'client' | 'internal';
-export type RouteAuth = 'developer' | 'developer_or_client' | 'none' | 'robot_upload' | 'in_handler';
+/**
+ * `ops` (2026-10-02, fleetless/fleetless#103): a bearer token the operator
+ * holds (`OPS_API_TOKEN`); never reachable through a public host.
+ */
+export type RouteAuth = 'developer' | 'developer_or_client' | 'none' | 'robot_upload' | 'in_handler' | 'ops';
 export type RouteTransport = 'http' | 'websocket';
 export type RouteSection = 'health' | 'developer-auth' | 'client-auth' | 'org' | 'users' | 'apps' | 'robots' | 'config' | 'alerts' | 'commands' | 'cameras' | 'assets' | 'mcp' | 'transports';
 export interface RouteParam {

package/dist/routes.js

@@ -11,6 +11,7 @@ import { acceptTeamInviteRequest, authMeResponse, createPasskeyRequest, createPa
 import { jobRunListResponse, jobRunQuery, jobRunSummary, jobRunSummaryQuery } from './jobs.js';
 import { MCP_APP_PATHS, mcpRobotDatasheet, mcpRolePreviewResponse } from './mcp.js';
 import { authorizationServerMetadata, dynamicClientRegistrationRequest, dynamicClientRegistrationResponse, oauthAuthorizeQuery, oauthRedirectResponse, oauthTokenRequest, oauthTokenResponse, protectedResourceMetadata, } from './oauth.js';
+import { adminPlanChangeRequest, orgPlan, planChangeRequest } from './plans.js';
 import { cameraListResponse, cancelRequest, configDraftResponse, configVersionResponse, configVersionsResponse, createRobotRequest, createRobotResponse, datapointListResponse, datapointValue, exposureListResponse, fetchTypesRequest, fetchTypesResponse, historyQuery, historyResponse, introspectionResponse, invokeOrServiceResponse, invokeRequest, jobResponse, liveSessionResponse, orgHealthQuery, orgLatencyQuery, orgLatencyResponse, orgQuotaUsage, orgUsageQuery, orgUsageResponse, patchRobotRequest, patchRobotResponse, publishConfigResponse, publishRequest, putConfigDraftRequest, putRobotDetailsRequest, putRobotDetailsResponse, robotTokenRotateResponse, jointStatePutRequest, jointStatePutResponse, releaseLiveQuery, renameSlugRequest, renameSlugResponse, robotDeleteQuery, resourceHealthListResponse, robotDeletionSummary, robotDetailResponse, robotJobsResponse, robotListResponse, slugUsageResponse, snapshotMetaResponse, typesResponse, } from './rest.js';
 export const ROUTE_SECTIONS = [
     { id: 'health', title: 'Health' },
@@ -2787,6 +2788,64 @@ export const ROUTES = [
             '`not_configured` when this cloud has no feedback address. At most 10 messages per developer per hour; the 11th answers ' +
             '`429 rate_limited` with `retry_after_ms`. Replies come by mail, to the sender\'s address.',
     },
+    /* ----------------------------------------------------------- org (plan) */
+    {
+        method: 'GET', path: '/api/org/plan', section: 'org',
+        summary: "Reads the org's plan: its limits, its usage against them, its add-ons and any change already queued.",
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: false, status: 200,
+        params: [], query: null, request: null, response: orgPlan,
+        errors: [...DEVELOPER_GUARD], transport: 'http',
+        notes: "The one read the console's Plan & billing page, its usage and limit gauges, and every upgrade prompt and feature gate draw from — " +
+            'nothing else computes `limits` or `usage` on its own. `limits` is already the effective ceiling, the catalogue row raised by ' +
+            '`addons` or replaced by an operator\'s override, so a consumer never recomputes it from the catalogue. `usage` is counted fresh on ' +
+            'every call, never cached. `switch` is present only for an organization still on the beta that has not yet landed on a priced plan.',
+    },
+    {
+        method: 'PUT', path: '/api/org/plan/change', section: 'org',
+        summary: "Moves the org's plan down — a lower plan or a cancellation to Basic — queuing the change rather than applying it at once.",
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: true, status: 200,
+        params: [], query: null, request: planChangeRequest, response: orgPlan,
+        errors: [...DEVELOPER_GUARD, 'tier_required', 'validation_error', 'plan_limit', 'target_state_conflict'], transport: 'http',
+        notes: 'Owner tier, and **downward only**: this route moves the org to a lower plan or cancels it outright to Basic. It never moves the org ' +
+            'up — until payment exists, an upgrade or an add-on is not this route\'s job at all, and is handled today as a Feedback request that ' +
+            'Fleetless then applies through the admin route. `409 target_state_conflict` names `target_plan` with rule `not_lower` when the ' +
+            'chosen plan is not below the org\'s current one; with rule `locked_basic_only` when the org is locked (`orgLock`) and the chosen ' +
+            'plan is anything but Basic; and with rule `migration_basic_only` when the org is still on the beta, awaiting the switch to priced ' +
+            'plans, and the chosen plan is anything but Basic — that choice is exactly what the org lands on at the switch. An owner is never ' +
+            'named in `keep` and always stays, but still counts against the target plan\'s `seats`; `409 plan_limit` names `seats` when the ' +
+            'owners alone already exceed it, and names whichever other limit `keep` still exceeds otherwise. `keep` is `null` when the org\'s ' +
+            'current usage already fits the target plan outright and nothing is deleted; named, it lists exactly the robots, apps, app users and ' +
+            'developers that stay. The choice is stored as `pending_change` and takes effect at `period_ends_at` — **everything of the chosen ' +
+            'kind not named in `keep` is deleted at that instant, never before** — except a choice made while the org is locked, which takes ' +
+            'effect at once, and a beta org\'s choice, which takes effect at the switch date instead. Anything created while the choice is ' +
+            'pending is checked against the target plan too and, when it passes, is folded into `keep`, so exactly what the confirmation counted ' +
+            'is what is actually deleted. A later `PUT` replaces a still-pending choice outright.',
+    },
+    {
+        method: 'DELETE', path: '/api/org/plan/change', section: 'org',
+        summary: 'Withdraws a plan change that was queued but has not taken effect yet.',
+        audience: 'developer', auth: 'developer', rateLimited: false, ownerTier: true, status: 204,
+        params: [], query: null, request: null, response: null,
+        errors: [...DEVELOPER_GUARD, 'tier_required', 'not_found'], transport: 'http',
+        notes: 'Owner tier. `404 not_found` when the org has no `pending_change` to withdraw. The org stays on its current plan, unchanged, as if ' +
+            'the choice had never been made; a developer who wants a different one sends a new `PUT`, which would have replaced this one outright ' +
+            'anyway.',
+    },
+    {
+        method: 'PATCH', path: '/api/admin/orgs/:id/plan', section: 'org',
+        summary: "Changes an org's plan, add-ons, limit overrides, currency or billing period as the operator.",
+        audience: 'internal', auth: 'ops', rateLimited: true, ownerTier: false, status: 200,
+        params: [{ name: 'id', description: 'The org\'s uuid, whose plan, add-ons or overrides the operator is changing.' }],
+        query: null, request: adminPlanChangeRequest, response: orgPlan,
+        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, 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) */
     {
         method: 'POST', path: '/api/bridge/assets', section: 'assets',

package/package.json

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