@unnoodle/browser 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,517 @@
+/**
+ * Suggestions, AI generation, and generic action types.
+ */
+/**
+ * An action button shown in legacy AI response panels and deprecated plugin hooks.
+ */
+interface UnnoodleAction {
+    type: "link" | "copy" | "custom";
+    label: string;
+    value: string;
+}
+
+/**
+ * A single stage entry as returned by the backend.
+ */
+interface ProductMemoryEntryResponse {
+    id: number;
+    productMemoryId: number;
+    snapshotHtml: string;
+    explanation: string;
+    url: string;
+    pageTitle: string;
+    capturedByName: string;
+    capturedByRole: string;
+    capturedAt: string;
+    sortOrder: number;
+    createdAt: string;
+    sanitizerVersion?: string;
+    targetingMetadata?: {
+        id?: string;
+        dataTestId?: string;
+        tag: string;
+        role: string | null;
+        text: string;
+    };
+}
+/**
+ * Full detail response — memory + all entries.
+ * Returned by create, addEntry, updateEntry, updateTitle, getById.
+ */
+interface ProductMemoryDetailResponse {
+    id: number;
+    userId: number;
+    title: string;
+    entries: ProductMemoryEntryResponse[];
+    createdAt: string;
+    updatedAt: string;
+    watchForChanges: boolean;
+}
+/**
+ * List-view response — title and entry count only.
+ * Returned by GET /api/product-memories (paginated list).
+ */
+interface ProductMemoryResponse {
+    id: number;
+    userId: number;
+    title: string;
+    entryCount: number;
+    createdAt: string;
+    updatedAt: string;
+    watchForChanges: boolean;
+}
+
+/**
+ * Glossary, term, and discussion types.
+ */
+/** A resolved cross-reference to another term within the same context. */
+interface TermRef {
+    id: number;
+    term: string;
+    slug: string;
+}
+/** A single glossary term as returned by the backend. */
+interface GlossaryTerm {
+    id: number;
+    term: string;
+    definition: string;
+    /** Optional short alias or abbreviation */
+    abbreviation?: string;
+    /** Resolved @slug cross-references within this context. */
+    relations?: TermRef[];
+    status: "ACTIVE" | "DEPRECATED" | "PENDING";
+    contextId: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Minimal context metadata returned alongside the glossary. */
+interface ContextMetadata {
+    id: number;
+    name: string;
+    slug: string;
+    /** Display name of the context owner. Absent for SDK auto-created contexts. */
+    ownerName?: string;
+}
+/** Response from POST /api/init (SdkInitResponse on the backend). */
+interface WidgetInitResponse {
+    context: ContextMetadata;
+    glossary: GlossaryTerm[];
+    /** Optional clarifications included in init response for better performance */
+    clarifications?: ContextDiscussion[];
+    /** Optional product memories included in init response for better performance */
+    productMemories?: ProductMemoryResponse[];
+    tenantName: string;
+    subdomain: string;
+}
+/** A context-level clarification post (question or reply). */
+interface ContextDiscussion {
+    id: number;
+    contextId: number;
+    parentId: number | null;
+    body: string;
+    authorName: string | null;
+    aiGenerated: boolean;
+    aiModel?: string | null;
+    createdAt: string;
+    replies: ContextDiscussion[];
+}
+/**
+ * @deprecated Only kept for backwards-compat with old plugin hooks.
+ * New code should use WidgetInitResponse.
+ */
+interface UnnoodleApiResponse {
+    message?: string;
+    actions?: UnnoodleAction[];
+    prUrl?: string;
+    error?: string;
+}
+
+/**
+ * Configuration for the Unnoodle widget SDK.
+ * Designed to be extensible across major versions without breaking changes.
+ */
+interface UnnoodleConfig {
+    /**
+     * Your workspace API key. Starts with `pk_live_` (production) or `pk_test_` (development).
+     * Identifies the tenant and authorizes SDK requests.
+     * Required.
+     */
+    apiKey: string;
+    /**
+     * The knowledge context name to load (e.g. "engineering", "sales").
+     * Must match a context configured in your Unnoodle workspace.
+     * Required.
+     */
+    context: string;
+    /**
+     * Target environment. Defaults to "prod".
+     */
+    environment?: "dev" | "staging" | "prod";
+    /**
+     * Override the API base URL. Defaults to https://api.unnoodle.com
+     * Useful for local development or self-hosted deployments.
+     */
+    baseUrl?: string;
+    /**
+     * Provide a function that returns the current user's auth token.
+     * Called at the time of each request — never stored.
+     * When provided and returns a non-null value the login screen is skipped.
+     */
+    getAuthToken?: () => string | null;
+    /**
+     * Visual theme overrides.
+     */
+    theme?: {
+        /**
+         * @deprecated Has no effect. Pass design tokens via `shadowTokens` instead.
+         * Will be removed in a future major version.
+         */
+        primaryColor?: string;
+        /**
+         * @deprecated Has no effect. Pass design tokens via `shadowTokens` instead.
+         * Will be removed in a future major version.
+         */
+        borderRadius?: string;
+        /**
+         * CSS `:host { }` block containing `--unn-*` design tokens for injection
+         * into the widget's Shadow DOM. Generate with `getShadowDomTokens()` from
+         * `@unnoodle/design-system` in your host app.
+         *
+         * @example
+         *   import { getShadowDomTokens } from "@unnoodle/design-system";
+         *   initUnnoodle({ theme: { shadowTokens: getShadowDomTokens() } });
+         */
+        shadowTokens?: string;
+    };
+    /**
+     * Enable automatic PR suggestions in the response panel.
+     */
+    enableAutoPR?: boolean;
+    /**
+     * Returns additional metadata to include in context payloads.
+     * Called at request time — should be cheap and synchronous.
+     */
+    customMetadata?: () => Record<string, unknown>;
+    /**
+     * URL of the Unnoodle workspace app — used for "View details" links.
+     * Defaults to https://app.unnoodle.com
+     */
+    workspaceUrl?: string;
+    /**
+     * Plugin hooks — reserved for future plugin system.
+     * @internal
+     */
+    _plugins?: UnnoodlePlugin[];
+}
+/**
+ * Plugin interface — reserved for future extensibility.
+ * Plugins can hook into lifecycle events without modifying core.
+ * @internal
+ */
+interface UnnoodlePlugin {
+    name: string;
+    onInit?: (config: UnnoodleConfig) => void;
+    onContextCollected?: (ctx: Record<string, unknown>) => Record<string, unknown>;
+    onResponse?: (response: WidgetInitResponse) => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * The context payload sent to the Unnoodle API.
+ */
+interface UnnoodleContext {
+    apiKey: string;
+    context: string;
+    environment: string;
+    route: string;
+    title: string;
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+}
+
+/**
+ * StateWatcher
+ *
+ * Single responsibility:
+ *   Observe a captured DOM element for meaningful state changes and report
+ *   them via a callback — enabling automatic new-state detection in the UI
+ *   memory timeline.
+ *
+ * Behaviour:
+ *   - watch(el, onStateChange): attaches a MutationObserver that listens for
+ *     text, attribute, and structural changes on the element and its subtree.
+ *   - Changes are debounced for 500ms so rapid successive mutations (e.g.
+ *     CSS class toggling during an animation) produce a single diff.
+ *   - Noise filter: style attribute mutations are ignored (too noisy).
+ *   - unwatch(): disconnects the observer and cancels pending callbacks.
+ *
+ * Change classification (StateDiff.type):
+ *   - "text"      — visible text content changed (textContent assignment
+ *                   fires a childList mutation with only text nodes, or a
+ *                   characterData mutation on a text node directly).
+ *   - "attribute" — a non-style attribute changed (class, disabled,
+ *                   aria-*, data-*, etc.).
+ *   - "structure" — child elements were added or removed.
+ *
+ * Design principles:
+ *   - No DOM mutation — observer only.
+ *   - No coupling to panel, API, or captureOrchestrator.
+ *   - before/after are always strings (attribute values, textContent, or
+ *     serialised child counts for structural diffs).
+ */
+interface StateDiff {
+    /** Category of the detected change. */
+    type: "text" | "attribute" | "structure";
+    /** Name of the changed attribute — only set when type === "attribute". */
+    attribute?: string;
+    /** State before the change. */
+    before: string;
+    /** State after the change. */
+    after: string;
+}
+interface IStateWatcher {
+    /**
+     * Begin watching `el` for meaningful mutations.
+     * Calls `onStateChange` (debounced 500ms) when a diff is detected.
+     * Replaces any previous watch.
+     */
+    watch(el: Element, onStateChange: (diff: StateDiff) => void): void;
+    /**
+     * Stop watching. Cancels any pending debounced callback.
+     * Safe to call when no watch is active.
+     */
+    unwatch(): void;
+}
+declare class StateWatcher implements IStateWatcher {
+    private observer;
+    private timerId;
+    private pendingMutations;
+    private watchedEl;
+    private callback;
+    /** Snapshot of watched element state at the start of the current quiet window. */
+    private preBatchState;
+    watch(el: Element, onStateChange: (diff: StateDiff) => void): void;
+    unwatch(): void;
+    private scheduleFlush;
+    private flush;
+    private computeDiff;
+}
+
+/**
+ * meaningInference
+ *
+ * Single responsibility:
+ *   Given a StateDiff and the current live element, produce a concise
+ *   human-readable string suggesting what UI state the change represents.
+ *   Returns null when no confident semantic meaning can be inferred.
+ *
+ * Rule-based approach (no ML, fully deterministic):
+ *
+ *   Text changes — keyword scan of diff.after:
+ *     loading/spinner/submitting/saving → "Loading state"
+ *     error/failed/invalid/try again   → "Error state"
+ *     success/saved/complete/done      → "Success state"
+ *
+ *   Attribute changes on "class":
+ *     Newly added class keyword scan (diff.after classes minus diff.before classes):
+ *       loading/spinner/pending        → "Loading state"
+ *       disabled/inactive              → "Disabled state"
+ *       error/invalid/danger           → "Error state"
+ *       success/valid/done             → "Success state"
+ *       active/selected/open           → "Active state"
+ *       collapsed/closed/hidden        → "Collapsed state"
+ *
+ *   The "disabled" attribute:
+ *     Attribute present after change   → "Disabled state"
+ *     Attribute absent after change    → "Enabled state"
+ *
+ *   ARIA attributes:
+ *     aria-expanded = "true"           → "Expanded state"
+ *     aria-expanded = "false"          → "Collapsed state"
+ *     aria-selected = "true"           → "Selected state"
+ *     aria-busy     = "true"           → "Loading state"
+ *     aria-label    changed            → "Label changed to: <value>"
+ *
+ *   Structure changes → null (caller decides context).
+ *
+ * Design principles:
+ *   - Pure function — no side effects, no DOM mutation.
+ *   - Returns null rather than guessing.
+ *   - Deterministic output for testability.
+ */
+
+/**
+ * Infer a human-readable state meaning from a StateDiff.
+ *
+ * @param diff  The state change detected by StateWatcher.
+ * @param el    The live element after the change (used for attribute reads).
+ * @returns     A short description, or null if no meaning can be inferred.
+ */
+declare function inferMeaning(diff: StateDiff, el: Element): string | null;
+
+/**
+ * LiveRenderer
+ *
+ * Single responsibility:
+ *   Highlight the DOM element that corresponds to a captured ProductMemory
+ *   entry — giving the viewer a live "this is the element" pointer.
+ *
+ * Behaviour:
+ *   - show(el): scrolls the element into view then draws a read-only highlight
+ *     ring (position:fixed) over the element's bounding rect.
+ *   - hide(): removes the ring from the DOM.
+ *   - Calling hide() before show() is safe (no-op).
+ *   - Calling show() a second time replaces the previous ring.
+ *
+ * Design principles:
+ *   - No click handlers — read-only visual indicator only.
+ *   - No coupling to panel, API, or state machine.
+ *   - Reuses the same visual language as ElementPicker (dashed Unnoodle violet
+ *     ring) but with a solid fill to distinguish "live" from "pick" mode.
+ */
+interface ILiveRenderer {
+    /** Scroll the element into view and draw the live highlight ring. */
+    show(el: Element): void;
+    /** Remove the highlight ring. Safe to call when ring is not shown. */
+    hide(): void;
+}
+declare class LiveRenderer implements ILiveRenderer {
+    private ring;
+    show(el: Element): void;
+    hide(): void;
+}
+
+/**
+ * targetingEngine
+ *
+ * Single responsibility:
+ *   Given a StoredTarget (element-identification metadata harvested at capture
+ *   time), find the corresponding live element in the current host page.
+ *
+ * Resolution strategy — tiered, highest-confidence first:
+ *
+ *   Tier 1a — id attribute (O(1), most stable):
+ *     document.getElementById(id) → verify same tag → return if found.
+ *
+ *   Tier 1b — data-testid attribute (O(1), second most stable):
+ *     querySelector('[data-testid="..."]') → verify tag + unique → return.
+ *
+ *   Tier 2 — text match (O(n) over elements of the given tag):
+ *     querySelectorAll(tag) → filter by exact trimmed textContent → return
+ *     if exactly one match. Falls through when text is empty or not unique.
+ *
+ * Design principles:
+ *   - Never mutates the DOM
+ *   - Returns null on any ambiguity rather than guessing wrong
+ *   - All DOM traversal is synchronous and lightweight
+ */
+/**
+ * Element-identification data persisted per captured entry.
+ * Mirrors the backend TargetingMetadata DTO.
+ */
+interface StoredTarget {
+    /** element.id attribute — most stable identifier, set by developers. */
+    id?: string;
+    /** data-testid attribute — second most stable. */
+    dataTestId?: string;
+    /** Lower-case tag name. Never undefined. */
+    tag: string;
+    /** ARIA role at capture time. May be null. */
+    role: string | null;
+    /** Trimmed visible text content at capture time. */
+    text: string;
+    /** Page URL at capture time — used by callers for page-match checks. */
+    url: string;
+}
+/** Implemented by TargetingEngine; injectable for testing. */
+interface ITargetingEngine {
+    resolve(target: StoredTarget): Element | null;
+}
+
+/**
+ * MemoryDetailController
+ *
+ * Single responsibility:
+ *   After a ProductMemory is loaded, optionally start a StateWatcher on the
+ *   originally captured DOM element and surface its diffs via an onDiff
+ *   callback — enabling automatic new-state detection.
+ *
+ * Behaviour:
+ *   load(memory, onDiff):
+ *     1. Unloads any prior watch.
+ *     2. If memory.watchForChanges is false, does nothing more.
+ *     3. Checks that the first entry's URL matches the current page URL
+ *        (origin + pathname only, ignoring query / hash).
+ *     4. Uses TargetingEngine.resolve() to find the captured element.
+ *     5. Starts StateWatcher.watch(el, onDiff).
+ *
+ *   unload():
+ *     Stops any active StateWatcher. Safe to call when nothing is watching.
+ *
+ * Design principles:
+ *   - No DOM mutation.
+ *   - All dependencies are injected via interfaces for full testability.
+ */
+
+interface IMemoryDetailController {
+    load(memory: ProductMemoryDetailResponse, onDiff: (diff: StateDiff) => void): void;
+    unload(): void;
+}
+declare class MemoryDetailController implements IMemoryDetailController {
+    private readonly stateWatcher;
+    private readonly targetingEngine;
+    constructor(stateWatcher: IStateWatcher, targetingEngine: ITargetingEngine);
+    load(memory: ProductMemoryDetailResponse, onDiff: (diff: StateDiff) => void): void;
+    unload(): void;
+}
+
+/**
+ * Initializes the Unnoodle widget SDK.
+ *
+ * Call once when your application boots. Safe to call in SSR environments —
+ * it will no-op if `document` is not available.
+ *
+ * @example
+ * ```ts
+ * import { initUnnoodle } from "@unnoodle/browser";
+ *
+ * initUnnoodle({ apiKey: "pk_live_abc123", context: "engineering" });
+ * ```
+ */
+declare function initUnnoodle(config: UnnoodleConfig): void;
+/**
+ * Programmatically open the Unnoodle panel.
+ * No-op if the SDK has not been initialized.
+ */
+declare function openUnnoodle(): void;
+/**
+ * Programmatically close the Unnoodle panel.
+ * No-op if the SDK has not been initialized.
+ */
+declare function closeUnnoodle(): void;
+/**
+ * Tear down the Unnoodle widget and remove all DOM elements and listeners.
+ * Useful for single-page apps that need to clean up on route change.
+ */
+declare function destroyUnnoodle(): void;
+/**
+ * Namespace-style API — preferred for script-tag / CDN usage.
+ *
+ * @example
+ * ```ts
+ * import { Unnoodle } from "@unnoodle/browser";
+ *
+ * Unnoodle.init({ apiKey: "pk_live_abc123", context: "engineering" });
+ * ```
+ */
+declare const Unnoodle: {
+    /** Initialize the Unnoodle widget SDK. Equivalent to `initUnnoodle()`. */
+    readonly init: typeof initUnnoodle;
+    /** Programmatically open the panel. */
+    readonly open: typeof openUnnoodle;
+    /** Programmatically close the panel. */
+    readonly close: typeof closeUnnoodle;
+    /** Tear down the widget and remove all DOM elements. */
+    readonly destroy: typeof destroyUnnoodle;
+};
+
+export { type ILiveRenderer, type IMemoryDetailController, type IStateWatcher, LiveRenderer, MemoryDetailController, type StateDiff, StateWatcher, Unnoodle, type UnnoodleAction, type UnnoodleApiResponse, type UnnoodleConfig, type UnnoodleContext, type UnnoodlePlugin, closeUnnoodle, destroyUnnoodle, inferMeaning, initUnnoodle, openUnnoodle };