@siteping/adapter-drizzle 0.1.0 → 0.2.1

package/dist/siteping-core.d.cts

@@ -1,20 +1,23 @@
 export { settleWithConcurrencyLimit } from "./concurrency.cjs";
-export { buildDeepLink, parseHttpUrl } from "./deep-link.cjs";
+export { buildDeepLink, isSafeImageUrl, parseHttpUrl } from "./deep-link.cjs";
 export { EMAIL_PATTERN, isValidEmail } from "./email.cjs";
-export type { SitepingErrorCode } from "./errors.cjs";
-export { SitepingAuthError, SitepingError, SitepingNetworkError, SitepingValidationError } from "./errors.cjs";
+export type { SitepingClientError, SitepingConfigErrorCode, SitepingErrorCode } from "./errors.cjs";
+export { isSitepingConfigError, isSitepingError, SitepingAuthError, SitepingConfigError, SitepingError, SitepingNetworkError, SitepingValidationError, } from "./errors.cjs";
 export type { FilterResult, Pagination } from "./filters.cjs";
 export { applyFeedbackFilters, clampPagination, DEFAULT_PAGE_LIMIT, isUnreachableOffset, MAX_PAGE_LIMIT, matchesFeedbackQuery, } from "./filters.cjs";
 export type { I18n, LocaleLoaders, TranslateFunction } from "./i18n.cjs";
 export { canonicalizeLocale, createI18n, interpolate, intlLocale, tWithParams } from "./i18n.cjs";
+export type { SitepingLogger, SitepingWarnLogger } from "./logger.cjs";
+export { warnSafely } from "./logger.cjs";
 export type { FieldDef, IndexDef, ModelDef, PrismaNativeType, PrismaScalarType, RelationDef, RelationKind, RelationOnDelete, SitepingModelFieldName, SitepingModelName, } from "./schema.cjs";
 export { isRelationField, isScalarField, SITEPING_MODELS } from "./schema.cjs";
 export type { ScreenshotStorage } from "./screenshot-storage.cjs";
 export { SCREENSHOT_DELETE_CONCURRENCY, screenshotMimeType } from "./screenshot-storage.cjs";
 export type { CollectionStore, CollectionStoreBackend } from "./store-helpers.cjs";
 export { buildAnnotationRecord, buildCommentRecord, buildFeedbackRecord, createCollectionStore, } from "./store-helpers.cjs";
+export { REPLACEMENT_CHARACTER, toStorableText, toStorableValue, UNSTORABLE_CODE_UNITS } from "./text.cjs";
 export type { AssertEqual, IfEquals, Prettify, Serialized } from "./type-utils.cjs";
 export { hasOwn, isRecord } from "./type-utils.cjs";
-export type { AnchorData, AnnotationCreateInput, AnnotationPayload, AnnotationRecord, AnnotationResponse, BuiltinLocale, ClosedFeedbackStatus, CommentAuthorRole, CommentCreateInput, CommentDeletePayload, CommentPayload, CommentRecord, CommentResponse, ConsoleDiagnosticEntry, ConsoleDiagnosticLevel, DiagnosticsCaptureOptions, DiagnosticsSnapshot, FeedbackCreateInput, FeedbackCreateOutcome, FeedbackListPermissions, FeedbackPage, FeedbackPayload, FeedbackPermissions, FeedbackQuery, FeedbackRecord, FeedbackResponse, FeedbackResponseList, FeedbackStatus, FeedbackType, FeedbackUpdateInput, NetworkDiagnosticEntry, OpenFeedbackStatus, PageScope, RectData, ScreenshotRegion, SitepingBaseConfig, SitepingCapabilities, SitepingConfig, SitepingDeepLinkOptions, SitepingHeadersOption, SitepingHttpConfig, SitepingIdentity, SitepingInstance, SitepingLocale, SitepingPanelAction, SitepingPanelActionContext, SitepingPanelActionFeedback, SitepingPanelButtonAction, SitepingPanelLinkAction, SitepingPosition, SitepingPublicEventListener, SitepingPublicEvents, SitepingSkipReason, SitepingStore, SitepingStoreConfig, SitepingTheme, SitepingUnsubscribe, } from "./types.cjs";
-export { ANCHOR_ELEMENT_ID_MAX, ANCHOR_ELEMENT_TAG_MAX, BUILTIN_LOCALES, CLOSED_FEEDBACK_STATUSES, COMMENT_AUTHOR_ROLES, COMMENT_BODY_MAX_LENGTH, CONSOLE_DIAGNOSTIC_LEVELS, FEEDBACK_STATUSES, FEEDBACK_TYPES, flattenAnnotation, IDENTITY_FIELD_MAX_LENGTH, isClosedStatus, isStoreDuplicate, isStoreLimit, isStoreNotFound, isStorePersistence, isStoreValueTooLong, MAX_COMMENTS_PER_FEEDBACK, OPEN_FEEDBACK_STATUSES, StoreDuplicateError, StoreLimitError, StoreNotFoundError, StorePersistenceError, StoreValueTooLongError, toFeedbackUpdate, } from "./types.cjs";
+export type { AnchorData, AnnotationCreateInput, AnnotationPayload, AnnotationRecord, AnnotationResponse, BuiltinLocale, ClosedFeedbackStatus, CommentAuthorRole, CommentCreateInput, CommentCreateOutcome, CommentDeletePayload, CommentPayload, CommentPermissions, CommentRecord, CommentResponse, ConsoleDiagnosticEntry, ConsoleDiagnosticLevel, DiagnosticsCaptureOptions, DiagnosticsSnapshot, FeedbackCreateInput, FeedbackCreateOutcome, FeedbackListPermissions, FeedbackPage, FeedbackPayload, FeedbackPermissions, FeedbackQuery, FeedbackRecord, FeedbackResponse, FeedbackResponseList, FeedbackStatus, FeedbackType, FeedbackUpdateInput, NetworkDiagnosticEntry, OpenFeedbackStatus, PageScope, RectData, ScreenshotRegion, SitepingBaseConfig, SitepingCapabilities, SitepingConfig, SitepingDeepLinkOptions, SitepingHeadersOption, SitepingHttpConfig, SitepingIdentity, SitepingInstance, SitepingLocale, SitepingPanelAction, SitepingPanelActionContext, SitepingPanelActionFeedback, SitepingPanelButtonAction, SitepingPanelLinkAction, SitepingPosition, SitepingPublicEventListener, SitepingPublicEvents, SitepingSkipReason, SitepingStore, SitepingStoreConfig, SitepingTheme, SitepingUnsubscribe, } from "./types.cjs";
+export { ANCHOR_ELEMENT_ID_MAX, ANCHOR_ELEMENT_TAG_MAX, BUILTIN_LOCALES, CLIENT_ID_MAX_LENGTH, CLOSED_FEEDBACK_STATUSES, COMMENT_AUTHOR_ROLES, COMMENT_BODY_MAX_LENGTH, CONSOLE_DIAGNOSTIC_LEVELS, FEEDBACK_STATUSES, FEEDBACK_TYPES, flattenAnnotation, IDENTITY_FIELD_MAX_LENGTH, isClosedStatus, isStoreDuplicate, isStoreLimit, isStoreNotFound, isStorePersistence, isStoreValueTooLong, MAX_COMMENTS_PER_FEEDBACK, OPEN_FEEDBACK_STATUSES, PROJECT_NAME_MAX_LENGTH, SITEPING_PROTOCOL_VERSION, StoreDuplicateError, StoreLimitError, StoreNotFoundError, StorePersistenceError, StoreValueTooLongError, toFeedbackUpdate, } from "./types.cjs";
 export { errorFromResponse, feedbackQueryToSearchParams, isCommentGone, isThreadFull, mergeRequestHeaders, networkErrorFromException, newClientId, withSearchParams, } from "./wire.cjs";

package/dist/siteping-core.d.ts

@@ -1,20 +1,23 @@
 export { settleWithConcurrencyLimit } from "./concurrency.js";
-export { buildDeepLink, parseHttpUrl } from "./deep-link.js";
+export { buildDeepLink, isSafeImageUrl, parseHttpUrl } from "./deep-link.js";
 export { EMAIL_PATTERN, isValidEmail } from "./email.js";
-export type { SitepingErrorCode } from "./errors.js";
-export { SitepingAuthError, SitepingError, SitepingNetworkError, SitepingValidationError } from "./errors.js";
+export type { SitepingClientError, SitepingConfigErrorCode, SitepingErrorCode } from "./errors.js";
+export { isSitepingConfigError, isSitepingError, SitepingAuthError, SitepingConfigError, SitepingError, SitepingNetworkError, SitepingValidationError, } from "./errors.js";
 export type { FilterResult, Pagination } from "./filters.js";
 export { applyFeedbackFilters, clampPagination, DEFAULT_PAGE_LIMIT, isUnreachableOffset, MAX_PAGE_LIMIT, matchesFeedbackQuery, } from "./filters.js";
 export type { I18n, LocaleLoaders, TranslateFunction } from "./i18n.js";
 export { canonicalizeLocale, createI18n, interpolate, intlLocale, tWithParams } from "./i18n.js";
+export type { SitepingLogger, SitepingWarnLogger } from "./logger.js";
+export { warnSafely } from "./logger.js";
 export type { FieldDef, IndexDef, ModelDef, PrismaNativeType, PrismaScalarType, RelationDef, RelationKind, RelationOnDelete, SitepingModelFieldName, SitepingModelName, } from "./schema.js";
 export { isRelationField, isScalarField, SITEPING_MODELS } from "./schema.js";
 export type { ScreenshotStorage } from "./screenshot-storage.js";
 export { SCREENSHOT_DELETE_CONCURRENCY, screenshotMimeType } from "./screenshot-storage.js";
 export type { CollectionStore, CollectionStoreBackend } from "./store-helpers.js";
 export { buildAnnotationRecord, buildCommentRecord, buildFeedbackRecord, createCollectionStore, } from "./store-helpers.js";
+export { REPLACEMENT_CHARACTER, toStorableText, toStorableValue, UNSTORABLE_CODE_UNITS } from "./text.js";
 export type { AssertEqual, IfEquals, Prettify, Serialized } from "./type-utils.js";
 export { hasOwn, isRecord } from "./type-utils.js";
-export type { AnchorData, AnnotationCreateInput, AnnotationPayload, AnnotationRecord, AnnotationResponse, BuiltinLocale, ClosedFeedbackStatus, CommentAuthorRole, CommentCreateInput, CommentDeletePayload, CommentPayload, CommentRecord, CommentResponse, ConsoleDiagnosticEntry, ConsoleDiagnosticLevel, DiagnosticsCaptureOptions, DiagnosticsSnapshot, FeedbackCreateInput, FeedbackCreateOutcome, FeedbackListPermissions, FeedbackPage, FeedbackPayload, FeedbackPermissions, FeedbackQuery, FeedbackRecord, FeedbackResponse, FeedbackResponseList, FeedbackStatus, FeedbackType, FeedbackUpdateInput, NetworkDiagnosticEntry, OpenFeedbackStatus, PageScope, RectData, ScreenshotRegion, SitepingBaseConfig, SitepingCapabilities, SitepingConfig, SitepingDeepLinkOptions, SitepingHeadersOption, SitepingHttpConfig, SitepingIdentity, SitepingInstance, SitepingLocale, SitepingPanelAction, SitepingPanelActionContext, SitepingPanelActionFeedback, SitepingPanelButtonAction, SitepingPanelLinkAction, SitepingPosition, SitepingPublicEventListener, SitepingPublicEvents, SitepingSkipReason, SitepingStore, SitepingStoreConfig, SitepingTheme, SitepingUnsubscribe, } from "./types.js";
-export { ANCHOR_ELEMENT_ID_MAX, ANCHOR_ELEMENT_TAG_MAX, BUILTIN_LOCALES, CLOSED_FEEDBACK_STATUSES, COMMENT_AUTHOR_ROLES, COMMENT_BODY_MAX_LENGTH, CONSOLE_DIAGNOSTIC_LEVELS, FEEDBACK_STATUSES, FEEDBACK_TYPES, flattenAnnotation, IDENTITY_FIELD_MAX_LENGTH, isClosedStatus, isStoreDuplicate, isStoreLimit, isStoreNotFound, isStorePersistence, isStoreValueTooLong, MAX_COMMENTS_PER_FEEDBACK, OPEN_FEEDBACK_STATUSES, StoreDuplicateError, StoreLimitError, StoreNotFoundError, StorePersistenceError, StoreValueTooLongError, toFeedbackUpdate, } from "./types.js";
+export type { AnchorData, AnnotationCreateInput, AnnotationPayload, AnnotationRecord, AnnotationResponse, BuiltinLocale, ClosedFeedbackStatus, CommentAuthorRole, CommentCreateInput, CommentCreateOutcome, CommentDeletePayload, CommentPayload, CommentPermissions, CommentRecord, CommentResponse, ConsoleDiagnosticEntry, ConsoleDiagnosticLevel, DiagnosticsCaptureOptions, DiagnosticsSnapshot, FeedbackCreateInput, FeedbackCreateOutcome, FeedbackListPermissions, FeedbackPage, FeedbackPayload, FeedbackPermissions, FeedbackQuery, FeedbackRecord, FeedbackResponse, FeedbackResponseList, FeedbackStatus, FeedbackType, FeedbackUpdateInput, NetworkDiagnosticEntry, OpenFeedbackStatus, PageScope, RectData, ScreenshotRegion, SitepingBaseConfig, SitepingCapabilities, SitepingConfig, SitepingDeepLinkOptions, SitepingHeadersOption, SitepingHttpConfig, SitepingIdentity, SitepingInstance, SitepingLocale, SitepingPanelAction, SitepingPanelActionContext, SitepingPanelActionFeedback, SitepingPanelButtonAction, SitepingPanelLinkAction, SitepingPosition, SitepingPublicEventListener, SitepingPublicEvents, SitepingSkipReason, SitepingStore, SitepingStoreConfig, SitepingTheme, SitepingUnsubscribe, } from "./types.js";
+export { ANCHOR_ELEMENT_ID_MAX, ANCHOR_ELEMENT_TAG_MAX, BUILTIN_LOCALES, CLIENT_ID_MAX_LENGTH, CLOSED_FEEDBACK_STATUSES, COMMENT_AUTHOR_ROLES, COMMENT_BODY_MAX_LENGTH, CONSOLE_DIAGNOSTIC_LEVELS, FEEDBACK_STATUSES, FEEDBACK_TYPES, flattenAnnotation, IDENTITY_FIELD_MAX_LENGTH, isClosedStatus, isStoreDuplicate, isStoreLimit, isStoreNotFound, isStorePersistence, isStoreValueTooLong, MAX_COMMENTS_PER_FEEDBACK, OPEN_FEEDBACK_STATUSES, PROJECT_NAME_MAX_LENGTH, SITEPING_PROTOCOL_VERSION, StoreDuplicateError, StoreLimitError, StoreNotFoundError, StorePersistenceError, StoreValueTooLongError, toFeedbackUpdate, } from "./types.js";
 export { errorFromResponse, feedbackQueryToSearchParams, isCommentGone, isThreadFull, mergeRequestHeaders, networkErrorFromException, newClientId, withSearchParams, } from "./wire.js";

package/dist/store-helpers.d.cts

@@ -69,8 +69,9 @@ export interface CollectionStoreBackend {
     /** Generate a unique id for a new feedback, annotation or comment record. */
     generateId(): string;
     /**
-     * Keep discussion threads on the records: the store gains `addComment` and
-     * `deleteComment`, and new records start with `comments: []`. Opt in once
+     * Keep discussion threads on the records: the store gains `addComment`,
+     * `addCommentIfAbsent` and `deleteComment`, and new records start with
+     * `comments: []`. Opt in once
      * `load` hands back what `persist` wrote for them, each comment's
      * `createdAt` a `Date` again (a JSON backend revives it like the record's
      * own dates). Off by default, so an adapter written before threads never
@@ -87,12 +88,14 @@ export type CollectionStore = SitepingStore & Required<Pick<SitepingStore, "veri
 /**
  * Build a fully conformant `SitepingStore` on top of a snapshot backend.
  *
- * The engine implements the whole store contract: clientId dedup (idempotent
- * create, with `createFeedbackIfAbsent` reporting inserts), newest-first
+ * The engine implements the whole store contract: clientId dedup (a repeated
+ * `clientId` makes `createFeedback` throw `StoreDuplicateError`, and
+ * `createFeedbackIfAbsent` report the existing record), newest-first
  * ordering, the standard filter/pagination pipeline, `StoreNotFoundError` on
  * missing update/delete, project-scoped bulk delete,
  * `verifyProjectOwnership`, and — with `comments: true` — discussion threads
- * (`addComment`, `deleteComment`) kept on each record. The snapshot returned by `load` is
+ * (`addComment`, `addCommentIfAbsent` reporting inserts, `deleteComment`)
+ * kept on each record. The snapshot returned by `load` is
  * never mutated: every write hands `persist` a new array, so a failed write leaves
  * a cached snapshot exactly as it was. When `persist` fails during `createFeedback`
  * and the record carries an inline screenshot, the engine retries once
@@ -101,12 +104,13 @@ export type CollectionStore = SitepingStore & Required<Pick<SitepingStore, "veri
  * returning the record would claim a success that was never persisted.
  *
  * Mutations (`createFeedbackIfAbsent`, `createFeedback`, `updateFeedback`,
- * `deleteFeedback`, `deleteAllFeedbacks`, `addComment`, `deleteComment`) run
+ * `deleteFeedback`, `deleteAllFeedbacks`, `addComment`, `addCommentIfAbsent`,
+ * `deleteComment`) run
  * one at a time through a queue owned by the returned store, so concurrent
  * calls — the widget's `Promise.all` bulk resolve/delete, a comment posted
  * while its feedback is resolved — never start from the same snapshot and
- * overwrite each other, and `createFeedbackIfAbsent` reports `created: true`
- * exactly once per `clientId`. A failed mutation rejects with its own error
+ * overwrite each other, and `createFeedbackIfAbsent` and `addCommentIfAbsent`
+ * report `created: true` exactly once per `clientId`. A failed mutation rejects with its own error
  * and does not block the ones queued after it, but `load` and `persist` must
  * always settle: one that never does stalls every later mutation on the
  * store, so give network-backed primitives a timeout. Reads are not queued: they see the
@@ -136,5 +140,5 @@ export type CollectionStore = SitepingStore & Required<Pick<SitepingStore, "veri
  */
 export declare function createCollectionStore(backend: CollectionStoreBackend & {
     comments: true;
-}): CollectionStore & Required<Pick<SitepingStore, "createFeedbackIfAbsent" | "addComment" | "deleteComment">>;
+}): CollectionStore & Required<Pick<SitepingStore, "createFeedbackIfAbsent" | "addComment" | "addCommentIfAbsent" | "deleteComment">>;
 export declare function createCollectionStore(backend: CollectionStoreBackend): CollectionStore & Required<Pick<SitepingStore, "createFeedbackIfAbsent">>;

package/dist/store-helpers.d.ts

@@ -69,8 +69,9 @@ export interface CollectionStoreBackend {
     /** Generate a unique id for a new feedback, annotation or comment record. */
     generateId(): string;
     /**
-     * Keep discussion threads on the records: the store gains `addComment` and
-     * `deleteComment`, and new records start with `comments: []`. Opt in once
+     * Keep discussion threads on the records: the store gains `addComment`,
+     * `addCommentIfAbsent` and `deleteComment`, and new records start with
+     * `comments: []`. Opt in once
      * `load` hands back what `persist` wrote for them, each comment's
      * `createdAt` a `Date` again (a JSON backend revives it like the record's
      * own dates). Off by default, so an adapter written before threads never
@@ -87,12 +88,14 @@ export type CollectionStore = SitepingStore & Required<Pick<SitepingStore, "veri
 /**
  * Build a fully conformant `SitepingStore` on top of a snapshot backend.
  *
- * The engine implements the whole store contract: clientId dedup (idempotent
- * create, with `createFeedbackIfAbsent` reporting inserts), newest-first
+ * The engine implements the whole store contract: clientId dedup (a repeated
+ * `clientId` makes `createFeedback` throw `StoreDuplicateError`, and
+ * `createFeedbackIfAbsent` report the existing record), newest-first
  * ordering, the standard filter/pagination pipeline, `StoreNotFoundError` on
  * missing update/delete, project-scoped bulk delete,
  * `verifyProjectOwnership`, and — with `comments: true` — discussion threads
- * (`addComment`, `deleteComment`) kept on each record. The snapshot returned by `load` is
+ * (`addComment`, `addCommentIfAbsent` reporting inserts, `deleteComment`)
+ * kept on each record. The snapshot returned by `load` is
  * never mutated: every write hands `persist` a new array, so a failed write leaves
  * a cached snapshot exactly as it was. When `persist` fails during `createFeedback`
  * and the record carries an inline screenshot, the engine retries once
@@ -101,12 +104,13 @@ export type CollectionStore = SitepingStore & Required<Pick<SitepingStore, "veri
  * returning the record would claim a success that was never persisted.
  *
  * Mutations (`createFeedbackIfAbsent`, `createFeedback`, `updateFeedback`,
- * `deleteFeedback`, `deleteAllFeedbacks`, `addComment`, `deleteComment`) run
+ * `deleteFeedback`, `deleteAllFeedbacks`, `addComment`, `addCommentIfAbsent`,
+ * `deleteComment`) run
  * one at a time through a queue owned by the returned store, so concurrent
  * calls — the widget's `Promise.all` bulk resolve/delete, a comment posted
  * while its feedback is resolved — never start from the same snapshot and
- * overwrite each other, and `createFeedbackIfAbsent` reports `created: true`
- * exactly once per `clientId`. A failed mutation rejects with its own error
+ * overwrite each other, and `createFeedbackIfAbsent` and `addCommentIfAbsent`
+ * report `created: true` exactly once per `clientId`. A failed mutation rejects with its own error
  * and does not block the ones queued after it, but `load` and `persist` must
  * always settle: one that never does stalls every later mutation on the
  * store, so give network-backed primitives a timeout. Reads are not queued: they see the
@@ -136,5 +140,5 @@ export type CollectionStore = SitepingStore & Required<Pick<SitepingStore, "veri
  */
 export declare function createCollectionStore(backend: CollectionStoreBackend & {
     comments: true;
-}): CollectionStore & Required<Pick<SitepingStore, "createFeedbackIfAbsent" | "addComment" | "deleteComment">>;
+}): CollectionStore & Required<Pick<SitepingStore, "createFeedbackIfAbsent" | "addComment" | "addCommentIfAbsent" | "deleteComment">>;
 export declare function createCollectionStore(backend: CollectionStoreBackend): CollectionStore & Required<Pick<SitepingStore, "createFeedbackIfAbsent">>;

package/dist/text.d.cts

@@ -0,0 +1,28 @@
+/**
+ * Text a database may refuse — shared by the stores that write to one.
+ *
+ * PostgreSQL rejects NUL in `text` and `jsonb`, and a surrogate without its
+ * pair, which UTF-8 cannot encode: `jsonb` rejects it and `text` turns it
+ * into U+FFFD. A string cut inside an emoji ends with such an unpaired
+ * surrogate. The store contract accepts either the text as sent or U+FFFD in
+ * place of each such code unit (see the conformance suite), so a SQL store
+ * normalizes everything it writes or looks up with {@link toStorableText}.
+ */
+/** The UTF-16 code units a JavaScript string may hold but PostgreSQL cannot store: NUL and an unpaired surrogate. */
+export declare const UNSTORABLE_CODE_UNITS: RegExp;
+/** U+FFFD, the Unicode replacement character — what stands for each unstorable code unit. */
+export declare const REPLACEMENT_CHARACTER = "\uFFFD";
+/**
+ * `text` with every code unit PostgreSQL cannot store (NUL, an unpaired
+ * surrogate) replaced by U+FFFD. Applied to everything a store writes or
+ * looks up, a submission holding one is stored instead of failing, a record
+ * reads back exactly as the store returned it, and a search or lookup
+ * holding one matches what was stored for it.
+ */
+export declare function toStorableText(text: string): string;
+/**
+ * `value` with {@link toStorableText} applied to every string it holds, keys
+ * included, through arrays and plain objects (annotations, diagnostics…).
+ * Other values — numbers, dates, `null` — are kept as they are.
+ */
+export declare function toStorableValue<Value>(value: Value): Value;

package/dist/text.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Text a database may refuse — shared by the stores that write to one.
+ *
+ * PostgreSQL rejects NUL in `text` and `jsonb`, and a surrogate without its
+ * pair, which UTF-8 cannot encode: `jsonb` rejects it and `text` turns it
+ * into U+FFFD. A string cut inside an emoji ends with such an unpaired
+ * surrogate. The store contract accepts either the text as sent or U+FFFD in
+ * place of each such code unit (see the conformance suite), so a SQL store
+ * normalizes everything it writes or looks up with {@link toStorableText}.
+ */
+/** The UTF-16 code units a JavaScript string may hold but PostgreSQL cannot store: NUL and an unpaired surrogate. */
+export declare const UNSTORABLE_CODE_UNITS: RegExp;
+/** U+FFFD, the Unicode replacement character — what stands for each unstorable code unit. */
+export declare const REPLACEMENT_CHARACTER = "\uFFFD";
+/**
+ * `text` with every code unit PostgreSQL cannot store (NUL, an unpaired
+ * surrogate) replaced by U+FFFD. Applied to everything a store writes or
+ * looks up, a submission holding one is stored instead of failing, a record
+ * reads back exactly as the store returned it, and a search or lookup
+ * holding one matches what was stored for it.
+ */
+export declare function toStorableText(text: string): string;
+/**
+ * `value` with {@link toStorableText} applied to every string it holds, keys
+ * included, through arrays and plain objects (annotations, diagnostics…).
+ * Other values — numbers, dates, `null` — are kept as they are.
+ */
+export declare function toStorableValue<Value>(value: Value): Value;

package/dist/types.d.cts

@@ -1,10 +1,13 @@
 import { type DeepReadonly, 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. */
+/**
+ * Visual theme of the widget and the dashboard — `auto` follows the system
+ * preference, live: an OS switch mid-session re-themes the UI.
+ */
 export type SitepingTheme = "light" | "dark" | "auto";
 /** Built-in UI locales shipped with the widget. */
-export declare const BUILTIN_LOCALES: readonly ["en", "fr", "de", "es", "it", "pt", "ru", "ja"];
+export declare const BUILTIN_LOCALES: readonly ["en", "fr", "de", "es", "it", "pt", "ru", "ja", "ko"];
 export type BuiltinLocale = (typeof BUILTIN_LOCALES)[number];
 /**
  * Locale identifier accepted by the widget. Built-in locales are kept as
@@ -38,6 +41,15 @@ export interface SitepingIdentity {
  * it persists is never a 400 on every later submission.
  */
 export declare const IDENTITY_FIELD_MAX_LENGTH = 200;
+/**
+ * Max length of a `projectName` and of a feedback's or comment's `clientId`
+ * — the identifiers the stores index. 191 characters is the longest
+ * `VARCHAR` every MySQL version indexes under `utf8mb4` (767 bytes), which
+ * is why Prisma maps a plain `String` to `VARCHAR(191)` there: the HTTP
+ * schema caps them at that length, so their columns need no prefix index.
+ */
+export declare const PROJECT_NAME_MAX_LENGTH = 191;
+export declare const CLIENT_ID_MAX_LENGTH = 191;
 /** 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"`. */
@@ -184,9 +196,9 @@ export interface SitepingBaseConfig {
     minViewportWidth?: number | undefined;
     /** Enable debug logging of lifecycle events — defaults to false */
     debug?: boolean | undefined;
-    /** Color theme — defaults to 'light' */
+    /** Color theme — defaults to `light`; `auto` follows the system preference live. */
     theme?: SitepingTheme | undefined;
-    /** UI locale — defaults to 'en'. Built-in: en, fr, de, es, it, pt (Brazilian), ru, ja. Any other string falls back to English. */
+    /** UI locale — defaults to 'en'. Built-in: en, fr, de, es, it, pt (Brazilian), ru, ja, ko. Any other string falls back to English. */
     locale?: SitepingLocale | undefined;
     /**
      * Returns the current page scope for annotations and panel filtering.
@@ -204,7 +216,9 @@ export interface SitepingBaseConfig {
      * When true (default), the widget filters initial markers and panel results
      * by `feedback.url === scope.url`, so annotations created on one page never
      * leak to other pages — even if their CSS selector accidentally matches.
-     * Set to `false` to revert to the legacy project-wide behavior.
+     * Set to `false` for a project-wide view: the panel lists every feedback of
+     * the project, and a marker shows wherever its anchor resolves — for
+     * feedback on what every page shares, such as a header or a footer.
      */
     scopeAnnotationsByUrl?: boolean | undefined;
     /**
@@ -276,7 +290,7 @@ export interface SitepingBaseConfig {
      */
     captureDiagnostics?: boolean | DiagnosticsCaptureOptions | undefined;
     /** Called when the widget is skipped (production mode, viewport under `minViewportWidth`, SSR — no DOM) */
-    onSkip?: (reason: SitepingSkipReason) => void;
+    onSkip?: ((reason: SitepingSkipReason) => void) | undefined;
     /**
      * Auto-focus a specific annotation when its ID appears in the URL query
      * string. Lets hosts deeplink directly into a feedback from external
@@ -286,7 +300,8 @@ export interface SitepingBaseConfig {
      * `window.location.search` right after the initial markers load. If the
      * value matches a visible feedback ID, the widget scrolls the annotation
      * into view, pins its highlight, and pulses the marker — the same visual
-     * affordance a marker click produces.
+     * affordance a marker click produces — then opens the panel on that
+     * feedback's detail view, where its discussion thread is.
      *
      * - `false` / `undefined` (default): no URL parsing. Existing behavior
      *   unchanged, no host URL inspection.
@@ -327,6 +342,8 @@ export interface SitepingBaseConfig {
      * Pre-fill author identity from the host application — typically the
      * currently signed-in user. When set, the widget uses these values
      * directly and never shows the identity modal, even on first feedback.
+     * It names the reviewer who sends feedback — the dashboard's `author` is
+     * the team member who replies, a different person.
      *
      * Use case: SSO-integrated apps where the end user is already
      * authenticated by the host. Avoids the awkward "enter your name and
@@ -372,12 +389,13 @@ export interface SitepingBaseConfig {
      *
      * The widget always emits a `SitepingError` (or a subclass:
      * `SitepingNetworkError`, `SitepingValidationError`, `SitepingAuthError`)
-     * for HTTP-mode failures — host apps can `instanceof` to drive retry
-     * logic, or read `error.code` (`"NETWORK" | "VALIDATION" | "AUTH" |
-     * "SERVER"`) and `error.retryable` — and an `AUTH` error's `status`
-     * (`401` for missing or dead credentials, `403` for a refusal). The type
-     * is widened to `Error` so direct-store callers can still surface raw
-     * errors without breaking the contract.
+     * for a failed call — match it with `isSitepingError(error)` (not
+     * `instanceof`: the classes aren't exported), then read `error.code`
+     * (`"NETWORK" | "VALIDATION" | "AUTH" | "SERVER" | "TIMEOUT"`),
+     * `error.retryable` and an `AUTH` error's `status` (`401` for missing or
+     * dead credentials, `403` for a refusal). The type is widened to `Error`
+     * because a store in `store` mode may throw its own errors, which reach
+     * here unchanged.
      *
      * Also receives whatever a `panelActions` callback throws or rejects with
      * (non-`Error` values are wrapped). Those host failures are not API
@@ -450,14 +468,24 @@ export interface SitepingStoreConfig extends SitepingBaseConfig {
 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. */
+    /**
+     * Release this handle and detach the listeners added through its `on()`.
+     * Every `initSiteping()` call returns its own handle over the one widget,
+     * which leaves the DOM, all its listeners cleaned up, once the last handle
+     * is destroyed. A repeat call is a no-op, and the handle's other methods do
+     * nothing afterwards.
+     */
     destroy: () => void;
     /** Open the panel programmatically */
     open: () => void;
     /** Close the panel */
     close: () => void;
-    /** Reload feedbacks from server */
-    refresh: () => void;
+    /**
+     * Reload feedbacks from the server. Resolves once the pins (and the open
+     * panel) show the reloaded list; never rejects — like the dashboard's
+     * `refresh()`, a failed reload leaves the current view in place.
+     */
+    refresh: () => Promise<void>;
     /**
      * Scroll the matching annotation into view, pin its highlight, and
      * pulse its marker. Returns `true` when a visible feedback matched the
@@ -835,9 +863,10 @@ export declare class StoreLimitError extends Error {
 }
 /**
  * Thrown when a value is longer than the store can hold, though the HTTP
- * validation accepts it — on MySQL, Prisma maps a plain `String` to
- * `VARCHAR(191)`. Handlers translate this to HTTP 422: the submission can
- * never be stored as it is, so a client must not retry it.
+ * validation accepts it — a MySQL schema that predates the columns `sync`
+ * now sizes from the HTTP caps keeps Prisma's `VARCHAR(191)` for a plain
+ * `String`. Handlers translate this to HTTP 422: the submission can never be
+ * stored as it is, so a client must not retry it.
  */
 export declare class StoreValueTooLongError extends Error {
     readonly code: "STORE_VALUE_TOO_LONG";
@@ -885,6 +914,19 @@ export interface FeedbackCreateOutcome {
      */
     created: boolean;
 }
+/**
+ * Outcome of `SitepingStore.addCommentIfAbsent` — the comment plus whether
+ * this very call inserted it.
+ */
+export interface CommentCreateOutcome {
+    comment: CommentRecord;
+    /**
+     * `true` when this call inserted the comment, `false` when a comment with
+     * the same `clientId` already existed and is returned instead (a replay, or
+     * a concurrent request that won the race).
+     */
+    created: boolean;
+}
 /** Paginated result returned by `SitepingStore.getFeedbacks`. */
 export interface FeedbackPage {
     feedbacks: FeedbackRecord[];
@@ -901,19 +943,17 @@ export interface FeedbackPage {
  *
  * - **`updateFeedback` / `deleteFeedback`**: throw `StoreNotFoundError` when
  *   the record does not exist.
- * - **`createFeedback`**: either return the existing record on duplicate
- *   `clientId` (idempotent) or throw `StoreDuplicateError`. The handler
- *   handles both patterns — but only a throw, or the optional
- *   `createFeedbackIfAbsent`, tells it the record was not inserted by this
- *   call; stores that return the existing record should implement
- *   `createFeedbackIfAbsent` so creation side effects never run twice.
+ * - **`createFeedback`**: throw `StoreDuplicateError` on a duplicate
+ *   `clientId` — never return the existing record, so a caller always knows
+ *   whether this call inserted. The optional `createFeedbackIfAbsent`
+ *   reports the existing record instead, as `{ created: false }`.
  * - **All mutations**: when a write is accepted but cannot be persisted
  *   (e.g. storage quota), throw `StorePersistenceError` instead of reporting
  *   a phantom success. Detect it with `isStorePersistence`.
  * - Other methods should not throw on empty results — return empty arrays or `null`.
  */
 export interface SitepingStore {
-    /** Create a feedback with its annotations. Idempotent on `clientId` — return existing record on duplicate, or throw `StoreDuplicateError`. Throws `StorePersistenceError` when the write cannot be persisted. */
+    /** Create a feedback with its annotations. Throws `StoreDuplicateError` when a feedback with the same `clientId` exists, `StorePersistenceError` when the write cannot be persisted. */
     createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord>;
     /** Paginated query with optional filters. Returns empty array (not error) when no results. */
     getFeedbacks(query: FeedbackQuery): Promise<FeedbackPage>;
@@ -926,14 +966,11 @@ export interface SitepingStore {
     /** 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.
+     * Return `true` when the record with `id` belongs to `projectName`, `false`
+     * otherwise (including when it does not exist). HTTP handlers use it to
+     * reject cross-project PATCH/DELETE requests, which address records by id.
      */
-    verifyProjectOwnership?(id: string, projectName: string): Promise<boolean>;
+    verifyProjectOwnership(id: string, projectName: string): Promise<boolean>;
     /**
      * Optional — `createFeedback` that reports whether this call inserted the
      * record (`created: true`) or found an existing one with the same
@@ -945,11 +982,10 @@ export interface SitepingStore {
      * processes need an atomic backend primitive (unique constraint,
      * transaction, compare-and-set).
      *
-     * HTTP handlers prefer it over `createFeedback` to fire creation side
-     * effects (webhooks) exactly once when concurrent requests race on the
-     * same `clientId`. Stores whose `createFeedback` throws
-     * `StoreDuplicateError` on a duplicate already give that signal and may
-     * leave it out.
+     * HTTP handlers prefer it over `createFeedback`: a replayed or racing
+     * submission resolves to the stored record in one atomic call, without a
+     * `StoreDuplicateError` to catch and a lookup to follow it. Without it,
+     * they fall back to `createFeedback` and recover its duplicate error.
      */
     createFeedbackIfAbsent?(data: FeedbackCreateInput): Promise<FeedbackCreateOutcome>;
     /**
@@ -971,6 +1007,19 @@ export interface SitepingStore {
      * HTTP handlers serve empty threads and answer comment writes with 501.
      */
     addComment?(feedbackId: string, data: CommentCreateInput): Promise<CommentRecord>;
+    /**
+     * Optional, alongside `addComment` — `addComment` that reports whether this
+     * call inserted the comment (`created: true`) or found one with the same
+     * `clientId` (`created: false`). Same errors as `addComment`, and the dedup
+     * check and the insert must be atomic like `createFeedbackIfAbsent`'s: of N
+     * concurrent calls with the same `clientId`, exactly one may report
+     * `created: true`, and all must return that same comment.
+     *
+     * HTTP handlers need it to fire the `comment.created` webhook and the
+     * `onCommentCreated` hook exactly once per reply — a retried post returns
+     * the stored comment, which `addComment` alone cannot tell from a new one.
+     */
+    addCommentIfAbsent?(feedbackId: string, data: CommentCreateInput): Promise<CommentCreateOutcome>;
     /**
      * Optional — delete comment `commentId` from the thread of `feedbackId`.
      * Scoped to that thread, which the caller was authorized for: throws
@@ -1167,6 +1216,16 @@ export interface FeedbackPermissions {
     /** Delete replies from its thread. */
     canDeleteComment: boolean;
 }
+/**
+ * What a requester may do with one comment of a thread, as the server's
+ * access policy decides — finer than the feedback's `canDeleteComment`, which
+ * covers the whole thread: a policy that lets authors delete their own
+ * replies only grants it comment by comment.
+ */
+export interface CommentPermissions {
+    /** Delete it. */
+    canDelete: boolean;
+}
 /** What a requester may do with a whole project, sent with each list. */
 export interface FeedbackListPermissions {
     /** Delete every feedback of the project at once. */
@@ -1182,7 +1241,23 @@ export type AnnotationResponse = Prettify<Serialized<AnnotationRecord>>;
  * serialized and `clientId` omitted, like on `FeedbackResponse`. Its
  * `authorEmail` is redacted on the same terms as the feedback's.
  */
-export type CommentResponse = Prettify<Serialized<Omit<CommentRecord, "clientId">>>;
+export type CommentResponse = Prettify<Serialized<Omit<CommentRecord, "clientId">> & {
+    /**
+     * What the requester may do with this comment — always sent by
+     * `@siteping/server`. Absent from servers that predate it, and in store
+     * mode: the feedback's `canDeleteComment` decides then.
+     */
+    permissions?: CommentPermissions | undefined;
+}>;
+/**
+ * Version of the HTTP protocol `@siteping/server` speaks, sent as `protocol`
+ * on every list response. It rises with each addition a client may rely on —
+ * a route, a field, a status — so a client checks `protocol >= N` before
+ * using what protocol N added, instead of probing for fields. A server that
+ * predates it sends none: read that as 0. The OpenAPI document shipped as
+ * `@siteping/server/openapi.json` describes this version.
+ */
+export declare const SITEPING_PROTOCOL_VERSION = 1;
 /** What the store behind an endpoint supports — advertised on every list response. */
 export interface SitepingCapabilities {
     /** Whether comments can be posted: the store implements `addComment`. */
@@ -1198,6 +1273,8 @@ export interface SitepingCapabilities {
 export interface FeedbackResponseList {
     feedbacks: FeedbackResponse[];
     total: number;
+    /** The server's {@link SITEPING_PROTOCOL_VERSION} — absent from servers that predate it: read that as 0. */
+    protocol?: number | undefined;
     /** Always sent by `@siteping/server` — absent from servers that predate it. */
     capabilities?: SitepingCapabilities | undefined;
     /** Always sent by `@siteping/server` — absent from servers that predate it. */