feat: implement durable API response snapshots for Meta-heavy reads

- Add `ApiSnapshot` model to store cached responses for Instagram API calls.
- Introduce snapshot management functions: `getApiSnapshot`, `setApiSnapshot`, and `buildApiSnapshotKey`.
- Update Instagram profile and posts API routes to utilize snapshots for caching.
- Enhance PostPicker component with manual refresh functionality and display last fetched timestamp.
- Create `RefreshIcon` component for UI refresh actions.
- Modify client cache hook to support bypassing server-side caches during refresh.
- Implement snapshot cleanup cron job to remove expired snapshots.
- Update Prisma schema and migrations to include new `ApiSnapshot` table and relationships.

Author: Xeven777

__tests__/snapshot-cleanup.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Snapshot Cleanup Cron — Unit Tests
+ *
+ * Covers bearer-token auth (CRON_SECRET with NEXTAUTH_SECRET fallback) and the
+ * expired-snapshot sweep (delete anything expired more than 7 days ago).
+ */
+
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const { mockPrisma } = vi.hoisted(() => ({
+  mockPrisma: {
+    apiSnapshot: {
+      deleteMany: vi.fn(),
+    },
+  },
+}));
+
+vi.mock("@/lib/db/client", () => ({
+  prisma: mockPrisma,
+}));
+
+import { GET } from "../app/api/cron/snapshot-cleanup/route";
+
+const KEEP_EXPIRED_FOR_DAYS = 7;
+const CRON_SECRET = "cron_secret_123";
+const NEXTAUTH_SECRET = "nextauth_secret_456";
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function buildRequest(authorization?: string): Parameters<typeof GET>[0] {
+  return new Request("https://app.example.com/api/cron/snapshot-cleanup", {
+    headers: authorization ? { authorization } : undefined,
+  }) as Parameters<typeof GET>[0];
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  vi.unstubAllEnvs();
+  mockPrisma.apiSnapshot.deleteMany.mockResolvedValue({ count: 0 });
+});
+
+describe("snapshot cleanup cron", () => {
+  it("rejects requests without an authorization header", async () => {
+    const response = await GET(buildRequest());
+
+    expect(response.status).toBe(401);
+    await expect(response.json()).resolves.toEqual({
+      success: false,
+      error: "Unauthorized",
+    });
+    expect(mockPrisma.apiSnapshot.deleteMany).not.toHaveBeenCalled();
+  });
+
+  it("rejects requests with the wrong bearer token", async () => {
+    vi.stubEnv("CRON_SECRET", CRON_SECRET);
+
+    const response = await GET(buildRequest("Bearer wrong_token"));
+
+    expect(response.status).toBe(401);
+    expect(mockPrisma.apiSnapshot.deleteMany).not.toHaveBeenCalled();
+  });
+
+  it("sweeps snapshots expired more than 7 days ago and reports the count", async () => {
+    vi.stubEnv("CRON_SECRET", CRON_SECRET);
+    mockPrisma.apiSnapshot.deleteMany.mockResolvedValue({ count: 5 });
+
+    const before = Date.now();
+    const response = await GET(buildRequest(`Bearer ${CRON_SECRET}`));
+
+    expect(response.status).toBe(200);
+    const body = await response.json();
+    expect(body.success).toBe(true);
+    expect(body.data.deleted).toBe(5);
+
+    // One sweep, cut off at now minus 7 days (within a small tolerance for
+    // the time that elapses while the test runs).
+    expect(mockPrisma.apiSnapshot.deleteMany).toHaveBeenCalledTimes(1);
+    const cutoff = mockPrisma.apiSnapshot.deleteMany.mock
+      .calls[0][0] as { where: { expiresAt: { lt: Date } } };
+    expect(cutoff.where.expiresAt.lt).toBeInstanceOf(Date);
+
+    const cutoffMs = cutoff.where.expiresAt.lt.getTime();
+    const expectedMs = before - KEEP_EXPIRED_FOR_DAYS * DAY_MS;
+    expect(Math.abs(cutoffMs - expectedMs)).toBeLessThan(5000);
+
+    // The reported cutoff round-trips the exact value used in the query.
+    expect(body.data.cutoff).toBe(cutoff.where.expiresAt.lt.toISOString());
+  });
+
+  it("falls back to NEXTAUTH_SECRET when CRON_SECRET is not set", async () => {
+    vi.stubEnv("CRON_SECRET", "");
+    vi.stubEnv("NEXTAUTH_SECRET", NEXTAUTH_SECRET);
+
+    const response = await GET(buildRequest(`Bearer ${NEXTAUTH_SECRET}`));
+
+    expect(response.status).toBe(200);
+    expect(mockPrisma.apiSnapshot.deleteMany).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns success with zero deletions when nothing is expired", async () => {
+    vi.stubEnv("CRON_SECRET", CRON_SECRET);
+    mockPrisma.apiSnapshot.deleteMany.mockResolvedValue({ count: 0 });
+
+    const response = await GET(buildRequest(`Bearer ${CRON_SECRET}`));
+
+    expect(response.status).toBe(200);
+    const body = await response.json();
+    expect(body).toMatchObject({ success: true, data: { deleted: 0 } });
+  });
+});

app/(dashboard)/inbox/page.tsx

@@ -287,7 +287,9 @@ export default function InboxPage() {
             ) : convError ? (
               <p className="px-4 py-6 text-sm text-error">{convError}</p>
             ) : conversations.length === 0 ? (
-              <p className="px-4 py-6 text-sm text-muted">No conversations yet.</p>
+              <p className="px-4 py-6 text-sm text-muted">
+                No conversations yet.
+              </p>
             ) : (
               conversations.map((c) => {
                 const isActive = c.id === activeId;
@@ -324,7 +326,7 @@ export default function InboxPage() {
         {/* Thread. On mobile it is only shown once a conversation is open and
             fills the pane; on sm+ it always sits beside the list. */}
         <div
-          className={`min-h-0 flex-col ${active ? "flex" : "hidden sm:flex"}`}
+          className={`min-h-0 flex-col w-[70%] ${active ? "flex" : "hidden sm:flex"}`}
         >
           {!active ? (
             <div className="flex flex-1 items-center justify-center p-6 text-sm text-muted">
@@ -346,7 +348,10 @@ export default function InboxPage() {
                 </span>
               </div>
 
-              <div ref={scrollRef} className="min-h-0 flex-1 space-y-2 overflow-y-auto p-4">
+              <div
+                ref={scrollRef}
+                className="min-h-0 flex-1 space-y-2 overflow-y-auto p-4"
+              >
                 {threadLoading && messages.length === 0 ? (
                   <p className="text-sm text-muted">Loading…</p>
                 ) : messages.length === 0 ? (
@@ -364,7 +369,9 @@ export default function InboxPage() {
                             : "bg-surface text-foreground border border-border"
                         }`}
                       >
-                        <p className="whitespace-pre-wrap break-words">{m.text}</p>
+                        <p className="whitespace-pre-wrap wrap-break-word">
+                          {m.text}
+                        </p>
                         <p
                           className={`mt-1 text-[10px] ${
                             m.fromMe ? "text-white/70" : "text-zinc-500"
@@ -389,7 +396,7 @@ export default function InboxPage() {
                     onKeyDown={handleKeyDown}
                     rows={1}
                     placeholder="Write a reply…  (Enter to send, Shift+Enter for a new line)"
-                    className="max-h-32 min-h-[40px] flex-1 resize-none rounded-lg border border-border bg-surface px-3 py-2 text-sm text-foreground placeholder:text-zinc-500 focus:border-accent/40 focus:outline-none"
+                    className="max-h-32 min-h-10 flex-1 resize-none rounded-lg border border-border bg-surface px-3 py-2 text-sm text-foreground placeholder:text-zinc-500 focus:border-accent/40 focus:outline-none"
                   />
                   <button
                     type="button"

app/(dashboard)/overview/page.tsx

@@ -8,11 +8,13 @@
  * the insights permission); likes and comments are always available.
  */
 
-import { useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import dynamic from "next/dynamic";
 import AccountSelect from "@/components/account-select";
+import RefreshIcon from "@/components/refresh-icon";
 import StatCard from "@/components/stat-card";
 import { useCachedFetch } from "@/lib/client-cache";
+import { formatTimeAgo } from "@/lib/utils/time";
 import type { OverviewResponse } from "@/app/api/instagram/overview/route";
 
 // recharts is heavy (~100KB+ gzip); keep it out of the initial bundle and
@@ -46,25 +48,56 @@ const COUNT_OPTIONS = [
 export default function OverviewPage() {
   const [selectedAccountId, setSelectedAccountId] = useState("all");
   const [count, setCount] = useState("50");
+  // Snapshot freshness reported by the API (snapshot.fetchedAt) — surfaces
+  // when the underlying Instagram data was last pulled from Meta.
+  const [lastFetchedAt, setLastFetchedAt] = useState<string | null>(null);
+  const [refreshing, setRefreshing] = useState(false);
+
+  // Identifies the active account/range selection. Shared by the ref below and
+  // the fetcher so a response can tell whether it still belongs to the current
+  // selection (single source of truth — they can't drift apart).
+  const requestKey = `overview:${selectedAccountId}:${count}`;
+
+  // Always the latest selection, so async completions can tell whether the
+  // response they belong to is still the active one.
+  const requestKeyRef = useRef("");
+  useEffect(() => {
+    requestKeyRef.current = requestKey;
+  });
 
   // The overview is backed by the Meta Graph API, so it is the slowest page.
   // Cached copies paint instantly on return visits and background refetches
-  // (max age 60s — Instagram insights don't move faster than that).
+  // (max age 60s — Instagram insights don't move faster than that). Manual
+  // refresh passes `bypass=true`, which re-fetches straight from Meta.
   const overviewFetch = useCachedFetch<OverviewResponse>(
     `dash:overview:${selectedAccountId}:${count}`,
-    async () => {
+    async (bypass = false) => {
       const params = new URLSearchParams();
       if (selectedAccountId !== "all") {
         params.set("instagramAccountId", selectedAccountId);
       }
       params.set("count", count);
+      if (bypass) params.set("refresh", "true");
 
-      const res = await fetch(`/api/instagram/overview?${params}`);
-      const payload = await res.json();
-      if (!payload.success) {
-        throw new Error(payload.error ?? "Failed to load overview");
+      if (bypass) setRefreshing(true);
+      try {
+        const res = await fetch(`/api/instagram/overview?${params}`);
+        const payload = await res.json();
+        if (!payload.success) {
+          throw new Error(payload.error ?? "Failed to load overview");
+        }
+        if (
+          payload.snapshot?.fetchedAt &&
+          requestKey === requestKeyRef.current
+        ) {
+          setLastFetchedAt(payload.snapshot.fetchedAt as string);
+        }
+        return payload.data as OverviewResponse;
+      } finally {
+        // Transient UI flag — safe to clear even for a stale request, since a
+        // stale request means the current selection is no longer refreshing.
+        if (bypass) setRefreshing(false);
       }
-      return payload.data as OverviewResponse;
     },
     { maxAgeMs: 60_000 }
   );
@@ -73,10 +106,14 @@ export default function OverviewPage() {
 
   function handleAccountChange(accountId: string) {
     setSelectedAccountId(accountId);
+    // The old selection's freshness no longer applies; hide it until the new
+    // selection's fetch reports its snapshot time.
+    setLastFetchedAt(null);
   }
 
   function handleCountChange(next: string) {
     setCount(next);
+    setLastFetchedAt(null);
   }
 
   if (overviewFetch.loading && !data) {
@@ -132,8 +169,23 @@ export default function OverviewPage() {
               {followers.toLocaleString()} followers
             </p>
           )}
+          {lastFetchedAt && (
+            <p className="mt-1 text-xs text-muted/80">
+              Last refreshed {formatTimeAgo(lastFetchedAt)}
+            </p>
+          )}
         </div>
         <div className="flex flex-wrap items-end gap-x-4 gap-y-3">
+          <button
+            type="button"
+            onClick={() => overviewFetch.refresh(true)}
+            disabled={refreshing}
+            title="Refresh from Instagram"
+            aria-label="Refresh from Instagram"
+            className="flex h-9 w-9 items-center justify-center rounded-lg border border-border bg-surface text-muted transition hover:border-border-hover hover:text-foreground disabled:opacity-50"
+          >
+            <RefreshIcon className={refreshing ? "animate-spin" : ""} />
+          </button>
           <label className="flex flex-col gap-2 text-sm">
             <span className="text-xs font-semibold uppercase tracking-wide text-zinc-500">
               Range

app/api/cron/snapshot-cleanup/route.ts

@@ -0,0 +1,39 @@
+import { NextRequest, NextResponse } from "next/server";
+import { prisma } from "@/lib/db/client";
+
+/**
+ * Sweeps expired API snapshots.
+ *
+ * Snapshots are overwritten in place by stable keys, so growth is already
+ * bounded — but a deleted account, a changed key scheme, or a failed upsert
+ * can still orphan rows. Anything that expired more than this long ago is
+ * unrecoverable garbage and can be removed.
+ */
+const KEEP_EXPIRED_FOR_DAYS = 7;
+
+export async function GET(request: NextRequest) {
+  const authHeader = request.headers.get("authorization");
+  const cronSecret = process.env.CRON_SECRET || process.env.NEXTAUTH_SECRET;
+
+  if (authHeader !== `Bearer ${cronSecret}`) {
+    return NextResponse.json(
+      { success: false, error: "Unauthorized" },
+      { status: 401 }
+    );
+  }
+
+  const cutoff = new Date();
+  cutoff.setDate(cutoff.getDate() - KEEP_EXPIRED_FOR_DAYS);
+
+  const { count } = await prisma.apiSnapshot.deleteMany({
+    where: { expiresAt: { lt: cutoff } },
+  });
+
+  return NextResponse.json({
+    success: true,
+    data: {
+      deleted: count,
+      cutoff: cutoff.toISOString(),
+    },
+  });
+}