@siteping/widget 0.10.5 → 0.10.7

package/dist/types.d.cts

@@ -1,4 +1,4 @@
-import { type Prettify } from "./type-utils.cjs";
+import { type Prettify, type Serialized } from "./type-utils.cjs";
 /** FAB anchor — bottom-corner placement supported by the widget. */
 export type SitepingPosition = "bottom-right" | "bottom-left";
 /** Visual theme — `auto` resolves to `light` or `dark` via system preference. */
@@ -19,10 +19,10 @@ export type SitepingLocale = BuiltinLocale | (string & {});
 export type SitepingSkipReason = "production" | "mobile" | "ssr";
 /** Per-channel + per-buffer-size diagnostics configuration. */
 export interface DiagnosticsCaptureOptions {
-    console?: boolean;
-    network?: boolean;
-    maxConsoleEntries?: number;
-    maxNetworkEntries?: number;
+    console?: boolean | undefined;
+    network?: boolean | undefined;
+    maxConsoleEntries?: number | undefined;
+    maxNetworkEntries?: number | undefined;
 }
 /** Identity payload supplied by the host application — bypasses the modal. */
 export interface SitepingIdentity {
@@ -32,7 +32,7 @@ export interface SitepingIdentity {
 /** Deep-link configuration — controls how a feedback id is read from the URL. */
 export interface SitepingDeepLinkOptions {
     /** Query parameter name carrying the feedback id. Defaults to `"siteping"`. */
-    param?: string;
+    param?: string | undefined;
 }
 /**
  * Extra request headers for HTTP mode — a static map, or a factory (sync or
@@ -40,39 +40,17 @@ export interface SitepingDeepLinkOptions {
  * session token).
  */
 export type SitepingHeadersOption = Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
-/** Configuration options for the Siteping widget. */
-export interface SitepingConfig {
-    /** HTTP endpoint that receives feedbacks (e.g. '/api/siteping'). Required unless `store` is provided. */
-    endpoint?: string | undefined;
-    /**
-     * Convenience auth for HTTP mode — sent as `Authorization: Bearer <apiKey>`
-     * on every request to `endpoint`.
-     *
-     * **WARNING: the widget runs in every visitor's browser, so a static key
-     * configured here is public** — anyone can read it from your page source
-     * and replay it against your API. Only use `apiKey` for internal tools
-     * already behind your own login. On public sites, prefer `headers` with a
-     * per-request factory returning a short-lived session token.
-     *
-     * Ignored in store mode.
-     */
-    apiKey?: string | undefined;
-    /**
-     * Extra headers for every HTTP-mode request — a static map, or a factory
-     * (sync or async) called once per request (e.g. to fetch a fresh session
-     * token). Merged over the widget's generated headers, so an explicit
-     * `Authorization` entry overrides `apiKey`. A throwing/rejecting factory
-     * fails the request like a network error.
-     *
-     * Ignored in store mode.
-     */
-    headers?: SitepingHeadersOption | undefined;
+/**
+ * Options shared by both widget modes (HTTP and direct store).
+ *
+ * Do not use this type directly — use {@link SitepingConfig}, the
+ * discriminated union that adds the mode-specific fields.
+ */
+export interface SitepingBaseConfig {
     /** Required — project identifier used to scope feedbacks */
     projectName: string;
-    /** Direct store for client-side mode. When set, bypasses HTTP and uses the store directly in the browser. */
-    store?: SitepingStore | undefined;
     /** FAB position — defaults to 'bottom-right' */
-    position?: SitepingPosition;
+    position?: SitepingPosition | undefined;
     /**
      * Show the "toggle markers visibility" item in the FAB radial menu.
      * Defaults to `true` (current behavior). Set to `false` to hide that
@@ -88,7 +66,7 @@ export interface SitepingConfig {
      */
     showAnnotationsToggle?: boolean | undefined;
     /** Accent color for the widget UI — defaults to '#0066ff' */
-    accentColor?: string;
+    accentColor?: string | undefined;
     /**
      * Render the widget even when it would normally be skipped — this bypasses
      * BOTH the production-environment guard AND the mobile-viewport guard.
@@ -97,7 +75,7 @@ export interface SitepingConfig {
      * Defaults to false. Use it for dedicated review tools, staging environments,
      * or responsive testing where you always want the widget present.
      */
-    forceShow?: boolean;
+    forceShow?: boolean | undefined;
     /**
      * Minimum viewport width (px) at or above which the widget renders. Below it,
      * the widget is skipped and `onSkip("mobile")` fires. Defaults to `768`.
@@ -107,9 +85,9 @@ export interface SitepingConfig {
      */
     minViewportWidth?: number | undefined;
     /** Enable debug logging of lifecycle events — defaults to false */
-    debug?: boolean;
+    debug?: boolean | undefined;
     /** Color theme — defaults to 'light' */
-    theme?: SitepingTheme;
+    theme?: SitepingTheme | undefined;
     /** UI locale — defaults to 'en'. Built-in: en, fr, de, es, it, pt (Brazilian), ru. Any other string falls back to English. */
     locale?: SitepingLocale | undefined;
     /**
@@ -262,10 +240,11 @@ export interface SitepingConfig {
      */
     identity?: SitepingIdentity | undefined;
     /** Called when the feedback panel is opened. */
-    onOpen?: () => void;
+    onOpen?: (() => void) | undefined;
     /** Called when the feedback panel is closed. */
-    onClose?: () => void;
-    onFeedbackSent?: (feedback: FeedbackResponse) => void;
+    onClose?: (() => void) | undefined;
+    /** Called after a feedback is successfully submitted. */
+    onFeedbackSent?: ((feedback: FeedbackResponse) => void) | undefined;
     /**
      * Called when a feedback API call fails.
      *
@@ -277,12 +256,64 @@ export interface SitepingConfig {
      * direct-store callers can still surface raw errors without breaking the
      * contract.
      */
-    onError?: (error: Error) => void;
+    onError?: ((error: Error) => void) | undefined;
     /** Called when the user starts drawing an annotation. */
-    onAnnotationStart?: () => void;
+    onAnnotationStart?: (() => void) | undefined;
     /** Called when the user finishes drawing an annotation. */
-    onAnnotationEnd?: () => void;
+    onAnnotationEnd?: (() => void) | undefined;
 }
+/**
+ * HTTP mode — the widget talks to a server endpoint backed by a store
+ * adapter (e.g. `@siteping/adapter-prisma` request handlers).
+ */
+export interface SitepingHttpConfig extends SitepingBaseConfig {
+    /** HTTP endpoint that receives feedbacks (e.g. '/api/siteping'). */
+    endpoint: string;
+    /**
+     * Convenience auth for HTTP mode — sent as `Authorization: Bearer <apiKey>`
+     * on every request to `endpoint`.
+     *
+     * **WARNING: the widget runs in every visitor's browser, so a static key
+     * configured here is public** — anyone can read it from your page source
+     * and replay it against your API. Only use `apiKey` for internal tools
+     * already behind your own login. On public sites, prefer `headers` with a
+     * per-request factory returning a short-lived session token.
+     */
+    apiKey?: string | undefined;
+    /**
+     * Extra headers for every HTTP-mode request — a static map, or a factory
+     * (sync or async) called once per request (e.g. to fetch a fresh session
+     * token). Merged over the widget's generated headers, so an explicit
+     * `Authorization` entry overrides `apiKey`. A throwing/rejecting factory
+     * fails the request like a network error.
+     */
+    headers?: SitepingHeadersOption | undefined;
+    /** Not available in HTTP mode — use either `endpoint` or `store`, never both. */
+    store?: never;
+}
+/**
+ * Store mode — the widget talks to a `SitepingStore` directly in the
+ * browser, no server needed (demos, prototypes, localStorage persistence).
+ */
+export interface SitepingStoreConfig extends SitepingBaseConfig {
+    /** Direct store for client-side mode. Bypasses HTTP entirely. */
+    store: SitepingStore;
+    /** Not available in store mode — use either `endpoint` or `store`, never both. */
+    endpoint?: never;
+    /** HTTP-mode only — meaningless without an `endpoint`. */
+    apiKey?: never;
+    /** HTTP-mode only — meaningless without an `endpoint`. */
+    headers?: never;
+}
+/**
+ * Configuration options for the Siteping widget.
+ *
+ * A discriminated union over the two transport modes: pass `endpoint`
+ * (HTTP mode, optionally with `apiKey`/`headers`) **or** `store` (direct
+ * client-side mode) — never both, never neither. Invalid combinations are
+ * compile errors instead of runtime warnings.
+ */
+export type SitepingConfig = SitepingHttpConfig | SitepingStoreConfig;
 /** Instance returned by initSiteping() with lifecycle methods. */
 export interface SitepingInstance {
     /** Remove the widget from the DOM and clean up all listeners. */
@@ -317,8 +348,18 @@ export type SitepingUnsubscribe = () => void;
 export interface SitepingPublicEvents {
     "feedback:sent": [FeedbackResponse];
     "feedback:deleted": [FeedbackResponse["id"]];
+    /**
+     * A feedback API call failed. Same payload contract as
+     * `SitepingConfig.onError` — a `SitepingError` subclass in HTTP mode,
+     * possibly a raw `Error` in store mode.
+     */
+    "feedback:error": [Error];
     "panel:open": [];
     "panel:close": [];
+    /** The user started drawing an annotation. */
+    "annotation:start": [];
+    /** The user finished drawing an annotation. */
+    "annotation:end": [];
 }
 /** Single source of truth for feedback types — used by both TS types and Zod schemas. */
 export declare const FEEDBACK_TYPES: readonly ["question", "change", "bug", "other"];
@@ -333,8 +374,14 @@ export type FeedbackStatus = (typeof FEEDBACK_STATUSES)[number];
  * handler, dashboard) — store adapters persist whatever they are given.
  */
 export declare const CLOSED_FEEDBACK_STATUSES: readonly ["resolved", "wont_fix"];
-/** Whether a status is terminal (`resolved` or `wont_fix`). */
-export declare function isClosedStatus(status: FeedbackStatus): boolean;
+/** A terminal status — `resolved` or `wont_fix`. */
+export type ClosedFeedbackStatus = (typeof CLOSED_FEEDBACK_STATUSES)[number];
+/** Non-terminal statuses — the feedback still needs attention. */
+export declare const OPEN_FEEDBACK_STATUSES: readonly ["open", "in_progress"];
+/** A non-terminal status — `open` or `in_progress`. */
+export type OpenFeedbackStatus = (typeof OPEN_FEEDBACK_STATUSES)[number];
+/** Whether a status is terminal (`resolved` or `wont_fix`). Narrows the status type. */
+export declare function isClosedStatus(status: FeedbackStatus): status is ClosedFeedbackStatus;
 /**
  * Page scope returned by `SitepingConfig.getPageScope()`.
  *
@@ -448,11 +495,29 @@ export interface FeedbackQuery {
      */
     urlPattern?: string | undefined;
 }
-/** Update payload for patching a feedback. */
-export interface FeedbackUpdateInput {
-    status: FeedbackStatus;
-    resolvedAt: Date | null;
-}
+/**
+ * Update payload for patching a feedback.
+ *
+ * A discriminated union encoding the closure invariant: a feedback entering
+ * a closed status carries its closure timestamp, an open one carries `null`.
+ * `{ status: "resolved", resolvedAt: null }` is a compile error instead of a
+ * silent data bug. Build it from a plain `FeedbackStatus` with
+ * {@link toFeedbackUpdate}.
+ */
+export type FeedbackUpdateInput = {
+    status: OpenFeedbackStatus;
+    resolvedAt: null;
+} | {
+    status: ClosedFeedbackStatus;
+    resolvedAt: Date;
+};
+/**
+ * Derive the {@link FeedbackUpdateInput} for a status change — the closure
+ * timestamp is stamped for closed statuses and cleared otherwise. This is
+ * the edge derivation described on {@link CLOSED_FEEDBACK_STATUSES}; store
+ * adapters persist the result verbatim.
+ */
+export declare function toFeedbackUpdate(status: FeedbackStatus, closedAt?: Date): FeedbackUpdateInput;
 /** A persisted feedback record returned by the store. */
 export interface FeedbackRecord {
     id: string;
@@ -567,7 +632,7 @@ export declare function isStoreDuplicate(error: unknown): error is StoreDuplicat
  */
 export declare function isStorePersistence(error: unknown): error is StorePersistenceError | CodedError<"STORE_PERSISTENCE">;
 /** Flatten a widget `AnnotationPayload` (nested anchor + rect) into a flat `AnnotationCreateInput`. */
-export declare function flattenAnnotation(ann: AnnotationPayload): Prettify<AnnotationCreateInput>;
+export declare function flattenAnnotation(ann: AnnotationPayload): AnnotationCreateInput;
 /** Paginated result returned by `SitepingStore.getFeedbacks`. */
 export interface FeedbackPage {
     feedbacks: FeedbackRecord[];
@@ -605,6 +670,15 @@ export interface SitepingStore {
     deleteFeedback(id: string): Promise<void>;
     /** Bulk delete all feedbacks for a project. No-op (not error) if none exist. Throws `StorePersistenceError` when the write cannot be persisted. */
     deleteAllFeedbacks(projectName: string): Promise<void>;
+    /**
+     * Optional — return `true` when the record with `id` belongs to
+     * `projectName`, `false` otherwise (including when it does not exist).
+     *
+     * HTTP handlers use this to reject cross-project PATCH/DELETE requests.
+     * Implement it whenever your store serves multiple projects; when absent,
+     * handlers skip the ownership check and rely on `id` alone.
+     */
+    verifyProjectOwnership?(id: string, projectName: string): Promise<boolean>;
 }
 /** Payload sent from the widget to the server when submitting feedback. */
 export interface FeedbackPayload {
@@ -642,8 +716,10 @@ export interface FeedbackPayload {
      */
     diagnostics?: DiagnosticsSnapshot | null | undefined;
 }
+/** Single source of truth for console diagnostic severity levels. */
+export declare const CONSOLE_DIAGNOSTIC_LEVELS: readonly ["log", "info", "warn", "error"];
 /** Severity levels persisted in `ConsoleDiagnosticEntry`. */
-export type ConsoleDiagnosticLevel = "log" | "info" | "warn" | "error";
+export type ConsoleDiagnosticLevel = (typeof CONSOLE_DIAGNOSTIC_LEVELS)[number];
 /** A single console entry captured by `ConsoleBuffer`. */
 export interface ConsoleDiagnosticEntry {
     level: ConsoleDiagnosticLevel;
@@ -740,61 +816,22 @@ export interface AnnotationPayload {
     viewportH: number;
     devicePixelRatio: number;
 }
-/** Feedback record as returned by the API (dates serialized as strings). */
-export interface FeedbackResponse {
-    id: string;
-    projectName: string;
-    type: FeedbackType;
-    message: string;
-    status: FeedbackStatus;
-    url: string;
-    /** Parameterized URL template the feedback was created on, or null. */
-    urlPattern: string | null;
-    viewport: string;
-    userAgent: string;
-    authorName: string;
-    /**
-     * May be an empty string — HTTP adapters redact it for unauthenticated
-     * requests. The full value requires a Bearer-authenticated request.
-     */
-    authorEmail: string;
-    resolvedAt: string | null;
-    createdAt: string;
-    updatedAt: string;
-    annotations: AnnotationResponse[];
-    /** Screenshot URL (data: or http:) — see `FeedbackRecord.screenshotUrl`. */
-    screenshotUrl: string | null;
-    /** Annotation rect within the screenshot image, or null — see `ScreenshotRegion`. */
-    screenshotRegion: ScreenshotRegion | null;
-    /** Console + failed-network snapshot, or null when diagnostics weren't captured. */
-    diagnostics: DiagnosticsSnapshot | null;
-}
-/** Annotation record as returned by the API. */
-export interface AnnotationResponse {
-    id: string;
-    feedbackId: string;
-    cssSelector: string;
-    xpath: string;
-    textSnippet: string;
-    elementTag: string;
-    elementId: string | null;
-    textPrefix: string;
-    textSuffix: string;
-    fingerprint: string;
-    neighborText: string;
-    /** Semantic anchor identifier from `data-feedback-anchor`, or null. */
-    anchorKey: string | null;
-    xPct: number;
-    yPct: number;
-    wPct: number;
-    hPct: number;
-    scrollX: number;
-    scrollY: number;
-    viewportW: number;
-    viewportH: number;
-    devicePixelRatio: number;
-    createdAt: string;
-}
+/**
+ * Feedback record as returned by the API — derived from
+ * {@link FeedbackRecord}: dates are serialized to ISO strings and `clientId`
+ * is omitted (server-side dedup concern, never exposed on the wire). Adding
+ * a field to `FeedbackRecord` updates this type automatically.
+ *
+ * Note: `authorEmail` may be an empty string — HTTP adapters redact it for
+ * unauthenticated requests; the full value requires a Bearer-authenticated
+ * request.
+ */
+export type FeedbackResponse = Prettify<Serialized<Omit<FeedbackRecord, "clientId">>>;
+/**
+ * Annotation record as returned by the API — {@link AnnotationRecord} with
+ * `createdAt` serialized to an ISO string.
+ */
+export type AnnotationResponse = Prettify<Serialized<AnnotationRecord>>;
 /** Paginated `FeedbackResponse` shape returned by the API. */
 export interface FeedbackResponseList {
     feedbacks: FeedbackResponse[];