@beezping/adapter-prisma 0.7.0 → 0.8.0

package/dist/index.d.cts

@@ -1,189 +1,7 @@
-import { FeedbackPayload, SitepingStore, ScreenshotStorage, FeedbackCreateInput, FeedbackRecord as FeedbackRecord$1, FeedbackQuery, FeedbackPage, FeedbackUpdateInput } from './siteping-core.cjs';
-export { ScreenshotStorage, SitepingStore, StoreDuplicateError, StoreNotFoundError, StorePersistenceError, flattenAnnotation, isStorePersistence } from './siteping-core.cjs';
-import { FeedbackStatus, FeedbackRecord, FeedbackType } from './siteping-core.js';
-
-/** HTTP methods served by `createSitepingHandler`. */
-type SitepingHttpMethod = "GET" | "POST" | "PATCH" | "DELETE" | "OPTIONS";
-
-/** Options of the built-in shared-secret policy (the historical `adapter-prisma` behavior). */
-interface ApiKeyAccessOptions {
-    /**
-     * Shared secret expected as `Authorization: Bearer {apiKey}`.
-     *
-     * - **When set:** every request not listed in `publicEndpoints` must carry it (401 otherwise).
-     * - **When not set:** the API is public, except DELETE/PATCH while
-     *   `requireAuthForDestructive` is on.
-     */
-    apiKey?: string | undefined;
-    /** Methods that skip the key. Defaults to `['POST', 'OPTIONS']` when `apiKey` is set. */
-    publicEndpoints?: ReadonlyArray<SitepingHttpMethod>;
-    /**
-     * Whether DELETE/PATCH require `apiKey`. Defaults to `true`: without `apiKey`
-     * the handler refuses to start in production and answers 401 elsewhere.
-     * Set `false` only behind your own auth layer — or pass `access` instead.
-     */
-    requireAuthForDestructive?: boolean;
-    /**
-     * Blank `authorEmail` in responses to requests without a valid key.
-     * Defaults to `true` — reviewer emails are PII and GET must stay reachable
-     * by the widget.
-     */
-    redactUnauthenticatedEmails?: boolean;
-}
-
-/**
- * Outgoing webhook notifications for newly-created feedbacks.
- *
- * 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.
- *
- * - **Type-specific formatting**: Slack uses `{ text, blocks }`, Discord uses
- *   `{ content, embeds }`, generic posts the record as JSON (minus `clientId`).
- * - **Untrusted input**: `message` and `authorName` come from anonymous
- *   visitors. Slack text is escaped and Discord mention parsing is disabled,
- *   so a public feedback form can never be turned into a channel-wide ping.
- * - **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.
- */
-
-/** Supported webhook integrations — drives the JSON body shape. */
-type WebhookType = "slack" | "discord" | "generic";
-/**
- * Outgoing webhook configuration.
- *
- * - `url` — required, the HTTPS endpoint to POST to.
- * - `type` — payload format. Defaults to `"generic"` (raw JSON).
- * - `headers` — extra headers merged on top of `Content-Type: application/json`.
- *   Useful for signed-payload schemes (`X-Signature`, bearer tokens, …).
- * - `timeoutMs` — abort the fetch after this many ms. 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.
- */
-interface WebhookConfig {
-    url: string;
-    type?: WebhookType;
-    headers?: Record<string, string>;
-    timeoutMs?: number;
-    onError?: (err: Error, feedbackId: string) => void;
-}
-/** Block Kit envelope used by Slack incoming webhooks. */
-interface SlackWebhookPayload {
-    text: string;
-    blocks: ReadonlyArray<SlackHeaderBlock | SlackSectionBlock | SlackContextBlock>;
-}
-interface SlackHeaderBlock {
-    type: "header";
-    text: {
-        type: "plain_text";
-        text: string;
-        emoji: true;
-    };
-}
-interface SlackSectionBlock {
-    type: "section";
-    text: {
-        type: "mrkdwn";
-        text: string;
-    };
-}
-interface SlackContextBlock {
-    type: "context";
-    elements: ReadonlyArray<{
-        type: "mrkdwn";
-        text: string;
-    }>;
-}
-/** Embed envelope used by Discord incoming webhooks. */
-interface DiscordWebhookPayload {
-    content: string;
-    embeds: ReadonlyArray<{
-        title: string;
-        description: string;
-        color: number;
-        fields: ReadonlyArray<{
-            name: string;
-            value: string;
-            inline: boolean;
-        }>;
-        timestamp: string;
-    }>;
-    /**
-     * Mention parsing is switched off: `content` carries end-user text, so an
-     * author called `@everyone` must render as text, never as a notification.
-     */
-    allowed_mentions: {
-        parse: ReadonlyArray<"roles" | "users" | "everyone">;
-    };
-}
-/**
- * Generic webhook body — the stored record as JSON. `clientId` is stripped like
- * on every other output: it is the browser-local dedup secret and the POST
- * replay path hands the full record to whoever presents it.
- */
-type GenericWebhookPayload = Omit<FeedbackRecord, "clientId">;
-/** Mapping from webhook type to its concrete body shape. */
-interface WebhookPayloadMap {
-    slack: SlackWebhookPayload;
-    discord: DiscordWebhookPayload;
-    generic: GenericWebhookPayload;
-}
-/**
- * Dispatch a single webhook. Fire-and-forget: never throws, never rejects.
- *
- * - Builds the type-specific payload.
- * - POSTs with an `AbortSignal` timeout.
- * - On any error (network, non-2xx, timeout, exception), invokes
- *   `config.onError(err, feedbackId)` if provided; otherwise logs a one-liner.
- */
-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.
- */
-declare function dispatchWebhooks(configs: readonly WebhookConfig[], feedback: FeedbackRecord): Promise<void>;
-/** One handler per HTTP method — mount them on any Fetch-API router. */
-interface SitepingHandler {
-    OPTIONS: (request: Request) => Response;
-    POST: (request: Request) => Promise<Response>;
-    GET: (request: Request) => Promise<Response>;
-    PATCH: (request: Request) => Promise<Response>;
-    DELETE: (request: Request) => Promise<Response>;
-}
-interface FeedbackPatchInput {
-    id: string;
-    projectName: string;
-    status: FeedbackStatus;
-}
-interface FeedbackDeleteSingle {
-    id: string;
-    projectName: string;
-}
-interface FeedbackDeleteAll {
-    projectName: string;
-    deleteAll: true;
-}
-type FeedbackDeleteInput = FeedbackDeleteSingle | FeedbackDeleteAll;
-interface GetQueryInput {
-    projectName: string;
-    /** Set to 1 by schema default when omitted from raw input. */
-    page: number;
-    /** Set to 50 by schema default when omitted from raw input. */
-    limit: number;
-    type?: FeedbackType | undefined;
-    status?: FeedbackStatus | undefined;
-    statuses?: FeedbackStatus[] | undefined;
-    search?: string | undefined;
-    url?: string | undefined;
-    urlPattern?: string | undefined;
-}
+import { FeedbackPayload, BeezpingStore, ScreenshotStorage, CommentCreateInput, CommentRecord, FeedbackCreateInput, FeedbackRecord, FeedbackQuery, FeedbackPage, FeedbackUpdateInput } from './beezping-core.cjs';
+export { BeezpingStore, CommentCreateInput, CommentPayload, FeedbackCreateInput, FeedbackRecord, ScreenshotStorage, StoreDuplicateError, StoreLimitError, StoreNotFoundError, StorePersistenceError, StoreValueTooLongError, flattenAnnotation, isStorePersistence } from './beezping-core.cjs';
+import { BeezpingApiKeyHandlerOptions, BeezpingPrincipal, BeezpingAccessHandlerOptions, BeezpingHandler } from '@beezping/server';
+export { BeezpingAccessControl, BeezpingAction, BeezpingAuthorizationContext, BeezpingDeletionTarget, BeezpingHandler, BeezpingHandlerBaseOptions, BeezpingHttpMethod, BeezpingLifecycleHooks, BeezpingLogger, BeezpingPrincipal, BeezpingRequestContext, DiscordWebhookPayload, FeedbackDeleteInput, FeedbackPatchInput, GenericWebhookPayload, GetQueryInput, SlackWebhookPayload, WebhookConfig, WebhookPayloadMap, WebhookType, dispatchWebhook, dispatchWebhooks } from '@beezping/server';
 
 /**
  * @deprecated The create wire shape is core's `FeedbackPayload` — import
@@ -192,7 +10,7 @@ interface GetQueryInput {
 type FeedbackCreateSchemaInput = FeedbackPayload;
 
 /**
- * Structural type for a Prisma model delegate (`prisma.sitepingFeedback`).
+ * Structural type for a Prisma model delegate (`prisma.beezpingFeedback`).
  *
  * Arguments are kept `unknown` so any Prisma version's generated client
  * satisfies the constraint; the adapter assembles type-safe payloads
@@ -221,8 +39,15 @@ interface PrismaModelDelegate {
  * defines the subset of methods the adapter actually uses, so it can be
  * referenced in handler option types without importing `@prisma/client`.
  */
-interface SitepingPrismaClient {
-    sitepingFeedback: PrismaModelDelegate;
+interface BeezpingPrismaClient {
+    beezpingFeedback: PrismaModelDelegate;
+    /**
+     * Generated once the schema declares the `BeezpingComment` model
+     * (`npx @beezping/cli sync`). Optional, so a client generated from an older
+     * schema keeps type-checking: `PrismaStore` then has no threads and the
+     * handler answers comment writes with 501.
+     */
+    beezpingComment?: PrismaModelDelegate | undefined;
 }
 /**
  * Options accepted by `PrismaStore`.
@@ -253,7 +78,7 @@ interface PrismaStoreOptions {
     screenshotStorage?: ScreenshotStorage | undefined;
 }
 /**
- * Prisma-backed implementation of `SitepingStore`.
+ * Prisma-backed implementation of `BeezpingStore`.
  *
  * Wraps a PrismaClient to satisfy the abstract store interface.
  *
@@ -262,7 +87,7 @@ interface PrismaStoreOptions {
  * the database stays small. Without `screenshotStorage`, the data URL is
  * persisted inline (logged once on first use as a heads-up).
  */
-declare class PrismaStore implements SitepingStore {
+declare class PrismaStore implements BeezpingStore {
     /** @internal */
     private prisma;
     private readonly screenshotStorage;
@@ -270,8 +95,31 @@ declare class PrismaStore implements SitepingStore {
     private inlineFallbackWarned;
     /** @internal */
     private caseInsensitiveSearch;
-    constructor(prisma: SitepingPrismaClient, options?: PrismaStoreOptions);
-    createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord$1>;
+    /** Read shape of every feedback query — with the thread once the client has the comment model. */
+    private readonly include;
+    /**
+     * Add a comment to a feedback's thread — defined only when the client has
+     * the `BeezpingComment` delegate, unless a subclass defines its own. Without
+     * it the store has no threads, and the handler answers comment writes with
+     * 501 instead of every post failing with a Prisma error. Declared, not a
+     * field: a field would set it on every instance, hiding a subclass's method.
+     */
+    readonly addComment?: (feedbackId: string, data: CommentCreateInput) => Promise<CommentRecord>;
+    /** Delete one comment from a feedback's thread — defined under the same condition as {@link addComment}. */
+    readonly deleteComment?: (feedbackId: string, commentId: string) => Promise<void>;
+    constructor(prisma: BeezpingPrismaClient, options?: PrismaStoreOptions);
+    createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord>;
+    /**
+     * Drop the screenshot uploaded by a replay of a stored clientId — unless the
+     * stored row references it. Uploads are keyed on clientId, so with a
+     * deterministic key (`feedback/${feedbackId}.jpg`) the replay wrote to the
+     * very object the existing row points at: deleting it would strip the
+     * surviving feedback of its screenshot. If the lookup itself fails the
+     * object is kept — an orphan beats data loss. Other insert failures never
+     * get here: with such a key, a retry on another instance may have rewritten
+     * the object and not yet inserted the row that will point at it.
+     */
+    private discardUnreferencedUpload;
     private insertFeedback;
     /**
      * Resolve the value to persist on `Feedback.screenshotUrl`.
@@ -296,13 +144,34 @@ declare class PrismaStore implements SitepingStore {
      * logged and swallowed: an orphaned object is preferable to a delete that
      * reports failure after the row is already gone. Inline `data:` URLs and
      * stores without a `delete` hook are skipped.
+     *
+     * Deletes run through a pool of at most {@link SCREENSHOT_DELETE_CONCURRENCY}
+     * concurrent calls: a project delete may free thousands of objects, and one
+     * socket each at once would exhaust the file descriptors of a serverless
+     * function, orphaning most of them.
      */
     private discardScreenshots;
     /** URLs of the stored screenshots in `projectName` — only fetched when a `delete` hook can use them. */
     private storedScreenshotUrls;
-    findByClientId(clientId: string): Promise<FeedbackRecord$1 | null>;
+    findByClientId(clientId: string): Promise<FeedbackRecord | null>;
     getFeedbacks(query: FeedbackQuery): Promise<FeedbackPage>;
-    updateFeedback(id: string, data: FeedbackUpdateInput): Promise<FeedbackRecord$1>;
+    updateFeedback(id: string, data: FeedbackUpdateInput): Promise<FeedbackRecord>;
+    /**
+     * Insert a comment. A replayed `clientId` returns the stored comment, looked
+     * up first so a replay never runs into the thread cap; a concurrent replay
+     * that wins the insert race surfaces as P2002 and is read back the same
+     * way. The `connect` turns a missing feedback into Prisma's P2025 on every
+     * provider, rather than each database's own foreign-key error. The cap on
+     * `client` comments is a count before the insert, so posts racing for the
+     * last free slot may overshoot it; a `team` comment skips it.
+     */
+    private insertComment;
+    private findComment;
+    /**
+     * Delete one comment. Both ids go in one `deleteMany`, so a comment of
+     * another thread and an unknown one are the same zero-row miss.
+     */
+    private removeComment;
     deleteFeedback(id: string): Promise<void>;
     deleteAllFeedbacks(projectName: string): Promise<void>;
     /**
@@ -311,11 +180,12 @@ declare class PrismaStore implements SitepingStore {
      */
     verifyProjectOwnership(id: string, projectName: string): Promise<boolean>;
 }
-interface HandlerOptions extends ApiKeyAccessOptions {
+/** How the handler reaches its data: a Prisma client, or any store. */
+interface PrismaHandlerStoreOptions {
     /** Prisma client — used when `store` is not provided. Wrapped in a `PrismaStore` internally. */
-    prisma?: SitepingPrismaClient;
+    prisma?: BeezpingPrismaClient;
     /** Abstract store — when provided, takes precedence over `prisma`. */
-    store?: SitepingStore;
+    store?: BeezpingStore;
     /**
      * Optional storage backend for screenshots. Used only with `prisma`
      * (ignored when a custom `store` is passed — that store is responsible
@@ -323,8 +193,6 @@ interface HandlerOptions extends ApiKeyAccessOptions {
      * persisted inline on `Feedback.screenshotUrl` with a one-time warn.
      */
     screenshotStorage?: ScreenshotStorage;
-    /** Allowed CORS origins — when set, validates the Origin header */
-    allowedOrigins?: ReadonlyArray<string> | undefined;
     /**
      * Override case-insensitive search behaviour for the built-in `PrismaStore`.
      *
@@ -333,31 +201,45 @@ interface HandlerOptions extends ApiKeyAccessOptions {
      * auto-detection and per-provider semantics.
      */
     caseInsensitiveSearch?: boolean;
-    /**
-     * Outgoing webhooks fired after a feedback is successfully persisted.
-     * Fire-and-forget; provide `onError` on each config to observe failures.
-     */
-    webhooks?: WebhookConfig | ReadonlyArray<WebhookConfig>;
+}
+/** Options of `createBeezpingHandler` under the `apiKey` policy — every `@beezping/server` option. */
+interface HandlerOptions extends Omit<BeezpingApiKeyHandlerOptions, "store">, PrismaHandlerStoreOptions {
+}
+/** Options of `createBeezpingHandler` under a custom `access` policy (see `@beezping/server`). */
+interface PrismaAccessHandlerOptions<Principal extends BeezpingPrincipal> extends Omit<BeezpingAccessHandlerOptions<Principal>, "store">, PrismaHandlerStoreOptions {
 }
 /**
- * Create request handlers for the Siteping API endpoint.
+ * Create request handlers for the Beezping API endpoint — `@beezping/server`'s
+ * `createBeezpingHandler` over a Prisma-backed store, with every server option.
  *
  * Accepts either a `store` (abstract) or a `prisma` client (backwards compatible).
  * When `prisma` is provided without `store`, it is wrapped in a `PrismaStore`.
- * For custom auth (sessions, roles), lifecycle hooks or input transforms use
- * `createSitepingHandler` from `@beezping/server` with a `PrismaStore`.
  *
  * **Rate limiting** is not handled by this library. Apply rate limiting at the
  * framework or reverse-proxy level (e.g. Next.js middleware, Nginx, Cloudflare).
+ * The POST endpoint in particular should be rate-limited to prevent abuse, since
+ * the widget typically calls it from unauthenticated browser contexts.
+ *
+ * @example Next.js App Router — `app/api/beezping/route.ts`
+ * ```ts
+ * import { createBeezpingHandler } from '@beezping/adapter-prisma'
+ * import { prisma } from '@/lib/prisma'
+ *
+ * export const { GET, POST, PATCH, DELETE, OPTIONS } = createBeezpingHandler({ prisma })
+ * ```
  *
- * @example Next.js App Router — `app/api/siteping/route.ts`
+ * @example With abstract store
  * ```ts
- * import { createSitepingHandler } from '@beezping/adapter-prisma'
+ * import { createBeezpingHandler, PrismaStore } from '@beezping/adapter-prisma'
  * import { prisma } from '@/lib/prisma'
  *
- * export const { GET, POST, PATCH, DELETE, OPTIONS } = createSitepingHandler({ prisma })
+ * const store = new PrismaStore(prisma)
+ * export const { GET, POST, PATCH, DELETE, OPTIONS } = createBeezpingHandler({ store })
  * ```
  */
-declare function createSitepingHandler({ prisma, store: providedStore, screenshotStorage, caseInsensitiveSearch, ...handlerOptions }: HandlerOptions): SitepingHandler;
+declare function createBeezpingHandler<Principal extends BeezpingPrincipal>(options: PrismaAccessHandlerOptions<Principal>): BeezpingHandler;
+declare function createBeezpingHandler(options: HandlerOptions): BeezpingHandler;
+/** Options assembled at runtime, either policy. */
+declare function createBeezpingHandler<Principal extends BeezpingPrincipal>(options: HandlerOptions | PrismaAccessHandlerOptions<Principal>): BeezpingHandler;
 
-export { type DiscordWebhookPayload, type FeedbackCreateSchemaInput, type FeedbackDeleteInput, type FeedbackPatchInput, type GenericWebhookPayload, type GetQueryInput, type HandlerOptions, type PrismaModelDelegate, PrismaStore, type PrismaStoreOptions, type SitepingHandler, type SitepingHttpMethod, type SitepingPrismaClient, type SlackWebhookPayload, type WebhookConfig, type WebhookPayloadMap, type WebhookType, createSitepingHandler, dispatchWebhook, dispatchWebhooks };
+export { type BeezpingPrismaClient, type FeedbackCreateSchemaInput, type HandlerOptions, type PrismaAccessHandlerOptions, type PrismaModelDelegate, PrismaStore, type PrismaStoreOptions, createBeezpingHandler };