n8n-nodes-aluvia/README.md

n8n community node for making HTTP requests through Aluvia's mobile connectivity network

# n8n-nodes-aluvia

This is an n8n community node that lets you make HTTP requests through [Aluvia's mobile connectivity network](https://aluvia.io).

Aluvia provides high-quality mobile connectivity, allowing you to send requests from real mobile devices around the world. This node integrates seamlessly with n8n workflows, requiring only your Aluvia Token.![n8n.io - Workflow Automation](https://raw.githubusercontent.com/n8n-io/n8n/master/assets/n8n-logo.png)

## Installation

Follow the [installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) in the n8n community nodes documentation.

1. Go to **Settings > Community Nodes**.
2. Select **Install**.
3. Enter `n8n-nodes-aluvia` as the package name.
4. Agree to the [risks](https://docs.n8n.io/integrations/community-nodes/risks/) of using community nodes: select **I understand the risks of installing unverified code from a public source**.
5. Select **Install**.

After installation, the **Aluvia** node will be available in your n8n instance.

## Credentials

Before using the Aluvia node, you need to configure credentials:

1. **Get an Aluvia Token**:
   - Sign up at [https://aluvia.io](https://aluvia.io)
   - Navigate to your dashboard and copy your token

2. **Configure credentials in n8n**:
   - In n8n, go to **Credentials** and select **Create New**
   - Search for "Aluvia Token" and select it
   - Enter your token from step 1
   - Test the connection and save

## Operations

### Mobile Request

Send HTTP requests through Aluvia's mobile connectivity network.

**Parameters:**

- **Method**: HTTP method (GET, POST, PUT, PATCH, DELETE)
- **URL**: Target URL to send the request to
- **Query Parameters**: Optional URL query parameters
- **Headers**: Optional HTTP headers
- **Body Content Type**: For POST/PUT/PATCH requests (None, JSON, Form URL Encoded)
- **JSON Body**: Request body in JSON format (when Body Content Type is JSON)
- **Form Body**: Request body as form fields (when Body Content Type is Form URL Encoded)
- **Options**:
  - **Timeout**: Request timeout in milliseconds (default: 10000)

## Example Usage

Here's a simple workflow example that demonstrates how to use the Aluvia node:

### Check Your IP Address Through Mobile Connectivity

1. **Add an Aluvia node** to your workflow
2. **Configure the node**:
   - **Resource**: Mobile
   - **Operation**: Mobile Request
   - **Method**: GET
   - **URL**: `https://ipinfo.io/json`
3. **Execute the workflow**

The response will show your IP information, but the IP address will be from Aluvia's mobile network instead of your server's IP.

### API Request Through Mobile Connectivity

1. **Add an Aluvia node** to your workflow
2. **Configure the node**:
   - **Resource**: Mobile
   - **Operation**: Mobile Request
   - **Method**: POST
   - **URL**: `https://api.example.com/data`
   - **Headers**:
     - `Authorization`: `Bearer your-api-key`
     - `Content-Type`: `application/json`
   - **Body Content Type**: JSON
   - **JSON Body**: `{"key": "value"}`

This will send your API request through Aluvia's mobile connectivity network, making it appear to come from a real mobile device.

## Use Cases

- **Web Scraping**: Access websites that block datacenter IPs
- **API Testing**: Test APIs from different mobile networks
- **Geo-location Testing**: Access region-specific content
- **Ad Verification**: Verify ads from different mobile carriers
- **Market Research**: Collect data as if browsing from mobile devices
- **Social Media Automation**: Manage accounts through mobile connectivity

## Response Format

### Successful Requests

For requests with JSON responses:

```json
{
  "data": "response data as JSON object"
}
```

For non-JSON responses:

```json
{
  "statusCode": 200,
  "headers": { "content-type": "text/html" },
  "body": "response body as string"
}
```

### Failed Requests

HTTP error responses are returned with status code and body:

```json
{
  "statusCode": 404,
  "headers": { "content-type": "application/json" },
  "body": "{\"error\": \"Not Found\"}"
}
```

## Error Handling

The node includes comprehensive error handling:

- **Missing Token**: Clear error message directing you to configure credentials
- **Mobile Connectivity Errors**: Detailed error messages when connectivity setup fails
- **HTTP Errors**: Returns error responses with status codes for debugging
- **Timeout Errors**: Configurable timeouts with clear error messages

## Development

This package is built using:

- **TypeScript** for type safety
- **n8n-workflow** for n8n integration
- **aluvia-ts-sdk** for Aluvia API communication
- **got** for HTTP requests
- **proxy-agent** for mobile connectivity support

## Resources

- [Aluvia Documentation](https://www.docs.aluvia.io/)
- [Aluvia TypeScript SDK](https://github.com/aluvia-connect/aluvia-ts-sdk)
- [n8n Community Nodes Documentation](https://docs.n8n.io/integrations/community-nodes/)
- [n8n Node Development](https://docs.n8n.io/integrations/creating-nodes/)

## Support

For issues related to this n8n node:

- Open an issue on [GitHub](https://github.com/aluvia-connect/n8n-nodes-aluvia)

For Aluvia API support:

- Contact [support@aluvia.io](mailto:support@aluvia.io)
- Visit [https://aluvia.io](https://aluvia.io)

## License

MIT License - see the [LICENSE](LICENSE) file for details.