@siteping/server 0.0.0-stage → 0.1.1

package/dist/screenshot-storage.d.cts

@@ -0,0 +1,103 @@
+/**
+ * Pluggable storage for feedback screenshots.
+ *
+ * `adapter-prisma` and `adapter-drizzle` accept an optional
+ * `screenshotStorage` config. When provided, the adapter forwards the
+ * widget-supplied data URL to `upload()` and persists the returned URL on
+ * `Feedback.screenshotUrl`. When not provided, the adapter falls back to
+ * inline base64 (with a one-time warn) — fine for dev and small
+ * deployments, a footgun for production Postgres.
+ *
+ * `@siteping/screenshot-storage` implements it over any S3-compatible
+ * bucket (AWS S3, Cloudflare R2, Backblaze B2, MinIO…), Cloudflare Images,
+ * a database table, the local filesystem or memory. Implement it yourself
+ * for anything else.
+ *
+ * @example
+ * ```ts
+ * // Minimal S3 implementation
+ * import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
+ *
+ * const s3 = new S3Client({ region: "eu-west-3" });
+ * const screenshotStorage: ScreenshotStorage = {
+ *   async upload(dataUrl, { mimeType }) {
+ *     const body = Buffer.from(dataUrl.slice(dataUrl.indexOf(",") + 1), "base64");
+ *     const key = `siteping/${crypto.randomUUID()}`; // fresh per upload, see URL ownership
+ *     await s3.send(new PutObjectCommand({
+ *       Bucket: "my-bucket", Key: key, Body: body, ContentType: mimeType,
+ *     }));
+ *     return { url: `https://cdn.example.com/${key}` };
+ *   },
+ * };
+ *
+ * createSitepingHandler({ prisma, screenshotStorage });
+ * ```
+ */
+export interface ScreenshotStorage {
+    /**
+     * Persist a base64 data URL and return the URL the widget will use as
+     * `<img src>`. Implementations decide the underlying storage and any
+     * post-processing (resize, virus scan, content-type sniff).
+     *
+     * Adapters call this synchronously inside `createFeedback` — keep it
+     * fast or move to a queue if needed.
+     *
+     * `ctx.feedbackId` identifies the upload. Adapters that upload before the
+     * record exists pass the *client-generated* `clientId` (Prisma); the
+     * Drizzle adapter passes the server-generated id the create attempt will
+     * insert the record under.
+     *
+     * **URL ownership:** every call must return a URL no other call returns —
+     * key the object by a fresh random value (`crypto.randomUUID()`, as the
+     * example does), never by `ctx.feedbackId` alone nor by a content hash.
+     * Adapters treat each URL as the property of the one record that stores it
+     * and may pass it to `delete` once that record is deleted, or once its
+     * create lost a race: two submissions of one `clientId` both upload, and
+     * the object of the one that is not stored is deleted. Under Prisma,
+     * `ctx.feedbackId` is that client-supplied `clientId`, so an object keyed
+     * by it is rewritten by every replay — a retry, or anyone who learns the
+     * id — and a URL shared by several records lets deleting one remove the
+     * object another still points at.
+     *
+     * **Security note:** treat `ctx.feedbackId` as attacker-controlled:
+     * sanitize before using it in filesystem paths or object keys, even though
+     * server adapters validate its shape upstream.
+     */
+    upload(dataUrl: string, ctx: {
+        feedbackId: string;
+        mimeType: string;
+    }): Promise<{
+        url: string;
+    }>;
+    /**
+     * Optional cleanup hook called when the feedback is deleted, and for an
+     * object uploaded by a create whose record was not stored: one rejected
+     * because its `clientId` is already stored, or — in adapters that key
+     * uploads per attempt, like Drizzle — one whose insert failed. An object a
+     * stored row still references (a deterministic key reused by the replay)
+     * is kept. Receives only URLs returned by {@link ScreenshotStorage.upload}.
+     * Adapters call this best-effort and swallow errors — orphaned objects are
+     * preferred over failed deletes.
+     */
+    delete?: (url: string) => Promise<void>;
+}
+/**
+ * Most `ScreenshotStorage.delete` calls one cleanup keeps in flight — a
+ * project delete may free thousands of objects, and firing them all at once
+ * can exhaust sockets (one per request with `fetch`) or memory and trip
+ * object-store rate limits. It stays under the 50 sockets the AWS SDK opens
+ * per client by default, yet a project delete, which waits for its cleanup,
+ * is not serialised: 1,000 objects take 32 rounds. Adapters run their
+ * deletes through `settleWithConcurrencyLimit` with this bound.
+ */
+export declare const SCREENSHOT_DELETE_CONCURRENCY = 32;
+/**
+ * MIME type an adapter reports to {@link ScreenshotStorage.upload}: the one
+ * an image data URL declares (`data:image/png;base64,…` → `image/png`),
+ * limited to the JPEG, PNG and WebP the HTTP schema accepts. Stores are
+ * public and may be fed unvalidated data URLs, and an `image/svg+xml` label
+ * would make the stored object script-capable when served inline. Anything
+ * else — including a data URL that declares no type — reports JPEG, the
+ * widget's capture format.
+ */
+export declare function screenshotMimeType(dataUrl: string): string;

package/dist/screenshot-storage.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Pluggable storage for feedback screenshots.
+ *
+ * `adapter-prisma` and `adapter-drizzle` accept an optional
+ * `screenshotStorage` config. When provided, the adapter forwards the
+ * widget-supplied data URL to `upload()` and persists the returned URL on
+ * `Feedback.screenshotUrl`. When not provided, the adapter falls back to
+ * inline base64 (with a one-time warn) — fine for dev and small
+ * deployments, a footgun for production Postgres.
+ *
+ * `@siteping/screenshot-storage` implements it over any S3-compatible
+ * bucket (AWS S3, Cloudflare R2, Backblaze B2, MinIO…), Cloudflare Images,
+ * a database table, the local filesystem or memory. Implement it yourself
+ * for anything else.
+ *
+ * @example
+ * ```ts
+ * // Minimal S3 implementation
+ * import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
+ *
+ * const s3 = new S3Client({ region: "eu-west-3" });
+ * const screenshotStorage: ScreenshotStorage = {
+ *   async upload(dataUrl, { mimeType }) {
+ *     const body = Buffer.from(dataUrl.slice(dataUrl.indexOf(",") + 1), "base64");
+ *     const key = `siteping/${crypto.randomUUID()}`; // fresh per upload, see URL ownership
+ *     await s3.send(new PutObjectCommand({
+ *       Bucket: "my-bucket", Key: key, Body: body, ContentType: mimeType,
+ *     }));
+ *     return { url: `https://cdn.example.com/${key}` };
+ *   },
+ * };
+ *
+ * createSitepingHandler({ prisma, screenshotStorage });
+ * ```
+ */
+export interface ScreenshotStorage {
+    /**
+     * Persist a base64 data URL and return the URL the widget will use as
+     * `<img src>`. Implementations decide the underlying storage and any
+     * post-processing (resize, virus scan, content-type sniff).
+     *
+     * Adapters call this synchronously inside `createFeedback` — keep it
+     * fast or move to a queue if needed.
+     *
+     * `ctx.feedbackId` identifies the upload. Adapters that upload before the
+     * record exists pass the *client-generated* `clientId` (Prisma); the
+     * Drizzle adapter passes the server-generated id the create attempt will
+     * insert the record under.
+     *
+     * **URL ownership:** every call must return a URL no other call returns —
+     * key the object by a fresh random value (`crypto.randomUUID()`, as the
+     * example does), never by `ctx.feedbackId` alone nor by a content hash.
+     * Adapters treat each URL as the property of the one record that stores it
+     * and may pass it to `delete` once that record is deleted, or once its
+     * create lost a race: two submissions of one `clientId` both upload, and
+     * the object of the one that is not stored is deleted. Under Prisma,
+     * `ctx.feedbackId` is that client-supplied `clientId`, so an object keyed
+     * by it is rewritten by every replay — a retry, or anyone who learns the
+     * id — and a URL shared by several records lets deleting one remove the
+     * object another still points at.
+     *
+     * **Security note:** treat `ctx.feedbackId` as attacker-controlled:
+     * sanitize before using it in filesystem paths or object keys, even though
+     * server adapters validate its shape upstream.
+     */
+    upload(dataUrl: string, ctx: {
+        feedbackId: string;
+        mimeType: string;
+    }): Promise<{
+        url: string;
+    }>;
+    /**
+     * Optional cleanup hook called when the feedback is deleted, and for an
+     * object uploaded by a create whose record was not stored: one rejected
+     * because its `clientId` is already stored, or — in adapters that key
+     * uploads per attempt, like Drizzle — one whose insert failed. An object a
+     * stored row still references (a deterministic key reused by the replay)
+     * is kept. Receives only URLs returned by {@link ScreenshotStorage.upload}.
+     * Adapters call this best-effort and swallow errors — orphaned objects are
+     * preferred over failed deletes.
+     */
+    delete?: (url: string) => Promise<void>;
+}
+/**
+ * Most `ScreenshotStorage.delete` calls one cleanup keeps in flight — a
+ * project delete may free thousands of objects, and firing them all at once
+ * can exhaust sockets (one per request with `fetch`) or memory and trip
+ * object-store rate limits. It stays under the 50 sockets the AWS SDK opens
+ * per client by default, yet a project delete, which waits for its cleanup,
+ * is not serialised: 1,000 objects take 32 rounds. Adapters run their
+ * deletes through `settleWithConcurrencyLimit` with this bound.
+ */
+export declare const SCREENSHOT_DELETE_CONCURRENCY = 32;
+/**
+ * MIME type an adapter reports to {@link ScreenshotStorage.upload}: the one
+ * an image data URL declares (`data:image/png;base64,…` → `image/png`),
+ * limited to the JPEG, PNG and WebP the HTTP schema accepts. Stores are
+ * public and may be fed unvalidated data URLs, and an `image/svg+xml` label
+ * would make the stored object script-capable when served inline. Anything
+ * else — including a data URL that declares no type — reports JPEG, the
+ * widget's capture format.
+ */
+export declare function screenshotMimeType(dataUrl: string): string;

package/dist/siteping-core.d.cts

@@ -0,0 +1,20 @@
+export { settleWithConcurrencyLimit } from "./concurrency.cjs";
+export { buildDeepLink, 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 { 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 { 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 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 { errorFromResponse, feedbackQueryToSearchParams, isCommentGone, isThreadFull, mergeRequestHeaders, networkErrorFromException, newClientId, withSearchParams, } from "./wire.cjs";

package/dist/siteping-core.d.ts

@@ -0,0 +1,20 @@
+export { settleWithConcurrencyLimit } from "./concurrency.js";
+export { buildDeepLink, 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 { 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 { 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 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 { errorFromResponse, feedbackQueryToSearchParams, isCommentGone, isThreadFull, mergeRequestHeaders, networkErrorFromException, newClientId, withSearchParams, } from "./wire.js";

package/dist/store-helpers.d.cts

@@ -0,0 +1,140 @@
+/**
+ * Record-construction helpers and the collection-store engine.
+ *
+ * Every snapshot-style adapter (memory, localStorage, flat file, KV, …)
+ * needs the same three ingredients: turn a `FeedbackCreateInput` into a
+ * `FeedbackRecord` (null-normalizing optional fields, stamping ids and
+ * timestamps), filter/paginate with `applyFeedbackFilters`, and implement
+ * the dedup/update/delete choreography of the `SitepingStore` contract.
+ *
+ * `buildFeedbackRecord` / `buildAnnotationRecord` / `buildCommentRecord`
+ * cover the first part for any adapter. `createCollectionStore` covers all
+ * of it: give it `load`, `persist`, and `generateId`, and it returns a fully
+ * conformant `SitepingStore` — writing a new snapshot adapter is ~20 lines
+ * plus its storage specifics.
+ */
+import type { AnnotationCreateInput, AnnotationRecord, CommentCreateInput, CommentRecord, FeedbackCreateInput, FeedbackRecord, SitepingStore } from "./types.cjs";
+/**
+ * Build a persisted `AnnotationRecord` from its create input — normalizes
+ * the optional anchor fields to `null` and stamps identity/timestamp.
+ */
+export declare function buildAnnotationRecord(input: AnnotationCreateInput, ctx: {
+    id: string;
+    feedbackId: string;
+    now: Date;
+}): AnnotationRecord;
+/** Build a persisted `CommentRecord` from its create input — stamps identity, thread and timestamp. */
+export declare function buildCommentRecord(input: CommentCreateInput, ctx: {
+    id: string;
+    feedbackId: string;
+    now?: Date;
+}): CommentRecord;
+/**
+ * Build a persisted `FeedbackRecord` (with its annotations) from a create
+ * input — normalizes every optional field to `null` and stamps ids and
+ * timestamps. Adapters without external screenshot storage keep the data
+ * URL inline on `screenshotUrl`, which is what this helper does; adapters
+ * with a `ScreenshotStorage` upload first and override `screenshotUrl`.
+ * It leaves `comments` out, so the record minus its `annotations` stays an
+ * insertable feedback row; a store with threads returns `comments: []` itself.
+ */
+export declare function buildFeedbackRecord(input: FeedbackCreateInput, ctx: {
+    id: string;
+    annotationId: () => string;
+    now?: Date;
+}): FeedbackRecord;
+/**
+ * Storage primitives behind a collection store. `load`/`persist` may be
+ * sync or async, so in-memory arrays, localStorage and async KV stores all
+ * fit the same three functions. When both are sync, a mutation runs from
+ * `load` to `persist` without yielding, so no other code in the realm can
+ * write in between; an async backend is only serialized against the
+ * engine's own queue.
+ */
+export interface CollectionStoreBackend {
+    /**
+     * Return the current full snapshot of feedback records. The engine never
+     * mutates this array — handing out a live cache is safe.
+     */
+    load(): FeedbackRecord[] | Promise<FeedbackRecord[]>;
+    /**
+     * Persist the full snapshot — always a new array, never the one `load()`
+     * returned. Throw `StorePersistenceError` when the write is lost (quota,
+     * storage disabled, …) — never swallow the failure. Because the loaded
+     * snapshot is left untouched, a throw here leaves a cached `load()` result
+     * consistent with durable storage: no phantom record, no half-applied
+     * update.
+     */
+    persist(feedbacks: FeedbackRecord[]): void | Promise<void>;
+    /** 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
+     * `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
+     * gains them — over storage never written for them — on an engine update.
+     */
+    comments?: boolean | undefined;
+}
+/**
+ * A `SitepingStore` with the optional `verifyProjectOwnership` guaranteed —
+ * what `createCollectionStore` returns, which also guarantees
+ * `createFeedbackIfAbsent`.
+ */
+export type CollectionStore = SitepingStore & Required<Pick<SitepingStore, "verifyProjectOwnership">>;
+/**
+ * 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
+ * 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
+ * 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
+ * without the screenshot (by far the heaviest field) so the text feedback
+ * survives a storage-quota hit; if that also fails, the error propagates —
+ * returning the record would claim a success that was never persisted.
+ *
+ * Mutations (`createFeedbackIfAbsent`, `createFeedback`, `updateFeedback`,
+ * `deleteFeedback`, `deleteAllFeedbacks`, `addComment`, `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
+ * 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
+ * last persisted snapshot. The guarantee is scoped to one store instance in
+ * one JS realm — two instances over the same storage (two
+ * `LocalStorageStore`s on one key, two browser tabs, several server
+ * processes sharing a KV or a file) are not coordinated; a backend that
+ * needs that must bring its own atomic primitive (a transaction, a
+ * compare-and-set).
+ *
+ * @example
+ * ```ts
+ * export class MemoryStore implements SitepingStore {
+ *   private feedbacks: FeedbackRecord[] = [];
+ *   private readonly store = createCollectionStore({
+ *     load: () => this.feedbacks,
+ *     persist: (next) => {
+ *       this.feedbacks = next;
+ *     },
+ *     generateId: () => crypto.randomUUID(),
+ *     comments: true,
+ *   });
+ *   createFeedback = this.store.createFeedback;
+ *   // …delegate the remaining methods the same way
+ * }
+ * ```
+ */
+export declare function createCollectionStore(backend: CollectionStoreBackend & {
+    comments: true;
+}): CollectionStore & Required<Pick<SitepingStore, "createFeedbackIfAbsent" | "addComment" | "deleteComment">>;
+export declare function createCollectionStore(backend: CollectionStoreBackend): CollectionStore & Required<Pick<SitepingStore, "createFeedbackIfAbsent">>;

package/dist/store-helpers.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Record-construction helpers and the collection-store engine.
+ *
+ * Every snapshot-style adapter (memory, localStorage, flat file, KV, …)
+ * needs the same three ingredients: turn a `FeedbackCreateInput` into a
+ * `FeedbackRecord` (null-normalizing optional fields, stamping ids and
+ * timestamps), filter/paginate with `applyFeedbackFilters`, and implement
+ * the dedup/update/delete choreography of the `SitepingStore` contract.
+ *
+ * `buildFeedbackRecord` / `buildAnnotationRecord` / `buildCommentRecord`
+ * cover the first part for any adapter. `createCollectionStore` covers all
+ * of it: give it `load`, `persist`, and `generateId`, and it returns a fully
+ * conformant `SitepingStore` — writing a new snapshot adapter is ~20 lines
+ * plus its storage specifics.
+ */
+import type { AnnotationCreateInput, AnnotationRecord, CommentCreateInput, CommentRecord, FeedbackCreateInput, FeedbackRecord, SitepingStore } from "./types.js";
+/**
+ * Build a persisted `AnnotationRecord` from its create input — normalizes
+ * the optional anchor fields to `null` and stamps identity/timestamp.
+ */
+export declare function buildAnnotationRecord(input: AnnotationCreateInput, ctx: {
+    id: string;
+    feedbackId: string;
+    now: Date;
+}): AnnotationRecord;
+/** Build a persisted `CommentRecord` from its create input — stamps identity, thread and timestamp. */
+export declare function buildCommentRecord(input: CommentCreateInput, ctx: {
+    id: string;
+    feedbackId: string;
+    now?: Date;
+}): CommentRecord;
+/**
+ * Build a persisted `FeedbackRecord` (with its annotations) from a create
+ * input — normalizes every optional field to `null` and stamps ids and
+ * timestamps. Adapters without external screenshot storage keep the data
+ * URL inline on `screenshotUrl`, which is what this helper does; adapters
+ * with a `ScreenshotStorage` upload first and override `screenshotUrl`.
+ * It leaves `comments` out, so the record minus its `annotations` stays an
+ * insertable feedback row; a store with threads returns `comments: []` itself.
+ */
+export declare function buildFeedbackRecord(input: FeedbackCreateInput, ctx: {
+    id: string;
+    annotationId: () => string;
+    now?: Date;
+}): FeedbackRecord;
+/**
+ * Storage primitives behind a collection store. `load`/`persist` may be
+ * sync or async, so in-memory arrays, localStorage and async KV stores all
+ * fit the same three functions. When both are sync, a mutation runs from
+ * `load` to `persist` without yielding, so no other code in the realm can
+ * write in between; an async backend is only serialized against the
+ * engine's own queue.
+ */
+export interface CollectionStoreBackend {
+    /**
+     * Return the current full snapshot of feedback records. The engine never
+     * mutates this array — handing out a live cache is safe.
+     */
+    load(): FeedbackRecord[] | Promise<FeedbackRecord[]>;
+    /**
+     * Persist the full snapshot — always a new array, never the one `load()`
+     * returned. Throw `StorePersistenceError` when the write is lost (quota,
+     * storage disabled, …) — never swallow the failure. Because the loaded
+     * snapshot is left untouched, a throw here leaves a cached `load()` result
+     * consistent with durable storage: no phantom record, no half-applied
+     * update.
+     */
+    persist(feedbacks: FeedbackRecord[]): void | Promise<void>;
+    /** 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
+     * `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
+     * gains them — over storage never written for them — on an engine update.
+     */
+    comments?: boolean | undefined;
+}
+/**
+ * A `SitepingStore` with the optional `verifyProjectOwnership` guaranteed —
+ * what `createCollectionStore` returns, which also guarantees
+ * `createFeedbackIfAbsent`.
+ */
+export type CollectionStore = SitepingStore & Required<Pick<SitepingStore, "verifyProjectOwnership">>;
+/**
+ * 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
+ * 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
+ * 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
+ * without the screenshot (by far the heaviest field) so the text feedback
+ * survives a storage-quota hit; if that also fails, the error propagates —
+ * returning the record would claim a success that was never persisted.
+ *
+ * Mutations (`createFeedbackIfAbsent`, `createFeedback`, `updateFeedback`,
+ * `deleteFeedback`, `deleteAllFeedbacks`, `addComment`, `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
+ * 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
+ * last persisted snapshot. The guarantee is scoped to one store instance in
+ * one JS realm — two instances over the same storage (two
+ * `LocalStorageStore`s on one key, two browser tabs, several server
+ * processes sharing a KV or a file) are not coordinated; a backend that
+ * needs that must bring its own atomic primitive (a transaction, a
+ * compare-and-set).
+ *
+ * @example
+ * ```ts
+ * export class MemoryStore implements SitepingStore {
+ *   private feedbacks: FeedbackRecord[] = [];
+ *   private readonly store = createCollectionStore({
+ *     load: () => this.feedbacks,
+ *     persist: (next) => {
+ *       this.feedbacks = next;
+ *     },
+ *     generateId: () => crypto.randomUUID(),
+ *     comments: true,
+ *   });
+ *   createFeedback = this.store.createFeedback;
+ *   // …delegate the remaining methods the same way
+ * }
+ * ```
+ */
+export declare function createCollectionStore(backend: CollectionStoreBackend & {
+    comments: true;
+}): CollectionStore & Required<Pick<SitepingStore, "createFeedbackIfAbsent" | "addComment" | "deleteComment">>;
+export declare function createCollectionStore(backend: CollectionStoreBackend): CollectionStore & Required<Pick<SitepingStore, "createFeedbackIfAbsent">>;

package/dist/type-utils.d.cts

@@ -0,0 +1,66 @@
+/**
+ * General-purpose TypeScript utility types used across `@siteping/*`.
+ *
+ * These are kept dependency-free and re-exported from the package entry
+ * so adapters and integrators can rely on the same primitives the core
+ * uses internally.
+ */
+/**
+ * Force TypeScript to expand a computed type into a flat object literal in
+ * tooltips and error messages. Purely cosmetic — same structural type, just
+ * easier to read.
+ *
+ * @example
+ *   type Raw = Omit<FeedbackRecord, "annotations"> & { annotations: number };
+ *   type Pretty = Prettify<Raw>; // displayed as a flat object
+ */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+/**
+ * Returns `Y` when `A` is exactly assignable to `B` and vice-versa,
+ * otherwise `N`. Powers compile-time equality assertions.
+ */
+export type IfEquals<A, B, Y = true, N = false> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? Y : N;
+/**
+ * Compile-time exact-type guard — resolves to `true` when `Actual` and
+ * `Expected` are identical, `never` otherwise. Assign the result to a
+ * `const _lock: AssertEqual<A, B> = true;` so any drift becomes a compile
+ * error at the declaration site.
+ */
+export type AssertEqual<Actual, Expected> = IfEquals<Actual, Expected, true, never>;
+/**
+ * JSON-serialized shape of `T` — the wire form produced by `Response.json()`
+ * / `JSON.stringify`: `Date` becomes ISO `string` (nullability preserved),
+ * arrays are serialized element-wise, everything else is untouched.
+ *
+ * Used to derive the `*Response` API types from the `*Record` store types so
+ * the two can never drift: add a field to `FeedbackRecord` and
+ * `FeedbackResponse` follows automatically.
+ */
+export type Serialized<T> = {
+    [K in keyof T]: T[K] extends Date ? string : T[K] extends Date | null ? string | null : T[K] extends (infer U)[] ? Serialized<U>[] : T[K];
+};
+/**
+ * Read-only all the way down, for plain data that is deeply frozen at
+ * runtime: nested objects get read-only properties, arrays become
+ * `readonly` arrays.
+ */
+export type DeepReadonly<T> = T extends readonly (infer U)[] ? readonly DeepReadonly<U>[] : T extends object ? {
+    readonly [K in keyof T]: DeepReadonly<T[K]>;
+} : T;
+/**
+ * Type guard that narrows `value` to a non-null `Record<PropertyKey, unknown>`.
+ * Useful when validating arbitrary inputs before reading fields.
+ */
+export declare function isRecord(value: unknown): value is Record<PropertyKey, unknown>;
+/**
+ * Returns true when `value` is an object that exposes the requested key.
+ * Type-narrows `value` so the property can be accessed without further
+ * casting — a strictly typed replacement for `"k" in obj`.
+ *
+ * Named after the standardised `Object.hasOwn` helper rather than the
+ * legacy `Object.prototype.hasOwnProperty`, which the linter forbids
+ * shadowing.
+ */
+export declare function hasOwn<K extends PropertyKey>(value: unknown, key: K): value is Record<K, unknown>;