request-iframe 0.0.1

package/QUICKSTART.CN.md

@@ -0,0 +1,269 @@
+# 快速开始
+
+5 分钟上手 request-iframe，像发送 HTTP 请求一样与 iframe 通信！
+
+## 安装
+
+```bash
+npm install request-iframe
+# 或
+yarn add request-iframe
+```
+
+## 场景说明
+
+假设你有一个父页面需要和嵌入的 iframe 通信：
+
+```
+┌─────────────────────────────────────────┐
+│  父页面 (parent.html)                    │
+│  ┌───────────────────────────────────┐  │
+│  │  iframe (child.html)              │  │
+│  │                                   │  │
+│  │  需要获取 iframe 内的数据           │  │
+│  │                                   │  │
+│  └───────────────────────────────────┘  │
+└─────────────────────────────────────────┘
+```
+
+## Step 1: 父页面创建 Client
+
+```typescript
+// parent.html
+import { requestIframeClient } from 'request-iframe';
+
+// 获取 iframe 元素
+const iframe = document.getElementById('my-iframe') as HTMLIFrameElement;
+
+// 创建 client（用于发送请求）
+const client = requestIframeClient(iframe, { 
+  secretKey: 'my-app'  // 消息隔离标识，需要和 iframe 内保持一致
+});
+
+// 发送请求并等待响应
+async function getUserInfo(userId: number) {
+  const response = await client.send('/api/getUserInfo', { userId });
+  return response.data;
+}
+
+// 使用
+const user = await getUserInfo(123);
+console.log(user); // { name: 'Tom', age: 18 }
+```
+
+## Step 2: iframe 内创建 Server
+
+```typescript
+// child.html (iframe 内)
+import { requestIframeServer } from 'request-iframe';
+
+// 创建 server（用于接收请求）
+const server = requestIframeServer({ 
+  secretKey: 'my-app'  // 必须和父页面的 client 保持一致！
+});
+
+// 注册请求处理器
+server.on('/api/getUserInfo', (req, res) => {
+  const { userId } = req.body;
+  
+  // 模拟从数据库获取用户信息
+  const user = { name: 'Tom', age: 18 };
+  
+  // 返回响应
+  res.send(user);
+});
+```
+
+**就是这么简单！** 🎉
+
+---
+
+## 更多示例
+
+### 异步处理
+
+```typescript
+// Server 端
+server.on('/api/fetchData', async (req, res) => {
+  // 异步操作（如网络请求）
+  const data = await fetch('https://api.example.com/data').then(r => r.json());
+  res.send(data);
+});
+```
+
+当处理器返回 Promise 时，框架会自动：
+1. 通知 Client 这是异步任务
+2. 将超时时间从 5 秒切换到 120 秒
+
+### 错误处理
+
+```typescript
+// Server 端
+server.on('/api/getData', (req, res) => {
+  if (!req.body.id) {
+    return res.status(400).send({ error: '缺少 id 参数' });
+  }
+  res.send({ data: '...' });
+});
+
+// Client 端
+try {
+  const response = await client.send('/api/getData', {});
+} catch (error) {
+  if (error.response?.status === 400) {
+    console.error('参数错误:', error.response.data.error);
+  }
+}
+```
+
+### 添加鉴权
+
+```typescript
+// Server 端添加中间件
+server.use((req, res, next) => {
+  const token = req.headers['authorization'];
+  
+  if (!token || !isValidToken(token)) {
+    return res.status(401).send({ error: '未授权' });
+  }
+  
+  next(); // 继续执行
+});
+
+// Client 端添加请求拦截器
+client.interceptors.request.use((config) => {
+  config.headers = {
+    ...config.headers,
+    'Authorization': `Bearer ${getToken()}`
+  };
+  return config;
+});
+```
+
+### 批量注册接口
+
+```typescript
+server.map({
+  '/api/users/list': (req, res) => {
+    res.send([{ id: 1, name: 'Tom' }, { id: 2, name: 'Jerry' }]);
+  },
+  '/api/users/create': async (req, res) => {
+    const user = await createUser(req.body);
+    res.status(201).send(user);
+  },
+  '/api/users/delete': async (req, res) => {
+    await deleteUser(req.body.id);
+    res.send({ success: true });
+  }
+});
+```
+
+### 文件下载
+
+```typescript
+// Server 端
+server.on('/api/download', async (req, res) => {
+  const content = '这是文件内容';
+  await res.sendFile(content, {
+    mimeType: 'text/plain',
+    fileName: 'example.txt'
+  });
+});
+
+// Client 端
+const response = await client.send('/api/download', {});
+if (response.fileData) {
+  // 创建下载链接
+  const blob = new Blob(
+    [atob(response.fileData.content)], 
+    { type: response.fileData.mimeType }
+  );
+  const url = URL.createObjectURL(blob);
+  
+  // 触发下载
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = response.fileData.fileName || 'download';
+  a.click();
+}
+```
+
+### 调试模式
+
+开启 trace 模式查看详细日志：
+
+```typescript
+const client = requestIframeClient(iframe, { 
+  secretKey: 'my-app',
+  trace: true  // 开启调试日志
+});
+
+const server = requestIframeServer({ 
+  secretKey: 'my-app',
+  trace: true
+});
+```
+
+控制台会输出：
+```
+[request-iframe] [INFO] 📤 Request Start { path: '/api/getData', body: {...} }
+[request-iframe] [INFO] 📨 ACK Received { requestId: 'req_xxx' }
+[request-iframe] [INFO] ✅ Request Success { status: 200, data: {...} }
+```
+
+---
+
+## 常见问题
+
+### Q: 为什么请求一直超时？
+
+检查以下几点：
+1. iframe 是否已加载完成
+2. Client 和 Server 的 `secretKey` 是否一致
+3. Server 的处理器路径是否正确
+
+### Q: 如何在 iframe 内向父页面发送请求？
+
+```typescript
+// iframe 内
+const client = requestIframeClient(window.parent, { secretKey: 'reverse' });
+await client.send('/notify', { event: 'ready' });
+
+// 父页面
+const server = requestIframeServer({ secretKey: 'reverse' });
+server.on('/notify', (req, res) => {
+  console.log('iframe 已就绪');
+  res.send({ ok: true });
+});
+```
+
+### Q: 支持 TypeScript 吗？
+
+完全支持！所有 API 都有完整的类型定义。
+
+```typescript
+import { 
+  requestIframeClient, 
+  requestIframeServer,
+  Response,
+  ServerRequest,
+  ServerResponse 
+} from 'request-iframe';
+
+// 泛型支持
+interface User {
+  id: number;
+  name: string;
+}
+
+const response = await client.send<User>('/api/user', { id: 1 });
+console.log(response.data.name); // TypeScript 知道这是 string
+```
+
+---
+
+## 下一步
+
+- 查看 [README.CN.md](./README.CN.md) 了解完整 API（中文）
+- 查看 [README.md](./README.md) 了解完整 API（English）
+- 查看 [src/__tests__](./src/__tests__) 目录下的测试用例获取更多示例

package/QUICKSTART.md

@@ -0,0 +1,269 @@
+# Quick Start
+
+Get started with request-iframe in 5 minutes - communicate with iframes like sending HTTP requests!
+
+## Installation
+
+```bash
+npm install request-iframe
+# or
+yarn add request-iframe
+```
+
+## Scenario
+
+Suppose you have a parent page that needs to communicate with an embedded iframe:
+
+```
+┌─────────────────────────────────────────┐
+│  Parent Page (parent.html)                │
+│  ┌───────────────────────────────────┐  │
+│  │  iframe (child.html)               │  │
+│  │                                    │  │
+│  │  Need to get data from iframe      │  │
+│  │                                    │  │
+│  └───────────────────────────────────┘  │
+└─────────────────────────────────────────┘
+```
+
+## Step 1: Create Client in Parent Page
+
+```typescript
+// parent.html
+import { requestIframeClient } from 'request-iframe';
+
+// Get iframe element
+const iframe = document.getElementById('my-iframe') as HTMLIFrameElement;
+
+// Create client (for sending requests)
+const client = requestIframeClient(iframe, { 
+  secretKey: 'my-app'  // Message isolation identifier, must match iframe
+});
+
+// Send request and wait for response
+async function getUserInfo(userId: number) {
+  const response = await client.send('/api/getUserInfo', { userId });
+  return response.data;
+}
+
+// Use
+const user = await getUserInfo(123);
+console.log(user); // { name: 'Tom', age: 18 }
+```
+
+## Step 2: Create Server in iframe
+
+```typescript
+// child.html (inside iframe)
+import { requestIframeServer } from 'request-iframe';
+
+// Create server (for receiving requests)
+const server = requestIframeServer({ 
+  secretKey: 'my-app'  // Must match parent page's client!
+});
+
+// Register request handler
+server.on('/api/getUserInfo', (req, res) => {
+  const { userId } = req.body;
+  
+  // Simulate fetching user info from database
+  const user = { name: 'Tom', age: 18 };
+  
+  // Return response
+  res.send(user);
+});
+```
+
+**That's it!** 🎉
+
+---
+
+## More Examples
+
+### Async Processing
+
+```typescript
+// Server side
+server.on('/api/fetchData', async (req, res) => {
+  // Async operation (like network request)
+  const data = await fetch('https://api.example.com/data').then(r => r.json());
+  res.send(data);
+});
+```
+
+When the handler returns a Promise, the framework automatically:
+1. Notifies Client this is an async task
+2. Switches timeout from 5 seconds to 120 seconds
+
+### Error Handling
+
+```typescript
+// Server side
+server.on('/api/getData', (req, res) => {
+  if (!req.body.id) {
+    return res.status(400).send({ error: 'Missing id parameter' });
+  }
+  res.send({ data: '...' });
+});
+
+// Client side
+try {
+  const response = await client.send('/api/getData', {});
+} catch (error) {
+  if (error.response?.status === 400) {
+    console.error('Parameter error:', error.response.data.error);
+  }
+}
+```
+
+### Add Authentication
+
+```typescript
+// Server side: Add middleware
+server.use((req, res, next) => {
+  const token = req.headers['authorization'];
+  
+  if (!token || !isValidToken(token)) {
+    return res.status(401).send({ error: 'Unauthorized' });
+  }
+  
+  next(); // Continue execution
+});
+
+// Client side: Add request interceptor
+client.interceptors.request.use((config) => {
+  config.headers = {
+    ...config.headers,
+    'Authorization': `Bearer ${getToken()}`
+  };
+  return config;
+});
+```
+
+### Batch Register Interfaces
+
+```typescript
+server.map({
+  '/api/users/list': (req, res) => {
+    res.send([{ id: 1, name: 'Tom' }, { id: 2, name: 'Jerry' }]);
+  },
+  '/api/users/create': async (req, res) => {
+    const user = await createUser(req.body);
+    res.status(201).send(user);
+  },
+  '/api/users/delete': async (req, res) => {
+    await deleteUser(req.body.id);
+    res.send({ success: true });
+  }
+});
+```
+
+### File Download
+
+```typescript
+// Server side
+server.on('/api/download', async (req, res) => {
+  const content = 'This is file content';
+  await res.sendFile(content, {
+    mimeType: 'text/plain',
+    fileName: 'example.txt'
+  });
+});
+
+// Client side
+const response = await client.send('/api/download', {});
+if (response.fileData) {
+  // Create download link
+  const blob = new Blob(
+    [atob(response.fileData.content)], 
+    { type: response.fileData.mimeType }
+  );
+  const url = URL.createObjectURL(blob);
+  
+  // Trigger download
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = response.fileData.fileName || 'download';
+  a.click();
+}
+```
+
+### Debug Mode
+
+Enable trace mode to view detailed logs:
+
+```typescript
+const client = requestIframeClient(iframe, { 
+  secretKey: 'my-app',
+  trace: true  // Enable debug logs
+});
+
+const server = requestIframeServer({ 
+  secretKey: 'my-app',
+  trace: true
+});
+```
+
+Console will output:
+```
+[request-iframe] [INFO] 📤 Request Start { path: '/api/getData', body: {...} }
+[request-iframe] [INFO] 📨 ACK Received { requestId: 'req_xxx' }
+[request-iframe] [INFO] ✅ Request Success { status: 200, data: {...} }
+```
+
+---
+
+## Common Questions
+
+### Q: Why does the request keep timing out?
+
+Check the following:
+1. Is the iframe fully loaded?
+2. Do Client and Server have the same `secretKey`?
+3. Is the Server handler path correct?
+
+### Q: How to send requests from iframe to parent page?
+
+```typescript
+// Inside iframe
+const client = requestIframeClient(window.parent, { secretKey: 'reverse' });
+await client.send('/notify', { event: 'ready' });
+
+// Parent page
+const server = requestIframeServer({ secretKey: 'reverse' });
+server.on('/notify', (req, res) => {
+  console.log('iframe is ready');
+  res.send({ ok: true });
+});
+```
+
+### Q: Does it support TypeScript?
+
+Fully supported! All APIs have complete type definitions.
+
+```typescript
+import { 
+  requestIframeClient, 
+  requestIframeServer,
+  Response,
+  ServerRequest,
+  ServerResponse 
+} from 'request-iframe';
+
+// Generic support
+interface User {
+  id: number;
+  name: string;
+}
+
+const response = await client.send<User>('/api/user', { id: 1 });
+console.log(response.data.name); // TypeScript knows this is string
+```
+
+---
+
+## Next Steps
+
+- View [README.md](./README.md) for complete API documentation (English)
+- View [README.CN.md](./README.CN.md) for complete API documentation (中文)
+- Check [src/__tests__](./src/__tests__) directory for more examples from test cases