@gigamusic/admin 0.1.0

package/src/index.ts

@@ -0,0 +1,24 @@
+// Default entry — page components + shared form components. Server-only
+// handler factories live in `./server`; the consumer imports them separately
+// to keep "use client" boundaries clean.
+
+export { AdminLayout } from "./pages/AdminLayout";
+export { AdminHomePage } from "./pages/AdminHomePage";
+export { AdminLoginPage } from "./pages/AdminLoginPage";
+export { AdminReleasesPage } from "./pages/AdminReleasesPage";
+export { AdminNewReleasePage } from "./pages/AdminNewReleasePage";
+export { AdminEditReleasePage } from "./pages/AdminEditReleasePage";
+export { AdminLinksPage } from "./pages/AdminLinksPage";
+export { AdminSettingsPage } from "./pages/AdminSettingsPage";
+export { AdminOrdersPage } from "./pages/AdminOrdersPage";
+
+export { ReleaseForm } from "./components/ReleaseForm";
+export type { ReleaseFormProps } from "./components/ReleaseForm";
+export { AdminLoginForm } from "./components/AdminLoginForm";
+export { AdminNav } from "./components/AdminNav";
+
+export type {
+  AdminDeps,
+  AdminLogger,
+  RouteHandler,
+} from "./lib/types";

package/src/lib/rate-limit.ts

@@ -0,0 +1,31 @@
+import type { Queries } from "@gigamusic/db";
+
+/**
+ * Extract a best-effort client IP for rate-limit bucketing. Honours common
+ * Vercel/Cloudflare forward headers and falls back to a constant so the
+ * handler still rate-limits the entire route when no IP is available.
+ */
+export function clientIp(req: Request): string {
+  const forwarded = req.headers.get("x-forwarded-for");
+  if (forwarded) {
+    const first = forwarded.split(",")[0]?.trim();
+    if (first) return first;
+  }
+  const real = req.headers.get("x-real-ip");
+  if (real) return real;
+  return "unknown";
+}
+
+const LOGIN_MAX_ATTEMPTS = 10;
+const LOGIN_WINDOW_MS = 15 * 60 * 1000;
+
+/** Consume one slot in the admin-login bucket for `ip`. Returns false when over the limit. */
+export function consumeAdminLoginAttempt(
+  queries: Queries,
+  ip: string,
+): Promise<{ ok: boolean; remaining: number; resetAt: Date }> {
+  return queries.consumeRateLimit(`admin-login:${ip}`, {
+    max: LOGIN_MAX_ATTEMPTS,
+    windowMs: LOGIN_WINDOW_MS,
+  });
+}

package/src/lib/responses.ts

@@ -0,0 +1,19 @@
+/**
+ * Tiny JSON response helpers. Avoids the package depending on `NextResponse`
+ * — every handler factory returns plain `Response` objects, which Next.js's
+ * App Router accepts identically.
+ */
+
+export function json(body: unknown, init?: ResponseInit): Response {
+  return new Response(JSON.stringify(body), {
+    ...init,
+    headers: { "content-type": "application/json", ...(init?.headers ?? {}) },
+  });
+}
+
+export const unauthorized = () => json({ error: "Unauthorized" }, { status: 401 });
+export const badRequest = (error: string, extra: Record<string, unknown> = {}) =>
+  json({ error, ...extra }, { status: 400 });
+export const notFound = (error = "Not found") => json({ error }, { status: 404 });
+export const serverError = (error: string, extra: Record<string, unknown> = {}) =>
+  json({ error, ...extra }, { status: 500 });

package/src/lib/session.ts

@@ -0,0 +1,89 @@
+import { cookies } from "next/headers";
+import {
+  createAdminSessionToken,
+  verifyAdminSessionToken,
+} from "@gigamusic/core";
+
+export const ADMIN_SESSION_COOKIE = "admin_session";
+const SESSION_DURATION_SECONDS = 60 * 60 * 24;
+
+/** Default cookie options consumed by every Set-Cookie path. */
+function cookieOptions(maxAge: number) {
+  return {
+    httpOnly: true,
+    secure: true,
+    sameSite: "lax" as const,
+    maxAge,
+    path: "/",
+  };
+}
+
+/**
+ * Mint a fresh admin session token and write the httpOnly cookie. Called
+ * after a successful password check from `createAdminLoginHandler`.
+ */
+export async function writeAdminSessionCookie(
+  adminSessionSecret: string,
+): Promise<void> {
+  const token = await createAdminSessionToken({ secret: adminSessionSecret });
+  const jar = await cookies();
+  jar.set(ADMIN_SESSION_COOKIE, token, cookieOptions(SESSION_DURATION_SECONDS));
+}
+
+/** Clear the admin session cookie (logout). */
+export async function clearAdminSessionCookie(): Promise<void> {
+  const jar = await cookies();
+  jar.set(ADMIN_SESSION_COOKIE, "", cookieOptions(0));
+}
+
+/**
+ * Check the current request's cookie jar for a valid admin session.
+ *
+ * Returns `true` if the cookie verifies; `false` for missing or invalid tokens.
+ * Never throws — callers can branch on the boolean.
+ */
+export async function isAdminAuthenticated(
+  adminSessionSecret: string,
+): Promise<boolean> {
+  const jar = await cookies();
+  const token = jar.get(ADMIN_SESSION_COOKIE)?.value;
+  if (!token) return false;
+  try {
+    await verifyAdminSessionToken(token, adminSessionSecret);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Stateless verification for handlers that already have a `Request`. Reads the
+ * cookie out of the request's `Cookie` header so the function works in
+ * middleware-like contexts where `next/headers` is unavailable.
+ */
+export async function verifyAdminSession(
+  req: Request,
+  adminSessionSecret: string,
+): Promise<boolean> {
+  const header = req.headers.get("cookie");
+  if (!header) return false;
+  const token = parseCookieHeader(header, ADMIN_SESSION_COOKIE);
+  if (!token) return false;
+  try {
+    await verifyAdminSessionToken(token, adminSessionSecret);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Tiny single-cookie reader. Avoids pulling in a cookie parser dependency. */
+function parseCookieHeader(header: string, name: string): string | null {
+  const parts = header.split(";");
+  for (const raw of parts) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith(`${name}=`)) continue;
+    return decodeURIComponent(trimmed.slice(name.length + 1));
+  }
+  return null;
+}

package/src/lib/types.ts

@@ -0,0 +1,45 @@
+import type { Queries } from "@gigamusic/db";
+import type { StorageProvider } from "@gigamusic/storage";
+import type * as Audio from "@gigamusic/audio";
+import type { EmailBranding } from "@gigamusic/email";
+
+/**
+ * The Next.js App Router route-handler signature. Defined locally so the admin
+ * package doesn't have to depend on Next.js's internal `NextRequest` re-export
+ * — handler factories return ordinary `Request → Promise<Response>` callables.
+ */
+export type RouteHandler = (
+  req: Request,
+  context?: { params: Promise<Record<string, string>> },
+) => Promise<Response>;
+
+/**
+ * Aggregate dependency bag for every admin route handler factory. The consumer
+ * builds this once at startup and passes a slice (or the whole bag) into each
+ * factory; nothing inside the admin package reads `process.env` directly.
+ */
+export interface AdminDeps {
+  queries: Queries;
+  storage: StorageProvider;
+  audio: typeof Audio;
+  adminPasswordHash: string;
+  adminSessionSecret: string;
+  branding: EmailBranding;
+  /**
+   * Optional logger. Defaults to a no-op so the package never writes to
+   * console on the consumer's behalf.
+   */
+  logger?: AdminLogger;
+}
+
+export interface AdminLogger {
+  info(message: string, meta?: Record<string, unknown>): void;
+  warn(message: string, meta?: Record<string, unknown>): void;
+  error(message: string, meta?: Record<string, unknown>): void;
+}
+
+export const noopLogger: AdminLogger = {
+  info() {},
+  warn() {},
+  error() {},
+};

package/src/pages/AdminEditReleasePage.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { ReleaseForm, type ReleaseFormProps } from "../components/ReleaseForm";
+
+/**
+ * Edit-release page. The consumer's route handler hands us the `id` from
+ * `params`; we fetch the full record from `/api/admin/releases/{id}` and
+ * mount `<ReleaseForm>` once it's loaded.
+ */
+export function AdminEditReleasePage({ id }: { id: string }) {
+  const [release, setRelease] = useState<ReleaseFormProps["release"] | null>(
+    null,
+  );
+  const [error, setError] = useState("");
+
+  useEffect(() => {
+    let cancelled = false;
+    fetch(`/api/admin/releases/${id}`)
+      .then((r) => (r.ok ? r.json() : Promise.reject(new Error("Load failed"))))
+      .then((data) => {
+        if (!cancelled) setRelease(data as ReleaseFormProps["release"]);
+      })
+      .catch((err) => !cancelled && setError(String(err)));
+    return () => {
+      cancelled = true;
+    };
+  }, [id]);
+
+  if (error) return <p className="text-sm text-destructive">{error}</p>;
+  if (!release) return <p className="text-sm text-muted-foreground">Loading…</p>;
+
+  return (
+    <div className="max-w-2xl">
+      <h1 className="mb-6 text-2xl font-semibold">{release.name}</h1>
+      <ReleaseForm release={release} />
+    </div>
+  );
+}

package/src/pages/AdminHomePage.tsx

@@ -0,0 +1,38 @@
+"use client";
+
+import Link from "next/link";
+
+/**
+ * Default admin landing page. Just links into the major sections. Consumers
+ * who want to drop directly to releases can simply re-export
+ * `AdminReleasesPage` from `/admin/page.tsx` instead.
+ */
+export function AdminHomePage() {
+  return (
+    <div className="space-y-6">
+      <h1 className="text-2xl font-semibold">Admin</h1>
+      <ul className="space-y-2 text-sm">
+        <li>
+          <Link href="/admin/releases" className="hover:underline">
+            Releases
+          </Link>
+        </li>
+        <li>
+          <Link href="/admin/orders" className="hover:underline">
+            Orders
+          </Link>
+        </li>
+        <li>
+          <Link href="/admin/links" className="hover:underline">
+            Links
+          </Link>
+        </li>
+        <li>
+          <Link href="/admin/settings" className="hover:underline">
+            Settings
+          </Link>
+        </li>
+      </ul>
+    </div>
+  );
+}

package/src/pages/AdminLayout.tsx

@@ -0,0 +1,20 @@
+import type { ReactNode } from "react";
+import { AdminNav } from "../components/AdminNav";
+
+/**
+ * Visual chrome for the admin section: nav bar + content container. This
+ * component does **not** auth-gate by itself — consumers protect the route
+ * via a `proxy.ts` that calls `verifyAdminSession` and redirects to
+ * `/admin/login` on failure.
+ *
+ * Keeping the layout free of auth state lets it stay synchronous and
+ * matches the locked contract (`children`-only).
+ */
+export function AdminLayout({ children }: { children: ReactNode }) {
+  return (
+    <div className="gm-admin-shell mx-auto max-w-5xl px-4 py-6">
+      <AdminNav />
+      {children}
+    </div>
+  );
+}

package/src/pages/AdminLinksPage.tsx

@@ -0,0 +1,187 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useSlot } from "@gigamusic/ui/client";
+
+interface LinkItem {
+  id: number;
+  title: string;
+  url: string;
+  position: number;
+  isVisible: boolean;
+  showOnHero: boolean;
+}
+
+/**
+ * Editor for the global `/links` page link list. Optimistic updates with a
+ * 500ms debounced PUT; reordering uses the bulk `orderedIds` endpoint so two
+ * swapped neighbors land in a single round-trip.
+ */
+export function AdminLinksPage() {
+  const Button = useSlot("Button");
+  const [links, setLinks] = useState<LinkItem[]>([]);
+  const [newTitle, setNewTitle] = useState("");
+  const [newUrl, setNewUrl] = useState("");
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    let cancelled = false;
+    fetch("/api/admin/links")
+      .then((r) => (r.ok ? r.json() : Promise.reject(new Error("Load failed"))))
+      .then((data: LinkItem[]) => {
+        if (!cancelled) {
+          setLinks(data);
+          setLoading(false);
+        }
+      })
+      .catch(() => !cancelled && setLoading(false));
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  async function addLink() {
+    if (!newTitle || !newUrl) return;
+    const res = await fetch("/api/admin/links", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ title: newTitle, url: newUrl }),
+    });
+    if (res.ok) {
+      const link = (await res.json()) as LinkItem;
+      setLinks((prev) => [...prev, link]);
+      setNewTitle("");
+      setNewUrl("");
+    }
+  }
+
+  async function saveLink(link: LinkItem) {
+    await fetch("/api/admin/links", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(link),
+    });
+  }
+
+  async function deleteLink(id: number) {
+    await fetch(`/api/admin/links?id=${id}`, { method: "DELETE" });
+    setLinks((prev) => prev.filter((l) => l.id !== id));
+  }
+
+  function updateField<K extends keyof LinkItem>(
+    id: number,
+    field: K,
+    value: LinkItem[K],
+  ) {
+    setLinks((prev) => {
+      const next = prev.map((l) => (l.id === id ? { ...l, [field]: value } : l));
+      const updated = next.find((l) => l.id === id);
+      if (updated) void saveLink(updated);
+      return next;
+    });
+  }
+
+  async function moveLink(index: number, direction: "up" | "down") {
+    const swap = direction === "up" ? index - 1 : index + 1;
+    if (swap < 0 || swap >= links.length) return;
+    const next = [...links];
+    [next[index]!, next[swap]!] = [next[swap]!, next[index]!];
+    setLinks(next);
+    await fetch("/api/admin/links", {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ orderedIds: next.map((l) => l.id) }),
+    });
+  }
+
+  if (loading) return <p className="text-sm text-muted-foreground">Loading…</p>;
+
+  return (
+    <div className="space-y-6">
+      <h1 className="text-2xl font-semibold">Links</h1>
+      <p className="text-sm text-muted-foreground">
+        Edits the global <code>/links</code> page and hero links on the homepage.
+      </p>
+
+      <div className="space-y-3">
+        {links.map((link, index) => (
+          <div
+            key={link.id}
+            className="flex items-start gap-3 rounded border border-border p-3"
+          >
+            <div className="flex flex-col gap-1">
+              <Button
+                variant="ghost"
+                size="icon-xs"
+                disabled={index === 0}
+                onClick={() => moveLink(index, "up")}
+              >
+                ▲
+              </Button>
+              <Button
+                variant="ghost"
+                size="icon-xs"
+                disabled={index === links.length - 1}
+                onClick={() => moveLink(index, "down")}
+              >
+                ▼
+              </Button>
+            </div>
+            <div className="flex flex-1 flex-wrap items-center gap-2">
+              <input
+                value={link.title}
+                onChange={(e) => updateField(link.id, "title", e.target.value)}
+                placeholder="Title"
+                className="min-w-0 flex-1 rounded border border-border bg-background px-2 py-1 text-sm"
+              />
+              <input
+                value={link.url}
+                onChange={(e) => updateField(link.id, "url", e.target.value)}
+                placeholder="URL"
+                className="min-w-0 flex-1 rounded border border-border bg-background px-2 py-1 text-sm"
+              />
+              <Button
+                variant="ghost"
+                size="sm"
+                onClick={() => updateField(link.id, "isVisible", !link.isVisible)}
+              >
+                {link.isVisible ? "Visible" : "Hidden"}
+              </Button>
+              <label className="flex items-center gap-1 text-xs text-muted-foreground">
+                <input
+                  type="checkbox"
+                  checked={link.showOnHero}
+                  onChange={() =>
+                    updateField(link.id, "showOnHero", !link.showOnHero)
+                  }
+                />
+                homepage
+              </label>
+              <Button variant="destructive" size="sm" onClick={() => deleteLink(link.id)}>
+                Delete
+              </Button>
+            </div>
+          </div>
+        ))}
+      </div>
+
+      <div className="flex flex-wrap items-center gap-2 rounded border border-dashed border-border p-3">
+        <input
+          value={newTitle}
+          onChange={(e) => setNewTitle(e.target.value)}
+          placeholder="Link title"
+          className="min-w-0 flex-1 rounded border border-border bg-background px-2 py-1 text-sm"
+        />
+        <input
+          value={newUrl}
+          onChange={(e) => setNewUrl(e.target.value)}
+          placeholder="https://..."
+          className="min-w-0 flex-1 rounded border border-border bg-background px-2 py-1 text-sm"
+        />
+        <Button onClick={addLink} disabled={!newTitle || !newUrl}>
+          Add Link
+        </Button>
+      </div>
+    </div>
+  );
+}

package/src/pages/AdminLoginPage.tsx

@@ -0,0 +1,11 @@
+import { AdminLoginForm } from "../components/AdminLoginForm";
+
+/** Standalone login page — useful when the consumer wants `/admin/login` separate from layout-driven gating. */
+export function AdminLoginPage() {
+  return (
+    <div className="gm-admin-shell mx-auto max-w-sm px-4 py-20">
+      <h1 className="mb-6 text-center text-2xl font-semibold">Admin Login</h1>
+      <AdminLoginForm />
+    </div>
+  );
+}

package/src/pages/AdminNewReleasePage.tsx

@@ -0,0 +1,12 @@
+"use client";
+
+import { ReleaseForm } from "../components/ReleaseForm";
+
+export function AdminNewReleasePage() {
+  return (
+    <div className="max-w-2xl">
+      <h1 className="mb-6 text-2xl font-semibold">New Release</h1>
+      <ReleaseForm />
+    </div>
+  );
+}

package/src/pages/AdminOrdersPage.tsx

@@ -0,0 +1,127 @@
+"use client";
+
+import { useState } from "react";
+import { useSlot } from "@gigamusic/ui/client";
+import { formatCurrency } from "@gigamusic/ui";
+
+interface OrderItem {
+  id: number;
+  release?: { name: string } | null;
+  track?: { name: string } | null;
+}
+
+interface Order {
+  id: number;
+  email: string;
+  amountTotal: number;
+  status: "pending" | "completed" | "failed";
+  createdAt: string;
+  stripePaymentId: string | null;
+  items: OrderItem[];
+}
+
+/**
+ * Email-lookup orders view. The consumer can swap this for a paginated table
+ * backed by a custom `/api/admin/orders` endpoint that supports filtering by
+ * date range; the minimum surface here is "find a customer's orders to
+ * troubleshoot a missing download."
+ */
+export function AdminOrdersPage() {
+  const Button = useSlot("Button");
+  const [email, setEmail] = useState("");
+  const [orders, setOrders] = useState<Order[] | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState("");
+
+  async function search(e: React.FormEvent) {
+    e.preventDefault();
+    if (!email) return;
+    setLoading(true);
+    setError("");
+    try {
+      const res = await fetch(
+        `/api/admin/orders?email=${encodeURIComponent(email)}`,
+      );
+      if (!res.ok) throw new Error(`Search failed (${res.status})`);
+      setOrders((await res.json()) as Order[]);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <div>
+      <h1 className="mb-6 text-2xl font-semibold">Orders</h1>
+      <form onSubmit={search} className="mb-6 flex gap-2">
+        <input
+          type="email"
+          value={email}
+          onChange={(e) => setEmail(e.target.value)}
+          placeholder="Search by email..."
+          className="flex-1 rounded border border-border bg-background px-3 py-2 text-sm"
+        />
+        <Button type="submit" disabled={loading}>
+          {loading ? "Searching..." : "Search"}
+        </Button>
+      </form>
+
+      {error && <p className="text-sm text-destructive">{error}</p>}
+
+      {orders && (
+        <table className="w-full text-sm">
+          <thead>
+            <tr className="border-b border-border text-left">
+              <th className="py-2">ID</th>
+              <th className="py-2">Date</th>
+              <th className="py-2">Items</th>
+              <th className="py-2 text-right">Amount</th>
+              <th className="py-2 text-right">Status</th>
+              <th className="py-2 text-right">Stripe</th>
+            </tr>
+          </thead>
+          <tbody>
+            {orders.map((order) => (
+              <tr key={order.id} className="border-b border-border/40">
+                <td className="py-2 font-mono text-xs">#{order.id}</td>
+                <td className="py-2">
+                  {new Date(order.createdAt).toLocaleDateString()}
+                </td>
+                <td className="py-2 max-w-[200px] truncate text-muted-foreground">
+                  {order.items
+                    .map((i) => i.release?.name ?? i.track?.name ?? "—")
+                    .join(", ")}
+                </td>
+                <td className="py-2 text-right">
+                  {formatCurrency(order.amountTotal)}
+                </td>
+                <td className="py-2 text-right">{order.status}</td>
+                <td className="py-2 text-right">
+                  {order.stripePaymentId ? (
+                    <a
+                      href={`https://dashboard.stripe.com/payments/${order.stripePaymentId}`}
+                      rel="noopener noreferrer"
+                      className="text-xs hover:underline"
+                    >
+                      View
+                    </a>
+                  ) : (
+                    <span className="text-xs text-muted-foreground">—</span>
+                  )}
+                </td>
+              </tr>
+            ))}
+            {orders.length === 0 && (
+              <tr>
+                <td colSpan={6} className="py-8 text-center text-muted-foreground">
+                  No orders found.
+                </td>
+              </tr>
+            )}
+          </tbody>
+        </table>
+      )}
+    </div>
+  );
+}