@gigamusic/links 2.1.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gigamusic/links",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "Editable Linktree-style link pages for gigamusic artist sites. Ships a Drizzle schema, admin API handler factories, and platform-detection helpers.",
   "license": "MIT",
   "repository": {
@@ -31,8 +31,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@gigamusic/core": "1.0.0",
-    "@gigamusic/db": "2.1.0"
+    "zod": "^3.24.1",
+    "@gigamusic/db": "3.0.0",
+    "@gigamusic/core": "3.0.0"
   },
   "peerDependencies": {
     "drizzle-orm": ">=0.45",

package/src/api/handlers.ts

@@ -1,5 +1,13 @@
 import { revalidateTag } from "next/cache";
-import type { LinkPageQueries } from "../types";
+import { z } from "zod";
+import { LinkPageInputSchema, LinkPageItemInputSchema } from "@gigamusic/core";
+import type {
+  DefaultLinkPageTables,
+  LinkPageInput,
+  LinkPageItemInput,
+  LinkPageQueries,
+  LinkPageQueryTables,
+} from "../types";
 import {
   INVALID_SLUG_MESSAGE,
   RESERVED_SLUGS,
@@ -24,11 +32,28 @@ export type RouteHandler<Params = Record<string, string>> = (
 /**
  * Deps for the admin-side link-page handler factories.
  *
+ * Generic over the consumer's `LinkPageQueryTables` so the `Queries` and the
+ * `afterWrite` callbacks see consumer-extended `linkPages` / `linkPageItems`
+ * row shapes when the consumer built tables via `buildLinkPages(...)` /
+ * `buildLinkPageItems(...)`.
+ *
  * Auth: the package assumes the request has been gated by the consumer's
  * `proxy.ts` / middleware. These handlers don't verify a session.
  */
-export interface LinkPagesAdminDeps {
-  queries: LinkPageQueries;
+export interface LinkPagesAdminDeps<
+  T extends LinkPageQueryTables = DefaultLinkPageTables,
+  TPageInput extends z.ZodObject<any> = typeof LinkPageInputSchema,
+  TItemInput extends z.ZodObject<any> = typeof LinkPageItemInputSchema,
+> {
+  queries: LinkPageQueries<T>;
+  /** Defaults to `LinkPageInputSchema`. Pass an `.extend()`ed schema for extras. */
+  pageInputSchema?: TPageInput;
+  /** Defaults to `LinkPageItemInputSchema`. Pass an `.extend()`ed schema for extras. */
+  itemInputSchema?: TItemInput;
+  /** Invoked after `queries.createLinkPage` / `updateLinkPage` resolves. Not tx-atomic. */
+  afterPageWrite?: (pageId: number, input: z.infer<TPageInput>) => Promise<void>;
+  /** Invoked after `queries.addLinkPageItem` / `updateLinkPageItem` resolves. Not tx-atomic. */
+  afterItemWrite?: (itemId: number, input: z.infer<TItemInput>) => Promise<void>;
 }
 
 function json(body: unknown, init?: ResponseInit): Response {
@@ -41,15 +66,6 @@ function json(body: unknown, init?: ResponseInit): Response {
   });
 }
 
-interface LinkPageBody {
-  title?: string;
-  slug?: string;
-  description?: string | null;
-  releaseId?: number | null;
-  coverImageUrl?: string | null;
-  isPublished?: boolean;
-}
-
 function validateSlug(slug: string): { ok: true } | { ok: false; res: Response } {
   if (!SLUG_PATTERN.test(slug)) {
     return { ok: false, res: json({ error: INVALID_SLUG_MESSAGE }, { status: 400 }) };
@@ -63,21 +79,30 @@ function validateSlug(slug: string): { ok: true } | { ok: false; res: Response }
 /**
  * `app/api/admin/link-pages/route.ts` handlers — list + create.
  */
-export function createAdminLinkPagesHandlers(deps: LinkPagesAdminDeps): {
+export function createAdminLinkPagesHandlers<
+  T extends LinkPageQueryTables = DefaultLinkPageTables,
+  TPageInput extends z.ZodObject<any> = typeof LinkPageInputSchema,
+  TItemInput extends z.ZodObject<any> = typeof LinkPageItemInputSchema,
+>(deps: LinkPagesAdminDeps<T, TPageInput, TItemInput>): {
   GET: RouteHandler<Record<string, never>>;
   POST: RouteHandler<Record<string, never>>;
 } {
+  const pageInputSchema = (deps.pageInputSchema ??
+    LinkPageInputSchema) as TPageInput;
   return {
-    GET: async (_req) => {
-const pages = await deps.queries.listAllLinkPages();
+    GET: async () => {
+      const pages = await deps.queries.listAllLinkPages();
       return json(pages);
     },
 
     POST: async (req) => {
-const body = (await req.json()) as LinkPageBody;
-      const title = body.title?.trim();
-      const slug = body.slug?.trim().toLowerCase();
+      const body = await safeJson(req);
+      const parsed = pageInputSchema.safeParse(body);
+      if (!parsed.success) return json({ error: "Validation failed" }, { status: 400 });
 
+      const data = parsed.data as LinkPageInput;
+      const title = data.title?.trim();
+      const slug = data.slug?.trim().toLowerCase();
       if (!title) return json({ error: "Title is required" }, { status: 400 });
       if (!slug) return json({ error: INVALID_SLUG_MESSAGE }, { status: 400 });
       const slugCheck = validateSlug(slug);
@@ -87,11 +112,17 @@ const body = (await req.json()) as LinkPageBody;
         const page = await deps.queries.createLinkPage({
           title,
           slug,
-          description: body.description ?? null,
-          releaseId: body.releaseId ?? null,
-          coverImageUrl: body.coverImageUrl ?? null,
-          isPublished: body.isPublished ?? true,
+          description: data.description ?? null,
+          releaseId: data.releaseId ?? null,
+          coverImageUrl: data.coverImageUrl ?? null,
+          isPublished: data.isPublished ?? true,
         });
+        if (deps.afterPageWrite) {
+          await deps.afterPageWrite(
+            (page as { id: number }).id,
+            parsed.data as z.infer<TPageInput>,
+          );
+        }
         revalidateTag(LINK_PAGES_TAG, "max");
         return json(page, { status: 201 });
       } catch (err) {
@@ -107,14 +138,22 @@ const body = (await req.json()) as LinkPageBody;
 /**
  * `app/api/admin/link-pages/[id]/route.ts` handlers — single-page CRUD.
  */
-export function createAdminLinkPageByIdHandlers(deps: LinkPagesAdminDeps): {
+export function createAdminLinkPageByIdHandlers<
+  T extends LinkPageQueryTables = DefaultLinkPageTables,
+  TPageInput extends z.ZodObject<any> = typeof LinkPageInputSchema,
+  TItemInput extends z.ZodObject<any> = typeof LinkPageItemInputSchema,
+>(deps: LinkPagesAdminDeps<T, TPageInput, TItemInput>): {
   GET: RouteHandler<{ id: string }>;
   PUT: RouteHandler<{ id: string }>;
   DELETE: RouteHandler<{ id: string }>;
 } {
+  const pageInputSchema = (deps.pageInputSchema ??
+    LinkPageInputSchema) as TPageInput;
+  // Updates accept partials — make every field optional.
+  const partialPageSchema = pageInputSchema.partial();
   return {
-    GET: async (req, { params }) => {
-const { id: idParam } = await params;
+    GET: async (_req, { params }) => {
+      const { id: idParam } = await params;
       const id = Number(idParam);
       if (!Number.isFinite(id)) return json({ error: "Not found" }, { status: 404 });
       const page = await deps.queries.getLinkPageById(id);
@@ -123,31 +162,36 @@ const { id: idParam } = await params;
     },
 
     PUT: async (req, { params }) => {
-const { id: idParam } = await params;
+      const { id: idParam } = await params;
       const id = Number(idParam);
       if (!Number.isFinite(id)) return json({ error: "Not found" }, { status: 404 });
-      const body = (await req.json()) as LinkPageBody;
+      const body = await safeJson(req);
+      const parsed = partialPageSchema.safeParse(body);
+      if (!parsed.success) return json({ error: "Validation failed" }, { status: 400 });
+      const data = parsed.data as Partial<LinkPageInput>;
 
-      const update: LinkPageBody = {};
-      if (body.title !== undefined) {
-        const title = body.title.trim();
+      const update: Partial<LinkPageInput> = {};
+      if (data.title !== undefined) {
+        const title = data.title.trim();
         if (!title) return json({ error: "Title is required" }, { status: 400 });
         update.title = title;
       }
-      if (body.slug !== undefined) {
-        const slug = body.slug.trim().toLowerCase();
+      if (data.slug !== undefined) {
+        const slug = data.slug.trim().toLowerCase();
         const slugCheck = validateSlug(slug);
         if (!slugCheck.ok) return slugCheck.res;
         update.slug = slug;
       }
-      if (body.description !== undefined) update.description = body.description;
-      if (body.releaseId !== undefined) update.releaseId = body.releaseId;
-      if (body.coverImageUrl !== undefined)
-        update.coverImageUrl = body.coverImageUrl;
-      if (body.isPublished !== undefined) update.isPublished = body.isPublished;
+      if (data.description !== undefined) update.description = data.description;
+      if (data.releaseId !== undefined) update.releaseId = data.releaseId;
+      if (data.coverImageUrl !== undefined) update.coverImageUrl = data.coverImageUrl;
+      if (data.isPublished !== undefined) update.isPublished = data.isPublished;
 
       try {
         const page = await deps.queries.updateLinkPage(id, update);
+        if (deps.afterPageWrite) {
+          await deps.afterPageWrite(id, parsed.data as z.infer<TPageInput>);
+        }
         revalidateTag(LINK_PAGES_TAG, "max");
         return json(page);
       } catch (err) {
@@ -158,8 +202,8 @@ const { id: idParam } = await params;
       }
     },
 
-    DELETE: async (req, { params }) => {
-const { id: idParam } = await params;
+    DELETE: async (_req, { params }) => {
+      const { id: idParam } = await params;
       const id = Number(idParam);
       if (!Number.isFinite(id)) return json({ error: "Not found" }, { status: 404 });
       await deps.queries.deleteLinkPage(id);
@@ -184,34 +228,52 @@ interface LinkPageItemBody {
  * PUT updates a single item by `itemId` in the JSON body.
  * DELETE removes an item by `itemId` in the query string.
  */
-export function createAdminLinkPageItemsHandlers(
-  deps: LinkPagesAdminDeps,
-): {
+export function createAdminLinkPageItemsHandlers<
+  T extends LinkPageQueryTables = DefaultLinkPageTables,
+  TPageInput extends z.ZodObject<any> = typeof LinkPageInputSchema,
+  TItemInput extends z.ZodObject<any> = typeof LinkPageItemInputSchema,
+>(deps: LinkPagesAdminDeps<T, TPageInput, TItemInput>): {
   POST: RouteHandler<{ id: string }>;
   PUT: RouteHandler<{ id: string }>;
   DELETE: RouteHandler<{ id: string }>;
 } {
+  const itemInputSchema = (deps.itemInputSchema ??
+    LinkPageItemInputSchema) as TItemInput;
+  const partialItemSchema = itemInputSchema.partial();
   return {
     POST: async (req, { params }) => {
-const { id: pageIdParam } = await params;
+      const { id: pageIdParam } = await params;
       const pageId = Number(pageIdParam);
       if (!Number.isFinite(pageId)) {
         return json({ error: "Not found" }, { status: 404 });
       }
-      const { title, url } = (await req.json()) as { title?: string; url?: string };
-      if (!title?.trim() || !url?.trim()) {
+      const body = await safeJson(req);
+      const parsed = itemInputSchema.safeParse(body);
+      if (!parsed.success) {
+        return json({ error: "Title and URL are required" }, { status: 400 });
+      }
+      const data = parsed.data as LinkPageItemInput;
+      if (!data.title?.trim() || !data.url?.trim()) {
         return json({ error: "Title and URL are required" }, { status: 400 });
       }
       const item = await deps.queries.addLinkPageItem(pageId, {
-        title: title.trim(),
-        url: url.trim(),
+        title: data.title.trim(),
+        url: data.url.trim(),
+        position: data.position,
+        isVisible: data.isVisible,
       });
+      if (deps.afterItemWrite) {
+        await deps.afterItemWrite(
+          (item as { id: number }).id,
+          parsed.data as z.infer<TItemInput>,
+        );
+      }
       revalidateTag(LINK_PAGES_TAG, "max");
       return json(item, { status: 201 });
     },
 
     PUT: async (req) => {
-const body = (await req.json()) as LinkPageItemBody;
+      const body = (await safeJson(req)) as LinkPageItemBody;
       if (body.itemId == null) {
         return json({ error: "itemId is required" }, { status: 400 });
       }
@@ -219,18 +281,20 @@ const body = (await req.json()) as LinkPageItemBody;
       if (!Number.isFinite(itemId)) {
         return json({ error: "itemId is required" }, { status: 400 });
       }
-      const item = await deps.queries.updateLinkPageItem(itemId, {
-        title: body.title,
-        url: body.url,
-        position: body.position,
-        isVisible: body.isVisible,
-      });
+      // Validate the remaining body against the partial-item schema.
+      const { itemId: _itemId, ...rest } = body;
+      const parsed = partialItemSchema.safeParse(rest);
+      if (!parsed.success) return json({ error: "Validation failed" }, { status: 400 });
+      const item = await deps.queries.updateLinkPageItem(itemId, parsed.data);
+      if (deps.afterItemWrite) {
+        await deps.afterItemWrite(itemId, parsed.data as z.infer<TItemInput>);
+      }
       revalidateTag(LINK_PAGES_TAG, "max");
       return json(item);
     },
 
     DELETE: async (req) => {
-const { searchParams } = new URL(req.url);
+      const { searchParams } = new URL(req.url);
       const itemIdRaw = searchParams.get("itemId");
       if (!itemIdRaw) {
         return json({ error: "itemId is required" }, { status: 400 });
@@ -245,3 +309,11 @@ const { searchParams } = new URL(req.url);
     },
   };
 }
+
+async function safeJson(req: Request): Promise<unknown> {
+  try {
+    return await req.json();
+  } catch {
+    return {};
+  }
+}

package/src/index.ts

@@ -3,11 +3,13 @@
 
 // ── Types ────────────────────────────────────────────────────────────────
 export type {
+  DefaultLinkPageTables,
   LinkPage,
   LinkPageItem,
   LinkPageReleaseRef,
   LinkPageWithItems,
   LinkPageQueries,
+  LinkPageQueryTables,
   LinkPageInput,
   LinkPageItemInput,
 } from "./types";

package/src/queries/link-pages.ts

@@ -1,14 +1,19 @@
 import { and, asc, desc, eq, max } from "drizzle-orm";
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
 import type * as gigamusicDbSchema from "@gigamusic/db/schema";
-import type * as linksSchema from "../schema/index.js";
-import { linkPageItems, linkPages } from "../schema/index.js";
+import type * as linksSchema from "../schema/index";
+import {
+  linkPageItems as baseLinkPageItems,
+  linkPages as baseLinkPages,
+} from "../schema/index";
 import type {
+  DefaultLinkPageTables,
   LinkPage,
   LinkPageInput,
   LinkPageItem,
   LinkPageItemInput,
   LinkPageQueries,
+  LinkPageQueryTables,
   LinkPageWithItems,
 } from "../types";
 
@@ -21,28 +26,49 @@ export type LinkPagesDb = NodePgDatabase<RequiredSchema>;
  * Factory that binds a Drizzle database into the `LinkPageQueries` contract.
  * Consumers typically merge the result with `@gigamusic/db`'s `createQueries`.
  *
+ * Pass a `tables` arg to thread consumer-extended `linkPages` / `linkPageItems`
+ * (built via the `buildLinkPages` / `buildLinkPageItems` factories) through
+ * every query — the returned `LinkPageQueries<T>` rows carry the consumer's
+ * extra columns. Single-arg callers fall back to the un-extended convenience
+ * tables.
+ *
  * The `db` instance must have been built with a schema that includes the
  * union of `@gigamusic/db/schema` and `@gigamusic/links/schema`; otherwise
  * the relational `with: { release: ... }` clause won't resolve at runtime.
  */
-export function createLinkPageQueries(db: LinkPagesDb): LinkPageQueries {
+export function createLinkPageQueries(db: LinkPagesDb): LinkPageQueries;
+export function createLinkPageQueries<T extends LinkPageQueryTables>(
+  db: LinkPagesDb,
+  tables: T,
+): LinkPageQueries<T>;
+export function createLinkPageQueries<T extends LinkPageQueryTables>(
+  db: LinkPagesDb,
+  tables?: T,
+): LinkPageQueries<T> {
+  // Identity is preserved at runtime; the casts only widen for the type
+  // checker so consumer-extended tables don't have to match the base shape
+  // exactly.
+  const linkPages = (tables?.linkPages ?? baseLinkPages) as unknown as typeof baseLinkPages;
+  const linkPageItems = (tables?.linkPageItems ??
+    baseLinkPageItems) as unknown as typeof baseLinkPageItems;
+
   return {
-    listPublishedLinkPages: async (): Promise<LinkPage[]> => {
+    listPublishedLinkPages: async (): Promise<LinkPage<T>[]> => {
       const rows = await db.query.linkPages.findMany({
         where: eq(linkPages.isPublished, true),
         orderBy: desc(linkPages.updatedAt),
       });
-      return rows;
+      return rows as unknown as LinkPage<T>[];
     },
 
-    listAllLinkPages: async (): Promise<LinkPage[]> => {
+    listAllLinkPages: async (): Promise<LinkPage<T>[]> => {
       const rows = await db.query.linkPages.findMany({
         orderBy: desc(linkPages.updatedAt),
       });
-      return rows;
+      return rows as unknown as LinkPage<T>[];
     },
 
-    getPublicLinkPageBySlug: async (slug: string): Promise<LinkPageWithItems | null> => {
+    getPublicLinkPageBySlug: async (slug: string): Promise<LinkPageWithItems<T> | null> => {
       const row = await db.query.linkPages.findFirst({
         where: and(eq(linkPages.slug, slug), eq(linkPages.isPublished, true)),
         with: {
@@ -61,10 +87,10 @@ export function createLinkPageQueries(db: LinkPagesDb): LinkPageQueries {
           },
         },
       });
-      return (row ?? null) as unknown as LinkPageWithItems | null;
+      return (row ?? null) as unknown as LinkPageWithItems<T> | null;
     },
 
-    getLinkPageById: async (id: number): Promise<LinkPageWithItems | null> => {
+    getLinkPageById: async (id: number): Promise<LinkPageWithItems<T> | null> => {
       const row = await db.query.linkPages.findFirst({
         where: eq(linkPages.id, id),
         with: {
@@ -80,10 +106,10 @@ export function createLinkPageQueries(db: LinkPagesDb): LinkPageQueries {
           items: { orderBy: asc(linkPageItems.position) },
         },
       });
-      return (row ?? null) as unknown as LinkPageWithItems | null;
+      return (row ?? null) as unknown as LinkPageWithItems<T> | null;
     },
 
-    createLinkPage: async (input: LinkPageInput): Promise<LinkPage> => {
+    createLinkPage: async (input: LinkPageInput): Promise<LinkPage<T>> => {
       const [row] = await db
         .insert(linkPages)
         .values({
@@ -95,10 +121,10 @@ export function createLinkPageQueries(db: LinkPagesDb): LinkPageQueries {
           isPublished: input.isPublished ?? true,
         })
         .returning();
-      return row!;
+      return row! as unknown as LinkPage<T>;
     },
 
-    updateLinkPage: async (id: number, input: Partial<LinkPageInput>): Promise<LinkPage> => {
+    updateLinkPage: async (id: number, input: Partial<LinkPageInput>): Promise<LinkPage<T>> => {
       const data: Record<string, unknown> = {};
       if (input.title !== undefined) data.title = input.title;
       if (input.slug !== undefined) data.slug = input.slug;
@@ -107,14 +133,17 @@ export function createLinkPageQueries(db: LinkPagesDb): LinkPageQueries {
       if (input.coverImageUrl !== undefined) data.coverImageUrl = input.coverImageUrl;
       if (input.isPublished !== undefined) data.isPublished = input.isPublished;
       const [row] = await db.update(linkPages).set(data).where(eq(linkPages.id, id)).returning();
-      return row!;
+      return row! as unknown as LinkPage<T>;
     },
 
     deleteLinkPage: async (id: number): Promise<void> => {
       await db.delete(linkPages).where(eq(linkPages.id, id));
     },
 
-    addLinkPageItem: async (pageId: number, input: LinkPageItemInput): Promise<LinkPageItem> => {
+    addLinkPageItem: async (
+      pageId: number,
+      input: LinkPageItemInput,
+    ): Promise<LinkPageItem<T>> => {
       const [maxRow] = await db
         .select({ max: max(linkPageItems.position) })
         .from(linkPageItems)
@@ -130,20 +159,24 @@ export function createLinkPageQueries(db: LinkPagesDb): LinkPageQueries {
           isVisible: input.isVisible ?? true,
         })
         .returning();
-      return row!;
+      return row! as unknown as LinkPageItem<T>;
     },
 
     updateLinkPageItem: async (
       id: number,
       input: Partial<LinkPageItemInput>,
-    ): Promise<LinkPageItem> => {
+    ): Promise<LinkPageItem<T>> => {
       const data: Record<string, unknown> = {};
       if (input.title !== undefined) data.title = input.title;
       if (input.url !== undefined) data.url = input.url;
       if (input.position !== undefined) data.position = input.position;
       if (input.isVisible !== undefined) data.isVisible = input.isVisible;
-      const [row] = await db.update(linkPageItems).set(data).where(eq(linkPageItems.id, id)).returning();
-      return row!;
+      const [row] = await db
+        .update(linkPageItems)
+        .set(data)
+        .where(eq(linkPageItems.id, id))
+        .returning();
+      return row! as unknown as LinkPageItem<T>;
     },
 
     deleteLinkPageItem: async (id: number): Promise<void> => {
@@ -162,9 +195,17 @@ export function createLinkPageQueries(db: LinkPagesDb): LinkPageQueries {
           await tx
             .update(linkPageItems)
             .set({ position })
-            .where(and(eq(linkPageItems.id, orderedItemIds[position]!), eq(linkPageItems.pageId, pageId)));
+            .where(
+              and(
+                eq(linkPageItems.id, orderedItemIds[position]!),
+                eq(linkPageItems.pageId, pageId),
+              ),
+            );
         }
       });
     },
   };
 }
+
+// Re-export DefaultLinkPageTables so the consumer can import it if they want.
+export type { DefaultLinkPageTables };

package/src/schema/index.ts

@@ -1,2 +1,2 @@
-export * from "./link-pages.js";
-export * from "./relations.js";
+export * from "./link-pages";
+export * from "./relations";

package/src/schema/link-pages.ts

@@ -1,41 +1,56 @@
 import { boolean, index, integer, pgTable, serial, text, timestamp } from "drizzle-orm/pg-core";
 import { releases } from "@gigamusic/db/schema";
+import type { ExtraColumns } from "@gigamusic/db/schema";
 
-export const linkPageColumns = {
-  id: serial("id").primaryKey(),
-  slug: text("slug").notNull().unique("link_pages_slug_key"),
-  title: text("title").notNull(),
-  description: text("description"),
-  coverImageUrl: text("coverImageUrl"),
-  releaseId: integer("releaseId").references(() => releases.id, { onDelete: "set null" }),
-  isPublished: boolean("isPublished").notNull().default(true),
-  createdAt: timestamp("createdAt", { mode: "date", precision: 3 }).notNull().defaultNow(),
-  updatedAt: timestamp("updatedAt", { mode: "date", precision: 3 })
-    .notNull()
-    .$defaultFn(() => new Date())
-    .$onUpdateFn(() => new Date()),
-} as const;
+// See @gigamusic/db/schema/releases.ts for the rationale on inlining
+// columns inside the factory (TTableName generic resolution).
+export function buildLinkPages<TExtras extends ExtraColumns = {}>(
+  extras: TExtras = {} as TExtras,
+) {
+  return pgTable(
+    "link_pages",
+    {
+      id:            serial("id").primaryKey(),
+      slug:          text("slug").notNull().unique("link_pages_slug_key"),
+      title:         text("title").notNull(),
+      description:   text("description"),
+      coverImageUrl: text("coverImageUrl"),
+      releaseId:     integer("releaseId").references(() => releases.id, { onDelete: "set null" }),
+      isPublished:   boolean("isPublished").notNull().default(true),
+      createdAt:     timestamp("createdAt", { mode: "date", precision: 3 }).notNull().defaultNow(),
+      updatedAt:     timestamp("updatedAt", { mode: "date", precision: 3 })
+        .notNull()
+        .$defaultFn(() => new Date())
+        .$onUpdateFn(() => new Date()),
+      ...extras,
+    },
+    (t) => [index("link_pages_releaseId_idx").on(t.releaseId)],
+  );
+}
 
-export const linkPages = pgTable("link_pages", linkPageColumns, (t) => [
-  index("link_pages_releaseId_idx").on(t.releaseId),
-]);
+export const linkPages = buildLinkPages();
 
-export const linkPageItemColumns = {
-  id: serial("id").primaryKey(),
-  pageId: integer("pageId")
-    .notNull()
-    .references(() => linkPages.id, { onDelete: "cascade" }),
-  title: text("title").notNull(),
-  url: text("url").notNull(),
-  position: integer("position").notNull().default(0),
-  isVisible: boolean("isVisible").notNull().default(true),
-  createdAt: timestamp("createdAt", { mode: "date", precision: 3 }).notNull().defaultNow(),
-  updatedAt: timestamp("updatedAt", { mode: "date", precision: 3 })
-    .notNull()
-    .$defaultFn(() => new Date())
-    .$onUpdateFn(() => new Date()),
-} as const;
+export function buildLinkPageItems<TExtras extends ExtraColumns = {}>(
+  extras: TExtras = {} as TExtras,
+) {
+  return pgTable(
+    "link_page_items",
+    {
+      id:     serial("id").primaryKey(),
+      pageId: integer("pageId").notNull().references(() => linkPages.id, { onDelete: "cascade" }),
+      title:     text("title").notNull(),
+      url:       text("url").notNull(),
+      position:  integer("position").notNull().default(0),
+      isVisible: boolean("isVisible").notNull().default(true),
+      createdAt: timestamp("createdAt", { mode: "date", precision: 3 }).notNull().defaultNow(),
+      updatedAt: timestamp("updatedAt", { mode: "date", precision: 3 })
+        .notNull()
+        .$defaultFn(() => new Date())
+        .$onUpdateFn(() => new Date()),
+      ...extras,
+    },
+    (t) => [index("link_page_items_pageId_idx").on(t.pageId)],
+  );
+}
 
-export const linkPageItems = pgTable("link_page_items", linkPageItemColumns, (t) => [
-  index("link_page_items_pageId_idx").on(t.pageId),
-]);
+export const linkPageItems = buildLinkPageItems();

package/src/schema/relations.ts

@@ -1,12 +1,54 @@
 import { relations } from "drizzle-orm";
-import { releases } from "@gigamusic/db/schema";
-import { linkPages, linkPageItems } from "./link-pages.js";
+import type { PgTable } from "drizzle-orm/pg-core";
+import { releases as baseReleases } from "@gigamusic/db/schema";
+import {
+  linkPages as baseLinkPages,
+  linkPageItems as baseLinkPageItems,
+} from "./link-pages";
 
-export const linkPagesRelations = relations(linkPages, ({ one, many }) => ({
-  release: one(releases, { fields: [linkPages.releaseId], references: [releases.id] }),
-  items: many(linkPageItems),
-}));
+// `PgTable<any>` so consumer concrete tables satisfy these factory params —
+// see @gigamusic/db's types.ts for the variance rationale.
+type AnyPgTableValue = PgTable<any>;
 
-export const linkPageItemsRelations = relations(linkPageItems, ({ one }) => ({
-  page: one(linkPages, { fields: [linkPageItems.pageId], references: [linkPages.id] }),
-}));
+export function createLinkPagesRelations(t: {
+  linkPages: AnyPgTableValue;
+  linkPageItems: AnyPgTableValue;
+  releases: AnyPgTableValue;
+}) {
+  const linkPages = t.linkPages as unknown as typeof baseLinkPages;
+  const linkPageItems = t.linkPageItems as unknown as typeof baseLinkPageItems;
+  const releases = t.releases as unknown as typeof baseReleases;
+  return relations(linkPages, ({ one, many }) => ({
+    release: one(releases, {
+      fields: [linkPages.releaseId],
+      references: [releases.id],
+    }),
+    items: many(linkPageItems),
+  }));
+}
+
+export function createLinkPageItemsRelations(t: {
+  linkPages: AnyPgTableValue;
+  linkPageItems: AnyPgTableValue;
+}) {
+  const linkPages = t.linkPages as unknown as typeof baseLinkPages;
+  const linkPageItems = t.linkPageItems as unknown as typeof baseLinkPageItems;
+  return relations(linkPageItems, ({ one }) => ({
+    page: one(linkPages, {
+      fields: [linkPageItems.pageId],
+      references: [linkPages.id],
+    }),
+  }));
+}
+
+// Convenience top-level exports bound to the un-extended convenience tables.
+export const linkPagesRelations = createLinkPagesRelations({
+  linkPages: baseLinkPages,
+  linkPageItems: baseLinkPageItems,
+  releases: baseReleases,
+});
+
+export const linkPageItemsRelations = createLinkPageItemsRelations({
+  linkPages: baseLinkPages,
+  linkPageItems: baseLinkPageItems,
+});

package/src/types.ts

@@ -1,10 +1,37 @@
+import type { PgTable } from "drizzle-orm/pg-core";
 import type { LinkPageInput, LinkPageItemInput } from "@gigamusic/core";
-import type { linkPageItems, linkPages } from "./schema/index.js";
+import type * as linksSchema from "./schema/index";
 
 export type { LinkPageInput, LinkPageItemInput };
 
+// `PgTable<any>` (not `PgTable<TableConfig>`) so consumer concrete tables
+// satisfy this constraint — Drizzle's column generics are invariant on
+// column shape; see @gigamusic/db's types.ts for the full rationale.
+type AnyPgTableValue = PgTable<any>;
+
+/**
+ * The bag of Drizzle table identities the link-page queries factory closes
+ * over. Consumers can pass extended versions of these tables built via the
+ * `buildLinkPages` / `buildLinkPageItems` factories; the `releases` reference
+ * is the consumer's `releases` table (for the cover-image fallback join).
+ */
+export interface LinkPageQueryTables {
+  linkPages: AnyPgTableValue;
+  linkPageItems: AnyPgTableValue;
+  releases: AnyPgTableValue;
+}
+
+export interface DefaultLinkPageTables extends LinkPageQueryTables {
+  linkPages: typeof linksSchema.linkPages;
+  linkPageItems: typeof linksSchema.linkPageItems;
+  // `releases` defaults to the gigamusic convenience table; consumers pass
+  // their own extended releases when they have one.
+  releases: AnyPgTableValue;
+}
+
 /** A single link button rendered inside a `LinkPage`. */
-export type LinkPageItem = typeof linkPageItems.$inferSelect;
+export type LinkPageItem<T extends LinkPageQueryTables = DefaultLinkPageTables> =
+  T["linkPageItems"]["$inferSelect"];
 
 /** Optional `Release` reference exposed to the public view for cover fallback. */
 export interface LinkPageReleaseRef {
@@ -16,32 +43,34 @@ export interface LinkPageReleaseRef {
 }
 
 /** Top-level "Linktree-style" page row. */
-export type LinkPage = typeof linkPages.$inferSelect;
+export type LinkPage<T extends LinkPageQueryTables = DefaultLinkPageTables> =
+  T["linkPages"]["$inferSelect"];
 
 /** A `LinkPage` joined with its visible (or all) items and an optional release ref. */
-export interface LinkPageWithItems extends LinkPage {
-  items: LinkPageItem[];
-  release?: LinkPageReleaseRef | null;
-}
+export type LinkPageWithItems<T extends LinkPageQueryTables = DefaultLinkPageTables> =
+  LinkPage<T> & {
+    items: LinkPageItem<T>[];
+    release?: LinkPageReleaseRef | null;
+  };
 
 /**
  * Query helpers that close over a Drizzle DB. Consumers merge this with
  * `@gigamusic/db`'s `Queries` factory result (or pass it through wherever a
  * `LinkPageQueries` is needed).
  */
-export interface LinkPageQueries {
-  listPublishedLinkPages(): Promise<LinkPage[]>;
-  listAllLinkPages(): Promise<LinkPage[]>;
-  getPublicLinkPageBySlug(slug: string): Promise<LinkPageWithItems | null>;
-  getLinkPageById(id: number): Promise<LinkPageWithItems | null>;
-  createLinkPage(input: LinkPageInput): Promise<LinkPage>;
-  updateLinkPage(id: number, input: Partial<LinkPageInput>): Promise<LinkPage>;
+export interface LinkPageQueries<T extends LinkPageQueryTables = DefaultLinkPageTables> {
+  listPublishedLinkPages(): Promise<LinkPage<T>[]>;
+  listAllLinkPages(): Promise<LinkPage<T>[]>;
+  getPublicLinkPageBySlug(slug: string): Promise<LinkPageWithItems<T> | null>;
+  getLinkPageById(id: number): Promise<LinkPageWithItems<T> | null>;
+  createLinkPage(input: LinkPageInput): Promise<LinkPage<T>>;
+  updateLinkPage(id: number, input: Partial<LinkPageInput>): Promise<LinkPage<T>>;
   deleteLinkPage(id: number): Promise<void>;
-  addLinkPageItem(pageId: number, input: LinkPageItemInput): Promise<LinkPageItem>;
+  addLinkPageItem(pageId: number, input: LinkPageItemInput): Promise<LinkPageItem<T>>;
   updateLinkPageItem(
     id: number,
     input: Partial<LinkPageItemInput>,
-  ): Promise<LinkPageItem>;
+  ): Promise<LinkPageItem<T>>;
   deleteLinkPageItem(id: number): Promise<void>;
   reorderLinkPageItems(pageId: number, orderedItemIds: number[]): Promise<void>;
 }