@frigear-nu/forms 0.1.2 → 0.1.3

package/dist/runtime/server/mcp/tools/admin/get-submission.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { eq } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
+import { isoDate } from "@frigear-nu/module-kit/server";
 export default defineScopedMcpTool({
   description: "Get one submission (staff). Answers, submitter and file names are only included with the forms:pii scope.",
   scopes: ["forms:manage"],
@@ -8,18 +9,17 @@ export default defineScopedMcpTool({
   annotations: { readOnlyHint: true },
   inputSchema: { id: z.string() },
   handler: async ({ id }, ctx) => {
-    const [row] = await db.select().from(schema.formSubmissions).where(eq(schema.formSubmissions.id, id)).limit(1);
-    if (!row) throw createError({ statusCode: 404, statusMessage: "Submission not found." });
+    const row = await findSubmissionById(id);
     const files = await db.select().from(schema.formSubmissionFiles).where(eq(schema.formSubmissionFiles.submissionId, row.id));
     const allow = ctx.hasScope("forms:pii");
     const submission = redactPii({
       ...pick(row, ["id", "formId", "formSlug", "formVersion", "locale", "deliveryStatus"]),
-      createdAt: row.createdAt.toISOString(),
+      createdAt: isoDate(row.createdAt),
       answeredFields: Object.keys(row.answers),
       fileCount: files.length,
       answers: row.answers,
       userId: row.userId,
-      files: files.map(({ id: id2, fieldKey, filename, contentType, size }) => ({ id: id2, fieldKey, filename, contentType, size }))
+      files: files.map(toSubmissionFileDto)
     }, { allow, fields: ["answers", "userId", "files"] });
     return { notice: piiNotice(allow, "forms:pii", "Answers, the submitter and file names"), submission };
   }

package/dist/runtime/server/mcp/tools/submit-form.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { submissionLocale } from "../../utils/submit.js";
 export default defineScopedMcpTool({
   description: "Submit a published form as yourself. Use get-form first to see the fields.",
   scopes: ["forms:submit"],
@@ -6,7 +7,7 @@ export default defineScopedMcpTool({
   inputSchema: {
     slug: z.string(),
     answers: z.record(z.string(), z.unknown()).describe("Answers keyed by field key."),
-    locale: z.string().max(20).optional()
+    locale: submissionLocale.optional()
   },
   handler: async ({ slug, answers, locale }, { event, user }) => {
     await enforceRateLimit(event, slug);

package/dist/runtime/server/routes/admin/form-clone.post.js

@@ -1,10 +1,11 @@
 import { db, schema } from "@nuxthub/db";
+import { created, idParams, uniqueCopySlug } from "@frigear-nu/module-kit/server";
 import { newId } from "../../../utils/index.js";
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const source = await findFormById(getRouterParam(event, "id"));
-  let slug = `${source.slug}-copy`;
-  for (let n = 2; await findFormBySlug(slug); n++) slug = `${source.slug}-copy-${n}`;
+  await formsStaff.require(event);
+  const { id } = await getValidatedRouterParams(event, idParams().parse);
+  const source = await findFormById(id);
+  const slug = await uniqueCopySlug(source.slug, findFormBySlug);
   const [row] = await db.insert(schema.forms).values({
     id: newId("frm"),
     slug,
@@ -12,6 +13,5 @@ export default defineEventHandler(async (event) => {
     status: "draft",
     definition: source.definition
   }).returning();
-  setResponseStatus(event, 201);
-  return toAdminForm(row);
+  return created(event, toAdminForm(row));
 });

package/dist/runtime/server/routes/admin/form-password.delete.js

@@ -1,8 +1,10 @@
 import { eq } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
+import { idParams, noContent } from "@frigear-nu/module-kit/server";
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const form = await findFormById(getRouterParam(event, "id"));
+  await formsStaff.require(event, { sessionOnly: true });
+  const { id } = await getValidatedRouterParams(event, idParams().parse);
+  const form = await findFormById(id);
   await db.delete(schema.formAccess).where(eq(schema.formAccess.formId, form.id));
-  return { set: false };
+  return noContent(event);
 });

package/dist/runtime/server/routes/admin/form-password.get.js

@@ -1,8 +1,10 @@
 import { eq } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
+import { idParams } from "@frigear-nu/module-kit/server";
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const form = await findFormById(getRouterParam(event, "id"));
+  await formsStaff.require(event);
+  const { id } = await getValidatedRouterParams(event, idParams().parse);
+  const form = await findFormById(id);
   const [row] = await db.select({ formId: schema.formAccess.formId }).from(schema.formAccess).where(eq(schema.formAccess.formId, form.id)).limit(1);
   return { set: !!row };
 });

package/dist/runtime/server/routes/admin/form-password.put.js

@@ -1,10 +1,12 @@
 import { z } from "zod";
 import { db, schema } from "@nuxthub/db";
+import { idParams } from "@frigear-nu/module-kit/server";
 const input = z.object({ password: z.string().min(6).max(200) });
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const form = await findFormById(getRouterParam(event, "id"));
+  await formsStaff.require(event, { sessionOnly: true });
+  const { id } = await getValidatedRouterParams(event, idParams().parse);
   const { password } = await readValidatedBody(event, input.parse);
+  const form = await findFormById(id);
   const passwordHash = await hashPassword(password);
   await db.insert(schema.formAccess).values({ formId: form.id, passwordHash }).onConflictDoUpdate({
     target: schema.formAccess.formId,

package/dist/runtime/server/routes/admin/form-secret.delete.js

@@ -1,8 +1,9 @@
+import { noContent } from "@frigear-nu/module-kit/server";
+import { secretParams } from "../../utils/admin-schemas.js";
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const form = await findFormById(getRouterParam(event, "id"));
-  const key = getRouterParam(event, "key");
-  if (!isFormSecretKey(key)) throw createError({ statusCode: 400, statusMessage: "Unknown secret key." });
+  await formsStaff.require(event, { sessionOnly: true });
+  const { id, key } = await getValidatedRouterParams(event, secretParams.parse);
+  const form = await findFormById(id);
   await deleteFormSecret(form.id, key);
-  return describeFormSecrets(event, form.id);
+  return noContent(event);
 });

package/dist/runtime/server/routes/admin/form-secret.put.js

@@ -0,0 +1,11 @@
+import { z } from "zod";
+import { secretParams } from "../../utils/admin-schemas.js";
+const input = z.object({ value: z.string().trim().min(1).max(2e3) });
+export default defineEventHandler(async (event) => {
+  await formsStaff.require(event, { sessionOnly: true });
+  const { id, key } = await getValidatedRouterParams(event, secretParams.parse);
+  const { value } = await readValidatedBody(event, input.parse);
+  const form = await findFormById(id);
+  await setFormSecret(form.id, key, value);
+  return describeFormSecrets(event, form.id);
+});

package/dist/runtime/server/routes/admin/form-secrets.get.js

@@ -1,5 +1,7 @@
+import { idParams } from "@frigear-nu/module-kit/server";
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const form = await findFormById(getRouterParam(event, "id"));
+  await formsStaff.require(event);
+  const { id } = await getValidatedRouterParams(event, idParams().parse);
+  const form = await findFormById(id);
   return describeFormSecrets(event, form.id);
 });

package/dist/runtime/server/routes/admin/form-token.delete.js

@@ -1,12 +1,15 @@
 import { and, eq } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
+import { idParams, noContent, notFound } from "@frigear-nu/module-kit/server";
+const params = idParams().extend(idParams("tokenId").shape);
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const form = await findFormById(getRouterParam(event, "id"));
+  await formsStaff.require(event, { sessionOnly: true });
+  const { id, tokenId } = await getValidatedRouterParams(event, params.parse);
+  const form = await findFormById(id);
   const [row] = await db.update(schema.formAccessTokens).set({ revokedAt: /* @__PURE__ */ new Date() }).where(and(
-    eq(schema.formAccessTokens.id, getRouterParam(event, "tokenId")),
+    eq(schema.formAccessTokens.id, tokenId),
     eq(schema.formAccessTokens.formId, form.id)
-  )).returning();
-  if (!row) throw createError({ statusCode: 404, statusMessage: "Token not found." });
-  return toTokenDto(row);
+  )).returning({ id: schema.formAccessTokens.id });
+  if (!row) throw notFound("Token not found.");
+  return noContent(event);
 });

package/dist/runtime/server/routes/admin/form-tokens.get.js

@@ -1,8 +1,10 @@
 import { desc, eq } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
+import { idParams } from "@frigear-nu/module-kit/server";
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const form = await findFormById(getRouterParam(event, "id"));
+  await formsStaff.require(event);
+  const { id } = await getValidatedRouterParams(event, idParams().parse);
+  const form = await findFormById(id);
   const rows = await db.select().from(schema.formAccessTokens).where(eq(schema.formAccessTokens.formId, form.id)).orderBy(desc(schema.formAccessTokens.createdAt));
-  return rows.map(toTokenDto);
+  return rows.map(toFormTokenDto);
 });

package/dist/runtime/server/routes/admin/form-tokens.post.js

@@ -1,12 +1,13 @@
 import { z } from "zod";
 import { db, schema } from "@nuxthub/db";
+import { created, idParams } from "@frigear-nu/module-kit/server";
 const input = z.object({ name: z.string().trim().min(1).max(100) });
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const form = await findFormById(getRouterParam(event, "id"));
+  await formsStaff.require(event, { sessionOnly: true });
+  const { id: formId } = await getValidatedRouterParams(event, idParams().parse);
   const { name } = await readValidatedBody(event, input.parse);
+  const form = await findFormById(formId);
   const { id, token, tokenHash, prefix } = await generateToken();
   const [row] = await db.insert(schema.formAccessTokens).values({ id, formId: form.id, name, tokenHash, prefix }).returning();
-  setResponseStatus(event, 201);
-  return { ...toTokenDto(row), token };
+  return created(event, { ...toFormTokenDto(row), token });
 });

package/dist/runtime/server/routes/admin/form.delete.js

@@ -1,8 +1,10 @@
 import { eq } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
+import { idParams, noContent } from "@frigear-nu/module-kit/server";
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const current = await findFormById(getRouterParam(event, "id"));
-  const [row] = await db.update(schema.forms).set({ status: "archived" }).where(eq(schema.forms.id, current.id)).returning();
-  return toAdminForm(row);
+  await formsStaff.require(event);
+  const { id } = await getValidatedRouterParams(event, idParams().parse);
+  const current = await findFormById(id);
+  await db.update(schema.forms).set({ status: "archived" }).where(eq(schema.forms.id, current.id));
+  return noContent(event);
 });

package/dist/runtime/server/routes/admin/form.get.js

@@ -1,8 +1,10 @@
 import { count, eq } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
+import { idParams } from "@frigear-nu/module-kit/server";
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const row = await findFormById(getRouterParam(event, "id"));
+  await formsStaff.require(event);
+  const { id } = await getValidatedRouterParams(event, idParams().parse);
+  const row = await findFormById(id);
   const [totals] = await db.select({ total: count() }).from(schema.formSubmissions).where(eq(schema.formSubmissions.formId, row.id));
   return { ...toAdminForm(row), submissionCount: totals?.total ?? 0 };
 });

package/dist/runtime/server/routes/admin/form.patch.js

@@ -1,8 +1,8 @@
+import { idParams } from "@frigear-nu/module-kit/server";
 import { formPatch } from "../../utils/admin-schemas.js";
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const id = getRouterParam(event, "id");
-  await findFormById(id);
+  await formsStaff.require(event);
+  const { id } = await getValidatedRouterParams(event, idParams().parse);
   const input = await readValidatedBody(event, formPatch.parse);
   return toAdminForm(await patchForm(id, input));
 });

package/dist/runtime/server/routes/admin/forms.get.js

@@ -1,19 +1,40 @@
-import { count, desc } from "drizzle-orm";
+import { and, count, eq, inArray, ne, or, sql } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
+import { z } from "zod";
+import { likeContains, orderByQuery, pageQuery, pageRange, paginate } from "@frigear-nu/module-kit/server";
+const querySchema = pageQuery({
+  sort: ["updatedAt", "createdAt", "name", "slug", "status", "submissionCount"],
+  defaultSort: "updatedAt",
+  defaultOrder: "desc",
+  filters: {
+    status: z.enum(["draft", "published", "archived"]).optional(),
+    /** `false` hides archived forms (ignored when `status` is set). */
+    archived: z.enum(["true", "false"]).optional()
+  }
+});
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const rows = await db.select().from(schema.forms).orderBy(desc(schema.forms.updatedAt));
-  const counts = await db.select({ formId: schema.formSubmissions.formId, total: count() }).from(schema.formSubmissions).groupBy(schema.formSubmissions.formId);
-  const totals = new Map(counts.map((row) => [row.formId, row.total]));
-  return rows.map((row) => ({
-    id: row.id,
-    slug: row.slug,
-    name: row.name,
-    status: row.status,
-    version: row.version,
-    storage: row.definition.storage,
-    mode: row.definition.mode,
-    submissionCount: totals.get(row.id) ?? 0,
-    updatedAt: row.updatedAt.toISOString()
-  }));
+  await formsStaff.require(event);
+  const query = await getValidatedQuery(event, querySchema.parse);
+  const conditions = [];
+  if (query.q) conditions.push(or(likeContains(schema.forms.name, query.q), likeContains(schema.forms.slug, query.q)));
+  if (query.status) conditions.push(eq(schema.forms.status, query.status));
+  else if (query.archived === "false") conditions.push(ne(schema.forms.status, "archived"));
+  const where = conditions.length ? and(...conditions) : void 0;
+  const submissionCount = sql`(select count(*) from ${schema.formSubmissions} where ${schema.formSubmissions.formId} = ${schema.forms.id})`;
+  const orderBy = orderByQuery({
+    updatedAt: schema.forms.updatedAt,
+    createdAt: schema.forms.createdAt,
+    name: schema.forms.name,
+    slug: schema.forms.slug,
+    status: schema.forms.status,
+    submissionCount
+  }, query, { tiebreaker: schema.forms.id });
+  const { limit, offset } = pageRange(query);
+  const [rows, [totals]] = await Promise.all([
+    db.select().from(schema.forms).where(where).orderBy(...orderBy).limit(limit).offset(offset),
+    db.select({ total: count() }).from(schema.forms).where(where)
+  ]);
+  const counts = rows.length ? await db.select({ formId: schema.formSubmissions.formId, total: count() }).from(schema.formSubmissions).where(inArray(schema.formSubmissions.formId, rows.map((row) => row.id))).groupBy(schema.formSubmissions.formId) : [];
+  const totalsByForm = new Map(counts.map((row) => [row.formId, row.total]));
+  return paginate({ items: rows.map((row) => toFormSummaryDto(row, totalsByForm.get(row.id) ?? 0)), total: totals?.total ?? 0, query });
 });

package/dist/runtime/server/routes/admin/forms.post.js

@@ -1,8 +1,7 @@
+import { created } from "@frigear-nu/module-kit/server";
 import { formInput } from "../../utils/admin-schemas.js";
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
+  await formsStaff.require(event);
   const input = await readValidatedBody(event, formInput.parse);
-  const row = await createForm(input);
-  setResponseStatus(event, 201);
-  return toAdminForm(row);
+  return created(event, toAdminForm(await createForm(input)));
 });

package/dist/runtime/server/routes/admin/import.post.js

@@ -1,6 +1,7 @@
 import { importInput } from "../../utils/admin-schemas.js";
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
+  await formsStaff.require(event);
   const { forms } = await readValidatedBody(event, importInput.parse);
-  return seedForms(forms.map((form) => ({ ...form, definition: form.definition })));
+  const { inserted, skipped } = await seedForms(forms.map((form) => ({ ...form, definition: form.definition })));
+  return { inserted, skipped };
 });

package/dist/runtime/server/routes/admin/submission-file.get.js

@@ -1,15 +1,18 @@
 import { and, eq } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
 import { blob } from "@nuxthub/blob";
+import { idParams, notFound } from "@frigear-nu/module-kit/server";
+const params = idParams().extend(idParams("fileId").shape);
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
+  await formsStaff.require(event);
+  const { id, fileId } = await getValidatedRouterParams(event, params.parse);
   const [file] = await db.select().from(schema.formSubmissionFiles).where(and(
-    eq(schema.formSubmissionFiles.submissionId, getRouterParam(event, "id")),
-    eq(schema.formSubmissionFiles.id, getRouterParam(event, "fileId"))
+    eq(schema.formSubmissionFiles.submissionId, id),
+    eq(schema.formSubmissionFiles.id, fileId)
   )).limit(1);
-  if (!file) throw createError({ statusCode: 404, statusMessage: "File not found." });
+  if (!file) throw notFound("File not found.");
   const stored = await blob.get(file.pathname);
-  if (!stored) throw createError({ statusCode: 404, statusMessage: "File not found." });
+  if (!stored) throw notFound("File not found.");
   setResponseHeader(event, "content-type", file.contentType);
   setResponseHeader(event, "content-disposition", `attachment; filename="${encodeURIComponent(file.filename)}"`);
   setResponseHeader(event, "x-content-type-options", "nosniff");

package/dist/runtime/server/routes/admin/submission-redeliver.post.js

@@ -1,9 +1,10 @@
 import { eq } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
+import { idParams } from "@frigear-nu/module-kit/server";
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const [row] = await db.select().from(schema.formSubmissions).where(eq(schema.formSubmissions.id, getRouterParam(event, "id"))).limit(1);
-  if (!row) throw createError({ statusCode: 404, statusMessage: "Submission not found." });
+  await formsStaff.require(event);
+  const { id } = await getValidatedRouterParams(event, idParams().parse);
+  const row = await findSubmissionById(id);
   const files = await db.select().from(schema.formSubmissionFiles).where(eq(schema.formSubmissionFiles.submissionId, row.id));
   const [form] = await db.select().from(schema.forms).where(eq(schema.forms.id, row.formId)).limit(1);
   const ctx = {

package/dist/runtime/server/routes/admin/submission.get.js

@@ -1,22 +1,10 @@
 import { eq } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
+import { idParams } from "@frigear-nu/module-kit/server";
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const [row] = await db.select().from(schema.formSubmissions).where(eq(schema.formSubmissions.id, getRouterParam(event, "id"))).limit(1);
-  if (!row) throw createError({ statusCode: 404, statusMessage: "Submission not found." });
+  await formsStaff.require(event);
+  const { id } = await getValidatedRouterParams(event, idParams().parse);
+  const row = await findSubmissionById(id);
   const files = await db.select().from(schema.formSubmissionFiles).where(eq(schema.formSubmissionFiles.submissionId, row.id));
-  return {
-    id: row.id,
-    formId: row.formId,
-    formSlug: row.formSlug,
-    formVersion: row.formVersion,
-    definition: row.definitionSnapshot,
-    answers: row.answers,
-    files: files.map(({ id, fieldKey, filename, contentType, size }) => ({ id, fieldKey, filename, contentType, size })),
-    locale: row.locale,
-    userId: row.userId,
-    deliveryStatus: row.deliveryStatus,
-    deliveryError: row.deliveryError,
-    createdAt: row.createdAt.toISOString()
-  };
+  return toSubmissionDto(row, files);
 });

package/dist/runtime/server/routes/admin/submissions.get.js

@@ -1,16 +1,32 @@
-import { desc, eq } from "drizzle-orm";
+import { and, count, eq } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
-import { renderAnswers } from "../../utils/render.js";
+import { z } from "zod";
+import { idParams, orderByQuery, pageQuery, pageRange, paginate } from "@frigear-nu/module-kit/server";
+const querySchema = pageQuery({
+  sort: ["createdAt", "deliveryStatus", "locale"],
+  defaultSort: "createdAt",
+  defaultOrder: "desc",
+  filters: {
+    deliveryStatus: z.enum(["none", "pending", "delivered", "failed"]).optional()
+  }
+});
 export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const form = await findFormById(getRouterParam(event, "id"));
-  const rows = await db.select().from(schema.formSubmissions).where(eq(schema.formSubmissions.formId, form.id)).orderBy(desc(schema.formSubmissions.createdAt)).limit(500);
-  return rows.map((row) => ({
-    id: row.id,
-    createdAt: row.createdAt.toISOString(),
-    locale: row.locale,
-    userId: row.userId,
-    deliveryStatus: row.deliveryStatus,
-    preview: renderAnswers(row.definitionSnapshot, row.answers, row.locale).filter((answer) => answer.value).slice(0, 3).map(({ label, value }) => ({ label, value: value.slice(0, 120) }))
-  }));
+  await formsStaff.require(event);
+  const { id } = await getValidatedRouterParams(event, idParams().parse);
+  const query = await getValidatedQuery(event, querySchema.parse);
+  const form = await findFormById(id);
+  const conditions = [eq(schema.formSubmissions.formId, form.id)];
+  if (query.deliveryStatus) conditions.push(eq(schema.formSubmissions.deliveryStatus, query.deliveryStatus));
+  const where = and(...conditions);
+  const orderBy = orderByQuery({
+    createdAt: schema.formSubmissions.createdAt,
+    deliveryStatus: schema.formSubmissions.deliveryStatus,
+    locale: schema.formSubmissions.locale
+  }, query, { tiebreaker: schema.formSubmissions.id });
+  const { limit, offset } = pageRange(query);
+  const [rows, [totals]] = await Promise.all([
+    db.select().from(schema.formSubmissions).where(where).orderBy(...orderBy).limit(limit).offset(offset),
+    db.select({ total: count() }).from(schema.formSubmissions).where(where)
+  ]);
+  return paginate({ items: rows.map(toSubmissionSummaryDto), total: totals?.total ?? 0, query });
 });

package/dist/runtime/server/routes/public/access.get.js

@@ -1,3 +1,5 @@
+import { slugParams } from "../../utils/admin-schemas.js";
 export default defineEventHandler(async (event) => {
-  return describeFormAccess(event, await findPublishedForm(getRouterParam(event, "slug")));
+  const { slug } = await getValidatedRouterParams(event, slugParams.parse);
+  return describeFormAccess(event, await findPublishedForm(slug));
 });

package/dist/runtime/server/routes/public/form.get.js

@@ -1,5 +1,7 @@
+import { slugParams } from "../../utils/admin-schemas.js";
 export default defineEventHandler(async (event) => {
-  const form = await findPublishedForm(getRouterParam(event, "slug"));
+  const { slug } = await getValidatedRouterParams(event, slugParams.parse);
+  const form = await findPublishedForm(slug);
   await authorizeFormAccess(event, form);
   return toPublicForm(form);
 });

package/dist/runtime/server/routes/public/submit.post.js

@@ -1,5 +1,6 @@
+import { slugParams } from "../../utils/admin-schemas.js";
 export default defineEventHandler(async (event) => {
-  const slug = getRouterParam(event, "slug");
+  const { slug } = await getValidatedRouterParams(event, slugParams.parse);
   await enforceRateLimit(event, slug);
   const form = await findPublishedForm(slug);
   const { userId } = await authorizeFormAccess(event, form);

package/dist/runtime/server/utils/access.js

@@ -1,3 +1,4 @@
+import { apiError, isoDate } from "@frigear-nu/module-kit/server";
 import { and, eq, isNull } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
 import { isFormOpen, newId, nextFormOpening, resolveAccess } from "../../utils/index.js";
@@ -20,7 +21,7 @@ export function readToken(event) {
 }
 const unauthorized = (event, message, scheme) => {
   if (scheme) setResponseHeader(event, "www-authenticate", scheme);
-  return createError({ statusCode: 401, statusMessage: message, data: { access: true } });
+  return apiError(401, "unauthorized", message, { access: true });
 };
 async function verifyToken(event, form) {
   const token = readToken(event);
@@ -47,7 +48,7 @@ export async function authorizeFormAccess(event, form) {
   const { auth, schedule } = resolveAccess(form.definition);
   if (!isFormOpen(schedule)) {
     const opensAt = nextFormOpening(schedule);
-    throw createError({ statusCode: 403, statusMessage: "This form is closed.", data: { closed: true, opensAt: opensAt?.toISOString() ?? null } });
+    throw apiError(403, "form_closed", "This form is closed.", { closed: true, opensAt: isoDate(opensAt) });
   }
   const user = await getUser(event, { scopes: ["forms:submit"] });
   if (auth === "user" && !user) throw unauthorized(event, "Sign in to use this form.");

package/dist/runtime/server/utils/admin-schemas.d.ts

@@ -493,3 +493,12 @@ export declare const importInput: z.ZodObject<{
         }>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
+/** Router params of the public routes (`/api/forms/:slug`). */
+export declare const slugParams: z.ZodObject<{
+    slug: z.ZodString;
+}, z.core.$strip>;
+/** Router params of `/api/admin/forms/:id/secrets/:key`; an unknown key is a 400. */
+export declare const secretParams: z.ZodObject<{
+    id: z.ZodString;
+    key: z.ZodString;
+}, z.core.$strip>;

package/dist/runtime/server/utils/admin-schemas.js

@@ -1,5 +1,7 @@
 import { z } from "zod";
+import { idParams } from "@frigear-nu/module-kit/server";
 import { formDefinitionSchema } from "../../utils/index.js";
+import { isFormSecretKey } from "./secrets.js";
 const slug = z.string().min(1).max(100).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Use lowercase letters, digits and dashes.").refine((value) => value !== "admin", "This slug is reserved.");
 const statusSchema = z.enum(["draft", "published", "archived"]);
 export const formInput = z.object({
@@ -12,3 +14,5 @@ export const formPatch = formInput.partial().extend({ status: statusSchema.optio
 export const importInput = z.object({
   forms: z.array(formInput.extend({ status: statusSchema.optional() })).min(1).max(50)
 });
+export const slugParams = idParams("slug");
+export const secretParams = idParams().extend({ key: z.string().refine(isFormSecretKey, "Unknown secret key.") });

package/dist/runtime/server/utils/auth.d.ts

@@ -1,8 +1,12 @@
 import type { H3Event } from 'h3';
-/** Gate for the admin routes (form definitions, submissions, files). */
-export declare function requireFormsManager(event: H3Event): Promise<{
-    userId: number;
-}>;
+/**
+ * The staff gate of the admin routes (form definitions, submissions, files, access credentials): the `forms:manage`
+ * scope for bearer credentials, then the host's `forms:authorize` Nitro hook (denied by default).
+ *
+ *     await formsStaff.require(event)                        // reads and ordinary edits
+ *     await formsStaff.require(event, { sessionOnly: true }) // minting or removing access credentials
+ */
+export declare const formsStaff: any;
 /** Non-throwing form of the `forms:authorize` policy for the caller of an already-authenticated request (MCP). */
 export declare const canManageForms: (event: H3Event, principal: {
     user: {

package/dist/runtime/server/utils/auth.js

@@ -1,7 +1,6 @@
-const gate = definePolicyGate("forms:authorize");
-export async function requireFormsManager(event) {
-  const user = await requireUser(event, { scopes: ["forms:manage"] });
-  await gate.assert(event, user.id, "You are not allowed to manage forms.");
-  return { userId: user.id };
-}
-export const canManageForms = (event, principal) => gate.isAllowed(event, principal.user.id);
+export const formsStaff = defineStaffGuard({
+  hook: "forms:authorize",
+  scope: "forms:manage",
+  message: "You are not allowed to manage forms."
+});
+export const canManageForms = (event, principal) => formsStaff.can(event, principal.user.id);

package/dist/runtime/server/utils/captcha.js

@@ -1,3 +1,4 @@
+import { apiError } from "@frigear-nu/module-kit/server";
 const VERIFY_URLS = {
   turnstile: "https://challenges.cloudflare.com/turnstile/v0/siteverify",
   recaptcha: "https://www.google.com/recaptcha/api/siteverify",
@@ -11,7 +12,7 @@ export async function verifyCaptcha(event, provider, token, formId) {
   if (ctx.valid !== void 0) return ctx.valid;
   if (!secret) {
     console.error(`[forms] captcha provider "${provider}" has no secret key: set one on the form or NUXT_FORMS_CAPTCHA_${provider.toUpperCase()}_SECRET_KEY.`);
-    throw createError({ statusCode: 500, statusMessage: `The ${provider} captcha is not configured on the server.`, data: { captcha: true } });
+    throw apiError(500, "not_configured", `The ${provider} captcha is not configured on the server.`, { captcha: true });
   }
   const body = new URLSearchParams({ secret, response: token });
   if (ip) body.set("remoteip", ip);
@@ -20,6 +21,6 @@ export async function verifyCaptcha(event, provider, token, formId) {
     return result?.success === true;
   } catch (cause) {
     console.error(`[forms] ${provider} verification request failed:`, cause);
-    throw createError({ statusCode: 502, statusMessage: "The captcha could not be verified. Please try again.", data: { captcha: true } });
+    throw apiError(502, "captcha_unavailable", "The captcha could not be verified. Please try again.", { captcha: true });
   }
 }

package/dist/runtime/server/utils/forms.d.ts

@@ -1,11 +1,21 @@
 import { schema } from '@nuxthub/db';
-import type { FormAccessTokenDto, FormAdminDto, PublicFormDto } from '../../../types.js';
+import type { FormAccessTokenDto, FormAdminDto, FormSummaryDto, PublicFormDto, SubmissionDto, SubmissionFileDto, SubmissionSummaryDto } from '../../../types.js';
 import type { z } from 'zod';
 import type { formInput, formPatch } from './admin-schemas.js';
 type FormRow = typeof schema.forms.$inferSelect;
 export declare const toPublicForm: (row: FormRow) => PublicFormDto;
-export declare const toTokenDto: (row: typeof schema.formAccessTokens.$inferSelect) => FormAccessTokenDto;
+export declare const toFormTokenDto: (row: typeof schema.formAccessTokens.$inferSelect) => FormAccessTokenDto;
 export declare const toAdminForm: (row: FormRow) => FormAdminDto;
+/** A row of the admin form list. */
+export declare const toFormSummaryDto: (row: FormRow, submissionCount: number) => FormSummaryDto;
+type SubmissionRow = typeof schema.formSubmissions.$inferSelect;
+type SubmissionFileRow = typeof schema.formSubmissionFiles.$inferSelect;
+/** A row of a form's submission list: the first few answers as a preview. */
+export declare const toSubmissionSummaryDto: (row: SubmissionRow) => SubmissionSummaryDto;
+/** File metadata of a submission; the blob pathname stays on the server. */
+export declare const toSubmissionFileDto: (row: SubmissionFileRow) => SubmissionFileDto;
+export declare const toSubmissionDto: (row: SubmissionRow, files: SubmissionFileRow[]) => SubmissionDto;
+export declare function findSubmissionById(id: string): Promise<SubmissionRow>;
 export declare function findFormById(id: string): Promise<FormRow>;
 export declare function findFormBySlug(slug: string): Promise<FormRow | undefined>;
 export declare function findPublishedForm(slug: string): Promise<FormRow>;