@quartal/bridge-client/docs/URL_TRANSPORT_CONFIG.md

Universal client library for embedding applications with URL-configurable transport support (iframe, postMessage) and framework adapters for Angular and Vue

# URL-Based Transport Configuration

The Quartal Bridge Client supports configuring transport types via URL parameters. This allows parent applications to specify which transport method the embedded child application should use without requiring code changes in the child application.

## Supported URL Parameters

| Parameter      | Type    | Default          | Description                               |
|----------------|---------|------------------|-------------------------------------------|
| `transport`    | string  | `iframe`         | Transport type: `iframe` or `postmessage` |
| `debug`        | boolean | `false`          | Enable debug logging                      |
| `trace`        | boolean | `false`          | Enable trace logging                      |
| `targetOrigin` | string  | `*`              | Target origin for postMessage (security)  |
| `channel`      | string  | `quartal-bridge` | Channel name for postMessage              |
| `timeout`      | number  | `10000`          | Connection timeout in milliseconds        |
| `appPrefix`    | string  | auto             | Prefix for debug messages                 |
| `autoConnect`  | boolean | `true`           | Auto-connect on initialization            |

## Usage Examples

### 1. Iframe Transport (Default)
```html
<!-- Standard iframe embedding -->
<iframe src="https://your-domain.com/quartal-accounting-embed"></iframe>

<!-- With debug enabled -->
<iframe src="https://your-domain.com/quartal-accounting-embed?debug=true"></iframe>
```

### 2. PostMessage Transport
```html
<!-- PostMessage transport for popup windows -->
<iframe src="https://your-domain.com/quartal-accounting-embed?transport=postmessage"></iframe>

<!-- PostMessage with specific target origin (recommended for security) -->
<iframe src="https://your-domain.com/quartal-accounting-embed?transport=postmessage&targetOrigin=https://parent-domain.com"></iframe>
```

### 3. JavaScript Popup Window
```javascript
// Open child app in popup with postMessage transport
const popup = window.open(
  'https://your-domain.com/quartal-invoicing-ui?transport=postmessage&targetOrigin=' + window.location.origin,
  'quartal-invoicing',
  'width=1200,height=800,scrollbars=yes,resizable=yes'
);

// Parent connects using PostMessage transport
const transport = TransportFactory.create('postmessage', {
  targetWindow: popup,
  targetOrigin: 'https://your-domain.com'
});

const parentClient = new ParentClient({
  debug: true,
  appPrefix: 'PARENT'
}, {}, transport);

await parentClient.connect();
```

### 4. Debug Configuration
```html
<!-- Full debug configuration -->
<iframe src="https://your-domain.com/quartal-accounting-embed?transport=postmessage&debug=true&trace=true&channel=my-channel&timeout=15000"></iframe>
```

## Transport Type Comparison

### Iframe Transport
- **Best for**: Standard cross-domain iframe embedding
- **Pros**: 
  - Mature, well-tested
  - Automatic iframe detection
  - Built-in reconnection logic
  - Synchronous connection handling (waits for actual connection)
- **Cons**: 
  - Requires iframe element
  - Limited to iframe embedding

### PostMessage Transport  
- **Best for**: Popup windows, custom windows, same-domain embedding
- **Pros**:
  - Works with any window type
  - Direct postMessage API
  - Fine-grained control
- **Cons**:
  - Manual target window management
  - Requires careful origin validation

## Child Application Integration

Child applications using the Quartal adapters automatically support URL-based transport configuration:

### Vue.js (quartal-accounting-embed)
```typescript
// No code changes needed - automatically uses URL parameters
const adapter = new QuartalVueAdapter(router, userService);
const childClient = adapter.createChildClient({
  appPrefix: 'QA',
  autoConnect: true
}, callbacks);
```

### Angular (quartal-invoicing-ui)  
```typescript
// No code changes needed - automatically uses URL parameters
const adapter = new QuartalAngularAdapter(router, userService);
const childClient = adapter.createChildClient({
  appPrefix: 'Q', 
  autoConnect: true
}, callbacks);
```

## Override URL Configuration

If you need to override URL parameters programmatically:

```typescript
// Bypass URL parsing and use explicit transport
const childClient = adapter.createChildClientWithTransport({
  appPrefix: 'APP',
  autoConnect: true
}, callbacks, 'postmessage', {
  targetOrigin: 'https://specific-parent.com',
  channel: 'custom-channel'
});
```

## Security Considerations

### PostMessage Transport
- Always specify `targetOrigin` instead of using `*` for production
- Validate message origins in production environments
- Use specific channel names to avoid message conflicts

```html
<!-- ✅ Secure -->
<iframe src="https://quartal.com/app?transport=postmessage&targetOrigin=https://your-domain.com"></iframe>

<!-- ❌ Insecure -->
<iframe src="https://quartal.com/app?transport=postmessage"></iframe>
```

## Debugging

Enable debug mode to see transport configuration and message flow:

```html
<iframe src="https://quartal.com/app?debug=true&trace=true"></iframe>
```

Debug output will show:
- Parsed URL configuration
- Transport type selection
- Connection attempts and timing
- Message sending/receiving
- Error details

### Connection Issues

If you experience connection issues (especially with iframe transport), the system includes:
- **Timeout handling**: 10-second connection timeout with clear error messages
- **Dual state checking**: Both internal state and bellhop library state verification
- **Robust error handling**: Detailed error messages for debugging

Common issues:
- **"Iframe transport not connected"**: Usually indicates timing issues between parent and child
- **Connection timeout**: May indicate network issues or incorrect iframe setup
- **Transport not initialized**: Check that the transport is properly configured before connecting