@fleetless/contracts 6.0.0-next.3 → 6.1.0-next.1

package/dist/plans.d.ts

@@ -0,0 +1,525 @@
+// 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 exist on
+ * `pro` only; see `ADDONS` and the `addons` feature.
+ */
+export declare const planId: z.ZodEnum<{
+    basic: "basic";
+    plus: "plus";
+    pro: "pro";
+    enterprise: "enterprise";
+}>;
+export type PlanId = z.infer<typeof planId>;
+/**
+ * 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 declare const PLAN_ORDER: readonly PlanId[];
+/**
+ * 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 declare const planLimitKey: z.ZodEnum<{
+    apps: "apps";
+    robots: "robots";
+    seats: "seats";
+    app_users: "app_users";
+    live_video_ms_per_month: "live_video_ms_per_month";
+    asset_bytes_per_robot: "asset_bytes_per_robot";
+    history_days: "history_days";
+    audit_days: "audit_days";
+}>;
+export type PlanLimitKey = z.infer<typeof planLimitKey>;
+export declare const planLimits: z.ZodObject<{
+    seats: z.ZodNullable<z.ZodNumber>;
+    robots: z.ZodNullable<z.ZodNumber>;
+    apps: z.ZodNullable<z.ZodNumber>;
+    app_users: z.ZodNullable<z.ZodNumber>;
+    live_video_ms_per_month: z.ZodNullable<z.ZodNumber>;
+    asset_bytes_per_robot: z.ZodNullable<z.ZodNumber>;
+    history_days: z.ZodNullable<z.ZodNumber>;
+    audit_days: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type PlanLimits = z.infer<typeof planLimits>;
+/**
+ * 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` only).
+ */
+export declare const planFeature: z.ZodEnum<{
+    require_two_factor: "require_two_factor";
+    two_factor: "two_factor";
+    app_mcp: "app_mcp";
+    app_oidc: "app_oidc";
+    hosted_logo: "hosted_logo";
+    audit_export: "audit_export";
+    addons: "addons";
+}>;
+export type PlanFeature = z.infer<typeof planFeature>;
+export declare const planFeatures: z.ZodObject<{
+    require_two_factor: z.ZodBoolean;
+    two_factor: z.ZodBoolean;
+    app_mcp: z.ZodBoolean;
+    app_oidc: z.ZodBoolean;
+    hosted_logo: z.ZodBoolean;
+    audit_export: z.ZodBoolean;
+    addons: z.ZodBoolean;
+}, z.core.$strip>;
+export type PlanFeatures = z.infer<typeof planFeatures>;
+export declare const planPrices: z.ZodObject<{
+    eur_month: z.ZodNumber;
+    usd_month: z.ZodNumber;
+    eur_year: z.ZodNumber;
+    usd_year: z.ZodNumber;
+}, z.core.$strip>;
+export type PlanPrices = z.infer<typeof planPrices>;
+export declare const planSupport: z.ZodEnum<{
+    email: "email";
+    community: "community";
+    priority: "priority";
+    named_contact: "named_contact";
+}>;
+export type PlanSupport = z.infer<typeof planSupport>;
+export declare const planCatalogueEntry: z.ZodObject<{
+    id: z.ZodEnum<{
+        basic: "basic";
+        plus: "plus";
+        pro: "pro";
+        enterprise: "enterprise";
+    }>;
+    name: z.ZodString;
+    limits: z.ZodObject<{
+        seats: z.ZodNullable<z.ZodNumber>;
+        robots: z.ZodNullable<z.ZodNumber>;
+        apps: z.ZodNullable<z.ZodNumber>;
+        app_users: z.ZodNullable<z.ZodNumber>;
+        live_video_ms_per_month: z.ZodNullable<z.ZodNumber>;
+        asset_bytes_per_robot: z.ZodNullable<z.ZodNumber>;
+        history_days: z.ZodNullable<z.ZodNumber>;
+        audit_days: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    features: z.ZodObject<{
+        require_two_factor: z.ZodBoolean;
+        two_factor: z.ZodBoolean;
+        app_mcp: z.ZodBoolean;
+        app_oidc: z.ZodBoolean;
+        hosted_logo: z.ZodBoolean;
+        audit_export: z.ZodBoolean;
+        addons: z.ZodBoolean;
+    }, z.core.$strip>;
+    prices: z.ZodNullable<z.ZodObject<{
+        eur_month: z.ZodNumber;
+        usd_month: z.ZodNumber;
+        eur_year: z.ZodNumber;
+        usd_year: z.ZodNumber;
+    }, z.core.$strip>>;
+    support: z.ZodEnum<{
+        email: "email";
+        community: "community";
+        priority: "priority";
+        named_contact: "named_contact";
+    }>;
+}, z.core.$strip>;
+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`).
+ */
+export declare const addonKey: z.ZodEnum<{
+    apps: "apps";
+    robots: "robots";
+    seats: "seats";
+    app_user_packs: "app_user_packs";
+    live_video_packs: "live_video_packs";
+}>;
+export type AddonKey = z.infer<typeof addonKey>;
+export declare const addonCatalogueEntry: z.ZodObject<{
+    key: z.ZodEnum<{
+        apps: "apps";
+        robots: "robots";
+        seats: "seats";
+        app_user_packs: "app_user_packs";
+        live_video_packs: "live_video_packs";
+    }>;
+    raises: z.ZodEnum<{
+        apps: "apps";
+        robots: "robots";
+        seats: "seats";
+        app_users: "app_users";
+        live_video_ms_per_month: "live_video_ms_per_month";
+        asset_bytes_per_robot: "asset_bytes_per_robot";
+        history_days: "history_days";
+        audit_days: "audit_days";
+    }>;
+    per_unit: z.ZodNumber;
+    prices: z.ZodObject<{
+        eur_month: z.ZodNumber;
+        usd_month: z.ZodNumber;
+        eur_year: z.ZodNumber;
+        usd_year: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type AddonCatalogueEntry = z.infer<typeof addonCatalogueEntry>;
+/**
+ * **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 declare function usdCentsFromEurCents(eurCents: number): number;
+/** Yearly is twelve months at 15% off, rounded to the nearest cent. */
+export declare function yearlyEurCents(monthEurCents: number): number;
+/**
+ * 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 declare function pricesFromEurMonth(eurMonthCents: number): PlanPrices;
+/**
+ * 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 declare const PLANS: Readonly<Record<PlanId, PlanCatalogueEntry>>;
+/**
+ * The add-on catalogue. Every price goes through `pricesFromEurMonth`, same
+ * discipline as `PLANS`.
+ */
+export declare const ADDONS: Readonly<Record<AddonKey, AddonCatalogueEntry>>;
+/** The cheapest plan that has the feature. */
+export declare function requiredPlanFor(feature: PlanFeature): PlanId;
+/**
+ * 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 declare function nextPlanRaising(plan: PlanId, key: PlanLimitKey): PlanId | null;
+/** What an org is billed in. The catalogue's prices are fixed in both; this picks which one an invoice reads in. */
+export declare const planCurrency: z.ZodEnum<{
+    eur: "eur";
+    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;
+    apps: z.ZodNumber;
+    app_user_packs: z.ZodNumber;
+    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;
+    apps: z.ZodNumber;
+    app_users: z.ZodNumber;
+    live_video_ms_this_month: z.ZodNumber;
+    asset_bytes: z.ZodNumber;
+}, z.core.$strip>;
+export type OrgPlanUsage = z.infer<typeof orgPlanUsage>;
+/**
+ * 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 declare const planChangeKeep: z.ZodObject<{
+    robots: z.ZodArray<z.ZodUUID>;
+    apps: z.ZodArray<z.ZodUUID>;
+    app_users: z.ZodArray<z.ZodUUID>;
+    developers: z.ZodArray<z.ZodUUID>;
+}, z.core.$strict>;
+export type PlanChangeKeep = z.infer<typeof planChangeKeep>;
+/**
+ * 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 declare const planChangeReason: z.ZodEnum<{
+    cancel: "cancel";
+    downgrade: "downgrade";
+    migration: "migration";
+    lock: "lock";
+}>;
+export type PlanChangeReason = z.infer<typeof planChangeReason>;
+/**
+ * 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 declare const pendingPlanChange: z.ZodObject<{
+    target_plan: z.ZodEnum<{
+        basic: "basic";
+        plus: "plus";
+        pro: "pro";
+        enterprise: "enterprise";
+    }>;
+    reason: z.ZodEnum<{
+        cancel: "cancel";
+        downgrade: "downgrade";
+        migration: "migration";
+        lock: "lock";
+    }>;
+    effective_at: z.ZodNullable<z.ZodISODateTime>;
+    keep: z.ZodNullable<z.ZodObject<{
+        robots: z.ZodArray<z.ZodUUID>;
+        apps: z.ZodArray<z.ZodUUID>;
+        app_users: z.ZodArray<z.ZodUUID>;
+        developers: z.ZodArray<z.ZodUUID>;
+    }, z.core.$strict>>;
+    history_days_after: z.ZodNumber;
+    chosen_by: z.ZodUUID;
+    chosen_at: z.ZodISODateTime;
+}, 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 —
+ * 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 declare const orgLock: z.ZodObject<{
+    reason: z.ZodEnum<{
+        migration: "migration";
+        payment: "payment";
+    }>;
+    since: z.ZodISODateTime;
+}, z.core.$strip>;
+export type OrgLock = z.infer<typeof orgLock>;
+/**
+ * **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 declare const orgPlan: z.ZodObject<{
+    plan: z.ZodEnum<{
+        basic: "basic";
+        plus: "plus";
+        pro: "pro";
+        enterprise: "enterprise";
+    }>;
+    currency: z.ZodEnum<{
+        eur: "eur";
+        usd: "usd";
+    }>;
+    period_ends_at: z.ZodISODateTime;
+    addons: z.ZodObject<{
+        seats: z.ZodNumber;
+        robots: z.ZodNumber;
+        apps: z.ZodNumber;
+        app_user_packs: z.ZodNumber;
+        live_video_packs: z.ZodNumber;
+    }, z.core.$strip>;
+    limits: z.ZodObject<{
+        seats: z.ZodNullable<z.ZodNumber>;
+        robots: z.ZodNullable<z.ZodNumber>;
+        apps: z.ZodNullable<z.ZodNumber>;
+        app_users: z.ZodNullable<z.ZodNumber>;
+        live_video_ms_per_month: z.ZodNullable<z.ZodNumber>;
+        asset_bytes_per_robot: z.ZodNullable<z.ZodNumber>;
+        history_days: z.ZodNullable<z.ZodNumber>;
+        audit_days: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>;
+    features: z.ZodObject<{
+        require_two_factor: z.ZodBoolean;
+        two_factor: z.ZodBoolean;
+        app_mcp: z.ZodBoolean;
+        app_oidc: z.ZodBoolean;
+        hosted_logo: z.ZodBoolean;
+        audit_export: z.ZodBoolean;
+        addons: z.ZodBoolean;
+    }, z.core.$strip>;
+    usage: z.ZodObject<{
+        seats: z.ZodNumber;
+        robots: z.ZodNumber;
+        apps: z.ZodNumber;
+        app_users: z.ZodNumber;
+        live_video_ms_this_month: z.ZodNumber;
+        asset_bytes: z.ZodNumber;
+    }, z.core.$strip>;
+    pending_change: z.ZodNullable<z.ZodObject<{
+        target_plan: z.ZodEnum<{
+            basic: "basic";
+            plus: "plus";
+            pro: "pro";
+            enterprise: "enterprise";
+        }>;
+        reason: z.ZodEnum<{
+            cancel: "cancel";
+            downgrade: "downgrade";
+            migration: "migration";
+            lock: "lock";
+        }>;
+        effective_at: z.ZodNullable<z.ZodISODateTime>;
+        keep: z.ZodNullable<z.ZodObject<{
+            robots: z.ZodArray<z.ZodUUID>;
+            apps: z.ZodArray<z.ZodUUID>;
+            app_users: z.ZodArray<z.ZodUUID>;
+            developers: z.ZodArray<z.ZodUUID>;
+        }, z.core.$strict>>;
+        history_days_after: z.ZodNumber;
+        chosen_by: z.ZodUUID;
+        chosen_at: z.ZodISODateTime;
+    }, z.core.$strip>>;
+    lock: z.ZodNullable<z.ZodObject<{
+        reason: z.ZodEnum<{
+            migration: "migration";
+            payment: "payment";
+        }>;
+        since: z.ZodISODateTime;
+    }, z.core.$strip>>;
+    switch: z.ZodNullable<z.ZodObject<{
+        at: z.ZodNullable<z.ZodISODateTime>;
+        needs_choice: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type OrgPlan = z.infer<typeof orgPlan>;
+/**
+ * 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 declare const planChangeRequest: z.ZodObject<{
+    target_plan: z.ZodEnum<{
+        basic: "basic";
+        plus: "plus";
+        pro: "pro";
+        enterprise: "enterprise";
+    }>;
+    keep: z.ZodNullable<z.ZodObject<{
+        robots: z.ZodArray<z.ZodUUID>;
+        apps: z.ZodArray<z.ZodUUID>;
+        app_users: z.ZodArray<z.ZodUUID>;
+        developers: z.ZodArray<z.ZodUUID>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type PlanChangeRequest = z.infer<typeof planChangeRequest>;
+/**
+ * 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 declare const planOverrides: z.ZodObject<{
+    apps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    robots: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    seats: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    app_users: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    live_video_ms_per_month: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    asset_bytes_per_robot: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    history_days: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    audit_days: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+}, 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
+ * 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 declare const adminPlanChangeRequest: z.ZodObject<{
+    plan: z.ZodEnum<{
+        basic: "basic";
+        plus: "plus";
+        pro: "pro";
+        enterprise: "enterprise";
+    }>;
+    addons: z.ZodOptional<z.ZodObject<{
+        seats: z.ZodOptional<z.ZodNumber>;
+        robots: z.ZodOptional<z.ZodNumber>;
+        apps: z.ZodOptional<z.ZodNumber>;
+        app_user_packs: z.ZodOptional<z.ZodNumber>;
+        live_video_packs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    overrides: z.ZodOptional<z.ZodObject<{
+        apps: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        robots: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        seats: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        app_users: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        live_video_ms_per_month: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        asset_bytes_per_robot: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        history_days: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        audit_days: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    }, z.core.$strict>>;
+    currency: z.ZodOptional<z.ZodEnum<{
+        eur: "eur";
+        usd: "usd";
+    }>>;
+    period_ends_at: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
+}, z.core.$strict>;
+export type AdminPlanChangeRequest = z.infer<typeof adminPlanChangeRequest>;