@indigoai-us/hq-cli 5.345.142 → 5.345.144

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

@@ -0,0 +1,262 @@
+/**
+ * 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 { BUNDLED_USAGE_CARD, formatBoxQuotes, formatCardUsd, } from "./usage-card.js";
+// Static imports on purpose: resident command paths (agents, daemon, ...) may
+// not lazy-load packages (src/utils/resident-package-preload.test.ts).
+// vault-api loads plan-limit-nag with a dynamic import, so there is no
+// static cycle through this module.
+import * as vaultApi from "../../utils/vault-api.js";
+import * as cognitoSession from "../../utils/cognito-session.js";
+async function http() {
+    return vaultApi;
+}
+async function session() {
+    return cognitoSession;
+}
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/**
+ * 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 function pricingPlanFromBody(body) {
+    const rec = asRecord(body);
+    if (!rec)
+        return null;
+    if (rec.pricingPlan === "usage-only")
+        return "usage-only";
+    if (rec.pricingPlan === "current")
+        return "current";
+    if (asRecord(rec.personalUsage))
+        return "usage-only";
+    return null;
+}
+export function isUsageOnly(plan) {
+    return plan === "usage-only";
+}
+/** True when a company summary says a usage-only trial is running. Absent is false. */
+export function usageTrialActiveFromBody(body) {
+    return asRecord(asRecord(body)?.usageTrial)?.status === "active";
+}
+async function defaultGetJson(token, path, query, timeoutMs) {
+    const { vaultApiFetch } = await http();
+    const res = await vaultApiFetch({
+        token,
+        path,
+        ...(query ? { query } : {}),
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok)
+        return null;
+    return res.json().catch(() => null);
+}
+function getter(deps) {
+    return deps.getJson
+        ? deps.getJson
+        : (t, p, q) => defaultGetJson(t, p, q, deps.timeoutMs ?? 5000);
+}
+const companyCache = new Map();
+const companyLimitsCache = new Map();
+let membershipCache;
+let personCache;
+let personLimitsCache;
+/** Test-only: forget cached reads. */
+export function _resetPricingPlanCacheForTests() {
+    companyCache.clear();
+    companyLimitsCache.clear();
+    membershipCache = undefined;
+    personCache = undefined;
+    personLimitsCache = undefined;
+}
+/**
+ * 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 function pricingPlanFromMembership(body, companyRef) {
+    const rows = asRecord(body)?.memberships;
+    if (!Array.isArray(rows))
+        return null;
+    const ref = companyRef.trim().toLowerCase();
+    for (const raw of rows) {
+        const row = asRecord(raw);
+        if (!row)
+            continue;
+        const uid = typeof row.companyUid === "string" ? row.companyUid.toLowerCase() : "";
+        const slug = typeof row.companySlug === "string" ? row.companySlug.toLowerCase() : "";
+        if (uid !== ref && slug !== ref)
+            continue;
+        if (row.pricingPlan === "usage-only" || row.pricingPlan === "current")
+            return row.pricingPlan;
+        return null;
+    }
+    return null;
+}
+/** The company billing summary body, read once per process. Null when unreadable. */
+export async function fetchCompanyBillingSummary(token, companyUid, deps = {}) {
+    let pending = companyCache.get(companyUid);
+    if (!pending) {
+        pending = getter(deps)(token, "/v1/billing/summary", { companyUid }).catch(() => null);
+        companyCache.set(companyUid, pending);
+    }
+    return pending;
+}
+/** The company's pricing plan (membership row, usage-limits, then summary). Null when unknown. */
+/** Resolve `work`, or null once `ms` has passed. Never rejects. */
+async function withDeadline(work, ms) {
+    let timer;
+    const late = new Promise((resolve) => {
+        timer = setTimeout(() => resolve(null), ms);
+        timer.unref?.();
+    });
+    try {
+        return await Promise.race([work.catch(() => null), late]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+const DEFAULT_DEADLINE_MS = 6000;
+export async function fetchCompanyPricingPlan(token, companyUid, deps = {}) {
+    return withDeadline(lookupCompanyPricingPlan(token, companyUid, deps), deps.deadlineMs ?? DEFAULT_DEADLINE_MS);
+}
+async function lookupCompanyPricingPlan(token, companyUid, deps) {
+    const get = getter(deps);
+    membershipCache ??= get(token, "/membership/me").catch(() => null);
+    const fromMembership = pricingPlanFromMembership(await membershipCache, companyUid);
+    if (fromMembership)
+        return fromMembership;
+    let limits = companyLimitsCache.get(companyUid);
+    if (!limits) {
+        limits = get(token, "/v1/billing/usage-limits", { companyUid }).catch(() => null);
+        companyLimitsCache.set(companyUid, limits);
+    }
+    const fromLimits = pricingPlanFromBody(await limits);
+    if (fromLimits)
+        return fromLimits;
+    return pricingPlanFromBody(await fetchCompanyBillingSummary(token, companyUid, deps));
+}
+/** The caller's personal pricing plan (person usage-limits, then summary). Null when unknown. */
+export async function fetchPersonPricingPlan(token, deps = {}) {
+    return withDeadline(lookupPersonPricingPlan(token, deps), deps.deadlineMs ?? DEFAULT_DEADLINE_MS);
+}
+async function lookupPersonPricingPlan(token, deps) {
+    personLimitsCache ??= getter(deps)(token, "/v1/billing/person/usage-limits").catch(() => null);
+    const fromLimits = pricingPlanFromBody(await personLimitsCache);
+    if (fromLimits)
+        return fromLimits;
+    personCache ??= getter(deps)(token, "/v1/billing/person/summary").catch(() => null);
+    const body = await personCache;
+    if (body === null || body === undefined)
+        return null;
+    // The person summary answered: no `personalUsage` block means the legacy
+    // personal plan, not unknown.
+    return pricingPlanFromBody(body) ?? "current";
+}
+/**
+ * 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 async function resolveCompanyPricingPlan(company, deps = {}) {
+    try {
+        const { ensureCognitoToken } = await session();
+        const { getCompanyUid } = await http();
+        const token = await ensureCognitoToken({ interactive: false });
+        const companyUid = await getCompanyUid(token, company);
+        return await fetchCompanyPricingPlan(token, companyUid, deps);
+    }
+    catch {
+        return null;
+    }
+}
+/** Best-effort person-scope counterpart of {@link resolveCompanyPricingPlan}. */
+export async function resolvePersonPricingPlan(deps = {}) {
+    try {
+        const { ensureCognitoToken } = await session();
+        const token = await ensureCognitoToken({ interactive: false });
+        return await fetchPersonPricingPlan(token, deps);
+    }
+    catch {
+        return null;
+    }
+}
+// ── Copy for usage-only accounts ─────────────────────────────────────────────
+// One place for what the CLI tells an account on usage pricing. None of these
+// lines names a Workforce, Individual or Starter plan or their prices.
+/** One sentence every usage-only surface uses to point at the bill. */
+export 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 function usageIncludedSentence(card = BUNDLED_USAGE_CARD) {
+    return `It pays per use, with ${formatCardUsd(card.includedUsd)} of usage included each month.`;
+}
+/** `hq billing upgrade` for a usage-only company. */
+export function usageOnlyUpgradeLines(card = BUNDLED_USAGE_CARD) {
+    return [
+        "This company is on usage pricing, so there is no plan to upgrade to.",
+        usageIncludedSentence(card),
+        USAGE_PRICING_POINTER,
+    ];
+}
+/** The `Plan:` orientation line (`hq whoami --plan`) for a usage-only company. */
+export function usageOnlyPlanLine(card = BUNDLED_USAGE_CARD) {
+    return (`Plan: usage pricing — ${formatCardUsd(card.includedUsd)} of usage included each month. ` +
+        "See `hq billing usage`.");
+}
+/** Agent boxes on usage pricing, priced by size from the card. */
+export function usageOnlyBoxSentence(card = BUNDLED_USAGE_CARD) {
+    return `Agent boxes on usage pricing are billed by size: ${formatBoxQuotes(card)}.`;
+}
+/**
+ * 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 function usageOnlyCardRequiredLines(what, card = BUNDLED_USAGE_CARD) {
+    return [
+        `${what} is billed on usage pricing and needs a card on file.`,
+        "Add one with `hq billing checkout` (safe to share with whoever owns billing), then re-run.",
+        `The company pays per use, with ${formatCardUsd(card.includedUsd)} of usage included each month.`,
+        USAGE_PRICING_POINTER,
+    ];
+}
+/** `hq billing sponsor request` for a person on usage pricing. */
+export function usageOnlySponsorLines(card = BUNDLED_USAGE_CARD) {
+    return [
+        "Your personal account is on usage pricing, so there is no personal plan for a company to cover.",
+        `It includes ${formatCardUsd(card.includedUsd)} of usage each month; usage above that is billed to your card.`,
+        "Run `hq billing usage --personal` for this month's usage and projected bill.",
+    ];
+}
+/** A personal feature refusal for a person on usage pricing. */
+export function usageOnlyPersonalFeatureNotice(label) {
+    return (`${label} is not available on your personal account yet. ` +
+        "Your personal account is on usage pricing, so there is no plan to upgrade to. " +
+        "Run `hq billing usage --personal` for this month's usage.");
+}
+//# sourceMappingURL=usage-only.js.map

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

@@ -0,0 +1,51 @@
+/**
+ * Meter rates for `hq billing usage`, derived from the usage card
+ * (`./usage-card.ts`, the one place usage prices live in this CLI).
+ *
+ * hq-pro publishes the card in the `usage` block of `GET /v1/pricing`. When
+ * the feed has no `usage` block yet (or cannot be read), the bundled card is
+ * used; it equals the feed contract.
+ *
+ * Keys match the feed's meter ids so a usage reading, the feed and this file
+ * join without a mapping table. Only meters this CLI knows how to bill (gauge
+ * or counter) are priced here; an unknown feed meter is left out of the bill
+ * rather than billed with a guessed shape.
+ */
+import { type UsageCard } from "./usage-card.js";
+export type UsageMeterKey = "member-sync" | "integration-call" | "hq-mcp-call" | "agent-run" | "storage" | "secret" | "vault";
+/**
+ * Gauges are billed on the amount held (GB, secrets, vaults) for the month.
+ * Counters are billed per event, so a month-to-date count is projected to
+ * month end.
+ */
+export type UsageMeterKind = "gauge" | "counter";
+export interface UsageMeterRate {
+    readonly key: UsageMeterKey;
+    readonly displayName: string;
+    /** What one billed unit is, in words. */
+    readonly unit: string;
+    /** Price of one unit in US dollars. */
+    readonly unitUsd: number;
+    readonly kind: UsageMeterKind;
+    /** Not billed while a trial runs (the vault fee). */
+    readonly waivedInTrial?: boolean;
+}
+export declare function isUsageMeterKey(id: string): id is UsageMeterKey;
+/** Rates for the meters this CLI can bill, in card order. */
+export declare function ratesFromCard(card: UsageCard): UsageMeterRate[];
+/** Included usage every month before anything bills, in USD. */
+export declare const USAGE_MONTHLY_ALLOWANCE_USD: number;
+/** The bundled card's rates. */
+export declare const BUNDLED_USAGE_METER_RATES: readonly UsageMeterRate[];
+export interface UsageRates {
+    rates: readonly UsageMeterRate[];
+    allowanceUsd: number;
+    source: "published" | "bundled";
+    card: UsageCard;
+}
+/**
+ * Rates from a `GET /v1/pricing` body. A body with no `usage` block (before
+ * hq-pro ships it) returns the bundled card.
+ */
+export declare function ratesFromPricingStatement(body: unknown): UsageRates;
+//# sourceMappingURL=usage-rate-card.d.ts.map

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

@@ -0,0 +1,62 @@
+/**
+ * Meter rates for `hq billing usage`, derived from the usage card
+ * (`./usage-card.ts`, the one place usage prices live in this CLI).
+ *
+ * hq-pro publishes the card in the `usage` block of `GET /v1/pricing`. When
+ * the feed has no `usage` block yet (or cannot be read), the bundled card is
+ * used; it equals the feed contract.
+ *
+ * Keys match the feed's meter ids so a usage reading, the feed and this file
+ * join without a mapping table. Only meters this CLI knows how to bill (gauge
+ * or counter) are priced here; an unknown feed meter is left out of the bill
+ * rather than billed with a guessed shape.
+ */
+import { BUNDLED_USAGE_CARD, usageCardFromPricingFeed, } from "./usage-card.js";
+const METER_KINDS = {
+    "member-sync": "counter",
+    "integration-call": "counter",
+    "hq-mcp-call": "counter",
+    "agent-run": "counter",
+    storage: "gauge",
+    secret: "gauge",
+    vault: "gauge",
+};
+export function isUsageMeterKey(id) {
+    return Object.prototype.hasOwnProperty.call(METER_KINDS, id);
+}
+/** Rates for the meters this CLI can bill, in card order. */
+export function ratesFromCard(card) {
+    const out = [];
+    for (const m of card.meters) {
+        if (!isUsageMeterKey(m.id))
+            continue;
+        out.push({
+            key: m.id,
+            displayName: m.label,
+            unit: m.unit,
+            unitUsd: m.unitUsd,
+            kind: METER_KINDS[m.id],
+            ...(m.waivedInTrial ? { waivedInTrial: true } : {}),
+        });
+    }
+    return out;
+}
+/** Included usage every month before anything bills, in USD. */
+export const USAGE_MONTHLY_ALLOWANCE_USD = BUNDLED_USAGE_CARD.includedUsd;
+/** The bundled card's rates. */
+export const BUNDLED_USAGE_METER_RATES = ratesFromCard(BUNDLED_USAGE_CARD);
+/**
+ * Rates from a `GET /v1/pricing` body. A body with no `usage` block (before
+ * hq-pro ships it) returns the bundled card.
+ */
+export function ratesFromPricingStatement(body) {
+    const { card, source } = usageCardFromPricingFeed(body);
+    const rates = ratesFromCard(card);
+    return {
+        rates: rates.length > 0 ? rates : BUNDLED_USAGE_METER_RATES,
+        allowanceUsd: card.includedUsd,
+        source: source === "feed" ? "published" : "bundled",
+        card,
+    };
+}
+//# sourceMappingURL=usage-rate-card.js.map