@indigoai-us/hq-cli 5.345.159 → 5.345.160

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

@@ -24,8 +24,44 @@
  */
 import { type UsageCard } from "./usage-card.js";
 export type PricingPlan = "usage-only" | "current";
+/** Whether a server supplied shared status (including an unreadable/null value). */
+export declare function hasBillingStateField(body: unknown): boolean;
+export type BillingStateKind = "usage" | "usage-trial" | "legacy-payer" | "legacy-free" | "enterprise" | "comped";
 /**
- * Read the pricing plan out of a decoded hq-pro body. `pricingPlan` wins;
+ * hq-pro's shared plan status (`billingState`, hq-pro #5088
+ * src/billing/billing-state.ts), the fields the CLI reads. Version 1 only.
+ */
+export interface SharedBillingState {
+    kind: BillingStateKind;
+    scope: "company" | "person";
+    view: "full" | "member";
+    trial: {
+        daysLeft: number;
+        endsAt: string;
+    } | null;
+    /** A pause the server is applying now, or null. */
+    paused: {
+        reason: string;
+        resumesOn: string | null;
+    } | null;
+    /** What this caller may do. All false in the member view. */
+    actions: {
+        addCard: boolean;
+        raiseLimit: boolean;
+        switchToUsage: boolean;
+        manageBilling: boolean;
+    };
+}
+/**
+ * Read a known v1 `billingState` off a decoded body. An unknown version,
+ * scope, view or kind (or a malformed trial) is null: it is never read as a
+ * legacy plan. A person state is always the full view.
+ */
+export declare function readBillingState(body: unknown): SharedBillingState | null;
+export { usagePauseFromBody, type UsagePause } from "./usage-pause.js";
+/**
+ * Read the pricing plan out of a decoded hq-pro body. Known `billingState` wins;
+ * only a server without that field uses the legacy `pricingPlan` signal;
  * a `personalUsage` object (person summary) means usage-only. Anything else
  * is UNKNOWN.
  */

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

@@ -40,8 +40,84 @@ function asRecord(value) {
         ? value
         : null;
 }
+/** Whether a server supplied shared status (including an unreadable/null value). */
+export function hasBillingStateField(body) {
+    const rec = asRecord(body);
+    return rec !== null && Object.prototype.hasOwnProperty.call(rec, "billingState");
+}
+const BILLING_STATE_KINDS = [
+    "usage",
+    "usage-trial",
+    "legacy-payer",
+    "legacy-free",
+    "enterprise",
+    "comped",
+];
+function readTrial(value) {
+    if (value === null || value === undefined)
+        return null;
+    const trial = asRecord(value);
+    if (!trial ||
+        typeof trial.daysLeft !== "number" ||
+        !Number.isFinite(trial.daysLeft) ||
+        trial.daysLeft < 0 ||
+        typeof trial.endsAt !== "string" ||
+        !Number.isFinite(Date.parse(trial.endsAt))) {
+        return undefined;
+    }
+    return { daysLeft: trial.daysLeft, endsAt: trial.endsAt };
+}
+function readPaused(value) {
+    const paused = asRecord(value);
+    if (!paused || typeof paused.reason !== "string" || !paused.reason)
+        return null;
+    return {
+        reason: paused.reason,
+        resumesOn: typeof paused.resumesOn === "string" ? paused.resumesOn : null,
+    };
+}
 /**
- * Read the pricing plan out of a decoded hq-pro body. `pricingPlan` wins;
+ * Read a known v1 `billingState` off a decoded body. An unknown version,
+ * scope, view or kind (or a malformed trial) is null: it is never read as a
+ * legacy plan. A person state is always the full view.
+ */
+export function readBillingState(body) {
+    const state = asRecord(asRecord(body)?.billingState);
+    if (!state || state.version !== 1)
+        return null;
+    if (state.scope !== "company" && state.scope !== "person")
+        return null;
+    if (state.view !== "full" && state.view !== "member")
+        return null;
+    if (state.scope === "person" && state.view !== "full")
+        return null;
+    if (typeof state.kind !== "string" || !BILLING_STATE_KINDS.includes(state.kind))
+        return null;
+    const trial = readTrial(state.trial);
+    if (trial === undefined)
+        return null;
+    const actions = asRecord(state.actions);
+    return {
+        kind: state.kind,
+        scope: state.scope,
+        view: state.view,
+        trial,
+        paused: readPaused(state.paused),
+        actions: {
+            addCard: actions?.addCard === true,
+            raiseLimit: actions?.raiseLimit === true,
+            switchToUsage: actions?.switchToUsage === true,
+            manageBilling: actions?.manageBilling === true,
+        },
+    };
+}
+function sharedBillingState(body) {
+    return readBillingState(body);
+}
+export { usagePauseFromBody } from "./usage-pause.js";
+/**
+ * Read the pricing plan out of a decoded hq-pro body. Known `billingState` wins;
+ * only a server without that field uses the legacy `pricingPlan` signal;
  * a `personalUsage` object (person summary) means usage-only. Anything else
  * is UNKNOWN.
  */
@@ -49,6 +125,10 @@ export function pricingPlanFromBody(body) {
     const rec = asRecord(body);
     if (!rec)
         return null;
+    if (hasBillingStateField(rec)) {
+        const state = sharedBillingState(rec);
+        return state ? (state.kind === "usage" || state.kind === "usage-trial" ? "usage-only" : "current") : null;
+    }
     if (rec.pricingPlan === "usage-only")
         return "usage-only";
     if (rec.pricingPlan === "current")
@@ -62,6 +142,8 @@ export function isUsageOnly(plan) {
 }
 /** True when a company summary says a usage-only trial is running. Absent is false. */
 export function usageTrialActiveFromBody(body) {
+    if (hasBillingStateField(body))
+        return sharedBillingState(body)?.kind === "usage-trial";
     return asRecord(asRecord(body)?.usageTrial)?.status === "active";
 }
 async function defaultGetJson(token, path, query, timeoutMs) {
@@ -111,9 +193,12 @@ export function pricingPlanFromMembership(body, companyRef) {
         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;
+        if (hasBillingStateField(row)) {
+            const state = sharedBillingState(row);
+            if (!state || state.scope !== "company")
+                return null;
+        }
+        return pricingPlanFromBody(row);
     }
     return null;
 }

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

@@ -0,0 +1,27 @@
+/**
+ * The usage pause block on a 402 body (hq-pro src/billing/usage-pause.ts,
+ * US-024): `{ code: "usage_paused", reason, message, actionUrl }`.
+ *
+ * Every refusal hq-pro makes because of an account's usage state (the trial
+ * cap, a card needed past the monthly allowance, the monthly spend limit)
+ * carries it. A client shows `message` as written and links `actionUrl`; it
+ * adds no plan name and no upgrade offer.
+ *
+ * Leaf module (no imports) so the sync refusal tracker and the 402 decoder
+ * can share it without loading the HTTP layer.
+ */
+export declare const USAGE_PAUSE_CODE = "usage_paused";
+export interface UsagePause {
+    /** `usage_trial_cap` | `usage_card_required` | `usage_spend_limit` (or a newer code). */
+    reason: string;
+    /** One plain-language paragraph from the server. */
+    message: string;
+    /** Where to act: the company or personal Billing page (https). */
+    actionUrl?: string;
+}
+/**
+ * Read `usagePause` off a decoded 402 body, or off any record that carries
+ * it. Null when absent or malformed (wrong code, empty message).
+ */
+export declare function usagePauseFromBody(body: unknown): UsagePause | null;
+//# sourceMappingURL=usage-pause.d.ts.map

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

@@ -0,0 +1,50 @@
+/**
+ * The usage pause block on a 402 body (hq-pro src/billing/usage-pause.ts,
+ * US-024): `{ code: "usage_paused", reason, message, actionUrl }`.
+ *
+ * Every refusal hq-pro makes because of an account's usage state (the trial
+ * cap, a card needed past the monthly allowance, the monthly spend limit)
+ * carries it. A client shows `message` as written and links `actionUrl`; it
+ * adds no plan name and no upgrade offer.
+ *
+ * Leaf module (no imports) so the sync refusal tracker and the 402 decoder
+ * can share it without loading the HTTP layer.
+ */
+export const USAGE_PAUSE_CODE = "usage_paused";
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function httpsUrl(value) {
+    if (typeof value !== "string" || value.trim() !== value)
+        return undefined;
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" && url.hostname && !url.username && !url.password
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Read `usagePause` off a decoded 402 body, or off any record that carries
+ * it. Null when absent or malformed (wrong code, empty message).
+ */
+export function usagePauseFromBody(body) {
+    const pause = asRecord(asRecord(body)?.usagePause);
+    if (!pause || pause.code !== USAGE_PAUSE_CODE)
+        return null;
+    const message = typeof pause.message === "string" ? pause.message.trim() : "";
+    if (!message)
+        return null;
+    const actionUrl = httpsUrl(pause.actionUrl);
+    return {
+        reason: typeof pause.reason === "string" ? pause.reason : "",
+        message,
+        ...(actionUrl ? { actionUrl } : {}),
+    };
+}
+//# sourceMappingURL=usage-pause.js.map

package/dist/lib/db/control-plane.d.ts

@@ -1,3 +1,4 @@
+import { type UsagePause } from "../billing/usage-pause.js";
 /**
  * Control-plane client for remote vault DB (US-009).
  * Injectable fetch for tests — never logs response bodies that might hold secrets.
@@ -167,5 +168,9 @@ export type ControlPlaneHttpError = Error & {
     status?: number;
     code?: string;
     reason?: string;
+    /** The 402 usage pause (hq-pro `usagePause`), when the server sent one. */
+    usagePause?: UsagePause;
+    /** The body's customer sentence (`message`), when it sent one. */
+    serverMessage?: string;
 };
 //# sourceMappingURL=control-plane.d.ts.map

package/dist/lib/db/control-plane.js

@@ -1,4 +1,5 @@
 import { planGateErrorFromPayload } from "../../utils/plan-gate-error.js";
+import { usagePauseFromBody } from "../billing/usage-pause.js";
 // Provision may allocate remote resources, so allow two minutes and never retry.
 const DB_PROVISION_TIMEOUT_MS = 120_000;
 // Status is a read-only probe; 15 seconds is longer than its normal response time.
@@ -195,6 +196,8 @@ function httpError(label, status, text) {
     let msg = `${label} failed (${status})`;
     let code;
     let reason;
+    let usagePause = null;
+    let serverMessage;
     try {
         const j = JSON.parse(text);
         if (typeof j.error === "string")
@@ -203,6 +206,9 @@ function httpError(label, status, text) {
             code = j.code;
         if (typeof j.reason === "string")
             reason = j.reason;
+        if (typeof j.message === "string" && j.message.trim())
+            serverMessage = j.message.trim();
+        usagePause = usagePauseFromBody(j);
     }
     catch {
         /* keep */
@@ -213,6 +219,10 @@ function httpError(label, status, text) {
         err.code = code;
     if (reason)
         err.reason = reason;
+    if (usagePause)
+        err.usagePause = usagePause;
+    if (serverMessage)
+        err.serverMessage = serverMessage;
     return err;
 }
 function personalHttpError(label, status, text) {