@spark-apps/quickpeek 1.1.1 → 1.1.3

package/dist/voices-BtYZey4Y.d.mts

@@ -0,0 +1,287 @@
+/**
+ * Configuration types and defaults for QuickPeek
+ */
+declare const VERSION = "1.1.1";
+declare const CONFIG_FILE = "quickpeek.config.json";
+type UserTier = 'free' | 'pro';
+interface Config {
+    lang?: string;
+    plan?: {
+        maxSteps: number;
+    };
+    browser?: {
+        extension?: string;
+    };
+    video: {
+        width: number;
+        height: number;
+        format: string;
+        preset: 'ultrafast' | 'superfast' | 'veryfast' | 'faster' | 'fast' | 'medium' | 'slow' | 'slower' | 'veryslow';
+        quality: number;
+        fps: number;
+        cursor: boolean;
+        highlight: false | 'outline' | 'full';
+        fadeIn: number;
+        fadeOut: number;
+        transitions: 'none' | 'fade' | 'blend';
+        contrast: number;
+        tempo: number;
+        stepDelay: number;
+    };
+    audio?: {
+        voice?: string;
+        format: string;
+        bitrate: string;
+    };
+    music?: {
+        path: string;
+        volume: number;
+    };
+    timing: {
+        minStepDuration: number;
+    };
+    output: {
+        dir: string;
+    };
+}
+interface CaptionWordStyle {
+    color: string;
+    size: number;
+    bold: boolean;
+}
+interface CaptionStyle {
+    font: string;
+    outline: string;
+    outlineWidth: number;
+    shadow: number;
+    marginBottom: number;
+    regular: CaptionWordStyle;
+    highlight: CaptionWordStyle;
+}
+declare const DEFAULT_CONFIG: Config;
+declare const DEFAULT_CAPTIONS: CaptionStyle;
+
+/**
+ * AI API client — Spark AI communication
+ * Handles token management, rate limiting, and retries
+ *
+ * The API key is embedded at build time via tsup `define`.
+ * Per-user rate limiting is handled server-side via email.
+ */
+
+interface RateLimitInfo {
+    used: number;
+    limit: number;
+    tier: UserTier;
+    resetAt?: string;
+}
+interface AIResponse {
+    success: true;
+    content: string;
+    limits: RateLimitInfo;
+}
+interface AIError {
+    success: false;
+    error: string;
+    isRateLimit?: boolean;
+    isAuthError?: boolean;
+    retryAfterSeconds?: number;
+}
+type AIResult = AIResponse | AIError;
+/**
+ * Call Spark AI chat endpoint. Automatically retries on rate limit using Retry-After header.
+ */
+declare function callAI(systemPrompt: string, userPrompt: string, tier?: UserTier): Promise<AIResult>;
+/**
+ * Parse AI-generated plan JSON from response text
+ */
+declare function parseAIPlanResponse(content: string): {
+    success: true;
+    plan: {
+        title?: string;
+        description?: string;
+        steps: Array<{
+            id?: number;
+            action?: string;
+            caption?: string;
+            target?: string;
+            value?: string;
+        }>;
+    };
+} | {
+    success: false;
+    error: string;
+};
+/**
+ * Normalize a URL by adding https:// and stripping www prefix
+ */
+declare function normalizeUrl(input: string): string;
+
+/**
+ * Shared types for QuickPeek core
+ */
+/** Action type suggested for an element based on its type */
+type SuggestedAction = 'click' | 'type' | 'upload' | 'drag' | 'select' | 'check';
+/** Element type discovered on a page */
+type ElementType = 'button' | 'input' | 'link' | 'text' | 'file' | 'select' | 'range' | 'checkbox';
+/** Discovered element from page crawl */
+interface ElementInfo {
+    /** Element type */
+    type: ElementType | string;
+    /** Display text/label for the element */
+    text: string;
+    /** CSS selector to target the element */
+    selector: string;
+    /** Suggested action for this element */
+    action?: SuggestedAction;
+    /** Simplified target name (just the text, for AI use) */
+    target?: string;
+}
+/** Highlight mode for UI elements */
+type HighlightMode = false | 'outline' | 'full';
+/** Step in a demo plan */
+interface Step {
+    id: number | string;
+    action: string;
+    target?: string;
+    value?: string;
+    caption?: string;
+    description?: string;
+    duration?: number;
+    zoom?: number | string;
+    partial?: string;
+    transition?: 'fade' | 'blend';
+    highlight?: HighlightMode;
+    mediaFile?: string;
+    mediaType?: 'image' | 'video';
+}
+/** Demo plan structure */
+interface Plan {
+    url: string;
+    title: string;
+    description: string;
+    lang?: string;
+    steps: Step[];
+}
+
+/**
+ * Page crawling and interactive element extraction
+ */
+
+/**
+ * Crawl a page and extract interactive elements with smart selectors
+ * @param url - URL to crawl
+ * @param task - Optional progress reporter (CLI uses ora spinners, web can omit)
+ */
+declare function crawlPage(url: string, task?: (text: string) => {
+    succeed: (text?: string) => void;
+}): Promise<{
+    title: string;
+    elements: ElementInfo[];
+}>;
+
+/**
+ * Utility functions for QuickPeek
+ */
+/**
+ * Get full language name from ISO code
+ */
+declare function getLanguageName(lang?: string): string | null;
+/**
+ * Convert hex color (#RRGGBB) to ASS subtitle format (&HAABBGGRR)
+ */
+declare function hexToASS(hex: string, alpha?: number): string;
+/**
+ * Convert rgba() or rgb() color string to hex
+ */
+declare function rgbaToHex(color: string): string;
+/**
+ * Convert a Windows absolute path (D:\...) to WSL mount format (/mnt/d/...).
+ * Returns null if the path is not a Windows drive-letter path.
+ */
+declare function windowsPathToWSL(path: string): string | null;
+/**
+ * Parse partial field "start-end" into trim values
+ * e.g., "0-3.5" -> { trimStart: 0, trimEnd: 3.5 }
+ * e.g., "2-" -> { trimStart: 2, trimEnd: undefined }
+ */
+declare function parsePartial(partial: string | undefined): {
+    trimStart?: number;
+    trimEnd?: number;
+};
+/**
+ * Extract a message string from an unknown error value
+ */
+declare function getErrorMessage(err: unknown): string;
+/**
+ * Convert text to Title Case, keeping prepositions/articles lowercase
+ * First word is always capitalized
+ */
+declare function toTitleCase(text: string): string;
+
+/**
+ * AI prompts for demo plan generation
+ */
+
+declare function buildSystemPrompt(maxSteps: number): string;
+declare function buildUserPrompt(url: string, title: string, elements: ElementInfo[], langName: string | null, description: string | undefined, maxSteps: number): string;
+
+/**
+ * Shared constants for page scraping and element filtering
+ * Used by both CLI and web versions
+ */
+declare const EXCLUDED_LINK_PATTERNS: string[];
+/** CSS selectors for interactive page elements */
+declare const INTERACTIVE_SELECTORS: string[];
+/** Check if link text or href matches an excluded pattern */
+declare function isExcludedLink(text: string, href?: string): boolean;
+/** Check if a link should be skipped during crawling */
+declare function shouldSkipLink(text: string, href: string, currentPath: string): boolean;
+
+type Tier = 'free' | 'pro';
+declare const FEATURES: Record<string, string[]>;
+interface SparkSubscription {
+    payment_type: 'subscription' | 'one_time';
+    status: 'active' | 'trialing' | 'past_due' | 'canceled' | 'lifetime';
+    is_lifetime: boolean;
+    current_period_end: string;
+    cancel_at_period_end: boolean;
+    billing_interval: 'monthly' | 'yearly' | 'one_time';
+    price_id: string;
+    created_at: string;
+}
+interface SparkTrial {
+    is_expired: boolean;
+    days_remaining: number;
+    uses_remaining: number;
+    max_days: number;
+    max_uses: number;
+}
+interface SparkStatus {
+    subscription: SparkSubscription | null;
+    verified: boolean;
+    registered: boolean;
+    usage_count: number;
+    trial: SparkTrial | null;
+    message?: string;
+}
+declare const getStatus: (email: string) => Promise<SparkStatus>;
+declare function getStatusCached(email: string): Promise<SparkStatus>;
+declare function getTier(d: SparkStatus): Tier;
+declare const isPaid: (d: SparkStatus) => boolean;
+declare const hasAccess: (d: SparkStatus, min: Tier) => boolean;
+declare const hasTrialRemaining: (d: SparkStatus) => boolean;
+declare const showPaywall: (d: SparkStatus) => boolean;
+declare const isCanceling: (d: SparkStatus) => boolean;
+/** Resolve tier directly from an email — the most common consumer call. Falls back to 'free' on error. */
+declare function getTierByEmail(email: string): Promise<Tier>;
+/** Check whether an email is verified. Falls back to false on error. */
+declare function isVerified(email: string): Promise<boolean>;
+declare function pricingUrl(opts?: {
+    email?: string;
+    returnUrl?: string;
+}): string;
+
+declare const LANGUAGE_VOICES: Record<string, string>;
+
+export { type AIError as A, isPaid as B, type Config as C, DEFAULT_CAPTIONS as D, EXCLUDED_LINK_PATTERNS as E, FEATURES as F, isVerified as G, type HighlightMode as H, INTERACTIVE_SELECTORS as I, normalizeUrl as J, parseAIPlanResponse as K, LANGUAGE_VOICES as L, parsePartial as M, pricingUrl as N, rgbaToHex as O, type Plan as P, shouldSkipLink as Q, type RateLimitInfo as R, type SparkStatus as S, type Tier as T, type UserTier as U, VERSION as V, showPaywall as W, toTitleCase as X, windowsPathToWSL as Y, getTier as Z, type AIResponse as a, type AIResult as b, CONFIG_FILE as c, type CaptionStyle as d, type CaptionWordStyle as e, DEFAULT_CONFIG as f, type ElementInfo as g, type ElementType as h, type SparkSubscription as i, type SparkTrial as j, type Step as k, type SuggestedAction as l, buildSystemPrompt as m, buildUserPrompt as n, callAI as o, crawlPage as p, getErrorMessage as q, getLanguageName as r, getStatus as s, getStatusCached as t, getTierByEmail as u, hasAccess as v, hasTrialRemaining as w, hexToASS as x, isCanceling as y, isExcludedLink as z };

package/dist/web.d.mts

@@ -0,0 +1,102 @@
+export { A as AIError, a as AIResponse, b as AIResult, E as EXCLUDED_LINK_PATTERNS, g as ElementInfo, h as ElementType, F as FEATURES, H as HighlightMode, I as INTERACTIVE_SELECTORS, L as LANGUAGE_VOICES, P as Plan, R as RateLimitInfo, S as SparkStatus, i as SparkSubscription, j as SparkTrial, k as Step, l as SuggestedAction, T as Tier, m as buildSystemPrompt, n as buildUserPrompt, o as callAI, p as crawlPage, q as getErrorMessage, r as getLanguageName, s as getStatus, t as getStatusCached, Z as getTier, u as getTierByEmail, v as hasAccess, w as hasTrialRemaining, x as hexToASS, y as isCanceling, z as isExcludedLink, B as isPaid, G as isVerified, J as normalizeUrl, K as parseAIPlanResponse, M as parsePartial, N as pricingUrl, O as rgbaToHex, Q as shouldSkipLink, W as showPaywall, X as toTitleCase, Y as windowsPathToWSL } from './voices-BtYZey4Y.mjs';
+
+/**
+ * Plan Validation - Shared between CLI and Web
+ * Contains validation logic, prompts, and value preservation utilities
+ */
+/** Action types supported by QuickPeek */
+type StepAction = 'navigate' | 'click' | 'type' | 'select' | 'check' | 'wait' | 'scroll' | 'upload' | 'drag' | 'media' | 'showDownload';
+/** Base step structure - shared between CLI and Web */
+interface BaseStep {
+    action: StepAction | string;
+    target?: string;
+    value?: string;
+    caption?: string;
+    description?: string;
+}
+/** CLI step format */
+interface CLIStep extends BaseStep {
+    id: number;
+    caption: string;
+    duration?: number;
+    zoom?: number;
+}
+/** CLI plan format */
+interface CLIPlan {
+    url: string;
+    title: string;
+    description: string;
+    steps: CLIStep[];
+}
+/** Validation failure info */
+interface StepFailure {
+    stepIndex: number;
+    step: BaseStep;
+    error: string;
+    suggestion?: string;
+}
+/** Invalid target patterns - only filter out clearly wrong targets (file paths, generic terms) */
+declare const INVALID_TARGETS: RegExp[];
+/** Actions that require a target element */
+declare const ACTIONS_REQUIRING_TARGET: string[];
+/**
+ * Check if a step target is invalid (matches known bad patterns)
+ */
+declare function isInvalidTarget(target: string): boolean;
+/**
+ * Validate a single plan step
+ * Returns null if valid, error message if invalid
+ */
+declare function validateStep(step: BaseStep & {
+    mediaFile?: string;
+}): string | null;
+/**
+ * Check if a step is valid (returns boolean for filter operations)
+ */
+declare function isValidStep(step: BaseStep): boolean;
+/**
+ * Filter and validate plan steps, returning only valid ones
+ */
+declare function filterValidSteps<T extends BaseStep>(steps: T[]): T[];
+/** System prompt for refining plans based on user feedback */
+declare const REFINE_PLAN_SYSTEM_PROMPT = "You refine demo video plans based on user feedback.\n\nAVAILABLE ACTIONS (use these exact formats):\n\n1. WAIT - Pause for narration (intro/outro/explanations)\n   Format: { \"action\": \"wait\", \"caption\": \"Your narration text...\" }\n   Use when: Starting intro, ending outro, explaining something without interaction\n   NO target needed\n\n2. CLICK - Click buttons, links, or interactive elements\n   Format: { \"action\": \"click\", \"target\": \"button text\", \"caption\": \"Click description...\" }\n   Target: Just the button/link text (case insensitive, partial match OK)\n   Examples: \"extract frame\", \"download\", \"submit\", \"next\"\n   Use when: User says \"click\", \"press\", \"tap\", \"select button\", \"open\", \"close\"\n\n3. TYPE - Enter text into input fields\n   Format: { \"action\": \"type\", \"target\": \"input[name=\\\"field\\\"]\", \"value\": \"text to type\", \"caption\": \"...\" }\n   Selectors: input[type=\"text\"], input[name=\"...\"], textarea, #id\n   Use when: User says \"type\", \"enter\", \"input\", \"fill in\", \"write\"\n   CRITICAL: PRESERVE existing value - never change what's being typed\n\n4. UPLOAD - Upload a file to a web form's file input element\n   Format: { \"action\": \"upload\", \"target\": \"input[type=\\\"file\\\"]\", \"value\": \"path/to/file\", \"caption\": \"...\" }\n   Target: REQUIRED - CSS selector for file input, usually input[type=\"file\"]\n   Value: Path to file being uploaded\n   Use when: Uploading a file TO a website's form (the page has a file picker)\n   CRITICAL: PRESERVE existing value - never change the file path\n\n5. SCROLL - Scroll page or zoom camera\n   Format: { \"action\": \"scroll\", \"value\": \"direction\", \"caption\": \"...\" }\n   Values: \"up\", \"down\", \"bottom\", \"80%\" (page scroll) OR \"-10\", \"10\" (zoom: negative=out, positive=in)\n   Use when: User says \"scroll\", \"zoom in\", \"zoom out\", \"show more\", \"go to bottom\"\n   NO target needed\n\n6. DRAG - Drag sliders or rotate 3D objects\n   Format: { \"action\": \"drag\", \"target\": \"input[type=\\\"range\\\"]\", \"value\": \"50\", \"caption\": \"...\" }\n   Values: \"0\"-\"100\" for sliders, \"rotate\" for 3D rotation (stays at new angle), \"around\" for full 360\u00B0 (returns to start)\n   Selectors: input[type=\"range\"], canvas, .slider\n   Use when: User says \"drag\", \"slide\", \"adjust slider\", \"rotate\", \"spin\", \"move\"\n   NOTE: Use \"rotate\" (not \"around\") for showcasing 3D models - it rotates ~270\u00B0 and stays at the new position\n\n7. SELECT - Choose option from dropdown\n   Format: { \"action\": \"select\", \"target\": \"select[name=\\\"..\\\"]\", \"value\": \"option text\", \"caption\": \"...\" }\n   Selector: select, select[name=\"...\"], #id\n   Use when: User says \"select\", \"choose\", \"pick from dropdown\", \"change option\"\n\n8. CHECK - Toggle checkbox\n   Format: { \"action\": \"check\", \"target\": \"input[type=\\\"checkbox\\\"]\", \"caption\": \"...\" }\n   Selector: input[type=\"checkbox\"], [role=\"checkbox\"]\n   Use when: User says \"check\", \"uncheck\", \"toggle\", \"enable\", \"disable\"\n\n9. MEDIA - Display a media file fullscreen (NOT for uploading to a form!)\n   Format: { \"action\": \"media\", \"value\": \"path/to/file.png\", \"caption\": \"...\" }\n   Target: OPTIONAL - \"scale\" (fill viewport) or \"center\" (original size). Defaults to center.\n   Value: REQUIRED - File path to display\n   Supported: .png, .jpg, .jpeg, .gif, .webp, .mp4, .webm, .mov, .glb\n   Use when: Showing a file directly in the demo (screenshot, 3D model, video clip)\n   NOT for uploading - use UPLOAD action if page has a file input\n   CRITICAL: PRESERVE existing value - never change the file path\n\n10. SHOW_DOWNLOAD - Display a download animation/result\n    Format: { \"action\": \"showDownload\", \"caption\": \"...\" }\n    Use when: Showing the final result after a download action\n    NO target needed\n\nIMPORTANT - UPLOAD vs MEDIA:\n\u2022 UPLOAD: File goes INTO a web form (page has <input type=\"file\">). Requires target selector.\n\u2022 MEDIA: File is DISPLAYED fullscreen in demo (no web interaction). No target needed.\nExample: \"Show the 3D model\" \u2192 use MEDIA action\nExample: \"Upload a file to the converter\" \u2192 use UPLOAD action\n\nTARGET SYNTAX (simplified):\n\u2022 Buttons/Links: Just use the text! \"extract frame\", \"download\", \"submit\" (case insensitive)\n\u2022 Inputs: input[type=\"text\"], input[name=\"field\"], input[type=\"file\"], input[type=\"range\"]\n\u2022 By ID: #elementId (only if text won't work)\n\u2022 By class: .className (only if text won't work)\n\nPREFER SIMPLE TEXT for buttons: \"download\" instead of button:has-text(\"Download\")\n\nDETECTING USER INTENT:\n\u2022 \"add intro/outro\" \u2192 add wait step at start/end\n\u2022 \"remove step X\" \u2192 delete that step\n\u2022 \"change caption\" \u2192 update the caption text only\n\u2022 \"click X instead\" \u2192 change target to X\n\u2022 \"add a click on X\" \u2192 insert new click step\n\u2022 \"show the slider\" \u2192 add drag step for input[type=\"range\"]\n\u2022 \"zoom in/out\" \u2192 add scroll with numeric value\n\u2022 \"reorder\" \u2192 rearrange step sequence\n\nRULES:\n\u2022 Return ONLY valid JSON\n\u2022 Keep step ids sequential (1, 2, 3...)\n\u2022 PRESERVE upload/type values EXACTLY - copy from input unchanged\n\u2022 Only modify steps mentioned in feedback\n\u2022 Use available elements list when provided to find correct selectors\n\nReturn ONLY the modified JSON plan:\n{\n  \"steps\": [\n    { \"id\": 1, \"action\": \"wait\", \"caption\": \"intro text\" },\n    { \"id\": 2, \"action\": \"click\", \"target\": \"start\", \"caption\": \"Click to begin\" },\n    { \"id\": 3, \"action\": \"upload\", \"target\": \"input[type=\\\"file\\\"]\", \"value\": \"path/to/file.png\", \"caption\": \"Upload the file\" },\n    { \"id\": 4, \"action\": \"click\", \"target\": \"extract\", \"caption\": \"Process the file\" },\n    { \"id\": 5, \"action\": \"media\", \"value\": \"path/to/result.png\", \"caption\": \"Here's the result\" },\n    ...\n  ]\n}";
+/** System prompt for fixing failed steps using AI */
+declare const FIX_PLAN_SYSTEM_PROMPT = "You are a web automation expert. Fix demo plan steps that failed validation.\n\nRULES:\n\u2022 Return ONLY valid JSON with the complete plan structure\n\u2022 Fix ONLY the failed steps - keep working steps unchanged\n\u2022 Use the available page elements to find correct selectors\n\u2022 For click targets: use simplified button text like \"extract frame\", \"download\" (case insensitive)\n\u2022 For elements not found, check if a similar element exists in the page elements list\n\u2022 If an element truly doesn't exist, remove the step or change the action\n\u2022 Preserve file paths in \"value\" fields\n\u2022 Keep step ids sequential starting from 1\n\nTARGET PATTERNS:\n\u2022 Buttons/Links: Just the text! \"extract frame\", \"download\", \"submit\" (case insensitive)\n\u2022 File inputs: input[type=\"file\"]\n\u2022 Sliders: input[type=\"range\"]\n\u2022 Text inputs: input[name=\"field\"], #id, [placeholder=\"...\"]\n\nACTION FORMATS:\n\u2022 click: { \"target\": \"download\" } - use simplified button text\n\u2022 scroll: { \"value\": \"up|down\" } for page, { \"value\": \"10|-10\" } for zoom (positive=in, negative=out)\n\u2022 drag: { \"target\": \"input[type=\\\"range\\\"]\", \"value\": \"10\" } for sliders, { \"value\": \"rotate\" } for 3D rotation (auto-targets canvas)\n\u2022 media: { \"value\": \"path/to/file.png\" } - display file fullscreen (NOT upload!)\n\u2022 upload: { \"target\": \"input[type=\\\"file\\\"]\", \"value\": \"path/to/file\" } - upload to form\n\nIMPORTANT: Only use elements that actually exist on the page based on the provided list.";
+/** Collected values from original plan steps for preservation */
+interface PreservedValues {
+    uploadSteps: Array<{
+        value: string | undefined;
+        target: string | undefined;
+        mediaFile: string | undefined;
+        mediaType: string | undefined;
+    }>;
+    mediaSteps: Array<{
+        mediaFile: string | undefined;
+        mediaType: string | undefined;
+        target: string | undefined;
+    }>;
+    otherValues: Map<string, string>;
+}
+/**
+ * Collect values from original plan that need to be preserved through AI modifications
+ */
+declare function collectPreservedValues<T extends BaseStep & {
+    mediaFile?: string;
+    mediaType?: string;
+}>(steps: T[]): PreservedValues;
+/**
+ * Restore preserved values to AI-modified steps
+ * Returns indices of how many upload/media steps were restored
+ */
+declare function restorePreservedValues<T extends BaseStep & {
+    mediaFile?: string;
+    mediaType?: string;
+}>(step: T, preserved: PreservedValues, indices: {
+    uploadIdx: number;
+    mediaIdx: number;
+}): {
+    uploadIdx: number;
+    mediaIdx: number;
+};
+
+export { ACTIONS_REQUIRING_TARGET, type BaseStep, type CLIPlan, type CLIStep, FIX_PLAN_SYSTEM_PROMPT, INVALID_TARGETS, type PreservedValues, REFINE_PLAN_SYSTEM_PROMPT, type StepAction, type StepFailure, collectPreservedValues, filterValidSteps, isInvalidTarget, isValidStep, restorePreservedValues, validateStep };