@perspective-ai/sdk 1.0.0-alpha.2

package/dist/browser.d.ts

@@ -0,0 +1,213 @@
+declare const ERROR_CODES: {
+    readonly SDK_OUTDATED: "SDK_OUTDATED";
+    readonly INVALID_RESEARCH: "INVALID_RESEARCH";
+    readonly UNKNOWN: "UNKNOWN";
+};
+type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+declare const THEME_VALUES: {
+    readonly dark: "dark";
+    readonly light: "light";
+    readonly system: "system";
+};
+type ThemeValue = (typeof THEME_VALUES)[keyof typeof THEME_VALUES];
+
+/**
+ * Type definitions for the Perspective Embed SDK
+ * This file is TYPE-ONLY - no runtime value imports or exports
+ * SSR-safe by design
+ */
+
+type EmbedType = "widget" | "popup" | "slider" | "float" | "fullpage" | "chat";
+/** Brand colors that can be passed via embed code */
+interface BrandColors {
+    /** Primary accent color (buttons, links, focus states) */
+    primary?: string;
+    /** Secondary accent color */
+    secondary?: string;
+    /** Background color of the embed */
+    bg?: string;
+    /** Primary text color */
+    text?: string;
+}
+interface EmbedConfig {
+    researchId: string;
+    type?: EmbedType;
+    /** Custom button text for popup/slider triggers */
+    buttonText?: string;
+    /** Custom params to pass to the interview (for tracking/attribution) */
+    params?: Record<string, string>;
+    /** Brand colors to override Research settings */
+    brand?: {
+        light?: BrandColors;
+        dark?: BrandColors;
+    };
+    /** Force theme mode: 'dark', 'light', or 'system' (default) */
+    theme?: ThemeValue;
+    /** Override the default host (defaults to https://getperspective.ai) */
+    host?: string;
+    /** Callback when embed is ready */
+    onReady?: () => void;
+    /** Callback when interview is submitted/completed */
+    onSubmit?: (data: {
+        researchId: string;
+    }) => void;
+    /** Callback when embed wants to navigate. If provided, parent handles navigation; otherwise SDK navigates via window.location.href */
+    onNavigate?: (url: string) => void;
+    /** Callback when embed is closed */
+    onClose?: () => void;
+    /** Callback on any error */
+    onError?: (error: EmbedError) => void;
+}
+/** Embed error with code for programmatic handling */
+interface EmbedError extends Error {
+    code?: ErrorCode;
+}
+/** Handle returned by embed creation functions */
+interface EmbedHandle {
+    unmount: () => void;
+    update: (options: Partial<Pick<EmbedConfig, "onReady" | "onSubmit" | "onNavigate" | "onClose" | "onError">>) => void;
+    /** @deprecated Use unmount() instead */
+    destroy: () => void;
+    /** @deprecated For legacy compatibility */
+    readonly researchId: string;
+    /** @deprecated For legacy compatibility */
+    readonly type: EmbedType;
+    /** @deprecated For legacy compatibility - may be null on server */
+    readonly iframe: HTMLIFrameElement | null;
+    /** @deprecated For legacy compatibility - may be null on server */
+    readonly container: HTMLElement | null;
+}
+/** Handle for float bubble with open/close control (persistent UI element) */
+interface FloatHandle extends Omit<EmbedHandle, "type"> {
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    readonly isOpen: boolean;
+    readonly type: "float";
+}
+/** Theme configuration from API */
+interface ThemeConfig {
+    primaryColor: string;
+    textColor: string;
+    darkPrimaryColor: string;
+    darkTextColor: string;
+}
+/** SDK global configuration */
+interface SDKConfig {
+    /** Override the default host */
+    host?: string;
+}
+
+/**
+ * Inline widget embed - renders directly in a container element
+ * SSR-safe - returns no-op handle on server
+ */
+
+declare function createWidget(container: HTMLElement | null, config: EmbedConfig): EmbedHandle;
+
+/**
+ * Popup/modal embed - opens in a centered modal overlay
+ * SSR-safe - returns no-op handle on server
+ */
+
+declare function openPopup(config: EmbedConfig): EmbedHandle;
+
+/**
+ * Slider/drawer embed - slides in from the right
+ * SSR-safe - returns no-op handle on server
+ */
+
+declare function openSlider(config: EmbedConfig): EmbedHandle;
+
+/**
+ * Floating bubble embed - floating button that opens a chat window
+ * SSR-safe - returns no-op handle on server
+ */
+
+type FloatConfig = EmbedConfig & {
+    _themeConfig?: ThemeConfig;
+};
+declare function createFloatBubble(config: FloatConfig): FloatHandle;
+/** @deprecated Use createFloatBubble instead */
+declare const createChatBubble: typeof createFloatBubble;
+
+/**
+ * Fullpage embed - takes over entire viewport
+ * SSR-safe - returns no-op handle on server
+ */
+
+declare function createFullpage(config: EmbedConfig): EmbedHandle;
+
+/**
+ * Embed SDK configuration
+ * SSR-safe - DOM access is guarded and lazy
+ */
+
+/**
+ * Configure the SDK globally
+ * Call this before creating any embeds if you need to override defaults
+ */
+declare function configure(config: SDKConfig): void;
+/**
+ * Get the current SDK configuration
+ */
+declare function getConfig(): SDKConfig;
+
+/**
+ * Perspective Embed SDK - Browser Entry
+ *
+ * CDN/Script Tag Entry Point - auto-init, attaches to window.Perspective
+ *
+ * Usage:
+ *   <script src="https://getperspective.ai/v1/perspective.js"></script>
+ *
+ *   <!-- Auto-init with data attributes -->
+ *   <div data-perspective-widget="research_xxx"></div>
+ *   <button data-perspective-popup="research_xxx">Open Survey</button>
+ *
+ *   <!-- Or programmatic -->
+ *   <script>
+ *     Perspective.openPopup({ researchId: 'xxx' });
+ *   </script>
+ */
+
+/**
+ * Initialize an embed programmatically
+ */
+declare function init(config: EmbedConfig): EmbedHandle | FloatHandle;
+/**
+ * Mount a widget into a container element
+ */
+declare function mount(container: HTMLElement | string, config: EmbedConfig): EmbedHandle;
+/**
+ * Destroy an embed instance
+ */
+declare function destroy(researchId: string): void;
+declare function destroyAll(): void;
+/**
+ * Auto-initialize embeds from data attributes
+ */
+declare function autoInit(): void;
+declare const Perspective: {
+    configure: typeof configure;
+    getConfig: typeof getConfig;
+    init: typeof init;
+    mount: typeof mount;
+    destroy: typeof destroy;
+    destroyAll: typeof destroyAll;
+    autoInit: typeof autoInit;
+    createWidget: typeof createWidget;
+    openPopup: typeof openPopup;
+    openSlider: typeof openSlider;
+    createFloatBubble: typeof createFloatBubble;
+    createFullpage: typeof createFullpage;
+    createChatBubble: typeof createFloatBubble;
+};
+declare global {
+    interface Window {
+        __PERSPECTIVE_SDK_INITIALIZED__?: boolean;
+        Perspective?: typeof Perspective;
+    }
+}
+
+export { autoInit, configure, createChatBubble, createFloatBubble, createFullpage, createWidget, Perspective as default, destroy, destroyAll, getConfig, init, mount, openPopup, openSlider };