@mahmulp/feedback-sdk 0.0.1

package/dist/mock.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Wire types shared between the SDK, the API, and the dashboard.
+ *
+ * NOTE: This file is the SDK's authoritative copy. The same shapes also live
+ * in `packages/shared-types/src/index.ts` for the API and dashboard. Keep
+ * them in sync when the wire format evolves.
+ */
+type FeedbackStatus = "open" | "resolved" | "archived";
+/** Pin coordinates: percentage-based (for re-rendering) and pixel (fallback). */
+interface FeedbackCoordinates {
+    /** 0..1, x position relative to the target element's bounding box. */
+    xPercent: number;
+    /** 0..1, y position relative to the target element's bounding box. */
+    yPercent: number;
+    /** Absolute x position in page pixels at capture time. */
+    xPx: number;
+    /** Absolute y position in page pixels at capture time. */
+    yPx: number;
+}
+interface ViewportInfo {
+    width: number;
+    height: number;
+    devicePixelRatio: number;
+}
+interface FeedbackAuthor {
+    name: string;
+    email?: string;
+}
+interface FeedbackComment {
+    id: string;
+    author: FeedbackAuthor;
+    body: string;
+    createdAt: string;
+}
+/** A pin/feedback record as seen on the wire. */
+interface Feedback {
+    id: string;
+    projectId: string;
+    pageUrl: string;
+    selector: string;
+    coordinates: FeedbackCoordinates;
+    viewport: ViewportInfo;
+    /** Storage key returned by the API after upload. Absent until a screenshot is uploaded. */
+    screenshotKey?: string;
+    status: FeedbackStatus;
+    thread: FeedbackComment[];
+    createdAt: string;
+    updatedAt: string;
+}
+/** Payload the SDK sends to create a new pin. The server fills in id/timestamps/status/thread. */
+interface CreateFeedbackInput {
+    projectId: string;
+    pageUrl: string;
+    selector: string;
+    coordinates: FeedbackCoordinates;
+    viewport: ViewportInfo;
+    /** Optional first comment posted alongside the pin. */
+    comment?: {
+        author: FeedbackAuthor;
+        body: string;
+    };
+}
+interface ListFeedbackQuery {
+    projectId: string;
+    pageUrl?: string;
+    status?: FeedbackStatus;
+}
+interface ListFeedbackResult {
+    items: Feedback[];
+}
+/**
+ * Transport contract used by the SDK to talk to "something that persists feedback".
+ * Default HTTP implementation lives in `transport.ts`. The mock transport in `mock.ts`
+ * is useful for local demos and tests.
+ */
+interface FeedbackTransport {
+    list(query: ListFeedbackQuery): Promise<ListFeedbackResult>;
+    create(input: CreateFeedbackInput): Promise<Feedback>;
+    reply(feedbackId: string, comment: {
+        author: FeedbackAuthor;
+        body: string;
+    }): Promise<Feedback>;
+    setStatus(feedbackId: string, status: FeedbackStatus): Promise<Feedback>;
+    /** Move a pin: persist new percent + pixel coordinates after a drag. */
+    move?(feedbackId: string, coordinates: FeedbackCoordinates): Promise<Feedback>;
+    /** Upload a screenshot blob for an already-created feedback. Returns the updated record. */
+    uploadScreenshot?(feedbackId: string, blob: Blob): Promise<Feedback>;
+}
+
+/**
+ * In-memory transport for local development / demos / tests.
+ *
+ *   import { createMockTransport } from '@mahmulp/feedback-sdk/mock'
+ *
+ * No persistence, no network. Useful before the API is wired up.
+ */
+interface MockTransportOptions {
+    /** Optional initial feedback records (e.g. seeded from a fixture). */
+    initial?: Feedback[];
+    /** Override id generation (defaults to `fb_<timestamp>_<rand>`). */
+    generateId?: () => string;
+    /** Optional fake latency in ms, applied to every call. */
+    latencyMs?: number;
+}
+declare function createMockTransport(options?: MockTransportOptions): FeedbackTransport & {
+    /** Direct read of the in-memory store for tests / debugging. */
+    _all(): Feedback[];
+    _reset(): void;
+};
+
+export { type MockTransportOptions, createMockTransport };

package/dist/mock.js

@@ -0,0 +1,96 @@
+// src/mock.ts
+function createMockTransport(options = {}) {
+  const items = options.initial ? options.initial.map(clone) : [];
+  const genId = options.generateId ?? defaultGenerateId;
+  const latency = options.latencyMs ?? 0;
+  async function delay() {
+    if (latency > 0) await new Promise((r) => setTimeout(r, latency));
+  }
+  return {
+    async list(query) {
+      await delay();
+      const filtered = items.filter((f) => query.projectId ? f.projectId === query.projectId : true).filter((f) => query.pageUrl ? f.pageUrl === query.pageUrl : true).filter((f) => query.status ? f.status === query.status : true).map(clone);
+      return { items: filtered };
+    },
+    async create(input) {
+      await delay();
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      const id = genId();
+      const fb = {
+        id,
+        projectId: input.projectId,
+        pageUrl: input.pageUrl,
+        selector: input.selector,
+        coordinates: { ...input.coordinates },
+        viewport: { ...input.viewport },
+        status: "open",
+        thread: input.comment ? [
+          {
+            id: `cm_${id}_0`,
+            author: { ...input.comment.author },
+            body: input.comment.body,
+            createdAt: now
+          }
+        ] : [],
+        createdAt: now,
+        updatedAt: now
+      };
+      items.push(fb);
+      return clone(fb);
+    },
+    async reply(feedbackId, comment) {
+      await delay();
+      const fb = items.find((f) => f.id === feedbackId);
+      if (!fb) throw new Error(`feedback not found: ${feedbackId}`);
+      const now = (/* @__PURE__ */ new Date()).toISOString();
+      fb.thread.push({
+        id: `cm_${feedbackId}_${fb.thread.length}`,
+        author: { ...comment.author },
+        body: comment.body,
+        createdAt: now
+      });
+      fb.updatedAt = now;
+      return clone(fb);
+    },
+    async setStatus(feedbackId, status) {
+      await delay();
+      const fb = items.find((f) => f.id === feedbackId);
+      if (!fb) throw new Error(`feedback not found: ${feedbackId}`);
+      fb.status = status;
+      fb.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      return clone(fb);
+    },
+    async move(feedbackId, coordinates) {
+      await delay();
+      const fb = items.find((f) => f.id === feedbackId);
+      if (!fb) throw new Error(`feedback not found: ${feedbackId}`);
+      fb.coordinates = { ...coordinates };
+      fb.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      return clone(fb);
+    },
+    async uploadScreenshot(feedbackId, _blob) {
+      await delay();
+      const fb = items.find((f) => f.id === feedbackId);
+      if (!fb) throw new Error(`feedback not found: ${feedbackId}`);
+      fb.screenshotKey = `screenshots/${feedbackId}.png`;
+      fb.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+      return clone(fb);
+    },
+    _all() {
+      return items.map(clone);
+    },
+    _reset() {
+      items.length = 0;
+    }
+  };
+}
+function defaultGenerateId() {
+  return `fb_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+export { createMockTransport };
+//# sourceMappingURL=mock.js.map
+//# sourceMappingURL=mock.js.map

package/dist/mock.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mock.ts"],"names":[],"mappings":"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","file":"mock.js","sourcesContent":["import type {\n  CreateFeedbackInput,\n  Feedback,\n  FeedbackAuthor,\n  FeedbackCoordinates,\n  FeedbackStatus,\n  FeedbackTransport,\n  ListFeedbackQuery,\n  ListFeedbackResult,\n} from \"./types.js\";\n\n/**\n * In-memory transport for local development / demos / tests.\n *\n *   import { createMockTransport } from '@mahmulp/feedback-sdk/mock'\n *\n * No persistence, no network. Useful before the API is wired up.\n */\n\nexport interface MockTransportOptions {\n  /** Optional initial feedback records (e.g. seeded from a fixture). */\n  initial?: Feedback[];\n  /** Override id generation (defaults to `fb_<timestamp>_<rand>`). */\n  generateId?: () => string;\n  /** Optional fake latency in ms, applied to every call. */\n  latencyMs?: number;\n}\n\nexport function createMockTransport(options: MockTransportOptions = {}): FeedbackTransport & {\n  /** Direct read of the in-memory store for tests / debugging. */\n  _all(): Feedback[];\n  _reset(): void;\n} {\n  const items: Feedback[] = options.initial ? options.initial.map(clone) : [];\n  const genId = options.generateId ?? defaultGenerateId;\n  const latency = options.latencyMs ?? 0;\n\n  async function delay() {\n    if (latency > 0) await new Promise((r) => setTimeout(r, latency));\n  }\n\n  return {\n    async list(query: ListFeedbackQuery): Promise<ListFeedbackResult> {\n      await delay();\n      // When `projectId` is empty, the SDK is relying on the API to scope by\n      // key — return every record. When set, scope by it.\n      const filtered = items\n        .filter((f) => (query.projectId ? f.projectId === query.projectId : true))\n        .filter((f) => (query.pageUrl ? f.pageUrl === query.pageUrl : true))\n        .filter((f) => (query.status ? f.status === query.status : true))\n        .map(clone);\n      return { items: filtered };\n    },\n\n    async create(input: CreateFeedbackInput): Promise<Feedback> {\n      await delay();\n      const now = new Date().toISOString();\n      const id = genId();\n      const fb: Feedback = {\n        id,\n        projectId: input.projectId,\n        pageUrl: input.pageUrl,\n        selector: input.selector,\n        coordinates: { ...input.coordinates },\n        viewport: { ...input.viewport },\n        status: \"open\",\n        thread: input.comment\n          ? [\n              {\n                id: `cm_${id}_0`,\n                author: { ...input.comment.author },\n                body: input.comment.body,\n                createdAt: now,\n              },\n            ]\n          : [],\n        createdAt: now,\n        updatedAt: now,\n      };\n      items.push(fb);\n      return clone(fb);\n    },\n\n    async reply(\n      feedbackId: string,\n      comment: { author: FeedbackAuthor; body: string }\n    ): Promise<Feedback> {\n      await delay();\n      const fb = items.find((f) => f.id === feedbackId);\n      if (!fb) throw new Error(`feedback not found: ${feedbackId}`);\n      const now = new Date().toISOString();\n      fb.thread.push({\n        id: `cm_${feedbackId}_${fb.thread.length}`,\n        author: { ...comment.author },\n        body: comment.body,\n        createdAt: now,\n      });\n      fb.updatedAt = now;\n      return clone(fb);\n    },\n\n    async setStatus(feedbackId: string, status: FeedbackStatus): Promise<Feedback> {\n      await delay();\n      const fb = items.find((f) => f.id === feedbackId);\n      if (!fb) throw new Error(`feedback not found: ${feedbackId}`);\n      fb.status = status;\n      fb.updatedAt = new Date().toISOString();\n      return clone(fb);\n    },\n\n    async move(feedbackId: string, coordinates: FeedbackCoordinates): Promise<Feedback> {\n      await delay();\n      const fb = items.find((f) => f.id === feedbackId);\n      if (!fb) throw new Error(`feedback not found: ${feedbackId}`);\n      fb.coordinates = { ...coordinates };\n      fb.updatedAt = new Date().toISOString();\n      return clone(fb);\n    },\n\n    async uploadScreenshot(feedbackId: string, _blob: Blob): Promise<Feedback> {\n      await delay();\n      const fb = items.find((f) => f.id === feedbackId);\n      if (!fb) throw new Error(`feedback not found: ${feedbackId}`);\n      fb.screenshotKey = `screenshots/${feedbackId}.png`;\n      fb.updatedAt = new Date().toISOString();\n      return clone(fb);\n    },\n\n    _all() {\n      return items.map(clone);\n    },\n    _reset() {\n      items.length = 0;\n    },\n  };\n}\n\nfunction defaultGenerateId(): string {\n  return `fb_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;\n}\n\nfunction clone<T>(value: T): T {\n  // Structured clone is fine here; the records are plain JSON shapes.\n  return JSON.parse(JSON.stringify(value)) as T;\n}\n"]}

package/dist/svelte.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Wire types shared between the SDK, the API, and the dashboard.
+ *
+ * NOTE: This file is the SDK's authoritative copy. The same shapes also live
+ * in `packages/shared-types/src/index.ts` for the API and dashboard. Keep
+ * them in sync when the wire format evolves.
+ */
+type FeedbackStatus = "open" | "resolved" | "archived";
+/** Pin coordinates: percentage-based (for re-rendering) and pixel (fallback). */
+interface FeedbackCoordinates {
+    /** 0..1, x position relative to the target element's bounding box. */
+    xPercent: number;
+    /** 0..1, y position relative to the target element's bounding box. */
+    yPercent: number;
+    /** Absolute x position in page pixels at capture time. */
+    xPx: number;
+    /** Absolute y position in page pixels at capture time. */
+    yPx: number;
+}
+interface ViewportInfo {
+    width: number;
+    height: number;
+    devicePixelRatio: number;
+}
+interface FeedbackAuthor {
+    name: string;
+    email?: string;
+}
+interface FeedbackComment {
+    id: string;
+    author: FeedbackAuthor;
+    body: string;
+    createdAt: string;
+}
+/** A pin/feedback record as seen on the wire. */
+interface Feedback {
+    id: string;
+    projectId: string;
+    pageUrl: string;
+    selector: string;
+    coordinates: FeedbackCoordinates;
+    viewport: ViewportInfo;
+    /** Storage key returned by the API after upload. Absent until a screenshot is uploaded. */
+    screenshotKey?: string;
+    status: FeedbackStatus;
+    thread: FeedbackComment[];
+    createdAt: string;
+    updatedAt: string;
+}
+/** Payload the SDK sends to create a new pin. The server fills in id/timestamps/status/thread. */
+interface CreateFeedbackInput {
+    projectId: string;
+    pageUrl: string;
+    selector: string;
+    coordinates: FeedbackCoordinates;
+    viewport: ViewportInfo;
+    /** Optional first comment posted alongside the pin. */
+    comment?: {
+        author: FeedbackAuthor;
+        body: string;
+    };
+}
+interface ListFeedbackQuery {
+    projectId: string;
+    pageUrl?: string;
+    status?: FeedbackStatus;
+}
+interface ListFeedbackResult {
+    items: Feedback[];
+}
+/**
+ * Transport contract used by the SDK to talk to "something that persists feedback".
+ * Default HTTP implementation lives in `transport.ts`. The mock transport in `mock.ts`
+ * is useful for local demos and tests.
+ */
+interface FeedbackTransport {
+    list(query: ListFeedbackQuery): Promise<ListFeedbackResult>;
+    create(input: CreateFeedbackInput): Promise<Feedback>;
+    reply(feedbackId: string, comment: {
+        author: FeedbackAuthor;
+        body: string;
+    }): Promise<Feedback>;
+    setStatus(feedbackId: string, status: FeedbackStatus): Promise<Feedback>;
+    /** Move a pin: persist new percent + pixel coordinates after a drag. */
+    move?(feedbackId: string, coordinates: FeedbackCoordinates): Promise<Feedback>;
+    /** Upload a screenshot blob for an already-created feedback. Returns the updated record. */
+    uploadScreenshot?(feedbackId: string, blob: Blob): Promise<Feedback>;
+}
+
+interface InitFeedbackOptions {
+    /** Base URL of the API (used when no `transport` is provided). */
+    apiUrl?: string;
+    /** Per-project ingest key (sent as `x-feedback-key` to the API). Required when using the HTTP transport. */
+    apiKey?: string;
+    /** Custom transport override. Useful for tests, mocks, or non-HTTP backends. */
+    transport?: FeedbackTransport;
+    /**
+     * Identifier used for client-side caching (author identity per project).
+     * Defaults to `apiKey`'s prefix when omitted; safe to leave unset.
+     */
+    cacheNamespace?: string;
+    /** Start with feedback mode enabled. Defaults to `false` (caller toggles via UI). */
+    enabled?: boolean;
+    /** Override how the page URL is captured. Defaults to `window.location.pathname + search`. */
+    getPageUrl?: () => string;
+    /**
+     * Modifier key used to "select parent" while picking a target.
+     * Defaults to "Alt".
+     */
+    selectParentModifier?: "Alt" | "Shift" | "Meta" | "Control";
+    /** Override how the author identity is read. Defaults to a localStorage cache. */
+    getAuthor?: () => FeedbackAuthor | null;
+    /** Override how the author identity is persisted after a successful submit. */
+    setAuthor?: (author: FeedbackAuthor) => void;
+    /** Capture a screenshot when a new pin is created. Defaults to `true`. */
+    captureScreenshots?: boolean;
+    /** Override the screenshot capture function. Returns null to skip silently. */
+    captureScreenshot?: () => Promise<Blob | null>;
+    /** Render the floating launcher widget. Defaults to `true`. */
+    showLauncher?: boolean;
+    /** Initial pin visibility. Defaults to `true`. */
+    pinsVisible?: boolean;
+    /** Called when a pin is clicked in display mode. Use to render a thread popover. */
+    onPinClick?: (feedback: Feedback) => void;
+    /** Called after a new pin is created. */
+    onPinCreate?: (feedback: Feedback) => void;
+    /** Called when an error happens during a SDK action. */
+    onError?: (err: unknown) => void;
+}
+interface FeedbackController {
+    /** Toggle / set feedback creation mode. */
+    setEnabled(enabled: boolean): void;
+    /** Read the current enabled state. */
+    isEnabled(): boolean;
+    /** Show or hide all pins (the floating launcher's eye toggle calls this). */
+    setPinsVisible(visible: boolean): void;
+    /** Show or hide the floating launcher widget. */
+    setLauncherVisible(visible: boolean): void;
+    /** Trigger a fresh fetch of feedback for the current project. */
+    refresh(): Promise<void>;
+    /** Tear down: remove DOM, listeners, and observers. Idempotent. */
+    destroy(): void;
+}
+
+/**
+ * Svelte adapter — thin lifecycle wrapper around the framework-agnostic core.
+ *
+ *   import { feedback, feedbackEnabled } from '@mahmulp/feedback-sdk/svelte'
+ *
+ * Usage:
+ *
+ *   <script lang="ts">
+ *     import { feedback, feedbackEnabled } from '@mahmulp/feedback-sdk/svelte'
+ *     const enabled = feedbackEnabled()
+ *   </script>
+ *
+ *   <div use:feedback={{ apiUrl: '/api', apiKey: 'mp_…' }}>
+ *     <slot />
+ *   </div>
+ *
+ *   <button on:click={() => enabled.toggle()}>
+ *     {$enabled ? 'Stop' : 'Start'} feedback
+ *   </button>
+ */
+
+type FeedbackActionParams = InitFeedbackOptions;
+interface FeedbackAction {
+    destroy(): void;
+    update(params: FeedbackActionParams): void;
+}
+/**
+ * Svelte action: `use:feedback={{ apiUrl, apiKey }}`.
+ *
+ * The action is a no-op during SSR (`initFeedback` already returns an SSR-safe
+ * controller, but we still skip it to avoid even constructing the host).
+ */
+declare function feedback(node: HTMLElement, params: FeedbackActionParams): FeedbackAction;
+interface EnabledStoreApi {
+    subscribe(run: (value: boolean) => void): () => void;
+    set(value: boolean): void;
+    toggle(): void;
+}
+/**
+ * Returns a writable-ish store of the "feedback mode" flag.
+ *
+ *   const enabled = feedbackEnabled()
+ *   $: console.log($enabled)
+ *   enabled.toggle()
+ */
+declare function feedbackEnabled(): EnabledStoreApi;
+
+export { type CreateFeedbackInput, type Feedback, type FeedbackAction, type FeedbackActionParams, type FeedbackController, type FeedbackStatus, type FeedbackTransport, type InitFeedbackOptions, feedback, feedbackEnabled };