@siteping/server 0.1.1 → 0.2.0

package/dist/index.d.cts

@@ -1,14 +1,17 @@
-import { Prettify, Serialized, FeedbackRecord, CommentResponse, SitepingStore, FeedbackCreateInput, CommentPayload, FeedbackStatus, FeedbackType } from './siteping-core.cjs';
-export { CommentCreateInput, CommentPayload, FeedbackCreateInput, FeedbackRecord, SitepingStore } from './siteping-core.cjs';
+import { Prettify, Serialized, FeedbackRecord, CommentResponse, CommentRecord, SitepingStore, FeedbackCreateInput, CommentPayload, SitepingLogger, FeedbackStatus, FeedbackType } from './siteping-core.cjs';
+export { CommentCreateInput, CommentCreateOutcome, CommentPayload, CommentRecord, CommentResponse, DiagnosticsSnapshot, FeedbackCreateInput, FeedbackListPermissions, FeedbackPermissions, FeedbackRecord, FeedbackResponse, FeedbackResponseList, FeedbackStatus, FeedbackType, SITEPING_PROTOCOL_VERSION, ScreenshotRegion, SitepingCapabilities, SitepingConfigErrorCode, SitepingLogger, SitepingStore, isSitepingConfigError } from './siteping-core.cjs';
 
 /**
- * Outgoing webhook notifications for newly-created feedbacks.
+ * Outgoing webhook notifications.
  *
  * Plug a Slack, Discord, or generic HTTP endpoint into `createSitepingHandler`
- * to receive a payload whenever a feedback is successfully persisted. Webhooks
- * are dispatched as fire-and-forget (`void Promise.all(...)`) so a slow or
- * down receiver never blocks the client response — the feedback is already in
- * the DB by the time we dial out.
+ * to receive a payload once a write succeeds: a feedback created (the
+ * default), its status changed, a feedback or a project's feedback deleted,
+ * a reply posted — each webhook picks its `events`, and every delivery names
+ * its event in the `X-Siteping-Event` header. Webhooks are dispatched as
+ * fire-and-forget (`void Promise.all(...)`) so a slow or down receiver never
+ * blocks the client response — the write is already in the DB by the time we
+ * dial out.
  *
  * - **Type-specific formatting**: Slack uses `{ text, blocks }`, Discord uses
  *   `{ content, embeds }`, generic posts the record as JSON (minus `clientId`).
@@ -17,13 +20,30 @@ export { CommentCreateInput, CommentPayload, FeedbackCreateInput, FeedbackRecord
  *   mention parsing disabled, so a public feedback form can never be turned
  *   into a channel-wide ping or a disguised link.
  * - **Timeout**: 5s by default (overridable per webhook).
- * - **Error handling**: `config.onError(err, feedback.id)` is invoked when
- *   present; otherwise we log a one-liner to `console.warn` so the issue is
- *   surfaced without crashing the request.
+ * - **Error handling**: `config.onError(err, feedbackId, delivery)` is invoked
+ *   when present; otherwise we log a one-liner to `console.warn` so the issue
+ *   is surfaced without crashing the request.
  */
 
 /** Supported webhook integrations — drives the JSON body shape. */
 type WebhookType = "slack" | "discord" | "generic";
+/**
+ * What a delivery reports — sent as its `X-Siteping-Event` header, and what a
+ * webhook's `events` subscribes to:
+ *
+ * - `feedback.created` — a feedback was stored (never for a replayed `clientId`).
+ * - `feedback.status_changed` — a PATCH set a feedback's status, even the one it had.
+ * - `feedback.deleted` — one feedback, or every feedback of a project, was deleted.
+ * - `comment.created` — a reply was stored (never for a replayed `clientId`).
+ */
+type WebhookEvent = keyof GenericWebhookEventMap;
+/** Every {@link WebhookEvent}, in the order above — e.g. to validate an `X-Siteping-Event` header. */
+declare const WEBHOOK_EVENTS: readonly ["feedback.created", "feedback.status_changed", "feedback.deleted", "comment.created"];
+/** What `onError` learns about the failed delivery, beyond the feedback id. */
+interface WebhookDeliveryInfo {
+    event: WebhookEvent;
+    projectName: string;
+}
 /**
  * Outgoing webhook configuration.
  *
@@ -33,18 +53,24 @@ type WebhookType = "slack" | "discord" | "generic";
  *   Useful for signed-payload schemes (`X-Signature`, bearer tokens, …).
  * - `timeoutMs` — abort the fetch after this many ms: a positive integer of
  *   at most 2,147,483,647, the longest delay a timer holds. Defaults to 5000.
- * - `onError` — invoked with the underlying error and the feedback id when
- *   the dispatch fails (network error, non-2xx, timeout). The webhook is
- *   fire-and-forget, so this is your only chance to observe failures. An
- *   async one is awaited: the delivery `waitUntil` holds covers it, and its
- *   rejection is reported like a throw, never left unhandled.
+ * - `events` — the {@link WebhookEvent}s this webhook receives: a non-empty
+ *   list, defaulting to `["feedback.created"]`, so a webhook set up before
+ *   events existed gets exactly the deliveries it always did.
+ * - `onError` — invoked with the underlying error, the id of the feedback the
+ *   delivery is about (`""` for a project-wide deletion) and the delivery's
+ *   event and project, when the dispatch fails (network error, non-2xx,
+ *   timeout). The webhook is fire-and-forget, so this is your only chance to
+ *   observe failures. An async one is awaited: the delivery `waitUntil` holds
+ *   covers it, and its rejection is reported like a throw, never left
+ *   unhandled.
  */
 interface WebhookConfig {
     url: string;
     type?: WebhookType;
     headers?: Record<string, string>;
     timeoutMs?: number;
-    onError?: (err: Error, feedbackId: string) => void | Promise<void>;
+    events?: ReadonlyArray<WebhookEvent>;
+    onError?: (err: Error, feedbackId: string, delivery: WebhookDeliveryInfo) => void | Promise<void>;
 }
 /** Block Kit envelope used by Slack incoming webhooks. */
 interface SlackWebhookPayload {
@@ -105,6 +131,31 @@ interface DiscordWebhookPayload {
 type GenericWebhookPayload = Prettify<Serialized<Omit<FeedbackRecord, "clientId" | "comments">> & {
     comments?: CommentResponse[] | undefined;
 }>;
+/**
+ * Generic body of `feedback.deleted` — what was deleted, as the `onDeleting`
+ * and `onDeleted` hooks receive it: `{ kind: "single", id, projectName }` for
+ * one feedback, `{ kind: "project", projectName }` for a `deleteAll`, which
+ * fires even when the project held nothing (stores report no count).
+ */
+type GenericWebhookDeletionPayload = SitepingDeletionTarget;
+/**
+ * Generic body of `comment.created` — the stored comment as the receiver
+ * parses it (`createdAt` an ISO string, `clientId` stripped), plus the
+ * project its feedback belongs to. The author's email is unredacted, like
+ * the feedback's in {@link GenericWebhookPayload}.
+ */
+type GenericWebhookCommentPayload = Prettify<Serialized<Omit<SitepingCreatedComment, "clientId">>>;
+/**
+ * The generic body of each {@link WebhookEvent} — what a `"generic"` receiver
+ * parses, read from its `X-Siteping-Event` header. `feedback.created` and
+ * `feedback.status_changed` both carry the feedback as stored after the write.
+ */
+interface GenericWebhookEventMap {
+    "feedback.created": GenericWebhookPayload;
+    "feedback.status_changed": GenericWebhookPayload;
+    "feedback.deleted": GenericWebhookDeletionPayload;
+    "comment.created": GenericWebhookCommentPayload;
+}
 /** Mapping from webhook type to its concrete body shape. */
 interface WebhookPayloadMap {
     slack: SlackWebhookPayload;
@@ -112,20 +163,24 @@ interface WebhookPayloadMap {
     generic: GenericWebhookPayload;
 }
 /**
- * Dispatch a single webhook. Fire-and-forget: never throws, never rejects.
+ * Dispatch a single webhook with `feedback`'s `feedback.created` delivery,
+ * whatever its `events` — the handler routes by `events` itself (see
+ * {@link dispatchWebhooks}). Fire-and-forget: never throws, never rejects.
  *
  * - Builds the type-specific payload.
- * - POSTs with an `AbortSignal` timeout.
+ * - POSTs with an `AbortSignal` timeout and an `X-Siteping-Event` header.
  * - On any error (network, non-2xx, timeout, exception), invokes
- *   `config.onError(err, feedbackId)` if provided; otherwise logs a one-liner.
- *   A `timeoutMs` no timer holds is such an error: nothing is sent.
+ *   `config.onError(err, feedbackId, delivery)` if provided; otherwise logs a
+ *   one-liner. A `timeoutMs` no timer holds is such an error: nothing is sent.
  */
 declare function dispatchWebhook(config: WebhookConfig, feedback: FeedbackRecord): Promise<void>;
 /**
- * Dispatch every configured webhook in parallel. Awaiting the returned promise
- * lets tests synchronize on completion, but production callers should drop the
- * promise on the floor (`void dispatchWebhooks(...)`) so the HTTP response
- * isn't held back on slow receivers.
+ * Dispatch `feedback`'s `feedback.created` delivery to every configured
+ * webhook that subscribes to it (every webhook without `events`), in
+ * parallel. Awaiting the returned promise lets tests synchronize on
+ * completion, but production callers should drop the promise on the floor
+ * (`void dispatchWebhooks(...)`) so the HTTP response isn't held back on slow
+ * receivers.
  */
 declare function dispatchWebhooks(configs: readonly WebhookConfig[], feedback: FeedbackRecord): Promise<void>;
 
@@ -139,6 +194,16 @@ interface SitepingRequestContext<Principal> {
     /** Whoever `access.authenticate` resolved — always `null` under the `apiKey` policy. */
     principal: Principal;
 }
+/**
+ * The project a response is about, and the request it answers — what
+ * `canReadAuthorEmail` and `canCommentAsTeam` decide for, beside the
+ * principal.
+ */
+interface SitepingProjectContext {
+    request: Request;
+    /** Project of the records the response carries, or of the thread a comment joins. */
+    projectName: string;
+}
 /** What `SitepingAccessControl.authorize` decides about. */
 interface SitepingAuthorizationContext<Principal> extends SitepingRequestContext<Principal> {
     action: SitepingAction;
@@ -147,8 +212,9 @@ interface SitepingAuthorizationContext<Principal> extends SitepingRequestContext
     /** Target record of `update` and `delete`; the feedback whose thread `createComment` and `deleteComment` target. */
     feedbackId?: string;
     /**
-     * Target comment of `deleteComment` — absent on a `dryRun`, whose answer
-     * covers the feedback's whole thread.
+     * Target comment of `deleteComment`. A `dryRun` asks first without one,
+     * for the feedback's whole thread; when that answer is `false`, it asks
+     * again for each comment of the thread, with its id.
      */
     commentId?: string;
     /**
@@ -176,34 +242,39 @@ type SitepingPrincipal = object | string | number;
  *   check is what binds the authorized `projectName` to the record. It is
  *   also asked, with `dryRun: true`, to fill in the `permissions` of every
  *   feedback a response carries — `update`, `delete`, `createComment` and
- *   `deleteComment` (without a `commentId`) per feedback, plus `deleteAll`
- *   once per list — so clients hide what it would refuse. A dry run that
- *   throws refuses that permission (logged) rather than failing the
- *   response. Keep it fast: a page of 50 feedbacks takes 201 dry runs, 8
- *   at a time, sharing the one `request` — cache lookups per request. That
- *   request is the response's whatever the action, and `authenticate` is
- *   not asked again: a principal it admits on some methods only needs
- *   `authorize` to refuse it the other actions.
+ *   `deleteComment` (without a `commentId`, for the whole thread) per
+ *   feedback, plus `deleteAll` once per list — so clients hide what it
+ *   would refuse. When the thread-wide `deleteComment` answer is `false`,
+ *   each comment is asked about with its `commentId`, for its own
+ *   `permissions`. A dry run that throws refuses that permission (logged)
+ *   rather than failing the response. Keep it fast: a page of 50 feedbacks
+ *   takes 201 dry runs, plus one per comment of a thread it refuses
+ *   wholesale, 8 at a time, sharing the one `request` — cache lookups per
+ *   request. That request is the response's whatever the action, and
+ *   `authenticate` is not asked again: a principal it admits on some
+ *   methods only needs `authorize` to refuse it the other actions.
  * - `canReadAuthorEmail` decides whether responses include `authorEmail`
  *   (reviewer PII), on feedbacks and their comments — the list, the PATCH
- *   answer and the POST answer alike. Only `true` includes it: without the
- *   callback, every response blanks it. A policy that serves anonymous
- *   visitors resolves a principal for them too, so being authenticated says
- *   nothing about who may read reviewers' emails.
+ *   answer and the POST answer alike. It is asked once per request, for the
+ *   project the request targets (`context.projectName`). Only `true`
+ *   includes it: without the callback, every response blanks it. A policy
+ *   that serves anonymous visitors resolves a principal for them too, so
+ *   being authenticated says nothing about who may read reviewers' emails.
  * - `canCommentAsTeam` decides whether a comment that asks for the `team`
- *   role keeps it; otherwise it is stamped `client`. Defaults to the
- *   principal's `canReadAuthorEmail` answer (whoever may read reviewer
- *   emails is on the project side), so a policy that sets neither never
- *   lets a caller speak as the team. Once set, anything but `true`
- *   (`undefined` from plain JavaScript included) refuses.
+ *   role keeps it, in the project of its thread; otherwise it is stamped
+ *   `client`. Defaults to the principal's `canReadAuthorEmail` answer for
+ *   that project (whoever may read reviewer emails is on the project side),
+ *   so a policy that sets neither never lets a caller speak as the team.
+ *   Once set, anything but `true` (`undefined` from plain JavaScript
+ *   included) refuses.
  *
- * A throw from any of them answers a logged 500.
+ * A throw from any of them answers a logged 500, before anything is written.
  */
 interface SitepingAccessControl<Principal extends SitepingPrincipal> {
     authenticate(request: Request): Principal | null | undefined | Promise<Principal | null | undefined>;
     authorize?(context: SitepingAuthorizationContext<Principal>): boolean | Promise<boolean>;
-    canReadAuthorEmail?(principal: Principal): boolean | Promise<boolean>;
-    canCommentAsTeam?(principal: Principal): boolean | Promise<boolean>;
+    canReadAuthorEmail?(principal: Principal, context: SitepingProjectContext): boolean | Promise<boolean>;
+    canCommentAsTeam?(principal: Principal, context: SitepingProjectContext): boolean | Promise<boolean>;
 }
 /**
  * What a DELETE removes: one record, or a whole project (`deleteAll`) —
@@ -217,15 +288,28 @@ type SitepingDeletionTarget = {
     kind: "project";
     projectName: string;
 };
+/**
+ * A stored reply, as `onCommentCreated` and the `comment.created` webhook
+ * receive it: the comment record plus the project of its feedback — the one
+ * the request named, checked against the feedback when the store implements
+ * `verifyProjectOwnership`.
+ */
+interface SitepingCreatedComment extends CommentRecord {
+    projectName: string;
+}
 /**
  * Side effects around persistence — issue trackers, chat notifications,
  * search indexes, audit logs. Hooks receive the stored record, `clientId` and
  * `authorEmail` included.
  *
- * `onCreated`, `onUpdated` and `onDeleted` are awaited before the response
- * (so serverless runtimes do not freeze them mid-flight); a throw is logged
- * and never fails the request — the write already happened. `onCreated`
- * runs once per inserted feedback, never for a replayed `clientId`.
+ * `onCreated`, `onUpdated`, `onDeleted` and `onCommentCreated` are awaited
+ * before the response (so serverless runtimes do not freeze them
+ * mid-flight); a throw is logged and never fails the request — the write
+ * already happened. `onCreated` runs once per inserted feedback and
+ * `onCommentCreated` once per inserted reply, never for a replayed
+ * `clientId`; `onCommentCreated` needs a store implementing
+ * `addCommentIfAbsent`, which tells the two apart (the handler refuses to
+ * start without it).
  * `onDeleting` runs before the delete: throw to abort it (the record is kept
  * and the request answers 502), e.g. when a resource tied to the feedback
  * could not be cleaned up and the delete must be retried.
@@ -235,19 +319,7 @@ interface SitepingLifecycleHooks<Principal> {
     onUpdated?(feedback: FeedbackRecord, context: SitepingRequestContext<Principal>): void | Promise<void>;
     onDeleting?(target: SitepingDeletionTarget, context: SitepingRequestContext<Principal>): void | Promise<void>;
     onDeleted?(target: SitepingDeletionTarget, context: SitepingRequestContext<Principal>): void | Promise<void>;
-}
-/**
- * Where the handler reports unexpected failures. Defaults to `console.error`.
- * A logger that throws, or returns a promise that rejects (a log shipper
- * down), falls back to `console.error`: it never fails the request, nor
- * leaves a rejection unhandled.
- *
- * The arguments come in console's and winston's order. pino's `error` takes
- * the context first and type-checks here anyway, then drops the context:
- * adapt it — `{ error: (message, { error, ...context }) => log.error({ err: error, ...context }, message) }`.
- */
-interface SitepingLogger {
-    error(message: string, context: Record<string, unknown>): void | Promise<void>;
+    onCommentCreated?(comment: SitepingCreatedComment, context: SitepingRequestContext<Principal>): void | Promise<void>;
 }
 /** Options shared by both access policies. */
 interface SitepingHandlerBaseOptions<Principal> {
@@ -268,13 +340,18 @@ interface SitepingHandlerBaseOptions<Principal> {
      */
     maxBodyBytes?: number | undefined;
     /**
-     * Outgoing webhooks fired after a feedback is successfully persisted.
+     * Outgoing webhooks fired after a write succeeds — by default when a
+     * feedback is stored; each config's `events` opts into status changes,
+     * deletions and replies (see `WebhookEvent`).
      *
-     * Pass a single config or an array — every entry receives a POST with a
-     * type-specific payload (Slack, Discord, or generic JSON). Dispatch is
+     * Pass a single config or an array — every entry subscribed to an event
+     * receives a POST with a type-specific payload (Slack, Discord, or generic
+     * JSON) and an `X-Siteping-Event` header naming it. Dispatch is
      * fire-and-forget: the HTTP response is returned to the widget before
      * webhook delivery completes, so a slow receiver never blocks the client.
-     * Provide `onError` on each config to observe failures.
+     * Provide `onError` on each config to observe failures. A `comment.created`
+     * subscription needs a store implementing `addCommentIfAbsent` (the
+     * handler refuses to start without it).
      */
     webhooks?: WebhookConfig | ReadonlyArray<WebhookConfig>;
     /**
@@ -282,7 +359,7 @@ interface SitepingHandlerBaseOptions<Principal> {
      * or cancel them once the response is sent (serverless functions, edge
      * workers): Next.js `after`, `waitUntil` from `@vercel/functions` or from
      * `cloudflare:workers` — a standalone function, not an unbound method.
-     * Called once per notified feedback with a promise that never rejects; a
+     * Called once per notified event with a promise that never rejects; a
      * throw is logged and the delivery still runs.
      */
     waitUntil?: ((promise: Promise<unknown>) => void) | undefined;
@@ -313,8 +390,15 @@ interface SitepingHandlerBaseOptions<Principal> {
     presentFeedback?(feedback: FeedbackRecord, context: SitepingRequestContext<Principal>): FeedbackRecord;
     /** Lifecycle side effects — see `SitepingLifecycleHooks`. */
     hooks?: SitepingLifecycleHooks<Principal>;
-    /** Where unexpected failures are reported. Defaults to `console.error`. */
-    logger?: SitepingLogger;
+    /**
+     * Where unexpected failures are reported, through `error` — the one level
+     * the handler uses, so `{ error }` alone is enough. Defaults to
+     * `console.error`. A logger that throws, or returns a promise that rejects
+     * (a log shipper down), falls back to `console.error`: it never fails the
+     * request, nor leaves a rejection unhandled. adapter-prisma also hands it
+     * to the `PrismaStore` it builds when it takes warnings (`warn`).
+     */
+    logger?: SitepingLogger | undefined;
     /**
      * Map an unexpected failure to the `error` string sent to the client.
      * Return `undefined` for the default (`"Internal server error"`). Store
@@ -485,4 +569,5 @@ interface ValidationIssue {
     message: string;
 }
 
-export { type DiscordWebhookPayload, type FeedbackDeleteInput, type FeedbackPatchInput, type GenericWebhookPayload, type GetQueryInput, type SitepingAccessControl, type SitepingAccessHandlerOptions, type SitepingAction, type SitepingApiKeyHandlerOptions, type SitepingAuthorizationContext, type SitepingDeletionTarget, type SitepingHandler, type SitepingHandlerBaseOptions, type SitepingHandlerOptions, type SitepingHttpMethod, type SitepingLifecycleHooks, type SitepingLogger, type SitepingPrincipal, type SitepingRequestContext, type SlackWebhookPayload, type ValidationIssue, type WebhookConfig, type WebhookPayloadMap, type WebhookType, createSitepingHandler, dispatchWebhook, dispatchWebhooks };
+export { WEBHOOK_EVENTS, createSitepingHandler, dispatchWebhook, dispatchWebhooks };
+export type { DiscordWebhookPayload, FeedbackDeleteInput, FeedbackPatchInput, GenericWebhookCommentPayload, GenericWebhookDeletionPayload, GenericWebhookEventMap, GenericWebhookPayload, GetQueryInput, SitepingAccessControl, SitepingAccessHandlerOptions, SitepingAction, SitepingApiKeyHandlerOptions, SitepingAuthorizationContext, SitepingCreatedComment, SitepingDeletionTarget, SitepingHandler, SitepingHandlerBaseOptions, SitepingHandlerOptions, SitepingHttpMethod, SitepingLifecycleHooks, SitepingPrincipal, SitepingProjectContext, SitepingRequestContext, SlackWebhookPayload, ValidationIssue, WebhookConfig, WebhookDeliveryInfo, WebhookEvent, WebhookPayloadMap, WebhookType };