@hira-core/sdk 1.0.4 → 1.0.5

package/README.md

@@ -1,243 +1,349 @@
-# @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
+# @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.
+
+📖 **[Full Documentation](https://hira-sdk.vercel.app/)** — Guides, API reference, and examples.
+
+## 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,
+  defineFlowConfig,
+  IScriptContext,
+  BrowserUtils,
+  FlowLogger,
+} from "@hira-core/sdk";
+
+const config = defineFlowConfig({
+  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 },
+  ],
+  output: [
+    { index: 0, key: "isLoggedIn", label: "Login Status" },
+    { index: 1, key: "pageTitle", label: "Page Title" },
+  ],
+});
+
+type MyConfig = typeof config;
+```
+
+> **`defineFlowConfig()`** validates for **duplicate keys, labels, and output indices** at compile time — providing instant TS errors if any field is duplicated.
+
+### 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, output } = 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();
+
+    // Write typed output (validated against config.output keys)
+    await utils.writeOutput("isLoggedIn", true);
+    await utils.writeOutput("pageTitle", 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: {
+      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", // Hidemium antidetect browser
+  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`      | `IAntidetectProfile`         | Current profile info (unified across providers)      |
+| `index`        | `number`                     | Profile index in the batch                           |
+| `globalInput`  | `InferGlobalInput<TConfig>`  | Typed global inputs                                  |
+| `profileInput` | `InferProfileInput<TConfig>` | Typed per-profile inputs                             |
+| `output`       | `InferOutput<TConfig>`       | Current output values (pre-populated from last run)  |
+| `logger`       | `ILogger`                    | Bound logger (auto-tagged with profile name)         |
+
+### `IAntidetectProfile`
+
+Unified profile interface — works across all providers (GPM, Hidemium, etc.):
+
+```typescript
+interface IAntidetectProfile {
+  id: string;              // Unique ID
+  name: string;            // Human-readable name
+  provider: "gpm" | "hidemium" | "genlogin";
+  raw_proxy?: string;      // Proxy string
+  browser_type: "chromium" | "firefox";
+  browser_version: string;
+  group_id?: string;
+  profile_path: string;
+  note: string;
+  created_at: string;      // ISO 8601
+}
+```
+
+> **Note:** `IGpmProfile` is deprecated — use `IAntidetectProfile` instead.
+
+### `BrowserUtils`
+
+Helper class for common browser actions. All methods auto-log and respect the abort signal.
+
+```typescript
+const utils = new BrowserUtils(context);
+```
+
+#### Navigation & Interaction
+
+| 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.sleep(ms)`                          | Delay (respects abort signal) |
+
+#### Tab Management
+
+| Method                            | Description              |
+| --------------------------------- | ------------------------ |
+| `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     |
+
+#### Output & Data
+
+| Method                               | Description                                      |
+| ------------------------------------ | ------------------------------------------------ |
+| `utils.writeOutput(key, value)`      | Write output value (type-safe against config)     |
+| `utils.writeProfileInput(key, val)`  | Update profile input value for next run           |
+| `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 and outputs:
+
+```typescript
+interface IFlowConfig {
+  globalInput: readonly IInputField[];   // shared across all profiles
+  profileInput: readonly IInputField[];  // per-profile data
+  output?: readonly IOutputField[];      // output fields per profile
+}
+
+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 }[];
+}
+
+interface IOutputField {
+  index: number;   // display order
+  key: string;     // unique key for writeOutput()
+  label: string;   // human-readable label
+}
+```
+
+### `defineFlowConfig()`
+
+Helper function that validates your config at compile time — catches duplicate keys, labels, indices, and option values:
+
+```typescript
+// ✅ OK
+const config = defineFlowConfig({
+  globalInput: [
+    { key: "url", label: "URL", type: "text" },
+  ],
+  profileInput: [
+    { key: "user", label: "User", type: "text" },
+  ],
+  output: [
+    { index: 0, key: "status", label: "Status" },
+    { index: 1, key: "title", label: "Title" },
+  ],
+});
+
+// ❌ TS Error — duplicate key "url" in globalInput
+const bad = defineFlowConfig({
+  globalInput: [
+    { key: "url", label: "URL 1", type: "text" },
+    { key: "url", label: "URL 2", type: "text" }, // Error!
+  ],
+  profileInput: [],
+});
+```
+
+### `ExcelStorage`
+
+Read profile data from Excel files and write output back:
+
+```typescript
+import { ExcelStorage } from "@hira-core/sdk";
+
+const storage = new ExcelStorage("data.xlsx");
+
+// Read rows from a sheet
+const rows = await storage.readRows("Sheet1");
+
+// Write output rows
+await storage.writeRows("Output", outputData);
+```
+
+---
+
+## Type Inference
+
+The SDK automatically infers TypeScript types from your config at compile time:
+
+```typescript
+const config = defineFlowConfig({
+  globalInput: [
+    { key: "url", type: "text" as const, label: "URL" },
+    { key: "count", type: "number" as const, label: "Count" },
+  ],
+  profileInput: [
+    { key: "username", type: "text" as const, label: "Username" },
+  ],
+  output: [
+    { index: 0, key: "isLoggedIn", label: "Logged In" },
+  ],
+});
+
+// Inside script():
+// globalInput.url         → string  ✅
+// globalInput.count       → number  ✅
+// profileInput.username   → string  ✅
+// output.isLoggedIn       → ProfileOutputValue | null  ✅
+```
+
+---
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hira-core/sdk",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "SDK for building Hira automation flows with TypeScript",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,6 +25,11 @@
     "puppeteer"
   ],
   "author": "tttKiet",
+  "homepage": "https://hira-sdk.vercel.app/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tttKiet/hira-automation"
+  },
   "license": "ISC",
   "engines": {
     "node": ">=18.0.0"