@ngrok/ngrok-api
    TypeScript icon, indicating that this package has built-in type declarations

    0.2.0 • Public • Published

    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

    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)
      }
    }

    Additional Examples

    import { EndpointConfiguration, Error, Ngrok } from '@ngrok/ngrok-api';
    
    const ngrok = new Ngrok({
        apiToken: 'an api token',
    });
    
    ngrok.endpointConfigurations.create({
        type: 'https',
        description: 'some endpoint configuration description',
        metadata: 'some endpoint configuration metadata',
        requestHeaders: {
            add: new Map([
                ['x-frontend', 'ngrok']
            ]),
            remove: ['cache-control'],
        },
    })
        .then((epc: EndpointConfiguration) => {
            console.log(epc);
        })
        .catch((err: Error) => {
            console.log(err);
        });

    Keywords

    none

    Install

    npm i @ngrok/ngrok-api

    Homepage

    ngrok.com

    DownloadsWeekly Downloads

    75

    Version

    0.2.0

    License

    MIT

    Unpacked Size

    3.22 MB

    Total Files

    221

    Last publish

    Collaborators

    • inconshreveable
    • darrineden
    • ngrok-sarid