@ngrok/ngrok-api 0.0.9 → 0.3.0

package/.eslintrc.js

@@ -21,8 +21,11 @@ module.exports = {
         "jest"
     ],
     "rules": {
+        "no-fallthrough": "warn",
+        "no-undef": "warn",
+        "no-unsafe-finally": "warn",
         "@typescript-eslint/no-empty-interface": "warn",
         "@typescript-eslint/no-this-alias": "warn",
-        "@typescript-eslint/no-var-requires": "warn"
+        "@typescript-eslint/no-var-requires": "warn",
     }
 };

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+## 0.2.0 (July 14, 2021)
+
+ENHANCEMENTS:
+
+* Restructure to use classes instead of embedded objects
+* Added support for namespaces to avoid clutter
+* Rewrote README explaining async usage, error handling, and more examples
+* Run tests against mock or actual API
+* Improved Typedoc generated documentation
+
+FIXES:
+
+* Use the correct naming convention for TypeScript properties
+* Use Markdown instead of plain text for Typedoc
+* Use Promise when a method returns no result instead of an empty object
+
+## 0.1.0 (June 18, 2021)
+
+ENHANCEMENTS:
+
+* List iterators supporting automatic paging
+* Generate TypeScript documentation
+
+## 0.0.11 (June 8, 2021)
+
+FIXES:
+
+* Fix missing Ngrok module
+* Fix Map type JSON serialization
+
+ENHANCEMENTS:
+
+* Refine error messages to an Error type
+* Add a CHANGELOG and an example usage

package/README.md

@@ -1,3 +1,149 @@
-# ngrok JavaScript Client
+## ngrok API client library for JavaScript and TypeScript
 
-[ngrok Link API](https://ngrok.com/docs/ngrok-link) JavaScript client library.
+This library wraps the [ngrok HTTP API](https://ngrok.com/docs/api) to make it
+easier to consume in JavaScript or TypeScript.
+
+### Installation
+
+The published library is available on
+[npm](https://www.npmjs.com/package/@ngrok/ngrok-api).
+
+```shell
+npm install @ngrok/ngrok-api
+```
+
+### Documentation
+
+A quickstart guide and a full API reference are included in the [ngrok
+TypeScript API documentation](https://typescript-api.docs.ngrok.com)
+
+### Quickstart
+
+After you've installed the package, you'll need an API Key. Create one on the
+[API Keys page of your ngrok dashboard](https://dashboard.ngrok.com/api/keys).
+
+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.
+
+```typescript
+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.
+
+```typescript
+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.
+
+
+```typescript
+// 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:
+
+```typescript
+
+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](https://ngrok.com/docs/errors) that you can use to distinguish unique
+error conditions. Use the `errorCode` property in your application code to
+handle handle different error conditions.
+
+```typescript
+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
+
+```typescript
+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);
+    });
+```

package/docs/CNAME

@@ -0,0 +1 @@
+typescript-api.docs.ngrok.com