ngrok / ngrok-api-typescript

ngrok API client library for Typescript and Javascript

Unstable

This library is currently unstable. We know of rough edges and are working to bring it to parity with our other API client libraries. Please feel free to try it out and let us know if you find it useful!

ngrok API client library for JavaScript and TypeScript

This library wraps the ngrok HTTP API to make it easier to consume in JavaScript or TypeScript.

Installation

The published library is available on npm.

npm install @ngrok/ngrok-api

Support

The best place to get support using this library is through the ngrok Slack Community. If you find any bugs, please contribute by opening a new GitHub issue.

Documentation

A quickstart guide and a full API reference are included in the ngrok TypeScript API documentation

Quickstart

After you've installed the package, you'll need an API Key. Create one on the API Keys page of your ngrok dashboard.

In your application's code, initialize an Ngrok client object with an API key. API resources can be accessed as properties of the Ngrok object.

import { Ngrok } from '@ngrok/ngrok-api';

const ngrok = new Ngrok({
  apiToken: '<API KEY>',
});

const domain = await ngrok.domains.create({
  name: 'your-name.ngrok.io',
});
console.log(domain);

Automatic Paging

The ngrok API pages all list resources but this library abstracts that implementation detail away from you. list() methods will return collections that can be iterated over and the implementation will fetch the pages from the API for you behind the scenes.

import { Ngrok } from '@ngrok/ngrok-api';

const ngrok = new Ngrok({
  apiToken: '<API KEY>',
});

(await ngrok.tunnels.list()).forEach(t => console.log(t));

Async Programming

All API methods return a Promise and are suitable for use in asynchronous programming. You can use callback chaining with .then() and .catch() syntax or the await keyword to wait for completion of an API call.

// await style
const cred = await ngrok.credentials.create({ description: 'example' });
console.log(cred);

// callback chaining
ngrok.credentials.create({ description: 'example' }).then(cred => {
  console.log(cred);
});

Error Handling

The ngrok API returns detailed information when an API call fails. If an error is encountered, API methods throw the rich Error type on resolution of a returned Promise. This allows your code to gracefully handle different error conditions.

The Error type includes a statusCode property which can be used to distinguish not found errors when a resource does not exist:

import { Error } from '@ngrok/ngrok-api';

try {
  await ngrok.ipPolicies.update({
    id: 'someInvalidId',
    description: 'updated description',
  });
} catch (err: Error) {
  if (err.statusCode == 404) {
    console.log('no ip policy with that id to update');
  }
}

Every error returned by the ngrok API includes a unique, documented error code that you can use to distinguish unique error conditions. Use the errorCode property in your application code to handle handle different error conditions.

import { Error } from '@ngrok/ngrok-api';

try {
  await ngrok.ipPolicies.create({
    action: 'something invalid',
  });
} catch (err: Error) {
  if (err.errorCode == 'ERR_NGROK_1410') {
    console.log('not a valid ip policy action');
  } else {
    console.log('some other error', err);
  }
}

ngrok-api-typescript's Issues

Missing form-data dependency

Your client source (https://github.com/ngrok/ngrok-api-typescript/blob/main/src/client.ts#L4) depends on form-data and yet there doesn't seem to be any explicit dependency on it (https://github.com/ngrok/ngrok-api-typescript/blob/main/package.json#L20-L23)

I got an error immediately upon trying to use this library saying that form-data did not exist.

Am I crazy that this library is currently broken? I did see form-data in package-lock so maybe its a difference of npm versions (I am on npm 7.24.2)

ngrok.tunnelSessions.stop fails with ERR_NGROK_213

{
  errorCode: 'ERR_NGROK_213',
  statusCode: 400,
  msg: "The 'application/json' request body could not be parsed. Please check your API client implementation and review the API documentation: https://ngrok.com/docs/api#api-tunnel-sessions-stop.",
  details: Map(1) { 'operationId' => 'op_2ft0OJTh21NetHp1AlCMJNAcsEo' }
}

Steps to reproduce:

1. Start tunnel using CLI:
   ngrok http 8080 --domain=myDomain

2. Try to kill it with API request from this repo

    const ngrok = new Ngrok({
        apiToken: process.env.NGROK_API_KEY
    });
    const endpoints = await ngrok.endpoints.list();
    const endpointToKill = await ngrok.endpoints.get(endpoints[0].id)
    const tunnelToKill = await ngrok.tunnels.get(endpointToKill.tunnel.id)
    // Before this line everything works as expected, and returns proper values
    await ngrok.tunnelSessions.stop(tunnelToKill.tunnelSession.id).catch(err => console.log(err));

Note that when I replace last stop request with get request: await ngrok.tunnelSessions.get it will work es expected

Env: Linux