@mahmulp/feedback-sdk 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,252 @@
+/**
+ * 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;
+}
+declare function initFeedback(options: InitFeedbackOptions): FeedbackController;
+
+/**
+ * DOM selector utilities. Deterministic and side-effect-free.
+ *
+ * Selector priority (see `.kiro/steering/feedback-data-model.md`):
+ *   1. data-feedback-id on the target or any ancestor
+ *   2. id="…" if it looks stable (no hashes, no auto-generated suffixes)
+ *   3. structural tag + nth-child chain, capped at MAX_DEPTH levels
+ *   4. tag.classname (single semantic class) as a last resort
+ */
+/**
+ * Build the most stable selector we can for the given element.
+ */
+declare function resolveSelector(target: Element): string;
+/**
+ * Resolve a previously-stored selector back to an Element. Returns null if not found.
+ * Never throws on malformed selectors.
+ */
+declare function findElement(selector: string, root?: ParentNode): Element | null;
+
+/**
+ * Compute pin coordinates for a click on a target element.
+ *
+ * - xPercent / yPercent are relative to the target's bounding box (clamped 0..1),
+ *   used to re-render the pin after layout changes.
+ * - xPx / yPx are absolute page coordinates, used as the orphaned-pin fallback.
+ */
+declare function computeCoordinates(target: Element, clientX: number, clientY: number): FeedbackCoordinates;
+declare function getViewportInfo(): ViewportInfo;
+/**
+ * Project stored coordinates back onto a (possibly resolved) target element.
+ * If `target` is null (orphaned), fall back to absolute page pixels.
+ *
+ * Returns coordinates in the **page** coordinate space (account for scroll separately
+ * when positioning fixed-overlay elements).
+ */
+declare function projectCoordinates(target: Element | null, coords: FeedbackCoordinates): {
+    x: number;
+    y: number;
+    orphaned: boolean;
+};
+
+/**
+ * Default HTTP transport: talks to the API at `apiUrl` using a per-project
+ * API key (`apiKey`, sent as `x-feedback-key`).
+ *
+ *   GET    /v1/feedback?pageUrl=…&status=…
+ *   POST   /v1/feedback
+ *   POST   /v1/feedback/:id/comments
+ *   PATCH  /v1/feedback/:id  { status }                  (admin-only; SDK rarely calls this)
+ *   PATCH  /v1/feedback/:id/coordinates  { coordinates } (drag-to-move)
+ *   POST   /v1/feedback/:id/screenshot                   (multipart, field "file")
+ *
+ * The SDK never sends `projectId` — the server resolves the project from
+ * the API key.
+ */
+interface HttpTransportOptions {
+    apiUrl: string;
+    /** Per-project ingest key sent as `x-feedback-key`. Required. */
+    apiKey: string;
+    fetch?: typeof fetch;
+    headers?: Record<string, string>;
+}
+declare function createHttpTransport(options: HttpTransportOptions): FeedbackTransport;
+
+/**
+ * Optional screenshot capture for new pins.
+ *
+ * `html2canvas` is **dynamically imported** so prototypes that never create
+ * a pin don't pay for it. Capture is best-effort: any failure logs and
+ * resolves to null rather than blocking pin creation.
+ */
+interface CaptureOptions {
+    /** Output mime type. Defaults to image/png. */
+    mimeType?: "image/png" | "image/jpeg" | "image/webp";
+    /** Quality (0..1) used for jpeg/webp. Ignored for png. */
+    quality?: number;
+    /** Viewport scale. Defaults to 1 to keep file sizes small. */
+    scale?: number;
+}
+/**
+ * Capture a screenshot of the current viewport.
+ *
+ * Hides the SDK's own overlay host before capture and restores it after,
+ * so the screenshot reflects the prototype, not the SDK chrome.
+ */
+declare function captureViewport(options?: CaptureOptions): Promise<Blob | null>;
+
+/**
+ * Public entry — framework-agnostic core.
+ *
+ *   import { initFeedback } from '@mahmulp/feedback-sdk'
+ *
+ * Svelte users may prefer the adapter at `@mahmulp/feedback-sdk/svelte`.
+ * For local development without a backend, see `@mahmulp/feedback-sdk/mock`.
+ */
+
+/** @internal */
+declare function _setGlobalController(c: FeedbackController | null): void;
+declare function setFeedbackEnabled(enabled: boolean): void;
+declare function destroyFeedback(): void;
+/**
+ * Wrapper that captures the most recently created controller, so the
+ * `setFeedbackEnabled` / `destroyFeedback` shortcuts work for the common case.
+ */
+declare function initFeedbackGlobal(options: InitFeedbackOptions): FeedbackController;
+
+export { type CaptureOptions, type CreateFeedbackInput, type Feedback, type FeedbackAuthor, type FeedbackComment, type FeedbackController, type FeedbackCoordinates, type FeedbackStatus, type FeedbackTransport, type HttpTransportOptions, type InitFeedbackOptions, type ListFeedbackQuery, type ListFeedbackResult, type ViewportInfo, _setGlobalController, captureViewport, computeCoordinates, createHttpTransport, destroyFeedback, findElement, getViewportInfo, initFeedback, initFeedbackGlobal, projectCoordinates, resolveSelector, setFeedbackEnabled };