feat(component): SubscriptionCard — Subscription Status & Management

[bntvllnt]

Summary

Full subscription status card handling the complete subscription lifecycle: active, trialing, canceling, past-due, canceled, and no-subscription states. Each state renders appropriate messaging, status badge, and call-to-action (subscribe, manage, sync). The primary billing page component for any SaaS product.

Proposed API

<SubscriptionCard
  subscription={{
    plan: "Pro",
    status: "active",
    currentPeriodEnd: 1713139200000,
    cancelAtPeriodEnd: false,
  }}
  onSubscribe={handleSubscribe}
  onManage={handleManage}
  onSync={handleSync}
/>

// No subscription
<SubscriptionCard
  subscription={null}
  onSubscribe={handleSubscribe}
  onSync={handleSync}
/>

// VIP/exempt
<SubscriptionCard exempt exemptLabel="VIP/Admin access. No subscription required." />

Requirements

• Status states: active (green border), trialing (blue), canceling (yellow), past_due (red), canceled (gray), null (neutral)
• Active state: plan name + status badge + renewal date + "Manage" CTA
• Canceling state: plan name + "Canceling" badge + "Access until {date}" + "Manage" CTA
• Inactive/null state: "No active subscription" + "Subscribe" CTA
• Exempt state: amber card with exempt message, no CTAs
• Built-in sync recovery action: "Already paid? Sync to restore access"
• Sync button with loading state + success/error feedback messages
• Status badge per state with matching color
• onSubscribe, onManage, onSync — render slots accept any CTA component (e.g., Polar CheckoutLink, Stripe portal link)
• Responsive: stacks vertically on mobile
• Dark mode: colored borders on dark backgrounds
• Accessible: status communicated via text, not just color

Visual States

┌─────────────────────────────────────────────────────────┐
│  ACTIVE                                                 │
│  ┌─────────────────────────── green border ─────────┐   │
│  │ AI OS Pro   [Active]           [Manage ▸]        │   │
│  │ Renews Mar 15, 2025                              │   │
│  └──────────────────────────────────────────────────┘   │
│                                                         │
│  CANCELING                                              │
│  ┌─────────────────────────── yellow border ────────┐   │
│  │ AI OS Pro   [Canceling]        [Manage ▸]        │   │
│  │ Access until Apr 15, 2025                        │   │
│  └──────────────────────────────────────────────────┘   │
│                                                         │
│  NO SUBSCRIPTION                                        │
│  ┌─────────────────────────── neutral border ───────┐   │
│  │ No active subscription         [Subscribe ▸]     │   │
│  │ Subscribe to unlock all features.                │   │
│  │ ─────────────────────────────────                │   │
│  │ [Sync Subscription]  Already paid? Sync.         │   │
│  └──────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘

Use Cases

• SaaS billing settings page
• Account management dashboard
• Admin panel user subscription view
• Onboarding paywall

Composes

• Badge, Button, Card

Origin

Extracted from SubscriptionStatus, ActiveSubscription, InactiveSubscription, SyncSubscriptionButton in apps/web-ai-os/app/account/billing/billing-client.tsx in vllnt/vllnt monorepo.