Skip to content

API.md

Latest commit

 

History

History
237 lines (178 loc) · 9.22 KB

API.md

File metadata and controls

237 lines (178 loc) · 9.22 KB

AutoWebhook API Reference

This document provides detailed information about the configuration, methods, and events for the AutoWebhook library.

Installation

npm install autowebhook
# or
bun add autowebhook

Quick Start

import { AutoWebhook } from 'autowebhook';

const webhook = new AutoWebhook({
  tunnels: [{ name: 'my-app', provider: 'ngrok', port: 3000 }]
});

const [url] = await webhook.start();
console.log('✨ Your webhook is ready:', url);

Configuration

You configure AutoWebhook by passing a configuration object to its constructor. The main component is the tunnels array, which defines all the tunnels you want to create.

import { AutoWebhook } from 'autowebhook';

const config = {
  // Default port for all tunnels if not specified individually
  port: 8080,

  // Array of tunnels to create
  tunnels: [
    {
      name: 'primary-ngrok', // A unique name for this tunnel
      provider: 'ngrok',
      port: 8081, // Override default port
      ngrok: { // ngrok-specific settings
        region: 'eu',
        subdomain: 'my-cool-bot', // Requires a paid ngrok plan
        auth: 'YOUR_NGROK_AUTHTOKEN',
      }
    },
    {
      name: 'backup-lhr',
      provider: 'localhost.run',
      port: 8082,
    }
  ],

  // Health check settings for all tunnels
  healthCheck: {
    enabled: true,
    interval: 20000,
    timeout: 10000,
    maxFailures: 3, // Attempts before restarting a tunnel
  },
  
  // Enable expanded logging for debugging
  expanded: false,
};

const webhook = new AutoWebhook(config);
const urls = await webhook.start();
console.log('Tunnels are ready:', urls);

AutoWebhookConfig

Field Type Default Description
tunnels TunnelConfig[] [] Required. An array of tunnel configurations to create.
port number 3000 A default port for all tunnels if not specified in the tunnel's config.
healthCheck HealthCheckConfig {...} Global health check settings applied to all tunnels.
expanded boolean false Enable detailed debug logging for all tunnels.
onError (error: Error) => void () => {} Callback for handling global errors that occur outside a specific tunnel.

TunnelConfig

This object defines a single tunnel to be managed by AutoWebhook.

Field Type Default Description
name string - Required. A unique name to identify the tunnel in events and status logs.
provider 'ngrok' | 'localhost.run' - Required. The tunneling service to use.
port number Inherits from global port The local port for this specific tunnel to expose.
ngrok NgrokTunnelConfig {} An object with ngrok-specific settings. See NgrokTunnelConfig below.

NgrokTunnelConfig

This object provides detailed configuration for tunnels using ngrok as the provider.

Field Type Default Description
proto 'http' | 'tcp' | 'tls' 'http' The protocol to tunnel (http, tcp, or tls).
region 'us' | 'eu' | 'ap' | 'au' | 'sa' | 'jp' | 'in' - The ngrok datacenter region to use.
subdomain string - A custom subdomain for your tunnel (requires a paid ngrok plan).
hostname string - A custom hostname for your tunnel (requires a paid ngrok plan).
auth string - Your ngrok authtoken.
basic_auth string - Protect the tunnel with a username and password (e.g., 'user:password').
allow_cidr string | string[] - A single CIDR or a list of CIDRs to whitelist for access to the tunnel.
command string - A raw ngrok command string to execute. If provided, it overrides all other ngrok settings like proto or port.

API Methods

webhook.start(): Promise<string[]>

Starts all tunnels defined in the tunnels configuration array. Returns a Promise that resolves with an array of the public URLs.

Example:

const urls = await webhook.start();
console.log('Available tunnels:', urls);
// Output: ['https://abc123.ngrok.io', 'https://random-id.lhr.life']

webhook.stop(): Promise<void>

Stops all active tunnels and their health checkers.

Example:

await webhook.stop();
console.log('All tunnels stopped');

webhook.getUrls(): string[]

Returns an array of the currently active public URLs for all managed tunnels.

Example:

const activeUrls = webhook.getUrls();
console.log('Currently active:', activeUrls);

webhook.getStatus()

Returns an object containing the detailed status of all managed tunnels, including their running state, URL, provider, restart attempts, and health status.

Example:

const status = webhook.getStatus();
console.log('Tunnel status:', JSON.stringify(status, null, 2));

Events

The AutoWebhook instance is an EventEmitter and emits the following events to allow you to react to the lifecycle of each tunnel:

tunnelReady (name: string, url: string)

Emitted when a tunnel is successfully started and its public URL is retrieved.

tunnelDown (name: string, error: Error)

Emitted when a tunnel fails its health check and is about to be restarted.

error (error: Error)

Emitted when a global error occurs that isn't specific to one tunnel (e.g., failure to start all tunnels).

Example usage:

webhook.on('tunnelReady', (name, url) => {
  console.log(`✅ Tunnel "${name}" is ready at: ${url}`);
});

webhook.on('tunnelDown', (name, error) => {
  console.warn(`⚠️ Tunnel "${name}" went down: ${error.message}`);
});

webhook.on('error', (error) => {
  console.error('❌ Global error:', error);
});

Environment Variables

AutoWebhook supports configuration through environment variables:

Variable Description Default
AUTOWEBHOOK_PORT Default port for all tunnels 3000
AUTOWEBHOOK_NGROK_AUTH ngrok authentication token -
AUTOWEBHOOK_NGROK_REGION Default region for ngrok tunnels us
AUTOWEBHOOK_EXPANDED Enable expanded logging false
AUTOWEBHOOK_HEALTH_CHECK Enable/disable health checks true

Example usage:

# .env
AUTOWEBHOOK_PORT=8080
AUTOWEBHOOK_NGROK_AUTH=your_ngrok_token
AUTOWEBHOOK_EXPANDED=true

TypeScript Support

AutoWebhook v3.0+ includes full TypeScript definitions out of the box. All configuration objects and method return types are properly typed.

import type { AutoWebhookConfig, TunnelConfig } from 'autowebhook';

const config: AutoWebhookConfig = {
  tunnels: [
    {
      name: 'my-tunnel',
      provider: 'ngrok', // TypeScript will validate this
      port: 3000
    }
  ]
};

Migration from v2.x

Breaking Changes in v3.0

  1. Package format changed: Now published as compiled JavaScript with TypeScript definitions
  2. Dual module support: Both ESM and CommonJS are supported
  3. Import path remains the same: import { AutoWebhook } from 'autowebhook'

No code changes required

Your existing code will work without modifications. The API remains the same, only the package distribution format changed.

// This still works exactly the same
import { AutoWebhook } from 'autowebhook';

const webhook = new AutoWebhook({
  tunnels: [{ name: 'test', provider: 'ngrok', port: 3000 }]
});