npm package: @intellicrawl/intellicrawl-module-sdk
Description: 輕量級的 IntelliCrawl 模組開發工具包 - 支援 ESM + TypeScript + Vite
Author: IntelliCrawl 開發團隊
Latest version: 2.0.8

# IntelliCrawl Module SDK

> 輕量級的 IntelliCrawl 模組開發工具包 - 支援 ESM + TypeScript + Vite

快速建立、開發和打包 IntelliCrawl 爬蟲模組的現代化開發工具。

## ✨ 特色

- 🚀 **開箱即用** - 一個命令即可建立完整的開發環境
- 📦 **Vite 驅動** - 快速的建置和熱重載
- 🔒 **類型安全** - 完整的 TypeScript 支援
- ⚡ **TypeScript 原生支援** - Vite Plugin 可直接處理 TypeScript 程式碼
- 🛡️ **內建驗證** - Vite 插件自動檢查 Node.js 模組白名單
- 🧪 **測試工具** - 內建 Mock 環境和測試輔助函數
- 📝 **完整類型定義** - 出色的 IDE 支援和自動補全

## � 依賴需求

### 必需依賴

- Node.js >= 18.0.0
- TypeScript >= 5.0.0

### Peer 依賴（可選）

SDK 使用 **peer dependencies** 來引用以下套件的型別，您的專案中需要安裝它們才能獲得完整的型別支援：

- **pino** (^8.0.0) - Logger 型別定義
- **playwright** (^1.40.0) - 瀏覽器自動化型別定義
- **vite** (^4.0.0 || ^5.0.0 || ^7.0.0) - 使用 Vite Plugin 時需要

```bash
# 安裝 peer dependencies
npm install --save-dev pino playwright vite
```


> **💡 注意**：這些依賴標記為 `optional`，即使不安裝也能使用基本功能，但強烈建議安裝以獲得更好的開發體驗。

## 📦 安裝

```bash
npm install @intellicrawl/intellicrawl-module-sdk
```

## 快速開始

### 建立新專案

```bash
# 使用 npx (推薦)
npx @intellicrawl/intellicrawl-module-sdk init my-crawler-module

# 或使用全域安裝
npm install -g @intellicrawl/intellicrawl-module-sdk
intellicrawl-cli init my-crawler-module
```

### 開發模組


```bash
cd my-crawler-module

# 安裝依賴
npm install

# 開發模式 (支援熱重載)
npm run dev

# 建置模組
npm run build

# 測試模組
npm test
```

## 🛠️ 使用方式



## �📦 快速開始

### 建立新專案

```bash
# 使用 npx (推薦)
npx @intellicrawl/intellicrawl-module-sdk init my-crawler-module

# 或使用全域安裝
npm install -g @intellicrawl/intellicrawl-module-sdk
intellicrawl-cli init my-crawler-module
```

### 開發模組

```bash
cd my-crawler-module

# 安裝依賴
npm install

# 開發模式 (支援熱重載)
npm run dev

# 建置模組
npm run build

# 測試模組
npm test
```

## 🛠️ 使用方式

### 1. 建立模組

建立一個簡單的爬蟲模組：

```typescript
每個模組都有相同的結構：

```typescript
// src/modules/my-module.ts
import type { UnifiedModule } from '@intellicrawl/intellicrawl-module-sdk';

export const MyModule: UnifiedModule = {
```

### 2. 配置 Vite 插件

`intellicrawlPlugin` 提供 Node.js 白名單驗證和自動轉換：

```typescript
```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import { intellicrawlPlugin } from '@intellicrawl/intellicrawl-module-sdk/vite-plugin';

export default defineConfig({
  plugins: [intellicrawlPlugin()],
});
```

### 3. 使用 EmbeddedWorkflow

建立複雜的工作流程模組：

```typescript
import type { UnifiedModule } from '@intellicrawl/intellicrawl-module-sdk';
import { myLoginModule } from './login';
import { myParserModule } from './parser';

export const workflowModule: UnifiedModule = {
  metadata: {
    name: 'workflow-example',
    version: '1.0.0',
  },

  // ✨ Vite 插件會自動將實例引用轉換為正確的格式
  embeddedWorkflow: {
    steps: [
      {
        id: 'login',
        module: myLoginModule,  // 直接引用！
        config: { username: 'user', password: 'pass' },
      },
      {
        id: 'parse',
        module: myParserModule,
        config: { format: 'json' },
      },
    ],
  },
};
```

### 4. TypeScript 完整支援

Vite Plugin 原生支援 TypeScript，無需額外配置：

```typescript
// ✅ 直接在 .ts 檔案中使用，plugin 會自動識別並處理

interface StepConfig {
  timeout: number;
  retries?: number;
}

export const typedWorkflow: WorkflowDefinition = {
  embeddedWorkflow: {
    steps: [
      {
        id: 'step1',
        module: MyModule,  // ✨ 自動轉換 TypeScript 中的引用
        config: {
          timeout: 5000,
          retries: 3
        } as StepConfig
      }
    ]
  }
};
```

**工作原理：**
- 自動偵測 `.ts`、`.tsx` 檔案並使用 TypeScript parser
- 支援 interface、type、enum、泛型等所有 TypeScript 特性
- 解析失敗時自動降級到 JavaScript parser
- 詳細說明請參考 [TypeScript 支援文件](./docs/TYPESCRIPT_SUPPORT.md)

### 5. 測試模組

使用內建的測試工具：

```typescript
// tests/example.test.ts
import { testModule, assert } from '../tests/test-helpers';
import { myModule } from '../src/modules/example';

async function testMyModule() {
  const result = await testModule(
    myModule,
    {
      url: 'https://example.com',
      selector: 'h1',
    },
    {
      mockBrowser: true,
      mockData: { textContent: 'Hello World' },
    }
  );

  assert(result.content === 'Hello World', '內容應該匹配');
  console.log('✓ 測試通過');
}

testMyModule();
```

## 📚 API 參考

### 核心類型

- **`UnifiedModule`** - 模組主介面
- **`ModuleExecutionContext`** - 執行環境上下文
- **`ModuleMetadata`** - 模組元資料
- **`EmbeddedWorkflowConfig`** - 工作流程配置
- **`ParameterDefinition`** - 參數定義

### Vite 插件

#### `intellicrawlPlugin(options)`

**選項：**

- `allowedNodeModules` - 允許的 Node.js 模組白名單
  - 物件格式：`{ [moduleName]: true | string[] }`
  - `true` 表示允許整個模組
  - `string[]` 表示只允許指定的匯出

- `transformEmbeddedWorkflow` - 自動轉換模組引用 (預設: `true`)

**範例：**

```typescript
allowedNodeModules: {
  crypto: ['createHash'],  // 只允許 createHash
  url: true,               // 允許整個 url 模組
}
```

### 測試工具

#### `testModule(module, config, options)`

測試模組並返回結果。

#### `MockContextFactory`

建立 Mock 執行環境：

```typescript
import { MockContextFactory } from './tests/mock-context';

const mockContext = MockContextFactory.createDefault({
  taskId: 'test-task',
  config: { /* ... */ },
  mockBrowser: true,
});
```

#### 斷言函數

- `assert(condition, message)` - 基本斷言
- `assertEqual(actual, expected, message)` - 相等斷言
- `assertDefined(value, message)` - 非空斷言

## 🔧 專案結構

建立的專案包含：

```
my-crawler-module/
├── src/
│   ├── index.ts              # 主入口
│   └── modules/
│       └── example.ts        # 範例模組
├── tests/
│   ├── test-helpers.ts       # 測試工具
│   ├── mock-context.ts       # Mock 環境
│   └── example.test.ts       # 測試範例
├── vite.config.ts            # Vite 配置
├── tsconfig.json             # TypeScript 配置
├── package.json              # 專案配置
└── README.md                 # 專案說明
```

## 🤔 常見問題

### 如何使用 Node.js 內建模組？

在 `vite.config.ts` 中配置白名單：

```typescript
allowedNodeModules: {
  crypto: ['createHash', 'randomBytes'],
  url: ['URL'],
}
```

### 如何除錯模組？

1. 使用 `npm run dev` 啟動開發模式
2. 檢查 `dist/bundle.cjs` 的建置輸出
3. 使用測試工具進行單元測試

### 模組打包大小過大？

檢查 `vite.config.ts` 的 `rollupOptions.external`，將大型依賴外部化。

## 📄 授權

MIT License

---

**版本**: 2.0.2
**相容性**: IntelliCrawl ^2.16.0