@karibsen/eponyme 0.1.1 → 0.3.0

package/dist/runtime/server/services/eponyme-store.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { createDefaultEponymeData } from "../../utils/create-default-eponyme-data.js";
 import { getEponymeCollections, getEponymeSchemas } from "../../utils/get-eponyme-schemas.js";
@@ -6,13 +7,44 @@ import { applyPreviewSlug } from "../../utils/preview.js";
 import { validateEponymeData, validateEponymePatch } from "../../utils/validate-eponyme-data.js";
 export const COLLECTION_METADATA_KEYS = ["updatedAt", "publishedAt", "title", "slug"];
 export class EponymeService {
-  constructor(config, client) {
+  constructor(config, client, options = {}) {
     this.client = client;
     this.schemas = getEponymeSchemas(config);
     this.collections = getEponymeCollections(config);
+    this.cacheMs = Math.max(0, options.cacheSeconds ?? 5) * 1e3;
   }
   schemas;
   collections;
+  /** Entries a read has already persisted the normalized shape for, so it only attempts it once. */
+  healedByRead = /* @__PURE__ */ new Set();
+  /**
+   * Read-path cache of normalized rows, so a page that reads the same entry from a
+   * singleton, a listing and a layout pays one round trip instead of one per read.
+   * Writers never read from it, so the `updatedAt` they lock on always comes from the
+   * database and a stale key can never turn into a spurious conflict.
+   */
+  cache = /* @__PURE__ */ new Map();
+  cacheMs;
+  cached(key, load) {
+    if (!this.cacheMs) return load();
+    const hit = this.cache.get(key);
+    if (hit && hit.expires > Date.now()) return hit.value;
+    const pending = load().catch((error) => {
+      this.cache.delete(key);
+      throw error;
+    });
+    this.cache.set(key, { value: pending, expires: Date.now() + this.cacheMs });
+    return pending;
+  }
+  /**
+   * Drops what a write to `name` invalidates: the entry itself, and the listing of the
+   * collection that contains it, whose row set just changed.
+   */
+  invalidate(name) {
+    this.cache.delete(`row:${name}`);
+    const collection = this.getCollectionEntry(name)?.name;
+    if (collection) this.cache.delete(`rows:${collection}`);
+  }
   getSchema(name) {
     return this.schemas[name] ?? this.getCollectionEntry(name)?.definition.fields;
   }
@@ -27,9 +59,9 @@ export class EponymeService {
       if (slug && !slug.includes("/")) return { name: collectionName, slug, definition };
     }
   }
-  /** Reconcile every configured eponyme at application startup. */
+  /** Reconcile every configured eponyme at application startup. This is the one place that heals. */
   async syncAll() {
-    await Promise.all(Object.keys(this.schemas).map((name) => this.loadState(name)));
+    await Promise.all(Object.keys(this.schemas).map((name) => this.loadState(name, { heal: true })));
   }
   reconcile(schema, value, mode) {
     const persisted = value && typeof value === "object" && !Array.isArray(value) ? value : {};
@@ -65,20 +97,50 @@ export class EponymeService {
       }
     };
   }
-  /** Reads the stored state along with the `updatedAt` it was read at, used as the optimistic lock token. */
-  async loadRow(name) {
+  /**
+   * A singleton row is created on first read, but only when it is genuinely missing.
+   * An `upsert` would send a write on every read instead, and each one costs a database
+   * round trip on the critical path of a public page.
+   */
+  async loadSingletonRow(name, schema) {
+    const row = await this.client.eponyme.findUnique({ where: { name } });
+    if (row) return row;
+    try {
+      return await this.client.eponyme.create({ data: { name, data: this.createState(schema) } });
+    } catch (error) {
+      if (isPrismaError(error, "P2002")) return await this.client.eponyme.findUnique({ where: { name } });
+      throw error;
+    }
+  }
+  /**
+   * Reads the stored state along with the `updatedAt` it was read at, used as the optimistic lock token.
+   *
+   * `heal` persists the normalized state when it differs from what is stored. It has to stay on for
+   * writers, because healing moves `updatedAt` and so decides the lock token they are about to compare.
+   *
+   * `cache` is only ever set for published content. Draft reads serve the preview panel, which has to
+   * show a save immediately, and they come from the dashboard rather than from a public page — so
+   * there is nothing to gain by caching them and a stale preview to lose.
+   */
+  async loadRow(name, { heal = false, cache = false } = {}) {
+    if (!cache || heal) return await this.readRow(name, heal);
+    return await this.cached(`row:${name}`, () => this.readRow(name, false));
+  }
+  async readRow(name, heal) {
     const schema = this.getSchema(name);
     if (!schema) return void 0;
-    const defaults = this.createState(schema);
-    const row = this.getCollectionEntry(name) ? await this.client.eponyme.findUnique({ where: { name } }) : await this.client.eponyme.upsert({ where: { name }, create: { name, data: defaults }, update: {} });
-    if (!row) return void 0;
+    const row = this.getCollectionEntry(name) ? await this.client.eponyme.findUnique({ where: { name } }) : await this.loadSingletonRow(name, schema);
+    if (!row || row.deletedAt) return void 0;
     const state = this.normalizeState(schema, row.data);
     if (sameData(state, row.data)) return { state, updatedAt: row.updatedAt };
+    if (!heal && this.healedByRead.has(name)) return { state, updatedAt: row.updatedAt };
+    this.healedByRead.add(name);
     const healed = await this.client.eponyme.update({ where: { name }, data: { data: state } });
+    this.invalidate(name);
     return { state, updatedAt: healed.updatedAt ?? row.updatedAt };
   }
-  async loadState(name) {
-    return (await this.loadRow(name))?.state;
+  async loadState(name, options = {}) {
+    return (await this.loadRow(name, options))?.state;
   }
   /**
    * Writes a new state only if the row still carries the `updatedAt` we read.
@@ -87,19 +149,38 @@ export class EponymeService {
    */
   async writeState(name, next, expectedUpdatedAt) {
     const data = next;
-    if (!expectedUpdatedAt) {
-      await this.client.eponyme.update({ where: { name }, data: { data } });
-      return true;
+    try {
+      if (!expectedUpdatedAt) {
+        await this.client.eponyme.update({ where: { name }, data: { data } });
+        return true;
+      }
+      const { count } = await this.client.eponyme.updateMany({ where: { name, updatedAt: expectedUpdatedAt }, data: { data } });
+      return count > 0;
+    } finally {
+      this.invalidate(name);
     }
-    const { count } = await this.client.eponyme.updateMany({ where: { name, updatedAt: expectedUpdatedAt }, data: { data } });
-    return count > 0;
+  }
+  /**
+   * The live rows of a collection, shared by the public listing and the sitemap so both
+   * read them once. The trash and the export deliberately query around it: one wants the
+   * rows this filter excludes, the other must not see a cached view of the content.
+   */
+  async liveCollectionRows(name, cache = false) {
+    const load = () => this.client.eponyme.findMany({
+      where: { name: { startsWith: `${name}/` }, deletedAt: null },
+      orderBy: [
+        { updatedAt: "desc" },
+        { name: "asc" }
+      ]
+    });
+    return cache ? await this.cached(`rows:${name}`, load) : await load();
   }
   async get(name, version = "published") {
     return (await this.getResult(name, version))?.data;
   }
   async getResult(name, version = "published") {
     if (typeof version === "number") return this.getVersionResult(name, version);
-    const state = await this.loadState(name);
+    const state = await this.loadState(name, { cache: version === "published" });
     if (!state) return void 0;
     if (version === "published" && this.getCollectionEntry(name) && !state.__eponyme.publishedAt) return void 0;
     return {
@@ -137,25 +218,20 @@ export class EponymeService {
   async listCollection(name, version = "published", query = {}) {
     const definition = this.collections[name];
     if (!definition) return void 0;
-    const rows = await this.client.eponyme.findMany({
-      where: { name: { startsWith: `${name}/` } },
-      orderBy: [
-        { updatedAt: "desc" },
-        { name: "asc" }
-      ]
-    });
-    const entries = await Promise.all(rows.filter((row) => !row.name.slice(name.length + 1).includes("/")).map(async (row) => {
+    const rows = await this.liveCollectionRows(name, version === "published");
+    const entries = rows.flatMap((row) => {
       const slug = row.name.slice(name.length + 1);
-      const result = await this.getResult(row.name, version);
-      return {
+      if (!slug || slug.includes("/")) return [];
+      const state = this.normalizeState(definition.fields, row.data);
+      return [{
         slug,
-        title: String(result?.data[definition.titleField] || slug),
-        data: result?.data ?? {},
-        status: version === "published" ? "published" : result?.status ?? "draft",
-        publishedAt: result?.publishedAt ?? null,
+        title: String(state.__eponyme[version][definition.titleField] || slug),
+        data: state.__eponyme[version],
+        status: version === "published" ? "published" : state.__eponyme.status,
+        publishedAt: state.__eponyme.publishedAt,
         updatedAt: row.updatedAt ? new Date(row.updatedAt).toISOString() : null
-      };
-    }));
+      }];
+    });
     const visible = version === "draft" ? entries : entries.filter((entry) => entry.publishedAt);
     const sorted = query.orderBy ? sortCollectionEntries(visible, query.orderBy, query.order ?? "desc") : visible;
     const skip = Math.max(0, Math.trunc(query.skip ?? 0) || 0);
@@ -180,13 +256,7 @@ export class EponymeService {
       }
       if (!path.includes(":slug"))
         throw new Error(`[Eponyme] previewPaths.${name} must include ":slug" to generate collection sitemap URLs.`);
-      const rows = await this.client.eponyme.findMany({
-        where: { name: { startsWith: `${name}/` } },
-        orderBy: [
-          { updatedAt: "desc" },
-          { name: "asc" }
-        ]
-      });
+      const rows = await this.liveCollectionRows(name, true);
       return rows.flatMap((row) => {
         const slug = row.name.slice(name.length + 1);
         if (!slug || slug.includes("/")) return [];
@@ -200,6 +270,109 @@ export class EponymeService {
       entries.set(entry.loc, entry);
     return [...entries.values()];
   }
+  /**
+   * Every singleton and every live collection entry, as a portable file.
+   * Collections are read with one query each rather than one per entry.
+   */
+  async exportContent() {
+    const schemas = {};
+    const entries = [];
+    for (const [name, schema] of Object.entries(this.schemas)) {
+      schemas[name] = schemaFingerprint(schema);
+      const row = await this.loadRow(name);
+      if (row) entries.push({ name, ...toExportEntry(row.state) });
+    }
+    for (const [name, definition] of Object.entries(this.collections)) {
+      schemas[name] = schemaFingerprint(definition.fields);
+      const rows = await this.client.eponyme.findMany({
+        where: { name: { startsWith: `${name}/` }, deletedAt: null },
+        orderBy: [
+          { updatedAt: "desc" },
+          { name: "asc" }
+        ]
+      });
+      for (const row of rows) {
+        const slug = row.name.slice(name.length + 1);
+        if (!slug || slug.includes("/")) continue;
+        entries.push({ name: row.name, collection: name, ...toExportEntry(this.normalizeState(definition.fields, row.data)) });
+      }
+    }
+    return {
+      eponyme: { format: 1, exportedAt: (/* @__PURE__ */ new Date()).toISOString(), schemas },
+      entries
+    };
+  }
+  /**
+   * Applies an export file on top of the current content: every entry it carries is
+   * upserted, everything else is left alone. Nothing is ever deleted.
+   *
+   * The schema check runs first and refuses the whole file, so an import can never
+   * land half of its entries into a configuration that no longer matches.
+   */
+  async importContent(file, options = {}) {
+    const parsed = parseExportFile(file);
+    if (!parsed) return { errors: ["This file is not an Eponyme export."] };
+    const declared = parsed.eponyme.schemas;
+    const mismatch = Object.keys(declared).filter((name) => {
+      const local = this.schemas[name] ?? this.collections[name]?.fields;
+      return !local || schemaFingerprint(local) !== declared[name];
+    });
+    for (const entry of parsed.entries) {
+      const owner = entry.collection ?? this.getCollectionEntry(entry.name)?.name ?? entry.name;
+      if (!(owner in declared) && !mismatch.includes(owner)) mismatch.push(owner);
+    }
+    if (mismatch.length) {
+      return {
+        errors: ["The exported schema does not match this application's configuration."],
+        schemaMismatch: mismatch
+      };
+    }
+    const result = { dryRun: Boolean(options.dryRun), created: 0, updated: 0, skipped: [] };
+    for (const entry of parsed.entries) {
+      const collectionEntry = this.getCollectionEntry(entry.name);
+      const schema = this.schemas[entry.name] ?? collectionEntry?.definition.fields;
+      if (!schema) {
+        result.skipped.push({ name: entry.name, reason: "No schema is configured for this entry." });
+        continue;
+      }
+      const row = await this.client.eponyme.findUnique({ where: { name: entry.name } });
+      if (row?.deletedAt) {
+        result.skipped.push({ name: entry.name, reason: "An entry with this name is in the trash. Restore it or delete it permanently first." });
+        continue;
+      }
+      const state = this.normalizeState(schema, {
+        __eponyme: {
+          version: 1,
+          draft: entry.draft,
+          published: entry.published,
+          status: entry.status,
+          publishedAt: entry.publishedAt
+        }
+      });
+      if (collectionEntry) {
+        const { slugField } = collectionEntry.definition;
+        if (slugField in state.__eponyme.draft) state.__eponyme.draft[slugField] = collectionEntry.slug;
+        if (slugField in state.__eponyme.published) state.__eponyme.published[slugField] = collectionEntry.slug;
+      }
+      if (!options.dryRun) {
+        const data = state;
+        await this.client.eponyme.upsert({ where: { name: entry.name }, create: { name: entry.name, data }, update: { data } });
+        this.invalidate(entry.name);
+        await this.client.eponymeVersion.create({
+          data: {
+            entryName: entry.name,
+            data,
+            action: "import",
+            status: state.__eponyme.status,
+            userId: options.actorId ?? null
+          }
+        });
+      }
+      if (row) result.updated++;
+      else result.created++;
+    }
+    return result;
+  }
   async createCollectionEntry(name, payload, actorId) {
     const definition = this.collections[name];
     if (!definition) return void 0;
@@ -210,8 +383,8 @@ export class EponymeService {
     const slug = normalizeSlug(String(input[definition.slugField] || input[definition.titleField] || ""));
     if (!slug) return { errors: { [definition.slugField]: ["A slug or title is required."] } };
     const entryName = `${name}/${slug}`;
-    if (await this.client.eponyme.findUnique({ where: { name: entryName } }))
-      return { errors: { [definition.slugField]: ["This slug is already in use."] } };
+    const taken = await this.slugTakenError(definition, entryName);
+    if (taken) return taken;
     const defaults = createDefaultEponymeData(definition.fields);
     const data = { ...defaults, ...input, [definition.slugField]: slug };
     const errors = validateEponymePatch(definition.fields, data, data, "draft");
@@ -227,27 +400,91 @@ export class EponymeService {
     };
     try {
       await this.client.eponyme.create({ data: { name: entryName, data: state } });
+      this.invalidate(entryName);
     } catch (error) {
-      if (isPrismaError(error, "P2002")) return { errors: { [definition.slugField]: ["This slug is already in use."] } };
+      if (isPrismaError(error, "P2002")) return await this.slugTakenError(definition, entryName) ?? { errors: { [definition.slugField]: ["This slug is already in use."] } };
       throw error;
     }
     await this.client.eponymeVersion.create({ data: { entryName, data: state, action: "draft", status: "draft", userId: actorId ?? null } });
     return { slug, data, status: "draft", publishedAt: null };
   }
+  /**
+   * A trashed entry keeps its row, so it keeps its slug: reusing one has to be
+   * refused with an error the editor can act on rather than the generic message.
+   */
+  async slugTakenError(definition, entryName) {
+    const row = await this.client.eponyme.findUnique({ where: { name: entryName } });
+    if (!row) return void 0;
+    return {
+      errors: {
+        [definition.slugField]: [row.deletedAt ? "An entry with this slug is in the trash. Restore it or delete it permanently first." : "This slug is already in use."]
+      }
+    };
+  }
+  /** Moves an entry to the trash. Its history is kept, so it stays restorable. */
   async deleteCollectionEntry(name) {
     if (!this.getCollectionEntry(name)) return false;
+    const { count } = await this.client.eponyme.updateMany({
+      where: { name, deletedAt: null },
+      data: { deletedAt: /* @__PURE__ */ new Date() }
+    });
+    this.invalidate(name);
+    return count > 0;
+  }
+  async restoreCollectionEntry(name) {
+    if (!this.getCollectionEntry(name)) return false;
+    const { count } = await this.client.eponyme.updateMany({
+      where: { name, deletedAt: { not: null } },
+      data: { deletedAt: null }
+    });
+    this.invalidate(name);
+    return count > 0;
+  }
+  /** Definitive: `onDelete: Cascade` takes the entry's whole history with it. */
+  async purgeCollectionEntry(name) {
+    if (!this.getCollectionEntry(name)) return false;
+    const row = await this.client.eponyme.findUnique({ where: { name } });
+    if (!row?.deletedAt) return false;
     try {
       await this.client.eponyme.delete({ where: { name } });
+      this.invalidate(name);
     } catch (error) {
       if (isPrismaError(error, "P2025")) return false;
       throw error;
     }
     return true;
   }
+  /** Trashed entries of a collection, most recently updated first. */
+  async listCollectionTrash(name) {
+    const definition = this.collections[name];
+    if (!definition) return void 0;
+    const rows = await this.client.eponyme.findMany({
+      where: { name: { startsWith: `${name}/` }, deletedAt: { not: null } },
+      orderBy: [
+        { updatedAt: "desc" },
+        { name: "asc" }
+      ]
+    });
+    const entries = rows.flatMap((row) => {
+      const slug = row.name.slice(name.length + 1);
+      if (!slug || slug.includes("/")) return [];
+      const state = this.normalizeState(definition.fields, row.data);
+      return [{
+        slug,
+        title: String(state.__eponyme.draft[definition.titleField] || slug),
+        data: state.__eponyme.draft,
+        status: state.__eponyme.status,
+        publishedAt: state.__eponyme.publishedAt,
+        updatedAt: row.updatedAt ? new Date(row.updatedAt).toISOString() : null,
+        deletedAt: row.deletedAt ? new Date(row.deletedAt).toISOString() : null
+      }];
+    });
+    return { entries, total: entries.length };
+  }
   async patch(name, payload, action = "publish", actorId) {
     const schema = this.getSchema(name);
     if (!schema) return void 0;
-    const row = await this.loadRow(name);
+    const row = await this.loadRow(name, { heal: true });
     if (!row) return void 0;
     const { state, updatedAt } = row;
     if (!payload || typeof payload !== "object" || Array.isArray(payload)) return { errors: { _form: ["Body must be an object."] } };
@@ -293,7 +530,7 @@ export class EponymeService {
     });
     return versions.map((version) => ({
       id: version.id,
-      action: version.action === "draft" || version.action === "publish" ? version.action : "restore",
+      action: isHistoryAction(version.action) ? version.action : "restore",
       status: version.status === "draft" ? "draft" : "published",
       createdAt: new Date(version.createdAt).toISOString(),
       user: version.user ? { id: version.user.id, username: version.user.username } : null
@@ -304,7 +541,7 @@ export class EponymeService {
     if (!schema) return void 0;
     const version = await this.client.eponymeVersion.findUnique({ where: { id: versionId } });
     if (!version || version.entryName !== name) return void 0;
-    const current = await this.loadRow(name);
+    const current = await this.loadRow(name, { heal: true });
     if (!current) return void 0;
     const state = this.normalizeState(schema, version.data);
     if (!await this.writeState(name, state, current.updatedAt)) return { conflict: true };
@@ -333,6 +570,68 @@ function getStoredState(value) {
   );
   return valid ? state : void 0;
 }
+function isHistoryAction(action) {
+  return action === "draft" || action === "publish" || action === "import";
+}
+function toExportEntry(state) {
+  return {
+    draft: state.__eponyme.draft,
+    published: state.__eponyme.published,
+    status: state.__eponyme.status,
+    publishedAt: state.__eponyme.publishedAt
+  };
+}
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function describeSchema(schema) {
+  const fields = schema;
+  return Object.keys(fields).sort().map((key) => `${key}:${describeField(fields[key])}`).join(",");
+}
+function describeField(field) {
+  if (!isPlainObject(field) || typeof field.type !== "string") return "unknown";
+  const options = isPlainObject(field.options) ? field.options : {};
+  if (field.type === "array") {
+    const item = isPlainObject(options.of) ? options.of : {};
+    return `array(${typeof item.type === "string" ? describeField(item) : describeSchema(item)})`;
+  }
+  if (field.type === "section")
+    return `section(${describeSchema(isPlainObject(options.fields) ? options.fields : {})})`;
+  if (field.type === "tabs") {
+    const tabs = isPlainObject(options.tabs) ? options.tabs : {};
+    return `tabs(${Object.keys(tabs).sort().map((key) => {
+      const tab = tabs[key];
+      return `${key}:${describeSchema(isPlainObject(tab) && isPlainObject(tab.fields) ? tab.fields : {})}`;
+    }).join(",")})`;
+  }
+  return field.type;
+}
+export function schemaFingerprint(schema) {
+  return createHash("sha256").update(describeSchema(schema)).digest("hex").slice(0, 32);
+}
+function parseExportFile(value) {
+  if (!isPlainObject(value)) return void 0;
+  const envelope = value.eponyme;
+  if (!isPlainObject(envelope) || envelope.format !== 1 || !isPlainObject(envelope.schemas)) return void 0;
+  if (!Object.values(envelope.schemas).every((fingerprint) => typeof fingerprint === "string")) return void 0;
+  if (!Array.isArray(value.entries)) return void 0;
+  const entries = [];
+  for (const entry of value.entries) {
+    if (!isPlainObject(entry)) return void 0;
+    const { name, collection, draft, published, status, publishedAt } = entry;
+    const valid = typeof name === "string" && name.length > 0 && isPlainObject(draft) && isPlainObject(published) && (status === "draft" || status === "published") && (publishedAt === null || typeof publishedAt === "string") && (collection === void 0 || typeof collection === "string");
+    if (!valid) return void 0;
+    entries.push({ name, collection, draft, published, status, publishedAt });
+  }
+  return {
+    eponyme: {
+      format: 1,
+      exportedAt: typeof envelope.exportedAt === "string" ? envelope.exportedAt : (/* @__PURE__ */ new Date()).toISOString(),
+      schemas: envelope.schemas
+    },
+    entries
+  };
+}
 function mergeErrors(...groups) {
   const errors = {};
   for (const group of groups) {

package/dist/runtime/server/utils/eponyme-captcha.d.ts

@@ -0,0 +1,6 @@
+import type { H3Event } from 'h3';
+import type { EponymeCaptchaResult, EponymeCaptchaVerifier } from '../../types/captcha.js';
+export declare const CAPTCHA_TOKEN_KEY = "_eponyme_captcha";
+export declare function eponymeCaptchaVerifier(): EponymeCaptchaVerifier;
+export declare function isEponymeCaptchaConfigured(): boolean;
+export declare function verifyEponymeCaptcha(event: H3Event, token: unknown): Promise<EponymeCaptchaResult>;

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

@@ -0,0 +1,14 @@
+import { getRequestIP } from "h3";
+import captchaVerifier from "#eponyme/captcha";
+export const CAPTCHA_TOKEN_KEY = "_eponyme_captcha";
+export function eponymeCaptchaVerifier() {
+  return captchaVerifier;
+}
+export function isEponymeCaptchaConfigured() {
+  return eponymeCaptchaVerifier().name !== "none";
+}
+export async function verifyEponymeCaptcha(event, token) {
+  if (typeof token !== "string" || !token.trim())
+    return { success: false, reason: "Missing captcha token." };
+  return eponymeCaptchaVerifier().verify(token, { ip: getRequestIP(event, { xForwardedFor: true }) });
+}

package/dist/runtime/server/utils/eponyme-entry.d.ts

@@ -0,0 +1,9 @@
+import type { EponymeService } from '../services/eponyme-store.js';
+/**
+ * Splits `<collection>/<slug>` when the name belongs to a configured collection, so
+ * hook listeners can branch on the collection without re-parsing the name themselves.
+ */
+export declare function splitEponymeCollectionEntry(service: EponymeService, name: string): {
+    name: string;
+    slug: string;
+} | undefined;

package/dist/runtime/server/utils/eponyme-entry.js

@@ -0,0 +1,7 @@
+export function splitEponymeCollectionEntry(service, name) {
+  const separator = name.lastIndexOf("/");
+  if (separator <= 0) return void 0;
+  const collection = name.slice(0, separator);
+  const slug = name.slice(separator + 1);
+  return slug && service.getCollection(collection) ? { name: collection, slug } : void 0;
+}

package/dist/runtime/server/utils/eponyme-hooks.d.ts

@@ -0,0 +1,16 @@
+import type { EponymeHooks } from '../../types/hooks.js';
+type HookName = keyof EponymeHooks;
+type HookContext<Name extends HookName> = Parameters<EponymeHooks[Name]>[0];
+/**
+ * Notification hooks. The write already happened, so a listener that throws is
+ * logged and swallowed: a failing webhook must not report a successful save as an
+ * error the editor cannot act on.
+ */
+export declare function callEponymeHook<Name extends Exclude<HookName, `${string}before${string}`>>(name: Name, context: HookContext<Name>): Promise<void>;
+/**
+ * Blocking hooks, run before the write. A listener may mutate `context.data` to amend
+ * the payload, or throw to reject the operation — the error surfaces as a 422 so the
+ * message reaches the editor.
+ */
+export declare function callEponymeBlockingHook<Name extends Extract<HookName, `${string}before${string}`>>(name: Name, context: HookContext<Name>): Promise<void>;
+export {};

package/dist/runtime/server/utils/eponyme-hooks.js

@@ -0,0 +1,24 @@
+import { createError } from "h3";
+import { useNitroApp } from "nitropack/runtime";
+function hooks() {
+  return useNitroApp().hooks;
+}
+export async function callEponymeHook(name, context) {
+  try {
+    await hooks().callHook(name, context);
+  } catch (error) {
+    console.error(`[Eponyme] The "${name}" hook threw. The operation itself succeeded.`, error);
+  }
+}
+export async function callEponymeBlockingHook(name, context) {
+  try {
+    await hooks().callHook(name, context);
+  } catch (error) {
+    if (error && typeof error === "object" && "statusCode" in error) throw error;
+    throw createError({
+      statusCode: 422,
+      statusMessage: error instanceof Error ? error.message : `Rejected by the "${name}" hook.`,
+      data: { errors: { _form: [error instanceof Error ? error.message : "Rejected by a server hook."] } }
+    });
+  }
+}

package/dist/runtime/types/captcha.d.ts

@@ -0,0 +1,16 @@
+export interface EponymeCaptchaResult {
+    success: boolean;
+    /** Provider-specific reason, surfaced in server logs rather than to the visitor. */
+    reason?: string;
+}
+/**
+ * Verifies the token a visitor's captcha widget produced. Implemented by an adapter
+ * package such as `@karibsen/eponyme-captcha`; the core ships none, so a project
+ * without an adapter simply has no captcha.
+ */
+export interface EponymeCaptchaVerifier {
+    name: string;
+    verify: (token: string, context: {
+        ip?: string;
+    }) => Promise<EponymeCaptchaResult>;
+}

package/dist/runtime/types/eponyme-config.d.ts

@@ -16,3 +16,10 @@ declare module '#eponyme/variables' {
   const variables: EponymeVariables
   export default variables
 }
+
+declare module '#eponyme/captcha' {
+  import type { EponymeCaptchaVerifier } from './captcha'
+
+  const verifier: EponymeCaptchaVerifier
+  export default verifier
+}

package/dist/runtime/types/eponyme.d.ts

@@ -42,6 +42,8 @@ export interface EponymeFormOptions<T extends EponymeFormSchema = EponymeFormSch
     honeypot?: string | false;
     /** In bytes. */
     maxBodyBytes?: number;
+    /** Requires a valid captcha token. Needs an adapter such as `@karibsen/eponyme-captcha`. */
+    captcha?: boolean;
 }
 export interface EponymeFormDefinitionBase {
     __eponymeForm: true;
@@ -51,6 +53,7 @@ export interface EponymeFormDefinitionBase {
     submission: Required<EponymeFormSubmissionOptions>;
     honeypot: string | false;
     maxBodyBytes: number;
+    captcha: boolean;
 }
 export interface EponymeFormDefinition<T extends EponymeFormSchema = EponymeFormSchema> extends EponymeFormDefinitionBase {
     fields: T;

package/dist/runtime/types/field.d.ts

@@ -70,6 +70,7 @@ export interface UrlValue {
     href: string;
     type: UrlType;
     openInNewTab: boolean;
+    download?: boolean;
 }
 export interface UrlFieldOptions extends DefaultFieldOptions<UrlValue> {
     placeholder?: string;