From d6c81bbc35cc21226357591b88d5ed6a538e9c7c Mon Sep 17 00:00:00 2001 From: Benjamin Eckel Date: Thu, 26 Dec 2019 12:35:14 -0600 Subject: [PATCH] Small tweaks to docs --- doc/GETTING_STARTED.md | 30 +++++++++++++++--------------- docs/index.html | 31 ++++++++++++++++--------------- package-lock.json | 41 ++++++++++++++++++++++++++++++----------- 3 files changed, 61 insertions(+), 41 deletions(-) diff --git a/doc/GETTING_STARTED.md b/doc/GETTING_STARTED.md index c4ddd6ab..bb42704e 100644 --- a/doc/GETTING_STARTED.md +++ b/doc/GETTING_STARTED.md @@ -30,7 +30,7 @@ To initialize a client, you only need an API key which can be obtained on the [A ```js const recurly = require('recurly') -// You should store your api key somewhere safe +// You should store your API key somewhere safe // and not in plain text if possible const myApiKey = '' const client = new recurly.Client(myApiKey) @@ -64,9 +64,9 @@ async function myFunc () { ### Creating Resources -For creating or updating resources, pass a json object to one of the create* or update* methods. -Keep in mind that the api accepts snake-cased keys but this library expects camel-cased keys. -We do the translation for you so this library can conform to js style standards. +For creating or updating resources, pass a plain object to one of the create* or update* methods. + +> **Note**: Keep in mind that the API accepts snake-cased keys but this library expects camel-cased keys. We do the translation for you so this library can conform to js style standards. ```js @@ -78,14 +78,14 @@ try { } const account = await client.createAccount(acctReq) } catch (err) { - if (err && err instanceof recurly.errors.ValidationError) { + if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params - console.log('Failed validation', err.params) + console.log('Failed validation:', err.params) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it - console.log('Unknown Error: ', err) + console.log('Unknown Error:', err) } } ``` @@ -187,21 +187,21 @@ try { if (err) { if (err.getResponse()) { const requstId = err.getResponse().requestId - console.log("Request Id useful for support: ", requestId) + console.log('Request Id useful for support:', requestId) } if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params - console.log('Failed validation', err.params) - // } else if (err instanceof recurly.errors.NotFoundError) { - // console.log('Failed validation', err.params) + console.log('Failed validation:', err.params) + } else if (err instanceof recurly.errors.NotFoundError) { + console.log('Subscription not found:', err) } else if (err instanceof recurly.ApiError) { - console.log('generic api error', err) + console.log('generic API error:', err) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it - console.log('Unknown Error: ', err) + console.log('Unknown Error:', err) } } } @@ -241,7 +241,7 @@ try { // You can also get the Response here const response = err.getResponse() } else { - console.log('Unknown Error: ', err) + console.log('Unknown Error:', err) } } ``` @@ -281,7 +281,7 @@ const xml = ` parseString(xml, function (err, result) { const code = result.new_account_notification.account[0].account_code[0]; - console.log("New account created with code: ", code); + console.log('New account created with code:', code); }) ``` diff --git a/docs/index.html b/docs/index.html index 6a4ce78e..6ed20f5d 100644 --- a/docs/index.html +++ b/docs/index.html @@ -2086,7 +2086,7 @@

Creating a client

each operation that can be performed in the API as a method.

To initialize a client, you only need an API key which can be obtained on the API Credentials Page.

const recurly = require('recurly')
-// You should store your api key somewhere safe
+// You should store your API key somewhere safe
 // and not in plain text if possible
 const myApiKey = '<myapikey>'
 const client = new recurly.Client(myApiKey)
@@ -2106,9 +2106,10 @@

Operations

} }

Creating Resources

-

For creating or updating resources, pass a json object to one of the create or update methods. -Keep in mind that the api accepts snake-cased keys but this library expects camel-cased keys. -We do the translation for you so this library can conform to js style standards.

+

For creating or updating resources, pass a plain object to one of the create or update methods.

+
+

Note: Keep in mind that the API accepts snake-cased keys but this library expects camel-cased keys. We do the translation for you so this library can conform to js style standards.

+
try {
   const acctReq = {
     code: 'new-account-code',
@@ -2117,14 +2118,14 @@ 
Creating Resources

   }
   const account = await client.createAccount(acctReq)
 } catch (err) {
-  if (err && err instanceof recurly.errors.ValidationError) {
+  if (err instanceof recurly.errors.ValidationError) {
     // If the request was not valid, you may want to tell your user
     // why. You can find the invalid params and reasons in err.params
-    console.log('Failed validation', err.params)
+    console.log('Failed validation:', err.params)
   } else {
     // If we don't know what to do with the err, we should
     // probably re-raise and let our web framework and logger handle it
-    console.log('Unknown Error: ', err)
+    console.log('Unknown Error:', err)
   }
 }

Pagination

@@ -2202,21 +2203,21 @@

Error Handling

if (err) { if (err.getResponse()) { const requstId = err.getResponse().requestId - console.log("Request Id useful for support: ", requestId) + console.log('Request Id useful for support:', requestId) } if (err instanceof recurly.errors.ValidationError) { // If the request was not valid, you may want to tell your user // why. You can find the invalid params and reasons in err.params - console.log('Failed validation', err.params) - // } else if (err instanceof recurly.errors.NotFoundError) { - // console.log('Failed validation', err.params) + console.log('Failed validation:', err.params) + } else if (err instanceof recurly.errors.NotFoundError) { + console.log('Subscription not found:', err) } else if (err instanceof recurly.ApiError) { - console.log('generic api error', err) + console.log('generic API error:', err) } else { // If we don't know what to do with the err, we should // probably re-raise and let our web framework and logger handle it - console.log('Unknown Error: ', err) + console.log('Unknown Error:', err) } } } @@ -2242,7 +2243,7 @@

HTTP Metadata

// You can also get the Response here const response = err.getResponse() } else { - console.log('Unknown Error: ', err) + console.log('Unknown Error:', err) } }

Webhooks

@@ -2274,7 +2275,7 @@

Webhooks

parseString(xml, function (err, result) { const code = result.new_account_notification.account[0].account_code[0]; - console.log("New account created with code: ", code); + console.log('New account created with code:', code); })

You can do this without dependencies, but you'll need to heed warnings about security concerns. Read more about the security implications of parsing untrusted XML in this OWASP cheatsheet.

diff --git a/package-lock.json b/package-lock.json index a42d734a..ff89c9aa 100644 --- a/package-lock.json +++ b/package-lock.json @@ -3657,7 +3657,8 @@ "ansi-regex": { "version": "2.1.1", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "aproba": { "version": "1.2.0", @@ -3678,12 +3679,14 @@ "balanced-match": { "version": "1.0.0", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "brace-expansion": { "version": "1.1.11", "bundled": true, "dev": true, + "optional": true, "requires": { "balanced-match": "^1.0.0", "concat-map": "0.0.1" @@ -3698,17 +3701,20 @@ "code-point-at": { "version": "1.1.0", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "concat-map": { "version": "0.0.1", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "console-control-strings": { "version": "1.1.0", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "core-util-is": { "version": "1.0.2", @@ -3825,7 +3831,8 @@ "inherits": { "version": "2.0.3", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "ini": { "version": "1.3.5", @@ -3837,6 +3844,7 @@ "version": "1.0.0", "bundled": true, "dev": true, + "optional": true, "requires": { "number-is-nan": "^1.0.0" } @@ -3851,6 +3859,7 @@ "version": "3.0.4", "bundled": true, "dev": true, + "optional": true, "requires": { "brace-expansion": "^1.1.7" } @@ -3858,12 +3867,14 @@ "minimist": { "version": "0.0.8", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "minipass": { "version": "2.3.5", "bundled": true, "dev": true, + "optional": true, "requires": { "safe-buffer": "^5.1.2", "yallist": "^3.0.0" @@ -3882,6 +3893,7 @@ "version": "0.5.1", "bundled": true, "dev": true, + "optional": true, "requires": { "minimist": "0.0.8" } @@ -3962,7 +3974,8 @@ "number-is-nan": { "version": "1.0.1", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "object-assign": { "version": "4.1.1", @@ -3974,6 +3987,7 @@ "version": "1.4.0", "bundled": true, "dev": true, + "optional": true, "requires": { "wrappy": "1" } @@ -4059,7 +4073,8 @@ "safe-buffer": { "version": "5.1.2", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "safer-buffer": { "version": "2.1.2", @@ -4095,6 +4110,7 @@ "version": "1.0.2", "bundled": true, "dev": true, + "optional": true, "requires": { "code-point-at": "^1.0.0", "is-fullwidth-code-point": "^1.0.0", @@ -4114,6 +4130,7 @@ "version": "3.0.1", "bundled": true, "dev": true, + "optional": true, "requires": { "ansi-regex": "^2.0.0" } @@ -4157,12 +4174,14 @@ "wrappy": { "version": "1.0.2", "bundled": true, - "dev": true + "dev": true, + "optional": true }, "yallist": { "version": "3.0.3", "bundled": true, - "dev": true + "dev": true, + "optional": true } } },