@siteping/widget 0.10.10 → 0.11.0

package/dist/store-helpers.d.cts

@@ -7,13 +7,13 @@
  * timestamps), filter/paginate with `applyFeedbackFilters`, and implement
  * the dedup/update/delete choreography of the `SitepingStore` contract.
  *
- * `buildFeedbackRecord` / `buildAnnotationRecord` 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.
+ * `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, FeedbackCreateInput, FeedbackRecord, SitepingStore } from "./types.cjs";
+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.
@@ -23,12 +23,20 @@ export declare function buildAnnotationRecord(input: AnnotationCreateInput, ctx:
     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;
@@ -37,8 +45,11 @@ export declare function buildFeedbackRecord(input: FeedbackCreateInput, ctx: {
 }): FeedbackRecord;
 /**
  * Storage primitives behind a collection store. `load`/`persist` may be
- * sync or async — the engine awaits both, so in-memory arrays, localStorage
- * and async KV stores all fit the same three functions.
+ * 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 {
     /**
@@ -55,28 +66,57 @@ export interface CollectionStoreBackend {
      * update.
      */
     persist(feedbacks: FeedbackRecord[]): void | Promise<void>;
-    /** Generate a unique id for a new feedback or annotation record. */
+    /** 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.
+ * 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), newest-first ordering, the standard filter/pagination pipeline,
- * `StoreNotFoundError` on missing update/delete, project-scoped bulk delete,
- * and `verifyProjectOwnership`. The snapshot returned by `load` is never
- * mutated: every write hands `persist` a new array, so a failed write leaves
+ * 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 {
@@ -87,10 +127,14 @@ export type CollectionStore = SitepingStore & Required<Pick<SitepingStore, "veri
  *       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): CollectionStore;
+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

@@ -7,13 +7,13 @@
  * timestamps), filter/paginate with `applyFeedbackFilters`, and implement
  * the dedup/update/delete choreography of the `SitepingStore` contract.
  *
- * `buildFeedbackRecord` / `buildAnnotationRecord` 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.
+ * `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, FeedbackCreateInput, FeedbackRecord, SitepingStore } from "./types.js";
+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.
@@ -23,12 +23,20 @@ export declare function buildAnnotationRecord(input: AnnotationCreateInput, ctx:
     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;
@@ -37,8 +45,11 @@ export declare function buildFeedbackRecord(input: FeedbackCreateInput, ctx: {
 }): FeedbackRecord;
 /**
  * Storage primitives behind a collection store. `load`/`persist` may be
- * sync or async — the engine awaits both, so in-memory arrays, localStorage
- * and async KV stores all fit the same three functions.
+ * 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 {
     /**
@@ -55,28 +66,57 @@ export interface CollectionStoreBackend {
      * update.
      */
     persist(feedbacks: FeedbackRecord[]): void | Promise<void>;
-    /** Generate a unique id for a new feedback or annotation record. */
+    /** 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.
+ * 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), newest-first ordering, the standard filter/pagination pipeline,
- * `StoreNotFoundError` on missing update/delete, project-scoped bulk delete,
- * and `verifyProjectOwnership`. The snapshot returned by `load` is never
- * mutated: every write hands `persist` a new array, so a failed write leaves
+ * 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 {
@@ -87,10 +127,14 @@ export type CollectionStore = SitepingStore & Required<Pick<SitepingStore, "veri
  *       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): CollectionStore;
+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

@@ -41,6 +41,14 @@ export type AssertEqual<Actual, Expected> = IfEquals<Actual, Expected, true, nev
 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.

package/dist/type-utils.d.ts

@@ -41,6 +41,14 @@ export type AssertEqual<Actual, Expected> = IfEquals<Actual, Expected, true, nev
 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.