@siteping/adapter-kit 0.1.0

package/dist/schema.d.cts

@@ -0,0 +1,263 @@
+/**
+ * Siteping database models — single source of truth.
+ *
+ * Used by:
+ * - CLI to generate Prisma schema (via prisma-ast)
+ * - Adapter for Zod validation
+ * - Type exports
+ *
+ * This is a TS representation, NOT a .prisma file.
+ * The CLI generates the actual Prisma schema from this definition.
+ */
+/** Prisma scalar types supported by Siteping field definitions. */
+export type PrismaScalarType = "String" | "Boolean" | "Int" | "BigInt" | "Float" | "Decimal" | "DateTime" | "Json" | "Bytes";
+/** Prisma native column hints applied via `@db.<NativeType>`. */
+export type PrismaNativeType = "Text" | "VarChar" | "Char" | "MediumText" | "LongText" | (string & {});
+/** Relation cardinality between two Siteping models. */
+export type RelationKind = "1-to-many" | "many-to-1";
+/** Prisma `onDelete` referential action. */
+export type RelationOnDelete = "Cascade" | "Restrict" | "NoAction" | "SetNull" | "SetDefault";
+/**
+ * Relation metadata attached to a {@link FieldDef}.
+ *
+ * - `1-to-many` fields point at the related model and require no inverse
+ *   column on this side (`fields`/`references` are inferred by Prisma).
+ * - `many-to-1` fields own the foreign key — Prisma needs `fields` and
+ *   `references` to wire it up.
+ */
+export interface RelationDef {
+    kind: RelationKind;
+    model: string;
+    fields?: readonly string[];
+    references?: readonly string[];
+    onDelete?: RelationOnDelete;
+}
+/**
+ * Definition of a single field in a Siteping database model.
+ *
+ * The interface intentionally keeps a wide structural shape so it stays
+ * easy to extend, but consumers can narrow via {@link isRelationField} /
+ * {@link isScalarField} when relation vs. scalar logic diverges.
+ */
+export interface FieldDef {
+    /** Prisma type (e.g. "String", "Int") for scalars, model name for relations. */
+    type: PrismaScalarType | (string & {});
+    /** Default literal (`"open"`) or function call (`now()`, `cuid()`). */
+    default?: string;
+    /** Whether the column is nullable. */
+    optional?: boolean;
+    /** Set on relation fields — absent on scalars. */
+    relation?: RelationDef;
+    isId?: boolean;
+    isUnique?: boolean;
+    /** Prisma native type attribute (e.g. "Text" for @db.Text) — used for MySQL compatibility on long strings */
+    nativeType?: PrismaNativeType;
+    /** Prisma @updatedAt attribute */
+    isUpdatedAt?: boolean;
+}
+/** Narrowing predicate: returns `true` when `field` declares a Prisma relation. */
+export declare function isRelationField(field: FieldDef): field is FieldDef & {
+    relation: RelationDef;
+};
+/** Narrowing predicate: returns `true` when `field` is a Prisma scalar (no relation metadata). */
+export declare function isScalarField(field: FieldDef): field is FieldDef & {
+    relation?: undefined;
+};
+/** Definition of a composite index on a Siteping database model. */
+export interface IndexDef {
+    fields: readonly string[];
+}
+/** Definition of a single Siteping database model (fields + indexes). */
+export interface ModelDef {
+    fields: Record<string, FieldDef>;
+    indexes?: readonly IndexDef[];
+}
+declare const _SITEPING_MODELS: {
+    readonly SitepingFeedback: {
+        readonly fields: {
+            readonly id: {
+                readonly type: "String";
+                readonly isId: true;
+                readonly default: "cuid()";
+            };
+            readonly projectName: {
+                readonly type: "String";
+            };
+            readonly type: {
+                readonly type: "String";
+            };
+            readonly message: {
+                readonly type: "String";
+                readonly nativeType: "Text";
+            };
+            readonly status: {
+                readonly type: "String";
+                readonly default: "\"open\"";
+            };
+            readonly url: {
+                readonly type: "String";
+            };
+            readonly urlPattern: {
+                readonly type: "String";
+                readonly optional: true;
+            };
+            readonly screenshotUrl: {
+                readonly type: "String";
+                readonly optional: true;
+                readonly nativeType: "Text";
+            };
+            readonly screenshotRegion: {
+                readonly type: "Json";
+                readonly optional: true;
+            };
+            readonly diagnostics: {
+                readonly type: "Json";
+                readonly optional: true;
+            };
+            readonly viewport: {
+                readonly type: "String";
+            };
+            readonly userAgent: {
+                readonly type: "String";
+            };
+            readonly authorName: {
+                readonly type: "String";
+            };
+            readonly authorEmail: {
+                readonly type: "String";
+            };
+            readonly clientId: {
+                readonly type: "String";
+                readonly isUnique: true;
+            };
+            readonly resolvedAt: {
+                readonly type: "DateTime";
+                readonly optional: true;
+            };
+            readonly createdAt: {
+                readonly type: "DateTime";
+                readonly default: "now()";
+            };
+            readonly updatedAt: {
+                readonly type: "DateTime";
+                readonly isUpdatedAt: true;
+            };
+            readonly annotations: {
+                readonly type: "SitepingAnnotation";
+                readonly relation: {
+                    readonly kind: "1-to-many";
+                    readonly model: "SitepingAnnotation";
+                };
+            };
+        };
+        readonly indexes: readonly [{
+            readonly fields: readonly ["projectName"];
+        }, {
+            readonly fields: readonly ["projectName", "status", "createdAt"];
+        }, {
+            readonly fields: readonly ["projectName", "url"];
+        }];
+    };
+    readonly SitepingAnnotation: {
+        readonly fields: {
+            readonly id: {
+                readonly type: "String";
+                readonly isId: true;
+                readonly default: "cuid()";
+            };
+            readonly feedbackId: {
+                readonly type: "String";
+            };
+            readonly feedback: {
+                readonly type: "SitepingFeedback";
+                readonly relation: {
+                    readonly kind: "many-to-1";
+                    readonly model: "SitepingFeedback";
+                    readonly fields: readonly ["feedbackId"];
+                    readonly references: readonly ["id"];
+                    readonly onDelete: "Cascade";
+                };
+            };
+            readonly cssSelector: {
+                readonly type: "String";
+                readonly nativeType: "Text";
+            };
+            readonly xpath: {
+                readonly type: "String";
+                readonly nativeType: "Text";
+            };
+            readonly textSnippet: {
+                readonly type: "String";
+                readonly nativeType: "Text";
+            };
+            readonly elementTag: {
+                readonly type: "String";
+            };
+            readonly elementId: {
+                readonly type: "String";
+                readonly optional: true;
+            };
+            readonly textPrefix: {
+                readonly type: "String";
+                readonly nativeType: "Text";
+            };
+            readonly textSuffix: {
+                readonly type: "String";
+                readonly nativeType: "Text";
+            };
+            readonly fingerprint: {
+                readonly type: "String";
+            };
+            readonly neighborText: {
+                readonly type: "String";
+                readonly nativeType: "Text";
+            };
+            readonly anchorKey: {
+                readonly type: "String";
+                readonly optional: true;
+            };
+            readonly xPct: {
+                readonly type: "Float";
+            };
+            readonly yPct: {
+                readonly type: "Float";
+            };
+            readonly wPct: {
+                readonly type: "Float";
+            };
+            readonly hPct: {
+                readonly type: "Float";
+            };
+            readonly scrollX: {
+                readonly type: "Float";
+            };
+            readonly scrollY: {
+                readonly type: "Float";
+            };
+            readonly viewportW: {
+                readonly type: "Int";
+            };
+            readonly viewportH: {
+                readonly type: "Int";
+            };
+            readonly devicePixelRatio: {
+                readonly type: "Float";
+                readonly default: "1";
+            };
+            readonly createdAt: {
+                readonly type: "DateTime";
+                readonly default: "now()";
+            };
+        };
+        readonly indexes: readonly [{
+            readonly fields: readonly ["feedbackId"];
+        }];
+    };
+};
+/** Map of Siteping models keyed by model name — frozen at runtime. */
+export declare const SITEPING_MODELS: typeof _SITEPING_MODELS;
+/** Union of every Siteping model name as a string literal. */
+export type SitepingModelName = keyof typeof SITEPING_MODELS;
+/** Field names declared on a specific Siteping model. */
+export type SitepingModelFieldName<M extends SitepingModelName> = keyof (typeof SITEPING_MODELS)[M]["fields"];
+export {};

package/dist/schema.d.ts

@@ -0,0 +1,263 @@
+/**
+ * Siteping database models — single source of truth.
+ *
+ * Used by:
+ * - CLI to generate Prisma schema (via prisma-ast)
+ * - Adapter for Zod validation
+ * - Type exports
+ *
+ * This is a TS representation, NOT a .prisma file.
+ * The CLI generates the actual Prisma schema from this definition.
+ */
+/** Prisma scalar types supported by Siteping field definitions. */
+export type PrismaScalarType = "String" | "Boolean" | "Int" | "BigInt" | "Float" | "Decimal" | "DateTime" | "Json" | "Bytes";
+/** Prisma native column hints applied via `@db.<NativeType>`. */
+export type PrismaNativeType = "Text" | "VarChar" | "Char" | "MediumText" | "LongText" | (string & {});
+/** Relation cardinality between two Siteping models. */
+export type RelationKind = "1-to-many" | "many-to-1";
+/** Prisma `onDelete` referential action. */
+export type RelationOnDelete = "Cascade" | "Restrict" | "NoAction" | "SetNull" | "SetDefault";
+/**
+ * Relation metadata attached to a {@link FieldDef}.
+ *
+ * - `1-to-many` fields point at the related model and require no inverse
+ *   column on this side (`fields`/`references` are inferred by Prisma).
+ * - `many-to-1` fields own the foreign key — Prisma needs `fields` and
+ *   `references` to wire it up.
+ */
+export interface RelationDef {
+    kind: RelationKind;
+    model: string;
+    fields?: readonly string[];
+    references?: readonly string[];
+    onDelete?: RelationOnDelete;
+}
+/**
+ * Definition of a single field in a Siteping database model.
+ *
+ * The interface intentionally keeps a wide structural shape so it stays
+ * easy to extend, but consumers can narrow via {@link isRelationField} /
+ * {@link isScalarField} when relation vs. scalar logic diverges.
+ */
+export interface FieldDef {
+    /** Prisma type (e.g. "String", "Int") for scalars, model name for relations. */
+    type: PrismaScalarType | (string & {});
+    /** Default literal (`"open"`) or function call (`now()`, `cuid()`). */
+    default?: string;
+    /** Whether the column is nullable. */
+    optional?: boolean;
+    /** Set on relation fields — absent on scalars. */
+    relation?: RelationDef;
+    isId?: boolean;
+    isUnique?: boolean;
+    /** Prisma native type attribute (e.g. "Text" for @db.Text) — used for MySQL compatibility on long strings */
+    nativeType?: PrismaNativeType;
+    /** Prisma @updatedAt attribute */
+    isUpdatedAt?: boolean;
+}
+/** Narrowing predicate: returns `true` when `field` declares a Prisma relation. */
+export declare function isRelationField(field: FieldDef): field is FieldDef & {
+    relation: RelationDef;
+};
+/** Narrowing predicate: returns `true` when `field` is a Prisma scalar (no relation metadata). */
+export declare function isScalarField(field: FieldDef): field is FieldDef & {
+    relation?: undefined;
+};
+/** Definition of a composite index on a Siteping database model. */
+export interface IndexDef {
+    fields: readonly string[];
+}
+/** Definition of a single Siteping database model (fields + indexes). */
+export interface ModelDef {
+    fields: Record<string, FieldDef>;
+    indexes?: readonly IndexDef[];
+}
+declare const _SITEPING_MODELS: {
+    readonly SitepingFeedback: {
+        readonly fields: {
+            readonly id: {
+                readonly type: "String";
+                readonly isId: true;
+                readonly default: "cuid()";
+            };
+            readonly projectName: {
+                readonly type: "String";
+            };
+            readonly type: {
+                readonly type: "String";
+            };
+            readonly message: {
+                readonly type: "String";
+                readonly nativeType: "Text";
+            };
+            readonly status: {
+                readonly type: "String";
+                readonly default: "\"open\"";
+            };
+            readonly url: {
+                readonly type: "String";
+            };
+            readonly urlPattern: {
+                readonly type: "String";
+                readonly optional: true;
+            };
+            readonly screenshotUrl: {
+                readonly type: "String";
+                readonly optional: true;
+                readonly nativeType: "Text";
+            };
+            readonly screenshotRegion: {
+                readonly type: "Json";
+                readonly optional: true;
+            };
+            readonly diagnostics: {
+                readonly type: "Json";
+                readonly optional: true;
+            };
+            readonly viewport: {
+                readonly type: "String";
+            };
+            readonly userAgent: {
+                readonly type: "String";
+            };
+            readonly authorName: {
+                readonly type: "String";
+            };
+            readonly authorEmail: {
+                readonly type: "String";
+            };
+            readonly clientId: {
+                readonly type: "String";
+                readonly isUnique: true;
+            };
+            readonly resolvedAt: {
+                readonly type: "DateTime";
+                readonly optional: true;
+            };
+            readonly createdAt: {
+                readonly type: "DateTime";
+                readonly default: "now()";
+            };
+            readonly updatedAt: {
+                readonly type: "DateTime";
+                readonly isUpdatedAt: true;
+            };
+            readonly annotations: {
+                readonly type: "SitepingAnnotation";
+                readonly relation: {
+                    readonly kind: "1-to-many";
+                    readonly model: "SitepingAnnotation";
+                };
+            };
+        };
+        readonly indexes: readonly [{
+            readonly fields: readonly ["projectName"];
+        }, {
+            readonly fields: readonly ["projectName", "status", "createdAt"];
+        }, {
+            readonly fields: readonly ["projectName", "url"];
+        }];
+    };
+    readonly SitepingAnnotation: {
+        readonly fields: {
+            readonly id: {
+                readonly type: "String";
+                readonly isId: true;
+                readonly default: "cuid()";
+            };
+            readonly feedbackId: {
+                readonly type: "String";
+            };
+            readonly feedback: {
+                readonly type: "SitepingFeedback";
+                readonly relation: {
+                    readonly kind: "many-to-1";
+                    readonly model: "SitepingFeedback";
+                    readonly fields: readonly ["feedbackId"];
+                    readonly references: readonly ["id"];
+                    readonly onDelete: "Cascade";
+                };
+            };
+            readonly cssSelector: {
+                readonly type: "String";
+                readonly nativeType: "Text";
+            };
+            readonly xpath: {
+                readonly type: "String";
+                readonly nativeType: "Text";
+            };
+            readonly textSnippet: {
+                readonly type: "String";
+                readonly nativeType: "Text";
+            };
+            readonly elementTag: {
+                readonly type: "String";
+            };
+            readonly elementId: {
+                readonly type: "String";
+                readonly optional: true;
+            };
+            readonly textPrefix: {
+                readonly type: "String";
+                readonly nativeType: "Text";
+            };
+            readonly textSuffix: {
+                readonly type: "String";
+                readonly nativeType: "Text";
+            };
+            readonly fingerprint: {
+                readonly type: "String";
+            };
+            readonly neighborText: {
+                readonly type: "String";
+                readonly nativeType: "Text";
+            };
+            readonly anchorKey: {
+                readonly type: "String";
+                readonly optional: true;
+            };
+            readonly xPct: {
+                readonly type: "Float";
+            };
+            readonly yPct: {
+                readonly type: "Float";
+            };
+            readonly wPct: {
+                readonly type: "Float";
+            };
+            readonly hPct: {
+                readonly type: "Float";
+            };
+            readonly scrollX: {
+                readonly type: "Float";
+            };
+            readonly scrollY: {
+                readonly type: "Float";
+            };
+            readonly viewportW: {
+                readonly type: "Int";
+            };
+            readonly viewportH: {
+                readonly type: "Int";
+            };
+            readonly devicePixelRatio: {
+                readonly type: "Float";
+                readonly default: "1";
+            };
+            readonly createdAt: {
+                readonly type: "DateTime";
+                readonly default: "now()";
+            };
+        };
+        readonly indexes: readonly [{
+            readonly fields: readonly ["feedbackId"];
+        }];
+    };
+};
+/** Map of Siteping models keyed by model name — frozen at runtime. */
+export declare const SITEPING_MODELS: typeof _SITEPING_MODELS;
+/** Union of every Siteping model name as a string literal. */
+export type SitepingModelName = keyof typeof SITEPING_MODELS;
+/** Field names declared on a specific Siteping model. */
+export type SitepingModelFieldName<M extends SitepingModelName> = keyof (typeof SITEPING_MODELS)[M]["fields"];
+export {};

package/dist/screenshot-storage.d.cts

@@ -0,0 +1,61 @@
+/**
+ * Pluggable storage for feedback screenshots.
+ *
+ * `adapter-prisma` accepts 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.
+ *
+ * Implementations typically wrap an object store: S3, Cloudflare R2,
+ * Backblaze B2, Cloudflare Images, local filesystem, etc. They are
+ * intentionally not shipped from this package — wire your own based on
+ * existing infra.
+ *
+ * @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, ctx) {
+ *     const buf = Buffer.from(dataUrl.split(",")[1], "base64");
+ *     const key = `feedback/${ctx.feedbackId}.jpg`;
+ *     await s3.send(new PutObjectCommand({
+ *       Bucket: "my-bucket", Key: key, Body: buf, ContentType: ctx.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.
+     *
+     * **Security note:** `ctx.feedbackId` is the *client-generated* id
+     * (`clientId`) — the record id does not exist yet at upload time. Treat it
+     * 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. Adapters
+     * call this best-effort and swallow errors — orphaned objects are
+     * preferred over failed deletes.
+     */
+    delete?: (url: string) => Promise<void>;
+}

package/dist/screenshot-storage.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Pluggable storage for feedback screenshots.
+ *
+ * `adapter-prisma` accepts 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.
+ *
+ * Implementations typically wrap an object store: S3, Cloudflare R2,
+ * Backblaze B2, Cloudflare Images, local filesystem, etc. They are
+ * intentionally not shipped from this package — wire your own based on
+ * existing infra.
+ *
+ * @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, ctx) {
+ *     const buf = Buffer.from(dataUrl.split(",")[1], "base64");
+ *     const key = `feedback/${ctx.feedbackId}.jpg`;
+ *     await s3.send(new PutObjectCommand({
+ *       Bucket: "my-bucket", Key: key, Body: buf, ContentType: ctx.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.
+     *
+     * **Security note:** `ctx.feedbackId` is the *client-generated* id
+     * (`clientId`) — the record id does not exist yet at upload time. Treat it
+     * 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. Adapters
+     * call this best-effort and swallow errors — orphaned objects are
+     * preferred over failed deletes.
+     */
+    delete?: (url: string) => Promise<void>;
+}

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

@@ -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.cjs'
+ * import { DrizzleStore } from '../src/index.js'
+ *
+ * testSitepingStore(() => new DrizzleStore(db))
+ * ```
+ */
+import type { SitepingStore } from "./types.cjs";
+/** 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;