Getting Started

Installation


pnpm add @hira-core/sdk

[!NOTE] The SDK requires puppeteer-core as a peer dependency. An anti-detect browser (GPM, Hidemium) provides the actual browser instance.

Create Your First Flow

Define the config

Use defineFlowConfig() to declare your flow’s inputs and outputs with full type safety:


import { defineFlowConfig } from '@hira-core/sdk'
 
export const config = defineFlowConfig({
  globalInput: [
    { key: 'targetUrl', label: 'Target URL', type: 'text', required: true },
    { key: 'maxPages', label: 'Max Pages', type: 'number', defaultValue: 5 },
  ],
  profileInput: [
    { key: 'email', label: 'Email', type: 'text', required: true },
    { key: 'password', label: 'Password', type: 'text', required: true },
  ],
  output: [
    { index: 0, key: 'loginStatus', label: 'Login Status' },
    { index: 1, key: 'pageTitle', label: 'Page Title' },
  ],
})

Create the flow class

Extend AntidetectBaseFlow and implement the script() method — this is where your automation logic runs for each profile:


import {
  AntidetectBaseFlow, AntidetectProvider, BrowserUtils,
  FlowLogger, IScriptContext,
} from '@hira-core/sdk'
import { config } from './config'
 
type Config = typeof config
 
export default class MyFirstFlow extends AntidetectBaseFlow<Config> {
  constructor(provider: AntidetectProvider = AntidetectProvider.GPM) {
    super(provider, new FlowLogger('MyFirstFlow'), config)
  }
 
  async script(context: IScriptContext<Config>) {
    const browser = new BrowserUtils(context)
    const { targetUrl } = context.globalInput
    const { email, password } = context.profileInput
 
    // Navigate to target
    await browser.goto(targetUrl)
    // Log: 🌐 Navigate → https://example.com
 
    // Login
    await browser.type('#email', email)
    // Log: ⌨️ Type "user@exam..." → #email
    await browser.type('#password', password)
    // Log: ⌨️ Type "secret123" → #password
    await browser.click('#login-btn')
    // Log: 🖱️ Click: #login-btn
 
    // Wait for page to load
    await browser.waitForNavigation()
    // Log: 🔄 Waiting for navigation...
 
    // Write output
    await browser.writeOutput('loginStatus', 'Success')
    // Log: 📤 Write Output [loginStatus] = Success
    const title = await browser.getText('h1')
    await browser.writeOutput('pageTitle', title ?? 'N/A')
    // Log: 📤 Write Output [pageTitle] = Dashboard
  }
}

Set up project structure


my-flow/
├── src/
│   ├── config.ts     ← defineFlowConfig()
│   └── index.ts      ← Flow class (default export)
├── package.json
└── tsconfig.json

Configure package.json


{
  "name": "my-first-flow",
  "version": "1.0.0",
  "main": "src/index.ts",
  "dependencies": {
    "@hira-core/sdk": "^1.0.16"
  }
}

Flow Lifecycle

When your flow runs, the SDK calls these methods in order:


run()              → Orchestrate profiles (concurrency, delay, retry)
  ↓
For each profile:
  Open browser      → Anti-detect adapter opens profile
  script()          → ★ Your main automation logic
  Close browser     → Auto-close profile
  ↓
All profiles done   → Flow complete

[!TIP] You only need to implement script(). The SDK handles browser opening/closing, retry, concurrency, and error handling automatically.

What’s Next?

Core Concepts — Deep dive into lifecycle, config, and type system
Browser Utils — All available browser methods
Excel Storage — Read/write data from Excel files