Skip to main content

Integrate with Fetch

Aluvia integrates with fetch by sending HTTP requests through a proxy.

Notes:

  • The Fetch standard does not define a cross-platform proxy option.
  • In Node.js, the most reliable approach is to use Undici (Node's HTTP client) and pass a dispatcher (e.g., ProxyAgent) to fetch.

Recommended (Node.js): use AluviaClient (local proxy) + Undici ProxyAgent​

By default, AluviaClient starts a local proxy on 127.0.0.1. This is the safest/cleanest integration because:

  • No gateway proxy credentials are embedded in your app (the SDK holds them internally).
  • The SDK can do per-hostname routing (direct vs Aluvia) when running the local proxy.
import { AluviaClient } from '@aluvia/sdk';

const client = new AluviaClient({
  apiKey: process.env.ALUVIA_API_KEY!,
  connectionId: process.env.ALUVIA_CONNECTION_ID, // optional
});

const connection = await client.start();

try {
  const res = await fetch('https://ipconfig.io/json', connection.asUndiciFetch());
  if (!res.ok) throw new Error(`Request failed (HTTP ${res.status})`);

  const json = await res.json();
  console.log(json);
} finally {
  await connection.close();
}

Node.js: fetch gateway proxy credentials via AluviaApi, then proxy Fetch via Undici​

If you don’t want to start the SDK’s local proxy process, you can call the Aluvia API directly via the SDK’s API wrapper (AluviaApi) to fetch the proxy username/password for an account connection, then send requests through the Aluvia gateway proxy with those credentials.

Important notes:

  • These calls use /account/... endpoints, so you must use an account API token.
  • The SDK’s gateway host is gateway.aluvia.io. You choose protocol/port (commonly http:8080 or https:8443).
  • Treat proxy credentials as secrets. Don’t log them.
import { fetch, ProxyAgent } from 'undici';
import { AluviaApi } from '@aluvia/sdk';

const apiKey = process.env.ALUVIA_API_KEY!;
const connectionId = process.env.ALUVIA_CONNECTION_ID!;

const api = new AluviaApi({ apiKey });

const accountConn = await api.account.connections.get(connectionId);
if (!accountConn) {
  throw new Error('Connection config was not returned (HTTP 304 Not Modified)');
}

const username = accountConn.proxy_username;
const password = accountConn.proxy_password;
if (!username || !password) {
  throw new Error('API response missing proxy credentials (proxy_username/proxy_password)');
}

// Gateway proxy server (choose protocol/port)
const gatewayProxyServer = 'http://gateway.aluvia.io:8080';

// For basic auth over an HTTP proxy, embed credentials in the proxy URL.
const proxyUrl = new URL(gatewayProxyServer);
proxyUrl.username = username;
proxyUrl.password = password;

const dispatcher = new ProxyAgent(proxyUrl.toString());

const res = await fetch('https://ipconfig.io/json', { dispatcher });
if (!res.ok) throw new Error(`Request failed (HTTP ${res.status})`);

console.log(await res.json());

Raw HTTP examples (JavaScript / Python)​

These examples show how to:

  • send an HTTP request to GET /v1/account/connections/:id
  • extract proxy_username / proxy_password
  • send an HTTP request through Aluvia using those proxy credentials
import { fetch, ProxyAgent } from 'undici';

const apiKey = process.env.ALUVIA_API_KEY;
const connectionId = process.env.ALUVIA_CONNECTION_ID;

if (!apiKey || !connectionId) {
  throw new Error('Missing ALUVIA_API_KEY or ALUVIA_CONNECTION_ID');
}

const res = await fetch(`https://api.aluvia.io/v1/account/connections/${connectionId}`, {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    Accept: 'application/json',
  },
});

if (!res.ok) {
  throw new Error(`Aluvia API request failed (HTTP ${res.status})`);
}

const json = await res.json();
const data = json?.data ?? null;
if (!data) {
  throw new Error('Aluvia API response missing data envelope');
}

const username = data.proxy_username;
const password = data.proxy_password;
if (!username || !password) {
  throw new Error('Aluvia API response missing proxy_username/proxy_password');
}

const gatewayProxyServer = 'http://gateway.aluvia.io:8080';
const proxyUrl = new URL(gatewayProxyServer);
proxyUrl.username = username;
proxyUrl.password = password;

const dispatcher = new ProxyAgent(proxyUrl.toString());

const ipRes = await fetch('https://ipconfig.io/json', { dispatcher });
if (!ipRes.ok) throw new Error(`IP request failed (HTTP ${ipRes.status})`);

console.log(await ipRes.json());