Changelog

Full release history for @hira-core/sdk.

Unreleased — Production Stability Hardening

🔧 Breaking API Behavior

• activeNewTab() returns Promise<boolean> — true when activated, false when no matching tab is found before timeout.
• activePopup() returns Promise<boolean> — true when activated, false when no matching popup is found before timeout.

const opened = await utils.activeNewTab({ timeout: 8000 });
if (!opened) {
  logger.warn("New tab did not open — skip this step");
  return;
}

🛡️ Stability Fixes

• Tab/popup lookup now soft-fails internally instead of throwing on normal timeout cases.
• Browser page activation now catches non-critical CDP focus and stealth-script errors.
• activeDefault() focus emulation is guarded to avoid profile crashes when the page is unstable.
• BaseFlow.processProfile() clears retained disconnect promise closures and mutes profile loggers in finally to prevent long-running memory leaks and ghost logs.
• GPM and Hidemium startup failures now propagate the last real provider error message instead of hiding it behind generic retry failures.

📊 ExcelStorage

• createExcelStorage({ outputFile }) now preloads Excel output values into context.output before beforeBrowserOpened() runs.
• Flows can now skip completed Excel rows before opening Chrome, e.g. if (context.output.status === "success") return false.
• Runtime output mutation remains shared across hooks: beforeBrowserOpened() writes are visible in script(), and script() writes are visible in afterBrowserClosed().
• Merge precedence is null defaults → Excel output → existingOutputEntries, so server active output slots still override local Excel values.

📦 Packaging

• Removed private @packages/shared runtime imports from the published SDK by mirroring the required public output/logging types inside @hira-core/sdk.
• Fixed published package compatibility for standard npm installs by avoiding leaked workspace: dependency references.

✅ Recommended Flow Pattern

await utils.click("#connect-wallet");
const popupReady = await utils.activePopup({ matcher: "MetaMask", timeout: 8000 });
if (!popupReady) {
  logger.warn("MetaMask popup not found");
  return;
}
await utils.click("#approve");

v1.0.19 — Lifecycle Hooks & Element Hidden Wait

✨ Features

• Lifecycle hooks: beforeBrowserOpened() & afterBrowserClosed(): Optional hooks that flow subclasses can override to run logic before the browser launches and after it closes. Return false to skip or stop the profile.

  protected async beforeBrowserOpened(context) {
    // Pre-checks, early output writes, skip logic
    if (shouldSkip) return false; // → profile status: "skipped"
  }
   
  protected async afterBrowserClosed(context) {
    // Cleanup, post-processing
    if (shouldStop) return false; // → stop remaining profiles
  }

• context.browserUtils: Now a first-class field on IScriptContext — available in hooks and script(). Before browser opens (in beforeBrowserOpened), only writeOutput() works; other methods throw a clear error.
• waitForElementHidden(selector, timeout?, scope?): Wait for an element to disappear from the DOM. Returns true if gone, false if still visible (soft fail).

  await utils.click("#submit");
  const gone = await utils.waitForElementHidden("//div[@class='spinner']", 10000);

• ProfileProcessResult: processProfile() now returns explicit status: "completed", "skipped", or "stopped".

🔧 Improvements

• Earlier context creation: Output, globalInput, profileInput, and the full context object are now built before browser opens — hooks have full access.
• Smarter abort handling: Abort signal checked at the top of processProfile() — cancelled flows are detected before any browser interaction.
• afterBrowserClosed safety: Only fires when the browser was actually closed (skipped when keepOpenOnError is active).

v1.0.17 — Keyboard Utilities & Critical Timeout Fix

✨ Features

• keyPress(key, options?): Press a single keyboard key (Enter, Escape, Tab, F5, ArrowDown, etc.)

  await utils.keyPress("Enter");
  await utils.keyPress("Tab");

• comboKey(modifier, key): Press key combinations with modifiers. Supports multi-modifier syntax (Control+Shift)

  await utils.comboKey("Control", "a");       // Select all
  await utils.comboKey("Control", "c");       // Copy
  await utils.comboKey("Control+Shift", "i"); // DevTools

• input(selector, value, options?): Set input value directly via JavaScript — no keyboard simulation. Uses native HTMLInputElement.prototype.value setter for React controlled input compatibility

  await utils.input("//input[@placeholder='0']", "250");
  await utils.input("#email", "user@example.com");

🐛 Critical Fixes

• waitForElement(selector, 0) infinite hang — Puppeteer treats waitForSelector({ timeout: 0 }) as “no timeout limit” (wait forever). exists() with no timeout argument (default 0) would hang indefinitely. Fixed: timeout <= 0 now uses instant $() query instead
• Timeout safety cap — waitForElement() caps any timeout to max 60 seconds to prevent accidental infinite waits
• keyPress / comboKey crash on iframe — used activeFrame.keyboard which doesn’t exist on Frame. Fixed to always use activePage.keyboard

v1.0.16 — Cursor Rewrite, Excel Mutex & Platform Features

Consolidates all changes from v1.0.9 through v1.0.15.

✨ Features

• Flow Library & Marketplace: Full server-side flow library management — upload, versioning, search, and purchase flows from the marketplace
• Payment Processing: Integrated payment module for flow purchases with transaction history
• User Reviews: Review and rating system for published flows
• Admin Dashboard: Admin modules for managing users, flows, payments, and platform analytics

🔧 Improvements

• HiraCursor rewrite: Replaced page.evaluateHandle callback injection with an inline IIFE string — prevents javascript-obfuscator from mangling Buffer references and breaking cursor SVG injection at runtime
• Cursor segment threshold: Lowered from 500px to 300px with shorter segments for smoother, more human-like long-distance mouse movements
• ExcelStorage per-file mutex: Added acquireLock() static method with per-file promise chaining — serializes concurrent writes to avoid “Corrupted zip” errors when multiple profiles write to the same Excel file simultaneously
• BrowserUtils cursor init guard: Constructor now captures cursor inject errors via _cursorInitPromise and rethrows on first action — prevents silent failures
• Selector truncation limit: Increased shortSelector() from 60 → 200 characters — long XPath selectors are no longer prematurely truncated in logs
• Viewport evaluation: Changed page.evaluate(() => window.innerHeight) to page.evaluate("window.innerHeight") — simpler expression string, avoids potential obfuscation issues

📦 Dependencies

• Bumped axios to ^1.13.4, typescript to ^5.9.3, @types/node to ^25.2.2
• Bumped ghost-cursor to ^1.4.2

v1.0.8 — Stealth Scripts & Virtual Cursor Toggle

✨ Features

• Stealth scripts: Automatically removes automation fingerprints (navigator.webdriver, empty plugins, Chrome DevTools protocol artifacts) via evaluateOnNewDocument — persists across navigations
• Virtual cursor toggle: New IExecutionConfig.virtualCursor option (default: true) — allows disabling the SVG cursor overlay from Execution Settings without changing flow code

🔧 Improvements

• Stealth scripts are re-applied when switching tabs (activeTab, activeNewTab, activePopup)
• All internal JSDoc comments translated to English

v1.0.7 — HiraCursor Rewrite & New Interactions

✨ Features

• HiraCursor rewrite: New Bézier curve mouse movement engine with human-like timing and realistic trajectory
• Smooth 60fps scroll: New scrollDelta() uses requestAnimationFrame inside the browser with ease-in-out sine curve — no Node.js setTimeout jitter
• Container scrolling: scrollContainerDelta() for overflow containers, moveToContainer() to position cursor before scrolling
• Scroll helpers: scrollToPosition("top" | "bottom"), scrollElementIntoView(element)
• select(): New method for <select> dropdowns — cursor moves to select → click → page.select() (native <option> elements are not clickable)
• getPosition(): Get element center or random point within bounds — useful for coordinate-based interactions
• Click by coordinates: click() now accepts { x, y } coordinates as a target in addition to selectors/ElementHandles
• Segment-based cursor movement: Long-distance cursor moves are split into segments with slight jitter for more natural movement

🔧 Improvements

• HiraCursor.clickElement() uses human-like random hesitation (80–250ms) and hold duration (30–120ms)
• Cursor state is persisted per-page via WeakMap — no cursor leaks across pages
• inject() / markDirty() pattern ensures cursor SVG survives page navigations

v1.0.6 — BrowserUtils API Overhaul

This version contains breaking changes to how BrowserUtils methods are called.

⚠️ Breaking Changes

• Options object pattern: All methods now accept an options object instead of positional arguments

  // Before (v1.0.5)
  await b.click('#btn', { timeout: 5000 });
   
  // After (v1.0.6)
  await b.click({ selector: '#btn', waitTimeout: 5000 });

• Renamed methods:

  Old	New
  switchToDefault()	activeDefault()
  switchToPopup()	activePopup()
  switchToTabIndex(n)	activeTab({ index: n })

• Removed deprecated methods: switchToPopup, switchToTabIndex, switchToDefault

✨ Features

• New methods:
  • activeIframe({ selector }) — switch context into an iframe
  • activeMainFrame() — return to the main frame
  • activeNewTab() — switch to the most recently opened tab
  • waitForNewTab({ action }) — perform an action and wait for a new tab to open
  • waitForPopup({ action }) — perform an action and wait for a popup to open

🔧 Improvements

• Default timeouts normalized to multiples of 4000ms
• screenshot() changed to soft-fail (no longer throws on failure)
• Added comprehensive English JSDoc with @param, @returns, @example
• Fixed Hidemium adapter: window scaling and connection reliability

v1.0.5 — Agent UX & Anti-detect Settings

🔧 Improvements

• Fixed Hidemium window scaling and connection reliability
• Added anti-detect browser selector in Execution Settings
• Settings sidebar, connection management

v1.0.4 — Output Slots & Execution Chain

✨ Features

• Implemented output slot CRUD with per-key merge and PIN-safe flush
• Slot-aware output persistence with merge strategy
• Pass versionId through flow execution chain for output slot

v1.0.3 — Provider Selector & Type-safe I/O

✨ Features

• Anti-detect provider selector (GPM, Hidemium)
• Type-safe writeOutput() with ProfileOutputValue (string, number, boolean, Array, Object)
• Type-safe writeProfileInput() with string | number | boolean
• Excel storage module

v1.0.2 — NPM Publish & Security

✨ Features

• Published to npm as @hira-core/sdk
• HMAC signing for flow packages
• Gzip compression for flow bundles
• Module allow-list security

v1.0.1 — Logger Refactor

🔧 Improvements

• createBoundLogger — structured profile logging
• Fixed closeAll() — logs “Closing browser…” per-profile
• Action/log delay in BrowserUtils

v1.0.0 — Initial Release

• Base flow lifecycle (AntidetectBaseFlow)
• BrowserUtils core methods
• Flow config system (inputs, outputs)
• GPM adapter