@siteping/adapter-kit 0.1.0

package/dist/siteping-core-testing.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Shared conformance test suite for `SitepingStore` implementations.
+ *
+ * Adapters import this and run it with their store factory to verify they
+ * satisfy the full store contract — no need to write the same 40+ tests
+ * from scratch.
+ *
+ * @example
+ * ```ts
+ * import { testSitepingStore } from './siteping-core-testing.js'
+ * import { DrizzleStore } from '../src/index.js'
+ *
+ * testSitepingStore(() => new DrizzleStore(db))
+ * ```
+ */
+import type { SitepingStore } from "./types.js";
+/** Tuning knobs for backends whose documented contract legitimately varies. */
+export interface StoreConformanceOptions {
+    /**
+     * How `createFeedback` reacts to a duplicate `clientId` — both are valid
+     * per the `SitepingStore` contract:
+     * - `"return"` (default): idempotently return the existing record.
+     * - `"throw"`: throw `StoreDuplicateError` (matched via `isStoreDuplicate`).
+     */
+    duplicateBehavior?: "return" | "throw" | undefined;
+    /**
+     * Whether `search` matches case-insensitively. Defaults to `true` (the
+     * in-memory pipeline's behavior). Set to `false` for SQL backends whose
+     * collation is case-sensitive — the suite then only asserts same-case
+     * substring matching.
+     */
+    caseInsensitiveSearch?: boolean | undefined;
+}
+/**
+ * Run the full `SitepingStore` conformance test suite.
+ *
+ * @param factory — called before each test to create a fresh, empty store instance. May be async.
+ * @param options — contract variations, see {@link StoreConformanceOptions}.
+ */
+export declare function testSitepingStore(factory: () => SitepingStore | Promise<SitepingStore>, options?: StoreConformanceOptions): void;

package/dist/siteping-core.d.cts

@@ -0,0 +1,16 @@
+export type { SitepingErrorCode } from "./errors.cjs";
+export { SitepingAuthError, SitepingError, SitepingNetworkError, SitepingValidationError } from "./errors.cjs";
+export type { FilterResult } from "./filters.cjs";
+export { applyFeedbackFilters } from "./filters.cjs";
+export type { I18n, LocaleLoaders, TranslateFunction } from "./i18n.cjs";
+export { createI18n, interpolate, 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 type { CollectionStore, CollectionStoreBackend } from "./store-helpers.cjs";
+export { buildAnnotationRecord, 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, ConsoleDiagnosticEntry, ConsoleDiagnosticLevel, DiagnosticsCaptureOptions, DiagnosticsSnapshot, FeedbackCreateInput, FeedbackPage, FeedbackPayload, FeedbackQuery, FeedbackRecord, FeedbackResponse, FeedbackResponseList, FeedbackStatus, FeedbackType, FeedbackUpdateInput, NetworkDiagnosticEntry, OpenFeedbackStatus, PageScope, RectData, ScreenshotRegion, SitepingBaseConfig, SitepingConfig, SitepingDeepLinkOptions, SitepingHeadersOption, SitepingHttpConfig, SitepingIdentity, SitepingInstance, SitepingLocale, SitepingPosition, SitepingPublicEventListener, SitepingPublicEvents, SitepingSkipReason, SitepingStore, SitepingStoreConfig, SitepingTheme, SitepingUnsubscribe, } from "./types.cjs";
+export { BUILTIN_LOCALES, CLOSED_FEEDBACK_STATUSES, CONSOLE_DIAGNOSTIC_LEVELS, FEEDBACK_STATUSES, FEEDBACK_TYPES, flattenAnnotation, isClosedStatus, isStoreDuplicate, isStoreNotFound, isStorePersistence, OPEN_FEEDBACK_STATUSES, StoreDuplicateError, StoreNotFoundError, StorePersistenceError, toFeedbackUpdate, } from "./types.cjs";
+export { errorFromResponse, feedbackQueryToSearchParams, networkErrorFromException } from "./wire.cjs";

package/dist/siteping-core.d.ts

@@ -0,0 +1,16 @@
+export type { SitepingErrorCode } from "./errors.js";
+export { SitepingAuthError, SitepingError, SitepingNetworkError, SitepingValidationError } from "./errors.js";
+export type { FilterResult } from "./filters.js";
+export { applyFeedbackFilters } from "./filters.js";
+export type { I18n, LocaleLoaders, TranslateFunction } from "./i18n.js";
+export { createI18n, interpolate, 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 type { CollectionStore, CollectionStoreBackend } from "./store-helpers.js";
+export { buildAnnotationRecord, 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, ConsoleDiagnosticEntry, ConsoleDiagnosticLevel, DiagnosticsCaptureOptions, DiagnosticsSnapshot, FeedbackCreateInput, FeedbackPage, FeedbackPayload, FeedbackQuery, FeedbackRecord, FeedbackResponse, FeedbackResponseList, FeedbackStatus, FeedbackType, FeedbackUpdateInput, NetworkDiagnosticEntry, OpenFeedbackStatus, PageScope, RectData, ScreenshotRegion, SitepingBaseConfig, SitepingConfig, SitepingDeepLinkOptions, SitepingHeadersOption, SitepingHttpConfig, SitepingIdentity, SitepingInstance, SitepingLocale, SitepingPosition, SitepingPublicEventListener, SitepingPublicEvents, SitepingSkipReason, SitepingStore, SitepingStoreConfig, SitepingTheme, SitepingUnsubscribe, } from "./types.js";
+export { BUILTIN_LOCALES, CLOSED_FEEDBACK_STATUSES, CONSOLE_DIAGNOSTIC_LEVELS, FEEDBACK_STATUSES, FEEDBACK_TYPES, flattenAnnotation, isClosedStatus, isStoreDuplicate, isStoreNotFound, isStorePersistence, OPEN_FEEDBACK_STATUSES, StoreDuplicateError, StoreNotFoundError, StorePersistenceError, toFeedbackUpdate, } from "./types.js";
+export { errorFromResponse, feedbackQueryToSearchParams, networkErrorFromException } from "./wire.js";

package/dist/store-helpers.d.cts

@@ -0,0 +1,87 @@
+/**
+ * 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` 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";
+/**
+ * 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 `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`.
+ */
+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 — the engine awaits both, so in-memory arrays, localStorage
+ * and async KV stores all fit the same three functions.
+ */
+export interface CollectionStoreBackend {
+    /** Return the current full snapshot of feedback records. */
+    load(): FeedbackRecord[] | Promise<FeedbackRecord[]>;
+    /**
+     * Persist the full snapshot. Throw `StorePersistenceError` when the write
+     * is lost (quota, storage disabled, …) — never swallow the failure.
+     */
+    persist(feedbacks: FeedbackRecord[]): void | Promise<void>;
+    /** Generate a unique id for a new feedback or annotation record. */
+    generateId(): string;
+}
+/**
+ * A `SitepingStore` with the optional `verifyProjectOwnership` guaranteed —
+ * what `createCollectionStore` returns.
+ */
+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`. 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.
+ *
+ * @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(),
+ *   });
+ *   createFeedback = this.store.createFeedback;
+ *   // …delegate the remaining methods the same way
+ * }
+ * ```
+ */
+export declare function createCollectionStore(backend: CollectionStoreBackend): CollectionStore;

package/dist/store-helpers.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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` 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";
+/**
+ * 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 `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`.
+ */
+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 — the engine awaits both, so in-memory arrays, localStorage
+ * and async KV stores all fit the same three functions.
+ */
+export interface CollectionStoreBackend {
+    /** Return the current full snapshot of feedback records. */
+    load(): FeedbackRecord[] | Promise<FeedbackRecord[]>;
+    /**
+     * Persist the full snapshot. Throw `StorePersistenceError` when the write
+     * is lost (quota, storage disabled, …) — never swallow the failure.
+     */
+    persist(feedbacks: FeedbackRecord[]): void | Promise<void>;
+    /** Generate a unique id for a new feedback or annotation record. */
+    generateId(): string;
+}
+/**
+ * A `SitepingStore` with the optional `verifyProjectOwnership` guaranteed —
+ * what `createCollectionStore` returns.
+ */
+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`. 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.
+ *
+ * @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(),
+ *   });
+ *   createFeedback = this.store.createFeedback;
+ *   // …delegate the remaining methods the same way
+ * }
+ * ```
+ */
+export declare function createCollectionStore(backend: CollectionStoreBackend): CollectionStore;