iframe.io 1.0.4 → 1.0.5

package/README.md

@@ -1,2 +1,459 @@
 # iframe.io
-Easy and friendly API to connect and interact between content window and its containing iframe
+
+Easy and friendly API to connect and interact between content window and its containing iframe with enhanced features like heartbeat monitoring, automatic reconnection, message queuing, and rate limiting.
+
+## Features
+
+- 🔄 **Bi-directional Communication** - Seamless messaging between parent window and iframe
+- 💓 **Heartbeat Monitoring** - Automatic connection health checking
+- 🔌 **Auto Reconnection** - Automatic reconnection with exponential backoff
+- 📦 **Message Queuing** - Queue messages when connection is lost
+- 🛡️ **Security** - Origin validation and message sanitization
+- ⚡ **Rate Limiting** - Prevent message flooding
+- 🎯 **Event System** - Robust event-driven architecture
+- ✨ **Promise Support** - Async/await compatible methods
+- 📊 **Connection Stats** - Real-time connection statistics
+
+## Installation
+
+```bash
+npm install iframe.io
+```
+
+## Quick Start
+
+### Parent Window (WINDOW type)
+
+```javascript
+import IOF from 'iframe.io'
+
+// Create iframe and get reference
+const iframe = document.createElement('iframe')
+iframe.src = 'https://example.com/iframe-content'
+document.body.appendChild(iframe)
+
+// Initialize connection
+const iof = new IOF({ type: 'WINDOW', debug: true })
+
+iframe.onload = () => {
+  // Initiate connection with iframe
+  iof.initiate(iframe.contentWindow, 'https://example.com')
+  
+  // Listen for connection
+  iof.on('connect', () => {
+    console.log('Connected to iframe!')
+    
+    // Send message
+    iof.emit('hello', { message: 'Hello from parent!' })
+  })
+  
+  // Listen for messages
+  iof.on('response', (data) => {
+    console.log('Received:', data)
+  })
+}
+```
+
+### Iframe Content (IFRAME type)
+
+```javascript
+import IOF from 'iframe.io'
+
+// Create connection listener
+const iof = new IOF({ type: 'IFRAME', debug: true })
+
+// Listen for parent connection
+iof.listen('https://parent-domain.com')
+
+// Handle connection
+iof.on('connect', () => {
+  console.log('Connected to parent!')
+})
+
+// Listen for messages
+iof.on('hello', (data, ack) => {
+  console.log('Received from parent:', data)
+  
+  // Send response
+  iof.emit('response', { message: 'Hello from iframe!' })
+  
+  // Acknowledge receipt (optional)
+  if (ack) ack(false, 'Message received')
+})
+```
+
+## API Reference
+
+### Constructor
+
+```javascript
+new IOF(options?)
+```
+
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `type` | `'WINDOW' \| 'IFRAME'` | `'IFRAME'` | Connection type |
+| `debug` | `boolean` | `false` | Enable debug logging |
+| `heartbeatInterval` | `number` | `30000` | Heartbeat interval in ms |
+| `connectionTimeout` | `number` | `10000` | Connection timeout in ms |
+| `maxMessageSize` | `number` | `1048576` | Max message size (1MB) |
+| `maxMessagesPerSecond` | `number` | `100` | Rate limit for messages |
+| `autoReconnect` | `boolean` | `true` | Enable auto reconnection |
+| `messageQueueSize` | `number` | `50` | Max queued messages |
+
+### Connection Methods
+
+#### `initiate(contentWindow, iframeOrigin)`
+
+Establish connection with an iframe (WINDOW type only).
+
+```javascript
+iof.initiate(iframe.contentWindow, 'https://iframe-origin.com')
+```
+
+**Parameters:**
+- `contentWindow` - The iframe's contentWindow
+- `iframeOrigin` - The iframe's origin URL
+
+#### `listen(hostOrigin?)`
+
+Listen for connection from parent window (IFRAME type).
+
+```javascript
+iof.listen('https://parent-origin.com') // Optional origin restriction
+```
+
+**Parameters:**
+- `hostOrigin` (optional) - Restrict connections to specific origin
+
+#### `disconnect(callback?)`
+
+Disconnect and clean up all resources.
+
+```javascript
+iof.disconnect(() => {
+  console.log('Disconnected!')
+})
+```
+
+### Messaging Methods
+
+#### `emit(event, payload?, callback?)`
+
+Send a message to the peer.
+
+```javascript
+// Simple message
+iof.emit('myEvent', { data: 'hello' })
+
+// With acknowledgment
+iof.emit('myEvent', { data: 'hello' }, (error, response) => {
+  if (error) {
+    console.error('Error:', error)
+  } else {
+    console.log('Response:', response)
+  }
+})
+
+// Callback as second parameter
+iof.emit('myEvent', (error, response) => {
+  console.log('Response:', response)
+})
+```
+
+#### `on(event, listener)`
+
+Add event listener.
+
+```javascript
+iof.on('myEvent', (data, ack) => {
+  console.log('Received:', data)
+  
+  // Send acknowledgment (optional)
+  if (ack) ack(false, 'Success response')
+})
+```
+
+#### `once(event, listener)`
+
+Add one-time event listener.
+
+```javascript
+iof.once('myEvent', (data) => {
+  console.log('This will only fire once:', data)
+})
+```
+
+#### `off(event, listener?)`
+
+Remove event listener(s).
+
+```javascript
+// Remove specific listener
+iof.off('myEvent', myListener)
+
+// Remove all listeners for event
+iof.off('myEvent')
+```
+
+#### `removeListeners(callback?)`
+
+Remove all event listeners.
+
+```javascript
+iof.removeListeners(() => {
+  console.log('All listeners removed')
+})
+```
+
+### Async Methods
+
+#### `emitAsync(event, payload?)`
+
+Send message and return Promise.
+
+```javascript
+try {
+  const response = await iof.emitAsync('getData', { id: 123 })
+  console.log('Response:', response)
+} catch (error) {
+  console.error('Error:', error)
+}
+```
+
+#### `onceAsync(event)`
+
+Wait for single event occurrence.
+
+```javascript
+const data = await iof.onceAsync('dataReady')
+console.log('Data received:', data)
+```
+
+#### `connectAsync(timeout?)`
+
+Wait for connection to be established.
+
+```javascript
+try {
+  await iof.connectAsync(5000) // 5 second timeout
+  console.log('Connected!')
+} catch (error) {
+  console.error('Connection timeout')
+}
+```
+
+### Utility Methods
+
+#### `isConnected()`
+
+Check if connection is active.
+
+```javascript
+if (iof.isConnected()) {
+  console.log('Connection is active')
+}
+```
+
+#### `getStats()`
+
+Get connection statistics.
+
+```javascript
+const stats = iof.getStats()
+console.log('Stats:', stats)
+/*
+{
+  connected: true,
+  peerType: 'WINDOW',
+  origin: 'https://example.com',
+  lastHeartbeat: 1640995200000,
+  queuedMessages: 0,
+  reconnectAttempts: 0,
+  activeListeners: 5,
+  messageRate: 10
+}
+*/
+```
+
+#### `clearQueue()`
+
+Clear queued messages.
+
+```javascript
+iof.clearQueue()
+```
+
+## Events
+
+### Built-in Events
+
+| Event | Description | Data |
+|-------|-------------|------|
+| `connect` | Connection established | - |
+| `disconnect` | Connection lost | `{ reason: string }` |
+| `reconnecting` | Reconnection attempt | `{ attempt: number, delay: number }` |
+| `reconnection_failed` | All reconnection attempts failed | `{ attempts: number }` |
+| `error` | Error occurred | `{ type: string, ...details }` |
+
+### Error Types
+
+- `RATE_LIMIT_EXCEEDED` - Message rate limit exceeded
+- `MESSAGE_HANDLING_ERROR` - Error processing received message
+- `EMIT_ERROR` - Error sending message
+- `LISTENER_ERROR` - Error in event listener
+- `INVALID_ORIGIN` - Message from unauthorized origin
+- `ORIGIN_MISMATCH` - Origin doesn't match established connection
+- `NO_CONNECTION` - Attempted to send without connection
+
+## Advanced Usage
+
+### Message Acknowledgments
+
+```javascript
+// Sender
+iof.emit('processData', { data: [...] }, (error, result) => {
+  if (error) {
+    console.error('Processing failed:', error)
+  } else {
+    console.log('Processing result:', result)
+  }
+})
+
+// Receiver
+iof.on('processData', async (data, ack) => {
+  try {
+    const result = await processData(data.data)
+    ack(false, result) // Success: ack(error, ...args)
+  } catch (error) {
+    ack(error.message) // Error: ack(errorMessage)
+  }
+})
+```
+
+### Connection Monitoring
+
+```javascript
+const iof = new IOF({
+  heartbeatInterval: 10000, // 10 seconds
+  connectionTimeout: 5000,  // 5 seconds
+  autoReconnect: true
+})
+
+iof.on('disconnect', ({ reason }) => {
+  console.log('Connection lost:', reason)
+})
+
+iof.on('reconnecting', ({ attempt, delay }) => {
+  console.log(`Reconnecting (${attempt}/5) in ${delay}ms`)
+})
+
+iof.on('reconnection_failed', ({ attempts }) => {
+  console.log(`Failed to reconnect after ${attempts} attempts`)
+})
+```
+
+### Message Queuing
+
+```javascript
+const iof = new IOF({
+  messageQueueSize: 100,
+  autoReconnect: true
+})
+
+// Messages sent while disconnected are automatically queued
+iof.emit('queuedMessage', { data: 'This will be queued if disconnected' })
+
+// Check queue status
+const stats = iof.getStats()
+console.log(`Queued messages: ${stats.queuedMessages}`)
+```
+
+### Rate Limiting
+
+```javascript
+const iof = new IOF({
+  maxMessagesPerSecond: 50,
+  maxMessageSize: 512 * 1024 // 512KB
+})
+
+iof.on('error', ({ type, limit, current }) => {
+  if (type === 'RATE_LIMIT_EXCEEDED') {
+    console.log(`Rate limit exceeded: ${current}/${limit} messages per second`)
+  }
+})
+```
+
+### Security Best Practices
+
+```javascript
+// Always specify allowed origins
+iof.listen('https://trusted-parent.com')
+
+// Handle security errors
+iof.on('error', ({ type, expected, received }) => {
+  if (type === 'INVALID_ORIGIN') {
+    console.warn(`Rejected message from ${received}, expected ${expected}`)
+  }
+})
+
+// Validate message content
+iof.on('userData', (data, ack) => {
+  if (!isValidUserData(data)) {
+    return ack('Invalid data format')
+  }
+  // Process valid data...
+})
+```
+
+## Browser Support
+
+- Modern browsers with postMessage API support
+- Chrome 2+
+- Firefox 3+
+- Safari 4+
+- IE 8+
+- Edge (all versions)
+
+## TypeScript Support
+
+The library is written in TypeScript and includes full type definitions:
+
+```typescript
+import IOF, { Options, PeerType, AckFunction, Listener } from 'iframe.io'
+
+const options: Options = {
+  type: 'WINDOW',
+  debug: true,
+  heartbeatInterval: 15000
+}
+
+const iof = new IOF(options)
+
+// Type-safe event handling
+iof.on('myEvent', (data: { message: string }, ack?: AckFunction) => {
+  console.log(data.message)
+  ack?.(false, 'success')
+})
+
+// Type-safe async emissions
+const response = await iof.emitAsync<{ query: string }, { result: any }>('search', { 
+  query: 'typescript' 
+})
+```
+
+## License
+
+MIT License - see LICENSE file for details.
+
+## Contributing
+
+Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.
+
+## Support
+
+- Create an issue on GitHub for bug reports
+- Check existing issues for common problems
+- Review the documentation for usage examples

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "iframe.io",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Easy and friendly API to connect and interact between content window and its containing iframe",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -34,6 +34,12 @@
   },
   "keywords": [
     "realtime",
+    "embeddable",
+    "widget",
+    "components",
+    "micro-frontend",
+    "Secure",
+    "cross-origin",
     "iframe",
     "browser",
     "events",