@gigamusic/admin 2.1.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gigamusic/admin",
-  "version": "2.1.0",
+  "version": "3.0.0",
   "description": "Server-only admin API handler factories for the gigamusic platform (releases CRUD, tracks, uploads, settings, links, orders).",
   "license": "MIT",
   "repository": {
@@ -24,10 +24,10 @@
   },
   "dependencies": {
     "zod": "^3.24.1",
-    "@gigamusic/audio": "1.0.0",
-    "@gigamusic/core": "1.0.0",
-    "@gigamusic/storage": "1.0.0",
-    "@gigamusic/db": "2.1.0"
+    "@gigamusic/db": "3.0.0",
+    "@gigamusic/audio": "3.0.0",
+    "@gigamusic/storage": "3.0.0",
+    "@gigamusic/core": "3.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.5",

package/src/handlers/links.ts

@@ -1,32 +1,46 @@
-import type { AdminDeps, RouteHandler } from "../lib/types";
-import type { LinkInput } from "@gigamusic/db";
+import { z } from "zod";
+import type {
+  DefaultTables,
+  LinkInput,
+  Queries,
+  QueryTables,
+} from "@gigamusic/db";
+import type { AdminLogger, RouteHandler } from "../lib/types";
 import { badRequest, json, notFound } from "../lib/responses";
 
-interface LinkBody {
-  id?: unknown;
-  title?: unknown;
-  url?: unknown;
-  position?: unknown;
-  isVisible?: unknown;
-  showOnHero?: unknown;
-}
+/**
+ * Base validation schema for a global `/links` page entry. Consumers extend
+ * this to validate extras (e.g. an internal flag) and pass it as `inputSchema`.
+ */
+export const LinkInputSchema = z.object({
+  id: z.number().int().optional(),
+  title: z.string().trim().min(1),
+  url: z.string().trim().min(1),
+  position: z.number().int().nonnegative().optional(),
+  isVisible: z.boolean().optional(),
+  showOnHero: z.boolean().optional(),
+});
 
 interface ReorderBody {
   orderedIds?: unknown;
 }
 
-function toLinkInput(body: LinkBody): LinkInput | null {
-  const title = typeof body.title === "string" ? body.title : null;
-  const url = typeof body.url === "string" ? body.url : null;
-  if (!title || !url) return null;
-  return {
-    id: typeof body.id === "number" && Number.isFinite(body.id) ? body.id : undefined,
-    title,
-    url,
-    position: typeof body.position === "number" ? body.position : undefined,
-    isVisible: typeof body.isVisible === "boolean" ? body.isVisible : undefined,
-    showOnHero: typeof body.showOnHero === "boolean" ? body.showOnHero : undefined,
-  };
+export interface LinksHandlerDeps<
+  T extends QueryTables = DefaultTables,
+   
+  TInput extends z.ZodObject<any> = typeof LinkInputSchema,
+> {
+  queries: Queries<T>;
+  logger?: AdminLogger;
+  /**
+   * Defaults to `LinkInputSchema`. Pass an `.extend()`ed schema to validate
+   * consumer extras on the wire. Note that `queries.upsertLink` only writes
+   * gigamusic-managed columns — consumers persist their extras via an
+   * `afterWrite` hook (best-effort, not tx-atomic with the gigamusic write).
+   */
+  inputSchema?: TInput;
+  /** Invoked after `queries.upsertLink` resolves. Not wrapped in a transaction. */
+  afterWrite?: (linkId: number, input: z.infer<TInput>) => Promise<void>;
 }
 
 /**
@@ -41,27 +55,39 @@ function toLinkInput(body: LinkBody): LinkInput | null {
  * Auth: the package assumes the request has been gated by the consumer's
  * `proxy.ts` / middleware. These handlers don't verify a session.
  */
-export function createAdminLinksHandlers(
-  deps: Pick<AdminDeps, "queries" | "logger">,
-): {
+export function createAdminLinksHandlers<
+  T extends QueryTables = DefaultTables,
+   
+  TInput extends z.ZodObject<any> = typeof LinkInputSchema,
+>(deps: LinksHandlerDeps<T, TInput>): {
   GET: RouteHandler;
   POST: RouteHandler;
   PUT: RouteHandler;
   DELETE: RouteHandler;
 } {
+  const inputSchema = (deps.inputSchema ?? LinkInputSchema) as TInput;
+
+  const runUpsert = async (input: z.infer<TInput>): Promise<unknown> => {
+    const link = await deps.queries.upsertLink(input as unknown as LinkInput);
+    if (deps.afterWrite) {
+      await deps.afterWrite((link as { id: number }).id, input);
+    }
+    return link;
+  };
+
   return {
     GET: async () => {
       return json(await deps.queries.listAllLinks());
     },
     POST: async (req) => {
-      const body = (await safeJson(req)) as LinkBody;
-      const input = toLinkInput(body);
-      if (!input) return badRequest("title and url are required");
-      const link = await deps.queries.upsertLink(input);
+      const body = (await safeJson(req)) as unknown;
+      const parsed = inputSchema.safeParse(body);
+      if (!parsed.success) return badRequest("title and url are required");
+      const link = await runUpsert(parsed.data as z.infer<TInput>);
       return json(link, { status: 201 });
     },
     PUT: async (req) => {
-      const body = (await safeJson(req)) as LinkBody & ReorderBody;
+      const body = (await safeJson(req)) as ReorderBody & Record<string, unknown>;
       if (Array.isArray(body.orderedIds)) {
         const ids = body.orderedIds
           .map((x) => (typeof x === "number" ? x : Number(x)))
@@ -69,18 +95,11 @@ export function createAdminLinksHandlers(
         await deps.queries.reorderLinks(ids);
         return json({ ok: true });
       }
-      const id = typeof body.id === "number" && Number.isFinite(body.id) ? body.id : null;
-      if (id == null) return badRequest("id is required");
-      // upsertLink handles partial updates when given an id; pass through
-      // every supplied field.
-      const link = await deps.queries.upsertLink({
-        id,
-        title: typeof body.title === "string" ? body.title : "",
-        url: typeof body.url === "string" ? body.url : "",
-        position: typeof body.position === "number" ? body.position : undefined,
-        isVisible: typeof body.isVisible === "boolean" ? body.isVisible : undefined,
-        showOnHero: typeof body.showOnHero === "boolean" ? body.showOnHero : undefined,
-      });
+      const parsed = inputSchema.safeParse(body);
+      if (!parsed.success) return badRequest("Validation failed");
+      const dataWithId = parsed.data as { id?: number };
+      if (dataWithId.id == null) return badRequest("id is required");
+      const link = await runUpsert(parsed.data as z.infer<TInput>);
       return json(link);
     },
     DELETE: async (req) => {

package/src/handlers/orders.ts

@@ -1,16 +1,19 @@
-import type { AdminDeps, RouteHandler } from "../lib/types";
+import type { DefaultTables, Queries, QueryTables } from "@gigamusic/db";
+import type { RouteHandler } from "../lib/types";
 import { badRequest, json } from "../lib/responses";
 
 /**
  * GET /api/admin/orders?email=… — returns the order history for a given
  * email address.
  *
+ * Read-only; no `inputSchema` / hooks since there's no write.
+ *
  * Auth: the package assumes the request has been gated by the consumer's
  * `proxy.ts` / middleware. This handler doesn't verify a session.
  */
-export function createAdminOrdersHandler(
-  deps: Pick<AdminDeps, "queries">,
-): RouteHandler {
+export function createAdminOrdersHandler<T extends QueryTables = DefaultTables>(deps: {
+  queries: Queries<T>;
+}): RouteHandler {
   return async (req) => {
     const url = new URL(req.url);
     const email = url.searchParams.get("email");

package/src/handlers/releases.ts

@@ -4,16 +4,31 @@ import {
   TrackInputSchema,
   type ReleaseInput,
 } from "@gigamusic/core";
-import { isUniqueConstraintError as isUniqueConstraintErrorByCode } from "@gigamusic/db";
-import type { AdminDeps, RouteHandler } from "../lib/types";
+import {
+  insertReleaseTx,
+  isUniqueConstraintError as isUniqueConstraintErrorByCode,
+  updateReleaseTx,
+  type DefaultTables,
+  type GigamusicDb,
+  type Queries,
+  type QueryTables,
+  type Tx,
+} from "@gigamusic/db";
+import type {
+  AdminDeps,
+  AdminLogger,
+  RouteHandler,
+  WriteHookContext,
+} from "../lib/types";
+import type { StorageProvider } from "@gigamusic/storage";
 import { badRequest, json, notFound } from "../lib/responses";
 
-type ReleasesDeps = Pick<AdminDeps, "queries" | "storage" | "logger">;
-
 /**
  * Draft releases skip the strict published-validation rules so an admin can
- * save in-progress work. We coerce missing numerics to 0 and missing track
- * arrays to `[]` so the persistence call sees a complete shape.
+ * save in-progress work. Built off the *base* `ReleaseInputSchema` — consumer
+ * extension columns are NOT carried into the draft variant, because draft
+ * validation stays gigamusic-managed. Consumers who want their extras
+ * validated on draft must pass an extended `inputSchema` themselves.
  */
 const DraftReleaseSchema = ReleaseInputSchema.extend({
   isPublished: z.literal(false),
@@ -23,8 +38,6 @@ const DraftReleaseSchema = ReleaseInputSchema.extend({
   tracks: z.array(TrackInputSchema.partial({ files: true, price: true })).optional(),
 });
 
-const ReleasePayloadSchema = z.union([ReleaseInputSchema, DraftReleaseSchema]);
-
 /**
  * Flatten zod issues into `{ "tracks[0].artist": ["msg", …] }` shape — matches
  * the field-error format the admin form expects.
@@ -42,32 +55,74 @@ function flattenIssues(error: z.ZodError): Record<string, string[]> {
   return out;
 }
 
+/**
+ * Deps shape shared by both releases handler factories.
+ *
+ * - `inputSchema`: defaults to `ReleaseInputSchema`. Pass an `.extend()`ed
+ *   schema to validate consumer extras alongside the gigamusic-managed
+ *   columns on the *published* path. Draft validation always uses gigamusic's
+ *   own draft schema; extras are passed straight through.
+ * - `beforeWrite` / `afterWrite`: invoked inside the same Drizzle transaction
+ *   as the gigamusic INSERT/UPDATE. Returning rejected → tx rolls back.
+ *   `db` + `tables` must be supplied on `AdminDeps` for hooks to be honored.
+ */
+export interface ReleasesHandlerDeps<
+  T extends QueryTables = DefaultTables,
+   
+  TInput extends z.ZodObject<any> = typeof ReleaseInputSchema,
+> {
+  queries: Queries<T>;
+  db?: GigamusicDb<T>;
+  tables?: T;
+  storage?: StorageProvider;
+  logger?: AdminLogger;
+  inputSchema?: TInput;
+  beforeWrite?: (
+    input: z.infer<TInput>,
+    ctx: WriteHookContext,
+  ) => Promise<void>;
+  afterWrite?: (
+    releaseId: number,
+    input: z.infer<TInput>,
+    ctx: WriteHookContext,
+  ) => Promise<void>;
+}
+
 /**
  * GET /api/admin/releases and POST /api/admin/releases.
  *
  * Auth: the package assumes the request has been gated by the consumer's
  * `proxy.ts` / middleware. These handlers don't verify a session.
  */
-export function createAdminReleasesHandlers(
-  deps: Pick<ReleasesDeps, "queries" | "logger">,
-): { GET: RouteHandler; POST: RouteHandler } {
+export function createAdminReleasesHandlers<
+  T extends QueryTables = DefaultTables,
+   
+  TInput extends z.ZodObject<any> = typeof ReleaseInputSchema,
+>(deps: ReleasesHandlerDeps<T, TInput>): { GET: RouteHandler; POST: RouteHandler } {
+  const inputSchema = (deps.inputSchema ?? ReleaseInputSchema) as TInput;
+  const payloadSchema = z.union([inputSchema, DraftReleaseSchema]);
+  const hooksConfigured = Boolean(deps.beforeWrite || deps.afterWrite);
+
   return {
     GET: async () => {
       const releases = await deps.queries.listAllReleases();
       return json(releases);
     },
     POST: async (req) => {
-const body = await readJson(req);
+      const body = await readJson(req);
       if (!body.ok) return badRequest("Invalid JSON");
 
-      const parsed = ReleasePayloadSchema.safeParse(body.value);
+      const parsed = payloadSchema.safeParse(body.value);
       if (!parsed.success) {
         return badRequest("Validation failed", {
           fieldErrors: flattenIssues(parsed.error),
         });
       }
+
       try {
-        const release = await deps.queries.createRelease(parsed.data as ReleaseInput);
+        const release = hooksConfigured
+          ? await createReleaseWithHooks(deps, parsed.data as z.infer<TInput>)
+          : await deps.queries.createRelease(parsed.data as unknown as ReleaseInput);
         return json(release, { status: 201 });
       } catch (err) {
         if (isUniqueConstraintError(err)) {
@@ -87,24 +142,32 @@ const body = await readJson(req);
  *
  * Auth: gated by the consumer upstream — see `createAdminReleasesHandlers`.
  */
-export function createAdminReleaseByIdHandlers(
-  deps: ReleasesDeps,
+export function createAdminReleaseByIdHandlers<
+  T extends QueryTables = DefaultTables,
+   
+  TInput extends z.ZodObject<any> = typeof ReleaseInputSchema,
+>(
+  deps: ReleasesHandlerDeps<T, TInput> & { storage: StorageProvider },
 ): { GET: RouteHandler; PUT: RouteHandler; DELETE: RouteHandler } {
+  const inputSchema = (deps.inputSchema ?? ReleaseInputSchema) as TInput;
+  const payloadSchema = z.union([inputSchema, DraftReleaseSchema]);
+  const hooksConfigured = Boolean(deps.beforeWrite || deps.afterWrite);
+
   return {
     GET: async (_req, ctx) => {
-const id = await resolveIdParam(ctx);
+      const id = await resolveIdParam(ctx);
       if (id == null) return badRequest("Missing id");
       const all = await deps.queries.listAllReleases();
-      const found = all.find((r) => r.id === id);
+      const found = all.find((r) => (r as unknown as { id: number }).id === id);
       return found ? json(found) : notFound("Release not found");
     },
     PUT: async (req, ctx) => {
-const id = await resolveIdParam(ctx);
+      const id = await resolveIdParam(ctx);
       if (id == null) return badRequest("Missing id");
 
       const body = await readJson(req);
       if (!body.ok) return badRequest("Invalid JSON");
-      const parsed = ReleasePayloadSchema.safeParse(body.value);
+      const parsed = payloadSchema.safeParse(body.value);
       if (!parsed.success) {
         return badRequest("Validation failed", {
           fieldErrors: flattenIssues(parsed.error),
@@ -112,10 +175,12 @@ const id = await resolveIdParam(ctx);
       }
 
       try {
-        const updated = await deps.queries.updateRelease(
-          id,
-          parsed.data as Partial<ReleaseInput>,
-        );
+        const updated = hooksConfigured
+          ? await updateReleaseWithHooks(deps, id, parsed.data as z.infer<TInput>)
+          : await deps.queries.updateRelease(
+              id,
+              parsed.data as unknown as Partial<ReleaseInput>,
+            );
         return json(updated);
       } catch (err) {
         if (isUniqueConstraintError(err)) {
@@ -128,16 +193,19 @@ const id = await resolveIdParam(ctx);
       }
     },
     DELETE: async (_req, ctx) => {
-const id = await resolveIdParam(ctx);
+      const id = await resolveIdParam(ctx);
       if (id == null) return badRequest("Missing id");
 
       // Snapshot storage keys before the cascade nukes the rows, so we can
       // clean up the bucket without an orphaned-file scan.
       const all = await deps.queries.listAllReleases();
-      const release = all.find((r) => r.id === id);
+      const release = all.find((r) => (r as unknown as { id: number }).id === id);
       if (!release) return notFound("Release not found");
 
-      const keys = collectStorageKeys(release, deps.storage);
+      const keys = collectStorageKeys(
+        release as unknown as ReleaseWithFiles,
+        deps.storage,
+      );
       await deps.queries.deleteRelease(id);
       await Promise.all(
         keys.map((key) =>
@@ -156,6 +224,68 @@ const id = await resolveIdParam(ctx);
   };
 }
 
+async function createReleaseWithHooks<
+  T extends QueryTables,
+   
+  TInput extends z.ZodObject<any>,
+>(deps: ReleasesHandlerDeps<T, TInput>, input: z.infer<TInput>): Promise<unknown> {
+  if (!deps.db || !deps.tables) {
+    throw new Error(
+      "createAdminReleasesHandlers: beforeWrite/afterWrite require deps.db and deps.tables.",
+    );
+  }
+  const db = deps.db;
+  const tables = deps.tables;
+  const releaseId = await db.transaction(async (tx) => {
+    const ctx: WriteHookContext = { tx: tx as Tx, logger: deps.logger };
+    if (deps.beforeWrite) await deps.beforeWrite(input, ctx);
+    const id = await insertReleaseTx(tx as Tx, tables, input as unknown as ReleaseInput);
+    if (deps.afterWrite) await deps.afterWrite(id, input, ctx);
+    return id;
+  });
+  // Re-fetch outside the tx so the row includes everything (including extras
+  // the consumer wrote via `afterWrite`).
+  const slug = (input as { slug?: string }).slug;
+  if (slug) {
+    const row = await deps.queries.getReleaseBySlug(slug);
+    if (row) return row;
+  }
+  // Fallback — slug missing or row not found by slug; pull via listAll + id.
+  const all = await deps.queries.listAllReleases();
+  return all.find((r) => (r as unknown as { id: number }).id === releaseId);
+}
+
+async function updateReleaseWithHooks<
+  T extends QueryTables,
+   
+  TInput extends z.ZodObject<any>,
+>(
+  deps: ReleasesHandlerDeps<T, TInput>,
+  id: number,
+  input: z.infer<TInput>,
+): Promise<unknown> {
+  if (!deps.db || !deps.tables) {
+    throw new Error(
+      "createAdminReleaseByIdHandlers: beforeWrite/afterWrite require deps.db and deps.tables.",
+    );
+  }
+  const db = deps.db;
+  const tables = deps.tables;
+  await db.transaction(async (tx) => {
+    const ctx: WriteHookContext = { tx: tx as Tx, logger: deps.logger };
+    if (deps.beforeWrite) await deps.beforeWrite(input, ctx);
+    await updateReleaseTx(
+      tx as Tx,
+      tables,
+      id,
+      input as unknown as Partial<ReleaseInput>,
+    );
+    if (deps.afterWrite) await deps.afterWrite(id, input, ctx);
+  });
+  const all = await deps.queries.listAllReleases();
+  return all.find((r) => (r as unknown as { id: number }).id === id);
+}
+
 interface ReleaseWithFiles {
   coverImageUrl: string | null;
   tracks: Array<{ files: Array<{ storageKey: string }> }>;
@@ -212,3 +342,5 @@ async function readJson(req: Request): Promise<{ ok: true; value: unknown } | {
   }
 }
 
+// Quiet unused-import lint when AdminDeps isn't needed externally.
+export type { AdminDeps };

package/src/handlers/settings.ts

@@ -1,9 +1,29 @@
-import type { AdminDeps, RouteHandler } from "../lib/types";
+import { z } from "zod";
+import type { DefaultTables, Queries, QueryTables } from "@gigamusic/db";
+import type { AdminLogger, RouteHandler } from "../lib/types";
 import { badRequest, json } from "../lib/responses";
 
-interface SettingPayload {
-  key?: unknown;
-  value?: unknown;
+/**
+ * Default settings payload schema — `{ key: string, value: unknown }`. Settings
+ * are heterogeneous so the default `value` is permissive; consumers wanting
+ * per-key validation pass a `.extend()`ed/`.refine()`d schema as `inputSchema`.
+ */
+export const SettingInputSchema = z.object({
+  key: z.string().trim().min(1),
+  value: z.unknown(),
+});
+
+export interface SettingsHandlerDeps<
+  T extends QueryTables = DefaultTables,
+   
+  TInput extends z.ZodObject<any> = typeof SettingInputSchema,
+> {
+  queries: Queries<T>;
+  logger?: AdminLogger;
+  /** Defaults to `SettingInputSchema`. Pass a tighter schema for per-key validation. */
+  inputSchema?: TInput;
+  /** Invoked after `queries.setSetting` resolves. Not tx-atomic. */
+  afterWrite?: (input: z.infer<TInput>) => Promise<void>;
 }
 
 /**
@@ -14,16 +34,18 @@ interface SettingPayload {
  * of truth for serialization (JSON stringification happens inside the db
  * layer).
  *
- * Per-key validation is intentionally not done here — settings are
- * heterogeneous and the admin form for each setting validates before
- * submitting.
+ * Per-key validation can be wired via `inputSchema`; settings remain
+ * heterogeneous so the default schema accepts any `value`.
  *
  * Auth: the package assumes the request has been gated by the consumer's
  * `proxy.ts` / middleware. These handlers don't verify a session.
  */
-export function createAdminSettingsHandlers(
-  deps: Pick<AdminDeps, "queries">,
-): { GET: RouteHandler; PUT: RouteHandler } {
+export function createAdminSettingsHandlers<
+  T extends QueryTables = DefaultTables,
+   
+  TInput extends z.ZodObject<any> = typeof SettingInputSchema,
+>(deps: SettingsHandlerDeps<T, TInput>): { GET: RouteHandler; PUT: RouteHandler } {
+  const inputSchema = (deps.inputSchema ?? SettingInputSchema) as TInput;
   return {
     GET: async (req) => {
       const url = new URL(req.url);
@@ -35,16 +57,17 @@ export function createAdminSettingsHandlers(
       return json({});
     },
     PUT: async (req) => {
-      let body: SettingPayload;
+      let body: unknown;
       try {
-        body = (await req.json()) as SettingPayload;
+        body = await req.json();
       } catch {
         return badRequest("Invalid JSON");
       }
-      if (typeof body.key !== "string" || body.key.length === 0) {
-        return badRequest("key is required");
-      }
-      await deps.queries.setSetting(body.key, body.value);
+      const parsed = inputSchema.safeParse(body);
+      if (!parsed.success) return badRequest("Validation failed");
+      const data = parsed.data as { key: string; value: unknown };
+      await deps.queries.setSetting(data.key, data.value);
+      if (deps.afterWrite) await deps.afterWrite(parsed.data as z.infer<TInput>);
       return json({ ok: true });
     },
   };

package/src/handlers/upload.ts

@@ -3,11 +3,15 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { writeFile, readFile, unlink, stat } from "node:fs/promises";
 import { createReadStream } from "node:fs";
+import type { DefaultTables, Queries, QueryTables } from "@gigamusic/db";
 import type { AdminDeps, RouteHandler } from "../lib/types";
 import { badRequest, json, serverError } from "../lib/responses";
 
 type PresignDeps = Pick<AdminDeps, "storage">;
-type ProcessDeps = Pick<AdminDeps, "storage" | "audio" | "queries" | "logger">;
+type ProcessDeps<T extends QueryTables = DefaultTables> = Pick<
+  AdminDeps<T>,
+  "storage" | "audio" | "logger"
+> & { queries: Queries<T> };
 
 // Path segments allow the punctuation common in real-world track filenames
 // alongside alphanumerics, dashes, dots, underscores, spaces, parens, and
@@ -121,7 +125,9 @@ function bufferFromDataUrl(value: unknown): Buffer | null {
  *      because the track row isn't created yet — the release POST handler
  *      persists the files alongside the row).
  */
-export function createAdminUploadProcessHandler(deps: ProcessDeps): RouteHandler {
+export function createAdminUploadProcessHandler<T extends QueryTables = DefaultTables>(
+  deps: ProcessDeps<T>,
+): RouteHandler {
   return async (req) => {
     const body = (await safeJson(req)) as ProcessBody;
     const key = typeof body.key === "string" ? body.key : "";

package/src/lib/types.ts

@@ -1,4 +1,10 @@
-import type { Queries } from "@gigamusic/db";
+import type {
+  DefaultTables,
+  GigamusicDb,
+  Queries,
+  QueryTables,
+  Tx,
+} from "@gigamusic/db";
 import type { StorageProvider } from "@gigamusic/storage";
 import type * as Audio from "@gigamusic/audio";
 
@@ -18,12 +24,28 @@ export type RouteHandler = (
  * bag) into each factory; nothing inside the admin package reads
  * `process.env` directly.
  *
+ * Generic over the consumer's `QueryTables` shape so the underlying `Queries`
+ * and `beforeWrite`/`afterWrite` hooks see consumer-extended tables when the
+ * consumer passed `buildX(extras)` tables in.
+ *
  * Auth deliberately isn't here: the package's handlers trust that the
  * request has been gated by the consumer's `proxy.ts` (or middleware /
  * route-level wrapper). See `docs/setup.md` for auth recipes.
  */
-export interface AdminDeps {
-  queries: Queries;
+export interface AdminDeps<T extends QueryTables = DefaultTables> {
+  queries: Queries<T>;
+  /**
+   * Raw Drizzle instance — used by handlers that need to open a transaction
+   * for the `beforeWrite` / `afterWrite` hooks. Not required when no hooks
+   * are configured.
+   */
+  db?: GigamusicDb<T>;
+  /**
+   * The consumer's table identities. Required only when a hook-using handler
+   * is constructed so the package can run tx-bound writes against the same
+   * tables the consumer's hook will write to.
+   */
+  tables?: T;
   storage: StorageProvider;
   audio: typeof Audio;
   /**
@@ -44,3 +66,14 @@ export const noopLogger: AdminLogger = {
   warn() {},
   error() {},
 };
+
+/**
+ * Context passed to `beforeWrite` / `afterWrite` hooks. `tx` is the active
+ * Drizzle transaction the gigamusic INSERT/UPDATE runs inside — consumer
+ * hooks INSERT/UPDATE their own tables through this handle, not through
+ * their app's `db` singleton, so failures roll back the gigamusic write.
+ */
+export interface WriteHookContext {
+  tx: Tx;
+  logger?: AdminLogger;
+}

package/src/server.ts

@@ -16,6 +16,7 @@ export {
   createAdminReleasesHandlers,
   createAdminReleaseByIdHandlers,
 } from "./handlers/releases";
+export type { ReleasesHandlerDeps } from "./handlers/releases";
 export {
   createAdminUploadPresignHandler,
   createAdminUploadProcessHandler,
@@ -28,4 +29,5 @@ export type {
   AdminDeps,
   AdminLogger,
   RouteHandler,
+  WriteHookContext,
 } from "./lib/types";