### Quickstart: Establish ngrok tunnel to localhost:8080

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

This example establishes a tunnel to localhost on port 8080 using the authtoken from environment variables. It outputs the ngrok URL to the console.

```javascript
// Require ngrok javascript sdk
const ngrok = require("@ngrok/ngrok");
// import ngrok from '@ngrok/ngrok' // if inside a module

(async function() {
  // Establish connectivity
  const listener = await ngrok.forward({ addr: 8080, authtoken_from_env: true });

  // Output ngrok url to console
  console.log(`Ingress established at: ${listener.url()}`);
})();

process.stdin.resume();

```

--------------------------------

### Clone and Run ngrok-javascript Examples

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

Use npx degit to clone an example directory from the ngrok-javascript repository. After cloning, navigate into the directory and install dependencies using npm i.

```bash
npx degit github:ngrok/ngrok-javascript/examples/<example> <folder-name>
cd <folder-name>
npm i
```

```bash
npx degit github:ngrok/ngrok-javascript/examples/express express && cd express && npm i
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/vue/README.md

Run this command to install all necessary project dependencies.

```sh
npm install
```

--------------------------------

### Full ngrok.forward Configuration

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

This snippet demonstrates all possible configuration items for ngrok.forward. It covers session, listener, and module-specific configurations. Ensure you have the necessary ngrok setup and potentially ngrok-javascript installed.

```javascript
const listener = await ngrok.forward({
  // session configuration
  addr: `localhost:8080`, // or `8080` or `unix:${UNIX_SOCKET}`
  authtoken: "<authtoken>",
  authtoken_from_env: true,
  onStatusChange: (status) => {
    console.log(`Ngrok status changed: ${status}`);
  },
  session_metadata: "Online in One Line",
  // advanced session connection configuration
  server_addr: "example.com:443",
  root_cas: "trusted",
  session_ca_cert: fs.readFileSync("ca.pem", "utf8"),  
  // listener configuration
  metadata: "example listener metadata from javascript",
  domain: "<domain>",
  proto: "http",
  proxy_proto: "", // One of: "", "1", "2"
  schemes: ["HTTPS"],
  labels: "edge:edghts_2G...",  // Along with proto="labeled"
  app_protocol: "http2",
  // module configuration
  basic_auth: ["ngrok:online1line"],
  circuit_breaker: 0.1,
  compression: true,
  allow_user_agent: "^mozilla.*",
  deny_user_agent: "^curl.*",
  ip_restriction_allow_cidrs: ["0.0.0.0/0"],
  ip_restriction_deny_cidrs: ["10.1.1.1/32"],
  crt: fs.readFileSync("crt.pem", "utf8"),
  key: fs.readFileSync("key.pem", "utf8"),
  mutual_tls_cas: [fs.readFileSync('ca.crt', 'utf8')],
  oauth_provider: "google",
  oauth_allow_domains: ["<domain>"],
  oauth_allow_emails: ["<email>"],
  oauth_scopes: ["<scope>"],
  oauth_client_id: "<id>",
  oauth_client_secret: "<secret>",
  oidc_issuer_url: "<url>",
  oidc_client_id: "<id>",
  oidc_client_secret: "<secret>",
  oidc_allow_domains: ["<domain>"],
  oidc_allow_emails: ["<email>"],
  oidc_scopes: ["<scope>"],
  traffic_policy: "<policy_json>",
  request_header_remove: ["X-Req-Nope"],
  response_header_remove: ["X-Res-Nope"],
  request_header_add: ["X-Req-Yup:true"],
  response_header_add: ["X-Res-Yup:true"],
  verify_upstream_tls: false,
  verify_webhook_provider: "twilio",
  verify_webhook_secret: "asdf",
  websocket_tcp_converter: true,
});
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/nestjs/README.md

Installs all necessary project dependencies using Yarn.

```bash
yarn install
```

--------------------------------

### Example Ngrok Output

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/nextjs/README.md

This is an example of the output you might see when running the Next.js development server with ngrok configured.

```bash
> node_modules/.bin/next
ready - started server on 0.0.0.0:3000, url: http://localhost:3000
warn  - Detected next.config.js, no exported configuration found. https://nextjs.org/docs/messages/empty-configuration
event - compiled client and server successfully in 210 ms (154 modules)
Forwarding to: localhost:3000 from ingress at: https://04d4d919d236.ngrok.app
```

--------------------------------

### Start Remix Production Server

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/remix/REMIX-README.md

Run this command after building the production version of your app to start the Remix app server in production mode.

```sh
npm start
```

--------------------------------

### Starting an ngrok Listener

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/index.html

The `forward` method is the primary way to start an ngrok session and establish a listener. It returns a promise that resolves to the public URL of the listener. It can be configured with various options to customize the connection.

```APIDOC
## forward()

### Description
Starts an ngrok session and establishes a listener to a specified address. Returns a promise that resolves to the public URL of the listener.

### Method
`forward(options?: ForwardOptions | string | number): Promise<Listener> `

### Parameters
#### Options (`ForwardOptions`)
- **addr** (string | number) - The address to forward to. Defaults to `localhost:80` if not specified.
- **proto** (string) - The listener type. Defaults to `http`. Use `tcp` for TCP listeners.
- **basic_auth** (string) - Basic authentication credentials in the format `username:password`.
- **oauth_provider** (string) - The OAuth provider to use (e.g., `google`).
- **oauth_allow_domains** (string) - Comma-separated list of domains allowed for OAuth.

### Request Example
```javascript
const ngrok = require("@ngrok/ngrok");

// Default HTTP listener to localhost:80
(async function() {
  console.log( (await ngrok.forward()).url() );
})();

// Forward to a specific port
const listener = await ngrok.forward(4242);

// Forward to a specific host and port
const listener = await ngrok.forward("localhost:4242");

// With advanced options
const listener = await ngrok.forward({ addr: 8080, basic_auth: "ngrok:online1line" });
const listener = await ngrok.forward({ addr: 8080, oauth_provider: "google", oauth_allow_domains: "example.com" });

// TCP listener
const listener = await ngrok.forward({ proto: 'tcp', addr: 25565 });
```

### Response
#### Success Response
A `Listener` object with a `url()` method to get the public URL.
```

--------------------------------

### Start TCP Listener

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/index.html

Starts an ngrok session and establishes a TCP listener on a specified port. The 'proto' option is set to 'tcp' and the 'addr' option specifies the port.

```javascript
const listener = await ngrok.forward({ proto: 'tcp', addr: 25565 });

```

--------------------------------

### Start HTTP Listener with OAuth

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/index.html

Starts an ngrok session and establishes an HTTP listener with OAuth integration for Google. The 'addr', 'oauth_provider', and 'oauth_allow_domains' options are provided in an object to the forward method.

```javascript
const listener = await ngrok.forward({ addr: 8080, oauth_provider: "google", oauth_allow_domains: "example.com" });

```

--------------------------------

### Run Next.js Development Server

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/nextjs/README.md

Execute this command to start the Next.js development server.

```bash
node_modules/.bin/next
```

--------------------------------

### Install ngrok-javascript with npm

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

Use npm to add the ngrok JavaScript SDK to your project.

```shell
npm install @ngrok/ngrok
```

--------------------------------

### Start HTTP Listener with Basic Authentication

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/index.html

Starts an ngrok session and establishes an HTTP listener with basic authentication enabled. The 'addr' and 'basic_auth' options are provided in an object to the forward method.

```javascript
const listener = await ngrok.forward({ addr: 8080, basic_auth: "ngrok:online1line" });

```

--------------------------------

### Start Svelte development server

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/svelte/README.md

Run the development server for your Svelte project. The `-- --open` flag will automatically open the app in your browser.

```bash
npm run dev
```

```bash
npm run dev -- --open
```

--------------------------------

### listen

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/LabeledListenerBuilder.html

Starts listening for new connections on this listener.

```APIDOC
## listen

### Description
Begin listening for new connections on this listener.

### Parameters
#### Parameters
- **bind** (null | boolean) - Optional parameter to control binding.

### Returns
Promise<[Listener](Listener.html)>
```

--------------------------------

### listenAndServe

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/LabeledListenerBuilder.html

Starts listening and forwards incoming connections to a given server object.

```APIDOC
## listenAndServe

### Description
Begin listening for new connections on this listener and forwarding them to the given server. This method will also set the `forwardsTo` value.

### Parameters
#### Parameters
- **server** (any) - The server object to forward connections to.

### Returns
Promise<[Listener](Listener.html)>
```

--------------------------------

### Start HTTP Listener to a Specific Host and Port

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/index.html

Starts an ngrok session and establishes an HTTP listener to a specified host and port. The host and port are provided as a string argument to the forward method.

```javascript
const listener = await ngrok.forward("localhost:4242");

```

--------------------------------

### Session Constructor

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/Session.html

Initializes a new ngrok session. This is the primary way to start an ngrok session.

```APIDOC
## new Session()

### Description
Initializes a new ngrok session.

### Returns
- **Session** - A new Session object.
```

--------------------------------

### listenAndForward

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/LabeledListenerBuilder.html

Starts listening and forwards incoming connections to a specified URL.

```APIDOC
## listenAndForward

### Description
Begin listening for new connections on this listener and forwarding them to the given url. This method will also set the `forwardsTo` value.

### Parameters
#### Parameters
- **toUrl** (string) - The URL to forward connections to.

### Returns
Promise<[Listener](Listener.html)>
```

--------------------------------

### Start HTTP Listener to a Specific Port

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/index.html

Starts an ngrok session and establishes an HTTP listener to localhost on a specified port. The port number is passed as an argument to the forward method.

```javascript
const listener = await ngrok.forward(4242);

```

--------------------------------

### Install ngrok-javascript with pnpm

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

Use pnpm to add the ngrok JavaScript SDK to your project.

```shell
pnpm add @ngrok/ngrok
```

--------------------------------

### Install ngrok-javascript with yarn

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

Use yarn to add the ngrok JavaScript SDK to your project.

```shell
yarn add @ngrok/ngrok
```

--------------------------------

### Run NestJS Application

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/nestjs/README.md

Starts the NestJS application in development mode.

```bash
yarn run start
```

--------------------------------

### Create a Minimal HTTP Listener with Builder

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

Use the SessionBuilder to establish a connection and then create an HTTP listener. This example forwards traffic to localhost:8081.

```jsx
async function create_listener() {
  const session = await new ngrok.SessionBuilder().authtokenFromEnv().connect();
  const listener = await session.httpEndpoint().listen();
  console.log("Ingress established at:", listener.url());
  listener.forward("localhost:8081");
}
```

--------------------------------

### listen

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/TcpListenerBuilder.html

Starts listening for new connections on this listener. Optionally, a boolean can be provided to control binding behavior.

```APIDOC
## listen

### Description
Begin listening for new connections on this listener.

### Parameters
#### Path Parameters
* **bind** (null | boolean) - Optional - Description: Controls binding behavior.

### Returns
Promise<[Listener](Listener.html)>
```

--------------------------------

### listen

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/functions/listen.html

Starts the given net.Server listening to a generated, or passed in, listener. It uses the NGROK_AUTHTOKEN environment variable to authenticate if a new listener is created.

```APIDOC
## listen

### Description
Starts the given net.Server listening to a generated, or passed in, listener. Uses the NGROK_AUTHTOKEN environment variable to authenticate if a new listener is created.

### Method
listen

### Parameters
#### Parameters
* server: Server
* `Optional` listener: Listener

### Returns
[Listener]

### Defined in
[index.d.ts:963](https://github.com/ngrok/ngrok-javascript/blob/bc870a65c82af0d8c0036b17907b0f96d12a0cb9/index.d.ts#L963)
```

--------------------------------

### Checkout and Pull Main Branch

Source: https://github.com/ngrok/ngrok-javascript/blob/main/RELEASE.md

Before starting a release, ensure you are on the main branch and have the latest changes pulled.

```bash
git checkout main; git pull origin main
```

--------------------------------

### Connection: Default forward to localhost:80

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

Start an HTTP listener to localhost port 80 with no arguments. The forward method returns a promise that resolves to the public URL of the listener.

```javascript
const ngrok = require("@ngrok/ngrok");
// import ngrok from '@ngrok/ngrok' // if inside a module

(async function() {
  console.log( (await ngrok.forward()).url() );
})();

```

--------------------------------

### labels()

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/Listener.html

Returns the labels that were applied when this listener was started.

```APIDOC
## labels()

### Description
The labels this listener was started with.

### Returns
* Record<string, string> - An object containing the labels applied to the listener.
```

--------------------------------

### Create Listener using NgrokSessionBuilder

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/index.html

A minimal example demonstrating the use of NgrokSessionBuilder to create a session and an HTTP endpoint listener. It forwards traffic to localhost:8081.

```javascript
async function create_listener() {
  const session = await new ngrok.NgrokSessionBuilder().authtokenFromEnv().connect();
  const listener = await session.httpEndpoint().listen();
  console.log("Ingress established at:", listener.url());
  listener.forward("localhost:8081");
}

```

--------------------------------

### Run NestJS Application in Production Mode

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/nestjs/README.md

Starts the NestJS application in production mode.

```bash
yarn run start:prod
```

--------------------------------

### Handle Asynchronous Errors with Promises

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

Demonstrates error handling for session and listener setup using promise chaining with .then() and .catch().

```jsx
await new ngrok.SessionBuilder().authtokenFromEnv().connect()
    .then((session) => {
        session.httpEndpoint().listen()
            .then((tun) => {}) // Listener setup successful
            .catch(err => console.log('listener setup error: ' + err))
    })
    .catch(err => console.log('session setup error: ' + err));
```

--------------------------------

### listenable()

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/functions/listenable.html

Get a listenable ngrok listener, suitable for passing to net.Server.listen(). Uses the NGROK_AUTHTOKEN environment variable to authenticate.

```APIDOC
## listenable()

### Description
Get a listenable ngrok listener, suitable for passing to net.Server.listen(). Uses the NGROK_AUTHTOKEN environment variable to authenticate.

### Returns
[Listener](../classes/Listener.html)[]

### Defined in
[index.d.ts:958](https://github.com/ngrok/ngrok-javascript/blob/bc870a65c82af0d8c0036b17907b0f96d12a0cb9/index.d.ts#L958)
```

--------------------------------

### Build and Document Project

Source: https://github.com/ngrok/ngrok-javascript/blob/main/RELEASE.md

Build the project and generate documentation. Ensure both steps complete successfully.

```bash
yarn build && yarn docs
```

--------------------------------

### Create New Remix Project and Copy App Folder

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/remix/REMIX-README.md

This sequence of commands demonstrates how to create a new Remix project, potentially with a pre-configured host, and then replace its default 'app/' folder with your existing application code.

```sh
cd ..
# create a new project, and pick a pre-configured host
npx create-remix@latest
cd my-new-remix-app
# remove the new project's app (not the old one!)
rm -rf app
# copy your app over
cp -R ../my-old-remix-app/app app
```

--------------------------------

### Build Svelte project for production

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/svelte/README.md

Generate a production-ready build of your Svelte application.

```bash
npm run build
```

--------------------------------

### appProtocol

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/LabeledListenerBuilder.html

Sets the L7 application protocol for the listener. Defaults to 'http1'.

```APIDOC
## appProtocol

### Description
Sets the L7 application protocol for this listener, i.e. "http1" or "http2" (defaults "http1").

### Parameters
#### Parameters
- **appProtocol** (string) - The L7 application protocol to set.

### Returns
this
```

--------------------------------

### Run NestJS Application in Watch Mode

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/nestjs/README.md

Starts the NestJS application in development mode with automatic restarts on file changes.

```bash
yarn run start:dev
```

--------------------------------

### connect

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/SessionBuilder.html

Attempts to establish an ngrok session with the current configuration.

```APIDOC
## connect

### Description

Attempt to establish an ngrok session using the current configuration.

### Returns

* Promise<[Session](Session.html)> - A promise that resolves with the established Session object.
```

--------------------------------

### Forward to Unix Socket with Basic Authentication

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/functions/forward.html

Set up forwarding to a Unix domain socket, including basic authentication credentials and using the authtoken from environment variables.

```typescript
listener = await ngrok.forward({addr: "unix:///path/to/unix.socket", basic_auth: "ngrok:online1line", authtoken_from_env: true});
```

--------------------------------

### proto()

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/Listener.html

Returns the protocol of the endpoint that this listener backs.

```APIDOC
## proto()

### Description
The protocol of the endpoint that this listener backs.

### Returns
* null | string - The protocol string (e.g., "http", "tcp") or null if not determined.
```

--------------------------------

### Connection: Forward with options (basic auth)

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

Pass options to the forward method to customize the connection, including basic authentication.

```javascript
const listener = await ngrok.forward({ addr: 8080, basic_auth: "ngrok:online1line" });
```

--------------------------------

### remoteAddr

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/TcpListenerBuilder.html

Sets the TCP address to request for this edge. These addresses can be reserved in the ngrok dashboard to use across sessions. Example: remote_addr("[2.tcp.ngrok.io:21746](http://2.tcp.ngrok.io:21746)").

```APIDOC
## remoteAddr

### Description
The TCP address to request for this edge. These addresses can be reserved in the [ngrok dashboard](https://dashboard.ngrok.com/cloud-edge/tcp-addresses) to use across sessions.

### Method
remoteAddr(remoteAddr: string): this

### Parameters
#### Path Parameters
* **remoteAddr** (string) - The TCP address to request (e.g., "[2.tcp.ngrok.io:21746](http://2.tcp.ngrok.io:21746)").

### Returns this
```

--------------------------------

### web_addr

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/interfaces/Config.html

This configuration option is unused and will be ignored with a warning.

```APIDOC
## web_addr

### Description
Unused configuration option that will be ignored with a warning.

### Type
`string`

### Optional
Yes
```

--------------------------------

### proto

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/interfaces/Config.html

Defines the type of listener to use. Defaults to 'http'.

```APIDOC
## proto

### Description
The type of listener to use, one of http|tcp|tls|labeled, defaults to http.

### Parameters
#### Request Body
- **proto** (string) - Optional - The type of listener (http, tcp, tls, labeled).
```

--------------------------------

### TcpListenerBuilder Constructor

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/TcpListenerBuilder.html

Initializes a new instance of the TcpListenerBuilder class.

```APIDOC
## TcpListenerBuilder Constructor

### Description
Initializes a new instance of the TcpListenerBuilder class.

### Returns
TcpListenerBuilder
```

--------------------------------

### Add and Commit Changes

Source: https://github.com/ngrok/ngrok-javascript/blob/main/RELEASE.md

Stage all changes and commit them with the version number as the commit message.

```bash
git add .
git commit -m '<version>'
```

--------------------------------

### Create a new Svelte project

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/svelte/README.md

Use npm to create a new Svelte project. You can create it in the current directory or specify a new directory name.

```bash
npm create svelte@latest
```

```bash
npm create svelte@latest my-app
```

--------------------------------

### Connection: Forward with options (OAuth)

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

Pass options to the forward method to customize the connection, including OAuth provider and allowed domains.

```javascript
const listener = await ngrok.forward({ addr: 8080, oauth_provider: "google", oauth_allow_domains: "example.com" });
```

--------------------------------

### Create Release Branch

Source: https://github.com/ngrok/ngrok-javascript/blob/main/RELEASE.md

Create a new branch for the release, named with your username and the version number.

```bash
git checkout -b <username>/<version>
```

--------------------------------

### connect

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/functions/connect.html

Alias for the forward function. Establishes connections with the provided configuration. See forward for the full set of options.

```APIDOC
## connect(config: string | number | Config): Promise<Listener>[]

### Description
Alias for [forward](forward.html). See [forward](forward.html) for the full set of options.

### Parameters
#### Parameters
* **config** (string | number | [Config](../interfaces/Config.html)) - Description of the configuration parameter.

### Returns
Promise<[Listener](../classes/Listener.html)">

### Defined in
[index.d.ts:354](https://github.com/ngrok/ngrok-javascript/blob/bc870a65c82af0d8c0036b17907b0f96d12a0cb9/index.d.ts#L354)
```

--------------------------------

### Run Development Server

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/vue/README.md

Use this command to compile and hot-reload your Vue 3 application during development.

```sh
npm run dev
```

--------------------------------

### Connection: Forward to host and port

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

Specify the host and port to forward to using a string.

```javascript
const listener = await ngrok.forward("localhost:4242");
```

--------------------------------

### httpEndpoint()

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/Session.html

Initiates the process of building a listener for an HTTP endpoint.

```APIDOC
## httpEndpoint()

### Description
Start building a listener backing an HTTP endpoint.

### Returns
- **HttpListenerBuilder** - An HttpListenerBuilder object to configure the HTTP listener.
```

--------------------------------

### LabeledListenerBuilder Constructor

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/LabeledListenerBuilder.html

Initializes a new instance of the LabeledListenerBuilder.

```APIDOC
## constructor

### Description
Initializes a new instance of the LabeledListenerBuilder.

### Returns
LabeledListenerBuilder
```

--------------------------------

### handleStopCommand

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/SessionBuilder.html

Sets up a handler function that is invoked when the ngrok service signals a request to stop the session.

```APIDOC
## handleStopCommand

### Description
Configures a function which is called when the ngrok service requests that this Session stops. Your application may choose to interpret this callback as a request to terminate the Session or the entire process. Errors returned by this function will be visible to the ngrok dashboard or API as the response to the Stop operation. Do not block inside this callback. It will cause the Dashboard or API stop operation to time out. Do not call std::process::exit inside this callback, it will also cause the operation to time out.

### Method
(Implicitly a method of SessionBuilder)

### Parameters
#### Handler Function
- **handler**: () => void - A function to be called when a stop command is received.

### Returns
- **this**: Returns the SessionBuilder instance for chaining.
```

--------------------------------

### Next.js Configuration for Ngrok

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/nextjs/README.md

Add this line to your `next.config.js` to set up the ngrok listener on the default port 3000.

```javascript
require("./ngrok.config.js");
```

--------------------------------

### connect

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/modules.html

Establishes a connection to the ngrok service. This function is the primary way to initiate an ngrok tunnel.

```APIDOC
## connect

### Description
Establishes a connection to the ngrok service. This function is the primary way to initiate an ngrok tunnel.

### Function Signature
`connect(config?: Config): Promise<Listener>`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* **config** (Config) - Optional - Configuration object for the connection. See the `Config` interface for details.
```

--------------------------------

### Config Options

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/interfaces/Config.html

This section details the optional configuration properties for ngrok listeners, covering various security and authentication mechanisms.

```APIDOC
## Config Options

This interface defines optional configuration parameters for ngrok listeners.

### Properties

#### `key`

- **Type**: `string`
- **Optional**
- **Description**: The certificate to use for TLS termination at the ngrok edge in PEM format. Only used if "proto" is "tls". See [TLS Termination](https://ngrok.com/docs/cloud-edge/modules/tls-termination/) in the ngrok docs for additional details.

#### `labels`

- **Type**: `string | string[]`
- **Optional**
- **Description**: Add label, value pairs for this listener, colon separated.

#### `metadata`

- **Type**: `string`
- **Optional**
- **Description**: Listener-specific opaque metadata. Viewable via the API.

#### `mutual_tls_cas`

- **Type**: `string | string[]`
- **Optional**
- **Description**: Certificates to use for client authentication at the ngrok edge. Only used if "proto" is "tls" or "http". See [Mutual TLS](https://ngrok.com/docs/cloud-edge/modules/mutual-tls/) in the ngrok docs for additional details.

#### `name`

- **Type**: `string`
- **Optional**
- **Description**: Unused, will warn and be ignored.

#### `oauth_allow_domains`

- **Type**: `string | string[]`
- **Optional**
- **Description**: OAuth configuration of domains to allow. See [OAuth](https://ngrok.com/docs/cloud-edge/modules/oauth/) in the ngrok docs for additional details.

#### `oauth_allow_emails`

- **Type**: `string | string[]`
- **Optional**
- **Description**: OAuth configuration of email addresses to allow. See [OAuth](https://ngrok.com/docs/cloud-edge/modules/oauth/) in the ngrok docs for additional details.

#### `oauth_client_id`

- **Type**: `string`
- **Optional**
- **Description**: OAuth configuration of client ID. Required for scopes. See [OAuth](https://ngrok.com/docs/cloud-edge/modules/oauth/) in the ngrok docs for additional details.

#### `oauth_client_secret`

- **Type**: `string`
- **Optional**
- **Description**: OAuth configuration of client secret. Required for scopes. See [OAuth](https://ngrok.com/docs/cloud-edge/modules/oauth/) in the ngrok docs for additional details.

#### `oauth_provider`

- **Type**: `string`
- **Optional**
- **Description**: OAuth configuration of the provider, e.g. "google". See [OAuth](https://ngrok.com/docs/cloud-edge/modules/oauth/) in the ngrok docs for additional details.

#### `oauth_scopes`

- **Type**: `string | string[]`
- **Optional**
- **Description**: OAuth configuration of scopes. See [OAuth](https://ngrok.com/docs/cloud-edge/modules/oauth/) in the ngrok docs for additional details.

#### `oidc_allow_domains`

- **Type**: `string | string[]`
- **Optional**
- **Description**: OIDC configuration of domains to allow. See [OpenID Connect](https://ngrok.com/docs/cloud-edge/modules/openid-connect/) in the ngrok docs for additional details.

#### `oidc_allow_emails`

- **Type**: `string | string[]`
- **Optional**
- **Description**: OIDC configuration of email addresses to allow. See [OpenID Connect](https://ngrok.com/docs/cloud-edge/modules/openid-connect/) in the ngrok docs for additional details.

```

--------------------------------

### Connection: TCP listener

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

Create a TCP listener by specifying the proto parameter as 'tcp' in the forward method.

```javascript
const listener = await ngrok.forward({ proto: 'tcp', addr: 25565 });
```

--------------------------------

### Forward with HTTPS Address and Auth Token from Environment

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/functions/forward.html

Configure forwarding to a local HTTPS address, automatically using the ngrok authtoken from environment variables.

```typescript
listener = await ngrok.forward({addr: "[https://localhost:8443](https://localhost:8443)", authtoken_from_env: true});
```

--------------------------------

### tlsEndpoint()

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/Session.html

Initiates the process of building a listener for a TLS endpoint.

```APIDOC
## tlsEndpoint()

### Description
Start building a listener backing a TLS endpoint.

### Returns
- **TlsListenerBuilder** - A TlsListenerBuilder object to configure the TLS listener.
```

--------------------------------

### binPath

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/interfaces/Config.html

Specifies the path to the ngrok binary. This option is currently unused and will be ignored with a warning.

```APIDOC
## binPath

### Description
Specifies the path to the ngrok binary. This option is currently unused and will be ignored with a warning.

### Type
string

### Optional
Yes
```

--------------------------------

### tcpEndpoint()

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/Session.html

Initiates the process of building a listener for a TCP endpoint.

```APIDOC
## tcpEndpoint()

### Description
Start building a listener backing a TCP endpoint.

### Returns
- **TcpListenerBuilder** - A TcpListenerBuilder object to configure the TCP listener.
```

--------------------------------

### join()

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/Listener.html

Waits for the forwarding task associated with this listener to exit.

```APIDOC
## join()

### Description
Wait for the forwarding task to exit.

### Returns
* Promise<void> - A promise that resolves when the forwarding task exits.
```

--------------------------------

### inspect

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/interfaces/Config.html

This option is currently unused and will be ignored with a warning.

```APIDOC
## inspect

### Description
Unused, will warn and be ignored

### Type
string

### Optional
Yes
```

--------------------------------

### authtokenFromEnv

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/SessionBuilder.html

A shortcut for setting the authtoken using the NGROK_AUTHTOKEN environment variable.

```APIDOC
## authtokenFromEnv

### Description

Shortcut for calling `SessionBuilder.authtoken` with the value of the NGROK_AUTHTOKEN environment variable.

### Returns

* this - The SessionBuilder instance for chaining.
```

--------------------------------

### proxyProto

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/HttpListenerBuilder.html

Configures the PROXY protocol version to use with this listener. Supported versions are '1' and '2'.

```APIDOC
## proxyProto

### Description
The version of PROXY protocol to use with this listener "1", "2", or "" if not using.

### Method
proxyProto

### Parameters
#### Path Parameters
* **proxyProto** (string) - Required - The PROXY protocol version ('1', '2', or '').

### Returns this
```

--------------------------------

### proxy_proto

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/interfaces/Config.html

Specifies the version of PROXY protocol to use with this listener.

```APIDOC
## proxy_proto

### Description
The version of PROXY protocol to use with this listener "1", "2", or "" if not using.

### Parameters
#### Request Body
- **proxy_proto** (string) - Optional - The PROXY protocol version ('1' or '2').
```

--------------------------------

### NgrokSessionBuilder

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/index.html

Provides more control over Sessions and Listeners using a builder pattern.

```APIDOC
## NgrokSessionBuilder

### Description
A builder class for creating and configuring ngrok sessions and listeners with more control.

### Method
- `new NgrokSessionBuilder()`
- `.authtokenFromEnv(): NgrokSessionBuilder`
- `.connect(): Promise<NgrokSession>`
- `session.httpEndpoint(): HttpEndpointBuilder`
- `httpEndpoint.listen(): Promise<Listener>`
- `listener.forward(address: string | number): Promise<void>`

### Request Example
```javascript
const ngrok = require("@ngrok/ngrok");

async function create_listener() {
  const session = await new ngrok.NgrokSessionBuilder().authtokenFromEnv().connect();
  const listener = await session.httpEndpoint().listen();
  console.log("Ingress established at:", listener.url());
  listener.forward("localhost:8081");
}
```
```

--------------------------------

### configPath

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/interfaces/Config.html

Specifies the path to the ngrok configuration file. This option is currently unused and will be ignored with a warning.

```APIDOC
## configPath

### Description
Unused, will warn and be ignored

### Type
string

### Optional
Yes
```

--------------------------------

### label

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/LabeledListenerBuilder.html

Adds a label and its value to the listener configuration.

```APIDOC
## label

### Description
Adds a label, value pair for this listener. See [Using Labels](https://ngrok.com/docs/guides/using-labels-within-ngrok/) in the ngrok docs for additional details.

### Parameters
#### Parameters
- **label** (string) - The name of the label.
- **value** (string) - The value of the label.

### Returns
this
```

--------------------------------

### Run Unit Tests

Source: https://github.com/ngrok/ngrok-javascript/blob/main/examples/nestjs/README.md

Executes the unit tests for the NestJS application.

```bash
yarn run test
```

--------------------------------

### hostname

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/interfaces/Config.html

A synonym for the 'domain' option.

```APIDOC
## hostname

### Description
Synonym for domain

### Type
string

### Optional
Yes
```

--------------------------------

### Listener Constructor

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/Listener.html

Initializes a new Listener instance. This constructor is typically used internally by the ngrok library.

```APIDOC
## Listener()

### Description
Initializes a new Listener instance.

### Returns
* Listener - A new Listener object.
```

--------------------------------

### SessionBuilder Constructor

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/SessionBuilder.html

Creates a new instance of the SessionBuilder to configure an ngrok session.

```APIDOC
## SessionBuilder Constructor

### Description

Creates a new session builder instance.

### Returns

* SessionBuilder - A new instance of SessionBuilder.
```

--------------------------------

### HttpListenerBuilder

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/HttpListenerBuilder.html

An ngrok listener backing an HTTP endpoint.

```APIDOC
## Class HttpListenerBuilder

An ngrok listener backing an HTTP endpoint.

### Constructors

*   **new HttpListenerBuilder()**: HttpListenerBuilder
    
    Creates a new instance of HttpListenerBuilder.

### Methods

*   **allowCidr(cidr: string)**: this
    
    Restriction placed on the origin of incoming connections to the edge to only allow these CIDR ranges. Call multiple times to add additional CIDR ranges. See [IP restrictions](https://ngrok.com/docs/cloud-edge/modules/ip-restrictions/) in the ngrok docs for additional details.
    
    #### Parameters
    
    *   **cidr** (string) - The CIDR range to allow.
    
    #### Returns
    
    *   this - The HttpListenerBuilder instance for chaining.

*   **allowUserAgent(regex: string)**: this
    
A set of regular expressions used to match User-Agents that will be allowed. On request, the User Agent Filter module will check the incoming User-Agent header value against the list of defined allow and deny regular expression rules. See [User Agent Filter](https://ngrok.com/docs/cloud-edge/modules/user-agent-filter/) in the ngrok docs for additional details.
    
    #### Parameters
    
    *   **regex** (string) - The regular expression for allowed User-Agents.
    
    #### Returns
    
    *   this - The HttpListenerBuilder instance for chaining.

*   **appProtocol(appProtocol: string)**: this
    
The L7 application protocol to use for this edge, e.g. "http2" or "http1".
    
    #### Parameters
    
    *   **appProtocol** (string) - The application protocol string.
    
    #### Returns
    
    *   this - The HttpListenerBuilder instance for chaining.

*   **basicAuth(username: string, password: string)**: this
    
    Credentials for basic authentication. If not called, basic authentication is disabled.
    
    #### Parameters
    
    *   **username** (string) - The username for basic authentication.
    *   **password** (string) - The password for basic authentication.
    
    #### Returns
    
    *   this - The HttpListenerBuilder instance for chaining.

*   **circuitBreaker(circuitBreaker: number)**: this
    
    Reject requests when 5XX responses exceed this ratio. Disabled when 0. See [Circuit Breaker](https://ngrok.com/docs/cloud-edge/modules/circuit-breaker/) in the ngrok docs for additional details.
    
    #### Parameters
    
    *   **circuitBreaker** (number) - The ratio of 5XX responses that triggers the circuit breaker.
    
    #### Returns
    
    *   this - The HttpListenerBuilder instance for chaining.

*   **compression()**: this
    
    Enable gzip compression for HTTP responses. See [Compression](https://ngrok.com/docs/cloud-edge/modules/compression/) in the ngrok docs for additional details.
    
    #### Returns
    
    *   this - The HttpListenerBuilder instance for chaining.

```

--------------------------------

### terminate_at

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/interfaces/Config.html

This parameter is unused and will be ignored with a warning.

```APIDOC
## terminate_at

### Description
Unused, will warn and be ignored.

### Parameters
#### Query Parameters
- **terminate_at** (string) - Optional - This parameter is unused.
```

--------------------------------

### Authorization: Use authtoken from environment variable

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

Configure the forward method to use the authtoken from the NGROK_AUTHTOKEN environment variable.

```javascript
await ngrok.forward({ authtoken_from_env: true, ... });
```

--------------------------------

### Forward to a TLS Backend

Source: https://github.com/ngrok/ngrok-javascript/blob/main/README.md

Configure ngrok to forward traffic to a local HTTPS service. Ensure the SSL_CERT_FILE environment variable is set if using custom certificates.

```jsx
await ngrok.forward({ addr: "https://127.0.0.1:3000", authtoken_from_env: true });
```

--------------------------------

### labeledListener()

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/classes/Session.html

Initiates the process of building a labeled listener, allowing for custom routing and metadata.

```APIDOC
## labeledListener()

### Description
Start building a labeled listener.

### Returns
- **LabeledListenerBuilder** - A LabeledListenerBuilder object to configure the labeled listener.
```

--------------------------------

### Configuration Properties

Source: https://github.com/ngrok/ngrok-javascript/blob/main/docs/interfaces/Config.html

This section outlines the available configuration properties for ngrok sessions. Each property is optional and can be used to customize the behavior of the ngrok tunnel.

```APIDOC
## Configuration Properties

This document outlines the various properties that can be configured for an ngrok session. These properties allow for fine-grained control over network connections, authentication, security, and more.

### `addr`

- **Type**: `string | number`
- **Description**: Specifies the port, network address, URL, or named pipe to connect to. Defaults to 80. Examples include "80", "localhost:8080", "[https://192.168.1.100:8443](https://192.168.1.100:8443)", "unix:/tmp/my.sock", or "pipe://./my-pipe".

### `allow_user_agent`

- **Type**: `string | string[]`
- **Description**: A set of regular expressions to match User-Agents that will be allowed. This works in conjunction with `deny_user_agent` to filter incoming requests based on their User-Agent header.
- **See Also**: [User Agent Filter](https://ngrok.com/docs/cloud-edge/modules/user-agent-filter/)

### `app_protocol`

- **Type**: `string`
- **Description**: Defines the Layer 7 application protocol to be used for this edge, such as "http2" or "http1".

### `auth`

- **Type**: `string | string[]`
- **Description**: Used for authentication purposes.

### `authtoken`

- **Type**: `string`
- **Description**: Configures the session to authenticate with the provided authtoken. You can find or create your authtoken in the ngrok dashboard.
- **See Also**: [authtoken parameter in the ngrok docs](https://ngrok.com/docs/ngrok-agent/config#authtoken)

### `authtoken_from_env`

- **Type**: `boolean`
- **Description**: A shortcut for using the NGROK_AUTHTOKEN environment variable for authentication.

### `basic_auth`

- **Type**: `string | string[]`
- **Description**: Specifies credentials for basic authentication in the format "username:password".

### `binPath`

- **Type**: `string`
- **Description**: Path to the ngrok binary.

### `circuit_breaker`

- **Type**: `object`
- **Description**: Configuration for the circuit breaker module.

### `compression`

- **Type**: `boolean`
- **Description**: Enables or disables compression for the tunnel.

### `configPath`

- **Type**: `string`
- **Description**: Path to the ngrok configuration file.

### `crt`

- **Type**: `string`
- **Description**: Path to a TLS certificate file.

### `deny_user_agent`

- **Type**: `string | string[]`
- **Description**: A set of regular expressions used to match User-Agents that will be denied. See `User Agent Filter` in the ngrok docs for additional details.
- **See Also**: [User Agent Filter](https://ngrok.com/docs/cloud-edge/modules/user-agent-filter/)

### `domain`

- **Type**: `string`
- **Description**: The custom domain to use for the tunnel.

### `force_new_session`

- **Type**: `boolean`
- **Description**: Forces the creation of a new session, even if one already exists.

### `forwards_to`

- **Type**: `string`
- **Description**: The address the tunnel should forward traffic to.

### `host`

- **Type**: `string`
- **Description**: The hostname to use for the tunnel.

### `host_header`

- **Type**: `string`
- **Description**: The value to use for the Host header in requests.

### `hostname`

- **Type**: `string`
- **Description**: The hostname for the tunnel.

### `inspect`

- **Type**: `boolean`
- **Description**: Enables or disables the inspection of tunnel traffic.

### `ip_restriction_allow_cidrs`

- **Type**: `string[]`
- **Description**: A list of CIDR blocks that are allowed to access the tunnel.

### `ip_restriction_deny_cidrs`

- **Type**: `string[]`
- **Description**: A list of CIDR blocks that are denied access to the tunnel.

### `key`

- **Type**: `string`
- **Description**: Path to a TLS private key file.

### `labels`

- **Type**: `object`
- **Description**: A set of labels to associate with the tunnel.

### `metadata`

- **Type**: `string`
- **Description**: Arbitrary metadata to associate with the tunnel.

### `mutual_tls_cas`

- **Type**: `string[]`
- **Description**: A list of trusted Certificate Authorities for mutual TLS authentication.

### `name`

- **Type**: `string`
- **Description**: A name for the tunnel.

### `oauth_allow_domains`

- **Type**: `string[]`
- **Description**: A list of domains allowed for OAuth authentication.

### `oauth_allow_emails`

- **Type**: `string[]`
- **Description**: A list of email addresses allowed for OAuth authentication.

### `oauth_client_id`

- **Type**: `string`
- **Description**: The client ID for OAuth authentication.

### `oauth_client_secret`

- **Type**: `string`
- **Description**: The client secret for OAuth authentication.

### `oauth_provider`

- **Type**: `string`
- **Description**: The OAuth provider to use.

### `oauth_scopes`

- **Type**: `string[]`
- **Description**: A list of scopes for OAuth authentication.

### `oidc_allow_domains`

- **Type**: `string[]`
- **Description**: A list of domains allowed for OIDC authentication.

### `oidc_allow_emails`

- **Type**: `string[]`
- **Description**: A list of email addresses allowed for OIDC authentication.

### `oidc_client_id`

- **Type**: `string`
- **Description**: The client ID for OIDC authentication.

### `oidc_client_secret`

- **Type**: `string`
- **Description**: The client secret for OIDC authentication.

### `oidc_issuer_url`

- **Type**: `string`
- **Description**: The issuer URL for OIDC authentication.

### `oidc_scopes`

- **Type**: `string[]`
- **Description**: A list of scopes for OIDC authentication.

### `onLogEvent`

- **Type**: `function`
- **Description**: A callback function to handle log events.

### `onStatusChange`

- **Type**: `function`
- **Description**: A callback function to handle status changes.

### `policy`

- **Type**: `string`
- **Description**: A policy to apply to the tunnel.

### `port`

- **Type**: `number`
- **Description**: The port number to use for the tunnel.

### `proto`

- **Type**: `string`
- **Description**: The protocol to use for the tunnel (e.g., "http", "https").

### `proxy_proto`

- **Type**: `boolean`
- **Description**: Enables or disables PROXY protocol.

### `region`

- **Type**: `string`
- **Description**: The region to use for the tunnel (e.g., "us-east-1").

### `remote_addr`

- **Type**: `string`
- **Description**: The remote address of the client.

### `request_header_add`

- **Type**: `object`
- **Description**: A map of headers to add to requests.

### `request_header_remove`

- **Type**: `string[]`
- **Description**: A list of headers to remove from requests.

### `response_header_add`

- **Type**: `object`
- **Description**: A map of headers to add to responses.

### `response_header_remove`

- **Type**: `string[]`
- **Description**: A list of headers to remove from responses.

### `root_cas`

- **Type**: `string[]`
- **Description**: A list of root Certificate Authorities for TLS verification.

### `schemes`

- **Type**: `string[]`
- **Description**: A list of schemes to use for the tunnel (e.g., ["http", "https"])

### `server_addr`

- **Type**: `string`
- **Description**: The server address of the tunnel.

### `session_ca_cert`

- **Type**: `string`
- **Description**: Path to a CA certificate for session verification.

### `session_metadata`

- **Type**: `string`
- **Description**: Metadata for the session.

### `subdomain`

- **Type**: `string`
- **Description**: The subdomain to use for the tunnel.

### `terminate_at`

- **Type**: `string`
- **Description**: The timestamp at which the tunnel should terminate.

### `traffic_policy`

- **Type**: `string`
- **Description**: A traffic policy to apply to the tunnel.

### `verify_upstream_tls`

- **Type**: `boolean`
- **Description**: Verifies the TLS certificate of the upstream server.

### `verify_webhook_provider`

- **Type**: `boolean`
- **Description**: Verifies the webhook provider.

### `verify_webhook_secret`

- **Type**: `string`
- **Description**: The secret for verifying webhook requests.

### `web_addr`

- **Type**: `string`
- **Description**: The address for the web interface.

### `websocket_tcp_converter`

- **Type**: `boolean`
- **Description**: Enables or disables the WebSocket to TCP converter.

```