Smee Client

Common errors

• TypeError: smee.start is not a function

  cause Attempting to call `smee.start()` without `await` in an asynchronous context after v5.0.0.
  fix Change the calling code to `await smee.start();`. Ensure the surrounding function is `async`.

• Error: Missing URL / Error: Invalid Smee URL

  cause The `source` option provided to `new SmeeClient()` is either missing, an empty string, or not a valid `https://smee.io/your-channel` format.
  fix Verify that the `source` property is a complete and valid Smee.io channel URL, including the protocol and a unique path. Obtain a fresh URL from https://smee.io/ if unsure.

Warnings

• breaking The `Client#start()` method is now an asynchronous function and must be awaited. Previously, it was synchronous.
  Fix: Ensure that calls to `smee.start()` are prefixed with `await`. For example: `await smee.start();`
• gotcha Features such as connection timeout, `startForward`/`stopForward` methods, and the `query-forwarding` option, which were introduced in versions like `v4.2.0` and `v4.4.0`, were subsequently reverted in `v4.4.2`. Users upgrading from `v4.2.0` or `v4.4.0` might find these functionalities unexpectedly removed in later `v4.x` releases.
  Fix: Refer to the specific version's changelog or documentation to confirm feature availability. If a desired feature was reverted, consider upgrading to v5.x if it has been re-implemented or find an alternative approach.

Install

• npm install smee-client npm
• yarn add smee-client yarn
• pnpm add smee-client pnpm

Imports

• SmeeClient
  wrong:

  const SmeeClient = require('smee-client')

  correct:

  import { SmeeClient } from 'smee-client'

  The library primarily uses named exports. `require` is not recommended for modern Node.js and TypeScript environments.
• SmeeClient

  import type { SmeeClientOptions } from 'smee-client'

  Import types separately for type-checking without bundling.
• SmeeClient
  wrong:

  import SmeeClient from 'smee-client'

  correct:

  import { Client as SmeeClient } from 'smee-client'

  While `Client` is the internal class name, `SmeeClient` is the recommended named export. There is no default export.

Quickstart

This quickstart initializes a SmeeClient to forward webhooks from a smee.io channel to a local endpoint, demonstrating its asynchronous start method and event listening.

import { SmeeClient } from 'smee-client';

async function runSmeeClient() {
  // Replace with your unique smee.io URL, e.g., from https://smee.io/
  // It's highly recommended to set this via an environment variable.
  const smeeUrl = process.env.SMEE_URL || 'https://smee.io/your-unique-channel-id';

  if (smeeUrl === 'https://smee.io/your-unique-channel-id') {
    console.warn('Warning: Using a placeholder Smee URL. Please set SMEE_URL environment variable or update the code.');
    console.warn('Get your unique channel URL from https://smee.io/.');
  }

  const smee = new SmeeClient({
    source: smeeUrl,
    target: 'http://localhost:3000/webhook', // Your local development server endpoint
    logger: console,
  });

  console.log(`Forwarding webhooks from ${smeeUrl} to http://localhost:3000/webhook`);

  try {
    // Client#start() is now an async function since v5.0.0
    const events = await smee.start();
    console.log('Smee client started. Waiting for events...');

    events.on('message', (message) => {
      console.log('Received webhook message:', message.url);
      // message contains 'headers', 'body', 'url', 'query', etc.
    });

    events.on('error', (error) => {
      console.error('Smee client encountered an error:', error);
    });

    events.on('close', () => {
      console.log('Smee client connection closed.');
    });

    // Example: Stop the client after a minute (optional)
    // setTimeout(() => {
    //   events.close();
    //   console.log('Smee client stopped after 1 minute.');
    // }, 60 * 1000);

  } catch (error) {
    console.error('Failed to start Smee client:', error);
  }
}

runSmeeClient();