@ngrok/ngrok-api 0.1.0 → 0.7.0

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 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:

package/README.md

@@ -1,50 +1,121 @@
-# ngrok API client library for JavaScript and TypeScript
+## ngrok API client library for JavaScript and TypeScript
 
-This library wraps the [ngrok HTTP API](https://ngrok.com/docs/api) to make it easier to consume in JavaScript or TypeScript.
+This library wraps the [ngrok HTTP API](https://ngrok.com/docs/api) to make it
+easier to consume in JavaScript or TypeScript.
 
-## Installation
+### Installation
 
-The published library is available on [npm](https://www.npmjs.com/package/@ngrok/ngrok-api)
+The published library is available on
+[npm](https://www.npmjs.com/package/@ngrok/ngrok-api).
 
 ```shell
-npm i @ngrok/ngrok-api
+npm install @ngrok/ngrok-api
 ```
 
-## Documentation
+### Documentation
 
-A quickstart guide and a full API reference are included in the [ngrok TypeScript API documentation](https://typescript-api.docs.ngrok.com)
+A quickstart guide and a full API reference are included in the [ngrok
+TypeScript API documentation](https://typescript-api.docs.ngrok.com)
 
-API tokens are available via the [ngrok dashboard](https://dashboard.ngrok.com/api/keys).
+### Quickstart
 
-## 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).
 
-Please consult the [documentation](https://typescript-api.docs.ngrok.com) for additional examples.
-
-# TypeScript Example
+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 { EndpointConfiguration, Error, Ngrok } from '@ngrok/ngrok-api';
+import { Ngrok } from '@ngrok/ngrok-api';
 
 const ngrok = new Ngrok({
-    apiToken: 'an api token',
-    baseUrl: 'https://api.ngrok.com',
+    apiToken: '<API KEY>',
 });
 
-ngrok.EndpointConfigurations.create({
-    type: 'https',
-    description: 'some endpoint configuration description',
-    metadata: 'some endpoint configuration metadata',
-    request_headers: {
-        add: new Map([
-            ['x-frontend', 'ngrok']
-        ]),
-        remove: ['cache-control'],
-    },
+const domain = await ngrok.domains.create({
+  name: 'your-name.ngrok.io'
 })
-    .then((epc: EndpointConfiguration) => {
-        console.log(epc);
-    })
-    .catch((err: Error) => {
-        console.log(err);
-    });
+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)
+  }
+}
 ```

package/docs/CNAME

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