@synod-ai/extension-feedback 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,253 @@
+type FindingSeverity = 'low' | 'medium' | 'high';
+interface FindingContextJson {
+    url?: string;
+    /** SPA route or pathname (best-effort). Helps the agent know which "screen" the user was on. */
+    route?: string;
+    /** Document title — gives the agent a human-readable label for the page. */
+    page_title?: string;
+    element_text?: string;
+    /** outerHTML of the selected element, truncated at ~1500 chars. */
+    element_html?: string;
+    /** Filtered attribute map of the selected element. */
+    element_attributes?: Record<string, string>;
+    /**
+     * Root-first parent chain, filtered to ancestors with an id or class.
+     * Generic wrappers are skipped on the client. Each entry is
+     * {tag, id?, className?}.
+     */
+    parent_chain?: Array<{
+        tag: string;
+        id?: string;
+        className?: string;
+    }>;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    user_agent?: string;
+    screenshot_data_url?: string;
+    batch_id?: string;
+    extension_version?: string;
+}
+interface FindingPayload {
+    title: string;
+    description: string;
+    severity: FindingSeverity;
+    suggested_action?: 'create_story';
+    context_json: FindingContextJson;
+}
+interface ExternalFindingsRequest {
+    project_id: string;
+    findings: FindingPayload[];
+}
+interface CreatedFinding {
+    id: string;
+    title: string;
+    severity: FindingSeverity;
+}
+interface FindingError {
+    index: number;
+    error: string;
+}
+interface BatchResponse {
+    created: CreatedFinding[];
+    errors: FindingError[];
+}
+interface BatchResult {
+    created: CreatedFinding[];
+    errors: FindingError[];
+}
+type ClientErrorCode = 'AUTH_ERROR' | 'RATE_LIMITED' | 'NETWORK_ERROR' | 'TIMEOUT' | 'SERVER_ERROR' | 'CLIENT_ERROR' | 'CONTEXT_TOO_LARGE';
+interface ClientError extends Error {
+    code: ClientErrorCode;
+    statusCode?: number;
+    retryable: boolean;
+}
+interface FeedbackConfig {
+    gatewayUrl: string;
+    projectId: string;
+    token: string;
+    keyCombo?: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+
+declare class SynodFeedbackClient {
+    private readonly config;
+    private _queue;
+    private _abortControllers;
+    constructor(config: FeedbackConfig);
+    /**
+     * Add a finding to the local batch queue.
+     * Pre-validates context_json size to prevent oversized payloads.
+     */
+    queue(finding: FindingPayload): void;
+    /**
+     * Get the current queue length.
+     */
+    get queueLength(): number;
+    /**
+     * Get a shallow copy of the current queue.
+     */
+    getQueueSnapshot(): FindingPayload[];
+    /**
+     * Clear all items from the queue.
+     */
+    clearQueue(): void;
+    /**
+     * Send all queued findings as a batch to the gateway.
+     * On success (201): created items are dequeued; errored items remain.
+     * On full failure (after retries): entire batch remains in queue.
+     *
+     * @returns BatchResult with created and errors arrays
+     * @throws ClientError on full failure after retries, or on non-retryable error
+     */
+    sendBatch(): Promise<BatchResult>;
+    /**
+     * POST to the gateway with retry/backoff logic.
+     * Retries up to maxRetries times on retryable failures (5xx, 429, network, timeout).
+     * Does NOT retry on 401 or other 4xx (except 429).
+     *
+     * Worst-case wall time: ~1s + timeout + 2s + timeout + 4s + timeout.
+     */
+    private postWithRetry;
+    /**
+     * Process the gateway response: dequeue created items, retain errored items.
+     * Findings are matched by their position in the original sent batch.
+     */
+    private processResponse;
+    /**
+     * Remove successfully sent items from the live queue.
+     *
+     * The sentFindings were a snapshot of the queue at send time. We need to remove
+     * the successful ones while keeping the failed ones. Since they were all at the
+     * front of the queue (in order), we rebuild: remove createdIndices from [0..sentCount-1].
+     */
+    private dequeueByIndices;
+    private classifyHttpError;
+    private classifyTransportError;
+    /**
+     * Abort all in-flight requests.
+     */
+    destroy(): void;
+    private sleep;
+}
+
+type EnableHandler = () => void;
+type DisableHandler = () => void;
+/**
+ * Singleton lifecycle manager for the feedback extension.
+ *
+ * State machine:
+ *   uninitialized → (init) → initialized (enabled=false)
+ *                              ↕ enable() / disable()
+ *                        initialized (enabled=true/false)
+ *
+ * The client and queue are ALWAYS available regardless of `enabled` state —
+ * `enabled` is a semantic signal for the interaction layer (SDG-294), not a gate on transport.
+ */
+declare class FeedbackManager {
+    private _initialized;
+    private _enabled;
+    private _client;
+    private _config;
+    private _enableHandlers;
+    private _disableHandlers;
+    get initialized(): boolean;
+    get enabled(): boolean;
+    /** The active client instance, or null if not initialized. */
+    get client(): SynodFeedbackClient | null;
+    /** The validated config, or null if not initialized. */
+    get config(): FeedbackConfig | null;
+    /**
+     * Initialize the feedback system with configuration.
+     * Creates the singleton client instance. Re-init replaces existing state.
+     */
+    init(config: FeedbackConfig): void;
+    /**
+     * Enable the feedback system. Fires all registered onEnable handlers.
+     */
+    enable(): void;
+    /**
+     * Disable the feedback system. Fires all registered onDisable handlers.
+     */
+    disable(): void;
+    /**
+     * Register a handler to be called when enable() is invoked.
+     * If already enabled, the handler fires immediately.
+     * @returns unregister function
+     */
+    onEnable(handler: EnableHandler): () => void;
+    /**
+     * Register a handler to be called when disable() is invoked.
+     * @returns unregister function
+     */
+    onDisable(handler: DisableHandler): () => void;
+    queue(finding: FindingPayload): void;
+    sendBatch(): Promise<BatchResult>;
+    get queueLength(): number;
+    getQueueSnapshot(): FindingPayload[];
+    /**
+     * Clear all items from the queue.
+     */
+    clearQueue(): void;
+    /**
+     * Replace the entire queue with the given items.
+     * Used by the interaction layer for remove/edit operations.
+     */
+    replaceQueue(items: FindingPayload[]): void;
+    /**
+     * Reset the manager to uninitialized state.
+     * Destroys client, clears handlers.
+     */
+    destroy(): void;
+    private requireClient;
+}
+
+/**
+ * Encode an array of findings into the clipboard transfer format.
+ * Screenshots are stripped from every finding's context_json.
+ *
+ * Empty arrays still encode (returns the prefix + empty-list base64)
+ * so consumers can distinguish "Synod clipboard blob with no items" from
+ * "not a Synod clipboard blob at all".
+ */
+declare function encodeFindingsToClipboard(findings: FindingPayload[]): string;
+/**
+ * Decode a clipboard string back into findings.
+ *
+ * Returns `{ ok: true, findings }` on success, or `{ ok: false, error }`
+ * if the input is not a Synod findings blob, the JSON is malformed, the
+ * version is unsupported, or any finding has an invalid shape.
+ *
+ * On any decode error the consumer should fall back to plain-text paste
+ * behaviour (or just show an "invalid clipboard" toast).
+ */
+declare function decodeFindingsFromClipboard(raw: string): {
+    ok: true;
+    findings: FindingPayload[];
+} | {
+    ok: false;
+    error: string;
+};
+
+declare function init(config: FeedbackConfig): void;
+declare function enable(): void;
+declare function disable(): void;
+declare function onEnable(handler: () => void): () => void;
+declare function onDisable(handler: () => void): () => void;
+declare function sendBatch(): Promise<BatchResult>;
+declare function queue(finding: FindingPayload): void;
+declare function clearQueue(): void;
+declare function replaceQueue(items: FindingPayload[]): void;
+declare function isEnabled(): boolean;
+declare function getQueueSnapshot(): FindingPayload[];
+declare function getQueueLength(): number;
+
+/**
+ * @internal Reset singleton state. Intended for test isolation only.
+ * Creates a fresh manager and re-registers interaction layer hooks.
+ */
+declare function __resetForTesting(): void;
+
+export { type BatchResponse, type BatchResult, type ClientError, type ClientErrorCode, type CreatedFinding, type ExternalFindingsRequest, type FeedbackConfig, FeedbackManager, type FindingContextJson, type FindingError, type FindingPayload, type FindingSeverity, SynodFeedbackClient, __resetForTesting, clearQueue, decodeFindingsFromClipboard, disable, enable, encodeFindingsToClipboard, getQueueLength, getQueueSnapshot, init, isEnabled, onDisable, onEnable, queue, replaceQueue, sendBatch };