@indigoai-us/hq-cli 5.345.143 → 5.345.144

package/dist/lib/billing/usage-cost.js

@@ -0,0 +1,440 @@
+/**
+ * `hq billing usage` core (usage-only-pricing US-015): this month's usage per
+ * meter, the projected bill, the allowance left, and the biggest drivers with
+ * a fix for each. Pure apart from the injected reads, so it is unit-tested
+ * without a network.
+ *
+ * ONE READ SEAM. Every usage number comes through {@link readMonthUsage}. Today
+ * it reads the sources the console and CLI already expose:
+ *   - `GET /v1/billing/usage-limits?companyUid=` (company) or
+ *     `GET /v1/billing/person/usage-limits` (solo, person scope) for storage
+ *     bytes and secrets stored. Both routes are member-gated server-side, so a
+ *     member only ever gets their own company's numbers.
+ *   - optionally, the live cloud file-history listing `hq storage status`
+ *     uses, to split storage into current files and old versions and to see a
+ *     prune right away (Storage Lens, behind usage-limits, updates daily).
+ * usage-limits also answers `vaults` when the server counts them; without it
+ * the vault meter is `not-available`.
+ * The call-count meters (syncs, gateway calls, HQ MCP calls, agent runs) have
+ * no member-visible source yet. They are reported
+ * as `not-available`, never as zero, and the bill is marked incomplete.
+ *
+ * When the daily rollup (US-005, hq-pro `usage-meter-rollup.ts`) gets a read
+ * route, add it as a {@link MonthUsageSource} and make it the default here.
+ * Nothing else in this file or in the command has to change.
+ *
+ * Read-only: nothing here prunes, deletes, collects garbage or reclaims space.
+ * Fixes are returned as commands for the caller to preview and run with the
+ * user's yes (the /hq-cost skill does that).
+ */
+import { BUNDLED_USAGE_CARD, SELF_HOSTED_GUIDE_URL, formatFreeItems } from "./usage-card.js";
+import { BUNDLED_USAGE_METER_RATES, USAGE_MONTHLY_ALLOWANCE_USD, } from "./usage-rate-card.js";
+/** Bytes per billed GB. Storage is billed like S3: 1 GB = 2^30 bytes. */
+export const BYTES_PER_GB = 1024 ** 3;
+export function monthWindow(now) {
+    const start = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 1));
+    const end = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() + 1, 1));
+    return { start, end };
+}
+function usedOf(body, key) {
+    const row = body?.[key];
+    if (!row || typeof row !== "object")
+        return { value: null, state: "unknown" };
+    if (row.usageState === "not-collected")
+        return { value: null, state: "not-available" };
+    if (typeof row.used === "number" && Number.isFinite(row.used) && row.used >= 0) {
+        return { value: row.used, state: "measured" };
+    }
+    return { value: null, state: "unknown" };
+}
+function hasRow(body, key) {
+    const row = body?.[key];
+    return row !== undefined && row !== null;
+}
+/** Today's source: plan usage-limits (storage bytes, secrets). */
+export function usageLimitsSource(deps) {
+    return {
+        name: "usage-limits",
+        async read(scope, now) {
+            const { start, end } = monthWindow(now);
+            const body = await deps.fetchUsageLimits(scope);
+            if (body === null) {
+                throw new Error("Could not read usage from HQ right now. Try again, or run `hq login` if you are signed out.");
+            }
+            const storage = usedOf(body, "storageBytes");
+            const secrets = usedOf(body, "secrets");
+            const vaults = usedOf(body, "vaults");
+            const meters = BUNDLED_USAGE_METER_RATES.map(({ key }) => {
+                if (key === "storage") {
+                    return { key, value: storage.value === null ? null : storage.value / BYTES_PER_GB, state: storage.state };
+                }
+                if (key === "secret")
+                    return { key, ...secrets };
+                // An absent vault row is a server that does not count vaults yet.
+                if (key === "vault") {
+                    return hasRow(body, "vaults") ? { key, ...vaults } : { key, value: null, state: "not-available" };
+                }
+                // No member-visible source until the daily rollup (US-005) is readable.
+                return { key, value: null, state: "not-available" };
+            });
+            return {
+                scope,
+                source: "usage-limits",
+                period: { start: start.toISOString(), end: end.toISOString(), asOf: now.toISOString() },
+                meters,
+            };
+        },
+    };
+}
+/** Rollup meter -> rate-card key, the unit scale to billed units, and how days combine. */
+const ROLLUP_METERS = {
+    member_syncs: { key: "member-sync", scale: 1, combine: "sum" },
+    storage_bytes: { key: "storage", scale: 1 / BYTES_PER_GB, combine: "average" },
+    secrets_stored: { key: "secret", scale: 1, combine: "average" },
+    hq_mcp_calls: { key: "hq-mcp-call", scale: 1, combine: "sum" },
+    integration_calls: { key: "integration-call", scale: 1, combine: "sum" },
+    agent_runs: { key: "agent-run", scale: 1, combine: "sum" },
+    vaults: { key: "vault", scale: 1, combine: "average" },
+};
+/**
+ * Turn a month of daily rollup rows into meter readings: counters are summed
+ * across days, storage and secrets (daily levels) are averaged over the days
+ * that have a value. A meter with no value on any day is `not-available`,
+ * never zero. External MCP calls through HQ are counted as gateway calls
+ * (`integration_calls`).
+ */
+export function meterReadingsFromDailyRows(rows) {
+    const totals = new Map();
+    for (const row of rows) {
+        for (const [meter, spec] of Object.entries(ROLLUP_METERS)) {
+            const v = row.meters?.[meter];
+            if (typeof v !== "number" || !Number.isFinite(v))
+                continue;
+            const t = totals.get(spec.key) ?? { sum: 0, days: 0, combine: spec.combine };
+            t.sum += v * spec.scale;
+            t.days += 1;
+            totals.set(spec.key, t);
+        }
+    }
+    return BUNDLED_USAGE_METER_RATES.map(({ key }) => {
+        const t = totals.get(key);
+        if (!t || t.days === 0)
+            return { key, value: null, state: "not-available" };
+        return { key, value: t.combine === "average" ? t.sum / t.days : t.sum, state: "measured" };
+    });
+}
+/**
+ * The rollup as a source. `fetchRows` is the US-006 company-usage route (or
+ * `readCompanyRange` server-side) for the month to date. Pass this to
+ * {@link readMonthUsage} once that route ships; the company scope only.
+ */
+export function dailyRollupSource(fetchRows) {
+    return {
+        name: "daily-rollup",
+        async read(scope, now) {
+            const { start, end } = monthWindow(now);
+            const rows = await fetchRows(scope, start.toISOString().slice(0, 10), now.toISOString().slice(0, 10));
+            if (rows === null)
+                throw new Error("Could not read the daily usage rollup right now. Try again later.");
+            return {
+                scope,
+                source: "daily-rollup",
+                period: { start: start.toISOString(), end: end.toISOString(), asOf: now.toISOString() },
+                meters: meterReadingsFromDailyRows(rows),
+            };
+        },
+    };
+}
+/**
+ * The one function every caller uses to read a month of usage. Switch the
+ * default source here when the US-005 rollup has a read route.
+ */
+export async function readMonthUsage(scope, deps, source = usageLimitsSource(deps)) {
+    const now = deps.now();
+    const read = await source.read(scope, now);
+    const trialActive = deps.readTrialActive ? await deps.readTrialActive(scope).catch(() => null) : null;
+    const base = typeof trialActive === "boolean" ? { ...read, trialActive } : read;
+    if (scope.kind !== "company" || !deps.readStorageSplit)
+        return base;
+    const split = await deps.readStorageSplit(scope).catch(() => null);
+    if (!split)
+        return base;
+    // The live listing is fresher than the daily Storage Lens figure, so a prune
+    // shows up in the very next read.
+    const liveGb = (split.currentBytes + split.oldVersionBytes) / BYTES_PER_GB;
+    return {
+        ...base,
+        storage: split,
+        meters: base.meters.map((m) => (m.key === "storage" ? { key: m.key, value: liveGb, state: "measured" } : m)),
+    };
+}
+const round2 = (n) => Math.round(n * 100) / 100;
+export function computeBill(usage, rates = BUNDLED_USAGE_METER_RATES, allowanceUsd = USAGE_MONTHLY_ALLOWANCE_USD) {
+    const asOf = new Date(usage.period.asOf);
+    const { start, end } = monthWindow(asOf);
+    const dayMs = 86_400_000;
+    const daysInMonth = Math.round((end.getTime() - start.getTime()) / dayMs);
+    // At least a quarter day so a read just after midnight on the 1st does not
+    // project a few minutes of use across the whole month.
+    const daysElapsed = Math.min(daysInMonth, Math.max(0.25, (asOf.getTime() - start.getTime()) / dayMs));
+    const byKey = new Map(usage.meters.map((m) => [m.key, m]));
+    let mtd = 0;
+    let projected = 0;
+    let incomplete = false;
+    const meters = rates.map((rate) => {
+        const reading = byKey.get(rate.key) ?? { key: rate.key, value: null, state: "not-available" };
+        if (reading.state !== "measured" || reading.value === null) {
+            incomplete = true;
+            return { ...pick(rate), value: null, state: reading.state, monthToDateUsd: null, projectedUsd: null };
+        }
+        if (rate.waivedInTrial && usage.trialActive === true) {
+            return { ...pick(rate), value: reading.value, state: "measured", monthToDateUsd: 0, projectedUsd: 0, waivedInTrial: true };
+        }
+        const full = reading.value * rate.unitUsd;
+        const m = rate.kind === "gauge" ? full * (daysElapsed / daysInMonth) : full;
+        const p = rate.kind === "gauge" ? full : full * (daysInMonth / daysElapsed);
+        mtd += m;
+        projected += p;
+        return { ...pick(rate), value: reading.value, state: "measured", monthToDateUsd: round2(m), projectedUsd: round2(p) };
+    });
+    return {
+        meters,
+        monthToDateUsd: round2(mtd),
+        projectedUsd: round2(projected),
+        allowanceUsd,
+        allowanceLeftUsd: round2(Math.max(0, allowanceUsd - mtd)),
+        projectedBillUsd: round2(Math.max(0, projected - allowanceUsd)),
+        incomplete,
+        daysElapsed: round2(daysElapsed),
+        daysInMonth,
+    };
+}
+function pick(rate) {
+    return { key: rate.key, displayName: rate.displayName, unit: rate.unit, unitUsd: rate.unitUsd };
+}
+function gb(n) {
+    return n >= 10 ? n.toFixed(0) : n >= 1 ? n.toFixed(1) : n.toFixed(2);
+}
+function usd(n) {
+    return `$${n.toFixed(2)}`;
+}
+function companyFlag(scope) {
+    return scope.kind === "company" ? ` --company ${scope.companySlug}` : "";
+}
+function personalFlag(scope) {
+    return scope.kind === "person" ? " --personal" : "";
+}
+/** ISO date `days` before `now`, for prune cutoffs. */
+export function daysBefore(now, days) {
+    return new Date(now.getTime() - days * 86_400_000).toISOString().slice(0, 10);
+}
+export function excludeFoldersFix(scope) {
+    return {
+        id: "exclude-folders",
+        title: "Stop syncing folders you do not need in the cloud",
+        detail: "Add the folders to .hqignore in your HQ folder so sync skips them, or limit what this company downloads with " +
+            "`hq sync mode shared`. Files already in the cloud stay until you remove them; nothing is deleted.",
+        preview: ["hq sync mode --show", ...(scope.kind === "company" ? [`hq storage status${companyFlag(scope)} --json`] : [])],
+        apply: ["(edit <HQ folder>/.hqignore: add one line per folder, for example `bigfolder/`)"],
+        savesUsdPerMonth: null,
+    };
+}
+export function turnSyncOffFix() {
+    return {
+        id: "turn-sync-off",
+        title: "Turn cloud sync off and share through git",
+        detail: "Stops HQ cloud sync on this computer, so its syncs stop counting. HQ core, the CLI, DMs and deploys (through " +
+            "/deploy) keep working, and none of them needs a card. In the HQ desktop app, use its Cloud off switch once it " +
+            "ships; until then turn off its Settings > Sync switches. Without the app, `hq daemon sync pause` does it " +
+            "(resume with `hq daemon sync resume`). Files already in the cloud stay there and still count as storage until " +
+            "you remove them.",
+        preview: ["hq daemon sync status --json"],
+        apply: ["hq daemon sync pause"],
+        savesUsdPerMonth: null,
+    };
+}
+/**
+ * Biggest drivers first. Only measured meters with a cost become drivers; the
+ * turn-sync-off fix is always offered while a bill is projected.
+ */
+export function findDrivers(usage, bill) {
+    const drivers = [];
+    const now = new Date(usage.period.asOf);
+    const rate = (k) => bill.meters.find((m) => m.key === k)?.unitUsd ?? 0;
+    const cost = (k) => bill.meters.find((m) => m.key === k);
+    const scope = usage.scope;
+    const storage = cost("storage");
+    if (storage?.projectedUsd) {
+        const split = usage.storage;
+        if (split && split.oldVersionBytes > 0) {
+            const oldGb = split.oldVersionBytes / BYTES_PER_GB;
+            const cutoff = daysBefore(now, 30);
+            const target = scope.kind === "company" ? scope.companySlug : "";
+            drivers.push({
+                meter: "storage-old-versions",
+                summary: `Old file versions: ${gb(oldGb)} GB of earlier copies of files you have since changed (${usd(oldGb * rate("storage"))} a month).`,
+                projectedUsd: round2(oldGb * rate("storage")),
+                fixes: [
+                    {
+                        id: "prune-old-versions",
+                        title: "Delete old file versions older than 30 days",
+                        detail: `Deletes earlier versions of files in ${target} that were replaced before ${cutoff}. Current files are not touched. ` +
+                            "This cannot be undone.",
+                        preview: [`hq storage prune --cloud-before ${cutoff}${companyFlag(scope)} --dry-run --json`],
+                        apply: [`hq storage prune --cloud-before ${cutoff}${companyFlag(scope)} --yes --json`],
+                        savesUsdPerMonth: null,
+                        ...(split.canDelete ? {} : { blockedReason: "Only a company owner or admin can delete old versions. Ask your owner to run /hq-cost." }),
+                    },
+                ],
+            });
+        }
+        const currentGb = split ? split.currentBytes / BYTES_PER_GB : (storage.value ?? 0);
+        if (currentGb > 0) {
+            drivers.push({
+                meter: "storage-current",
+                summary: split
+                    ? `Stored files: ${gb(currentGb)} GB of current files in the cloud (${usd(currentGb * rate("storage"))} a month).`
+                    : `Stored files: ${gb(currentGb)} GB in the cloud, old versions included (${usd(currentGb * rate("storage"))} a month). ` +
+                        "Run without --no-storage-scan to see how much is old versions.",
+                projectedUsd: round2(currentGb * rate("storage")),
+                fixes: [excludeFoldersFix(scope)],
+            });
+        }
+    }
+    const secrets = cost("secret");
+    if (secrets?.projectedUsd && secrets.value) {
+        drivers.push({
+            meter: "secret",
+            summary: `Secrets: ${secrets.value} stored at ${usd(secrets.unitUsd)} each a month (${usd(secrets.projectedUsd)}).`,
+            projectedUsd: secrets.projectedUsd,
+            fixes: [
+                {
+                    id: "remove-unused-secrets",
+                    title: "Remove secrets nothing uses any more",
+                    detail: `Each secret you delete saves ${usd(secrets.unitUsd)} a month. HQ does not record when a secret was last read, ` +
+                        "so the list shows when each was last changed; you pick which to delete, one at a time. This cannot be undone.",
+                    preview: [`hq secrets${companyFlag(scope)}${personalFlag(scope)} list`],
+                    // --force skips the CLI's own TTY prompt. Run it only for a name the
+                    // user said yes to after seeing the list.
+                    apply: [`hq secrets${companyFlag(scope)}${personalFlag(scope)} delete <NAME> --force`],
+                    savesUsdPerMonth: secrets.unitUsd,
+                },
+            ],
+        });
+    }
+    const sync = cost("member-sync");
+    if (sync?.projectedUsd) {
+        drivers.push({
+            meter: "member-sync",
+            summary: `Syncs: ${Math.round(sync.value ?? 0)} so far this month (${usd(sync.projectedUsd)} at this pace). ` +
+                "A sync loop or a folder that changes all the time is the usual cause.",
+            projectedUsd: sync.projectedUsd,
+            fixes: [excludeFoldersFix(scope), turnSyncOffFix()],
+        });
+    }
+    for (const key of ["integration-call", "hq-mcp-call", "agent-run"]) {
+        const m = cost(key);
+        if (m?.projectedUsd) {
+            drivers.push({
+                meter: key,
+                summary: `${m.displayName}: ${gb(m.value ?? 0)} ${m.unit}s so far (${usd(m.projectedUsd)} at this pace).`,
+                projectedUsd: m.projectedUsd,
+                fixes: [],
+            });
+        }
+    }
+    drivers.sort((a, b) => b.projectedUsd - a.projectedUsd);
+    if (bill.projectedBillUsd > 0 || bill.incomplete) {
+        const hasSyncOff = drivers.some((d) => d.fixes.some((f) => f.id === "turn-sync-off"));
+        if (!hasSyncOff) {
+            drivers.push({
+                meter: "member-sync",
+                summary: bill.incomplete
+                    ? "Syncs are not counted here yet. If you do not need cloud sync, turning it off stops them."
+                    : "Cloud sync is on. If you do not need it, turning it off stops sync charges.",
+                projectedUsd: 0,
+                fixes: [turnSyncOffFix()],
+            });
+        }
+    }
+    return drivers;
+}
+// ── Report ──────────────────────────────────────────────────────────────────
+/** The self-hosted / no-sync guide the usage card links (feed `signup.selfHosted.url`). */
+export const NO_SYNC_GUIDE_URL = SELF_HOSTED_GUIDE_URL;
+export function buildReport(usage, rates) {
+    const bill = computeBill(usage, rates.rates, rates.allowanceUsd);
+    return {
+        scope: usage.scope,
+        source: usage.source,
+        rateSource: rates.source,
+        period: usage.period,
+        bill,
+        ...(usage.storage ? { storage: usage.storage } : {}),
+        ...(typeof usage.trialActive === "boolean" ? { trialActive: usage.trialActive } : {}),
+        freeItems: formatFreeItems(rates.card ?? BUNDLED_USAGE_CARD),
+        drivers: findDrivers(usage, bill),
+        noSyncGuideUrl: NO_SYNC_GUIDE_URL,
+        readOnly: true,
+    };
+}
+function rateText(m) {
+    const price = m.unitUsd >= 1 ? usd(m.unitUsd) : `$${m.unitUsd.toFixed(2)}`;
+    const trial = m.key === "vault" && !m.waivedInTrial ? ", waived during the trial" : "";
+    return `${price} per ${m.unit}${trial}`;
+}
+function valueText(m) {
+    if (m.state === "not-available")
+        return "not counted here yet";
+    if (m.state === "unknown" || m.value === null)
+        return "could not be read";
+    if (m.key === "storage")
+        return `${gb(m.value)} GB`;
+    if (m.key === "vault")
+        return `${Math.round(m.value)} vault${Math.round(m.value) === 1 ? "" : "s"}`;
+    return `${Math.round(m.value)}`;
+}
+export function formatReport(r) {
+    const who = r.scope.kind === "company" ? r.scope.companySlug : "your personal HQ";
+    const month = r.period.start.slice(0, 7);
+    const lines = [];
+    lines.push(`Usage for ${who}, ${month} (day ${Math.floor(r.bill.daysElapsed) + 1} of ${r.bill.daysInMonth})`);
+    lines.push("");
+    const nameW = Math.max(...r.bill.meters.map((m) => m.displayName.length));
+    for (const m of r.bill.meters) {
+        const cost = m.waivedInTrial
+            ? "  waived during the trial"
+            : m.projectedUsd === null
+                ? ""
+                : `  ${usd(m.projectedUsd)} projected`;
+        lines.push(`  ${m.displayName.padEnd(nameW)}  ${valueText(m)}${cost}  (${rateText(m)})`);
+    }
+    lines.push(`  Free, no limit: ${r.freeItems}.`);
+    lines.push("");
+    const atLeast = r.bill.incomplete ? "at least " : "";
+    lines.push(`Used so far: ${atLeast}${usd(r.bill.monthToDateUsd)} of the ${usd(r.bill.allowanceUsd)} included each month (${usd(r.bill.allowanceLeftUsd)} left${r.bill.incomplete ? " at most" : ""}).`);
+    lines.push(`Projected for the month: ${atLeast}${usd(r.bill.projectedUsd)}. Projected bill after the included usage: ${atLeast}${usd(r.bill.projectedBillUsd)}.`);
+    if (r.scope.kind === "person") {
+        lines.push("Your personal account has its own $" + r.bill.allowanceUsd.toFixed(0) + " free each month; usage above it is billed to you.");
+    }
+    if (r.bill.incomplete) {
+        lines.push("Some meters are not counted here yet (they arrive with the daily usage rollup), so the real figures can be higher.");
+    }
+    if (r.drivers.length > 0) {
+        lines.push("");
+        lines.push("Biggest drivers:");
+        for (const d of r.drivers) {
+            lines.push(`  - ${d.summary}`);
+            for (const f of d.fixes) {
+                lines.push(`      Fix: ${f.title}${f.blockedReason ? ` (${f.blockedReason})` : ""}`);
+                lines.push(`        Preview: ${f.preview.join("; ")}`);
+            }
+        }
+    }
+    lines.push("");
+    lines.push("No card is needed to sign in, deploy or use DMs.");
+    lines.push("This command only reads. Run /hq-cost in Claude Code to preview and apply a fix with your yes.");
+    lines.push(`Use HQ free, self-hosted or on-prem: ${r.noSyncGuideUrl}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=usage-cost.js.map

package/dist/lib/billing/usage-only.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Is this account on usage pricing? (usage-only-pricing landing 2026-10-16, US-012)
+ *
+ * The signal is hq-pro's own `pricingPlan: "usage-only" | "current"` field,
+ * never a local guess. Sources, first answer wins:
+ *
+ *   - Company:
+ *     1. the company's row in `GET /membership/me` (hq-pro #5042; every member
+ *        sees it),
+ *     2. `GET /v1/billing/usage-limits?companyUid=` (hq-pro #5042; members),
+ *     3. `GET /v1/billing/summary?companyUid=` (hq-pro US-002; owner-gated,
+ *        403 for a non-owner).
+ *   - Person:
+ *     1. `GET /v1/billing/person/usage-limits` (hq-pro #5042),
+ *     2. `GET /v1/billing/person/summary`, which carries a `personalUsage`
+ *        block only for a person on usage-only pricing (hq-pro US-004).
+ *
+ * Any other decoded hq-pro body that carries the same fields is read the same
+ * way ({@link pricingPlanFromBody}).
+ *
+ * UNKNOWN (null) keeps the legacy copy: existing customers see exactly what
+ * they saw before, and an account is only told about usage pricing when the
+ * server said so.
+ */
+import { type UsageCard } from "./usage-card.js";
+export type PricingPlan = "usage-only" | "current";
+/**
+ * Read the pricing plan out of a decoded hq-pro body. `pricingPlan` wins;
+ * a `personalUsage` object (person summary) means usage-only. Anything else
+ * is UNKNOWN.
+ */
+export declare function pricingPlanFromBody(body: unknown): PricingPlan | null;
+export declare function isUsageOnly(plan: PricingPlan | null | undefined): boolean;
+/** True when a company summary says a usage-only trial is running. Absent is false. */
+export declare function usageTrialActiveFromBody(body: unknown): boolean;
+export interface PricingPlanFetchDeps {
+    /** GET a summary path. Resolves the decoded body, or null when it did not answer. */
+    getJson?: (token: string, path: string, query?: Record<string, string>) => Promise<unknown | null>;
+    /** Per-request timeout. */
+    timeoutMs?: number;
+    /**
+     * Whole-lookup deadline across every source (default 6000 ms). Past it the
+     * plan is unknown and the caller keeps the legacy copy, so a slow or
+     * unreachable API can never hold a refusal message hostage.
+     */
+    deadlineMs?: number;
+}
+/** Test-only: forget cached reads. */
+export declare function _resetPricingPlanCacheForTests(): void;
+/**
+ * The pricing plan on a company's row of a decoded `/membership/me` body,
+ * matched by uid or slug. Null when the row or the field is absent.
+ */
+export declare function pricingPlanFromMembership(body: unknown, companyRef: string): PricingPlan | null;
+/** The company billing summary body, read once per process. Null when unreadable. */
+export declare function fetchCompanyBillingSummary(token: string, companyUid: string, deps?: PricingPlanFetchDeps): Promise<unknown | null>;
+export declare function fetchCompanyPricingPlan(token: string, companyUid: string, deps?: PricingPlanFetchDeps): Promise<PricingPlan | null>;
+/** The caller's personal pricing plan (person usage-limits, then summary). Null when unknown. */
+export declare function fetchPersonPricingPlan(token: string, deps?: PricingPlanFetchDeps): Promise<PricingPlan | null>;
+/**
+ * Best-effort, non-interactive: resolve the token and company, then the plan.
+ * For error paths that do not already hold a token. Never throws and never
+ * opens a browser sign-in.
+ */
+export declare function resolveCompanyPricingPlan(company?: string, deps?: PricingPlanFetchDeps): Promise<PricingPlan | null>;
+/** Best-effort person-scope counterpart of {@link resolveCompanyPricingPlan}. */
+export declare function resolvePersonPricingPlan(deps?: PricingPlanFetchDeps): Promise<PricingPlan | null>;
+/** One sentence every usage-only surface uses to point at the bill. */
+export declare const USAGE_PRICING_POINTER = "Run `hq billing usage` for this month's usage, the included usage left and the projected bill.";
+/** "It pays per use, with <included> of usage included each month." */
+export declare function usageIncludedSentence(card?: UsageCard): string;
+/** `hq billing upgrade` for a usage-only company. */
+export declare function usageOnlyUpgradeLines(card?: UsageCard): string[];
+/** The `Plan:` orientation line (`hq whoami --plan`) for a usage-only company. */
+export declare function usageOnlyPlanLine(card?: UsageCard): string;
+/** Agent boxes on usage pricing, priced by size from the card. */
+export declare function usageOnlyBoxSentence(card?: UsageCard): string;
+/**
+ * A refusal that a legacy account answers by upgrading its plan. On usage
+ * pricing there is no plan: the account adds a card and pays per use.
+ */
+export declare function usageOnlyCardRequiredLines(what: string, card?: UsageCard): string[];
+/** `hq billing sponsor request` for a person on usage pricing. */
+export declare function usageOnlySponsorLines(card?: UsageCard): string[];
+/** A personal feature refusal for a person on usage pricing. */
+export declare function usageOnlyPersonalFeatureNotice(label: string): string;
+//# sourceMappingURL=usage-only.d.ts.map