@siteping/server 0.1.1 → 0.2.1

package/dist/index.cjs

@@ -30,9 +30,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  SITEPING_PROTOCOL_VERSION: () => SITEPING_PROTOCOL_VERSION,
+  WEBHOOK_EVENTS: () => WEBHOOK_EVENTS,
   createSitepingHandler: () => createSitepingHandler,
   dispatchWebhook: () => dispatchWebhook,
-  dispatchWebhooks: () => dispatchWebhooks
+  dispatchWebhooks: () => dispatchWebhooks,
+  isSitepingConfigError: () => isSitepingConfigError
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -47,8 +50,23 @@ function hasOwn(value, key) {
   return isRecord(value) && key in value;
 }
 
+// ../core/src/errors.ts
+var SitepingConfigError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "SitepingConfigError";
+  }
+};
+function isSitepingConfigError(error) {
+  return hasOwn(error, "name") && error.name === "SitepingConfigError" && hasOwn(error, "code") && typeof error.code === "string" && error.code.startsWith("CONFIG_");
+}
+
 // ../core/src/types.ts
 var IDENTITY_FIELD_MAX_LENGTH = 200;
+var PROJECT_NAME_MAX_LENGTH = 191;
+var CLIENT_ID_MAX_LENGTH = 191;
 var FEEDBACK_TYPES = ["question", "change", "bug", "other"];
 var FEEDBACK_STATUSES = ["open", "in_progress", "resolved", "wont_fix"];
 var CLOSED_FEEDBACK_STATUSES = ["resolved", "wont_fix"];
@@ -134,6 +152,7 @@ function flattenAnnotation(ann) {
 var CONSOLE_DIAGNOSTIC_LEVELS = ["log", "info", "warn", "error"];
 var ANCHOR_ELEMENT_TAG_MAX = 191;
 var ANCHOR_ELEMENT_ID_MAX = 191;
+var SITEPING_PROTOCOL_VERSION = 1;
 
 // src/constants.ts
 var MAX_ANNOTATIONS_PER_FEEDBACK = 50;
@@ -192,7 +211,8 @@ function createApiKeyGate({
   redactUnauthenticatedEmails = true
 }) {
   if (!apiKey && requireAuthForDestructive && isProductionEnvironment()) {
-    throw new Error(
+    throw new SitepingConfigError(
+      "CONFIG_API_KEY_REQUIRED",
       "[siteping] createSitepingHandler: apiKey is required in production. Set `apiKey` to enable destructive endpoints, pass `access` to plug in your own authentication, or pass `requireAuthForDestructive: false` if SitePing sits behind your own auth middleware."
     );
   }
@@ -203,15 +223,14 @@ function createApiKeyGate({
     return header !== null && safeCompare(header, `Bearer ${apiKey}`);
   };
   const authenticate = async (request, method) => {
-    const canReadAuthorEmail = !redactUnauthenticatedEmails || isBearerAuthenticated(request);
     if (!apiKey) {
       if (requireAuthForDestructive && (method === "DELETE" || method === "PATCH")) {
         return { ok: false, status: 401, error: ERROR_MESSAGES.apiKeyRequiredForDestructive };
       }
-      return { ok: true, principal: null, canReadAuthorEmail };
+      return { ok: true, principal: null };
     }
     if (publicMethods?.has(method) || isBearerAuthenticated(request)) {
-      return { ok: true, principal: null, canReadAuthorEmail };
+      return { ok: true, principal: null };
     }
     return { ok: false, status: 401, error: ERROR_MESSAGES.unauthorized };
   };
@@ -228,6 +247,10 @@ function createApiKeyGate({
     async authorize() {
       return true;
     },
+    // One key covers every project, so the project changes nothing here.
+    async canReadAuthorEmail({ request }) {
+      return !redactUnauthenticatedEmails || isBearerAuthenticated(request);
+    },
     // The key proves the caller is the project side; a public POST does not.
     async canCommentAsTeam({ request }) {
       return isBearerAuthenticated(request);
@@ -244,7 +267,7 @@ function createAccessGate(access) {
       if (!principal) {
         return { ok: false, status: 401, error: ERROR_MESSAGES.unauthorized };
       }
-      return { ok: true, principal, canReadAuthorEmail: await access.canReadAuthorEmail?.(principal) === true };
+      return { ok: true, principal };
     },
     // A dry run reuses the response's request, so `authenticate` is never asked
     // about another method: `authorize` decides, by action.
@@ -254,10 +277,15 @@ function createAccessGate(access) {
     async authorize(context) {
       return access.authorize ? access.authorize(context) : true;
     },
+    // Emails are personal data: only a `true` answer reveals them — no
+    // callback, or `undefined` from a principal missing the flag, hides them.
+    async canReadAuthorEmail({ request, principal }, projectName) {
+      return await access.canReadAuthorEmail?.(principal, { request, projectName }) === true;
+    },
     // Speaking as the team is an impersonation privilege: without the host's
     // word for it (its own callback, or the email access it grants), refuse.
-    async canCommentAsTeam({ principal }, canReadAuthorEmail) {
-      return access.canCommentAsTeam ? await access.canCommentAsTeam(principal) === true : canReadAuthorEmail;
+    async canCommentAsTeam({ request, principal }, projectName, canReadAuthorEmail) {
+      return access.canCommentAsTeam ? await access.canCommentAsTeam(principal, { request, projectName }) === true : canReadAuthorEmail;
     }
   };
 }
@@ -305,6 +333,389 @@ function preflightResponse(request, allowedOrigins) {
   return new Response(null, { status: 204, headers });
 }
 
+// src/webhooks.ts
+var WEBHOOK_EVENTS = [
+  "feedback.created",
+  "feedback.status_changed",
+  "feedback.deleted",
+  "comment.created"
+];
+var DEFAULT_EVENTS = ["feedback.created"];
+var EVENT_HEADER = "X-Siteping-Event";
+var DEFAULT_TIMEOUT_MS = 5e3;
+var TIMER_MAX_DELAY_MS = 2147483647;
+function timeoutProblem(timeoutMs) {
+  if (timeoutMs === void 0 || Number.isSafeInteger(timeoutMs) && timeoutMs > 0 && timeoutMs <= TIMER_MAX_DELAY_MS) {
+    return null;
+  }
+  return `timeoutMs must be a positive integer of at most ${TIMER_MAX_DELAY_MS}, got ${timeoutMs}`;
+}
+function eventsProblem(events) {
+  if (events === void 0) return null;
+  if (!Array.isArray(events) || events.length === 0) return "events must list at least one event";
+  const unknown = events.find((event) => !WEBHOOK_EVENTS.includes(event));
+  if (unknown !== void 0)
+    return `unknown event ${JSON.stringify(unknown)} in events (one of ${WEBHOOK_EVENTS.join(", ")})`;
+  return null;
+}
+function checkWebhookConfigs(configs) {
+  for (const config of configs) {
+    const problem = timeoutProblem(config.timeoutMs) ?? eventsProblem(config.events);
+    if (problem) {
+      throw new SitepingConfigError(
+        "CONFIG_WEBHOOK_TIMEOUT_INVALID",
+        `[siteping] createSitepingHandler: webhook to ${webhookOrigin(config.url)}: ${problem}.`
+      );
+    }
+  }
+}
+function subscribesTo(config, event) {
+  return (config.events ?? DEFAULT_EVENTS).includes(event);
+}
+var DISCORD_COLORS = {
+  bug: 15680580,
+  question: 3900150,
+  change: 16096779,
+  other: 7041664
+};
+var DEFAULT_DISCORD_COLOR = 7041664;
+function deliverySubject(delivery) {
+  switch (delivery.event) {
+    case "feedback.deleted":
+      return delivery.target.kind === "single" ? { feedbackId: delivery.target.id, projectName: delivery.target.projectName } : { feedbackId: "", projectName: delivery.target.projectName };
+    case "comment.created":
+      return { feedbackId: delivery.comment.feedbackId, projectName: delivery.comment.projectName };
+    default:
+      return { feedbackId: delivery.feedback.id, projectName: delivery.feedback.projectName };
+  }
+}
+function truncate(text, max = 300) {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max - 1)}\u2026`;
+}
+function fitEscaped(units, max) {
+  const escaped = units.join("");
+  if (escaped.length <= max) return escaped;
+  let out = "";
+  for (const unit of units) {
+    if (out.length + unit.length > max - 1) break;
+    out += unit;
+  }
+  return `${out}\u2026`;
+}
+var SLACK_HEADER_MAX = 150;
+var SLACK_TEXT_MAX = 3e3;
+function escapeSlackText(text) {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+var slackField = (value, max) => fitEscaped(Array.from(value, escapeSlackText), max);
+var SLACK_FROM_HALF = Math.floor((SLACK_TEXT_MAX - 11) / 2);
+var slackProject = (projectName) => `*Project:* ${slackField(projectName, SLACK_TEXT_MAX - 11)}`;
+var slackUrl = (url) => `*URL:* ${slackField(url, SLACK_TEXT_MAX - 7)}`;
+function slackMessage(headline, preview, context) {
+  return {
+    text: `${escapeSlackText(headline)}: ${preview}`,
+    blocks: [
+      {
+        type: "header",
+        text: { type: "plain_text", text: truncate(headline, SLACK_HEADER_MAX), emoji: true }
+      },
+      {
+        type: "section",
+        text: { type: "mrkdwn", text: preview }
+      },
+      {
+        type: "context",
+        elements: context.map((text) => ({ type: "mrkdwn", text }))
+      }
+    ]
+  };
+}
+function slackFrom(authorName, authorEmail) {
+  const email = authorEmail ? ` (${slackField(authorEmail, SLACK_FROM_HALF)})` : "";
+  return `*From:* ${slackField(authorName, SLACK_FROM_HALF)}${email}`;
+}
+var STATUS_VERBS = {
+  open: "reopened",
+  in_progress: "marked in progress",
+  resolved: "resolved",
+  wont_fix: "marked won't fix"
+};
+function buildSlackPayload(feedback) {
+  return slackMessage(
+    `New ${feedback.type} feedback from ${feedback.authorName}`,
+    escapeSlackText(truncate(feedback.message)),
+    [
+      slackProject(feedback.projectName),
+      `*Type:* ${feedback.type}`,
+      slackUrl(feedback.url),
+      `*From:* ${slackField(feedback.authorName, SLACK_FROM_HALF)} (${slackField(feedback.authorEmail, SLACK_FROM_HALF)})`
+    ]
+  );
+}
+function buildSlackStatusPayload(feedback) {
+  return slackMessage(
+    `Feedback ${STATUS_VERBS[feedback.status]}: ${feedback.type} from ${feedback.authorName}`,
+    escapeSlackText(truncate(feedback.message)),
+    [
+      slackProject(feedback.projectName),
+      `*Status:* ${feedback.status}`,
+      slackUrl(feedback.url),
+      slackFrom(feedback.authorName, feedback.authorEmail)
+    ]
+  );
+}
+function buildSlackDeletionPayload(target) {
+  if (target.kind === "project") {
+    return slackMessage(
+      "All feedback deleted",
+      `Every feedback of ${slackField(target.projectName, SLACK_TEXT_MAX - 30)} was deleted.`,
+      [slackProject(target.projectName)]
+    );
+  }
+  return slackMessage("Feedback deleted", `Feedback ${slackField(target.id, SLACK_TEXT_MAX - 30)} was deleted.`, [
+    slackProject(target.projectName),
+    `*ID:* ${slackField(target.id, SLACK_TEXT_MAX - 6)}`
+  ]);
+}
+function buildSlackCommentPayload(comment) {
+  return slackMessage(
+    `New ${comment.authorRole} reply from ${comment.authorName}`,
+    escapeSlackText(truncate(comment.body)),
+    [
+      slackProject(comment.projectName),
+      `*Feedback:* ${slackField(comment.feedbackId, SLACK_TEXT_MAX - 12)}`,
+      slackFrom(comment.authorName, comment.authorEmail)
+    ]
+  );
+}
+var DISCORD_CONTENT_MAX = 2e3;
+var DISCORD_TITLE_MAX = 256;
+var DISCORD_FIELD_VALUE_MAX = 1024;
+var DISCORD_MARKDOWN = /[\\*_~`|>#[\]()<]/g;
+var DISCORD_AUTOLINK = /(<https?:\/\/[^\s<>]+>|https?:\/\/[^\s<>]+)/i;
+var DISCORD_LINK_TRAILER = `.,:;"')]`;
+var escapeMarkdownChar = (char) => char.replace(DISCORD_MARKDOWN, "\\$&");
+var encodeLinkChar = (char) => char.replace(/[[\]()]/g, (bracket) => `%${bracket.charCodeAt(0).toString(16).toUpperCase()}`);
+var count = (text, char) => text.split(char).length - 1;
+function discordUrlUnits(url) {
+  const open = { ")": count(url, "(") - count(url, ")"), "]": count(url, "[") - count(url, "]") };
+  let end = url.length;
+  while (end > 0) {
+    const last = url.charAt(end - 1);
+    if (!DISCORD_LINK_TRAILER.includes(last)) break;
+    if (last === ")" || last === "]") {
+      if (open[last] >= 0) break;
+      open[last] += 1;
+    }
+    end -= 1;
+  }
+  return [...Array.from(url.slice(0, end), encodeLinkChar), ...url.slice(end)];
+}
+function escapeDiscordText(text, max) {
+  const units = text.split(DISCORD_AUTOLINK).flatMap((part, index) => index % 2 === 1 ? discordUrlUnits(part) : Array.from(part, escapeMarkdownChar));
+  return fitEscaped(units, max);
+}
+function buildDiscordPayload(feedback) {
+  const contentLead = `New **${feedback.type}** feedback from **`;
+  const titleLead = `${feedback.type} \u2014 `;
+  const authorHalf = Math.floor((DISCORD_FIELD_VALUE_MAX - 3) / 2);
+  return {
+    content: `${contentLead}${escapeDiscordText(feedback.authorName, DISCORD_CONTENT_MAX - contentLead.length - 2)}**`,
+    embeds: [
+      {
+        title: `${titleLead}${escapeDiscordText(feedback.projectName, DISCORD_TITLE_MAX - titleLead.length)}`,
+        description: escapeDiscordText(feedback.message, 300),
+        color: DISCORD_COLORS[feedback.type] ?? DEFAULT_DISCORD_COLOR,
+        fields: [
+          { name: "URL", value: escapeDiscordText(feedback.url, DISCORD_FIELD_VALUE_MAX), inline: false },
+          {
+            name: "Author",
+            value: `${escapeDiscordText(feedback.authorName, authorHalf)} (${escapeDiscordText(feedback.authorEmail, authorHalf)})`,
+            inline: true
+          },
+          { name: "Viewport", value: escapeDiscordText(feedback.viewport, DISCORD_FIELD_VALUE_MAX), inline: true }
+        ],
+        timestamp: new Date(feedback.createdAt).toISOString()
+      }
+    ],
+    allowed_mentions: { parse: [] }
+  };
+}
+var COMMENT_DISCORD_COLOR = 9133302;
+function discordMessage(content, embed) {
+  return { content, embeds: [embed], allowed_mentions: { parse: [] } };
+}
+function buildDiscordStatusPayload(feedback) {
+  const contentLead = `Feedback **${STATUS_VERBS[feedback.status]}**: ${feedback.type} from **`;
+  const titleLead = `${feedback.type} \u2014 `;
+  return discordMessage(
+    `${contentLead}${escapeDiscordText(feedback.authorName, DISCORD_CONTENT_MAX - contentLead.length - 2)}**`,
+    {
+      title: `${titleLead}${escapeDiscordText(feedback.projectName, DISCORD_TITLE_MAX - titleLead.length)}`,
+      description: escapeDiscordText(feedback.message, 300),
+      color: DISCORD_COLORS[feedback.type] ?? DEFAULT_DISCORD_COLOR,
+      fields: [
+        { name: "Status", value: feedback.status, inline: true },
+        { name: "URL", value: escapeDiscordText(feedback.url, DISCORD_FIELD_VALUE_MAX), inline: false }
+      ],
+      timestamp: new Date(feedback.updatedAt).toISOString()
+    }
+  );
+}
+function buildDiscordDeletionPayload(target) {
+  const project = (max) => escapeDiscordText(target.projectName, max);
+  const contentLead = target.kind === "project" ? "All feedback deleted from **" : "Feedback deleted from **";
+  const fields = [{ name: "Project", value: project(DISCORD_FIELD_VALUE_MAX), inline: true }];
+  if (target.kind === "single") {
+    fields.push({ name: "ID", value: escapeDiscordText(target.id, DISCORD_FIELD_VALUE_MAX), inline: true });
+  }
+  return discordMessage(`${contentLead}${project(DISCORD_CONTENT_MAX - contentLead.length - 2)}**`, {
+    title: target.kind === "project" ? "All feedback deleted" : "Feedback deleted",
+    description: target.kind === "project" ? `Every feedback of ${project(300)} was deleted.` : `Feedback ${escapeDiscordText(target.id, 300)} was deleted.`,
+    color: DEFAULT_DISCORD_COLOR,
+    fields,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString()
+  });
+}
+function buildDiscordCommentPayload(comment) {
+  const contentLead = `New **${comment.authorRole}** reply from **`;
+  const titleLead = "Reply \u2014 ";
+  const authorHalf = Math.floor((DISCORD_FIELD_VALUE_MAX - 3) / 2);
+  const author = comment.authorEmail ? `${escapeDiscordText(comment.authorName, authorHalf)} (${escapeDiscordText(comment.authorEmail, authorHalf)})` : escapeDiscordText(comment.authorName, DISCORD_FIELD_VALUE_MAX);
+  return discordMessage(
+    `${contentLead}${escapeDiscordText(comment.authorName, DISCORD_CONTENT_MAX - contentLead.length - 2)}**`,
+    {
+      title: `${titleLead}${escapeDiscordText(comment.projectName, DISCORD_TITLE_MAX - titleLead.length)}`,
+      description: escapeDiscordText(comment.body, 300),
+      color: COMMENT_DISCORD_COLOR,
+      fields: [
+        { name: "Feedback", value: escapeDiscordText(comment.feedbackId, DISCORD_FIELD_VALUE_MAX), inline: true },
+        { name: "Author", value: author, inline: true }
+      ],
+      timestamp: new Date(comment.createdAt).toISOString()
+    }
+  );
+}
+function buildGenericPayload(feedback) {
+  const { clientId: _clientId, comments, ...payload } = feedback;
+  if (!comments) return payload;
+  return { ...payload, comments: comments.map(({ clientId: _commentClientId, ...comment }) => comment) };
+}
+function buildGenericCommentPayload(comment) {
+  const { clientId: _clientId, ...payload } = comment;
+  return payload;
+}
+function buildDeliveryPayload(type, delivery) {
+  switch (delivery.event) {
+    case "feedback.created":
+      if (type === "slack") return buildSlackPayload(delivery.feedback);
+      if (type === "discord") return buildDiscordPayload(delivery.feedback);
+      return buildGenericPayload(delivery.feedback);
+    case "feedback.status_changed":
+      if (type === "slack") return buildSlackStatusPayload(delivery.feedback);
+      if (type === "discord") return buildDiscordStatusPayload(delivery.feedback);
+      return buildGenericPayload(delivery.feedback);
+    case "feedback.deleted":
+      if (type === "slack") return buildSlackDeletionPayload(delivery.target);
+      if (type === "discord") return buildDiscordDeletionPayload(delivery.target);
+      return { ...delivery.target };
+    case "comment.created":
+      if (type === "slack") return buildSlackCommentPayload(delivery.comment);
+      if (type === "discord") return buildDiscordCommentPayload(delivery.comment);
+      return buildGenericCommentPayload(delivery.comment);
+  }
+}
+async function dispatchWebhook(config, feedback) {
+  return deliver(config, { event: "feedback.created", feedback });
+}
+async function deliver(config, delivery) {
+  const problem = timeoutProblem(config.timeoutMs);
+  if (problem) return reportError(config, new RangeError(problem), delivery);
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const controller = new AbortController();
+  let timer;
+  try {
+    const body = JSON.stringify(buildDeliveryPayload(config.type ?? "generic", delivery));
+    const custom = config.headers ?? {};
+    const customNames = new Set(Object.keys(custom).map((name) => name.toLowerCase()));
+    const headers = {
+      ...customNames.has("content-type") ? {} : { "Content-Type": "application/json" },
+      ...customNames.has(EVENT_HEADER.toLowerCase()) ? {} : { [EVENT_HEADER]: delivery.event },
+      ...custom
+    };
+    timer = setTimeout(() => controller.abort(), timeoutMs);
+    const response = await fetch(config.url, {
+      method: "POST",
+      headers,
+      body,
+      signal: controller.signal
+    });
+    clearTimeout(timer);
+    if (!response.ok) {
+      const err = new Error(`Webhook responded with HTTP ${response.status}`);
+      await reportError(config, err, delivery);
+    }
+  } catch (rawError) {
+    clearTimeout(timer);
+    const err = rawError instanceof Error ? rawError : new Error(String(rawError));
+    await reportError(config, err, delivery);
+  }
+}
+async function reportError(config, err, delivery) {
+  const { feedbackId, projectName } = deliverySubject(delivery);
+  const subject = feedbackId ? `feedback ${feedbackId}` : `project ${projectName}`;
+  if (config.onError) {
+    try {
+      await config.onError(err, feedbackId, { event: delivery.event, projectName });
+    } catch (callbackErr) {
+      warnWithoutUrl(
+        config.url,
+        `webhook onError() callback threw for ${subject}: ${String(callbackErr)} (original error: ${err.message})`
+      );
+    }
+    return;
+  }
+  warnWithoutUrl(config.url, `webhook to ${webhookOrigin(config.url)} failed for ${subject}: ${err.message}`);
+}
+function webhookOrigin(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return "<invalid URL>";
+  }
+}
+function warnWithoutUrl(url, message) {
+  console.warn(`[siteping] ${url ? message.split(url).join(webhookOrigin(url)) : message}`);
+}
+async function dispatchWebhooks(configs, feedback) {
+  await dispatchDelivery(configs, { event: "feedback.created", feedback });
+}
+async function dispatchDelivery(configs, delivery) {
+  const subscribed = configs.filter((config) => subscribesTo(config, delivery.event));
+  if (subscribed.length === 0) return;
+  await Promise.all(subscribed.map((config) => deliver(config, delivery)));
+}
+
+// src/notify.ts
+function createNotifier(webhooks, waitUntil, pipeline) {
+  return (scope, delivery) => {
+    if (!webhooks.some((config) => subscribesTo(config, delivery.event))) return;
+    const pending = dispatchDelivery(webhooks, delivery);
+    try {
+      waitUntil?.(pending);
+    } catch (error) {
+      const { feedbackId, projectName } = deliverySubject(delivery);
+      pipeline.logError(scope, "[siteping] waitUntil failed", {
+        error,
+        event: delivery.event,
+        ...feedbackId ? { feedbackId } : {},
+        projectName
+      });
+    }
+  };
+}
+
 // src/validation.ts
 var zod = __toESM(require("zod"), 1);
 var z2 = "z" in zod ? zod.z : zod;
@@ -368,9 +779,9 @@ var screenshotRegionSchema = z2.strictObject({
   wPct: z2.number().min(0).max(1),
   hPct: z2.number().min(0).max(1)
 });
-var clientIdSchema = z2.string().min(1).max(200).regex(/^[a-zA-Z0-9_-]+$/, "clientId must be alphanumeric (a-z, A-Z, 0-9, _, -)");
+var clientIdSchema = z2.string().min(1).max(CLIENT_ID_MAX_LENGTH).regex(/^[a-zA-Z0-9_-]+$/, "clientId must be alphanumeric (a-z, A-Z, 0-9, _, -)");
 var feedbackCreateSchema = z2.object({
-  projectName: z2.string().min(1).max(200),
+  projectName: z2.string().min(1).max(PROJECT_NAME_MAX_LENGTH),
   type: z2.enum(FEEDBACK_TYPES),
   message: z2.string().min(1).max(5e3),
   // Page-scope identifier the widget uses to group feedbacks. Defaults to
@@ -408,7 +819,7 @@ var feedbackCreateSchema = z2.object({
   diagnostics: diagnosticsSchema.nullable().optional()
 });
 var commentCreateSchema = z2.object({
-  projectName: z2.string().min(1).max(200),
+  projectName: z2.string().min(1).max(PROJECT_NAME_MAX_LENGTH),
   feedbackId: z2.string().min(1).max(200),
   // Trimmed, so a whitespace-only reply is a 400 rather than an empty bubble.
   body: z2.string().trim().min(1).max(COMMENT_BODY_MAX_LENGTH),
@@ -422,21 +833,21 @@ var commentCreateSchema = z2.object({
   clientId: clientIdSchema
 });
 var commentDeleteSchema = z2.object({
-  projectName: z2.string().min(1).max(200),
+  projectName: z2.string().min(1).max(PROJECT_NAME_MAX_LENGTH),
   feedbackId: z2.string().min(1).max(200),
   commentId: z2.string().min(1).max(200)
 });
 var feedbackPatchSchema = z2.object({
   id: z2.string().min(1),
-  projectName: z2.string().min(1).max(200),
+  projectName: z2.string().min(1).max(PROJECT_NAME_MAX_LENGTH),
   status: z2.enum(FEEDBACK_STATUSES)
 });
 var feedbackDeleteSchema = z2.union([
-  z2.object({ id: z2.string().min(1), projectName: z2.string().min(1).max(200) }),
-  z2.object({ projectName: z2.string().min(1).max(200), deleteAll: z2.literal(true) })
+  z2.object({ id: z2.string().min(1), projectName: z2.string().min(1).max(PROJECT_NAME_MAX_LENGTH) }),
+  z2.object({ projectName: z2.string().min(1).max(PROJECT_NAME_MAX_LENGTH), deleteAll: z2.literal(true) })
 ]);
 var getQuerySchema = z2.object({
-  projectName: z2.string().min(1).max(200),
+  projectName: z2.string().min(1).max(PROJECT_NAME_MAX_LENGTH),
   page: z2.coerce.number().int().min(1).default(1),
   limit: z2.coerce.number().int().min(1).max(100).default(50),
   type: z2.enum(FEEDBACK_TYPES).optional(),
@@ -465,7 +876,9 @@ function formatValidationErrors(error) {
 function createCommentOperation({
   store,
   pipeline,
-  beforeComment
+  notify,
+  beforeComment,
+  onCommentCreated
 }) {
   return async (scope, body) => {
     const payload = pipeline.validate(scope, commentCreateSchema, body);
@@ -478,12 +891,25 @@ function createCommentOperation({
       if (store.verifyProjectOwnership && !await store.verifyProjectOwnership(feedbackId, projectName)) {
         return pipeline.error(scope, 404, ERROR_MESSAGES.feedbackNotFound);
       }
-      const role = authorRole === "team" && await pipeline.canCommentAsTeam(scope) ? "team" : "client";
-      const stored = await store.addComment(feedbackId, { ...comment, authorRole: role });
+      const role = authorRole === "team" && await pipeline.canCommentAsTeam(scope, projectName) ? "team" : "client";
+      const input = { ...comment, authorRole: role };
+      const { comment: stored, created } = store.addCommentIfAbsent ? await store.addCommentIfAbsent(feedbackId, input) : { comment: await store.addComment(feedbackId, input), created: false };
       if (stored.feedbackId !== feedbackId) {
         return pipeline.error(scope, 409, ERROR_MESSAGES.clientIdUsedByAnotherFeedback);
       }
-      return pipeline.json(scope, pipeline.presentCreatedComment(scope, stored), { status: 201 });
+      if (created) {
+        const reply = { ...stored, projectName };
+        notify(scope, { event: "comment.created", comment: reply });
+        if (onCommentCreated) {
+          await pipeline.runHook(
+            scope,
+            "onCommentCreated",
+            { feedbackId, projectName, commentId: stored.id },
+            () => onCommentCreated(reply, scope.context)
+          );
+        }
+      }
+      return pipeline.json(scope, await pipeline.presentCreatedComment(scope, stored, projectName), { status: 201 });
     } catch (error) {
       if (isStoreNotFound(error)) return pipeline.error(scope, 404, ERROR_MESSAGES.feedbackNotFound);
       if (isStoreLimit(error)) return pipeline.error(scope, 409, ERROR_MESSAGES.tooManyComments);
@@ -493,209 +919,6 @@ function createCommentOperation({
   };
 }
 
-// src/webhooks.ts
-var DEFAULT_TIMEOUT_MS = 5e3;
-var TIMER_MAX_DELAY_MS = 2147483647;
-function timeoutProblem(timeoutMs) {
-  if (timeoutMs === void 0 || Number.isSafeInteger(timeoutMs) && timeoutMs > 0 && timeoutMs <= TIMER_MAX_DELAY_MS) {
-    return null;
-  }
-  return `timeoutMs must be a positive integer of at most ${TIMER_MAX_DELAY_MS}, got ${timeoutMs}`;
-}
-function checkWebhookTimeouts(configs) {
-  for (const config of configs) {
-    const problem = timeoutProblem(config.timeoutMs);
-    if (problem) {
-      throw new Error(`[siteping] createSitepingHandler: webhook to ${webhookOrigin(config.url)}: ${problem}.`);
-    }
-  }
-}
-var DISCORD_COLORS = {
-  bug: 15680580,
-  question: 3900150,
-  change: 16096779,
-  other: 7041664
-};
-var DEFAULT_DISCORD_COLOR = 7041664;
-function truncate(text, max = 300) {
-  if (text.length <= max) return text;
-  return `${text.slice(0, max - 1)}\u2026`;
-}
-function fitEscaped(units, max) {
-  const escaped = units.join("");
-  if (escaped.length <= max) return escaped;
-  let out = "";
-  for (const unit of units) {
-    if (out.length + unit.length > max - 1) break;
-    out += unit;
-  }
-  return `${out}\u2026`;
-}
-var SLACK_HEADER_MAX = 150;
-var SLACK_TEXT_MAX = 3e3;
-function escapeSlackText(text) {
-  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}
-function buildSlackPayload(feedback) {
-  const preview = escapeSlackText(truncate(feedback.message));
-  const escapeField = (value, max) => fitEscaped(Array.from(value, escapeSlackText), max);
-  const fromHalf = Math.floor((SLACK_TEXT_MAX - 11) / 2);
-  const headline = `New ${feedback.type} feedback from ${feedback.authorName}`;
-  return {
-    text: `${escapeSlackText(headline)}: ${preview}`,
-    blocks: [
-      {
-        type: "header",
-        text: { type: "plain_text", text: truncate(headline, SLACK_HEADER_MAX), emoji: true }
-      },
-      {
-        type: "section",
-        text: { type: "mrkdwn", text: preview }
-      },
-      {
-        type: "context",
-        elements: [
-          { type: "mrkdwn", text: `*Project:* ${escapeField(feedback.projectName, SLACK_TEXT_MAX - 11)}` },
-          { type: "mrkdwn", text: `*Type:* ${feedback.type}` },
-          { type: "mrkdwn", text: `*URL:* ${escapeField(feedback.url, SLACK_TEXT_MAX - 7)}` },
-          {
-            type: "mrkdwn",
-            text: `*From:* ${escapeField(feedback.authorName, fromHalf)} (${escapeField(feedback.authorEmail, fromHalf)})`
-          }
-        ]
-      }
-    ]
-  };
-}
-var DISCORD_CONTENT_MAX = 2e3;
-var DISCORD_TITLE_MAX = 256;
-var DISCORD_FIELD_VALUE_MAX = 1024;
-var DISCORD_MARKDOWN = /[\\*_~`|>#[\]()<]/g;
-var DISCORD_AUTOLINK = /(<https?:\/\/[^\s<>]+>|https?:\/\/[^\s<>]+)/i;
-var DISCORD_LINK_TRAILER = `.,:;"')]`;
-var escapeMarkdownChar = (char) => char.replace(DISCORD_MARKDOWN, "\\$&");
-var encodeLinkChar = (char) => char.replace(/[[\]()]/g, (bracket) => `%${bracket.charCodeAt(0).toString(16).toUpperCase()}`);
-var count = (text, char) => text.split(char).length - 1;
-function discordUrlUnits(url) {
-  const open = { ")": count(url, "(") - count(url, ")"), "]": count(url, "[") - count(url, "]") };
-  let end = url.length;
-  while (end > 0) {
-    const last = url.charAt(end - 1);
-    if (!DISCORD_LINK_TRAILER.includes(last)) break;
-    if (last === ")" || last === "]") {
-      if (open[last] >= 0) break;
-      open[last] += 1;
-    }
-    end -= 1;
-  }
-  return [...Array.from(url.slice(0, end), encodeLinkChar), ...url.slice(end)];
-}
-function escapeDiscordText(text, max) {
-  const units = text.split(DISCORD_AUTOLINK).flatMap((part, index) => index % 2 === 1 ? discordUrlUnits(part) : Array.from(part, escapeMarkdownChar));
-  return fitEscaped(units, max);
-}
-function buildDiscordPayload(feedback) {
-  const contentLead = `New **${feedback.type}** feedback from **`;
-  const titleLead = `${feedback.type} \u2014 `;
-  const authorHalf = Math.floor((DISCORD_FIELD_VALUE_MAX - 3) / 2);
-  return {
-    content: `${contentLead}${escapeDiscordText(feedback.authorName, DISCORD_CONTENT_MAX - contentLead.length - 2)}**`,
-    embeds: [
-      {
-        title: `${titleLead}${escapeDiscordText(feedback.projectName, DISCORD_TITLE_MAX - titleLead.length)}`,
-        description: escapeDiscordText(feedback.message, 300),
-        color: DISCORD_COLORS[feedback.type] ?? DEFAULT_DISCORD_COLOR,
-        fields: [
-          { name: "URL", value: escapeDiscordText(feedback.url, DISCORD_FIELD_VALUE_MAX), inline: false },
-          {
-            name: "Author",
-            value: `${escapeDiscordText(feedback.authorName, authorHalf)} (${escapeDiscordText(feedback.authorEmail, authorHalf)})`,
-            inline: true
-          },
-          { name: "Viewport", value: escapeDiscordText(feedback.viewport, DISCORD_FIELD_VALUE_MAX), inline: true }
-        ],
-        timestamp: new Date(feedback.createdAt).toISOString()
-      }
-    ],
-    allowed_mentions: { parse: [] }
-  };
-}
-function buildGenericPayload(feedback) {
-  const { clientId: _clientId, comments, ...payload } = feedback;
-  if (!comments) return payload;
-  return { ...payload, comments: comments.map(({ clientId: _commentClientId, ...comment }) => comment) };
-}
-function buildWebhookPayload(type, feedback) {
-  switch (type) {
-    case "slack":
-      return buildSlackPayload(feedback);
-    case "discord":
-      return buildDiscordPayload(feedback);
-    default:
-      return buildGenericPayload(feedback);
-  }
-}
-async function dispatchWebhook(config, feedback) {
-  const problem = timeoutProblem(config.timeoutMs);
-  if (problem) return reportError(config, new RangeError(problem), feedback.id);
-  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const controller = new AbortController();
-  let timer;
-  try {
-    const body = JSON.stringify(buildWebhookPayload(config.type ?? "generic", feedback));
-    const custom = config.headers ?? {};
-    const setsContentType = Object.keys(custom).some((name) => name.toLowerCase() === "content-type");
-    const headers = setsContentType ? custom : { "Content-Type": "application/json", ...custom };
-    timer = setTimeout(() => controller.abort(), timeoutMs);
-    const response = await fetch(config.url, {
-      method: "POST",
-      headers,
-      body,
-      signal: controller.signal
-    });
-    clearTimeout(timer);
-    if (!response.ok) {
-      const err = new Error(`Webhook responded with HTTP ${response.status}`);
-      await reportError(config, err, feedback.id);
-    }
-  } catch (rawError) {
-    clearTimeout(timer);
-    const err = rawError instanceof Error ? rawError : new Error(String(rawError));
-    await reportError(config, err, feedback.id);
-  }
-}
-async function reportError(config, err, feedbackId) {
-  if (config.onError) {
-    try {
-      await config.onError(err, feedbackId);
-    } catch (callbackErr) {
-      warnWithoutUrl(
-        config.url,
-        `webhook onError() callback threw for feedback ${feedbackId}: ${String(callbackErr)} (original error: ${err.message})`
-      );
-    }
-    return;
-  }
-  warnWithoutUrl(
-    config.url,
-    `webhook to ${webhookOrigin(config.url)} failed for feedback ${feedbackId}: ${err.message}`
-  );
-}
-function webhookOrigin(url) {
-  try {
-    return new URL(url).origin;
-  } catch {
-    return "<invalid URL>";
-  }
-}
-function warnWithoutUrl(url, message) {
-  console.warn(`[siteping] ${url ? message.split(url).join(webhookOrigin(url)) : message}`);
-}
-async function dispatchWebhooks(configs, feedback) {
-  if (configs.length === 0) return;
-  await Promise.all(configs.map((c) => dispatchWebhook(c, feedback)));
-}
-
 // src/operations/create-feedback.ts
 var FAILED_TO_CREATE = "[siteping] Failed to create feedback";
 function toCreateInput(data) {
@@ -720,8 +943,7 @@ function toCreateInput(data) {
 function createFeedbackOperation({
   store,
   pipeline,
-  webhooks,
-  waitUntil,
+  notify,
   beforeCreate,
   onCreated
 }) {
@@ -781,14 +1003,7 @@ function createFeedbackOperation({
     const subject = { feedbackId: feedback.id, projectName: feedback.projectName };
     try {
       if (owner && inserted && feedback.projectName === input.projectName) {
-        if (webhooks.length > 0) {
-          const delivery = dispatchWebhooks(webhooks, feedback);
-          try {
-            waitUntil?.(delivery);
-          } catch (error) {
-            pipeline.logError(scope, "[siteping] waitUntil failed", { error, ...subject });
-          }
-        }
+        notify(scope, { event: "feedback.created", feedback });
         if (onCreated) await pipeline.runHook(scope, "onCreated", subject, () => onCreated(feedback, scope.context));
       }
       if (feedback.projectName !== input.projectName) {
@@ -827,6 +1042,7 @@ function deleteCommentOperation({ store, pipeline }) {
 function deleteFeedbackOperation({
   store,
   pipeline,
+  notify,
   onDeleting,
   onDeleted
 }) {
@@ -853,6 +1069,7 @@ function deleteFeedbackOperation({
       }
       if (target.kind === "project") await store.deleteAllFeedbacks(target.projectName);
       else await store.deleteFeedback(target.id);
+      notify(scope, { event: "feedback.deleted", target });
       if (onDeleted) await pipeline.runHook(scope, "onDeleted", { target }, () => onDeleted(target, scope.context));
       return pipeline.json(scope, { deleted: true });
     } catch (error) {
@@ -893,6 +1110,8 @@ function listFeedbacksOperation({ store, pipeline }) {
         {
           ...page,
           feedbacks,
+          // Lets clients rely on what a protocol version added instead of probing for fields.
+          protocol: SITEPING_PROTOCOL_VERSION,
           // Lets clients hide their comment composer, and delete buttons, up front instead of meeting a 501.
           capabilities: {
             comments: store.addComment !== void 0,
@@ -913,6 +1132,7 @@ function listFeedbacksOperation({ store, pipeline }) {
 function updateFeedbackOperation({
   store,
   pipeline,
+  notify,
   onUpdated
 }) {
   return async (request) => {
@@ -929,6 +1149,7 @@ function updateFeedbackOperation({
         return pipeline.error(scope, 404, ERROR_MESSAGES.feedbackNotFound);
       }
       const feedback = await store.updateFeedback(id, toFeedbackUpdate(status));
+      notify(scope, { event: "feedback.status_changed", feedback });
       if (onUpdated) {
         const subject = { feedbackId: feedback.id, projectName: feedback.projectName };
         await pipeline.runHook(scope, "onUpdated", subject, () => onUpdated(feedback, scope.context));
@@ -1071,14 +1292,26 @@ function createPipeline({
     ]);
     return { canChangeStatus, canDelete, canComment, canDeleteComment };
   };
-  const present = async (scope, feedback, includeEmail = scope.canReadAuthorEmail) => ({
-    ...toWireFeedback(
-      presentFeedback ? presentFeedback(feedback, scope.context) : feedback,
-      includeEmail,
-      scope.canReadAuthorEmail
-    ),
-    permissions: await permissions(scope, feedback)
+  const commentPermissions = async (scope, thread, commentId, canDeleteThread) => ({
+    canDelete: canDeleteThread || await may(scope, "DELETE", { action: "deleteComment", ...thread, commentId })
   });
+  const present = async (scope, feedback, echoEmail = false) => {
+    const canReadEmails = await scope.canReadAuthorEmail(feedback.projectName);
+    const wire = toWireFeedback(
+      presentFeedback ? presentFeedback(feedback, scope.context) : feedback,
+      echoEmail || canReadEmails,
+      canReadEmails
+    );
+    const granted = await permissions(scope, feedback);
+    const thread = { projectName: feedback.projectName, feedbackId: feedback.id };
+    const comments = await Promise.all(
+      wire.comments.map(async (comment) => ({
+        ...comment,
+        permissions: await commentPermissions(scope, thread, comment.id, granted.canDeleteComment)
+      }))
+    );
+    return { ...wire, comments, permissions: granted };
+  };
   return {
     json,
     error,
@@ -1114,12 +1347,21 @@ function createPipeline({
         };
       }
       if (!outcome.ok) return { ok: false, response: error({ corsHeaders }, outcome.status, outcome.error) };
+      const context = { request, principal: outcome.principal };
+      const emailAccess = /* @__PURE__ */ new Map();
       return {
         ok: true,
         value: {
-          context: { request, principal: outcome.principal },
+          context,
           corsHeaders,
-          canReadAuthorEmail: outcome.canReadAuthorEmail
+          canReadAuthorEmail(projectName) {
+            let answer = emailAccess.get(projectName);
+            if (!answer) {
+              answer = gate.canReadAuthorEmail(context, projectName);
+              emailAccess.set(projectName, answer);
+            }
+            return answer;
+          }
         }
       };
     },
@@ -1129,9 +1371,16 @@ function createPipeline({
       const body = await readJson(scope);
       return body.ok ? validate(scope, schema, body.value) : body;
     },
-    /** `null` when the policy allows the request, its 403 otherwise. */
+    /**
+     * `null` when the policy allows the request, its 403 otherwise. An
+     * allowed request also settles its email access for the project now,
+     * before anything is written: a throwing `canReadAuthorEmail` answers
+     * the operation's 500 with nothing stored.
+     */
     async authorize(scope, target) {
-      return await gate.authorize({ ...scope.context, ...target }) ? null : error(scope, 403, ERROR_MESSAGES.forbidden);
+      if (!await gate.authorize({ ...scope.context, ...target })) return error(scope, 403, ERROR_MESSAGES.forbidden);
+      await scope.canReadAuthorEmail(target.projectName);
+      return null;
     },
     /**
      * Wire shape of a record answering a POST (fresh or replayed): the
@@ -1139,15 +1388,29 @@ function createPipeline({
      * its submitter — who supplied the feedback's, never its thread's.
      */
     presentCreated(scope, feedback) {
-      return present(scope, feedback, gate.echoesAuthorEmailOnCreate || scope.canReadAuthorEmail);
+      return present(scope, feedback, gate.echoesAuthorEmailOnCreate);
     },
-    /** Wire shape of a comment answering a POST — the same echo rule as {@link presentCreated}. */
-    presentCreatedComment(scope, comment) {
-      return toWireComment(comment, gate.echoesAuthorEmailOnCreate || scope.canReadAuthorEmail);
+    /**
+     * Wire shape of a comment answering a POST, in `projectName`'s thread —
+     * the same echo rule as {@link presentCreated}, with its permissions.
+     */
+    async presentCreatedComment(scope, comment, projectName) {
+      const thread = { projectName, feedbackId: comment.feedbackId };
+      const [canReadEmails, canDeleteThread] = await Promise.all([
+        scope.canReadAuthorEmail(projectName),
+        may(scope, "DELETE", { action: "deleteComment", ...thread })
+      ]);
+      return {
+        ...toWireComment(comment, gate.echoesAuthorEmailOnCreate || canReadEmails),
+        permissions: await commentPermissions(scope, thread, comment.id, canDeleteThread)
+      };
     },
-    /** Whether this caller's comment keeps the `team` role it asks for — see `AccessGate.canCommentAsTeam`. */
-    canCommentAsTeam(scope) {
-      return gate.canCommentAsTeam(scope.context, scope.canReadAuthorEmail);
+    /**
+     * Whether this caller's comment in `projectName` keeps the `team` role it
+     * asks for — see `AccessGate.canCommentAsTeam`.
+     */
+    async canCommentAsTeam(scope, projectName) {
+      return gate.canCommentAsTeam(scope.context, projectName, await scope.canReadAuthorEmail(projectName));
     },
     /**
      * Answer a value the store cannot hold with a 422, which a client does
@@ -1217,15 +1480,17 @@ function createSitepingHandler(options) {
     maxBodyBytes = DEFAULT_MAX_BODY_BYTES
   } = options;
   if (!store) {
-    throw new Error("[siteping] createSitepingHandler requires a `store`.");
+    throw new SitepingConfigError("CONFIG_STORE_MISSING", "[siteping] createSitepingHandler requires a `store`.");
   }
   if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes <= 0) {
-    throw new Error(
+    throw new SitepingConfigError(
+      "CONFIG_MAX_BODY_BYTES_INVALID",
       `[siteping] createSitepingHandler: \`maxBodyBytes\` must be a positive integer, got ${maxBodyBytes}.`
     );
   }
   if (options.access?.authorize && !store.verifyProjectOwnership) {
-    throw new Error(
+    throw new SitepingConfigError(
+      "CONFIG_OWNERSHIP_CHECK_MISSING",
       "[siteping] createSitepingHandler: `access.authorize` needs a store implementing `verifyProjectOwnership`. Without it, a caller authorized for one project could PATCH or DELETE another project's feedback by id."
     );
   }
@@ -1233,26 +1498,37 @@ function createSitepingHandler(options) {
   const logger = customLogger ? safeLogger(customLogger) : consoleLogger;
   const pipeline = createPipeline({ gate, allowedOrigins, logger, describeError, presentFeedback, maxBodyBytes });
   const webhookList = webhooks ? Array.isArray(webhooks) ? webhooks : [webhooks] : [];
-  checkWebhookTimeouts(webhookList);
+  checkWebhookConfigs(webhookList);
+  if (!store.addCommentIfAbsent && (hooks.onCommentCreated || webhookList.some((config) => subscribesTo(config, "comment.created")))) {
+    throw new Error(
+      "[siteping] createSitepingHandler: `comment.created` webhooks and the `onCommentCreated` hook need a store implementing `addCommentIfAbsent`, which tells a new reply from a retried one."
+    );
+  }
+  const notify = createNotifier(webhookList, waitUntil, pipeline);
   return {
     OPTIONS: (request) => preflightResponse(request, allowedOrigins),
     POST: routeByBody(
       pipeline,
       "POST",
       "feedbackId",
-      createCommentOperation({ store, pipeline, beforeComment }),
+      createCommentOperation({
+        store,
+        pipeline,
+        notify,
+        beforeComment,
+        onCommentCreated: hooks.onCommentCreated?.bind(hooks)
+      }),
       createFeedbackOperation({
         store,
         pipeline,
-        webhooks: webhookList,
-        waitUntil,
+        notify,
         beforeCreate,
         // Bound so hooks written as class methods keep their `this`.
         onCreated: hooks.onCreated?.bind(hooks)
       })
     ),
     GET: listFeedbacksOperation({ store, pipeline }),
-    PATCH: updateFeedbackOperation({ store, pipeline, onUpdated: hooks.onUpdated?.bind(hooks) }),
+    PATCH: updateFeedbackOperation({ store, pipeline, notify, onUpdated: hooks.onUpdated?.bind(hooks) }),
     DELETE: routeByBody(
       pipeline,
       "DELETE",
@@ -1261,6 +1537,7 @@ function createSitepingHandler(options) {
       deleteFeedbackOperation({
         store,
         pipeline,
+        notify,
         onDeleting: hooks.onDeleting?.bind(hooks),
         onDeleted: hooks.onDeleted?.bind(hooks)
       })