@easy-cms/core 1.14.0 → 1.15.1

package/dist/{chunk-Q7MVE3BT.js → chunk-Q3QLUBFK.js}

@@ -35,7 +35,7 @@ import {
   warnDeprecated,
   withCharset,
   withPrivacy
-} from "./chunk-RTKWMVAC.js";
+} from "./chunk-SKGKGKUN.js";
 
 // src/access.ts
 var isSystemAdmin = (user) => user?.role === "admin" && !user.apiKey && user.scoped !== true;
@@ -2314,7 +2314,10 @@ var ADAPTER_API_VERSION = 1;
 
 // src/document.ts
 import { randomUUID } from "crypto";
-var EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+function isEmail(value) {
+  const at = value.indexOf("@");
+  return at > 0 && !value.includes("@", at + 1) && !/\s/.test(value) && value.slice(at + 2, -1).includes(".");
+}
 var isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 function itemsOf(field, n) {
   const unit = field.type === "upload" ? "file" : field.type === "relationship" ? "document" : "row";
@@ -2522,8 +2525,7 @@ async function normalizeValue(field, raw, path, options, fail, errors, reference
       return raw;
     }
     case "email": {
-      if (typeof raw !== "string" || !EMAIL_PATTERN.test(raw))
-        return fail("must be a valid email address");
+      if (typeof raw !== "string" || !isEmail(raw)) return fail("must be a valid email address");
       return raw.trim().toLowerCase();
     }
     case "number": {
@@ -3377,6 +3379,10 @@ function errorFields(error) {
     return { name: error.name, message: error.message, stack: error.stack };
   return { message: String(error) };
 }
+var traceIds;
+function setTraceIds(read2) {
+  traceIds = read2;
+}
 function jsonLogger(write = (line, level) => (level === "info" ? process.stdout : process.stderr).write(`${line}
 `)) {
   const log = (level) => (message2, details) => {
@@ -3389,6 +3395,7 @@ function jsonLogger(write = (line, level) => (level === "info" ? process.stdout
       message: message2,
       ...store2?.requestId ? { requestId: store2.requestId } : {},
       ...store2?.runId ? { runId: store2.runId } : {},
+      ...traceIds?.(),
       ...rest,
       ...error === void 0 ? {} : { error: errorFields(error) }
     };
@@ -3730,6 +3737,7 @@ async function populate(load, collections, fields, docs, depth) {
 }
 function collectSlots(fields, data, bySlug, slots) {
   for (const field of fields) {
+    if (field.name === "__proto__") continue;
     const value = data[field.name];
     if (value === null || value === void 0) continue;
     if (field.type === "group") {
@@ -4435,7 +4443,10 @@ for (const [net, prefix] of [
   ["::1", 128],
   ["64:ff9b:1::", 48],
   ["100::", 64],
+  // Teredo and 6to4 tunnel to an IPv4 address the IPv6 one carries: any of them, private too.
+  ["2001::", 32],
   ["2001:db8::", 32],
+  ["2002::", 16],
   ["fc00::", 7],
   ["fe80::", 10],
   ["ff00::", 8]
@@ -4637,7 +4648,7 @@ function read(response, maxBytes, deadline) {
 var keys = (list) => new Set(list.split(/\s+/).filter(Boolean));
 var CONFIG = keys(`secret db serverURL cors cronSecret timeZone webhooks events jobs localization routes admin
   upload auth collections globals endpoints cliCommands onRequest fieldTypes apiKeys email backups
-  audit logs countCacheSeconds maxPage httpCache outbox search plugins`);
+  audit logs countCacheSeconds maxPage httpCache outbox search telemetry plugins`);
 var ADMIN = keys("path locale brand siteURL nav commands modules pages dashboard switcher");
 var AUTH = keys(`roles rbac tokenExpiration maxLoginAttempts lockWindow trustedOrigins
   resetPasswordExpiration inviteExpiration providers providerSignUp password setupCode members emails`);
@@ -5383,6 +5394,7 @@ function validateConfig(config) {
   validateCountCache(config, add);
   validateOutbox(config, add);
   validateSearch(config, add);
+  validateTelemetry(config, add);
   validateMaxPage(config, add);
   validateHttpCache(config, add);
   validateAuth(config, add);
@@ -6036,6 +6048,18 @@ function validateOutbox(config, add) {
   if (config.outbox !== void 0 && typeof config.outbox !== "boolean")
     add("outbox", "must be true or false");
 }
+function validateTelemetry(config, add) {
+  const value = config.telemetry;
+  if (value === void 0 || typeof value === "boolean") return;
+  if (typeof value !== "object" || value === null) {
+    add("telemetry", "must be true, false or { traces, metrics }");
+    return;
+  }
+  for (const [key, v] of Object.entries(value))
+    if (key !== "traces" && key !== "metrics")
+      add(`telemetry.${key}`, "is not an option", "traces or metrics");
+    else if (typeof v !== "boolean") add(`telemetry.${key}`, "must be true or false");
+}
 function validateSearch(config, add) {
   const adapter = config.search;
   if (adapter !== void 0) {
@@ -6388,6 +6412,15 @@ function validateFields2(fields, path, reserved, collectionSlugs, add) {
       add(`${path}[${i}].name`, `must be a valid identifier (got ${JSON.stringify(name)})`);
       return;
     }
+    if (name === "__proto__") {
+      add(`${path}[${i}].name`, '"__proto__" is reserved by JavaScript');
+      return;
+    }
+    if (name === "constructor" || name === "prototype")
+      warnDeprecated(
+        "EASY_CMS_DEP006",
+        `A field named "${name}" (${path}.${name}) works through 1.x; rename it before 2.0.`
+      );
     if (reserved.has(name)) {
       add(`${path}.${name}`, `"${name}" is reserved`, "Easy CMS adds this field automatically");
     }
@@ -7011,6 +7044,201 @@ function cacheableResponse(request, body, status, headers, times, tags) {
   return new Response(request.method.toUpperCase() === "HEAD" ? null : body, { status, headers });
 }
 
+// src/version.ts
+var VERSION = true ? "1.15.1" : "0.0.0-dev";
+
+// src/telemetry.ts
+var DB_CALLS = /* @__PURE__ */ new Set([
+  "find",
+  "findPage",
+  "findAfter",
+  "findById",
+  "findByIds",
+  "count",
+  "create",
+  "update",
+  "increment",
+  "delete",
+  "findGlobal",
+  "updateGlobal"
+]);
+var Telemetry = class _Telemetry {
+  constructor(api, traces, metrics) {
+    this.api = api;
+    this.tracer = traces ? api.trace.getTracer("easy-cms", VERSION) : void 0;
+    if (metrics) {
+      const meter = api.metrics.getMeter("easy-cms", VERSION);
+      this.httpDuration = meter.createHistogram("http.server.request.duration", {
+        unit: "s",
+        description: "Duration of API requests"
+      });
+      this.dbDuration = meter.createHistogram("db.client.operation.duration", {
+        unit: "s",
+        description: "Duration of database calls"
+      });
+      this.jobRuns = meter.createCounter("easy_cms.jobs.runs", {
+        description: "Runs of the config\u2019s jobs, by job and result"
+      });
+      this.jobDuration = meter.createHistogram("easy_cms.jobs.duration", {
+        unit: "s",
+        description: "Duration of the config\u2019s jobs"
+      });
+      meter.createObservableGauge("easy_cms.queue.size", {
+        description: "Background work waiting or failed, as of the last job run"
+      }).addCallback((result) => {
+        for (const [queue, sizes] of Object.entries(this.queues))
+          for (const state of ["pending", "failed"])
+            result.observe(sizes[state], { queue, state });
+      });
+      meter.createObservableGauge("easy_cms.scheduled.late", {
+        description: "Scheduled publishes more than 10 minutes late, as of the last job run"
+      }).addCallback((result) => result.observe(this.late));
+    }
+    if (traces)
+      setTraceIds(() => {
+        const context = api.trace.getActiveSpan()?.spanContext();
+        return context && api.isSpanContextValid(context) ? { traceId: context.traceId, spanId: context.spanId } : void 0;
+      });
+  }
+  api;
+  tracer;
+  httpDuration;
+  dbDuration;
+  jobRuns;
+  jobDuration;
+  queues = {};
+  late = 0;
+  /** `undefined` without `telemetry`; throws when `@opentelemetry/api` isn't installed. */
+  static async load(config) {
+    if (!config) return void 0;
+    const { traces = true, metrics = true } = config === true ? {} : config;
+    if (!traces && !metrics) return void 0;
+    let api;
+    try {
+      api = await import("@opentelemetry/api");
+    } catch {
+      throw new ConfigError([
+        {
+          path: "telemetry",
+          message: "needs @opentelemetry/api",
+          hint: "npm install @opentelemetry/api, and set up the OpenTelemetry SDK in your app"
+        }
+      ]);
+    }
+    return new _Telemetry(api, traces, metrics);
+  }
+  /** Runs `fn` in a span; with traces off, just runs it. Errors mark the span and go on. */
+  async span(name, attributes, fn, kind = "internal") {
+    if (!this.tracer) return fn(void 0);
+    const spanKind = { internal: 0, server: 1, client: 2 }[kind];
+    return this.tracer.startActiveSpan(name, { kind: spanKind, attributes }, async (span) => {
+      try {
+        return await fn(span);
+      } catch (error) {
+        span.setStatus({ code: this.api.SpanStatusCode.ERROR });
+        span.setAttribute("error.type", errorType(error));
+        throw error;
+      } finally {
+        span.end();
+      }
+    });
+  }
+  /**
+   * An API request: a server span when nothing traces it yet (`easy-cms serve`), else a span
+   * inside the framework's (Next.js, Nuxt with an SDK).
+   */
+  async request(method, route2, fn) {
+    const started = performance.now();
+    const kind = this.api.trace.getActiveSpan() ? "internal" : "server";
+    const attributes = { "http.request.method": method, "http.route": route2 };
+    let status = 500;
+    try {
+      return await this.span(
+        `easy-cms ${method} ${route2}`,
+        attributes,
+        async (span) => {
+          const response = await fn();
+          status = response.status;
+          span?.setAttribute("http.response.status_code", status);
+          if (status >= 500) span?.setStatus({ code: this.api.SpanStatusCode.ERROR });
+          return response;
+        },
+        kind
+      );
+    } finally {
+      this.httpDuration?.record((performance.now() - started) / 1e3, {
+        ...attributes,
+        "http.response.status_code": status
+      });
+    }
+  }
+  /** The database with a client span and a duration per call (`db <call> <collection>`). */
+  database(db, system2) {
+    return new Proxy(db, {
+      get: (target, key, receiver) => {
+        const value = Reflect.get(target, key, receiver);
+        if (typeof key !== "string" || !DB_CALLS.has(key) || typeof value !== "function")
+          return value;
+        return (args, ...rest) => {
+          const name = args?.collection ?? args?.slug ?? "";
+          const attributes = {
+            "db.system.name": system2,
+            "db.operation.name": key,
+            "db.collection.name": name
+          };
+          const started = performance.now();
+          return this.span(
+            `db ${key} ${name}`,
+            attributes,
+            () => Promise.resolve(value.call(target, args, ...rest)),
+            "client"
+          ).finally(() => this.dbDuration?.record((performance.now() - started) / 1e3, attributes));
+        };
+      }
+    });
+  }
+  /** A run of one of the config's jobs, for `easy_cms.jobs.*`. */
+  jobRan(name, ok, ms) {
+    const attributes = { job: name, result: ok ? "ok" : "failed" };
+    this.jobRuns?.add(1, attributes);
+    this.jobDuration?.record(ms / 1e3, { job: name });
+  }
+  /** Whether the queue gauges are reported (and worth counting for). */
+  get measuresQueues() {
+    return this.jobRuns !== void 0;
+  }
+  /** Queue sizes found by the last job run, for the gauges. */
+  queuesCounted(queues, late) {
+    this.queues = queues;
+    this.late = late;
+  }
+};
+function errorType(error) {
+  if (error && typeof error === "object") {
+    const code = error.code;
+    if (typeof code === "string" && code) return code;
+    const name = error.name;
+    if (typeof name === "string" && name) return name;
+  }
+  return "Error";
+}
+function routeOf(path, root) {
+  if (path === null) return "other";
+  if (root) return path;
+  const parts = path.split("/").filter(Boolean);
+  const [first] = parts;
+  const fixed = /* @__PURE__ */ new Set(["auth", "admin", "jobs", "search", "healthz", "readyz", "api-keys"]);
+  const word = /^[a-z][a-z.-]{0,39}$/;
+  const route2 = parts.map((part, i) => {
+    if (i === 0) return fixed.has(part) || part === "globals" ? part : ":collection";
+    if (first === "globals" && i === 1) return ":global";
+    if (first === "admin" || first === "auth") return word.test(part) ? part : ":param";
+    if (i === 1) return /^\d+$/.test(part) || !word.test(part) ? ":id" : part;
+    return word.test(part) ? part : ":id";
+  });
+  return `/${route2.join("/")}`;
+}
+
 // src/local-api.ts
 async function createEasyCMS(config, options = {}) {
   const resolved3 = await resolveConfig(config);
@@ -7023,13 +7251,15 @@ async function createEasyCMS(config, options = {}) {
   const storage = resolved3.upload.storage ?? diskStorage({ dir: resolved3.upload.dir });
   await storage.init?.({ cwd });
   if (resolved3.upload.privateStorage) await resolved3.upload.privateStorage.init?.({ cwd });
-  const db = await resolved3.db.init({
+  const telemetry = await Telemetry.load(resolved3.telemetry);
+  const connected = await resolved3.db.init({
     config: resolved3,
     cwd,
     schema: options.schema ?? (process.env.NODE_ENV === "production" ? "verify" : "push"),
     logger,
     interactive: options.interactive ?? false
   });
+  const db = telemetry ? telemetry.database(connected, dbSystem(resolved3.db.name)) : connected;
   if (resolved3.outbox && db.outbox !== true) {
     await db.destroy();
     throw new ConfigError([
@@ -7041,6 +7271,7 @@ async function createEasyCMS(config, options = {}) {
     ]);
   }
   const cms = new EasyCMS(resolved3, db, logger, storage, cwd);
+  cms.telemetry = telemetry;
   if (resolved3.search?.ephemeral && process.env.NODE_ENV === "production")
     logger.warn(
       `Search: the "${resolved3.search.name ?? "custom"}" index lives in this process's memory: it is built again at each start, and each instance has its own. Use a search engine adapter for large sites or several instances.`
@@ -7054,6 +7285,10 @@ async function createEasyCMS(config, options = {}) {
     );
   return cms;
 }
+function dbSystem(name) {
+  if (name.includes("postgres") || name.includes("pglite")) return "postgresql";
+  return name.includes("sqlite") ? "sqlite" : name;
+}
 var toJob = (row) => ({
   id: row.id,
   action: row.action,
@@ -7090,6 +7325,8 @@ var EasyCMS = class {
   outbox;
   /** With `search`: keeps the index in step with published documents. */
   searchIndex;
+  /** @internal With `telemetry`: OpenTelemetry spans and metrics (set by `createEasyCMS`). */
+  telemetry;
   /** @internal */
   constructor(config, db, logger = consoleLogger, storage = diskStorage({ dir: config.upload.dir }), cwd = process.cwd(), privateStorage) {
     this.config = config;
@@ -7117,7 +7354,15 @@ var EasyCMS = class {
       logger,
       config.collections.some((c) => c.slug === EMAIL_DELIVERIES) ? this.emailQueue() : void 0
     );
-    this.outbox = config.collections.some((c) => c.slug === OUTBOX) ? new Outbox(db, logger, (entry, done, mark) => this.runOutbox(entry, done, mark)) : void 0;
+    this.outbox = config.collections.some((c) => c.slug === OUTBOX) ? new Outbox(
+      db,
+      logger,
+      (entry, done, mark) => this.telemetry ? this.telemetry.span(
+        `easy-cms outbox ${entry.event} ${entry.target}`,
+        { "easy_cms.event": entry.event, "easy_cms.collection": entry.target },
+        () => this.runOutbox(entry, done, mark)
+      ) : this.runOutbox(entry, done, mark)
+    ) : void 0;
     this.searchIndex = config.search ? new SearchIndex(
       config.search,
       config.collections,
@@ -7164,99 +7409,112 @@ var EasyCMS = class {
     };
   }
   async find(collection2, options = {}) {
-    const config = this.collection(collection2);
-    const guard = guardOf(options);
-    const limit = options.limit ?? 10;
-    const page = options.page ?? 1;
-    if (!Number.isInteger(limit) || limit < 0)
-      throw new QueryError("limit must be a non-negative integer");
-    if (!Number.isInteger(page) || page < 1) throw new QueryError("page must be a positive integer");
-    const draft = readsDrafts(guard, options.draft);
-    const where = this.whereFor(
-      config,
-      draftWhere(config, draft, await this.readWhere(config, guard, options.where)),
-      options
-    );
-    const requested = options.sort === void 0 ? ["-createdAt"] : [options.sort].flat();
-    await this.checkQueryFields(config, guard, void 0, requested);
-    const locale = this.localeOf(options);
-    const sort = locale === void 0 ? requested : localizeSort(
-      config.fields,
-      requested,
-      locale === ALL_LOCALES ? this.config.localization?.defaultLocale ?? locale : locale,
-      this.config.localization?.locales ?? []
-    );
-    if (options.cursor !== void 0) {
-      if (options.page !== void 0) throw new QueryError("Use either cursor or page, not both");
-      if (limit === 0) throw new QueryError("A cursor needs a limit above 0");
-      if (!this.db.findAfter) throw new QueryError("This database adapter has no cursor pagination");
-      const query = cursorQuery(collection2, options.where, requested, locale, draft);
-      const after = readCursor(options.cursor, query);
-      const result2 = await this.db.findAfter({ collection: collection2, where, sort, limit, after });
-      const found2 = draft ? await this.withDrafts(config, result2.docs) : result2.docs;
-      const docs2 = await this.output(config, found2, guard, { ...options, draft });
-      return {
-        docs: docs2,
-        limit,
-        nextCursor: result2.hasNextPage && result2.next ? writeCursor(result2.next, query) : null,
-        hasNextPage: result2.hasNextPage,
-        hasPrevPage: after !== null,
-        totalDocs: null,
-        totalPages: null,
-        page: null
-      };
-    }
-    const args = { collection: collection2, where, sort, limit, page };
-    const count = options.count !== false || limit === 0;
-    const result = count ? await this.db.find(args) : this.db.findPage ? await this.db.findPage(args) : { ...await this.db.find(args), totalDocs: null, totalPages: null };
-    const found = draft ? await this.withDrafts(config, result.docs) : result.docs;
-    const docs = await this.output(config, found, guard, { ...options, draft });
-    return { ...result, docs };
+    return this.traced("find", String(collection2), async () => {
+      const config = this.collection(collection2);
+      const guard = guardOf(options);
+      const limit = options.limit ?? 10;
+      const page = options.page ?? 1;
+      if (!Number.isInteger(limit) || limit < 0)
+        throw new QueryError("limit must be a non-negative integer");
+      if (!Number.isInteger(page) || page < 1)
+        throw new QueryError("page must be a positive integer");
+      const draft = readsDrafts(guard, options.draft);
+      const where = this.whereFor(
+        config,
+        draftWhere(config, draft, await this.readWhere(config, guard, options.where)),
+        options
+      );
+      const requested = options.sort === void 0 ? ["-createdAt"] : [options.sort].flat();
+      await this.checkQueryFields(config, guard, void 0, requested);
+      const locale = this.localeOf(options);
+      const sort = locale === void 0 ? requested : localizeSort(
+        config.fields,
+        requested,
+        locale === ALL_LOCALES ? this.config.localization?.defaultLocale ?? locale : locale,
+        this.config.localization?.locales ?? []
+      );
+      if (options.cursor !== void 0) {
+        if (options.page !== void 0) throw new QueryError("Use either cursor or page, not both");
+        if (limit === 0) throw new QueryError("A cursor needs a limit above 0");
+        if (!this.db.findAfter)
+          throw new QueryError("This database adapter has no cursor pagination");
+        const query = cursorQuery(collection2, options.where, requested, locale, draft);
+        const after = readCursor(options.cursor, query);
+        const result2 = await this.db.findAfter({ collection: collection2, where, sort, limit, after });
+        const found2 = draft ? await this.withDrafts(config, result2.docs) : result2.docs;
+        const docs2 = await this.output(config, found2, guard, { ...options, draft });
+        return {
+          docs: docs2,
+          limit,
+          nextCursor: result2.hasNextPage && result2.next ? writeCursor(result2.next, query) : null,
+          hasNextPage: result2.hasNextPage,
+          hasPrevPage: after !== null,
+          totalDocs: null,
+          totalPages: null,
+          page: null
+        };
+      }
+      const args = { collection: collection2, where, sort, limit, page };
+      const count = options.count !== false || limit === 0;
+      const result = count ? await this.db.find(args) : this.db.findPage ? await this.db.findPage(args) : { ...await this.db.find(args), totalDocs: null, totalPages: null };
+      const found = draft ? await this.withDrafts(config, result.docs) : result.docs;
+      const docs = await this.output(config, found, guard, { ...options, draft });
+      return { ...result, docs };
+    });
   }
   async findById(collection2, id, options = {}) {
-    const config = this.collection(collection2);
-    const guard = guardOf(options);
-    const parsed = parseId(id);
-    if (parsed === void 0) return null;
-    const draft = readsDrafts(guard, options.draft);
-    const where = this.whereFor(
-      config,
-      draftWhere(config, draft, await this.readWhere(config, guard, void 0)),
-      options
-    );
-    const doc = where ? (await this.db.find({
-      collection: collection2,
-      where: andWhere(where, { id: { equals: parsed } }),
-      sort: [],
-      limit: 1,
-      page: 1
-    })).docs[0] : await this.db.findById({ collection: collection2, id: parsed });
-    if (!doc) return null;
-    const [current] = draft ? await this.withDrafts(config, [doc]) : [doc];
-    const [out] = await this.output(config, [current], guard, { ...options, draft });
-    return out ?? null;
+    return this.traced("findById", String(collection2), async () => {
+      const config = this.collection(collection2);
+      const guard = guardOf(options);
+      const parsed = parseId(id);
+      if (parsed === void 0) return null;
+      const draft = readsDrafts(guard, options.draft);
+      const where = this.whereFor(
+        config,
+        draftWhere(config, draft, await this.readWhere(config, guard, void 0)),
+        options
+      );
+      const doc = where ? (await this.db.find({
+        collection: collection2,
+        where: andWhere(where, { id: { equals: parsed } }),
+        sort: [],
+        limit: 1,
+        page: 1
+      })).docs[0] : await this.db.findById({ collection: collection2, id: parsed });
+      if (!doc) return null;
+      const [current] = draft ? await this.withDrafts(config, [doc]) : [doc];
+      const [out] = await this.output(config, [current], guard, {
+        ...options,
+        draft
+      });
+      return out ?? null;
+    });
   }
   async count(collection2, options = {}) {
-    const config = this.collection(collection2);
-    const where = this.whereFor(
-      config,
-      draftWhere(
+    return this.traced("count", String(collection2), async () => {
+      const config = this.collection(collection2);
+      const where = this.whereFor(
         config,
-        readsDrafts(guardOf(options), options.draft),
-        await this.readWhere(config, guardOf(options), options.where)
-      ),
-      options
-    );
-    return this.db.count({ collection: collection2, where });
+        draftWhere(
+          config,
+          readsDrafts(guardOf(options), options.draft),
+          await this.readWhere(config, guardOf(options), options.where)
+        ),
+        options
+      );
+      return this.db.count({ collection: collection2, where });
+    });
   }
   async create(collection2, data, options = {}) {
-    const config = this.collection(collection2);
-    if (config.slug === MEDIA) {
-      throw new ValidationError(MEDIA, [
-        { field: "file", message: "upload files with cms.upload() or POST multipart" }
-      ]);
-    }
-    return await this.createDocument(config, asObject(data, collection2), options);
+    return this.traced("create", String(collection2), async () => {
+      const config = this.collection(collection2);
+      if (config.slug === MEDIA) {
+        throw new ValidationError(MEDIA, [
+          { field: "file", message: "upload files with cms.upload() or POST multipart" }
+        ]);
+      }
+      return await this.createDocument(config, asObject(data, collection2), options);
+    });
   }
   /**
    * Stores a file and creates its `media` document (FR-UPL). The type is detected from
@@ -7711,7 +7969,14 @@ var EasyCMS = class {
     }
   }
   async update(collection2, id, data, options = {}) {
-    return await this.updateDocument(collection2, id, asObject(data, collection2), options);
+    return this.traced("update", String(collection2), async () => {
+      return await this.updateDocument(
+        collection2,
+        id,
+        asObject(data, collection2),
+        options
+      );
+    });
   }
   /**
    * Adds `by` (negative to take away) to a top-level number field in one database statement, so
@@ -8082,65 +8347,69 @@ var EasyCMS = class {
    * gives the documents they own to another user; without it they have no owner.
    */
   async delete(collection2, id, options = {}) {
-    const config = this.collection(collection2);
-    const guard = guardOf(options);
-    const parsed = parseId(id);
-    const existing = parsed === void 0 ? null : await this.db.findById({ collection: collection2, id: parsed });
-    if (!existing || parsed === void 0) throw new NotFoundError(collection2, id);
-    await this.checkDocumentAccess(config, "delete", guard, parsed, void 0);
-    if (config.slug === USERS)
-      await this.guardLastAdmin(parsed, existing, { ...existing, active: false });
-    const base = this.hookArgs(config, guard);
-    for (const hook of config.hooks?.beforeDelete ?? []) await hook({ ...base, id: parsed });
-    if (config.slug === USERS) {
-      const to = options.transferTo;
-      if (to !== void 0 && to !== null) {
-        const target = parseId(to);
-        const heir = target === void 0 ? null : await this.db.findById({ collection: USERS, id: target });
-        if (!heir || String(heir.id) === String(parsed))
-          throw new ValidationError(USERS, [
-            { field: "transferTo", message: "must be another existing user" }
-          ]);
-        await this.roles.transfer(parsed, heir.id);
-      } else await this.roles.transfer(parsed, null);
-      await this.auth.revokeSessions(parsed);
-      await this.auth.sso.forget(parsed);
-    }
-    if (collection2 === MEDIA_FOLDERS) {
-      await this.checkMoveLimit(await this.folders.privacyAfter(parsed, { private: false }));
-      await this.folders.release(existing);
-    }
-    const outbox = this.outboxRow(config, "delete", guard, existing, { docId: parsed });
-    await this.db.delete({ collection: collection2, id: parsed, outbox });
-    if (collection2 === MEDIA_FOLDERS) {
-      this.folders.invalidate();
-      const parent = existing.parent ?? null;
-      if (parent !== null) await this.settlePrivacy(parent);
-      else await this.settleTopLevel();
-    }
-    if (versionLimit(config)) await this.versions.deleteAll(collectionParent(collection2), parsed);
-    if (config.schedule) {
-      for (const job of await this.pendingJobs(collection2, parsed))
-        await this.db.delete({ collection: SCHEDULED_JOBS, id: job.id });
-    }
-    if (outbox) this.outbox?.kick();
-    else {
-      await this.notify(config.hooks?.afterDelete, "afterDelete", config.slug, {
-        ...base,
-        id: parsed,
-        doc: existing
-      });
-      this.emitChange(config, "delete", existing);
-    }
-    await this.audited(config, "delete", existing, existing, guard);
-    const [out] = await this.output(config, [existing], guard, { depth: 0, draft: true });
-    return out;
+    return this.traced("delete", String(collection2), async () => {
+      const config = this.collection(collection2);
+      const guard = guardOf(options);
+      const parsed = parseId(id);
+      const existing = parsed === void 0 ? null : await this.db.findById({ collection: collection2, id: parsed });
+      if (!existing || parsed === void 0) throw new NotFoundError(collection2, id);
+      await this.checkDocumentAccess(config, "delete", guard, parsed, void 0);
+      if (config.slug === USERS)
+        await this.guardLastAdmin(parsed, existing, { ...existing, active: false });
+      const base = this.hookArgs(config, guard);
+      for (const hook of config.hooks?.beforeDelete ?? []) await hook({ ...base, id: parsed });
+      if (config.slug === USERS) {
+        const to = options.transferTo;
+        if (to !== void 0 && to !== null) {
+          const target = parseId(to);
+          const heir = target === void 0 ? null : await this.db.findById({ collection: USERS, id: target });
+          if (!heir || String(heir.id) === String(parsed))
+            throw new ValidationError(USERS, [
+              { field: "transferTo", message: "must be another existing user" }
+            ]);
+          await this.roles.transfer(parsed, heir.id);
+        } else await this.roles.transfer(parsed, null);
+        await this.auth.revokeSessions(parsed);
+        await this.auth.sso.forget(parsed);
+      }
+      if (collection2 === MEDIA_FOLDERS) {
+        await this.checkMoveLimit(await this.folders.privacyAfter(parsed, { private: false }));
+        await this.folders.release(existing);
+      }
+      const outbox = this.outboxRow(config, "delete", guard, existing, { docId: parsed });
+      await this.db.delete({ collection: collection2, id: parsed, outbox });
+      if (collection2 === MEDIA_FOLDERS) {
+        this.folders.invalidate();
+        const parent = existing.parent ?? null;
+        if (parent !== null) await this.settlePrivacy(parent);
+        else await this.settleTopLevel();
+      }
+      if (versionLimit(config)) await this.versions.deleteAll(collectionParent(collection2), parsed);
+      if (config.schedule) {
+        for (const job of await this.pendingJobs(collection2, parsed))
+          await this.db.delete({ collection: SCHEDULED_JOBS, id: job.id });
+      }
+      if (outbox) this.outbox?.kick();
+      else {
+        await this.notify(config.hooks?.afterDelete, "afterDelete", config.slug, {
+          ...base,
+          id: parsed,
+          doc: existing
+        });
+        this.emitChange(config, "delete", existing);
+      }
+      await this.audited(config, "delete", existing, existing, guard);
+      const [out] = await this.output(config, [existing], guard, { depth: 0, draft: true });
+      return out;
+    });
   }
   async findGlobal(slug2, options = {}) {
-    const config = this.global(slug2);
-    const guard = guardOf(options);
-    await this.checkGlobalAccess(config, "read", guard);
-    return this.readGlobal(config, this.globalKey(config, guard), guard, options);
+    return this.traced("findGlobal", String(slug2), async () => {
+      const config = this.global(slug2);
+      const guard = guardOf(options);
+      await this.checkGlobalAccess(config, "read", guard);
+      return this.readGlobal(config, this.globalKey(config, guard), guard, options);
+    });
   }
   /** A global as stored under `key` (see `globalKey`); empty when there is no key. */
   async readGlobal(config, key, guard, options) {
@@ -8180,7 +8449,9 @@ var EasyCMS = class {
     return key;
   }
   async updateGlobal(slug2, data, options = {}) {
-    return this.saveGlobal(slug2, asObject(data, slug2), options);
+    return this.traced("updateGlobal", String(slug2), async () => {
+      return this.saveGlobal(slug2, asObject(data, slug2), options);
+    });
   }
   /** Takes a global off the site (`status: 'draft'`). See `unpublish`. */
   async unpublishGlobal(slug2, options = {}) {
@@ -8447,36 +8718,39 @@ var EasyCMS = class {
    * hold fewer documents than `limit`.
    */
   async search(query, options = {}) {
-    const index = this.searchIndex;
-    if (!index) throw new QueryError("Search needs a `search` adapter in the config");
-    const limit = options.limit ?? 10;
-    const page = options.page ?? 1;
-    if (!Number.isInteger(limit) || limit < 1 || limit > 100)
-      throw new QueryError("limit must be an integer from 1 to 100");
-    if (!Number.isInteger(page) || page < 1) throw new QueryError("page must be an integer from 1");
-    const collections = options.collections ?? index.searchable;
-    for (const slug2 of collections)
-      if (!index.configOf(slug2)) throw new QueryError(`"${slug2}" is not searchable`);
-    const localization = this.config.localization;
-    const asked = options.locale && options.locale !== ALL_LOCALES ? options.locale : void 0;
-    if (asked !== void 0 && localization && !localization.locales.includes(asked))
-      throw new QueryError(`Unknown locale "${asked}"`);
-    const locale = localization ? asked ?? localization.defaultLocale ?? null : null;
-    const text3 = query.trim().slice(0, 200);
-    const empty = { hits: [], total: 0, page, limit, hasNextPage: false };
-    if (!text3 || collections.length === 0) return empty;
-    const { collections: _, limit: __, page: ___, ...read2 } = options;
-    const { hits, total } = await index.search(
-      { query: text3, collections, locale, limit, offset: (page - 1) * limit },
-      async (collection2, ids) => (await this.find(collection2, {
-        ...read2,
-        ...locale ? { locale } : {},
-        where: { id: { in: ids.map((id) => parseId(id) ?? id) } },
-        limit: ids.length,
-        draft: false
-      })).docs
-    );
-    return { hits, total, page, limit, hasNextPage: page * limit < total };
+    return this.traced("search", "", async () => {
+      const index = this.searchIndex;
+      if (!index) throw new QueryError("Search needs a `search` adapter in the config");
+      const limit = options.limit ?? 10;
+      const page = options.page ?? 1;
+      if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+        throw new QueryError("limit must be an integer from 1 to 100");
+      if (!Number.isInteger(page) || page < 1)
+        throw new QueryError("page must be an integer from 1");
+      const collections = options.collections ?? index.searchable;
+      for (const slug2 of collections)
+        if (!index.configOf(slug2)) throw new QueryError(`"${slug2}" is not searchable`);
+      const localization = this.config.localization;
+      const asked = options.locale && options.locale !== ALL_LOCALES ? options.locale : void 0;
+      if (asked !== void 0 && localization && !localization.locales.includes(asked))
+        throw new QueryError(`Unknown locale "${asked}"`);
+      const locale = localization ? asked ?? localization.defaultLocale ?? null : null;
+      const text3 = query.trim().slice(0, 200);
+      const empty = { hits: [], total: 0, page, limit, hasNextPage: false };
+      if (!text3 || collections.length === 0) return empty;
+      const { collections: _, limit: __, page: ___, ...read2 } = options;
+      const { hits, total } = await index.search(
+        { query: text3, collections, locale, limit, offset: (page - 1) * limit },
+        async (collection2, ids) => (await this.find(collection2, {
+          ...read2,
+          ...locale ? { locale } : {},
+          where: { id: { in: ids.map((id) => parseId(id) ?? id) } },
+          limit: ids.length,
+          draft: false
+        })).docs
+      );
+      return { hits, total, page, limit, hasNextPage: page * limit < total };
+    });
   }
   /**
    * Builds the search index again from the database, for every searchable collection or one:
@@ -8515,6 +8789,18 @@ var EasyCMS = class {
       if (!found.hasNextPage) return;
     }
   }
+  /** A Local API call in a span (`easy-cms <operation> <collection>`) with `telemetry`. */
+  traced(operation, target, fn) {
+    if (!this.telemetry) return fn();
+    return this.telemetry.span(
+      `easy-cms ${operation}${target ? ` ${target}` : ""}`,
+      {
+        "easy_cms.operation": operation,
+        ...target ? { "easy_cms.collection": target } : {}
+      },
+      fn
+    );
+  }
   /** @internal Puts a failed outbox entry back in line (Settings → Jobs). */
   retryOutbox(id) {
     return this.outbox?.retry(id) ?? Promise.resolve(false);
@@ -8546,7 +8832,9 @@ var EasyCMS = class {
    * scheduler and the cron endpoint (`GET <api>/jobs/run`) call.
    */
   runJobs(now = /* @__PURE__ */ new Date()) {
-    const run = this.running.then(() => this.runJobsNow(now));
+    const run = this.running.then(
+      () => this.telemetry ? this.telemetry.span("easy-cms jobs.run", {}, () => this.runJobsNow(now)) : this.runJobsNow(now)
+    );
     this.running = run.catch(() => {
     });
     return run;
@@ -8573,6 +8861,10 @@ var EasyCMS = class {
         jobs: await this.runConfigJobs(now),
         outbox: await this.outbox?.run(now) ?? { ran: 0, failed: 0 }
       };
+      if (this.telemetry?.measuresQueues)
+        await this.countQueues(now).catch(
+          (error) => this.logger.error(`Telemetry: ${error.message}`, { error })
+        );
       const ranAt = (/* @__PURE__ */ new Date()).toISOString();
       await this.db.updateGlobal({ slug: JOBS_RAN, data: { at: ranAt, updatedAt: ranAt } }).catch((error) => this.logger.error(`Jobs: ${error.message}`, { error }));
       return result;
@@ -8641,19 +8933,47 @@ var EasyCMS = class {
       const started = Date.now();
       let error = null;
       try {
-        await job.run({ cms: this, now });
+        const work = async () => job.run({ cms: this, now });
+        await (this.telemetry ? this.telemetry.span(`easy-cms job ${job.name}`, { "easy_cms.job": job.name }, work) : work());
         ran++;
       } catch (caught) {
         failed++;
         error = (caught.message || String(caught)).slice(0, 500);
         this.logger.error(`Job ${job.name} failed: ${error}`, { error: caught, job: job.name });
       }
+      this.telemetry?.jobRan(job.name, error === null, Date.now() - started);
       await this.recordJobRun(job.name, stamp, error, Date.now() - started).catch(
         (caught) => this.logger.error(`Job ${job.name}: ${caught.message}`, { error: caught })
       );
     }
     return { ran, failed };
   }
+  /** Background work waiting and failed, for `telemetry`'s queue gauges. */
+  async countQueues(now) {
+    const has3 = (slug2) => this.config.collections.some((c) => c.slug === slug2);
+    const sizes = async (collection2, pending) => ({
+      pending: await this.db.count({ collection: collection2, where: { state: { in: pending } } }),
+      failed: await this.db.count({ collection: collection2, where: { state: { equals: "failed" } } })
+    });
+    const queues = {};
+    if (has3(OUTBOX)) queues.outbox = await sizes(OUTBOX, ["pending", "running"]);
+    if (has3(WEBHOOK_DELIVERIES)) queues.webhooks = await sizes(WEBHOOK_DELIVERIES, ["pending"]);
+    if (has3(EMAIL_DELIVERIES)) queues.emails = await sizes(EMAIL_DELIVERIES, ["pending"]);
+    let late = 0;
+    if (has3(SCHEDULED_JOBS)) {
+      queues.scheduled = await sizes(SCHEDULED_JOBS, ["pending", "running"]);
+      late = await this.db.count({
+        collection: SCHEDULED_JOBS,
+        where: {
+          and: [
+            { state: { equals: "pending" } },
+            { runAt: { lt: new Date(now.getTime() - 10 * 6e4).toISOString() } }
+          ]
+        }
+      });
+    }
+    this.telemetry?.queuesCounted(queues, late);
+  }
   async recordJobRun(name, at, error, ms) {
     const { docs } = await this.db.find({
       collection: JOB_RUNS,
@@ -10750,9 +11070,6 @@ async function readAdminModule(cms, index) {
   return { body, etag: `"${createHash6("sha1").update(body).digest("base64url")}"` };
 }
 
-// src/version.ts
-var VERSION = true ? "1.14.0" : "0.0.0-dev";
-
 // src/rest/handler.ts
 import { randomUUID as randomUUID4 } from "crypto";
 
@@ -10881,7 +11198,6 @@ async function deleteFailedDeliveries(cms, kind) {
 }
 
 // src/rest/admin-email.ts
-var EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
 var LIMIT = 5;
 var WINDOW = 10 * 6e4;
 var sentAt = /* @__PURE__ */ new WeakMap();
@@ -10930,7 +11246,7 @@ async function sendTestEmail(cms, user, to, locale) {
   const adapter = cms.config.email;
   if (!adapter) return { ok: false, error: "Email is not set up (`email` in the config)" };
   const address = typeof to === "string" && to.trim() ? to.trim() : user.email;
-  if (!EMAIL.test(address))
+  if (!isEmail(address))
     throw new ValidationError("email", [{ field: "to", message: "must be an email address" }]);
   const times = sentAt.get(cms) ?? /* @__PURE__ */ new Map();
   sentAt.set(cms, times);
@@ -11528,6 +11844,7 @@ async function adminStatus(cms) {
       storage: config.upload.storage?.name ?? "local",
       email: config.email ? config.email.name ?? "custom" : null,
       search: config.search ? config.search.name ?? "custom" : null,
+      telemetry: !!config.telemetry,
       plugins: config.installedPlugins.map((p) => ({ ...p })),
       fieldTypes: config.fieldTypes.map((t) => t.name)
     },
@@ -11726,7 +12043,14 @@ var HEALTH_CHECKS = /* @__PURE__ */ new Map([
   ["readyz", "readyz"]
 ]);
 var REQUEST_ID = /^[\w.-]{1,128}$/;
-async function respond(cms, request, url, path, root, options, production) {
+function respond(cms, request, url, path, root, options, production) {
+  const run = () => respondLogged(cms, request, url, path, root, options, production);
+  const probe = !root && (path === "/healthz" || path === "/readyz");
+  if (!cms.telemetry || probe) return run();
+  const route2 = root || path === null ? routeOf(path, root) : `${cms.config.routes.api}${routeOf(path, root)}`;
+  return cms.telemetry.request(request.method, route2, run);
+}
+async function respondLogged(cms, request, url, path, root, options, production) {
   const started = performance.now();
   const incoming = request.headers.get("x-request-id");
   const requestId = incoming && REQUEST_ID.test(incoming) ? incoming : randomUUID4();
@@ -13044,13 +13368,14 @@ function errorResponse(cms, error, headers, production) {
     }
     return new Response(JSON.stringify({ errors }), { status: error.status, headers });
   }
-  const message2 = error instanceof Error ? error.message : String(error);
-  cms.logger.error(`REST request failed: ${message2}`, { error });
-  const body = {
-    errors: [
-      { message: production ? "Internal Server Error" : message2, code: "INTERNAL_SERVER_ERROR" }
-    ]
-  };
+  cms.logger.error(
+    `REST request failed: ${error instanceof Error ? error.message : String(error)}`,
+    {
+      error
+    }
+  );
+  const message2 = !production && error instanceof Error ? error.message : "Internal Server Error";
+  const body = { errors: [{ message: message2, code: "INTERNAL_SERVER_ERROR" }] };
   return new Response(JSON.stringify(body), { status: 500, headers });
 }
 
@@ -13186,6 +13511,7 @@ export {
   SSO_COOKIE,
   Auth,
   ADAPTER_API_VERSION,
+  isEmail,
   slugify,
   applyDefaults,
   fillMissing,
@@ -13227,10 +13553,10 @@ export {
   applyPlugins,
   resolveConfig,
   cacheTags,
+  VERSION,
   createEasyCMS,
   EasyCMS,
   resolveAdminModule,
-  VERSION,
   CSRF_COOKIE,
   CSRF_HEADER,
   createRestHandler,