@growth-operations/ui-shared 1.19.0 → 1.21.0

package/src/lib/creditDisplay.js

@@ -59,37 +59,53 @@ export function hasTopUpBank(ent) {
 //                          no bank section)
 //   alert                — { variant, title, message } or null
 //   grantExpiresAt       — pass-through for the free-grant countdown
+//   renewsOn             — "YYYY-MM-DD" the monthly pool renews on, from the
+//                          state.credits block (null when absent)
 //
 // BAR COLORS ARE PER-BAR FILL LEVELS (Jasper 2026-10): a pool at 99% used
 // with a full bank must NOT render green just because the account is healthy
 // — each bar colors by its own level; the StatusTag keeps the account-state
-// colors. Thresholds mirror the backend's ~80/95 low-credit alert ladder
-// (common.entitlements LOW/DEPLETED banding). Comparisons are integer
-// cross-multiplications — no float fuzz at the 80/95/50/20 boundaries.
+// colors. The pool bar colors on % CONSUMED (Andrew 2026-10: green under
+// 50%, orange 50–80%, red over 80%). Comparisons are integer
+// cross-multiplications — no float fuzz at the 50/80/20 boundaries.
 //
-//   pool (DEPLETION meter, value = poolUsed of poolGrant):
-//     success when used < 80%, warning at >= 80%, danger at >= 95%.
+// THE state.credits BLOCK (2026-10 contract addition): when the payload
+// carries `credits` ({ monthly: { remaining, included, renews_on },
+// additional: { remaining, purchased, expires } }) it is AUTHORITATIVE for
+// the two-bucket display — no deriving pool/bank from the entitlement's
+// combined numbers. Absent (older backends) -> the legacy entitlement
+// derivation below, unchanged.
+//
+//   pool (DEPLETION meter, value = poolUsed of poolGrant), colored on %
+//     consumed per Andrew's 2026-10 feedback: success under 50% used, warning
+//     from 50% through 80%, danger over 80%.
 //   bank (LEVEL gauge, value = bankRemaining of bankGranted):
-//     success above 50% full, warning at 20–50%, danger at <= 20%
-//     ("running out") — a draining bank is warning-worthy even though it
-//     never expires.
+//     success above 50% full, warning at <= 50%. NO danger variant:
+//     HubSpot's ProgressBar paints the WHOLE TRACK red in danger (not just
+//     the filled portion), so a low level gauge would read as a full bar
+//     (caught in Jasper's 2026-10-04 screenshot review). Urgency at <= 20%
+//     rides the "Running low" tag (bank.bankLow) instead of the bar color.
+//     danger stays on the pool bar, where near-full is the truth.
 function poolBarVariantFor(poolUsed, poolGrant) {
   if (!(poolGrant > 0)) return "success"; // no grant: nothing to deplete
-  if (poolUsed * 100 >= 95 * poolGrant) return "danger";
-  if (poolUsed * 100 >= 80 * poolGrant) return "warning";
+  if (poolUsed * 100 > 80 * poolGrant) return "danger";
+  if (poolUsed * 100 >= 50 * poolGrant) return "warning";
   return "success";
 }
 
 function bankBarVariantFor(bankRemaining, bankGranted) {
   if (!(bankGranted > 0)) return "success"; // degraded text-only line renders no bar
-  if (bankRemaining * 100 <= 20 * bankGranted) return "danger";
   if (bankRemaining * 100 <= 50 * bankGranted) return "warning";
   return "success";
 }
-export function resolveCreditMeter(entitlement, creditMeter) {
+export function resolveCreditMeter(entitlement, creditMeter, credits = null) {
   const ent = entitlement?.mode === "credits" ? entitlement : null;
   const meter = creditMeter ?? null;
-  if (!ent && !meter) return null;
+  // The state.credits block stands on its own (it IS the credit data), so it
+  // keeps the meter alive even on a payload whose entitlement arm is missing.
+  const creditsBlock =
+    credits && (credits.monthly || credits.additional) ? credits : null;
+  if (!ent && !meter && !creditsBlock) return null;
 
   // Number precedence: once the entitlement arm carries the top-up fields it
   // is authoritative — the credit_meter block stays RAW pool-only under the
@@ -101,9 +117,25 @@ export function resolveCreditMeter(entitlement, creditMeter) {
   const pick = (key) =>
     entHasTopUpFields ? ent[key] ?? meter?.[key] : meter?.[key] ?? ent?.[key];
 
-  const granted = pick("granted") ?? 0;
-  const used = pick("used") ?? 0;
-  const remaining = pick("remaining") ?? Math.max(granted - used, 0);
+  // Number source: the state.credits block when present (authoritative
+  // two-bucket numbers), else the entitlement/meter precedence chain.
+  let granted;
+  let used;
+  let remaining;
+  if (creditsBlock) {
+    const monthly = creditsBlock.monthly ?? {};
+    const additional = creditsBlock.additional ?? {};
+    const poolGrant = Math.max(0, monthly.included ?? 0);
+    const poolRemaining = Math.max(0, monthly.remaining ?? 0);
+    const bankRemaining = Math.max(0, additional.remaining ?? 0);
+    granted = poolGrant + bankRemaining;
+    remaining = poolRemaining + bankRemaining;
+    used = Math.max(granted - remaining, 0);
+  } else {
+    granted = pick("granted") ?? 0;
+    used = pick("used") ?? 0;
+    remaining = pick("remaining") ?? Math.max(granted - used, 0);
+  }
 
   const onPaidPlan = !!ent?.plan;
   const lowThreshold = ent?.low_threshold ?? 0;
@@ -123,26 +155,53 @@ export function resolveCreditMeter(entitlement, creditMeter) {
   // bank portion is bankRemaining and the rest is pool remaining; the pool
   // segment's full size is the combined denominator minus the bank.
   //
-  // The bank section renders ONLY while the bank has credits left
-  // (bankRemaining > 0): a zero bank — never topped up, or fully burned —
-  // renders the plain single-pool bar, and with bankRemaining 0 the combined
-  // numbers ARE the pool numbers (granted == poolGrant, remaining ==
-  // poolRemaining), so nothing is lost.
+  // Under the state.credits block the two-bucket layout is ALWAYS in force:
+  // the monthly line (+ "Renews on" subline + pool bar) renders even when the
+  // account has never bought additional credits; the additional-credits line
+  // rides along only when the account has (or ever bought) a bank —
+  // purchased > 0 carries the true lifetime total, so a spent bank reads
+  // "0 of 1,000 left" instead of disappearing (bank.showAdditional).
+  //
+  // Under the legacy derivation (no credits block) the bank section renders
+  // ONLY while the bank has credits left (bankRemaining > 0): a zero bank —
+  // never topped up, or fully burned — renders the plain single-pool bar, and
+  // with bankRemaining 0 the combined numbers ARE the pool numbers (granted
+  // == poolGrant, remaining == poolRemaining), so nothing is lost.
   let bank = null;
-  const bankRemaining = Math.max(0, ent?.top_up_bank_remaining ?? 0);
-  if (bankRemaining > 0) {
-    const poolGrant = Math.max(granted - bankRemaining, 0);
-    const poolRemaining = Math.min(Math.max(remaining - bankRemaining, 0), poolGrant);
+  const bankRemaining = creditsBlock
+    ? Math.max(0, creditsBlock.additional?.remaining ?? 0)
+    : Math.max(0, ent?.top_up_bank_remaining ?? 0);
+  const bankGrantedTotal = creditsBlock
+    ? Math.max(0, creditsBlock.additional?.purchased ?? 0)
+    : Math.max(0, ent?.top_up_bank_granted ?? 0);
+  if (creditsBlock || bankRemaining > 0) {
+    const poolGrant = creditsBlock
+      ? Math.max(0, creditsBlock.monthly?.included ?? 0)
+      : Math.max(granted - bankRemaining, 0);
+    const poolRemaining = creditsBlock
+      ? Math.min(Math.max(0, creditsBlock.monthly?.remaining ?? 0), poolGrant)
+      : Math.min(Math.max(remaining - bankRemaining, 0), poolGrant);
     bank = {
       bankRemaining,
       // The bank's lifetime granted total — the bank bar's denominator. 0 on
       // backends that predate top_up_bank_granted (the component degrades to
       // a text-only bank line; never divide by zero, never "of 0").
-      bankGranted: Math.max(0, ent?.top_up_bank_granted ?? 0),
+      bankGranted: bankGrantedTotal,
+      // Whether the additional-credits line renders at all. Legacy path: yes
+      // (we only get here with bankRemaining > 0). credits block: only when
+      // the account has or bought a bank — otherwise the two-bucket layout is
+      // just the monthly line.
+      showAdditional: creditsBlock
+        ? bankRemaining > 0 || bankGrantedTotal > 0
+        : true,
       poolGrant,
       poolRemaining,
       poolUsed: poolGrant - poolRemaining,
     };
+    // "Running low" tag at <= 20% of the granted total (the bar itself caps
+    // at warning — see the header block). False when the total is unknown.
+    bank.bankLow =
+      bank.bankGranted > 0 && bankRemaining * 100 <= 20 * bank.bankGranted;
   }
 
   let tagVariant;
@@ -152,7 +211,7 @@ export function resolveCreditMeter(entitlement, creditMeter) {
     tagLabel = "Depleted";
   } else if (thresholdState === "top_up_failed") {
     tagVariant = "danger";
-    tagLabel = "Top-up failed";
+    tagLabel = "Couldn't add credits";
   } else if (thresholdState === "limit_reached") {
     tagVariant = "warning";
     tagLabel = "Limit reached";
@@ -189,7 +248,7 @@ export function resolveCreditMeter(entitlement, creditMeter) {
       variant: "error",
       title: "You're out of credits",
       message: onPaidPlan
-        ? "Actions are paused until your next billing period or a successful top-up."
+        ? "Actions are paused until your plan renews or more credits are added."
         : "Choose a plan to resume your use.",
     };
   } else if (thresholdState === "top_up_failed") {
@@ -197,14 +256,14 @@ export function resolveCreditMeter(entitlement, creditMeter) {
       variant: "error",
       title: "We couldn't add credits",
       message:
-        "The automatic top-up charge failed — update your payment method in Billing.",
+        "The automatic additional-credits purchase failed — update your payment method in Billing.",
     };
   } else if (thresholdState === "limit_reached") {
     alert = {
       variant: "warning",
       title: "Billing limit reached",
       message:
-        "Automatic top-ups are paused at your spending limit for this period. Raise your billing limit in Billing to resume them.",
+        "Automatic additional-credit purchases are paused at your spending limit for this period. Raise your billing limit in Billing to resume them.",
     };
   } else if (overIncluded) {
     alert = {
@@ -217,7 +276,8 @@ export function resolveCreditMeter(entitlement, creditMeter) {
     alert = {
       variant: "warning",
       title: "Running low on credits",
-      message: "You're getting close to your limit — pick a plan to top up.",
+      message:
+        "You're getting close to your limit — pick a plan or add more credits.",
     };
   }
 
@@ -236,6 +296,9 @@ export function resolveCreditMeter(entitlement, creditMeter) {
     bankBarVariant,
     alert,
     grantExpiresAt: ent?.grant_expires_at ?? null,
+    // "YYYY-MM-DD" the monthly pool renews on (state.credits block only; null
+    // on older backends — the component just skips the subline).
+    renewsOn: creditsBlock ? (creditsBlock.monthly?.renews_on ?? null) : null,
   };
 }
 
@@ -276,7 +339,7 @@ export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun } =
     return {
       variant: "error",
       title: "We couldn't add credits",
-      message: `The automatic top-up charge failed. Update your payment method so your ${noun} aren't interrupted.`,
+      message: `The automatic additional-credits purchase failed. Update your payment method so your ${noun} aren't interrupted.`,
       cta: { kind: "portal", label: "Update payment method" },
     };
   }
@@ -285,7 +348,7 @@ export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun } =
       variant: "warning",
       title: "Billing limit reached",
       message:
-        "Automatic top-ups are paused — you've hit your spending limit for this billing period. Raise your billing limit to keep them going.",
+        "Automatic additional-credit purchases are paused — you've hit your spending limit for this billing period. Raise your billing limit to keep them going.",
       cta: { kind: "billing", label: "Raise your billing limit" },
     };
   }
@@ -306,7 +369,7 @@ export function resolveBillingBanner(entitlement, { actionLabel, actionsNoun } =
       variant: "error",
       title: "You're out of credits",
       message: onPaidPlan
-        ? `Your ${noun} are paused until your next billing period or a successful top-up.`
+        ? `Your ${noun} are paused until your plan renews or more credits are added.`
         : `Your credits are used up. Choose a plan in Billing to keep ${label}.`,
       cta: { kind: "billing", label: "Go to Billing →" },
     };

package/src/lib/featureUsage.js

@@ -0,0 +1,54 @@
+// Pure resolver for the Home "Most used features" / "Recommended to explore"
+// sections, fed by the additive `feature_usage` block on the /home payload
+// (growth-ops-apps-base computes it from the credit ledger). Framework-free
+// (no React) so the branch math is unit-testable; ../home/FeatureUsage.jsx
+// stays thin.
+//
+// Degrades gracefully by contract: the block is ABSENT on older backends,
+// on legacy (Anvil) installs, and on apps with no feature registry — every
+// one of those resolves to null (render nothing), never an empty box.
+
+// The wire field is `credits_or_events`: the registry anticipates
+// event-denominated features, so a most_used row MAY carry a `unit` hint
+// ("credits" | "events"; singular spellings accepted). Absent -> "credits",
+// which is what every current backend emits.
+const normalizeUnit = (u) =>
+  typeof u === "string" && u.toLowerCase().startsWith("event") ? "events" : "credits";
+
+// Resolve the feature_usage block into render-ready shape:
+//   { mostUsed: [{ key, name, count, unit }],
+//     notInUse: [{ key, name, docsUrl, rationale }] }
+// Returns null when the block is absent/malformed or BOTH lists are empty
+// (an install using every detectable feature has nothing to show here).
+export function resolveFeatureUsage(featureUsage) {
+  if (!featureUsage || typeof featureUsage !== "object") return null;
+
+  const mostUsed = (Array.isArray(featureUsage.most_used) ? featureUsage.most_used : [])
+    .filter((f) => f && f.key != null && f.name)
+    .map((f) => ({
+      key: f.key,
+      name: f.name,
+      count: typeof f.credits_or_events === "number" ? f.credits_or_events : 0,
+      unit: normalizeUnit(f.unit),
+    }));
+
+  const notInUse = (Array.isArray(featureUsage.not_in_use) ? featureUsage.not_in_use : [])
+    .filter((f) => f && f.key != null && f.name)
+    .map((f) => ({
+      key: f.key,
+      name: f.name,
+      docsUrl: typeof f.docs_url === "string" && f.docs_url ? f.docs_url : null,
+      rationale: typeof f.rationale === "string" ? f.rationale : "",
+    }));
+
+  if (mostUsed.length === 0 && notInUse.length === 0) return null;
+  return { mostUsed, notInUse };
+}
+
+// The block lives at payload.state.feature_usage on current backends. The
+// bare `payload.feature_usage` fallback keeps the component working if a
+// host ever passes the inner state block instead of the whole payload.
+export function featureUsageOf(state) {
+  if (!state || typeof state !== "object") return null;
+  return resolveFeatureUsage(state.state?.feature_usage ?? state.feature_usage);
+}

package/src/lib/homeBlocks.js

@@ -0,0 +1,146 @@
+// Pure resolvers for the Home cockpit blocks added for Andrew's 2026-10
+// App Home feedback: the trial banner (three states), the plan-fit signal,
+// and the period-over-period credit comparison. Framework-free (no React) so
+// the branch math is unit-testable; the components in ../home stay thin.
+//
+// Everything here degrades gracefully: every block is additive on the
+// /v1/home payload, and a resolver returns null (render nothing) whenever
+// the fields it needs are absent.
+import { daysUntil } from "./format";
+
+// --- Trial banner ----------------------------------------------------------
+
+// Rides under every trial banner (Andrew's exact copy).
+export const TRIAL_BANNER_FOOTER = "Need help? info@growthoperationsco.com";
+
+// Resolve the Home trial banner from the credits entitlement arm.
+// Returns null (render nothing) for non-credits modes, paid plans (the trial
+// is over), pre-install, or a backend that carries no grant clock. Otherwise
+// { variant, title, body, footer } — copy verbatim from Andrew, with the app
+// display name templated in.
+//
+// State selection (first match wins):
+//   out of credits  — the free grant is spent (depleted / remaining <= 0).
+//                     Beats the clock: a burned-through grant is "out of
+//                     credits" even with days left.
+//   trial ended     — the grant's 30-day clock ran out with credits left.
+//   trial active    — the clock is still running: "[XX] trial days remaining".
+export function resolveTrialBanner(entitlement, { appName } = {}) {
+  const ent = entitlement;
+  if (!ent || ent.mode !== "credits") return null;
+  if (ent.plan) return null; // a paid plan is past the trial
+  if (ent.status === "not_installed") return null;
+  const name = appName ?? "this app";
+
+  const granted = ent.granted ?? 0;
+  const used = ent.used ?? 0;
+  const remaining = ent.remaining ?? Math.max(granted - used, 0);
+  const daysLeft =
+    ent.grant_expires_at != null ? daysUntil(ent.grant_expires_at) : null;
+
+  if (ent.depleted === true || remaining <= 0) {
+    return {
+      variant: "error",
+      title: "You're out of credits",
+      body: `You have used ${used}/${granted} free credits. Select one of the plans below to continue use of ${name}.`,
+      footer: TRIAL_BANNER_FOOTER,
+    };
+  }
+  if (daysLeft != null && daysLeft <= 0) {
+    return {
+      variant: "warning",
+      title: "Your trial has ended",
+      body: `Your free trial has ended. Select a plan to continue use of ${name}.`,
+      footer: TRIAL_BANNER_FOOTER,
+    };
+  }
+  if (daysLeft != null) {
+    return {
+      variant: "info",
+      title: `${daysLeft} trial days remaining`,
+      body: `You have ${daysLeft} days remaining in your trial period. Select a plan to continue use of ${name}.`,
+      footer: TRIAL_BANNER_FOOTER,
+    };
+  }
+  // No grant clock on record (a backend that predates grant_expires_at) —
+  // nothing to count down, so no banner.
+  return null;
+}
+
+// --- Plan fit ---------------------------------------------------------------
+
+const capitalize = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+
+// "$40/mo" from a dollar number; whole amounts drop the decimals.
+const fmtSavings = (usd) =>
+  `$${Number.isInteger(usd) ? usd : usd.toFixed(2)}/mo`;
+
+// Resolve the plan_fit block. Returns:
+//   null                          — block absent/unknown verdict (render nothing)
+//   { kind: "right_plan" }        — reinforces the healthy hero
+//   { kind: "upgrade_recommended", text } — the savings banner body, Andrew's
+//     copy with the tier/savings/pack count templated in; degrades to a
+//     plainer sentence when the backend can't price the savings yet.
+export function resolvePlanFit(planFit) {
+  if (!planFit || typeof planFit !== "object") return null;
+
+  if (planFit.verdict === "right_plan") {
+    return { kind: "right_plan" };
+  }
+
+  if (planFit.verdict === "upgrade_recommended") {
+    const tier =
+      typeof planFit.target_tier === "string" && planFit.target_tier
+        ? capitalize(planFit.target_tier)
+        : null;
+    const savings =
+      typeof planFit.monthly_savings_usd === "number"
+        ? fmtSavings(planFit.monthly_savings_usd)
+        : null;
+    const packs = planFit.topup_packs_this_period ?? 0;
+    const packsText = `${packs} additional credit pack${packs === 1 ? "" : "s"}`;
+
+    let text;
+    if (savings && tier) {
+      text = `You could save ${savings} by moving to ${tier} — you bought ${packsText} this period.`;
+    } else if (tier) {
+      text = `You could save by moving to ${tier} — you bought ${packsText} this period.`;
+    } else {
+      text = `A higher plan may cost you less — you bought ${packsText} this period.`;
+    }
+    return { kind: "upgrade_recommended", text };
+  }
+
+  return null;
+}
+
+// --- Period comparison ------------------------------------------------------
+
+// Resolve the period_comparison block (null until the install has one full
+// closed period) into render-ready shape:
+//   { last, current, maxTotal } where each period is
+//   { label, total, byAction: [{ action, credits }] } and maxTotal is the
+//   shared bar denominator (so the two bars are visually comparable; >= 1 so
+//   a pair of zero periods never divides by zero).
+// Returns null when the block or either period is missing.
+export function resolvePeriodComparison(periodComparison) {
+  if (!periodComparison || typeof periodComparison !== "object") return null;
+  const norm = (p) => {
+    if (!p || typeof p !== "object") return null;
+    return {
+      label: p.label ?? "",
+      total: p.total_credits ?? 0,
+      byAction: Array.isArray(p.by_action)
+        ? p.by_action.filter((a) => a && a.action != null)
+        : [],
+    };
+  };
+  const last = norm(periodComparison.last_period);
+  const current = norm(periodComparison.current_period);
+  if (!last || !current) return null;
+  return {
+    last,
+    current,
+    maxTotal: Math.max(last.total, current.total, 1),
+  };
+}

package/src/sdk/app/topUps.js

@@ -28,24 +28,18 @@ export async function getTopUps(context, { appKey, portalId } = {}) {
   return callAppApi(context, billingPath(appKey, "top-ups", portalId), "GET");
 }
 
-// GET {billingBaseUrl}/v1/billing/invoices?token=... ->
-//   { invoices: [{ id, date, description, amount_cents, currency, status,
-//                  hosted_invoice_url, kind }] }  (newest first, capped at 24)
-//
-// The billing service (growth-ops-apps-app), NOT base — see the header note.
-// Auth is the signed billing-action `token` query param
-// (common.billing.action_token): the endpoint is read-only and accepts any
-// action; BillingTab passes the (interval-refreshed)
-// state.billing_action_tokens.portal. The claim carries app_key + portal_id,
-// so the response is scoped to THIS portal's Stripe customer — never a
-// stranger's invoices.
-//
-// Throws AppApiError on failure, with the FastAPI {"detail": ...} string as
-// the message — a 404 means the billing service predates the invoices route
-// (the caller hides the section rather than erroring forever).
-export async function getInvoices({ billingBaseUrl, token } = {}) {
-  const url = `${billingBaseUrl}/v1/billing/invoices?token=${encodeURIComponent(token)}`;
-  const response = await hubspot.fetch(url, { timeout: 10000, method: "GET" });
+// Shared fetch for the BILLING service's token-auth routes
+// (/v1/billing/*) — bare hubspot.fetch with the signed action token as a
+// query param, no custom headers (the platform rejects them), body as a plain
+// object (hubspot.fetch serializes it; see callAppApi's header note).
+// Throws AppApiError on failure with the FastAPI {"detail": ...} string as
+// the message.
+async function billingFetch(url, { method = "GET", body } = {}) {
+  const response = await hubspot.fetch(url, {
+    timeout: 10000,
+    method,
+    ...(body && { body }),
+  });
   if (!response.ok) {
     const errorText = await response.text();
     // FastAPI errors come back as {"detail": "..."} — surface just the detail
@@ -64,6 +58,49 @@ export async function getInvoices({ billingBaseUrl, token } = {}) {
   return response.json();
 }
 
+// GET {billingBaseUrl}/v1/billing/invoices?token=... ->
+//   { invoices: [{ id, date, description, amount_cents, currency, status,
+//                  hosted_invoice_url, kind }] }  (newest first, capped at 24)
+//
+// The billing service (growth-ops-apps-app), NOT base — see the header note.
+// Auth is the signed billing-action `token` query param
+// (common.billing.action_token): the endpoint is read-only and accepts any
+// action; BillingTab passes the (interval-refreshed)
+// state.billing_action_tokens.portal. The claim carries app_key + portal_id,
+// so the response is scoped to THIS portal's Stripe customer — never a
+// stranger's invoices.
+//
+// A 404 means the billing service predates the invoices route (the caller
+// hides the section rather than erroring forever).
+export async function getInvoices({ billingBaseUrl, token } = {}) {
+  const url = `${billingBaseUrl}/v1/billing/invoices?token=${encodeURIComponent(token)}`;
+  return billingFetch(url, { method: "GET" });
+}
+
+// POST /v1/hubspot/app_pages/{app}/billing/auto-provision, body
+// { enabled: bool } — set the account's auto-provision flag (REPLACES the old
+// billing-limit concept): enabled buys another pack of additional credits
+// when the monthly credits run out; disabled means no purchase and actions
+// start failing the entitlement gate.
+//
+// This route lives on the BASE service (same app_pages family as
+// billing/limit), NOT the GOAA billing service — there is no
+// /v1/billing/auto-provision there. Same callAppApi + ?token= posture as
+// setBillingLimit below: verify_hubspot plus the billing action token (the
+// claim scopes the change to THIS portal's account); BillingTab passes the
+// interval-refreshed state.billing_action_tokens.portal.
+export async function setAutoProvision(
+  context,
+  { appKey, portalId, enabled, token } = {}
+) {
+  return callAppApi(
+    context,
+    billingPath(appKey, "auto-provision", portalId, { token }),
+    "POST",
+    { enabled: !!enabled }
+  );
+}
+
 // POST /v1/hubspot/app_pages/{app}/billing/limit, body { limit_cents: int|null }
 // — set (or clear, with null) the per-period auto top-up spend cap. Body is a
 // plain object, never JSON.stringify'd (the hubspot.fetch rule callAppApi

package/src/sdk/index.js

@@ -4,7 +4,7 @@
 // App backend (context.variables.BASE_URL) via hubspot.fetch.
 export { callAppApi, AppApiError } from "./app/base";
 export { getAlerts, dismissAlert } from "./app/alerts";
-export { getTopUps, getInvoices, setBillingLimit } from "./app/topUps";
+export { getTopUps, getInvoices, setBillingLimit, setAutoProvision } from "./app/topUps";
 export { getSettings, updateSettings, makeSettingsApi } from "./app/settings";
 export {
   strToBase64,

package/src/usage/UsageTab.jsx

@@ -27,6 +27,7 @@ import {
 } from "@hubspot/ui-extensions";
 
 import { useStrictModeEffect } from "../lib/useStrictModeEffect";
+import { CreditMeter } from "../home/CreditMeter";
 
 const DEFAULT_BASE_PATH = "/api/v1/usage";
 
@@ -34,25 +35,39 @@ const WINDOW_OPTIONS = [
   { label: "Last 7 days", value: "7" },
   { label: "Last 30 days", value: "30" },
   { label: "Last 90 days", value: "90" },
+  { label: "Last 180 days", value: "180" },
+  { label: "Last 365 days", value: "365" },
 ];
 
 // context: extension context. basePath/portalId: target the right backend
-// (base-hosted apps pass both). appName: chart copy.
+// (base-hosted apps pass both). appName: chart copy. state: the /v1/home
+// payload (optional) — when present, the credit meter renders at the TOP of
+// the tab (Andrew's 2026-10 feedback: the meter moved off Home); without it
+// the tab is chart-only, same as before.
 export function UsageTab({
   context,
   basePath = DEFAULT_BASE_PATH,
   portalId,
   appName = "this app",
+  state = null,
 }) {
   const [days, setDays] = useState("30");
 
   return (
     <Flex direction="column" gap="medium">
+      {state && (
+        <CreditMeter
+          entitlement={state.entitlement}
+          creditMeter={state.credit_meter}
+          credits={state.credits}
+        />
+      )}
+
       <Flex direction="row" justify="between" align="end">
         <Heading>Usage</Heading>
         <Select
-          label="Window"
-          name="window"
+          label="Time period"
+          name="time-period"
           options={WINDOW_OPTIONS}
           value={days}
           onChange={setDays}
@@ -131,7 +146,7 @@ function UsageContent({ context, basePath, portalId, appName, days }) {
     <Flex direction="column" gap="medium">
       <Tile>
         <Statistics>
-          <StatisticsItem label="Used (window)" number={usedInWindow} />
+          <StatisticsItem label={`Used (last ${days} days)`} number={usedInWindow} />
           {hasBalance && <StatisticsItem label="Remaining" number={remaining} />}
           {hasBalance && <StatisticsItem label="Granted" number={granted} />}
         </Statistics>