@indigoai-us/hq-cli 5.345.143 → 5.345.145

package/dist/hq-cloud-sync-runner/package.json

@@ -1 +1 @@
-{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.77","bundleSha256":"73de73de427e8e81b321541a5b8f41cdbd60a3dda4fae9ca5577c9ec4a671732","formatVersion":1}
+{"name":"hq-cli-daemon-sync-runner","type":"module","version":"6.18.82","bundleSha256":"0bf6cd65150094c035cb4ee532c00bde78d030ad0d2132aa606c566f11997f41","formatVersion":1}

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

@@ -21,6 +21,7 @@
  * missing data (hq-absent-field-never-means-constraining-value).
  */
 import { parseFreeMonth, type PlanLimitFreeMonth } from "./free-month.js";
+import { type PricingPlan } from "./usage-only.js";
 export { parseFreeMonth, type PlanLimitFreeMonth };
 /**
  * Dimensions the bind notice names with a remedy. Owner decision 7 (2026-09-17)
@@ -50,6 +51,13 @@ export interface PlanLimitStatus {
      * silent rather than assume either way.
      */
     plan?: "free" | "paid" | "enterprise";
+    /**
+     * Usage pricing (US-012). `"usage-only"` when hq-pro says the company is on
+     * usage pricing: Starter caps, the free month and the Workforce upgrade do
+     * not apply, and every renderer below says so instead. Absent = unknown,
+     * which keeps the legacy copy.
+     */
+    pricingPlan?: PricingPlan;
     checkedAt: string;
 }
 /** Starter member cap quoted when the server did not send a users.limit. */
@@ -85,6 +93,11 @@ export declare function selectMemberUsage(body: unknown): PlanLimitMembers | nul
  */
 export declare function selectOverReasons(body: unknown): PlanLimitReason[];
 export declare function selectUsages(body: unknown): Partial<Record<PlanLimitReason, PlanLimitMembers>>;
+/**
+ * Attach the pricing plan. A usage-only company is never "over its Starter
+ * limits" and is never offered the Starter free month: it has no Starter caps.
+ */
+export declare function applyPricingPlan(status: PlanLimitStatus, pricingPlan: PricingPlan | null | undefined): PlanLimitStatus;
 /**
  * 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
@@ -121,7 +134,8 @@ export declare function renderPlanLimitNotice(status: PlanLimitStatus, opts?: {
 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.
+ * workspace — and an UNKNOWN plan — gets no line at all. A usage-pricing
+ * company gets the usage line instead.
  */
 export declare function renderPlanLine(status: PlanLimitStatus): string | null;
 /**

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

@@ -25,6 +25,7 @@ import { diagnosticsEnabled } from "../diagnostics.js";
 import { vaultApiFetch } from "../../utils/vault-api.js";
 import { parseFreeMonth } from "./free-month.js";
 import { selectPlanLimitUpgradeUrl } from "./plan-limit-upgrade-url.js";
+import { fetchCompanyPricingPlan, isUsageOnly, pricingPlanFromBody, pricingPlanFromMembership, usageOnlyPlanLine, usageOnlyUpgradeLines, } from "./usage-only.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.
@@ -198,7 +199,8 @@ function statusFromUsage(companySlug, companyUid, body, upgradeCompanySlug) {
     const reasons = selectOverReasons(body);
     const rec = asRecord(body);
     const anyOverFlag = rec?.anyOver === true;
-    return {
+    const pricingPlan = pricingPlanFromBody(body);
+    return applyPricingPlan({
         companySlug,
         companyUid,
         over: anyOverFlag || reasons.length > 0,
@@ -209,6 +211,23 @@ function statusFromUsage(companySlug, companyUid, body, upgradeCompanySlug) {
         freeMonth: parseFreeMonth(rec?.freeMonth),
         plan: selectPlan(body) ?? undefined,
         checkedAt: new Date().toISOString(),
+    }, pricingPlan);
+}
+/**
+ * Attach the pricing plan. A usage-only company is never "over its Starter
+ * limits" and is never offered the Starter free month: it has no Starter caps.
+ */
+export function applyPricingPlan(status, pricingPlan) {
+    if (!pricingPlan)
+        return status;
+    if (!isUsageOnly(pricingPlan))
+        return { ...status, pricingPlan };
+    return {
+        ...status,
+        pricingPlan,
+        over: false,
+        reasons: [],
+        freeMonth: undefined,
     };
 }
 function isSilentPlanLimitBodyError(error) {
@@ -235,10 +254,11 @@ export async function fetchPlanLimitStatus(token, companyRef, opts = {}) {
     });
     if (!res.ok)
         return null;
-    const selected = selectCompanyMembership(await res.json().catch((error) => {
+    const membershipBody = await res.json().catch((error) => {
         notePlanLimitBodyUnreadable(error);
         return null;
-    }), companyRef);
+    });
+    const selected = selectCompanyMembership(membershipBody, companyRef);
     if (!selected?.companyUid)
         return null;
     try {
@@ -258,7 +278,18 @@ export async function fetchPlanLimitStatus(token, companyRef, opts = {}) {
             return null;
         const selectedSlug = selected.companySlug ??
             (!companyRef.startsWith("cmp_") ? companyRef : undefined);
-        return statusFromUsage(companyRef, selected.companyUid, body, selectedSlug);
+        const status = statusFromUsage(companyRef, selected.companyUid, body, selectedSlug);
+        if (status.pricingPlan)
+            return status;
+        // Older hq-pro: usage-limits has no pricingPlan. Try the membership row,
+        // then the (owner-gated) billing summary. Unknown keeps the legacy copy.
+        const fromRow = pricingPlanFromMembership(membershipBody, selected.companyUid);
+        if (fromRow)
+            return applyPricingPlan(status, fromRow);
+        const pricingPlan = await fetchCompanyPricingPlan(token, selected.companyUid, {
+            timeoutMs,
+        }).catch(() => null);
+        return applyPricingPlan(status, pricingPlan);
     }
     catch {
         return null;
@@ -380,6 +411,9 @@ function capitalize(text) {
 export function renderPlanLimitNotice(status, opts = {}) {
     const { companySlug, freeMonth } = status;
     const lines = [];
+    if (isUsageOnly(status.pricingPlan)) {
+        return [`${companySlug}:`, ...usageOnlyUpgradeLines().map((l) => `  ${l}`)].join("\n");
+    }
     lines.push(`HQ Starter — ${companySlug} is over its plan limits.`);
     const reasons = status.reasons.length
         ? status.reasons.map(reasonLabel).join("; ")
@@ -420,6 +454,9 @@ export function renderPlanLimitNotice(status, opts = {}) {
  * Kept to a single line on purpose — it repeats each turn.
  */
 export function renderPlanLimitLine(status) {
+    if (isUsageOnly(status.pricingPlan)) {
+        return `Company ${status.companySlug} is on usage pricing. ${usageOnlyUpgradeLines()[2]}`;
+    }
     const detail = status.reasons.length
         ? status.reasons.map((reason) => reasonDetail(reason, status)).join("; ")
         : "over the Starter plan limits";
@@ -428,9 +465,12 @@ export function renderPlanLimitLine(status) {
 }
 /**
  * The `Plan: …` orientation line. Starter only: a paid or enterprise
- * workspace — and an UNKNOWN plan — gets no line at all.
+ * workspace — and an UNKNOWN plan — gets no line at all. A usage-pricing
+ * company gets the usage line instead.
  */
 export function renderPlanLine(status) {
+    if (isUsageOnly(status.pricingPlan))
+        return usageOnlyPlanLine();
     if (status.over)
         return "Plan: Starter — over its limits";
     if (status.plan !== "free")

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

@@ -0,0 +1,82 @@
+/**
+ * The usage pricing card (usage-only-pricing landing 2026-10-16, US-012).
+ *
+ * hq-pro owns the numbers and publishes them in the `usage` block of
+ * `GET /v1/pricing`. Every CLI surface that quotes a usage price (meters, the
+ * included amount, the trial, box sizes, domains) reads the card through this
+ * module and nowhere else:
+ *
+ *   - {@link fetchUsageCard} reads the feed and falls back to the bundled card
+ *     when the feed is offline, slow, or has no `usage` block yet.
+ *   - {@link BUNDLED_USAGE_CARD} is the fallback. It equals the feed contract in
+ *     companies/indigo/projects/usage-only-pricing/landing-2026-10-16/README.md.
+ *
+ * Field-level fallback: a feed that sends a `usage` block with one malformed
+ * field keeps the feed's other fields and takes the bundled value for that one
+ * field. Unknown meter ids are kept (they render with their own label and
+ * price); malformed meter or box rows are dropped.
+ */
+export interface UsageCardMeter {
+    readonly id: string;
+    readonly label: string;
+    readonly unit: string;
+    readonly unitUsd: number;
+    /** True when the meter is not billed while a trial runs (the vault fee). */
+    readonly waivedInTrial?: boolean;
+}
+export interface UsageCardBox {
+    readonly size: string;
+    readonly instanceType: string;
+    readonly monthlyUsd: number;
+}
+export interface UsageCard {
+    readonly version: string;
+    readonly newSignupsFrom: string;
+    readonly includedUsd: number;
+    readonly trial: {
+        readonly days: number;
+        readonly capUsd: number;
+    };
+    readonly meters: readonly UsageCardMeter[];
+    readonly boxes: readonly UsageCardBox[];
+    readonly free: readonly string[];
+    readonly domains: {
+        readonly standardUsd: number;
+        readonly premiumUsd: number;
+    };
+}
+export type UsageCardSource = "feed" | "bundled";
+export interface ResolvedUsageCard {
+    card: UsageCard;
+    source: UsageCardSource;
+}
+/** The feed contract, verbatim. Used whenever the feed has no usable `usage` block. */
+export declare const BUNDLED_USAGE_CARD: UsageCard;
+/** The self-hosted / on-prem guide the card links for teams that want no cloud bill. */
+export declare const SELF_HOSTED_GUIDE_URL = "https://docs.hq.computer/hq/guide/use-hq-for-free/";
+/**
+ * Parse the `usage` block of a `GET /v1/pricing` body. Returns null when the
+ * body has no `usage` object at all (the feed before hq-pro ships it).
+ */
+export declare function parseUsageCard(body: unknown): UsageCard | null;
+/** The card from a feed body, or the bundled card when the body has none. */
+export declare function usageCardFromPricingFeed(body: unknown): ResolvedUsageCard;
+export interface FetchUsageCardDeps {
+    /** GET /v1/pricing. Resolves the decoded body, or null when it did not answer. */
+    fetchPricing?: () => Promise<unknown | null>;
+    timeoutMs?: number;
+}
+/**
+ * Read the card from the feed. Never throws: an offline feed, a non-2xx, or a
+ * body without `usage` all resolve to the bundled card.
+ */
+export declare function fetchUsageCard(deps?: FetchUsageCardDeps): Promise<ResolvedUsageCard>;
+/** `$0.10`, `$2.00`, `$100`: cents only when the amount has them or is under $10. */
+export declare function formatCardUsd(amount: number): string;
+/** "small (t3.small) $100/month, medium (t3.medium) $200/month, ..." */
+export declare function formatBoxQuotes(card?: UsageCard): string;
+/** "deploys, DMs and background AI" */
+export declare function formatFreeItems(card?: UsageCard): string;
+/** The whole card as plain lines, for `hq billing usage --card` and help text. */
+export declare function formatUsageCardLines(card?: UsageCard): string[];
+//# sourceMappingURL=usage-card.d.ts.map

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

@@ -0,0 +1,198 @@
+/**
+ * The usage pricing card (usage-only-pricing landing 2026-10-16, US-012).
+ *
+ * hq-pro owns the numbers and publishes them in the `usage` block of
+ * `GET /v1/pricing`. Every CLI surface that quotes a usage price (meters, the
+ * included amount, the trial, box sizes, domains) reads the card through this
+ * module and nowhere else:
+ *
+ *   - {@link fetchUsageCard} reads the feed and falls back to the bundled card
+ *     when the feed is offline, slow, or has no `usage` block yet.
+ *   - {@link BUNDLED_USAGE_CARD} is the fallback. It equals the feed contract in
+ *     companies/indigo/projects/usage-only-pricing/landing-2026-10-16/README.md.
+ *
+ * Field-level fallback: a feed that sends a `usage` block with one malformed
+ * field keeps the feed's other fields and takes the bundled value for that one
+ * field. Unknown meter ids are kept (they render with their own label and
+ * price); malformed meter or box rows are dropped.
+ */
+import { vaultApiFetchPublic } from "../../utils/vault-api.js";
+/** The feed contract, verbatim. Used whenever the feed has no usable `usage` block. */
+export const BUNDLED_USAGE_CARD = {
+    version: "2026-10-16",
+    newSignupsFrom: "2026-10-16T18:00:00Z",
+    includedUsd: 10,
+    trial: { days: 30, capUsd: 500 },
+    meters: [
+        { id: "member-sync", label: "Sync", unit: "sync", unitUsd: 0.1 },
+        { id: "integration-call", label: "Gateway call", unit: "call", unitUsd: 0.05 },
+        { id: "hq-mcp-call", label: "HQ MCP call", unit: "call", unitUsd: 0.05 },
+        { id: "agent-run", label: "Agent run", unit: "run", unitUsd: 0.05 },
+        { id: "storage", label: "Storage", unit: "GB-month", unitUsd: 2 },
+        { id: "secret", label: "Secret", unit: "secret-month", unitUsd: 0.5 },
+        { id: "vault", label: "Vault", unit: "vault-month", unitUsd: 5, waivedInTrial: true },
+    ],
+    boxes: [
+        { size: "small", instanceType: "t3.small", monthlyUsd: 100 },
+        { size: "medium", instanceType: "t3.medium", monthlyUsd: 200 },
+        { size: "large", instanceType: "t3.large", monthlyUsd: 400 },
+        { size: "xlarge", instanceType: "t3.xlarge", monthlyUsd: 800 },
+    ],
+    free: ["deploys", "dms", "background-ai"],
+    domains: { standardUsd: 20, premiumUsd: 500 },
+};
+/** The self-hosted / on-prem guide the card links for teams that want no cloud bill. */
+export const SELF_HOSTED_GUIDE_URL = "https://docs.hq.computer/hq/guide/use-hq-for-free/";
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function nonNegative(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : null;
+}
+function nonEmpty(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function parseMeter(raw) {
+    const rec = asRecord(raw);
+    if (!rec)
+        return null;
+    const id = nonEmpty(rec.id);
+    const label = nonEmpty(rec.label);
+    const unit = nonEmpty(rec.unit);
+    const unitUsd = nonNegative(rec.unitUsd);
+    if (!id || !label || !unit || unitUsd === null)
+        return null;
+    return { id, label, unit, unitUsd, ...(rec.waivedInTrial === true ? { waivedInTrial: true } : {}) };
+}
+function parseBox(raw) {
+    const rec = asRecord(raw);
+    if (!rec)
+        return null;
+    const size = nonEmpty(rec.size);
+    const instanceType = nonEmpty(rec.instanceType);
+    const monthlyUsd = nonNegative(rec.monthlyUsd);
+    if (!size || !instanceType || monthlyUsd === null)
+        return null;
+    return { size, instanceType, monthlyUsd };
+}
+function rows(raw, parse) {
+    if (!Array.isArray(raw))
+        return null;
+    const out = raw.map(parse).filter((row) => row !== null);
+    return out.length > 0 ? out : null;
+}
+/**
+ * Parse the `usage` block of a `GET /v1/pricing` body. Returns null when the
+ * body has no `usage` object at all (the feed before hq-pro ships it).
+ */
+export function parseUsageCard(body) {
+    const usage = asRecord(asRecord(body)?.usage);
+    if (!usage)
+        return null;
+    const bundled = BUNDLED_USAGE_CARD;
+    const trial = asRecord(usage.trial);
+    const trialDays = nonNegative(trial?.days);
+    const trialCap = nonNegative(trial?.capUsd);
+    const domains = asRecord(usage.domains);
+    const standardUsd = nonNegative(domains?.standardUsd);
+    const premiumUsd = nonNegative(domains?.premiumUsd);
+    const free = Array.isArray(usage.free)
+        ? usage.free.filter((v) => typeof v === "string" && v.trim().length > 0)
+        : null;
+    return {
+        version: nonEmpty(usage.version) ?? bundled.version,
+        newSignupsFrom: nonEmpty(usage.newSignupsFrom) ?? bundled.newSignupsFrom,
+        includedUsd: nonNegative(usage.includedUsd) ?? bundled.includedUsd,
+        trial: {
+            days: trialDays ?? bundled.trial.days,
+            capUsd: trialCap ?? bundled.trial.capUsd,
+        },
+        meters: rows(usage.meters, parseMeter) ?? bundled.meters,
+        boxes: rows(usage.boxes, parseBox) ?? bundled.boxes,
+        free: free && free.length > 0 ? free : bundled.free,
+        domains: {
+            standardUsd: standardUsd ?? bundled.domains.standardUsd,
+            premiumUsd: premiumUsd ?? bundled.domains.premiumUsd,
+        },
+    };
+}
+/** The card from a feed body, or the bundled card when the body has none. */
+export function usageCardFromPricingFeed(body) {
+    const card = parseUsageCard(body);
+    return card ? { card, source: "feed" } : { card: BUNDLED_USAGE_CARD, source: "bundled" };
+}
+async function defaultFetchPricing(timeoutMs) {
+    let timer;
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(null), timeoutMs);
+        timer.unref?.();
+    });
+    const read = (async () => {
+        const res = await vaultApiFetchPublic({ path: "/v1/pricing" });
+        if (!res.ok)
+            return null;
+        return res.json().catch(() => null);
+    })();
+    try {
+        return await Promise.race([read, timeout]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+/**
+ * Read the card from the feed. Never throws: an offline feed, a non-2xx, or a
+ * body without `usage` all resolve to the bundled card.
+ */
+export async function fetchUsageCard(deps = {}) {
+    const timeoutMs = deps.timeoutMs ?? 5000;
+    try {
+        const body = await (deps.fetchPricing ? deps.fetchPricing() : defaultFetchPricing(timeoutMs));
+        return usageCardFromPricingFeed(body);
+    }
+    catch {
+        return { card: BUNDLED_USAGE_CARD, source: "bundled" };
+    }
+}
+// ── Rendering ────────────────────────────────────────────────────────────────
+/** `$0.10`, `$2.00`, `$100`: cents only when the amount has them or is under $10. */
+export function formatCardUsd(amount) {
+    return Number.isInteger(amount) && amount >= 10 ? `$${amount}` : `$${amount.toFixed(2)}`;
+}
+/** "small (t3.small) $100/month, medium (t3.medium) $200/month, ..." */
+export function formatBoxQuotes(card = BUNDLED_USAGE_CARD) {
+    return card.boxes
+        .map((b) => `${b.size} (${b.instanceType}) ${formatCardUsd(b.monthlyUsd)}/month`)
+        .join(", ");
+}
+const FREE_LABELS = {
+    deploys: "deploys",
+    dms: "DMs",
+    "background-ai": "background AI",
+};
+/** "deploys, DMs and background AI" */
+export function formatFreeItems(card = BUNDLED_USAGE_CARD) {
+    const items = card.free.map((f) => FREE_LABELS[f] ?? f);
+    if (items.length <= 1)
+        return items.join("");
+    return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+/** The whole card as plain lines, for `hq billing usage --card` and help text. */
+export function formatUsageCardLines(card = BUNDLED_USAGE_CARD) {
+    const lines = [];
+    const nameW = Math.max(...card.meters.map((m) => m.label.length));
+    for (const m of card.meters) {
+        const waived = m.waivedInTrial ? " (waived during the trial)" : "";
+        lines.push(`  ${m.label.padEnd(nameW)}  ${formatCardUsd(m.unitUsd)} per ${m.unit}${waived}`);
+    }
+    lines.push(`Included usage: ${formatCardUsd(card.includedUsd)} per month.`);
+    lines.push(`Trial: ${card.trial.days} days, capped at ${formatCardUsd(card.trial.capUsd)} of usage.`);
+    lines.push(`Boxes: ${formatBoxQuotes(card)}.`);
+    lines.push(`Free: ${formatFreeItems(card)}.`);
+    lines.push(`Domains: ${formatCardUsd(card.domains.standardUsd)} standard, ${formatCardUsd(card.domains.premiumUsd)} premium.`);
+    return lines;
+}
+//# sourceMappingURL=usage-card.js.map

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

@@ -0,0 +1,214 @@
+/**
+ * `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 { type UsageCard } from "./usage-card.js";
+import { type UsageMeterKey, type UsageMeterRate } from "./usage-rate-card.js";
+/** Bytes per billed GB. Storage is billed like S3: 1 GB = 2^30 bytes. */
+export declare const BYTES_PER_GB: number;
+export type UsageScope = {
+    kind: "company";
+    companyUid: string;
+    companySlug: string;
+    role?: string;
+} | {
+    kind: "person";
+};
+export type MeterState = "measured" | "unknown" | "not-available";
+export interface MeterReading {
+    key: UsageMeterKey;
+    /** In billed units (GB for storage). Null unless measured. */
+    value: number | null;
+    state: MeterState;
+}
+export interface StorageSplit {
+    /** Bytes in current files. */
+    currentBytes: number;
+    /** Bytes in old (noncurrent) versions. */
+    oldVersionBytes: number;
+    oldVersionCount: number;
+    /** When the listing was taken (ISO). */
+    listedAt?: string;
+    /** Whether the caller may prune old versions (owner or admin). */
+    canDelete: boolean;
+}
+export interface MonthUsage {
+    scope: UsageScope;
+    /** Which source answered; lets a reader tell interim numbers from the rollup. */
+    source: "usage-limits" | "daily-rollup";
+    /** Month-to-date window, UTC. */
+    period: {
+        start: string;
+        end: string;
+        asOf: string;
+    };
+    meters: MeterReading[];
+    storage?: StorageSplit;
+    /** True when the account's usage trial is running (meters waived in trial bill $0). Absent = unknown. */
+    trialActive?: boolean;
+}
+/** One way to read a month of usage. The rollup becomes a second implementation. */
+export interface MonthUsageSource {
+    name: MonthUsage["source"];
+    read(scope: UsageScope, now: Date): Promise<Omit<MonthUsage, "storage">>;
+}
+export interface ReadMonthUsageDeps {
+    /** GET a usage-limits body for the scope. Null when the server did not answer. */
+    fetchUsageLimits(scope: UsageScope): Promise<unknown | null>;
+    /** Live cloud file-history split for a company. Absent or null skips the split. */
+    readStorageSplit?: (scope: Extract<UsageScope, {
+        kind: "company";
+    }>) => Promise<StorageSplit | null>;
+    /** Whether the usage trial is running. Null or absent = unknown. */
+    readTrialActive?: (scope: UsageScope) => Promise<boolean | null>;
+    now(): Date;
+}
+export declare function monthWindow(now: Date): {
+    start: Date;
+    end: Date;
+};
+/** Today's source: plan usage-limits (storage bytes, secrets). */
+export declare function usageLimitsSource(deps: Pick<ReadMonthUsageDeps, "fetchUsageLimits">): MonthUsageSource;
+/**
+ * One day of the US-005 rollup (`UsageDailyRow` in hq-pro
+ * `src/billing/usage-meter-rollup.ts`, read with `readCompanyRange`). Only the
+ * fields this reader needs. An absent meter key means unknown, never zero.
+ */
+export interface UsageDailyRowLike {
+    day: string;
+    meters: Partial<Record<RollupMeter, number>>;
+    unknownMeters?: string[];
+}
+type RollupMeter = "storage_bytes" | "secrets_stored" | "hq_mcp_calls" | "integration_calls" | "agent_runs" | "member_syncs" | "vaults";
+/**
+ * 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 declare function meterReadingsFromDailyRows(rows: readonly UsageDailyRowLike[]): MeterReading[];
+/**
+ * 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 declare function dailyRollupSource(fetchRows: (scope: UsageScope, from: string, to: string) => Promise<readonly UsageDailyRowLike[] | null>): MonthUsageSource;
+/**
+ * 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 declare function readMonthUsage(scope: UsageScope, deps: ReadMonthUsageDeps, source?: MonthUsageSource): Promise<MonthUsage>;
+export interface MeterCost {
+    key: UsageMeterKey;
+    displayName: string;
+    unit: string;
+    unitUsd: number;
+    value: number | null;
+    state: MeterState;
+    /** Cost so far this month (gauges prorated by days elapsed). Null unless measured. */
+    monthToDateUsd: number | null;
+    /** Cost if the month ends at this pace (gauges at today's amount). Null unless measured. */
+    projectedUsd: number | null;
+    /** Not billed because the trial is running (vault fee). */
+    waivedInTrial?: boolean;
+}
+export interface UsageBill {
+    meters: MeterCost[];
+    monthToDateUsd: number;
+    projectedUsd: number;
+    allowanceUsd: number;
+    allowanceLeftUsd: number;
+    /** What would be invoiced at month end: projected cost above the allowance. */
+    projectedBillUsd: number;
+    /** True when any meter is not measured: the real bill can only be higher. */
+    incomplete: boolean;
+    daysElapsed: number;
+    daysInMonth: number;
+}
+export declare function computeBill(usage: MonthUsage, rates?: readonly UsageMeterRate[], allowanceUsd?: number): UsageBill;
+export type FixId = "prune-old-versions" | "remove-unused-secrets" | "exclude-folders" | "turn-sync-off";
+/**
+ * A fix is a pair of command lists. `preview` only reads (dry runs, listings);
+ * `apply` changes something and must only run after the user has seen the
+ * preview and said yes. This module never runs either.
+ */
+export interface Fix {
+    id: FixId;
+    title: string;
+    /** Plain words: what changes and what does not. */
+    detail: string;
+    preview: string[];
+    apply: string[];
+    /** Monthly saving if known, in USD. */
+    savesUsdPerMonth: number | null;
+    /** Set when the caller cannot apply this fix themselves. */
+    blockedReason?: string;
+}
+export interface Driver {
+    meter: UsageMeterKey | "storage-old-versions" | "storage-current";
+    /** One plain sentence naming what is costing money. */
+    summary: string;
+    projectedUsd: number;
+    fixes: Fix[];
+}
+/** ISO date `days` before `now`, for prune cutoffs. */
+export declare function daysBefore(now: Date, days: number): string;
+export declare function excludeFoldersFix(scope: UsageScope): Fix;
+export declare function turnSyncOffFix(): Fix;
+/**
+ * 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 declare function findDrivers(usage: MonthUsage, bill: UsageBill): Driver[];
+/** The self-hosted / no-sync guide the usage card links (feed `signup.selfHosted.url`). */
+export declare const NO_SYNC_GUIDE_URL = "https://docs.hq.computer/hq/guide/use-hq-for-free/";
+export interface UsageReport {
+    scope: UsageScope;
+    source: MonthUsage["source"];
+    rateSource: "published" | "bundled";
+    period: MonthUsage["period"];
+    bill: UsageBill;
+    storage?: StorageSplit;
+    /** Whether the usage trial is running. Absent = unknown. */
+    trialActive?: boolean;
+    /** What the card lists as free, in words. */
+    freeItems: string;
+    drivers: Driver[];
+    noSyncGuideUrl: string;
+    readOnly: true;
+}
+export declare function buildReport(usage: MonthUsage, rates: {
+    rates: readonly UsageMeterRate[];
+    allowanceUsd: number;
+    source: "published" | "bundled";
+    card?: UsageCard;
+}): UsageReport;
+export declare function formatReport(r: UsageReport): string;
+export {};
+//# sourceMappingURL=usage-cost.d.ts.map