@indigoai-us/hq-cli 5.122.2 → 5.123.0

package/dist/lib/billing/plan-lock.d.ts

@@ -1,65 +1,58 @@
 /**
- * `plan-lock` (starter-plan-hard-limits / US-011, rewritten for US-036) — the
- * CLI-side read + render of a workspace's Starter plan-limit state.
+ * CLI-side read + render of a workspace's Starter plan-limit nag
+ * (starter-plan-hard-limits / US-011, rewritten for US-036, then US-040).
  *
  * Starter (free) workspaces are capped on members, integrations, secrets and
  * agents (deployments and storage nag but never arm a stop). Going over does
  * NOT stop the workspace working (US-033 owner decision 12): everything that
  * exists keeps working, and the only two things that pause are adding new
  * files to the vault and adding new secrets (owner decision 13). Every string
- * this module renders is a nag, never a claim that HQ has stopped. The state
- * is NOT decided here — hq-pro is the single source of truth and ships the
- * answer on `GET /membership/me` as a per-company `planLock` object. This
- * module only reads that field and renders it.
+ * this module renders is a nag, never a claim that HQ has stopped.
+ *
+ * US-040: hq-pro no longer attaches `planLock` on `/membership/me` or
+ * `/v1/billing/usage-limits`. This module reads the nag payload from
+ * usage-limits (`planLimits` resource rows, top-level `freeMonth`,
+ * `upgradeUrl`) and never a lock object.
  *
  * Copy rule (US-036): no string a customer reads may contain "locked" or
  * "read-only". `plan-lock.test.ts` scans every rendered string for both.
  *
- * Member counts are decoration, never a second opinion: the count comes from
- * `GET /v1/billing/usage-limits` on a best-effort basis and its absence only
- * removes the "n of 5" detail from the notice. An absent field is UNKNOWN, so
- * nothing here ever infers a lock (or an unlock) from missing data
- * (hq-absent-field-never-means-constraining-value).
+ * An absent field is UNKNOWN, so nothing here ever infers over-limit from
+ * missing data (hq-absent-field-never-means-constraining-value).
  */
 /**
- * Mirror of hq-pro's `PlanLockReason`. Owner decision 7 (2026-09-17) fixes the
- * nagging set at these four: `deployments` and `storageBytes` are nag-only and
- * never appear here. An unrecognised reason is dropped by `parsePlanLock`, so a
- * server that adds a fifth dimension renders as the generic line rather than as
- * a false claim about members.
+ * Dimensions the bind notice names with a remedy. Owner decision 7 (2026-09-17)
+ * fixes the nagging set at these four: `deployments` and `storageBytes` are
+ * nag-only and never appear here.
  */
+export declare const PLAN_LIMIT_REASONS: readonly ["users", "integrations", "secrets", "agents"];
+/** @deprecated US-040 — alias of {@link PLAN_LIMIT_REASONS}. */
 export declare const PLAN_LOCK_REASONS: readonly ["users", "integrations", "secrets", "agents"];
-export type PlanLockReason = (typeof PLAN_LOCK_REASONS)[number];
-/** Mirror of hq-pro's `PlanLock` wire shape (see src/billing/plan-lock.ts). */
-export interface PlanLock {
-    locked: boolean;
-    reasons: PlanLockReason[];
-    upgradeUrl: string;
-    fixOptions: PlanLockFixOptions;
-}
-/**
- * The remedies hq-pro ships with the lock. The two original fields are always
- * present (defaulted when the server omits them) because shipped copy reads
- * them unconditionally; every dimension added since is optional, so an older
- * server simply leaves it absent and the renderer quotes the Starter cap.
- */
-export interface PlanLockFixOptions {
-    removeMembersTo: number;
-    disconnectIntegrations: boolean;
-    disconnectIntegrationsTo?: number;
-    removeSecretsTo?: number;
-    deprovisionAgentsTo?: number;
-}
+export type PlanLimitReason = (typeof PLAN_LIMIT_REASONS)[number];
+/** @deprecated US-040 — alias of {@link PlanLimitReason}. */
+export type PlanLockReason = PlanLimitReason;
 /** Optional member decoration for the notice ("7 of 5 members"). */
-export interface PlanLockMembers {
+export interface PlanLimitMembers {
     used: number;
     limit: number;
 }
-export interface PlanLockStatus {
+/** @deprecated US-040 — alias of {@link PlanLimitMembers}. */
+export type PlanLockMembers = PlanLimitMembers;
+export interface PlanLimitFreeMonth {
+    eligible: boolean;
+    trialDays?: number;
+    url?: string;
+}
+export interface PlanLimitStatus {
     companySlug: string;
     companyUid?: string;
-    lock: PlanLock;
-    members?: PlanLockMembers;
+    /** True when any named dimension is over its cap. */
+    over: boolean;
+    reasons: PlanLimitReason[];
+    members?: PlanLimitMembers;
+    usages: Partial<Record<PlanLimitReason, PlanLimitMembers>>;
+    upgradeUrl: string;
+    freeMonth?: PlanLimitFreeMonth;
     /**
      * Resolved plan id, when the usage endpoint answered. UNKNOWN (absent) when
      * it did not — surfaces that gate on "is this Starter?" must then stay
@@ -68,51 +61,53 @@ export interface PlanLockStatus {
     plan?: "free" | "paid" | "enterprise";
     checkedAt: string;
 }
-/** Starter member cap quoted when the server did not send `removeMembersTo`. */
+/** @deprecated US-040 — alias of {@link PlanLimitStatus}. */
+export type PlanLockStatus = PlanLimitStatus;
+/** Starter member cap quoted when the server did not send a users.limit. */
 export declare const STARTER_MEMBER_TARGET = 5;
 /**
- * Starter integration cap quoted when the server did not send
- * `disconnectIntegrationsTo`. One: Starter includes a single integration
- * (US-020 owner decision 11, 2026-09-17 — it was zero before that).
+ * Starter integration cap quoted when the server did not send a limit.
+ * One: Starter includes a single integration (US-020 owner decision 11).
  */
 export declare const STARTER_INTEGRATION_TARGET = 1;
-/** Starter secret cap quoted when the server did not send `removeSecretsTo`. */
+/** Starter secret cap quoted when the server did not send a secrets.limit. */
 export declare const STARTER_SECRET_TARGET = 10;
-/** Starter agent cap quoted when the server did not send `deprovisionAgentsTo`. */
+/** Starter agent cap quoted when the server did not send an agents.limit. */
 export declare const STARTER_AGENT_TARGET = 0;
 /** Upgrade destination quoted when the server did not send one. */
 export declare const DEFAULT_UPGRADE_URL = "https://hq.computer/billing";
-/** The paid plan the lock wall sends owners to. Copy lives in ONE place. */
+/** The paid plan the nag sends owners to. Copy lives in ONE place. */
 export declare const WORKFORCE_PLAN_LABEL = "HQ Workforce ($500/mo)";
-/**
- * Defensively parse a `planLock` payload. Anything malformed returns null —
- * the caller then behaves exactly as if the server had sent nothing, which is
- * "unknown", not "locked".
- */
-export declare function parsePlanLock(value: unknown): PlanLock | null;
+export declare function parseFreeMonth(value: unknown): PlanLimitFreeMonth | undefined;
 /**
  * Pick the membership row for `companySlug` (or `cmp_…` uid) out of a decoded
- * `/membership/me` body and return its parsed lock. No matching row — or no
- * `planLock` on it — is UNKNOWN, so this returns null rather than guessing.
+ * `/membership/me` body. No matching row is UNKNOWN. Does not read `planLock`.
  */
-export declare function selectPlanLock(body: unknown, companyRef: string): {
-    lock: PlanLock;
+export declare function selectCompanyMembership(body: unknown, companyRef: string): {
     companyUid?: string;
 } | null;
 /** Parse the resolved plan id out of a usage-limits body. Absent → null. */
 export declare function selectPlan(body: unknown): "free" | "paid" | "enterprise" | null;
 /** Parse the `users` dimension out of a usage-limits body. Absent → null. */
-export declare function selectMemberUsage(body: unknown): PlanLockMembers | null;
+export declare function selectMemberUsage(body: unknown): PlanLimitMembers | null;
+/**
+ * Read over-limit dimensions from a usage-limits body. `planLimits` nested
+ * map is preferred when present; otherwise the top-level resource rows.
+ */
+export declare function selectOverReasons(body: unknown): PlanLimitReason[];
+export declare function selectUsages(body: unknown): Partial<Record<PlanLimitReason, PlanLimitMembers>>;
 /**
- * Read the live lock for one company: `planLock` from `/membership/me`, plus a
- * best-effort member count for the notice. Returns null when the server did not
- * answer with a lock for this company — callers must then say nothing.
+ * Read the live nag for one company from usage-limits. `/membership/me` is
+ * used only to resolve slug → companyUid. Returns null when the server did
+ * not answer for this company — callers must then say nothing.
  */
-export declare function fetchPlanLockStatus(token: string, companyRef: string, opts?: {
+export declare function fetchPlanLimitStatus(token: string, companyRef: string, opts?: {
     timeoutMs?: number;
-}): Promise<PlanLockStatus | null>;
+}): Promise<PlanLimitStatus | null>;
+/** @deprecated US-040 — alias of {@link fetchPlanLimitStatus}. */
+export declare const fetchPlanLockStatus: typeof fetchPlanLimitStatus;
 /** Why the workspace is over, one clause per reason. */
-export declare function reasonLabel(reason: PlanLockReason): string;
+export declare function reasonLabel(reason: PlanLimitReason): string;
 /**
  * The one sentence every over-limit surface says about the two hard stops
  * (US-033 §3.3). Written once so the CLI, the console and the emails cannot
@@ -124,22 +119,22 @@ export declare const HARD_STOP_SENTENCE: string;
  * against the cap, and the ways out. Plain text — colour is applied by the
  * caller so scripts capturing stdout get a clean block.
  *
- * Every line is derived from `lock.reasons`. A workspace over on secrets is
+ * Every line is derived from `status.reasons`. A workspace over on secrets is
  * never told it has too many members, and an empty reason list (a server
  * dimension this CLI does not know) renders a generic line rather than a claim
  * about a dimension nobody measured.
  */
-export declare function renderPlanLimitNotice(status: PlanLockStatus): string;
+export declare function renderPlanLimitNotice(status: PlanLimitStatus): string;
 /**
  * The one-line form injected on every turn while the workspace stays over.
  * Kept to a single line on purpose — it repeats each turn.
  */
-export declare function renderPlanLimitLine(status: PlanLockStatus): string;
+export declare function renderPlanLimitLine(status: PlanLimitStatus): string;
 /**
  * The `Plan: …` orientation line. Starter only: a paid or enterprise
  * workspace — and an UNKNOWN plan — gets no line at all.
  */
-export declare function renderPlanLine(status: PlanLockStatus): string | null;
+export declare function renderPlanLine(status: PlanLimitStatus): string | null;
 /**
  * Colourised block for interactive output. Yellow, not red: this is a nag, and
  * an error colour would read as "HQ has stopped working", which is the exact