feat(payment): #5 subscription management surface end-to-end (#140)

User-facing subscription management plus the schema-drift fix the existing
component was carrying.

- SubscriptionManager: reconcile the interface to the REAL subscriptions schema
  (plan_amount/plan_interval/grace_period/grace_period_expires; status enum
  active|past_due|grace_period|canceled|expired). The old interface read phantom
  columns (amount/currency/interval/cancel_at_period_end/'paused') so cards
  rendered $undefined and cancel/resume flipped a non-existent field. Cancel/
  resume now key off `status` (matching what the edge functions write). Adds a
  grace-period countdown ("N days remaining") + grace badge.
- New /account/subscriptions route (ProtectedRoute → SubscriptionManager) with
  the not-configured banner; mirrors /account/audit. Linked from /account.
- Grace-period population in BOTH webhooks on payment-failed: status →
  grace_period + grace_period_expires = now + 7d (YYYY-MM-DD). Adds the missing
  PayPal BILLING.SUBSCRIPTION.PAYMENT.FAILED branch. Fixes a real bug: the Stripe
  handler used `supabase.sql\`failed_payment_count + 1\`` (no such client API) so
  the counter never incremented — now a read-then-write.
- Duplicate-subscription guard (root cause): partial unique index
  idx_subscriptions_one_live_per_user on (template_user_id) WHERE status in
  active/grace_period/past_due. Both webhook upserts catch 23505 and acknowledge
  (no 500 → no provider retry storm). No trigger / SECURITY DEFINER.
- Tests: grace countdown + expired-clamp + resume-for-canceled (component);
  un-skip the subscription-route-renders E2E; the seed-dependent flows get honest
  skip reasons (route + guard exist; they need a seed fixture).

Migration index + webhook redeploys applied to prod at merge time.

Co-authored-by: TurtleWolfe <TurtleWolfe@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

src/app/account/page.tsx

@@ -46,6 +46,12 @@ export default function AccountPage() {
             >
               View payment dashboard
             </Link>
+            <Link
+              href="/account/subscriptions"
+              className="btn btn-outline min-h-11 w-full"
+            >
+              Manage subscriptions
+            </Link>
           </div>
         </div>
       </main>

src/app/account/subscriptions/SubscriptionsContent.tsx

@@ -0,0 +1,53 @@
+'use client';
+
+import React from 'react';
+import { useAuth } from '@/contexts/AuthContext';
+import { SubscriptionManager } from '@/components/payment/SubscriptionManager';
+import { featureFlags } from '@/config/payment';
+
+/**
+ * Client body of /account/subscriptions (#5). Shows the not-configured banner
+ * when neither provider is set up (mirrors /payment-demo), then the
+ * SubscriptionManager for the signed-in user.
+ */
+export function SubscriptionsContent() {
+  const { user } = useAuth();
+  const noProvidersConfigured =
+    !featureFlags.stripeEnabled && !featureFlags.paypalEnabled;
+
+  return (
+    <div className="flex flex-col gap-6">
+      {noProvidersConfigured && (
+        <div role="alert" className="alert alert-warning">
+          <svg
+            xmlns="http://www.w3.org/2000/svg"
+            className="h-6 w-6 shrink-0 stroke-current"
+            fill="none"
+            viewBox="0 0 24 24"
+            aria-hidden="true"
+          >
+            <path
+              strokeLinecap="round"
+              strokeLinejoin="round"
+              strokeWidth="2"
+              d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z"
+            />
+          </svg>
+          <div>
+            <p className="font-semibold">Payment providers not configured</p>
+            <p className="text-sm">
+              New subscriptions can&apos;t be created until Stripe or PayPal is
+              set up. Set <code>NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY</code> and/or{' '}
+              <code>NEXT_PUBLIC_PAYPAL_CLIENT_ID</code> in <code>.env</code>.
+              See <code>docs/PAYMENT-DEPLOYMENT.md</code>.
+            </p>
+          </div>
+        </div>
+      )}
+
+      {user && <SubscriptionManager userId={user.id} />}
+    </div>
+  );
+}
+
+export default SubscriptionsContent;

src/app/account/subscriptions/page.tsx

@@ -0,0 +1,43 @@
+import React from 'react';
+import type { Metadata } from 'next';
+import Link from 'next/link';
+import ProtectedRoute from '@/components/auth/ProtectedRoute';
+import { SubscriptionsContent } from './SubscriptionsContent';
+
+export const metadata: Metadata = {
+  title: 'Subscriptions - ScriptHammer',
+  description: 'Manage your active subscriptions',
+  robots: {
+    index: false,
+    follow: false,
+    googleBot: {
+      index: false,
+      follow: false,
+    },
+  },
+};
+
+/**
+ * /account/subscriptions — user-facing subscription management (#5). Behind
+ * ProtectedRoute; wraps the SubscriptionManager organism (cancel/resume +
+ * grace-period countdown). Mirrors the /account/audit route (server page +
+ * client content) and the /payment-demo not-configured banner.
+ */
+export default function AccountSubscriptionsPage() {
+  return (
+    <ProtectedRoute>
+      <main className="container mx-auto px-4 py-12 sm:px-6 md:py-16 lg:px-8">
+        <div className="mx-auto max-w-3xl">
+          <div className="mb-6 flex items-center justify-between">
+            <h1 className="text-3xl font-bold">Subscriptions</h1>
+            <Link href="/account" className="btn btn-ghost min-h-11">
+              Back to Account
+            </Link>
+          </div>
+
+          <SubscriptionsContent />
+        </div>
+      </main>
+    </ProtectedRoute>
+  );
+}

src/components/payment/SubscriptionManager/SubscriptionManager.test.tsx

@@ -6,38 +6,38 @@ import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { render, screen, waitFor } from '@testing-library/react';
 import { SubscriptionManager } from './SubscriptionManager';
 
-// Mock Supabase client
+// Mutable rows so individual tests can stage grace-period / canceled states.
+let mockRows: Record<string, unknown>[] = [];
+
+const activeRow = {
+  id: 'sub-1',
+  provider_subscription_id: 'stripe_sub_123',
+  provider: 'stripe',
+  status: 'active',
+  plan_amount: 999,
+  plan_interval: 'month',
+  current_period_start: '2025-01-01T00:00:00Z',
+  current_period_end: '2025-02-01T00:00:00Z',
+  grace_period_expires: null,
+  canceled_at: null,
+  created_at: '2025-01-01T00:00:00Z',
+  updated_at: '2025-01-01T00:00:00Z',
+};
+
+// Mock Supabase client — returns the staged mockRows.
 vi.mock('@/lib/supabase/client', () => ({
   supabase: {
     from: vi.fn(() => ({
       select: vi.fn(() => ({
         eq: vi.fn(() => ({
           order: vi.fn(() => ({
-            data: [
-              {
-                id: 'sub-1',
-                provider_subscription_id: 'stripe_sub_123',
-                provider: 'stripe',
-                status: 'active',
-                amount: 999,
-                currency: 'usd',
-                interval: 'month',
-                current_period_start: '2025-01-01T00:00:00Z',
-                current_period_end: '2025-02-01T00:00:00Z',
-                cancel_at_period_end: false,
-                created_at: '2025-01-01T00:00:00Z',
-                updated_at: '2025-01-01T00:00:00Z',
-              },
-            ],
+            data: mockRows,
             error: null,
           })),
         })),
       })),
       update: vi.fn(() => ({
-        eq: vi.fn(() => ({
-          data: null,
-          error: null,
-        })),
+        eq: vi.fn(() => ({ data: null, error: null })),
       })),
     })),
   },
@@ -54,6 +54,7 @@ describe('SubscriptionManager', () => {
 
   beforeEach(() => {
     vi.clearAllMocks();
+    mockRows = [{ ...activeRow }];
   });
 
   it('should render loading state initially', () => {
@@ -83,4 +84,53 @@ describe('SubscriptionManager', () => {
     );
     expect(container.firstChild).toHaveClass('custom-class');
   });
+
+  it('shows a grace-period countdown with days remaining', async () => {
+    const inFiveDays = new Date(Date.now() + 5 * 86_400_000)
+      .toISOString()
+      .split('T')[0];
+    mockRows = [
+      {
+        ...activeRow,
+        status: 'grace_period',
+        grace_period_expires: inFiveDays,
+      },
+    ];
+    render(<SubscriptionManager {...defaultProps} />);
+    await waitFor(() => {
+      expect(screen.getByText(/5 days remaining/i)).toBeInTheDocument();
+    });
+    // The grace badge renders too (status === 'grace_period').
+    expect(screen.getAllByText(/Grace Period/i).length).toBeGreaterThan(0);
+  });
+
+  it('clamps an expired grace period to 0 days', async () => {
+    const yesterday = new Date(Date.now() - 86_400_000)
+      .toISOString()
+      .split('T')[0];
+    mockRows = [
+      {
+        ...activeRow,
+        status: 'grace_period',
+        grace_period_expires: yesterday,
+      },
+    ];
+    render(<SubscriptionManager {...defaultProps} />);
+    await waitFor(() => {
+      expect(screen.getByText(/0 days remaining/i)).toBeInTheDocument();
+    });
+  });
+
+  it('offers Resume (not Cancel) for a canceled subscription', async () => {
+    mockRows = [{ ...activeRow, status: 'canceled' }];
+    render(<SubscriptionManager {...defaultProps} />);
+    await waitFor(() => {
+      expect(
+        screen.getByRole('button', { name: /resume subscription/i })
+      ).toBeInTheDocument();
+    });
+    expect(
+      screen.queryByRole('button', { name: /cancel subscription/i })
+    ).not.toBeInTheDocument();
+  });
 });