@siteping/adapter-memory 0.4.3

package/README.md

@@ -0,0 +1,86 @@
+[![npm version](https://img.shields.io/npm/v/@siteping/adapter-memory)](https://www.npmjs.com/package/@siteping/adapter-memory)
+[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org/)
+
+# @siteping/adapter-memory
+
+In-memory adapter for [Siteping](https://github.com/NeosiaNexus/SitePing) — zero dependencies, works everywhere.
+
+Part of the [@siteping](https://github.com/NeosiaNexus/SitePing) monorepo.
+
+## Install
+
+```bash
+npm install @siteping/adapter-memory
+```
+
+## Usage
+
+### With the HTTP handler (server-side)
+
+```ts
+import { createSitepingHandler } from '@siteping/adapter-prisma'
+import { MemoryStore } from '@siteping/adapter-memory'
+
+const store = new MemoryStore()
+
+export const { GET, POST, PATCH, DELETE, OPTIONS } = createSitepingHandler({ store })
+```
+
+### With the widget directly (client-side, no server)
+
+```ts
+import { initSiteping } from '@siteping/widget'
+import { MemoryStore } from '@siteping/adapter-memory'
+
+const store = new MemoryStore()
+
+initSiteping({
+  store,
+  projectName: 'my-project',
+})
+```
+
+## API
+
+### `new MemoryStore()`
+
+Creates a new in-memory store. Data lives in a plain array — lost on process restart.
+
+### `store.clear()`
+
+Remove all data and reset the ID counter.
+
+## Use Cases
+
+- **Testing** — fast, isolated store for unit and integration tests
+- **Demos** — lightweight store that needs no database or localStorage
+- **Prototyping** — get started without any infrastructure
+- **Reference implementation** — simplest possible adapter for contributors
+
+## Creating Your Own Adapter
+
+`MemoryStore` is the simplest reference implementation of the `SitepingStore` interface. To create a new adapter (e.g. Drizzle, Supabase):
+
+1. Implement the `SitepingStore` interface (6 methods)
+2. Throw `StoreNotFoundError` on missing records in `updateFeedback` / `deleteFeedback`
+3. Validate with the conformance test suite:
+
+```ts
+import { testSitepingStore } from '@siteping/core/testing'
+import { MyStore } from '../src/index.js'
+
+testSitepingStore(() => new MyStore())
+```
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@siteping/widget`](https://www.npmjs.com/package/@siteping/widget) | Browser feedback widget |
+| [`@siteping/adapter-prisma`](https://www.npmjs.com/package/@siteping/adapter-prisma) | Server-side Prisma adapter |
+| [`@siteping/adapter-localstorage`](https://www.npmjs.com/package/@siteping/adapter-localstorage) | Client-side localStorage adapter |
+| [`@siteping/cli`](https://www.npmjs.com/package/@siteping/cli) | CLI for project setup |
+
+## License
+
+[MIT](https://github.com/NeosiaNexus/SitePing/blob/main/LICENSE)

package/dist/index.cjs

@@ -0,0 +1,139 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MemoryStore: () => MemoryStore,
+  StoreDuplicateError: () => StoreDuplicateError,
+  StoreNotFoundError: () => StoreNotFoundError
+});
+module.exports = __toCommonJS(index_exports);
+
+// ../core/src/types.ts
+var StoreNotFoundError = class extends Error {
+  code = "STORE_NOT_FOUND";
+  constructor(message = "Record not found") {
+    super(message);
+    this.name = "StoreNotFoundError";
+  }
+};
+var StoreDuplicateError = class extends Error {
+  code = "STORE_DUPLICATE";
+  constructor(message = "Duplicate record") {
+    super(message);
+    this.name = "StoreDuplicateError";
+  }
+};
+
+// src/index.ts
+var MemoryStore = class {
+  feedbacks = [];
+  idCounter = 1;
+  generateId() {
+    return `mem-${this.idCounter++}-${Date.now().toString(36)}`;
+  }
+  async createFeedback(data) {
+    const existing = this.feedbacks.find((f) => f.clientId === data.clientId);
+    if (existing) return existing;
+    const now = /* @__PURE__ */ new Date();
+    const feedbackId = this.generateId();
+    const annotations = data.annotations.map((ann) => ({
+      id: this.generateId(),
+      feedbackId,
+      cssSelector: ann.cssSelector,
+      xpath: ann.xpath,
+      textSnippet: ann.textSnippet,
+      elementTag: ann.elementTag,
+      elementId: ann.elementId ?? null,
+      textPrefix: ann.textPrefix,
+      textSuffix: ann.textSuffix,
+      fingerprint: ann.fingerprint,
+      neighborText: ann.neighborText,
+      xPct: ann.xPct,
+      yPct: ann.yPct,
+      wPct: ann.wPct,
+      hPct: ann.hPct,
+      scrollX: ann.scrollX,
+      scrollY: ann.scrollY,
+      viewportW: ann.viewportW,
+      viewportH: ann.viewportH,
+      devicePixelRatio: ann.devicePixelRatio,
+      createdAt: now
+    }));
+    const record = {
+      id: feedbackId,
+      type: data.type,
+      message: data.message,
+      status: data.status,
+      projectName: data.projectName,
+      url: data.url,
+      authorName: data.authorName,
+      authorEmail: data.authorEmail,
+      viewport: data.viewport,
+      userAgent: data.userAgent,
+      clientId: data.clientId,
+      resolvedAt: null,
+      createdAt: now,
+      updatedAt: now,
+      annotations
+    };
+    this.feedbacks.unshift(record);
+    return record;
+  }
+  async getFeedbacks(query) {
+    let results = this.feedbacks.filter((f) => f.projectName === query.projectName);
+    if (query.type) results = results.filter((f) => f.type === query.type);
+    if (query.status) results = results.filter((f) => f.status === query.status);
+    if (query.search) {
+      const s = query.search.toLowerCase();
+      results = results.filter((f) => f.message.toLowerCase().includes(s));
+    }
+    const total = results.length;
+    const page = query.page ?? 1;
+    const limit = Math.min(query.limit ?? 50, 100);
+    const start = (page - 1) * limit;
+    return { feedbacks: results.slice(start, start + limit), total };
+  }
+  async findByClientId(clientId) {
+    return this.feedbacks.find((f) => f.clientId === clientId) ?? null;
+  }
+  async updateFeedback(id, data) {
+    const fb = this.feedbacks.find((f) => f.id === id);
+    if (!fb) throw new StoreNotFoundError();
+    fb.status = data.status;
+    fb.resolvedAt = data.resolvedAt;
+    fb.updatedAt = /* @__PURE__ */ new Date();
+    return fb;
+  }
+  async deleteFeedback(id) {
+    const idx = this.feedbacks.findIndex((f) => f.id === id);
+    if (idx === -1) throw new StoreNotFoundError();
+    this.feedbacks.splice(idx, 1);
+  }
+  async deleteAllFeedbacks(projectName) {
+    this.feedbacks = this.feedbacks.filter((f) => f.projectName !== projectName);
+  }
+  /** Remove all data from this store instance. */
+  clear() {
+    this.feedbacks = [];
+    this.idCounter = 1;
+  }
+};
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../../core/src/types.ts"],"sourcesContent":["import {\n  type AnnotationCreateInput,\n  type AnnotationRecord,\n  type FeedbackCreateInput,\n  type FeedbackQuery,\n  type FeedbackRecord,\n  type FeedbackUpdateInput,\n  type SitepingStore,\n  StoreNotFoundError,\n} from \"@siteping/core\";\n\nexport type { SitepingStore } from \"@siteping/core\";\nexport { StoreDuplicateError, StoreNotFoundError } from \"@siteping/core\";\n\n/**\n * In-memory `SitepingStore` implementation.\n *\n * Zero dependencies, works in any JS environment (Node, Bun, Deno, browser,\n * Cloudflare Workers). Data lives in a plain array — lost on process restart.\n *\n * Use cases:\n * - **Testing** — fast, isolated store for unit/integration tests\n * - **Demos** — lightweight store that needs no database or localStorage\n * - **Reference** — simplest possible adapter for contributors to study\n *\n * @example\n * ```ts\n * import { MemoryStore } from '@siteping/adapter-memory'\n *\n * const store = new MemoryStore()\n * // Pass to createSitepingHandler({ store }) or initSiteping({ store })\n * ```\n */\nexport class MemoryStore implements SitepingStore {\n  private feedbacks: FeedbackRecord[] = [];\n  private idCounter = 1;\n\n  private generateId(): string {\n    return `mem-${this.idCounter++}-${Date.now().toString(36)}`;\n  }\n\n  async createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord> {\n    // ClientId dedup — idempotent\n    const existing = this.feedbacks.find((f) => f.clientId === data.clientId);\n    if (existing) return existing;\n\n    const now = new Date();\n    const feedbackId = this.generateId();\n\n    const annotations: AnnotationRecord[] = data.annotations.map((ann: AnnotationCreateInput) => ({\n      id: this.generateId(),\n      feedbackId,\n      cssSelector: ann.cssSelector,\n      xpath: ann.xpath,\n      textSnippet: ann.textSnippet,\n      elementTag: ann.elementTag,\n      elementId: ann.elementId ?? null,\n      textPrefix: ann.textPrefix,\n      textSuffix: ann.textSuffix,\n      fingerprint: ann.fingerprint,\n      neighborText: ann.neighborText,\n      xPct: ann.xPct,\n      yPct: ann.yPct,\n      wPct: ann.wPct,\n      hPct: ann.hPct,\n      scrollX: ann.scrollX,\n      scrollY: ann.scrollY,\n      viewportW: ann.viewportW,\n      viewportH: ann.viewportH,\n      devicePixelRatio: ann.devicePixelRatio,\n      createdAt: now,\n    }));\n\n    const record: FeedbackRecord = {\n      id: feedbackId,\n      type: data.type,\n      message: data.message,\n      status: data.status,\n      projectName: data.projectName,\n      url: data.url,\n      authorName: data.authorName,\n      authorEmail: data.authorEmail,\n      viewport: data.viewport,\n      userAgent: data.userAgent,\n      clientId: data.clientId,\n      resolvedAt: null,\n      createdAt: now,\n      updatedAt: now,\n      annotations,\n    };\n\n    this.feedbacks.unshift(record);\n    return record;\n  }\n\n  async getFeedbacks(query: FeedbackQuery): Promise<{ feedbacks: FeedbackRecord[]; total: number }> {\n    let results = this.feedbacks.filter((f) => f.projectName === query.projectName);\n\n    if (query.type) results = results.filter((f) => f.type === query.type);\n    if (query.status) results = results.filter((f) => f.status === query.status);\n    if (query.search) {\n      const s = query.search.toLowerCase();\n      results = results.filter((f) => f.message.toLowerCase().includes(s));\n    }\n\n    const total = results.length;\n    const page = query.page ?? 1;\n    const limit = Math.min(query.limit ?? 50, 100);\n    const start = (page - 1) * limit;\n\n    return { feedbacks: results.slice(start, start + limit), total };\n  }\n\n  async findByClientId(clientId: string): Promise<FeedbackRecord | null> {\n    return this.feedbacks.find((f) => f.clientId === clientId) ?? null;\n  }\n\n  async updateFeedback(id: string, data: FeedbackUpdateInput): Promise<FeedbackRecord> {\n    const fb = this.feedbacks.find((f) => f.id === id);\n    if (!fb) throw new StoreNotFoundError();\n\n    fb.status = data.status;\n    fb.resolvedAt = data.resolvedAt;\n    fb.updatedAt = new Date();\n    return fb;\n  }\n\n  async deleteFeedback(id: string): Promise<void> {\n    const idx = this.feedbacks.findIndex((f) => f.id === id);\n    if (idx === -1) throw new StoreNotFoundError();\n    this.feedbacks.splice(idx, 1);\n  }\n\n  async deleteAllFeedbacks(projectName: string): Promise<void> {\n    this.feedbacks = this.feedbacks.filter((f) => f.projectName !== projectName);\n  }\n\n  /** Remove all data from this store instance. */\n  clear(): void {\n    this.feedbacks = [];\n    this.idCounter = 1;\n  }\n}\n","// ---------------------------------------------------------------------------\n// Config\n// ---------------------------------------------------------------------------\n\n/** Configuration options for the Siteping widget. */\nexport interface SitepingConfig {\n  /** HTTP endpoint that receives feedbacks (e.g. '/api/siteping'). Required unless `store` is provided. */\n  endpoint?: string | undefined;\n  /** Required — project identifier used to scope feedbacks */\n  projectName: string;\n  /** Direct store for client-side mode. When set, bypasses HTTP and uses the store directly in the browser. */\n  store?: SitepingStore | undefined;\n  /** FAB position — defaults to 'bottom-right' */\n  position?: \"bottom-right\" | \"bottom-left\";\n  /** Accent color for the widget UI — defaults to '#0066ff' */\n  accentColor?: string;\n  /** Show the widget even in production — defaults to false */\n  forceShow?: boolean;\n  /** Enable debug logging of lifecycle events — defaults to false */\n  debug?: boolean;\n  /** Color theme — defaults to 'light' */\n  theme?: \"light\" | \"dark\" | \"auto\";\n  /** UI locale — defaults to 'en' */\n  locale?: \"fr\" | \"en\" | (string & {}) | undefined;\n  /** Called when the widget is skipped (production mode, mobile viewport) */\n  onSkip?: (reason: \"production\" | \"mobile\") => void;\n\n  // Events\n  /** Called when the feedback panel is opened. */\n  onOpen?: () => void;\n  /** Called when the feedback panel is closed. */\n  onClose?: () => void;\n  onFeedbackSent?: (feedback: FeedbackResponse) => void;\n  onError?: (error: Error) => void;\n  /** Called when the user starts drawing an annotation. */\n  onAnnotationStart?: () => void;\n  /** Called when the user finishes drawing an annotation. */\n  onAnnotationEnd?: () => void;\n}\n\n/** Instance returned by initSiteping() with lifecycle methods. */\nexport interface SitepingInstance {\n  /** Remove the widget from the DOM and clean up all listeners. */\n  destroy: () => void;\n  /** Open the panel programmatically */\n  open: () => void;\n  /** Close the panel */\n  close: () => void;\n  /** Reload feedbacks from server */\n  refresh: () => void;\n  /** Subscribe to a public widget event */\n  on: <K extends keyof SitepingPublicEvents>(\n    event: K,\n    listener: (...args: SitepingPublicEvents[K]) => void,\n  ) => () => void;\n  /** Unsubscribe from a public widget event */\n  off: <K extends keyof SitepingPublicEvents>(event: K, listener: (...args: SitepingPublicEvents[K]) => void) => void;\n}\n\n/** Events exposed to consumers via SitepingInstance.on / .off */\nexport interface SitepingPublicEvents {\n  \"feedback:sent\": [FeedbackResponse];\n  \"feedback:deleted\": [string];\n  \"panel:open\": [];\n  \"panel:close\": [];\n}\n\n// ---------------------------------------------------------------------------\n// Feedback\n// ---------------------------------------------------------------------------\n\n/** Single source of truth for feedback types — used by both TS types and Zod schemas. */\nexport const FEEDBACK_TYPES = [\"question\", \"change\", \"bug\", \"other\"] as const;\nexport type FeedbackType = (typeof FEEDBACK_TYPES)[number];\n\n/** Single source of truth for feedback statuses. */\nexport const FEEDBACK_STATUSES = [\"open\", \"resolved\"] as const;\nexport type FeedbackStatus = (typeof FEEDBACK_STATUSES)[number];\n\n// ---------------------------------------------------------------------------\n// Abstract Store — adapter pattern\n// ---------------------------------------------------------------------------\n\n/** Input for creating a feedback record in the store. */\nexport interface FeedbackCreateInput {\n  projectName: string;\n  type: FeedbackType;\n  message: string;\n  status: FeedbackStatus;\n  url: string;\n  viewport: string;\n  userAgent: string;\n  authorName: string;\n  authorEmail: string;\n  clientId: string;\n  annotations: AnnotationCreateInput[];\n}\n\n/** Input for a single annotation when creating a feedback. */\nexport interface AnnotationCreateInput {\n  cssSelector: string;\n  xpath: string;\n  textSnippet: string;\n  elementTag: string;\n  elementId?: string | undefined;\n  textPrefix: string;\n  textSuffix: string;\n  fingerprint: string;\n  neighborText: string;\n  xPct: number;\n  yPct: number;\n  wPct: number;\n  hPct: number;\n  scrollX: number;\n  scrollY: number;\n  viewportW: number;\n  viewportH: number;\n  devicePixelRatio: number;\n}\n\n/** Query parameters for fetching feedbacks. */\nexport interface FeedbackQuery {\n  projectName: string;\n  type?: FeedbackType | undefined;\n  status?: FeedbackStatus | undefined;\n  search?: string | undefined;\n  page?: number | undefined;\n  limit?: number | undefined;\n}\n\n/** Update payload for patching a feedback. */\nexport interface FeedbackUpdateInput {\n  status: FeedbackStatus;\n  resolvedAt: Date | null;\n}\n\n/** A persisted feedback record returned by the store. */\nexport interface FeedbackRecord {\n  id: string;\n  type: FeedbackType;\n  message: string;\n  status: FeedbackStatus;\n  projectName: string;\n  url: string;\n  authorName: string;\n  authorEmail: string;\n  viewport: string;\n  userAgent: string;\n  clientId: string;\n  resolvedAt: Date | null;\n  createdAt: Date;\n  updatedAt: Date;\n  annotations: AnnotationRecord[];\n}\n\n/** A persisted annotation record returned by the store. */\nexport interface AnnotationRecord {\n  id: string;\n  feedbackId: string;\n  cssSelector: string;\n  xpath: string;\n  textSnippet: string;\n  elementTag: string;\n  elementId: string | null;\n  textPrefix: string;\n  textSuffix: string;\n  fingerprint: string;\n  neighborText: string;\n  xPct: number;\n  yPct: number;\n  wPct: number;\n  hPct: number;\n  scrollX: number;\n  scrollY: number;\n  viewportW: number;\n  viewportH: number;\n  devicePixelRatio: number;\n  createdAt: Date;\n}\n\n// ---------------------------------------------------------------------------\n// Store errors — throw these from adapter implementations\n// ---------------------------------------------------------------------------\n\n/**\n * Thrown when a record is not found during update or delete.\n *\n * Handlers translate this to HTTP 404. Adapters MUST throw this (not\n * ORM-specific errors) so the handler layer remains ORM-agnostic.\n */\nexport class StoreNotFoundError extends Error {\n  readonly code = \"STORE_NOT_FOUND\" as const;\n  constructor(message = \"Record not found\") {\n    super(message);\n    this.name = \"StoreNotFoundError\";\n  }\n}\n\n/**\n * Thrown when a unique constraint is violated (e.g. duplicate `clientId`).\n *\n * Handlers use this to return the existing record instead of failing.\n */\nexport class StoreDuplicateError extends Error {\n  readonly code = \"STORE_DUPLICATE\" as const;\n  constructor(message = \"Duplicate record\") {\n    super(message);\n    this.name = \"StoreDuplicateError\";\n  }\n}\n\n/** Type guard — works for `StoreNotFoundError` and ORM-specific equivalents (e.g. Prisma P2025). */\nexport function isStoreNotFound(error: unknown): boolean {\n  if (error instanceof StoreNotFoundError) return true;\n  // Backwards compat: Prisma's P2025\n  return typeof error === \"object\" && error !== null && \"code\" in error && (error as { code: string }).code === \"P2025\";\n}\n\n/** Type guard — works for `StoreDuplicateError` and ORM-specific equivalents (e.g. Prisma P2002). */\nexport function isStoreDuplicate(error: unknown): boolean {\n  if (error instanceof StoreDuplicateError) return true;\n  // Backwards compat: Prisma's P2002\n  return typeof error === \"object\" && error !== null && \"code\" in error && (error as { code: string }).code === \"P2002\";\n}\n\n// ---------------------------------------------------------------------------\n// Store helpers — shared conversion logic for adapters\n// ---------------------------------------------------------------------------\n\n/** Flatten a widget `AnnotationPayload` (nested anchor + rect) into a flat `AnnotationCreateInput`. */\nexport function flattenAnnotation(ann: AnnotationPayload): AnnotationCreateInput {\n  return {\n    cssSelector: ann.anchor.cssSelector,\n    xpath: ann.anchor.xpath,\n    textSnippet: ann.anchor.textSnippet,\n    elementTag: ann.anchor.elementTag,\n    elementId: ann.anchor.elementId,\n    textPrefix: ann.anchor.textPrefix,\n    textSuffix: ann.anchor.textSuffix,\n    fingerprint: ann.anchor.fingerprint,\n    neighborText: ann.anchor.neighborText,\n    xPct: ann.rect.xPct,\n    yPct: ann.rect.yPct,\n    wPct: ann.rect.wPct,\n    hPct: ann.rect.hPct,\n    scrollX: ann.scrollX,\n    scrollY: ann.scrollY,\n    viewportW: ann.viewportW,\n    viewportH: ann.viewportH,\n    devicePixelRatio: ann.devicePixelRatio,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Abstract Store — adapter pattern\n// ---------------------------------------------------------------------------\n\n/**\n * Abstract storage interface for Siteping.\n *\n * Any adapter (Prisma, Drizzle, raw SQL, localStorage, etc.) implements this\n * interface. The HTTP handler and widget `StoreClient` operate against\n * `SitepingStore`, decoupled from the storage backend.\n *\n * ## Error contract\n *\n * - **`updateFeedback` / `deleteFeedback`**: throw `StoreNotFoundError` when\n *   the record does not exist.\n * - **`createFeedback`**: either return the existing record on duplicate\n *   `clientId` (idempotent) or throw `StoreDuplicateError`. The handler\n *   handles both patterns.\n * - Other methods should not throw on empty results — return empty arrays or `null`.\n */\nexport interface SitepingStore {\n  /** Create a feedback with its annotations. Idempotent on `clientId` — return existing record on duplicate, or throw `StoreDuplicateError`. */\n  createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord>;\n  /** Paginated query with optional filters. Returns empty array (not error) when no results. */\n  getFeedbacks(query: FeedbackQuery): Promise<{ feedbacks: FeedbackRecord[]; total: number }>;\n  /** Lookup by client-generated UUID. Returns `null` (not error) when not found. */\n  findByClientId(clientId: string): Promise<FeedbackRecord | null>;\n  /** Update status/resolvedAt. Throws `StoreNotFoundError` if `id` does not exist. */\n  updateFeedback(id: string, data: FeedbackUpdateInput): Promise<FeedbackRecord>;\n  /** Delete a single record. Throws `StoreNotFoundError` if `id` does not exist. */\n  deleteFeedback(id: string): Promise<void>;\n  /** Bulk delete all feedbacks for a project. No-op (not error) if none exist. */\n  deleteAllFeedbacks(projectName: string): Promise<void>;\n}\n\n/** Payload sent from the widget to the server when submitting feedback. */\nexport interface FeedbackPayload {\n  projectName: string;\n  type: FeedbackType;\n  message: string;\n  url: string;\n  viewport: string;\n  userAgent: string;\n  authorName: string;\n  authorEmail: string;\n  annotations: AnnotationPayload[];\n  /** Client-generated UUID for deduplication */\n  clientId: string;\n}\n\n// ---------------------------------------------------------------------------\n// Annotation — multi-selector anchoring (Hypothesis / W3C Web Annotation)\n// ---------------------------------------------------------------------------\n\n/** DOM anchoring data for re-attaching annotations to page elements. */\nexport interface AnchorData {\n  /** CSS selector generated by @medv/finder — primary anchor */\n  cssSelector: string;\n  /** XPath — fallback 1 */\n  xpath: string;\n  /** First ~120 chars of element innerText — empty string if none */\n  textSnippet: string;\n  /** Tag name for validation (e.g. \"DIV\", \"SECTION\") */\n  elementTag: string;\n  /** Element id attribute if available — most stable */\n  elementId?: string | undefined;\n  /** ~32 chars of text before this element in document flow (disambiguation) */\n  textPrefix: string;\n  /** ~32 chars of text after this element in document flow (disambiguation) */\n  textSuffix: string;\n  /** Structural fingerprint: \"childCount:siblingIdx:attrHash\" */\n  fingerprint: string;\n  /** Text content of adjacent sibling elements (context) */\n  neighborText: string;\n}\n\n/** Drawn rectangle coordinates as percentages relative to the anchor element. */\nexport interface RectData {\n  /** X offset as fraction of anchor element width — must be in range [0, 1] */\n  xPct: number;\n  /** Y offset as fraction of anchor element height — must be in range [0, 1] */\n  yPct: number;\n  /** Width as fraction of anchor element width — must be in range [0, 1] */\n  wPct: number;\n  /** Height as fraction of anchor element height — must be in range [0, 1] */\n  hPct: number;\n}\n\n/** Annotation data sent as part of a feedback submission. */\nexport interface AnnotationPayload {\n  anchor: AnchorData;\n  rect: RectData;\n  scrollX: number;\n  scrollY: number;\n  viewportW: number;\n  viewportH: number;\n  devicePixelRatio: number;\n}\n\n// ---------------------------------------------------------------------------\n// API responses\n// ---------------------------------------------------------------------------\n\n/** Feedback record as returned by the API (dates serialized as strings). */\nexport interface FeedbackResponse {\n  id: string;\n  projectName: string;\n  type: FeedbackType;\n  message: string;\n  status: FeedbackStatus;\n  url: string;\n  viewport: string;\n  userAgent: string;\n  authorName: string;\n  authorEmail: string;\n  resolvedAt: string | null;\n  createdAt: string;\n  updatedAt: string;\n  annotations: AnnotationResponse[];\n}\n\n/** Annotation record as returned by the API. */\nexport interface AnnotationResponse {\n  id: string;\n  feedbackId: string;\n  cssSelector: string;\n  xpath: string;\n  textSnippet: string;\n  elementTag: string;\n  elementId: string | null;\n  textPrefix: string;\n  textSuffix: string;\n  fingerprint: string;\n  neighborText: string;\n  xPct: number;\n  yPct: number;\n  wPct: number;\n  hPct: number;\n  scrollX: number;\n  scrollY: number;\n  viewportW: number;\n  viewportH: number;\n  devicePixelRatio: number;\n  createdAt: string;\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,40 @@
+import { SitepingStore, FeedbackCreateInput, FeedbackRecord, FeedbackQuery, FeedbackUpdateInput } from './siteping-core.js';
+export { SitepingStore, StoreDuplicateError, StoreNotFoundError } from './siteping-core.js';
+
+/**
+ * In-memory `SitepingStore` implementation.
+ *
+ * Zero dependencies, works in any JS environment (Node, Bun, Deno, browser,
+ * Cloudflare Workers). Data lives in a plain array — lost on process restart.
+ *
+ * Use cases:
+ * - **Testing** — fast, isolated store for unit/integration tests
+ * - **Demos** — lightweight store that needs no database or localStorage
+ * - **Reference** — simplest possible adapter for contributors to study
+ *
+ * @example
+ * ```ts
+ * import { MemoryStore } from '@siteping/adapter-memory'
+ *
+ * const store = new MemoryStore()
+ * // Pass to createSitepingHandler({ store }) or initSiteping({ store })
+ * ```
+ */
+declare class MemoryStore implements SitepingStore {
+    private feedbacks;
+    private idCounter;
+    private generateId;
+    createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord>;
+    getFeedbacks(query: FeedbackQuery): Promise<{
+        feedbacks: FeedbackRecord[];
+        total: number;
+    }>;
+    findByClientId(clientId: string): Promise<FeedbackRecord | null>;
+    updateFeedback(id: string, data: FeedbackUpdateInput): Promise<FeedbackRecord>;
+    deleteFeedback(id: string): Promise<void>;
+    deleteAllFeedbacks(projectName: string): Promise<void>;
+    /** Remove all data from this store instance. */
+    clear(): void;
+}
+
+export { MemoryStore };

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import { SitepingStore, FeedbackCreateInput, FeedbackRecord, FeedbackQuery, FeedbackUpdateInput } from './siteping-core.js';
+export { SitepingStore, StoreDuplicateError, StoreNotFoundError } from './siteping-core.js';
+
+/**
+ * In-memory `SitepingStore` implementation.
+ *
+ * Zero dependencies, works in any JS environment (Node, Bun, Deno, browser,
+ * Cloudflare Workers). Data lives in a plain array — lost on process restart.
+ *
+ * Use cases:
+ * - **Testing** — fast, isolated store for unit/integration tests
+ * - **Demos** — lightweight store that needs no database or localStorage
+ * - **Reference** — simplest possible adapter for contributors to study
+ *
+ * @example
+ * ```ts
+ * import { MemoryStore } from '@siteping/adapter-memory'
+ *
+ * const store = new MemoryStore()
+ * // Pass to createSitepingHandler({ store }) or initSiteping({ store })
+ * ```
+ */
+declare class MemoryStore implements SitepingStore {
+    private feedbacks;
+    private idCounter;
+    private generateId;
+    createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord>;
+    getFeedbacks(query: FeedbackQuery): Promise<{
+        feedbacks: FeedbackRecord[];
+        total: number;
+    }>;
+    findByClientId(clientId: string): Promise<FeedbackRecord | null>;
+    updateFeedback(id: string, data: FeedbackUpdateInput): Promise<FeedbackRecord>;
+    deleteFeedback(id: string): Promise<void>;
+    deleteAllFeedbacks(projectName: string): Promise<void>;
+    /** Remove all data from this store instance. */
+    clear(): void;
+}
+
+export { MemoryStore };

package/dist/index.js

@@ -0,0 +1,116 @@
+// ../core/src/types.ts
+var StoreNotFoundError = class extends Error {
+  code = "STORE_NOT_FOUND";
+  constructor(message = "Record not found") {
+    super(message);
+    this.name = "StoreNotFoundError";
+  }
+};
+var StoreDuplicateError = class extends Error {
+  code = "STORE_DUPLICATE";
+  constructor(message = "Duplicate record") {
+    super(message);
+    this.name = "StoreDuplicateError";
+  }
+};
+
+// src/index.ts
+var MemoryStore = class {
+  feedbacks = [];
+  idCounter = 1;
+  generateId() {
+    return `mem-${this.idCounter++}-${Date.now().toString(36)}`;
+  }
+  async createFeedback(data) {
+    const existing = this.feedbacks.find((f) => f.clientId === data.clientId);
+    if (existing) return existing;
+    const now = /* @__PURE__ */ new Date();
+    const feedbackId = this.generateId();
+    const annotations = data.annotations.map((ann) => ({
+      id: this.generateId(),
+      feedbackId,
+      cssSelector: ann.cssSelector,
+      xpath: ann.xpath,
+      textSnippet: ann.textSnippet,
+      elementTag: ann.elementTag,
+      elementId: ann.elementId ?? null,
+      textPrefix: ann.textPrefix,
+      textSuffix: ann.textSuffix,
+      fingerprint: ann.fingerprint,
+      neighborText: ann.neighborText,
+      xPct: ann.xPct,
+      yPct: ann.yPct,
+      wPct: ann.wPct,
+      hPct: ann.hPct,
+      scrollX: ann.scrollX,
+      scrollY: ann.scrollY,
+      viewportW: ann.viewportW,
+      viewportH: ann.viewportH,
+      devicePixelRatio: ann.devicePixelRatio,
+      createdAt: now
+    }));
+    const record = {
+      id: feedbackId,
+      type: data.type,
+      message: data.message,
+      status: data.status,
+      projectName: data.projectName,
+      url: data.url,
+      authorName: data.authorName,
+      authorEmail: data.authorEmail,
+      viewport: data.viewport,
+      userAgent: data.userAgent,
+      clientId: data.clientId,
+      resolvedAt: null,
+      createdAt: now,
+      updatedAt: now,
+      annotations
+    };
+    this.feedbacks.unshift(record);
+    return record;
+  }
+  async getFeedbacks(query) {
+    let results = this.feedbacks.filter((f) => f.projectName === query.projectName);
+    if (query.type) results = results.filter((f) => f.type === query.type);
+    if (query.status) results = results.filter((f) => f.status === query.status);
+    if (query.search) {
+      const s = query.search.toLowerCase();
+      results = results.filter((f) => f.message.toLowerCase().includes(s));
+    }
+    const total = results.length;
+    const page = query.page ?? 1;
+    const limit = Math.min(query.limit ?? 50, 100);
+    const start = (page - 1) * limit;
+    return { feedbacks: results.slice(start, start + limit), total };
+  }
+  async findByClientId(clientId) {
+    return this.feedbacks.find((f) => f.clientId === clientId) ?? null;
+  }
+  async updateFeedback(id, data) {
+    const fb = this.feedbacks.find((f) => f.id === id);
+    if (!fb) throw new StoreNotFoundError();
+    fb.status = data.status;
+    fb.resolvedAt = data.resolvedAt;
+    fb.updatedAt = /* @__PURE__ */ new Date();
+    return fb;
+  }
+  async deleteFeedback(id) {
+    const idx = this.feedbacks.findIndex((f) => f.id === id);
+    if (idx === -1) throw new StoreNotFoundError();
+    this.feedbacks.splice(idx, 1);
+  }
+  async deleteAllFeedbacks(projectName) {
+    this.feedbacks = this.feedbacks.filter((f) => f.projectName !== projectName);
+  }
+  /** Remove all data from this store instance. */
+  clear() {
+    this.feedbacks = [];
+    this.idCounter = 1;
+  }
+};
+export {
+  MemoryStore,
+  StoreDuplicateError,
+  StoreNotFoundError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../core/src/types.ts","../src/index.ts"],"sourcesContent":["// ---------------------------------------------------------------------------\n// Config\n// ---------------------------------------------------------------------------\n\n/** Configuration options for the Siteping widget. */\nexport interface SitepingConfig {\n  /** HTTP endpoint that receives feedbacks (e.g. '/api/siteping'). Required unless `store` is provided. */\n  endpoint?: string | undefined;\n  /** Required — project identifier used to scope feedbacks */\n  projectName: string;\n  /** Direct store for client-side mode. When set, bypasses HTTP and uses the store directly in the browser. */\n  store?: SitepingStore | undefined;\n  /** FAB position — defaults to 'bottom-right' */\n  position?: \"bottom-right\" | \"bottom-left\";\n  /** Accent color for the widget UI — defaults to '#0066ff' */\n  accentColor?: string;\n  /** Show the widget even in production — defaults to false */\n  forceShow?: boolean;\n  /** Enable debug logging of lifecycle events — defaults to false */\n  debug?: boolean;\n  /** Color theme — defaults to 'light' */\n  theme?: \"light\" | \"dark\" | \"auto\";\n  /** UI locale — defaults to 'en' */\n  locale?: \"fr\" | \"en\" | (string & {}) | undefined;\n  /** Called when the widget is skipped (production mode, mobile viewport) */\n  onSkip?: (reason: \"production\" | \"mobile\") => void;\n\n  // Events\n  /** Called when the feedback panel is opened. */\n  onOpen?: () => void;\n  /** Called when the feedback panel is closed. */\n  onClose?: () => void;\n  onFeedbackSent?: (feedback: FeedbackResponse) => void;\n  onError?: (error: Error) => void;\n  /** Called when the user starts drawing an annotation. */\n  onAnnotationStart?: () => void;\n  /** Called when the user finishes drawing an annotation. */\n  onAnnotationEnd?: () => void;\n}\n\n/** Instance returned by initSiteping() with lifecycle methods. */\nexport interface SitepingInstance {\n  /** Remove the widget from the DOM and clean up all listeners. */\n  destroy: () => void;\n  /** Open the panel programmatically */\n  open: () => void;\n  /** Close the panel */\n  close: () => void;\n  /** Reload feedbacks from server */\n  refresh: () => void;\n  /** Subscribe to a public widget event */\n  on: <K extends keyof SitepingPublicEvents>(\n    event: K,\n    listener: (...args: SitepingPublicEvents[K]) => void,\n  ) => () => void;\n  /** Unsubscribe from a public widget event */\n  off: <K extends keyof SitepingPublicEvents>(event: K, listener: (...args: SitepingPublicEvents[K]) => void) => void;\n}\n\n/** Events exposed to consumers via SitepingInstance.on / .off */\nexport interface SitepingPublicEvents {\n  \"feedback:sent\": [FeedbackResponse];\n  \"feedback:deleted\": [string];\n  \"panel:open\": [];\n  \"panel:close\": [];\n}\n\n// ---------------------------------------------------------------------------\n// Feedback\n// ---------------------------------------------------------------------------\n\n/** Single source of truth for feedback types — used by both TS types and Zod schemas. */\nexport const FEEDBACK_TYPES = [\"question\", \"change\", \"bug\", \"other\"] as const;\nexport type FeedbackType = (typeof FEEDBACK_TYPES)[number];\n\n/** Single source of truth for feedback statuses. */\nexport const FEEDBACK_STATUSES = [\"open\", \"resolved\"] as const;\nexport type FeedbackStatus = (typeof FEEDBACK_STATUSES)[number];\n\n// ---------------------------------------------------------------------------\n// Abstract Store — adapter pattern\n// ---------------------------------------------------------------------------\n\n/** Input for creating a feedback record in the store. */\nexport interface FeedbackCreateInput {\n  projectName: string;\n  type: FeedbackType;\n  message: string;\n  status: FeedbackStatus;\n  url: string;\n  viewport: string;\n  userAgent: string;\n  authorName: string;\n  authorEmail: string;\n  clientId: string;\n  annotations: AnnotationCreateInput[];\n}\n\n/** Input for a single annotation when creating a feedback. */\nexport interface AnnotationCreateInput {\n  cssSelector: string;\n  xpath: string;\n  textSnippet: string;\n  elementTag: string;\n  elementId?: string | undefined;\n  textPrefix: string;\n  textSuffix: string;\n  fingerprint: string;\n  neighborText: string;\n  xPct: number;\n  yPct: number;\n  wPct: number;\n  hPct: number;\n  scrollX: number;\n  scrollY: number;\n  viewportW: number;\n  viewportH: number;\n  devicePixelRatio: number;\n}\n\n/** Query parameters for fetching feedbacks. */\nexport interface FeedbackQuery {\n  projectName: string;\n  type?: FeedbackType | undefined;\n  status?: FeedbackStatus | undefined;\n  search?: string | undefined;\n  page?: number | undefined;\n  limit?: number | undefined;\n}\n\n/** Update payload for patching a feedback. */\nexport interface FeedbackUpdateInput {\n  status: FeedbackStatus;\n  resolvedAt: Date | null;\n}\n\n/** A persisted feedback record returned by the store. */\nexport interface FeedbackRecord {\n  id: string;\n  type: FeedbackType;\n  message: string;\n  status: FeedbackStatus;\n  projectName: string;\n  url: string;\n  authorName: string;\n  authorEmail: string;\n  viewport: string;\n  userAgent: string;\n  clientId: string;\n  resolvedAt: Date | null;\n  createdAt: Date;\n  updatedAt: Date;\n  annotations: AnnotationRecord[];\n}\n\n/** A persisted annotation record returned by the store. */\nexport interface AnnotationRecord {\n  id: string;\n  feedbackId: string;\n  cssSelector: string;\n  xpath: string;\n  textSnippet: string;\n  elementTag: string;\n  elementId: string | null;\n  textPrefix: string;\n  textSuffix: string;\n  fingerprint: string;\n  neighborText: string;\n  xPct: number;\n  yPct: number;\n  wPct: number;\n  hPct: number;\n  scrollX: number;\n  scrollY: number;\n  viewportW: number;\n  viewportH: number;\n  devicePixelRatio: number;\n  createdAt: Date;\n}\n\n// ---------------------------------------------------------------------------\n// Store errors — throw these from adapter implementations\n// ---------------------------------------------------------------------------\n\n/**\n * Thrown when a record is not found during update or delete.\n *\n * Handlers translate this to HTTP 404. Adapters MUST throw this (not\n * ORM-specific errors) so the handler layer remains ORM-agnostic.\n */\nexport class StoreNotFoundError extends Error {\n  readonly code = \"STORE_NOT_FOUND\" as const;\n  constructor(message = \"Record not found\") {\n    super(message);\n    this.name = \"StoreNotFoundError\";\n  }\n}\n\n/**\n * Thrown when a unique constraint is violated (e.g. duplicate `clientId`).\n *\n * Handlers use this to return the existing record instead of failing.\n */\nexport class StoreDuplicateError extends Error {\n  readonly code = \"STORE_DUPLICATE\" as const;\n  constructor(message = \"Duplicate record\") {\n    super(message);\n    this.name = \"StoreDuplicateError\";\n  }\n}\n\n/** Type guard — works for `StoreNotFoundError` and ORM-specific equivalents (e.g. Prisma P2025). */\nexport function isStoreNotFound(error: unknown): boolean {\n  if (error instanceof StoreNotFoundError) return true;\n  // Backwards compat: Prisma's P2025\n  return typeof error === \"object\" && error !== null && \"code\" in error && (error as { code: string }).code === \"P2025\";\n}\n\n/** Type guard — works for `StoreDuplicateError` and ORM-specific equivalents (e.g. Prisma P2002). */\nexport function isStoreDuplicate(error: unknown): boolean {\n  if (error instanceof StoreDuplicateError) return true;\n  // Backwards compat: Prisma's P2002\n  return typeof error === \"object\" && error !== null && \"code\" in error && (error as { code: string }).code === \"P2002\";\n}\n\n// ---------------------------------------------------------------------------\n// Store helpers — shared conversion logic for adapters\n// ---------------------------------------------------------------------------\n\n/** Flatten a widget `AnnotationPayload` (nested anchor + rect) into a flat `AnnotationCreateInput`. */\nexport function flattenAnnotation(ann: AnnotationPayload): AnnotationCreateInput {\n  return {\n    cssSelector: ann.anchor.cssSelector,\n    xpath: ann.anchor.xpath,\n    textSnippet: ann.anchor.textSnippet,\n    elementTag: ann.anchor.elementTag,\n    elementId: ann.anchor.elementId,\n    textPrefix: ann.anchor.textPrefix,\n    textSuffix: ann.anchor.textSuffix,\n    fingerprint: ann.anchor.fingerprint,\n    neighborText: ann.anchor.neighborText,\n    xPct: ann.rect.xPct,\n    yPct: ann.rect.yPct,\n    wPct: ann.rect.wPct,\n    hPct: ann.rect.hPct,\n    scrollX: ann.scrollX,\n    scrollY: ann.scrollY,\n    viewportW: ann.viewportW,\n    viewportH: ann.viewportH,\n    devicePixelRatio: ann.devicePixelRatio,\n  };\n}\n\n// ---------------------------------------------------------------------------\n// Abstract Store — adapter pattern\n// ---------------------------------------------------------------------------\n\n/**\n * Abstract storage interface for Siteping.\n *\n * Any adapter (Prisma, Drizzle, raw SQL, localStorage, etc.) implements this\n * interface. The HTTP handler and widget `StoreClient` operate against\n * `SitepingStore`, decoupled from the storage backend.\n *\n * ## Error contract\n *\n * - **`updateFeedback` / `deleteFeedback`**: throw `StoreNotFoundError` when\n *   the record does not exist.\n * - **`createFeedback`**: either return the existing record on duplicate\n *   `clientId` (idempotent) or throw `StoreDuplicateError`. The handler\n *   handles both patterns.\n * - Other methods should not throw on empty results — return empty arrays or `null`.\n */\nexport interface SitepingStore {\n  /** Create a feedback with its annotations. Idempotent on `clientId` — return existing record on duplicate, or throw `StoreDuplicateError`. */\n  createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord>;\n  /** Paginated query with optional filters. Returns empty array (not error) when no results. */\n  getFeedbacks(query: FeedbackQuery): Promise<{ feedbacks: FeedbackRecord[]; total: number }>;\n  /** Lookup by client-generated UUID. Returns `null` (not error) when not found. */\n  findByClientId(clientId: string): Promise<FeedbackRecord | null>;\n  /** Update status/resolvedAt. Throws `StoreNotFoundError` if `id` does not exist. */\n  updateFeedback(id: string, data: FeedbackUpdateInput): Promise<FeedbackRecord>;\n  /** Delete a single record. Throws `StoreNotFoundError` if `id` does not exist. */\n  deleteFeedback(id: string): Promise<void>;\n  /** Bulk delete all feedbacks for a project. No-op (not error) if none exist. */\n  deleteAllFeedbacks(projectName: string): Promise<void>;\n}\n\n/** Payload sent from the widget to the server when submitting feedback. */\nexport interface FeedbackPayload {\n  projectName: string;\n  type: FeedbackType;\n  message: string;\n  url: string;\n  viewport: string;\n  userAgent: string;\n  authorName: string;\n  authorEmail: string;\n  annotations: AnnotationPayload[];\n  /** Client-generated UUID for deduplication */\n  clientId: string;\n}\n\n// ---------------------------------------------------------------------------\n// Annotation — multi-selector anchoring (Hypothesis / W3C Web Annotation)\n// ---------------------------------------------------------------------------\n\n/** DOM anchoring data for re-attaching annotations to page elements. */\nexport interface AnchorData {\n  /** CSS selector generated by @medv/finder — primary anchor */\n  cssSelector: string;\n  /** XPath — fallback 1 */\n  xpath: string;\n  /** First ~120 chars of element innerText — empty string if none */\n  textSnippet: string;\n  /** Tag name for validation (e.g. \"DIV\", \"SECTION\") */\n  elementTag: string;\n  /** Element id attribute if available — most stable */\n  elementId?: string | undefined;\n  /** ~32 chars of text before this element in document flow (disambiguation) */\n  textPrefix: string;\n  /** ~32 chars of text after this element in document flow (disambiguation) */\n  textSuffix: string;\n  /** Structural fingerprint: \"childCount:siblingIdx:attrHash\" */\n  fingerprint: string;\n  /** Text content of adjacent sibling elements (context) */\n  neighborText: string;\n}\n\n/** Drawn rectangle coordinates as percentages relative to the anchor element. */\nexport interface RectData {\n  /** X offset as fraction of anchor element width — must be in range [0, 1] */\n  xPct: number;\n  /** Y offset as fraction of anchor element height — must be in range [0, 1] */\n  yPct: number;\n  /** Width as fraction of anchor element width — must be in range [0, 1] */\n  wPct: number;\n  /** Height as fraction of anchor element height — must be in range [0, 1] */\n  hPct: number;\n}\n\n/** Annotation data sent as part of a feedback submission. */\nexport interface AnnotationPayload {\n  anchor: AnchorData;\n  rect: RectData;\n  scrollX: number;\n  scrollY: number;\n  viewportW: number;\n  viewportH: number;\n  devicePixelRatio: number;\n}\n\n// ---------------------------------------------------------------------------\n// API responses\n// ---------------------------------------------------------------------------\n\n/** Feedback record as returned by the API (dates serialized as strings). */\nexport interface FeedbackResponse {\n  id: string;\n  projectName: string;\n  type: FeedbackType;\n  message: string;\n  status: FeedbackStatus;\n  url: string;\n  viewport: string;\n  userAgent: string;\n  authorName: string;\n  authorEmail: string;\n  resolvedAt: string | null;\n  createdAt: string;\n  updatedAt: string;\n  annotations: AnnotationResponse[];\n}\n\n/** Annotation record as returned by the API. */\nexport interface AnnotationResponse {\n  id: string;\n  feedbackId: string;\n  cssSelector: string;\n  xpath: string;\n  textSnippet: string;\n  elementTag: string;\n  elementId: string | null;\n  textPrefix: string;\n  textSuffix: string;\n  fingerprint: string;\n  neighborText: string;\n  xPct: number;\n  yPct: number;\n  wPct: number;\n  hPct: number;\n  scrollX: number;\n  scrollY: number;\n  viewportW: number;\n  viewportH: number;\n  devicePixelRatio: number;\n  createdAt: string;\n}\n","import {\n  type AnnotationCreateInput,\n  type AnnotationRecord,\n  type FeedbackCreateInput,\n  type FeedbackQuery,\n  type FeedbackRecord,\n  type FeedbackUpdateInput,\n  type SitepingStore,\n  StoreNotFoundError,\n} from \"@siteping/core\";\n\nexport type { SitepingStore } from \"@siteping/core\";\nexport { StoreDuplicateError, StoreNotFoundError } from \"@siteping/core\";\n\n/**\n * In-memory `SitepingStore` implementation.\n *\n * Zero dependencies, works in any JS environment (Node, Bun, Deno, browser,\n * Cloudflare Workers). Data lives in a plain array — lost on process restart.\n *\n * Use cases:\n * - **Testing** — fast, isolated store for unit/integration tests\n * - **Demos** — lightweight store that needs no database or localStorage\n * - **Reference** — simplest possible adapter for contributors to study\n *\n * @example\n * ```ts\n * import { MemoryStore } from '@siteping/adapter-memory'\n *\n * const store = new MemoryStore()\n * // Pass to createSitepingHandler({ store }) or initSiteping({ store })\n * ```\n */\nexport class MemoryStore implements SitepingStore {\n  private feedbacks: FeedbackRecord[] = [];\n  private idCounter = 1;\n\n  private generateId(): string {\n    return `mem-${this.idCounter++}-${Date.now().toString(36)}`;\n  }\n\n  async createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord> {\n    // ClientId dedup — idempotent\n    const existing = this.feedbacks.find((f) => f.clientId === data.clientId);\n    if (existing) return existing;\n\n    const now = new Date();\n    const feedbackId = this.generateId();\n\n    const annotations: AnnotationRecord[] = data.annotations.map((ann: AnnotationCreateInput) => ({\n      id: this.generateId(),\n      feedbackId,\n      cssSelector: ann.cssSelector,\n      xpath: ann.xpath,\n      textSnippet: ann.textSnippet,\n      elementTag: ann.elementTag,\n      elementId: ann.elementId ?? null,\n      textPrefix: ann.textPrefix,\n      textSuffix: ann.textSuffix,\n      fingerprint: ann.fingerprint,\n      neighborText: ann.neighborText,\n      xPct: ann.xPct,\n      yPct: ann.yPct,\n      wPct: ann.wPct,\n      hPct: ann.hPct,\n      scrollX: ann.scrollX,\n      scrollY: ann.scrollY,\n      viewportW: ann.viewportW,\n      viewportH: ann.viewportH,\n      devicePixelRatio: ann.devicePixelRatio,\n      createdAt: now,\n    }));\n\n    const record: FeedbackRecord = {\n      id: feedbackId,\n      type: data.type,\n      message: data.message,\n      status: data.status,\n      projectName: data.projectName,\n      url: data.url,\n      authorName: data.authorName,\n      authorEmail: data.authorEmail,\n      viewport: data.viewport,\n      userAgent: data.userAgent,\n      clientId: data.clientId,\n      resolvedAt: null,\n      createdAt: now,\n      updatedAt: now,\n      annotations,\n    };\n\n    this.feedbacks.unshift(record);\n    return record;\n  }\n\n  async getFeedbacks(query: FeedbackQuery): Promise<{ feedbacks: FeedbackRecord[]; total: number }> {\n    let results = this.feedbacks.filter((f) => f.projectName === query.projectName);\n\n    if (query.type) results = results.filter((f) => f.type === query.type);\n    if (query.status) results = results.filter((f) => f.status === query.status);\n    if (query.search) {\n      const s = query.search.toLowerCase();\n      results = results.filter((f) => f.message.toLowerCase().includes(s));\n    }\n\n    const total = results.length;\n    const page = query.page ?? 1;\n    const limit = Math.min(query.limit ?? 50, 100);\n    const start = (page - 1) * limit;\n\n    return { feedbacks: results.slice(start, start + limit), total };\n  }\n\n  async findByClientId(clientId: string): Promise<FeedbackRecord | null> {\n    return this.feedbacks.find((f) => f.clientId === clientId) ?? null;\n  }\n\n  async updateFeedback(id: string, data: FeedbackUpdateInput): Promise<FeedbackRecord> {\n    const fb = this.feedbacks.find((f) => f.id === id);\n    if (!fb) throw new StoreNotFoundError();\n\n    fb.status = data.status;\n    fb.resolvedAt = data.resolvedAt;\n    fb.updatedAt = new Date();\n    return fb;\n  }\n\n  async deleteFeedback(id: string): Promise<void> {\n    const idx = this.feedbacks.findIndex((f) => f.id === id);\n    if (idx === -1) throw new StoreNotFoundError();\n    this.feedbacks.splice(idx, 1);\n  }\n\n  async deleteAllFeedbacks(projectName: string): Promise<void> {\n    this.feedbacks = this.feedbacks.filter((f) => f.projectName !== projectName);\n  }\n\n  /** Remove all data from this store instance. */\n  clear(): void {\n    this.feedbacks = [];\n    this.idCounter = 1;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/schema.d.ts

@@ -0,0 +1,198 @@
+/**
+ * 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.
+ */
+/** Definition of a single field in a Siteping database model. */
+export interface FieldDef {
+    type: string;
+    default?: string;
+    optional?: boolean;
+    relation?: {
+        kind: "1-to-many" | "many-to-1";
+        model: string;
+        fields?: string[];
+        references?: string[];
+        onDelete?: string;
+    };
+    isId?: boolean;
+    isUnique?: boolean;
+    /** Prisma native type attribute (e.g. "Text" for @db.Text) — used for MySQL compatibility on long strings */
+    nativeType?: string;
+    /** Prisma @updatedAt attribute */
+    isUpdatedAt?: boolean;
+}
+/** Definition of a composite index on a Siteping database model. */
+export interface IndexDef {
+    fields: string[];
+}
+/** Definition of a single Siteping database model (fields + indexes). */
+export interface ModelDef {
+    fields: Record<string, FieldDef>;
+    indexes?: IndexDef[];
+}
+export declare const SITEPING_MODELS: Readonly<{
+    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 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 fields: ["projectName"];
+        }, {
+            readonly fields: ["projectName", "status", "createdAt"];
+        }];
+    };
+    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: ["feedbackId"];
+                    readonly references: ["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 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 fields: ["feedbackId"];
+        }];
+    };
+}>;

package/dist/siteping-core.d.ts

@@ -0,0 +1,4 @@
+export type { FieldDef, IndexDef, ModelDef } from "./schema.js";
+export { SITEPING_MODELS } from "./schema.js";
+export type { AnchorData, AnnotationCreateInput, AnnotationPayload, AnnotationRecord, AnnotationResponse, FeedbackCreateInput, FeedbackPayload, FeedbackQuery, FeedbackRecord, FeedbackResponse, FeedbackStatus, FeedbackType, FeedbackUpdateInput, RectData, SitepingConfig, SitepingInstance, SitepingPublicEvents, SitepingStore, } from "./types.js";
+export { FEEDBACK_STATUSES, FEEDBACK_TYPES, flattenAnnotation, isStoreDuplicate, isStoreNotFound, StoreDuplicateError, StoreNotFoundError, } from "./types.js";

package/dist/types.d.ts

@@ -0,0 +1,307 @@
+/** Configuration options for the Siteping widget. */
+export interface SitepingConfig {
+    /** HTTP endpoint that receives feedbacks (e.g. '/api/siteping'). Required unless `store` is provided. */
+    endpoint?: string | undefined;
+    /** Required — project identifier used to scope feedbacks */
+    projectName: string;
+    /** Direct store for client-side mode. When set, bypasses HTTP and uses the store directly in the browser. */
+    store?: SitepingStore | undefined;
+    /** FAB position — defaults to 'bottom-right' */
+    position?: "bottom-right" | "bottom-left";
+    /** Accent color for the widget UI — defaults to '#0066ff' */
+    accentColor?: string;
+    /** Show the widget even in production — defaults to false */
+    forceShow?: boolean;
+    /** Enable debug logging of lifecycle events — defaults to false */
+    debug?: boolean;
+    /** Color theme — defaults to 'light' */
+    theme?: "light" | "dark" | "auto";
+    /** UI locale — defaults to 'en' */
+    locale?: "fr" | "en" | (string & {}) | undefined;
+    /** Called when the widget is skipped (production mode, mobile viewport) */
+    onSkip?: (reason: "production" | "mobile") => void;
+    /** Called when the feedback panel is opened. */
+    onOpen?: () => void;
+    /** Called when the feedback panel is closed. */
+    onClose?: () => void;
+    onFeedbackSent?: (feedback: FeedbackResponse) => void;
+    onError?: (error: Error) => void;
+    /** Called when the user starts drawing an annotation. */
+    onAnnotationStart?: () => void;
+    /** Called when the user finishes drawing an annotation. */
+    onAnnotationEnd?: () => void;
+}
+/** Instance returned by initSiteping() with lifecycle methods. */
+export interface SitepingInstance {
+    /** Remove the widget from the DOM and clean up all listeners. */
+    destroy: () => void;
+    /** Open the panel programmatically */
+    open: () => void;
+    /** Close the panel */
+    close: () => void;
+    /** Reload feedbacks from server */
+    refresh: () => void;
+    /** Subscribe to a public widget event */
+    on: <K extends keyof SitepingPublicEvents>(event: K, listener: (...args: SitepingPublicEvents[K]) => void) => () => void;
+    /** Unsubscribe from a public widget event */
+    off: <K extends keyof SitepingPublicEvents>(event: K, listener: (...args: SitepingPublicEvents[K]) => void) => void;
+}
+/** Events exposed to consumers via SitepingInstance.on / .off */
+export interface SitepingPublicEvents {
+    "feedback:sent": [FeedbackResponse];
+    "feedback:deleted": [string];
+    "panel:open": [];
+    "panel:close": [];
+}
+/** Single source of truth for feedback types — used by both TS types and Zod schemas. */
+export declare const FEEDBACK_TYPES: readonly ["question", "change", "bug", "other"];
+export type FeedbackType = (typeof FEEDBACK_TYPES)[number];
+/** Single source of truth for feedback statuses. */
+export declare const FEEDBACK_STATUSES: readonly ["open", "resolved"];
+export type FeedbackStatus = (typeof FEEDBACK_STATUSES)[number];
+/** Input for creating a feedback record in the store. */
+export interface FeedbackCreateInput {
+    projectName: string;
+    type: FeedbackType;
+    message: string;
+    status: FeedbackStatus;
+    url: string;
+    viewport: string;
+    userAgent: string;
+    authorName: string;
+    authorEmail: string;
+    clientId: string;
+    annotations: AnnotationCreateInput[];
+}
+/** Input for a single annotation when creating a feedback. */
+export interface AnnotationCreateInput {
+    cssSelector: string;
+    xpath: string;
+    textSnippet: string;
+    elementTag: string;
+    elementId?: string | undefined;
+    textPrefix: string;
+    textSuffix: string;
+    fingerprint: string;
+    neighborText: string;
+    xPct: number;
+    yPct: number;
+    wPct: number;
+    hPct: number;
+    scrollX: number;
+    scrollY: number;
+    viewportW: number;
+    viewportH: number;
+    devicePixelRatio: number;
+}
+/** Query parameters for fetching feedbacks. */
+export interface FeedbackQuery {
+    projectName: string;
+    type?: FeedbackType | undefined;
+    status?: FeedbackStatus | undefined;
+    search?: string | undefined;
+    page?: number | undefined;
+    limit?: number | undefined;
+}
+/** Update payload for patching a feedback. */
+export interface FeedbackUpdateInput {
+    status: FeedbackStatus;
+    resolvedAt: Date | null;
+}
+/** A persisted feedback record returned by the store. */
+export interface FeedbackRecord {
+    id: string;
+    type: FeedbackType;
+    message: string;
+    status: FeedbackStatus;
+    projectName: string;
+    url: string;
+    authorName: string;
+    authorEmail: string;
+    viewport: string;
+    userAgent: string;
+    clientId: string;
+    resolvedAt: Date | null;
+    createdAt: Date;
+    updatedAt: Date;
+    annotations: AnnotationRecord[];
+}
+/** A persisted annotation record returned by the store. */
+export interface AnnotationRecord {
+    id: string;
+    feedbackId: string;
+    cssSelector: string;
+    xpath: string;
+    textSnippet: string;
+    elementTag: string;
+    elementId: string | null;
+    textPrefix: string;
+    textSuffix: string;
+    fingerprint: string;
+    neighborText: string;
+    xPct: number;
+    yPct: number;
+    wPct: number;
+    hPct: number;
+    scrollX: number;
+    scrollY: number;
+    viewportW: number;
+    viewportH: number;
+    devicePixelRatio: number;
+    createdAt: Date;
+}
+/**
+ * Thrown when a record is not found during update or delete.
+ *
+ * Handlers translate this to HTTP 404. Adapters MUST throw this (not
+ * ORM-specific errors) so the handler layer remains ORM-agnostic.
+ */
+export declare class StoreNotFoundError extends Error {
+    readonly code: "STORE_NOT_FOUND";
+    constructor(message?: string);
+}
+/**
+ * Thrown when a unique constraint is violated (e.g. duplicate `clientId`).
+ *
+ * Handlers use this to return the existing record instead of failing.
+ */
+export declare class StoreDuplicateError extends Error {
+    readonly code: "STORE_DUPLICATE";
+    constructor(message?: string);
+}
+/** Type guard — works for `StoreNotFoundError` and ORM-specific equivalents (e.g. Prisma P2025). */
+export declare function isStoreNotFound(error: unknown): boolean;
+/** Type guard — works for `StoreDuplicateError` and ORM-specific equivalents (e.g. Prisma P2002). */
+export declare function isStoreDuplicate(error: unknown): boolean;
+/** Flatten a widget `AnnotationPayload` (nested anchor + rect) into a flat `AnnotationCreateInput`. */
+export declare function flattenAnnotation(ann: AnnotationPayload): AnnotationCreateInput;
+/**
+ * Abstract storage interface for Siteping.
+ *
+ * Any adapter (Prisma, Drizzle, raw SQL, localStorage, etc.) implements this
+ * interface. The HTTP handler and widget `StoreClient` operate against
+ * `SitepingStore`, decoupled from the storage backend.
+ *
+ * ## Error contract
+ *
+ * - **`updateFeedback` / `deleteFeedback`**: throw `StoreNotFoundError` when
+ *   the record does not exist.
+ * - **`createFeedback`**: either return the existing record on duplicate
+ *   `clientId` (idempotent) or throw `StoreDuplicateError`. The handler
+ *   handles both patterns.
+ * - Other methods should not throw on empty results — return empty arrays or `null`.
+ */
+export interface SitepingStore {
+    /** Create a feedback with its annotations. Idempotent on `clientId` — return existing record on duplicate, or throw `StoreDuplicateError`. */
+    createFeedback(data: FeedbackCreateInput): Promise<FeedbackRecord>;
+    /** Paginated query with optional filters. Returns empty array (not error) when no results. */
+    getFeedbacks(query: FeedbackQuery): Promise<{
+        feedbacks: FeedbackRecord[];
+        total: number;
+    }>;
+    /** Lookup by client-generated UUID. Returns `null` (not error) when not found. */
+    findByClientId(clientId: string): Promise<FeedbackRecord | null>;
+    /** Update status/resolvedAt. Throws `StoreNotFoundError` if `id` does not exist. */
+    updateFeedback(id: string, data: FeedbackUpdateInput): Promise<FeedbackRecord>;
+    /** Delete a single record. Throws `StoreNotFoundError` if `id` does not exist. */
+    deleteFeedback(id: string): Promise<void>;
+    /** Bulk delete all feedbacks for a project. No-op (not error) if none exist. */
+    deleteAllFeedbacks(projectName: string): Promise<void>;
+}
+/** Payload sent from the widget to the server when submitting feedback. */
+export interface FeedbackPayload {
+    projectName: string;
+    type: FeedbackType;
+    message: string;
+    url: string;
+    viewport: string;
+    userAgent: string;
+    authorName: string;
+    authorEmail: string;
+    annotations: AnnotationPayload[];
+    /** Client-generated UUID for deduplication */
+    clientId: string;
+}
+/** DOM anchoring data for re-attaching annotations to page elements. */
+export interface AnchorData {
+    /** CSS selector generated by @medv/finder — primary anchor */
+    cssSelector: string;
+    /** XPath — fallback 1 */
+    xpath: string;
+    /** First ~120 chars of element innerText — empty string if none */
+    textSnippet: string;
+    /** Tag name for validation (e.g. "DIV", "SECTION") */
+    elementTag: string;
+    /** Element id attribute if available — most stable */
+    elementId?: string | undefined;
+    /** ~32 chars of text before this element in document flow (disambiguation) */
+    textPrefix: string;
+    /** ~32 chars of text after this element in document flow (disambiguation) */
+    textSuffix: string;
+    /** Structural fingerprint: "childCount:siblingIdx:attrHash" */
+    fingerprint: string;
+    /** Text content of adjacent sibling elements (context) */
+    neighborText: string;
+}
+/** Drawn rectangle coordinates as percentages relative to the anchor element. */
+export interface RectData {
+    /** X offset as fraction of anchor element width — must be in range [0, 1] */
+    xPct: number;
+    /** Y offset as fraction of anchor element height — must be in range [0, 1] */
+    yPct: number;
+    /** Width as fraction of anchor element width — must be in range [0, 1] */
+    wPct: number;
+    /** Height as fraction of anchor element height — must be in range [0, 1] */
+    hPct: number;
+}
+/** Annotation data sent as part of a feedback submission. */
+export interface AnnotationPayload {
+    anchor: AnchorData;
+    rect: RectData;
+    scrollX: number;
+    scrollY: number;
+    viewportW: number;
+    viewportH: number;
+    devicePixelRatio: number;
+}
+/** Feedback record as returned by the API (dates serialized as strings). */
+export interface FeedbackResponse {
+    id: string;
+    projectName: string;
+    type: FeedbackType;
+    message: string;
+    status: FeedbackStatus;
+    url: string;
+    viewport: string;
+    userAgent: string;
+    authorName: string;
+    authorEmail: string;
+    resolvedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    annotations: AnnotationResponse[];
+}
+/** Annotation record as returned by the API. */
+export interface AnnotationResponse {
+    id: string;
+    feedbackId: string;
+    cssSelector: string;
+    xpath: string;
+    textSnippet: string;
+    elementTag: string;
+    elementId: string | null;
+    textPrefix: string;
+    textSuffix: string;
+    fingerprint: string;
+    neighborText: string;
+    xPct: number;
+    yPct: number;
+    wPct: number;
+    hPct: number;
+    scrollX: number;
+    scrollY: number;
+    viewportW: number;
+    viewportH: number;
+    devicePixelRatio: number;
+    createdAt: string;
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@siteping/adapter-memory",
+  "version": "0.4.3",
+  "description": "In-memory adapter for Siteping — zero dependencies, works everywhere",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup && node ../../scripts/fix-dts.mjs dist",
+    "check": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "keywords": [
+    "siteping",
+    "memory",
+    "adapter",
+    "feedback",
+    "testing",
+    "demo",
+    "typescript"
+  ],
+  "author": "neosianexus",
+  "license": "MIT",
+  "homepage": "https://siteping.dev",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NeosiaNexus/SitePing.git",
+    "directory": "packages/adapter-memory"
+  },
+  "bugs": {
+    "url": "https://github.com/NeosiaNexus/SitePing/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@siteping/core": "workspace:*"
+  }
+}