@loupfeed/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,351 @@
+/**
+ * DSN parsing + ingest endpoint derivation.
+ *
+ * Format (Sentry-inspired):
+ *   https://<PUBLIC_KEY>@<INGEST_HOST>/o/<ORG_ID>/p/<PROJECT_ID>
+ *
+ * Self-host vs SaaS is purely the host — same protocol, same packages.
+ */
+type Dsn = {
+    raw: string;
+    protocol: string;
+    publicKey: string;
+    /** hostname only (no port). */
+    host: string;
+    port: string;
+    orgId: string;
+    projectId: string;
+    /** `${protocol}://${host[:port]}` — no trailing slash. */
+    baseUrl: string;
+};
+declare function parseDsn(dsn: string): Dsn;
+declare function eventsUrl(dsn: Dsn): string;
+declare function replaysUrl(dsn: Dsn): string;
+declare function manifestsUrl(dsn: Dsn): string;
+declare function resolveUrl(dsn: Dsn): string;
+
+/**
+ * Public type surface for @loupfeed/core. The on-the-wire `FeedbackEvent` is
+ * specified in docs/04-context-api.md (§The FeedbackEvent envelope).
+ */
+/** Allowed tag values. `null`/`undefined` are dropped at serialization. */
+type Primitive = string | number | boolean | null | undefined;
+type User = {
+    id?: string;
+    email?: string;
+    username?: string;
+    ip_address?: string;
+    /** Arbitrary developer-supplied fields (plan, role, …). */
+    [key: string]: unknown;
+};
+type BreadcrumbLevel = 'debug' | 'info' | 'warning' | 'error';
+type Breadcrumb = {
+    /** ISO timestamp; filled in automatically if omitted. */
+    timestamp?: string;
+    /** 'navigation' | 'ui.click' | 'http' | 'console' | custom. */
+    category: string;
+    type?: string;
+    message?: string;
+    level?: BreadcrumbLevel;
+    data?: Record<string, unknown>;
+};
+type ElementRect = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+/** Element anchor captured by the selector engine. */
+type ElementInfo = {
+    /** data-fb-id | structural CSS path, relative to the selector root. */
+    selector: string;
+    /** Opaque build-injected `data-fb` id → resolves to src:line server-side. */
+    elementId?: string;
+    tagName?: string;
+    /** Truncated, masking-aware. */
+    text?: string;
+    rect?: ElementRect;
+};
+type FeedbackInput = {
+    text: string;
+    /** The clicked DOM element (the web overlay supplies it). */
+    element?: Element;
+    /** Non-DOM platforms (React Native) supply the opaque id directly. */
+    elementId?: string;
+    /** Non-DOM platforms supply a prebuilt anchor (tag/rect/selector) directly. */
+    elementInfo?: Partial<ElementInfo>;
+    /** Screenshots etc. (uploaded separately by the transport). */
+    attachments?: Blob[];
+};
+type AttachmentRef = {
+    type: 'image';
+    blobId: string;
+};
+/** The on-the-wire envelope ingested by the backend. */
+type FeedbackEvent = {
+    eventId: string;
+    timestamp: string;
+    /** version@commit — the manifest join key. */
+    release: string;
+    environment: string;
+    text: string;
+    attachments?: AttachmentRef[];
+    element: ElementInfo;
+    user?: User;
+    contexts?: Record<string, Record<string, unknown>>;
+    tags?: Record<string, string | number | boolean>;
+    breadcrumbs?: Breadcrumb[];
+    request?: {
+        url: string;
+        route?: string;
+    };
+    replay?: {
+        replayId: string;
+        durationMs: number;
+    };
+    sdk?: {
+        name: string;
+        version: string;
+    };
+};
+/** Session-replay masking config (replay itself is deferred out of MVP). */
+type ReplayOptions = {
+    maskAllText?: boolean;
+    maskAllInputs?: boolean;
+    blockSelector?: string;
+    maskTextSelector?: string;
+};
+type ReplayBuffer = {
+    replayId: string;
+    durationMs: number;
+    /**
+     * Replay codec:
+     *  - 'rrweb'     — web DOM (default)
+     *  - 'wireframe' — React Native view-hierarchy snapshots (maskable, pure-JS)
+     *  - 'video'     — native screen recording (optional, pixels)
+     */
+    kind?: 'rrweb' | 'wireframe' | 'video';
+    /** rrweb events (kind: 'rrweb'). */
+    events?: unknown[];
+    /** view-hierarchy frames (kind: 'wireframe'). */
+    frames?: unknown[];
+    /** recorded viewport, for wireframe reconstruction. */
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    /** base64-encoded video (kind: 'video'). */
+    video?: string;
+    mimeType?: string;
+};
+/** Pluggable session recorder. Web = rrweb; React Native = native screen capture. */
+interface Recorder {
+    start(): void;
+    stop(): void;
+    isRecording(): boolean;
+    /** Freeze the rolling buffer for the current event (may be async for native capture). */
+    snapshot(): ReplayBuffer | Promise<ReplayBuffer>;
+}
+/** Pluggable transport — override for self-host / proxy. */
+interface Transport {
+    /** Send one event; resolves with the server-assigned eventId. */
+    send(event: FeedbackEvent): Promise<string>;
+    /** Upload a frozen replay buffer; resolves with its id + duration. */
+    sendReplay?(buffer: ReplayBuffer): Promise<{
+        replayId: string;
+        durationMs: number;
+    }>;
+    /** Wait for in-flight sends to settle (up to `timeout` ms). */
+    flush(timeout?: number): Promise<boolean>;
+    close?(): void;
+}
+type InitOptions = {
+    dsn: string;
+    environment?: string;
+    /** version@commit; build plugin can inject this. Defaults to ''. */
+    release?: string;
+    /** Fraction of feedbacks that attach a replay. 0..1. (Replay deferred.) */
+    replaysSampleRate?: number;
+    /** Rolling replay buffer length in seconds. Default 30. (Replay deferred.) */
+    replayBufferSeconds?: number;
+    replay?: ReplayOptions;
+    /** Auto-attach route, viewport, release. Default true. */
+    autoContext?: boolean;
+    /** Max breadcrumbs retained on the global scope. Default 50. */
+    maxBreadcrumbs?: number;
+    /** Last-chance scrub. Return null to drop the event. */
+    beforeSend?: (event: FeedbackEvent) => FeedbackEvent | null;
+    /** Override the transport (self-host / proxy / testing). */
+    transport?: Transport;
+    debug?: boolean;
+};
+type OverlayOptions = {
+    /** Root the selector engine generates paths relative to. Defaults to body. */
+    root?: Element | null;
+    /** Called when a user submits feedback. Defaults to core's `captureFeedback`. */
+    onSubmit?: (input: FeedbackInput) => void | Promise<void>;
+    /** Accent color (6-digit hex). Default '#6d28d9'. */
+    accentColor?: string;
+    /** z-index of the overlay host. Default 2147483600. */
+    zIndex?: number;
+    /** Show the built-in floating launcher button. Default true. */
+    launcher?: boolean;
+};
+
+/**
+ * Client — holds the parsed DSN, normalized options, and the transport. Owns
+ * `captureFeedback`: it builds the event from the active scope and sends it.
+ */
+
+declare class Client {
+    readonly dsn: Dsn;
+    private readonly options;
+    private readonly transport;
+    constructor(options: InitOptions);
+    getOptions(): InitOptions;
+    getDsn(): Dsn;
+    getTransport(): Transport;
+    captureFeedback(input: FeedbackInput): Promise<string>;
+    private maybeAttachReplay;
+    flush(timeout?: number): Promise<boolean>;
+    close(timeout?: number): Promise<boolean>;
+}
+
+/**
+ * The init/singleton wiring. `init()` is idempotent and safe to import on the
+ * server — no DOM work happens here (the overlay mounts separately, lazily).
+ */
+
+declare function init(options: InitOptions): Client;
+declare function getClient(): Client | undefined;
+declare function captureFeedback(input: FeedbackInput): Promise<string>;
+/** Flush + stop. */
+declare function close(timeout?: number): Promise<boolean>;
+
+/**
+ * Scope / context API — generalizes what Trivision's FeedbackProvider hard-codes
+ * (tenant/rep/version) into a Sentry-style developer-driven API.
+ *
+ *   - The global scope holds long-lived data (user, tags, persistent contexts).
+ *   - `withScope(cb)` forks a child for a single capture without polluting global.
+ */
+
+interface ScopeData {
+    user?: User;
+    tags: Record<string, Primitive>;
+    contexts: Record<string, Record<string, unknown>>;
+    breadcrumbs: Breadcrumb[];
+}
+declare class Scope {
+    private _user?;
+    private _tags;
+    private _contexts;
+    private _breadcrumbs;
+    private _maxBreadcrumbs;
+    setUser(user: User | null): this;
+    getUser(): User | undefined;
+    setTag(key: string, value: Primitive): this;
+    setTags(tags: Record<string, Primitive>): this;
+    setContext(key: string, data: Record<string, unknown> | null): this;
+    addBreadcrumb(breadcrumb: Breadcrumb, maxBreadcrumbs?: number): this;
+    setMaxBreadcrumbs(n: number): this;
+    clearBreadcrumbs(): this;
+    clone(): Scope;
+    getScopeData(): ScopeData;
+}
+declare function getGlobalScope(): Scope;
+/** The active scope: the top of the withScope stack, else the global scope. */
+declare function getCurrentScope(): Scope;
+/** Fork a child scope for a single capture; auto-popped when `cb` returns. */
+declare function withScope<T>(cb: (scope: Scope) => T): T;
+declare function setUser(user: User | null): void;
+declare function setContext(key: string, data: Record<string, unknown> | null): void;
+declare function setTag(key: string, value: Primitive): void;
+declare function setTags(tags: Record<string, Primitive>): void;
+declare function addBreadcrumb(breadcrumb: Breadcrumb): void;
+
+/**
+ * Session recorder — wraps rrweb behind loupfeed's own rolling-buffer + masking
+ * lifecycle (docs/05). We own the masking *defaults* (mask-by-default), the ring
+ * buffer, and the upload lifecycle; rrweb is just the DOM codec, swappable later.
+ *
+ * rrweb is loaded with a real dynamic import so it (a) stays out of apps that
+ * don't enable replay (tree-shakeable / lazy) and (b) is bundler-resolved on web.
+ * React Native uses a native recorder instead and stubs `rrweb` in Metro.
+ */
+
+/** The public `replay` API (re-exported from core's index). */
+declare const replay: {
+    start(): void;
+    stop(): void;
+    isRecording(): boolean;
+    /** Freeze the rolling buffer for the current event. */
+    snapshot(): ReplayBuffer;
+};
+declare function setReplayRecorder(recorder: Recorder | null): void;
+declare function getActiveRecorder(): Recorder;
+
+/**
+ * Element-identification engine (lifted + generalized from the Trivision
+ * `app/src/feedback/selector.ts`). Produces an identifier per element that:
+ *   1. Survives re-renders within a session
+ *   2. Survives a page refresh (comments persist across reloads)
+ *   3. Tolerates minor markup changes between deploys (best-effort)
+ *
+ * Three-tier resolution, in priority order:
+ *   1. el.closest('[data-fb-id]')  → hand-authored stable id
+ *   2. el.closest('[data-fb]')     → opaque build-injected id → manifest (src:line)
+ *   3. structural CSS path          → tag + :nth-of-type(n), relative to the root
+ *
+ * The opaque `data-fb` id never carries a source path; it resolves to
+ * `<rel-path>:<line>` server-side via the manifest. The client never sees paths.
+ */
+
+declare function setSelectorRoot(el: Element | null): void;
+declare function getSelectorRoot(): Element | null;
+/** Generate a stable selector for an element, relative to the root. */
+declare function selectorFor(el: Element): string;
+/** Try to resolve a stored selector back to a live element. */
+declare function resolveSelector(selector: string): Element | null;
+/** Snapshot an element's identity + display metadata at click time. */
+declare function snapshotElement(el: Element): ElementInfo;
+
+/**
+ * Framework-agnostic inspector overlay, rendered into a shadow root so the host
+ * app's CSS can neither style nor break it. Generalizes the hit-testing core of
+ * Trivision's FeedbackOverlay (elementsFromPoint + pointer-events isolation +
+ * portal) into vanilla DOM with zero runtime deps.
+ *
+ * Capture-only by design: the in-page widget collects element-anchored feedback;
+ * triage/threads/replay live in the dashboard (doc 06), not the host page.
+ *
+ * State machine: idle → inspect (hover-highlight) → compose (comment popup).
+ */
+
+type OverlayController = {
+    open(): void;
+    close(): void;
+    toggleInspect(): void;
+    isInspecting(): boolean;
+    destroy(): void;
+};
+/** Mount the overlay into the DOM. Returns an unmount function. SSR-safe (no-op). */
+declare function mountOverlay(opts?: OverlayOptions): () => void;
+/** Singleton control surface targeting the most recently mounted overlay. */
+declare const overlay: Omit<OverlayController, 'destroy'>;
+
+/**
+ * Fetch transport — POSTs the FeedbackEvent envelope (and, when present, the
+ * replay blob) to the DSN-derived ingest endpoints. Retries on network / 5xx,
+ * tracks in-flight sends for flush(), and uses `keepalive` so a submit can
+ * outlive an unload.
+ */
+
+declare function makeFetchTransport(dsn: Dsn, opts?: {
+    debug?: boolean;
+}): Transport;
+
+/** SDK version, surfaced on every event's `sdk` field. Bumped by Changesets. */
+declare const SDK_VERSION = "0.0.0";
+
+export { type AttachmentRef, type Breadcrumb, type BreadcrumbLevel, Client, type Dsn, type ElementInfo, type ElementRect, type FeedbackEvent, type FeedbackInput, type InitOptions, type OverlayController, type OverlayOptions, type Primitive, type Recorder, type ReplayBuffer, type ReplayOptions, SDK_VERSION, Scope, type ScopeData, type Transport, type User, addBreadcrumb, captureFeedback, close, eventsUrl, getActiveRecorder, getClient, getCurrentScope, getGlobalScope, getSelectorRoot, init, makeFetchTransport, manifestsUrl, mountOverlay, overlay, parseDsn, replay, replaysUrl, resolveSelector, resolveUrl, selectorFor, setContext, setReplayRecorder, setSelectorRoot, setTag, setTags, setUser, snapshotElement, withScope };