@frigear-nu/forms 0.1.2 → 0.1.3

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

@@ -1,17 +1,19 @@
 import { eq } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
+import { conflict, isoDate, notFound } from "@frigear-nu/module-kit/server";
 import { newId } from "../../utils/index.js";
+import { renderAnswers } from "./render.js";
 export const toPublicForm = (row) => {
   const { delivery: _delivery, ...definition } = row.definition;
   return { id: row.id, slug: row.slug, name: row.name, version: row.version, definition };
 };
-export const toTokenDto = (row) => ({
+export const toFormTokenDto = (row) => ({
   id: row.id,
   name: row.name,
   prefix: row.prefix,
-  createdAt: row.createdAt.toISOString(),
-  lastUsedAt: row.lastUsedAt?.toISOString() ?? null,
-  revokedAt: row.revokedAt?.toISOString() ?? null
+  createdAt: isoDate(row.createdAt),
+  lastUsedAt: isoDate(row.lastUsedAt),
+  revokedAt: isoDate(row.revokedAt)
 });
 export const toAdminForm = (row) => ({
   id: row.id,
@@ -20,12 +22,57 @@ export const toAdminForm = (row) => ({
   status: row.status,
   version: row.version,
   definition: row.definition,
-  createdAt: row.createdAt.toISOString(),
-  updatedAt: row.updatedAt.toISOString()
+  createdAt: isoDate(row.createdAt),
+  updatedAt: isoDate(row.updatedAt)
 });
+export const toFormSummaryDto = (row, submissionCount) => ({
+  id: row.id,
+  slug: row.slug,
+  name: row.name,
+  status: row.status,
+  version: row.version,
+  storage: row.definition.storage,
+  mode: row.definition.mode,
+  submissionCount,
+  updatedAt: isoDate(row.updatedAt)
+});
+export const toSubmissionSummaryDto = (row) => ({
+  id: row.id,
+  createdAt: isoDate(row.createdAt),
+  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) }))
+});
+export const toSubmissionFileDto = (row) => ({
+  id: row.id,
+  fieldKey: row.fieldKey,
+  filename: row.filename,
+  contentType: row.contentType,
+  size: row.size
+});
+export const toSubmissionDto = (row, files) => ({
+  id: row.id,
+  formId: row.formId,
+  formSlug: row.formSlug,
+  formVersion: row.formVersion,
+  definition: row.definitionSnapshot,
+  answers: row.answers,
+  files: files.map(toSubmissionFileDto),
+  locale: row.locale,
+  userId: row.userId,
+  deliveryStatus: row.deliveryStatus,
+  deliveryError: row.deliveryError,
+  createdAt: isoDate(row.createdAt)
+});
+export async function findSubmissionById(id) {
+  const [row] = await db.select().from(schema.formSubmissions).where(eq(schema.formSubmissions.id, id)).limit(1);
+  if (!row) throw notFound("Submission not found.");
+  return row;
+}
 export async function findFormById(id) {
   const [row] = await db.select().from(schema.forms).where(eq(schema.forms.id, id)).limit(1);
-  if (!row) throw createError({ statusCode: 404, statusMessage: "Form not found." });
+  if (!row) throw notFound("Form not found.");
   return row;
 }
 export async function findFormBySlug(slug) {
@@ -34,12 +81,12 @@ export async function findFormBySlug(slug) {
 }
 export async function findPublishedForm(slug) {
   const row = await findFormBySlug(slug);
-  if (!row || row.status !== "published") throw createError({ statusCode: 404, statusMessage: "Form not found." });
+  if (!row || row.status !== "published") throw notFound("Form not found.");
   return row;
 }
 export async function createForm(input) {
   if (await findFormBySlug(input.slug)) {
-    throw createError({ statusCode: 409, statusMessage: "A form with this slug already exists." });
+    throw conflict("A form with this slug already exists.", { field: "slug" });
   }
   const [row] = await db.insert(schema.forms).values({ id: newId("frm"), ...input }).returning();
   return row;
@@ -47,7 +94,7 @@ export async function createForm(input) {
 export async function patchForm(id, input) {
   const current = await findFormById(id);
   if (input.slug && input.slug !== current.slug && await findFormBySlug(input.slug)) {
-    throw createError({ statusCode: 409, statusMessage: "A form with this slug already exists." });
+    throw conflict("A form with this slug already exists.", { field: "slug" });
   }
   const definitionChanged = input.definition !== void 0 && JSON.stringify(input.definition) !== JSON.stringify(current.definition);
   const [row] = await db.update(schema.forms).set({

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

@@ -1,8 +1,9 @@
+import { forbidden } from "@frigear-nu/module-kit/server";
 import { resolveAccess } from "../../utils/index.js";
 export async function assertMcpFormAccess(event, form) {
   const { auth } = resolveAccess(form.definition);
   if (auth === "token" || auth === "password") {
-    throw createError({ statusCode: 403, statusMessage: "This form needs its own access token or password and cannot be used through MCP." });
+    throw forbidden("This form needs its own access token or password and cannot be used through MCP.");
   }
   await authorizeFormAccess(event, form);
 }

package/dist/runtime/server/utils/rate-limit.js

@@ -1,3 +1,4 @@
+import { apiError } from "@frigear-nu/module-kit/server";
 import { kv } from "@nuxthub/kv";
 export async function enforceRateLimit(event, slug) {
   const { rateLimit, rateLimitWindowSeconds } = useRuntimeConfig().forms;
@@ -8,7 +9,7 @@ export async function enforceRateLimit(event, slug) {
   const used = Number(await kv.get(key) ?? 0);
   if (used >= rateLimit) {
     setResponseHeader(event, "retry-after", rateLimitWindowSeconds);
-    throw createError({ statusCode: 429, statusMessage: "Too many submissions, try again later." });
+    throw apiError(429, "rate_limited", "Too many submissions, try again later.");
   }
   await kv.set(key, used + 1, { ttl: rateLimitWindowSeconds });
 }
@@ -22,7 +23,7 @@ export async function assertPasswordAttemptsLeft(event, slug) {
   if (!rateLimit) return;
   if (Number(await kv.get(attemptKey(event, slug)) ?? 0) >= rateLimit) {
     setResponseHeader(event, "retry-after", rateLimitWindowSeconds);
-    throw createError({ statusCode: 429, statusMessage: "Too many attempts, try again later." });
+    throw apiError(429, "rate_limited", "Too many attempts, try again later.");
   }
 }
 export async function recordPasswordFailure(event, slug) {

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

@@ -1,4 +1,5 @@
 import type { H3Event } from 'h3';
+import { z } from 'zod';
 import { schema } from '@nuxthub/db';
 type Upload = {
     filename: string;
@@ -12,6 +13,8 @@ export type SubmissionBody = {
     locale: string;
     uploads: Map<string, Upload[]>;
 };
+/** A BCP 47-ish locale tag (`en`, `da`, `en-GB`, `zh-Hant-TW`), as every submission path (HTTP, MCP) accepts it. */
+export declare const submissionLocale: z.ZodString;
 /** Validates and processes one submission for a published form. */
 export declare function processSubmission(event: H3Event, form: FormRow, userId: number | null, body?: SubmissionBody): Promise<{
     ok: true;

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

@@ -1,34 +1,46 @@
+import { z } from "zod";
+import { apiError, validationError } from "@frigear-nu/module-kit/server";
 import { eq } from "drizzle-orm";
 import { db, schema } from "@nuxthub/db";
 import { blob } from "@nuxthub/blob";
 import { buildFormSchema, newId, resolveAccess, resolveCaptcha, validatedFields } from "../../utils/index.js";
 const safeFilename = (name) => name.replace(/[^\w.-]+/g, "_").replace(/^\.+/, "").slice(0, 120) || "file";
+export const submissionLocale = z.string().trim().max(20).regex(/^[a-z]{2,3}(?:-[a-z0-9]{2,8})*$/i, "Invalid locale.");
+const submissionBodySchema = z.object({
+  answers: z.record(z.string(), z.unknown()).default({}),
+  locale: submissionLocale.default("en")
+}).prefault({});
 async function readSubmission(event) {
   const uploads = /* @__PURE__ */ new Map();
   const contentType = getRequestHeader(event, "content-type") ?? "";
   if (contentType.includes("multipart/form-data")) {
     const parts = await readMultipartFormData(event) ?? [];
     let answers = {};
-    let locale = "en";
+    let locale;
     for (const part of parts) {
       if (part.name === "answers") {
         try {
           answers = JSON.parse(part.data.toString("utf8"));
         } catch {
-          throw createError({ statusCode: 400, statusMessage: "Invalid answers." });
+          throw validationError([{ path: ["answers"], message: "Invalid answers." }]);
         }
       } else if (part.name === "locale") {
-        locale = part.data.toString("utf8").slice(0, 20);
+        locale = part.data.toString("utf8");
       } else if (part.name?.startsWith("file:") && part.filename) {
         const key = part.name.slice(5);
         uploads.set(key, [...uploads.get(key) ?? [], { filename: part.filename, type: part.type ?? "application/octet-stream", data: part.data }]);
       }
     }
-    return { answers, locale, uploads };
+    return { ...parseSubmissionBody({ answers, locale }), uploads };
   }
-  const body = await readBody(event);
-  return { answers: body?.answers ?? {}, locale: String(body?.locale ?? "en").slice(0, 20), uploads };
+  return { ...parseSubmissionBody(await readBody(event)), uploads };
 }
+function parseSubmissionBody(input) {
+  const parsed = submissionBodySchema.safeParse(input);
+  if (!parsed.success) throw validationError(toIssues(parsed.error.issues));
+  return parsed.data;
+}
+const toIssues = (issues) => issues.map((issue) => ({ path: issue.path.map((segment) => typeof segment === "symbol" ? String(segment) : segment), message: issue.message }));
 export async function processSubmission(event, form, userId, body) {
   const definition = form.definition;
   const { answers: raw, locale, uploads } = body ?? await readSubmission(event);
@@ -41,11 +53,7 @@ export async function processSubmission(event, form, userId, body) {
   const skipCaptcha = resolveAccess(definition).auth === "token";
   const parsed = buildFormSchema(definition, answers, { locale, skipCaptcha }).safeParse(answers);
   if (!parsed.success) {
-    throw createError({
-      statusCode: 422,
-      statusMessage: "Invalid submission.",
-      data: { issues: parsed.error.issues.map((issue) => ({ path: issue.path, message: issue.message })) }
-    });
+    throw validationError(toIssues(parsed.error.issues));
   }
   const validated = parsed.data;
   for (const field of validatedFields(definition, raw).filter((f) => f.type === "captcha")) {
@@ -54,11 +62,7 @@ export async function processSubmission(event, form, userId, body) {
     Reflect.deleteProperty(answers, field.key);
     if (skipCaptcha) continue;
     if (!await verifyCaptcha(event, resolveCaptcha(field, useRuntimeConfig(event).public.forms?.captcha?.defaultProvider).provider, String(token), form.id)) {
-      throw createError({
-        statusCode: 422,
-        statusMessage: "Invalid submission.",
-        data: { issues: [{ path: [field.key], message: "Captcha verification failed. Please try again." }] }
-      });
+      throw validationError([{ path: [field.key], message: "Captcha verification failed. Please try again." }]);
     }
   }
   const stored = definition.storage !== "none";
@@ -124,7 +128,7 @@ export async function processSubmission(event, form, userId, body) {
       deliveryError: error ?? null
     }).where(eq(schema.formSubmissions.id, submissionId));
   } else if (error) {
-    throw createError({ statusCode: 502, statusMessage: "The submission could not be delivered." });
+    throw apiError(502, "delivery_failed", "The submission could not be delivered.");
   }
   if (ctx.delivered || error) {
     const result = { submissionId, formSlug: form.slug, status: error ? "failed" : "delivered", error };

package/dist/runtime/utils/api.d.ts

@@ -0,0 +1,36 @@
+export declare const formsApi: {
+    /** `GET` a published form's definition. */
+    readonly form: (slug: string) => string;
+    /** `GET` what the public page needs to pick between the form, a gate and "not found". */
+    readonly access: (slug: string) => string;
+    /** `POST` a submission (JSON or multipart). */
+    readonly submit: (slug: string) => string;
+    readonly admin: {
+        /** `GET` (paginated) / `POST` forms. */
+        readonly forms: "/api/admin/forms";
+        /** `POST` an import of form definitions. */
+        readonly import: "/api/admin/forms/import";
+        /** `GET` / `PATCH` / `DELETE` (archive) one form. */
+        readonly form: (id: string) => string;
+        /** `POST` a copy of a form as a new draft. */
+        readonly clone: (id: string) => string;
+        /** `GET` a form's submissions (paginated). */
+        readonly submissions: (formId: string) => string;
+        /** `GET` / `POST` a form's access tokens. */
+        readonly tokens: (formId: string) => string;
+        /** `DELETE` (revoke) one access token. */
+        readonly token: (formId: string, tokenId: string) => string;
+        /** `GET` / `PUT` / `DELETE` a form's shared password. */
+        readonly password: (formId: string) => string;
+        /** `GET` which of a form's secrets are set. */
+        readonly secrets: (formId: string) => string;
+        /** `PUT` / `DELETE` one secret of a form. */
+        readonly secret: (formId: string, key: string) => string;
+        /** `GET` one submission. */
+        readonly submission: (id: string) => string;
+        /** `GET` (download) one uploaded file of a submission. */
+        readonly submissionFile: (id: string, fileId: string) => string;
+        /** `POST` to run delivery of a stored submission again. */
+        readonly redeliver: (id: string) => string;
+    };
+};

package/dist/runtime/utils/api.js

@@ -0,0 +1,39 @@
+const enc = encodeURIComponent;
+const PUBLIC_BASE = "/api/forms";
+const ADMIN_BASE = "/api/admin/forms";
+export const formsApi = {
+  /** `GET` a published form's definition. */
+  form: (slug) => `${PUBLIC_BASE}/${enc(slug)}`,
+  /** `GET` what the public page needs to pick between the form, a gate and "not found". */
+  access: (slug) => `${PUBLIC_BASE}/${enc(slug)}/access`,
+  /** `POST` a submission (JSON or multipart). */
+  submit: (slug) => `${PUBLIC_BASE}/${enc(slug)}/submit`,
+  admin: {
+    /** `GET` (paginated) / `POST` forms. */
+    forms: ADMIN_BASE,
+    /** `POST` an import of form definitions. */
+    import: `${ADMIN_BASE}/import`,
+    /** `GET` / `PATCH` / `DELETE` (archive) one form. */
+    form: (id) => `${ADMIN_BASE}/${enc(id)}`,
+    /** `POST` a copy of a form as a new draft. */
+    clone: (id) => `${ADMIN_BASE}/${enc(id)}/clone`,
+    /** `GET` a form's submissions (paginated). */
+    submissions: (formId) => `${ADMIN_BASE}/${enc(formId)}/submissions`,
+    /** `GET` / `POST` a form's access tokens. */
+    tokens: (formId) => `${ADMIN_BASE}/${enc(formId)}/tokens`,
+    /** `DELETE` (revoke) one access token. */
+    token: (formId, tokenId) => `${ADMIN_BASE}/${enc(formId)}/tokens/${enc(tokenId)}`,
+    /** `GET` / `PUT` / `DELETE` a form's shared password. */
+    password: (formId) => `${ADMIN_BASE}/${enc(formId)}/password`,
+    /** `GET` which of a form's secrets are set. */
+    secrets: (formId) => `${ADMIN_BASE}/${enc(formId)}/secrets`,
+    /** `PUT` / `DELETE` one secret of a form. */
+    secret: (formId, key) => `${ADMIN_BASE}/${enc(formId)}/secrets/${enc(key)}`,
+    /** `GET` one submission. */
+    submission: (id) => `${ADMIN_BASE}/submissions/${enc(id)}`,
+    /** `GET` (download) one uploaded file of a submission. */
+    submissionFile: (id, fileId) => `${ADMIN_BASE}/submissions/${enc(id)}/files/${enc(fileId)}`,
+    /** `POST` to run delivery of a stored submission again. */
+    redeliver: (id) => `${ADMIN_BASE}/submissions/${enc(id)}/redeliver`
+  }
+};

package/dist/runtime/utils/index.d.ts

@@ -24,3 +24,4 @@ export type { PhoneCountry } from './phone.js';
 export { embedMode } from './embed.js';
 export type { EmbedMode } from './embed.js';
 export { isFormOpen, nextFormOpening } from './schedule.js';
+export { formsApi } from './api.js';

package/dist/runtime/utils/index.js

@@ -69,3 +69,4 @@ export {
 } from "./phone.js";
 export { embedMode } from "./embed.js";
 export { isFormOpen, nextFormOpening } from "./schedule.js";
+export { formsApi } from "./api.js";

package/dist/types.d.mts

@@ -4,4 +4,4 @@ export { type Translated } from '@frigear-nu/ui/translated'
 
 export { default } from './module.mjs'
 
-export { type AuthorizeContext, type CaptchaConfig, type CaptchaProvider, type CaptchaVerifyContext, type Condition, type ConditionOp, type CreatedFormAccessTokenDto, type DeliveredContext, type DeliveryStatus, type FieldOption, type FieldType, type FieldValidation, type FileDescriptor, type FormAccess, type FormAccessInfoDto, type FormAccessTokenDto, type FormAdminDto, type FormAuthMode, type FormAvailability, type FormDefinition, type FormDelivery, type FormField, type FormMode, type FormPasswordStatusDto, type FormSecretsDto, type FormStatus, type FormStep, type FormStorage, type FormSubmitSettings, type FormSummaryDto, type FormsRuntimeConfig, type ModuleOptions, type PhoneConfig, type PublicFormDto, type PublicModuleOptions, type SecretSource, type SeedForm, type SubmissionDto, type SubmissionFileDto, type SubmissionSummaryDto, type SubmitResponse, type SubmittedContext, type SubmittedFile } from './module.mjs'
+export { type AuthorizeContext, type CaptchaConfig, type CaptchaProvider, type CaptchaVerifyContext, type Condition, type ConditionOp, type CreatedFormAccessTokenDto, type DeliveredContext, type DeliveryStatus, type FieldOption, type FieldType, type FieldValidation, type FileDescriptor, type FormAccess, type FormAccessInfoDto, type FormAccessTokenDto, type FormAdminDto, type FormAuthMode, type FormAvailability, type FormDefinition, type FormDelivery, type FormField, type FormImportResultDto, type FormMode, type FormPasswordStatusDto, type FormSecretsDto, type FormStatus, type FormStep, type FormStorage, type FormSubmitSettings, type FormSummaryDto, type FormsPage, type FormsRuntimeConfig, type ModuleOptions, type PhoneConfig, type PublicFormDto, type PublicModuleOptions, type SecretSource, type SeedForm, type SubmissionDeliveryDto, type SubmissionDto, type SubmissionFileDto, type SubmissionSummaryDto, type SubmitResponse, type SubmittedContext, type SubmittedFile } from './module.mjs'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frigear-nu/forms",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Dynamic, database-stored forms (single page or stepped) with submissions, file uploads and email delivery for the frigear ecosystem.",
   "homepage": "https://docs.frigear.dev/modules/forms",
   "repository": {
@@ -21,6 +21,11 @@
       "types": "./dist/runtime/utils/index.d.ts",
       "import": "./dist/runtime/utils/index.js",
       "default": "./dist/runtime/utils/index.js"
+    },
+    "./api": {
+      "types": "./dist/runtime/utils/api.d.ts",
+      "import": "./dist/runtime/utils/api.js",
+      "default": "./dist/runtime/utils/api.js"
     }
   },
   "files": [
@@ -30,13 +35,13 @@
     "playground"
   ],
   "dependencies": {
-    "@frigear-nu/admin": "0.1.2",
-    "@frigear-nu/module-kit": "1.1.2",
-    "@frigear-nu/notify": "0.1.2",
-    "@frigear-nu/ui": "0.1.2",
-    "@frigear-nu/auth": "0.1.3",
-    "@frigear-nu/mcp": "0.1.2",
-    "@frigear-nu/users": "1.1.3",
+    "@frigear-nu/admin": "0.1.3",
+    "@frigear-nu/module-kit": "1.1.3",
+    "@frigear-nu/notify": "0.1.3",
+    "@frigear-nu/ui": "0.1.3",
+    "@frigear-nu/auth": "0.1.4",
+    "@frigear-nu/mcp": "0.1.3",
+    "@frigear-nu/users": "1.1.4",
     "@libsql/client": "^0.18.0",
     "@nuxt/kit": "^4.6.1",
     "drizzle-kit": "^0.31.11",
@@ -46,7 +51,7 @@
     "zod": "^4.6.5"
   },
   "peerDependencies": {
-    "@frigear-nu/menu": "0.1.2",
+    "@frigear-nu/menu": "0.1.3",
     "@nuxt/ui": "^4.12.0",
     "@nuxthub/core": "^0.10.8"
   },
@@ -59,7 +64,7 @@
     }
   },
   "devDependencies": {
-    "@frigear-nu/menu": "0.1.2",
+    "@frigear-nu/menu": "0.1.3",
     "@nuxt/devtools": "^3.4.2",
     "@nuxt/eslint-config": "^1.17.0",
     "@nuxt/module-builder": "^1.0.3",

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

@@ -1,12 +0,0 @@
-import { z } from "zod";
-const input = z.object({
-  key: z.string().refine(isFormSecretKey, "Unknown secret key."),
-  value: z.string().trim().min(1).max(2e3)
-});
-export default defineEventHandler(async (event) => {
-  await requireFormsManager(event);
-  const form = await findFormById(getRouterParam(event, "id"));
-  const { key, value } = await readValidatedBody(event, input.parse);
-  await setFormSecret(form.id, key, value);
-  return describeFormSecrets(event, form.id);
-});