@indigoai-us/hq-cli 5.312.2-beta.0 → 5.314.0

package/dist/lib/billing/plan-lock.js

@@ -1,439 +0,0 @@
-/**
- * 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.
- *
- * 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.
- *
- * An absent field is UNKNOWN, so nothing here ever infers over-limit from
- * missing data (hq-absent-field-never-means-constraining-value).
- */
-import chalk from "chalk";
-import { vaultApiFetch } from "../../utils/vault-api.js";
-import { parseFreeMonth } from "./free-month.js";
-import { selectPlanLimitUpgradeUrl } from "./plan-limit-upgrade-url.js";
-// The free-month parser lives in a leaf module so the plan-gate 402 decoder can
-// share it without importing the HTTP layer; re-exported so existing callers
-// keep importing it from here.
-export { parseFreeMonth };
-/**
- * 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 const PLAN_LIMIT_REASONS = [
-    "users",
-    "integrations",
-    "secrets",
-    "agents",
-];
-/** @deprecated US-040 — alias of {@link PLAN_LIMIT_REASONS}. */
-export const PLAN_LOCK_REASONS = PLAN_LIMIT_REASONS;
-/** Starter member cap quoted when the server did not send a users.limit. */
-export const STARTER_MEMBER_TARGET = 5;
-/**
- * Starter integration cap quoted when the server did not send a limit.
- * One: Starter includes a single integration (US-020 owner decision 11).
- */
-export const STARTER_INTEGRATION_TARGET = 1;
-/** Starter secret cap quoted when the server did not send a secrets.limit. */
-export const STARTER_SECRET_TARGET = 10;
-/** Starter agent cap quoted when the server did not send an agents.limit. */
-export const STARTER_AGENT_TARGET = 0;
-/** Upgrade destination quoted when the server did not send one. */
-export const DEFAULT_UPGRADE_URL = "https://hq.computer/billing";
-/** The paid plan the nag sends owners to. Copy lives in ONE place. */
-export const WORKFORCE_PLAN_LABEL = "HQ Workforce ($500/mo)";
-function finiteNumber(value) {
-    return typeof value === "number" && Number.isFinite(value) ? value : null;
-}
-function asRecord(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
-        return null;
-    }
-    return value;
-}
-/** Published Starter cap for a dimension, quoted when the server sends no limit. */
-function starterCap(reason) {
-    switch (reason) {
-        case "users":
-            return STARTER_MEMBER_TARGET;
-        case "integrations":
-            return STARTER_INTEGRATION_TARGET;
-        case "secrets":
-            return STARTER_SECRET_TARGET;
-        case "agents":
-            return STARTER_AGENT_TARGET;
-    }
-}
-/**
- * Parse one usage row. An absent or null `limit` is UNKNOWN, never zero: the
- * renderer quotes the published Starter cap instead of "7 of 0 members"
- * (hq-absent-field-never-means-constraining-value).
- */
-function parseUsageRow(reason, value) {
-    const rec = asRecord(value);
-    if (!rec)
-        return null;
-    const used = finiteNumber(rec.used);
-    if (used === null)
-        return null;
-    const limit = finiteNumber(rec.limit);
-    return { used, limit: limit ?? starterCap(reason) };
-}
-function rowIsOver(value) {
-    const rec = asRecord(value);
-    if (!rec)
-        return false;
-    if (rec.over === true)
-        return true;
-    const used = finiteNumber(rec.used);
-    const limit = finiteNumber(rec.limit);
-    return used !== null && limit !== null && used > limit;
-}
-/**
- * Pick the membership row for `companySlug` (or `cmp_…` uid) out of a decoded
- * `/membership/me` body. No matching row is UNKNOWN. Does not read `planLock`.
- */
-export function selectCompanyMembership(body, companyRef) {
-    const rec = asRecord(body);
-    const rows = Array.isArray(rec?.memberships) ? rec.memberships : [];
-    const ref = companyRef.trim().toLowerCase();
-    for (const raw of rows) {
-        const row = asRecord(raw);
-        if (!row)
-            continue;
-        if (typeof row.status === "string" && row.status !== "active")
-            continue;
-        const slug = typeof row.companySlug === "string" ? row.companySlug.toLowerCase() : "";
-        const uid = typeof row.companyUid === "string" ? row.companyUid.toLowerCase() : "";
-        if (slug !== ref && uid !== ref)
-            continue;
-        return {
-            companyUid: typeof row.companyUid === "string" ? row.companyUid : undefined,
-            companySlug: typeof row.companySlug === "string" ? row.companySlug : undefined,
-        };
-    }
-    return null;
-}
-/** Parse the resolved plan id out of a usage-limits body. Absent → null. */
-export function selectPlan(body) {
-    const plan = asRecord(body)?.plan;
-    return plan === "free" || plan === "paid" || plan === "enterprise"
-        ? plan
-        : null;
-}
-/** Parse the `users` dimension out of a usage-limits body. Absent → null. */
-export function selectMemberUsage(body) {
-    const users = asRecord(asRecord(body)?.users);
-    if (!users)
-        return null;
-    if (typeof users.used !== "number" || !Number.isFinite(users.used)) {
-        return null;
-    }
-    const limit = typeof users.limit === "number" && Number.isFinite(users.limit)
-        ? users.limit
-        : STARTER_MEMBER_TARGET;
-    return { used: users.used, limit };
-}
-function selectUpgradeUrl(body, companySlug) {
-    const rec = asRecord(body);
-    const nested = asRecord(rec?.planLimits);
-    const topLevelUrl = typeof rec?.upgradeUrl === "string" && rec.upgradeUrl.trim().length > 0
-        ? rec.upgradeUrl.trim()
-        : undefined;
-    const nestedUrl = typeof nested?.upgradeUrl === "string" && nested.upgradeUrl.trim().length > 0
-        ? nested.upgradeUrl.trim()
-        : undefined;
-    return selectPlanLimitUpgradeUrl(companySlug, {
-        topLevelUrl,
-        nestedUrl,
-        legacyUrl: topLevelUrl ?? DEFAULT_UPGRADE_URL,
-    });
-}
-/**
- * Read over-limit dimensions from a usage-limits body. `planLimits` nested
- * map is preferred when present; otherwise the top-level resource rows.
- */
-export function selectOverReasons(body) {
-    const rec = asRecord(body);
-    if (!rec)
-        return [];
-    const nested = asRecord(rec.planLimits);
-    const source = nested ?? rec;
-    const reasons = [];
-    for (const key of PLAN_LIMIT_REASONS) {
-        if (rowIsOver(source[key]))
-            reasons.push(key);
-    }
-    return reasons;
-}
-export function selectUsages(body) {
-    const rec = asRecord(body);
-    if (!rec)
-        return {};
-    const nested = asRecord(rec.planLimits);
-    const source = nested ?? rec;
-    const out = {};
-    for (const key of PLAN_LIMIT_REASONS) {
-        const row = parseUsageRow(key, source[key]);
-        if (row)
-            out[key] = row;
-    }
-    return out;
-}
-function statusFromUsage(companySlug, companyUid, body, upgradeCompanySlug) {
-    const usages = selectUsages(body);
-    const reasons = selectOverReasons(body);
-    const rec = asRecord(body);
-    const anyOverFlag = rec?.anyOver === true;
-    return {
-        companySlug,
-        companyUid,
-        over: anyOverFlag || reasons.length > 0,
-        reasons,
-        members: selectMemberUsage(body) ?? usages.users,
-        usages,
-        upgradeUrl: selectUpgradeUrl(body, upgradeCompanySlug),
-        freeMonth: parseFreeMonth(rec?.freeMonth),
-        plan: selectPlan(body) ?? undefined,
-        checkedAt: new Date().toISOString(),
-    };
-}
-/**
- * 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 async function fetchPlanLimitStatus(token, companyRef, opts = {}) {
-    const timeoutMs = opts.timeoutMs ?? 8000;
-    const res = await vaultApiFetch({
-        token,
-        path: "/membership/me",
-        signal: AbortSignal.timeout(timeoutMs),
-    });
-    if (!res.ok)
-        return null;
-    const selected = selectCompanyMembership(await res.json().catch(() => null), companyRef);
-    if (!selected?.companyUid)
-        return null;
-    try {
-        const usage = await vaultApiFetch({
-            token,
-            path: "/v1/billing/usage-limits",
-            query: { companyUid: selected.companyUid },
-            signal: AbortSignal.timeout(timeoutMs),
-        });
-        if (!usage.ok)
-            return null;
-        const body = await usage.json().catch(() => null);
-        if (!body)
-            return null;
-        const selectedSlug = selected.companySlug ??
-            (!companyRef.startsWith("cmp_") ? companyRef : undefined);
-        return statusFromUsage(companyRef, selected.companyUid, body, selectedSlug);
-    }
-    catch {
-        return null;
-    }
-}
-/** @deprecated US-040 — alias of {@link fetchPlanLimitStatus}. */
-export const fetchPlanLockStatus = fetchPlanLimitStatus;
-/** Why the workspace is over, one clause per reason. */
-export function reasonLabel(reason) {
-    switch (reason) {
-        case "users":
-            return "too many members";
-        case "integrations":
-            return "too many integrations";
-        case "secrets":
-            return "too many secrets";
-        case "agents":
-            return "agents are not included on Starter";
-    }
-}
-function usageTarget(reason, status) {
-    const used = status.usages[reason]?.limit;
-    if (typeof used === "number")
-        return used;
-    switch (reason) {
-        case "users":
-            return status.members?.limit ?? STARTER_MEMBER_TARGET;
-        case "integrations":
-            return STARTER_INTEGRATION_TARGET;
-        case "secrets":
-            return STARTER_SECRET_TARGET;
-        case "agents":
-            return STARTER_AGENT_TARGET;
-    }
-}
-/** The remedy sentence for one reason — what the owner does to clear it. */
-function reasonRemedy(reason, status) {
-    const target = usageTarget(reason, status);
-    switch (reason) {
-        case "users":
-            return `remove members until you are at ${target} or fewer`;
-        case "integrations":
-            return `disconnect integrations until you are at ${target} or fewer`;
-        case "secrets":
-            return `delete secrets until you are at ${target} or fewer`;
-        case "agents":
-            return target > 0
-                ? `deprovision agents until you are at ${target} or fewer`
-                : "deprovision the workspace's agents";
-    }
-}
-/** The short per-reason clause used inside the one-line turn notice. */
-function reasonDetail(reason, status) {
-    const row = status.usages[reason];
-    const target = usageTarget(reason, status);
-    switch (reason) {
-        case "users":
-            return row || status.members
-                ? `${(row ?? status.members).used} of ${target} members`
-                : `over its ${target}-member limit`;
-        case "integrations":
-            return row
-                ? `${row.used} of ${target} integrations`
-                : `over its ${target}-integration limit`;
-        case "secrets":
-            return row
-                ? `${row.used} of ${target} secrets`
-                : `over its ${target}-secret limit`;
-        case "agents":
-            return "agents are not included on Starter";
-    }
-}
-function usageLine(reason, status) {
-    const row = status.usages[reason];
-    const target = usageTarget(reason, status);
-    switch (reason) {
-        case "users": {
-            const members = row ?? status.members;
-            return members
-                ? `  Members: ${members.used} of ${target}.`
-                : `  Members allowed on Starter: ${target}.`;
-        }
-        case "integrations":
-            return row
-                ? `  Integrations: ${row.used} of ${target}.`
-                : `  Integrations allowed on Starter: ${target}.`;
-        case "secrets":
-            return row
-                ? `  Secrets: ${row.used} of ${target}.`
-                : `  Secrets allowed on Starter: ${target}.`;
-        case "agents":
-            return row
-                ? `  Agents: ${row.used} of ${target}.`
-                : `  Agents allowed on Starter: ${target}.`;
-    }
-}
-/**
- * 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
- * drift into three different promises.
- */
-export const HARD_STOP_SENTENCE = "Nothing has been deleted and everything keeps working, except that new " +
-    "files and new secrets are paused until this is sorted.";
-const HARD_STOP_SENTENCE_LINES = [
-    "  Nothing has been deleted and everything keeps working, except that new",
-    "  files and new secrets are paused until this is sorted.",
-];
-function capitalize(text) {
-    return text.charAt(0).toUpperCase() + text.slice(1);
-}
-/**
- * The full over-limit block: why the workspace is over, where it stands
- * 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 `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 function renderPlanLimitNotice(status, opts = {}) {
-    const { companySlug, freeMonth } = status;
-    const lines = [];
-    lines.push(`HQ Starter — ${companySlug} is over its plan limits.`);
-    const reasons = status.reasons.length
-        ? status.reasons.map(reasonLabel).join("; ")
-        : "over the Starter plan limits";
-    lines.push(`  Why: ${reasons}.`);
-    for (const reason of status.reasons) {
-        lines.push(usageLine(reason, status));
-    }
-    lines.push(HARD_STOP_SENTENCE_LINES[0]);
-    lines.push(HARD_STOP_SENTENCE_LINES[1]);
-    const remedy = status.reasons.length
-        ? status.reasons.map((reason) => reasonRemedy(reason, status)).join(", and ")
-        : "come back under the Starter plan limits";
-    const freeMonthUrl = freeMonth?.url;
-    const hasFreeMonth = Boolean(freeMonth?.eligible && freeMonthUrl);
-    if (hasFreeMonth) {
-        lines.push("  Three ways to sort it:");
-        lines.push(`    1. Start your free month — add a card, first month free: ${freeMonthUrl}`);
-        lines.push(`    2. ${capitalize(remedy)}.`);
-        lines.push(`    3. Upgrade to ${WORKFORCE_PLAN_LABEL}.`);
-    }
-    else {
-        lines.push("  Two ways to sort it:");
-        lines.push(`    1. ${capitalize(remedy)}.`);
-        lines.push(`    2. Upgrade to ${WORKFORCE_PLAN_LABEL}.`);
-    }
-    lines.push(`  Upgrade: ${status.upgradeUrl}`);
-    if (opts.inviteTeammateEnabled === true &&
-        status.plan === "free" &&
-        status.over &&
-        status.members?.used === 1) {
-        lines.push(`  Invite a teammate with: hq members invite <email> --company ${companySlug} --role member`);
-    }
-    return lines.join("\n");
-}
-/**
- * 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 function renderPlanLimitLine(status) {
-    const detail = status.reasons.length
-        ? status.reasons.map((reason) => reasonDetail(reason, status)).join("; ")
-        : "over the Starter plan limits";
-    return (`Company ${status.companySlug} is over its Starter limits (${detail}). ` +
-        `New files and new secrets are paused until this is sorted: ${status.upgradeUrl}`);
-}
-/**
- * The `Plan: …` orientation line. Starter only: a paid or enterprise
- * workspace — and an UNKNOWN plan — gets no line at all.
- */
-export function renderPlanLine(status) {
-    if (status.over)
-        return "Plan: Starter — over its limits";
-    if (status.plan !== "free")
-        return null;
-    const target = status.members?.limit ?? STARTER_MEMBER_TARGET;
-    if (status.members) {
-        return `Plan: Starter — ${status.members.used} of ${target} members`;
-    }
-    return `Plan: Starter — ${target} members included`;
-}
-/**
- * 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
- * impression US-033 removes.
- */
-export function colorizePlanLimitNotice(notice) {
-    return chalk.yellow(notice);
-}
-//# sourceMappingURL=plan-lock.js.map