Skip to main content
Version: 4.6.1-saas

API Reference

Complete reference for NetFUNNEL Node.js Agent functions and usage.

Netfunnel Class​

The core class of the Node.js Agent. Used in Express or Nuxt middleware to perform NetFUNNEL queue control.

initialize Method​

Purpose: Initializes the NetFUNNEL agent.

Function Signature:

Netfunnel.initialize(config: NetfunnelConfig): void

Parameters:

ParameterTypeDescription
configNetfunnelConfigNetFUNNEL initialization configuration object

Example:

import { Netfunnel } from 'netfunnel-node-agent';

Netfunnel.initialize({
  clientId: '{{CLIENT_ID}}',
  secretKey: '{{SECRET_KEY}}'
});

Note: Initialization should be performed only once when the server starts. For Express, perform it in app.ts, and for Nuxt, perform it in middleware.

run Method​

Purpose: Executes NetFUNNEL queue control.

Function Signature:

Netfunnel.run(req: IncomingMessage, res: ServerResponse): Promise<boolean>

Parameters:

ParameterTypeDescription
reqIncomingMessageNode.js HTTP request object
resServerResponseNode.js HTTP response object

Return Value: Promise<boolean>

  • true: Request is processed normally and can proceed to the next middleware
  • false: Request is blocked or redirected, so it should not proceed to the next middleware

Behavior:

  1. Trigger rule matching: Compare the URL of the page accessed by the user with trigger rules
  2. When rules match: Request entry to NetFUNNEL server
  3. When waiting response: Automatically redirect to waiting room page (302)
  4. When entry succeeds: Issue key and continue with the request

Example:

// Used in Express middleware
import { Netfunnel } from 'netfunnel-node-agent';

export function netfunnelMiddleware(req, res, next) {
  Netfunnel.run(req, res).then(allowed => {
    if (!allowed) {
      return res.redirect(302, req._nfRedirect || '/');
    }
    next();
  });
}

// Used in Nuxt middleware
import { Netfunnel } from 'netfunnel-node-agent';
import { sendRedirect } from 'h3';

export default defineEventHandler(async event => {
  const allowed = await Netfunnel.run(event.node.req, event.node.res);
  
  if (!allowed) {
    const redirectUrl = (event.node.req as any)._nfRedirect || '/';
    return sendRedirect(event, redirectUrl);
  }
});

getVersion Method​

Purpose: Gets the NetFUNNEL agent version.

Function Signature:

Netfunnel.getVersion(): string

Return Value: string - Agent version string

Example:

import { Netfunnel } from 'netfunnel-node-agent';

console.log('NetFUNNEL Version:', Netfunnel.getVersion());

Operation Flow​

Normal Flow​

  1. User accesses page
  2. Call Netfunnel.run() in middleware
  3. Check trigger rule matching
  4. When rules match, request entry to NetFUNNEL server
  5. When entry is allowed, issue key and continue with request
  6. run() method returns true

Waiting Flow​

  1. User accesses page
  2. Call Netfunnel.run() in middleware
  3. Check trigger rule matching
  4. When rules match, request entry to NetFUNNEL server
  5. Receive waiting response
  6. Automatically redirect to waiting room page (302)
  7. run() method returns false

Blocked Flow​

  1. User accesses page
  2. Call Netfunnel.run() in middleware
  3. Check trigger rule matching
  4. When rules match, request entry to NetFUNNEL server
  5. Receive blocked response
  6. Redirect to blocked page or handle blocking
  7. run() method returns false

Best Practices​

Centralized Configuration​

// config/netfunnel.ts
import { Netfunnel } from 'netfunnel-node-agent';

export function initializeNetfunnel() {
  Netfunnel.initialize({
    clientId: process.env.NETFUNNEL_CLIENT_ID!,
    secretKey: process.env.NETFUNNEL_SECRET_KEY!
  });
}

Environment-Specific Configuration​

import { Netfunnel } from 'netfunnel-node-agent';

Netfunnel.initialize({
  clientId: process.env.NETFUNNEL_CLIENT_ID!,
  secretKey: process.env.NETFUNNEL_SECRET_KEY!,
  printLog: process.env.NODE_ENV === 'development'
});

Error Handling​

export function netfunnelMiddleware(req, res, next) {
  Netfunnel.run(req, res)
    .then(allowed => {
      if (!allowed) {
        return res.redirect(302, req._nfRedirect || '/');
      }
      next();
    })
    .catch(error => {
      console.error('NetFUNNEL error:', error);
      // Continue service even when error occurs
      next();
    });
}