@startsimpli/billing 0.4.32 → 0.4.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@startsimpli/billing",
-  "version": "0.4.32",
+  "version": "0.4.34",
   "description": "Universal billing integration for StartSimpli Next.js apps",
   "license": "MIT",
   "homepage": "https://startsimpli.com",
@@ -19,6 +19,7 @@
     "./client": "./src/index.ts",
     "./server": "./src/server/index.ts",
     "./plan": "./src/utils/plan.ts",
+    "./credits": "./src/credits/index.ts",
     "./types": "./src/types/index.ts",
     "./mock": "./src/mock/index.ts"
   },
@@ -33,7 +34,17 @@
   "peerDependencies": {
     "next": ">=14.0.0",
     "react": "^18.0.0 || ^19.0.0",
-    "react-dom": "^18.0.0 || ^19.0.0"
+    "react-dom": "^18.0.0 || ^19.0.0",
+    "@startsimpli/api": "^0.5.73",
+    "@startsimpli/ui": "^0.4.175"
+  },
+  "peerDependenciesMeta": {
+    "@startsimpli/api": {
+      "optional": true
+    },
+    "@startsimpli/ui": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@testing-library/jest-dom": "^6.9.1",
@@ -49,7 +60,9 @@
     "react-dom": "^19.2.5",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.5"
+    "vitest": "^4.1.5",
+    "@startsimpli/api": "0.5.73",
+    "@startsimpli/ui": "0.4.175"
   },
   "keywords": [
     "billing",

package/src/components/PricingDetailPage.tsx

@@ -20,6 +20,7 @@ import {
   planDirection,
   resolveCurrentOffer,
   trialApplies,
+  trialLabel,
   type CurrentPlanState,
 } from "../utils/plan";
 import { usePlanChange } from "../hooks/usePlanChange";
@@ -330,7 +331,7 @@ function DetailCard({
       <div className="mb-5 min-h-8">
         {trial ? (
           <span data-testid={`trial-pill-${offer.slug}`} className="inline-block bg-[var(--billing-accent-soft,#eff6ff)] text-[color:var(--billing-accent-text,#1d4ed8)] text-sm font-semibold px-3 py-1 rounded-lg w-fit">
-            {offer.trialDays}-day free trial
+            {trialLabel(offer)}
           </span>
         ) : yourPlanNote ? (
           <span data-testid={`your-plan-note-${offer.slug}`} className="inline-block bg-gray-100 text-gray-700 text-sm font-semibold px-3 py-1 rounded-lg w-fit">

package/src/components/PricingPage.tsx

@@ -13,7 +13,7 @@ import { useProduct } from "../hooks/useProduct";
 import type { ProductOffer } from "../types";
 import { FeatureIcon } from "./FeatureIcon";
 import { formatFeatureLabel } from "../utils/format";
-import { resolveCurrentOfferId, type CurrentPlanState } from "../utils/plan";
+import { resolveCurrentOfferId, trialLabel, type CurrentPlanState } from "../utils/plan";
 import { AnnualNote, IntervalToggle, OfferPrice, useIntervalOffers, type IntervalEntry } from "./IntervalToggle";
 
 export interface PricingPageProps {
@@ -136,7 +136,7 @@ function PricingCard({ entry, onSelect, isCurrent = false }: PricingCardProps) {
           data-testid="trial-badge"
           className="inline-block bg-blue-50 text-blue-700 text-sm font-semibold px-3 py-1 rounded-lg mb-5 w-fit"
         >
-          {offer.trialDays}-day free trial
+          {trialLabel(offer)}
         </span>
       )}
 

package/src/components/PricingSection.tsx

@@ -14,7 +14,7 @@ import type { OfferFeature, ProductOffer } from "../types";
 import { cardFeatures, cumulativeFeatureLookup, tierBelow } from "../utils/tiers";
 import { FeatureIcon } from "./FeatureIcon";
 import { formatFeatureLabel } from "../utils/format";
-import { resolveCurrentOfferId, type CurrentPlanState } from "../utils/plan";
+import { resolveCurrentOfferId, trialLabel, type CurrentPlanState } from "../utils/plan";
 import { AnnualNote, IntervalToggle, OfferPrice, useIntervalOffers, type IntervalEntry } from "./IntervalToggle";
 
 export interface PricingSectionProps {
@@ -152,7 +152,7 @@ function SectionCard({ entry, onSelect, maxFeatures, buildsOn, inherited, isCurr
             data-testid="trial-badge"
             className="inline-block bg-[var(--billing-accent-soft,#eff6ff)] text-[color:var(--billing-accent-text,#1d4ed8)] text-xs font-semibold px-2 py-0.5 rounded-md w-fit"
           >
-            {offer.trialDays}-day free trial
+            {trialLabel(offer)}
           </span>
         )}
       </div>

package/src/components/SubscriptionManager.tsx

@@ -29,6 +29,7 @@ import {
   planCtaLabel,
   planDirection,
   trialApplies,
+  trialLabel,
   TRIAL_NOTE_FEATURE_KEY,
   type PlanDirection,
 } from "../utils/plan";
@@ -95,11 +96,11 @@ function PlanFeatureList({ features, showTrialNote = true }: { features: OfferFe
  * startsim-pih — so users know "Start Free Trial" actually IS a free trial.
  * No "no card required": checkout collects a card up front and the offer
  * carries nothing that says otherwise (crochet_patterns-34n7). */
-function TrialCopy({ trialDays }: { trialDays: number }) {
-  if (!trialDays || trialDays <= 0) return null;
+function TrialCopy({ offer }: { offer: ProductOffer }) {
+  if (!offer.trialDays || offer.trialDays <= 0) return null;
   return (
     <p data-testid="trial-copy" className="-mt-1 mb-3 text-xs text-gray-500">
-      {trialDays}-day free trial
+      {trialLabel(offer)}
     </p>
   );
 }
@@ -566,7 +567,7 @@ export function SubscriptionManager({
                   {/* Trial copy is for prospective trialers only — once the
                       user is on this offer or moving downward, drop the
                       "14-day free trial" sales pitch. */}
-                  {showTrial && <TrialCopy trialDays={offer.trialDays} />}
+                  {showTrial && <TrialCopy offer={offer} />}
                   <PlanFeatureList features={offer.features} showTrialNote={showTrial || !(offer.trialDays > 0)} />
                   <button
                     data-testid={`upgrade-cta-${offer.slug}`}

package/src/components/UpgradeModal.tsx

@@ -21,6 +21,7 @@ import {
   planDirection,
   resolveCurrentOffer,
   trialApplies,
+  trialLabel,
   TRIAL_NOTE_FEATURE_KEY,
   type CurrentPlanState,
 } from "../utils/plan";
@@ -201,7 +202,7 @@ export function UpgradeModal({
 
                   {trial && (
                     <span data-testid={`trial-pill-${offer.slug}`} className="inline-block bg-blue-50 text-blue-700 text-xs font-semibold px-2.5 py-0.5 rounded-md mb-3 w-fit">
-                      {offer.trialDays}-day free trial
+                      {trialLabel(offer)}
                     </span>
                   )}
 

package/src/components/UsageMeters.test.tsx

@@ -0,0 +1,27 @@
+import { render, screen } from "@testing-library/react";
+import React from "react";
+import { describe, expect, it, vi } from "vitest";
+import { UsageMeters } from "./UsageMeters";
+
+const state = vi.hoisted(() => ({ usage: {} as Record<string, { used: number; limit: number | null }> }));
+vi.mock("../hooks/useUsage", () => ({ useUsage: () => ({ usage: state.usage, refetch: vi.fn() }) }));
+vi.mock("../hooks/useSubscription", () => ({
+  useSubscription: () => ({ subscription: { offer: { features: [{ key: "designs", name: "Designs" }] } } }),
+}));
+
+describe("UsageMeters", () => {
+  it("renders nothing without capped features", () => {
+    state.usage = { x: { used: 1, limit: null } };
+    const { container } = render(<UsageMeters productSlug="p" />);
+    expect(container.innerHTML).toBe("");
+  });
+
+  it("renders a meter per capped feature with the plan's label and a state note", () => {
+    state.usage = { designs: { used: 9, limit: 10 }, extra: { used: 3, limit: 3 } };
+    render(<UsageMeters productSlug="p" copy={{ atCap: "Maxed" }} />);
+    expect(screen.getByTestId("meter-designs").getAttribute("data-state")).toBe("approaching");
+    expect(screen.getByText("Designs")).toBeTruthy();
+    expect(screen.getByText("1 of 10 left")).toBeTruthy();
+    expect(screen.getByText("Maxed")).toBeTruthy();
+  });
+});

package/src/components/UsageMeters.tsx

@@ -0,0 +1,85 @@
+"use client";
+
+import { useEffect, useMemo, useRef } from "react";
+import { useSubscription } from "../hooks/useSubscription";
+import { useUsage } from "../hooks/useUsage";
+import { meterRows, type MeterState } from "../utils/usage-meters";
+
+export interface UsageMetersCopy {
+  /** Shown on a meter at 80%+ of its cap. */
+  approaching: string;
+  /** Shown on a meter at its cap. */
+  atCap: string;
+  /** "{left} of {limit} left" line. */
+  left: (left: number, limit: number) => string;
+}
+
+const DEFAULT_COPY: UsageMetersCopy = {
+  approaching: "Almost used up",
+  atCap: "Limit reached",
+  left: (left, limit) => `${left} of ${limit} left`,
+};
+
+const TONE: Record<MeterState, { box: string; bar: string }> = {
+  ok: { box: "border-border bg-card", bar: "bg-primary" },
+  approaching: { box: "border-amber-300 bg-amber-50", bar: "bg-amber-500" },
+  "at-cap": { box: "border-red-300 bg-red-50", bar: "bg-red-500" },
+};
+
+/** Re-reads after checkout: the first read can predate the new plan. */
+const AFTER_CHECKOUT_REFETCH_MS = 2000;
+const AFTER_CHECKOUT_REFETCH_TRIES = 5;
+
+export interface UsageMetersProps {
+  productSlug: string;
+  /** Back from checkout: ask again a few times while usage still reads empty. */
+  afterCheckout?: boolean;
+  copy?: Partial<UsageMetersCopy>;
+}
+
+/** One meter per capped feature of the person's plan; nothing for unlimited ones. */
+export function UsageMeters({ productSlug, afterCheckout = false, copy }: UsageMetersProps) {
+  const text = { ...DEFAULT_COPY, ...copy };
+  const { usage, refetch } = useUsage(productSlug);
+  const { subscription } = useSubscription(productSlug);
+
+  const left = useRef(AFTER_CHECKOUT_REFETCH_TRIES);
+  const stillEmpty = Object.keys(usage).length === 0;
+  useEffect(() => {
+    if (!afterCheckout || !stillEmpty || left.current <= 0) return;
+    const t = setTimeout(() => {
+      left.current -= 1;
+      refetch();
+    }, AFTER_CHECKOUT_REFETCH_MS);
+    return () => clearTimeout(t);
+  }, [afterCheckout, stillEmpty, refetch]);
+
+  const labels = useMemo(() => {
+    const map: Record<string, string> = {};
+    for (const f of subscription?.offer?.features ?? []) map[f.key] = f.name;
+    return map;
+  }, [subscription]);
+  const rows = meterRows(usage, labels);
+  if (rows.length === 0) return null;
+
+  return (
+    <div className="mb-6 space-y-3" data-testid="usage-meters">
+      {rows.map((r) => {
+        const tone = TONE[r.state];
+        const note = r.state === "at-cap" ? text.atCap : r.state === "approaching" ? text.approaching : null;
+        return (
+          <div key={r.key} data-testid={`meter-${r.key}`} data-state={r.state} className={`rounded-lg border p-4 ${tone.box}`}>
+            <div className="mb-1.5 flex items-center justify-between gap-3">
+              <h3 className="text-sm font-semibold">{r.label}</h3>
+              {note && <span className="text-xs font-medium">{note}</span>}
+            </div>
+            <p className="mb-2 text-sm text-muted-foreground tabular-nums">{text.left(r.left, r.limit)}</p>
+            <div className="h-2 w-full rounded-full bg-muted" aria-hidden="true">
+              <div className={`h-2 rounded-full transition-all ${tone.bar}`} style={{ width: `${Math.max(r.pct, 3)}%` }} />
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}

package/src/components/index.ts

@@ -18,3 +18,5 @@ export { LimitNudge } from "./LimitNudge";
 export type { LimitNudgeProps } from "./LimitNudge";
 export { PlanChangeConfirm, planChangeCopy } from "./PlanChangeConfirm";
 export type { PlanChangeConfirmProps } from "./PlanChangeConfirm";
+export { UsageMeters } from "./UsageMeters";
+export type { UsageMetersProps, UsageMetersCopy } from "./UsageMeters";

package/src/credits/CreditBalanceBadge.tsx

@@ -0,0 +1,13 @@
+import type { CreditsCopy } from "./copy";
+
+/** The balance, read out in full by screen readers. */
+export function CreditBalanceBadge({ balance, copy, className = "" }: { balance: number; copy: CreditsCopy; className?: string }) {
+  return (
+    <span
+      aria-label={copy.badgeLabel(balance)}
+      className={`inline-flex items-center rounded-full bg-green-100 px-3 py-1 text-sm font-medium text-green-800 ${className}`}
+    >
+      <span aria-hidden="true">{copy.badge(balance)}</span>
+    </span>
+  );
+}

package/src/credits/CreditHistoryList.tsx

@@ -0,0 +1,32 @@
+import type { CreditsCopy } from "./copy";
+import type { PatternCreditHistoryEntry } from "./types";
+
+const when = (iso: string) => {
+  const d = new Date(iso);
+  return Number.isNaN(d.getTime()) ? "" : d.toLocaleDateString("en-US", { month: "short", day: "numeric", year: "numeric" });
+};
+
+/** Purchases and use, in the order given (newest first from the server). */
+export function CreditHistoryList({ history, copy }: { history: PatternCreditHistoryEntry[]; copy: CreditsCopy }) {
+  if (history.length === 0) return <p className="text-sm text-muted-foreground">{copy.historyEmpty}</p>;
+  const label = (e: PatternCreditHistoryEntry) =>
+    e.entryType === "grant" && e.reason ? e.reason : copy.entry[e.entryType] ?? e.entryType;
+  return (
+    <ul aria-label={copy.historyTitle} className="divide-y divide-border rounded-lg border border-border bg-card">
+      {history.map((e) => (
+        <li key={e.id} className="flex items-center justify-between gap-3 px-4 py-3 text-sm">
+          <span className="min-w-0">
+            <span className="block truncate text-foreground">{label(e)}</span>
+            <span className="block text-xs text-muted-foreground">{when(e.createdAt)}</span>
+          </span>
+          <span
+            className={`shrink-0 font-semibold ${e.quantity > 0 ? "text-green-700" : "text-muted-foreground"}`}
+            aria-label={`${e.quantity > 0 ? "plus" : "minus"} ${Math.abs(e.quantity)}`}
+          >
+            {e.quantity > 0 ? `+${e.quantity}` : e.quantity}
+          </span>
+        </li>
+      ))}
+    </ul>
+  );
+}

package/src/credits/CreditPackCard.tsx

@@ -0,0 +1,51 @@
+import { Button } from "@startsimpli/ui";
+import { formatPackPrice, pricePerCredit, savingsPercent } from "../utils/credit-math";
+import type { CreditsCopy } from "./copy";
+import type { PatternCreditOffer } from "./types";
+
+export interface CreditPackCardProps {
+  offer: PatternCreditOffer;
+  copy: CreditsCopy;
+  /** Offer id being opened in checkout, if any. */
+  buying: string | null;
+  onBuy: (offerId: string) => void;
+}
+
+/** One pack: its price, the struck-through price and saving when the offer has one, and a Buy button. */
+export function CreditPackCard({ offer, copy, buying, onBuy }: CreditPackCardProps) {
+  const saving = savingsPercent(offer);
+  const name = copy.packName(offer.credits);
+  const opening = buying === offer.id;
+  return (
+    <li className={`flex flex-col rounded-xl border p-4 ${offer.featured ? "border-primary bg-primary/5" : "border-border bg-card"}`}>
+      <div className="flex items-start justify-between gap-2">
+        <p className="text-base font-semibold text-foreground">{name}</p>
+        {offer.featured && (
+          <span className="rounded-full bg-primary px-2 py-0.5 text-xs font-semibold text-primary-foreground">{copy.featured}</span>
+        )}
+      </div>
+      <p className="mt-3 flex flex-wrap items-baseline gap-x-2">
+        <span className="text-2xl font-bold text-foreground">{formatPackPrice(offer.price, offer.currency)}</span>
+        {saving !== null && (
+          <s className="text-sm text-muted-foreground" style={{ textDecoration: "line-through" }}>
+            {formatPackPrice(offer.compareAt, offer.currency)}
+          </s>
+        )}
+      </p>
+      <p className="mt-1 min-h-[1.25rem] text-sm text-muted-foreground">
+        {saving !== null && <span className="font-medium text-green-700">{copy.save(saving)}</span>}
+        {saving !== null && offer.credits > 1 && " · "}
+        {offer.credits > 1 && copy.perCredit(formatPackPrice(pricePerCredit(offer), offer.currency))}
+      </p>
+      <Button
+        className="mt-4 w-full"
+        variant={offer.featured ? "default" : "outline"}
+        disabled={buying !== null}
+        onClick={() => onBuy(offer.id)}
+        aria-label={opening ? undefined : copy.buy(name)}
+      >
+        {opening ? copy.buying : copy.buy(name)}
+      </Button>
+    </li>
+  );
+}

package/src/credits/CreditsPanel.tsx

@@ -0,0 +1,60 @@
+"use client";
+
+import { Button } from "@startsimpli/ui";
+import { CreditBalanceBadge } from "./CreditBalanceBadge";
+import { CreditHistoryList } from "./CreditHistoryList";
+import { CreditPackCard } from "./CreditPackCard";
+import { withCreditsCopy, type CreditsCopy } from "./copy";
+import type { CreditsView } from "./types";
+
+export interface CreditsPanelProps {
+  credits: CreditsView;
+  copy?: Partial<CreditsCopy>;
+  headingId?: string;
+}
+
+/**
+ * Buy credits, see the balance and the history. Renders nothing while the sale
+ * is off (flag off, signed out, or the server's 409), so the page is exactly
+ * what it was.
+ */
+export function CreditsPanel({ credits, copy: copyIn, headingId = "credits-heading" }: CreditsPanelProps) {
+  const copy = withCreditsCopy(copyIn);
+  if (credits.status === "disabled") return null;
+  return (
+    <section aria-labelledby={headingId} className="mb-8 rounded-xl border border-border bg-muted/40 p-4 sm:p-6">
+      <div className="mb-4 flex flex-wrap items-center justify-between gap-2">
+        <h3 id={headingId} className="text-lg font-semibold text-foreground">{copy.sectionTitle}</h3>
+        {credits.status === "ready" && <CreditBalanceBadge balance={credits.balance} copy={copy} />}
+      </div>
+
+      {credits.status === "loading" && (
+        <p role="status" aria-live="polite" className="text-sm text-muted-foreground">{copy.loading}</p>
+      )}
+
+      {credits.status === "error" && (
+        <div role="alert" className="flex flex-wrap items-center gap-3 rounded-lg border border-red-200 bg-red-50 p-3 text-sm text-red-700">
+          <span>{copy.loadError}</span>
+          <Button size="sm" variant="outline" onClick={() => void credits.refresh()}>{copy.retry}</Button>
+        </div>
+      )}
+
+      {credits.status === "ready" && (
+        <>
+          <p className="mb-4 text-sm text-muted-foreground">{copy.sectionIntro}</p>
+          {credits.error && (
+            <p role="alert" className="mb-4 rounded-lg border border-red-200 bg-red-50 p-3 text-sm text-red-700">{credits.error}</p>
+          )}
+          <ul className="mb-2 grid gap-3 sm:grid-cols-2 lg:grid-cols-3">
+            {credits.offers.map((offer) => (
+              <CreditPackCard key={offer.id} offer={offer} copy={copy} buying={credits.buying} onBuy={(id) => void credits.buy(id)} />
+            ))}
+          </ul>
+          <p className="mb-6 text-xs text-muted-foreground">{copy.secure}</p>
+          <h4 className="mb-2 text-sm font-semibold text-foreground">{copy.historyTitle}</h4>
+          <CreditHistoryList history={credits.history} copy={copy} />
+        </>
+      )}
+    </section>
+  );
+}

package/src/credits/CreditsReturn.tsx

@@ -0,0 +1,89 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Button } from "@startsimpli/ui";
+import { withCreditsCopy, type CreditsCopy } from "./copy";
+import type { CreditsView } from "./types";
+
+type Phase = "pending" | "done" | "waiting" | "error";
+
+const LINK = "rounded-lg px-4 py-2 text-sm font-semibold";
+
+export interface CreditsReturnLinks {
+  /** Where "continue" goes (e.g. the builder). */
+  continueHref: string;
+  billingHref: string;
+}
+
+export interface CreditsSuccessProps extends CreditsReturnLinks {
+  credits: Pick<CreditsView, "status" | "sync">;
+  /** Stripe session from the return URL (`creditSessionFrom`). */
+  sessionId: string | null;
+  copy?: Partial<CreditsCopy>;
+}
+
+/** Back from Stripe: confirm the paid session (the webhook may not have arrived) and show the balance. */
+export function CreditsSuccess({ credits, sessionId, continueHref, billingHref, copy: copyIn }: CreditsSuccessProps) {
+  const copy = withCreditsCopy(copyIn);
+  const [phase, setPhase] = useState<Phase>("pending");
+  const [balance, setBalance] = useState(0);
+  const started = useRef(false);
+  const { sync } = credits;
+
+  const run = useCallback(async () => {
+    if (!sessionId) return;
+    setPhase("pending");
+    try {
+      const r = await sync(sessionId);
+      setBalance(r.balance);
+      setPhase(r.granted ? "done" : "waiting");
+    } catch {
+      setPhase("error");
+    }
+  }, [sessionId, sync]);
+
+  useEffect(() => {
+    if (!sessionId || started.current || credits.status === "disabled") return;
+    started.current = true;
+    void run();
+  }, [sessionId, credits.status, run]);
+
+  return (
+    <div className="mx-auto max-w-lg py-10 text-center">
+      <h3 className="mb-4 text-xl font-semibold text-foreground">{copy.successTitle}</h3>
+      {!sessionId && <p className="text-sm text-muted-foreground">{copy.successMissingSession}</p>}
+      {sessionId && phase === "pending" && <p role="status" className="text-sm text-muted-foreground">{copy.successPending}</p>}
+      {sessionId && phase === "done" && <p role="status" className="text-sm text-foreground">{copy.successDone(1, balance)}</p>}
+      {sessionId && phase === "waiting" && (
+        <div role="status" className="space-y-3 text-sm text-muted-foreground">
+          <p>{copy.successStillPending}</p>
+          <Button variant="outline" onClick={() => void run()}>{copy.successCheckAgain}</Button>
+        </div>
+      )}
+      {sessionId && phase === "error" && (
+        <div role="alert" className="space-y-3 rounded-lg border border-red-200 bg-red-50 p-4 text-sm text-red-700">
+          <p>{copy.successSyncError}</p>
+          <Button variant="outline" onClick={() => void run()}>{copy.successCheckAgain}</Button>
+        </div>
+      )}
+      <div className="mt-6 flex flex-wrap justify-center gap-3">
+        <a href={continueHref} className={`${LINK} bg-primary text-primary-foreground hover:opacity-90`}>{copy.continueLabel}</a>
+        <a href={billingHref} className={`${LINK} border border-border text-foreground hover:bg-muted`}>{copy.seeBilling}</a>
+      </div>
+    </div>
+  );
+}
+
+/** Back from Stripe after cancelling. */
+export function CreditsCancelled({ billingHref, copy: copyIn }: { billingHref: string; copy?: Partial<CreditsCopy> }) {
+  const copy = withCreditsCopy(copyIn);
+  return (
+    <div className="mx-auto max-w-lg py-10 text-center">
+      <h3 className="mb-4 text-xl font-semibold text-foreground">{copy.cancelledTitle}</h3>
+      <p className="text-sm text-muted-foreground">{copy.cancelledBody}</p>
+      <div className="mt-6">
+        <a href={billingHref} className={`${LINK} bg-primary text-primary-foreground hover:opacity-90`}>{copy.tryAgain}</a>
+      </div>
+    </div>
+  );
+}

package/src/credits/UseCreditPrompt.tsx

@@ -0,0 +1,46 @@
+"use client";
+
+import { Button } from "@startsimpli/ui";
+import { CreditPackCard } from "./CreditPackCard";
+import { withCreditsCopy, type CreditsCopy } from "./copy";
+import type { PatternCreditOffer } from "./types";
+
+export interface UseCreditPromptProps {
+  balance: number;
+  offers: PatternCreditOffer[];
+  buying: string | null;
+  error: string | null;
+  onUse: () => void;
+  onBuy: (offerId: string) => void;
+  onCancel: () => void;
+  /** True when the plan's monthly allowance is used up (vs. no plan at all). */
+  planAllowanceUsed?: boolean;
+  copy?: Partial<CreditsCopy>;
+}
+
+/** At the action button, when the plan cannot cover it: confirm using a credit, or (with none left) buy a pack. */
+export function UseCreditPrompt({ balance, offers, buying, error, onUse, onBuy, onCancel, planAllowanceUsed, copy: copyIn }: UseCreditPromptProps) {
+  const copy = withCreditsCopy(copyIn);
+  const title = balance > 0 ? copy.confirmTitle : copy.outTitle;
+  return (
+    <div role="dialog" aria-label={title} className="w-full rounded-xl border border-border bg-muted/40 p-4 text-left">
+      <h4 className="text-base font-semibold text-foreground">{title}</h4>
+      <p className="mt-1 text-sm text-muted-foreground">{balance > 0 ? copy.confirmBody(balance) : copy.outBody}</p>
+      {planAllowanceUsed && balance > 0 && <p className="mt-1 text-xs text-muted-foreground">{copy.planAllowanceUsed}</p>}
+      {error && <p role="alert" className="mt-2 text-sm text-red-700">{error}</p>}
+      {balance > 0 ? (
+        <div className="mt-4 flex flex-wrap gap-2">
+          <Button onClick={onUse}>{copy.confirmUse}</Button>
+          <Button variant="outline" onClick={onCancel}>{copy.confirmCancel}</Button>
+        </div>
+      ) : (
+        <>
+          <ul className="mt-4 grid gap-3 sm:grid-cols-2">
+            {offers.map((o) => <CreditPackCard key={o.id} offer={o} copy={copy} buying={buying} onBuy={onBuy} />)}
+          </ul>
+          <div className="mt-3"><Button variant="outline" size="sm" onClick={onCancel}>{copy.confirmCancel}</Button></div>
+        </>
+      )}
+    </div>
+  );
+}