@hira-core/sdk 1.0.0 → 1.0.2

package/README.md

@@ -0,0 +1,232 @@
+# @hira-core/sdk
+
+SDK for building **Hira** automation flows with TypeScript. Provides type-safe base classes, browser utilities, and logger for running flows inside the Hira Agent sandbox.
+
+## Installation
+
+```bash
+npm install @hira-core/sdk
+# or
+pnpm add @hira-core/sdk
+```
+
+> **Peer dependency:** Requires `puppeteer-core` to be available at runtime (provided by the Hira Agent).
+
+---
+
+## Quick Start
+
+### 1. Define your Flow Config
+
+```typescript
+import {
+  AntidetectBaseFlow,
+  AntidetectProvider,
+  IFlowConfig,
+  IScriptContext,
+  BrowserUtils,
+  FlowLogger,
+} from "@hira-core/sdk";
+
+const config = {
+  globalInput: [
+    { key: "targetUrl", label: "Target URL", type: "text" as const, required: true },
+    { key: "delay",     label: "Delay (ms)",  type: "number" as const, defaultValue: 2000 },
+  ],
+  profileInput: [
+    { key: "username", label: "Username", type: "text" as const },
+    { key: "password", label: "Password", type: "text" as const },
+  ],
+} as const satisfies IFlowConfig;
+
+type MyConfig = typeof config;
+```
+
+### 2. Implement your Flow class
+
+```typescript
+export class MyFlow extends AntidetectBaseFlow<MyConfig> {
+  constructor() {
+    super(AntidetectProvider.GPM, new FlowLogger(MyFlow.name), config);
+  }
+
+  async script(context: IScriptContext<MyConfig>): Promise<void> {
+    const { page, logger, globalInput, profileInput } = context;
+    const utils = new BrowserUtils(context);
+
+    await utils.goto(globalInput.targetUrl);
+    logger.info(`Logging in as: ${profileInput.username}`);
+
+    await utils.type("#username", profileInput.username);
+    await utils.type("#password", profileInput.password);
+    await utils.click("#login-btn");
+
+    const title = await page.title();
+    logger.success(`✅ Done — page: ${title}`);
+  }
+}
+
+export default MyFlow;
+```
+
+### 3. Run locally (for development)
+
+```typescript
+import MyFlow from "./index";
+
+const flow = new MyFlow();
+
+await flow.run(
+  flow.createRunParams({
+    antidetect: {
+      name: "GPM",
+      profileSettings: [
+        flow.createProfileSetting("ProfileA", { username: "user1", password: "pass1" }),
+      ],
+    },
+    execution: { concurrency: 2, maxRetries: 1 },
+    globalInput: { targetUrl: "https://example.com", delay: 2000 },
+    window: { width: 1280, height: 720, scale: 1 },
+  })
+);
+```
+
+---
+
+## API Reference
+
+### `AntidetectBaseFlow<TConfig>`
+
+Abstract base class for browser automation flows.
+
+| Method / Property | Description |
+|---|---|
+| `abstract script(context)` | Your automation logic — implement this |
+| `run(params)` | Start the flow (called by Hira Agent) |
+| `createRunParams(params)` | Type-safe helper to build run params |
+| `createProfileSetting(name, data?)` | Type-safe helper to build profile settings |
+| `flowConfig` | The declared config schema (embedded in `.hira`) |
+
+### `AntidetectProvider`
+
+```typescript
+enum AntidetectProvider {
+  GPM = "gpm",        // GPM Login antidetect browser
+  HIDEMIUM = "hidemium",  // coming soon
+  GENLOGIN = "genlogin",  // coming soon
+}
+```
+
+### `IScriptContext<TConfig>`
+
+Injected into `script()` by the runtime:
+
+| Field | Type | Description |
+|---|---|---|
+| `browser` | `Browser` | Puppeteer browser instance |
+| `page` | `Page` | Active page |
+| `profile` | `IGpmProfile` | Current GPM profile info |
+| `index` | `number` | Profile index in the batch |
+| `globalInput` | `InferGlobalInput<TConfig>` | Typed global inputs |
+| `profileInput` | `InferProfileInput<TConfig>` | Typed per-profile inputs |
+| `logger` | `ILogger` | Bound logger (auto-tagged with profile name) |
+
+### `BrowserUtils`
+
+Helper class for common browser actions. All methods auto-log and respect the abort signal.
+
+```typescript
+const utils = new BrowserUtils(context);
+```
+
+| Method | Description |
+|---|---|
+| `utils.goto(url)` | Navigate to URL |
+| `utils.click(selector)` | Wait + scroll + click |
+| `utils.type(selector, text)` | Wait + clear + type |
+| `utils.getText(selector)` | Get text content |
+| `utils.exists(selector, timeout?)` | Check element exists |
+| `utils.waitForElement(selector, timeout?)` | Wait for element |
+| `utils.waitForNavigation()` | Wait for page navigation |
+| `utils.screenshot(path?)` | Take screenshot |
+| `utils.switchToPopup(matcher)` | Switch to popup tab |
+| `utils.switchToTabIndex(index)` | Switch to tab by index |
+| `utils.closeCurrentTab()` | Close current tab |
+| `utils.closeOtherTabs()` | Close all other tabs |
+| `utils.sleep(ms)` | Delay (respects abort signal) |
+| `utils.logGlobalInput()` | Log all global inputs |
+| `utils.logProfileInput()` | Log all profile inputs |
+
+### `FlowLogger`
+
+Logger that works both in standalone mode (console) and inside Hira Agent worker (postMessage).
+
+```typescript
+const logger = new FlowLogger("MyFlow");
+
+logger.info("message");
+logger.success("done");
+logger.warn("warning");
+logger.error("error");
+logger.debug("debug");
+```
+
+### `IFlowConfig`
+
+Schema declaration for your flow's inputs:
+
+```typescript
+interface IFlowConfig {
+  globalInput: readonly IInputField[];   // shared across all profiles
+  profileInput: readonly IInputField[];  // per-profile data
+}
+
+interface IInputField {
+  key: string;
+  label: string;
+  type: "text" | "number" | "boolean" | "select" | "textarea";
+  required?: boolean;
+  defaultValue?: string | number | boolean;
+  placeholder?: string;
+  options?: { label: string; value: string | number }[];
+}
+```
+
+---
+
+## Type Inference
+
+The SDK automatically infers TypeScript types from your config at compile time:
+
+```typescript
+const config = {
+  globalInput: [
+    { key: "url",   type: "text"   as const },
+    { key: "count", type: "number" as const },
+  ],
+  profileInput: [
+    { key: "username", type: "text" as const },
+  ],
+} as const satisfies IFlowConfig;
+
+// Inside script():
+// globalInput.url   → string  ✅
+// globalInput.count → number  ✅
+// profileInput.username → string  ✅
+```
+
+---
+
+## Building & Publishing a Flow
+
+Use [`@hira-core/cli`](https://www.npmjs.com/package/@hira-core/cli) to package your flow:
+
+```bash
+npx @hira-core/cli build
+```
+
+---
+
+## License
+
+ISC