docs(core): update examples to demonstrate z.errors.Error

docs/index.html

@@ -3320,9 +3320,7 @@ <h3 id="manual-http-requests">Manual HTTP Requests</h3>
   <span class="hljs-keyword">return</span> z
     .request(<span class="hljs-string">&apos;https://example.com/api/v2/recipes.json&apos;</span>, customHttpOptions)
     .then(<span class="hljs-function"><span class="hljs-params">response</span> =&gt;</span> {
-      <span class="hljs-keyword">if</span> (response.status &gt;= <span class="hljs-number">300</span>) {
-        <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span>(<span class="hljs-string">`Unexpected status code <span class="hljs-subst">${response.status}</span>`</span>);
-      }
+      response.throwForStatus();
 
       <span class="hljs-keyword">const</span> recipes = z.JSON.parse(response.content);
       <span class="hljs-comment">// do any custom processing of recipes here...</span>
@@ -3384,8 +3382,14 @@ <h4 id="post-and-put-requests">POST and PUT Requests</h4>
           <span class="hljs-keyword">return</span> z
             .request(<span class="hljs-string">&apos;https://example.com/api/v2/recipes.json&apos;</span>, options)
             .then(<span class="hljs-function"><span class="hljs-params">response</span> =&gt;</span> {
+              <span class="hljs-comment">// throw and try to extract message from standard error responses</span>
+              response.throwForStatus();
               <span class="hljs-keyword">if</span> (response.status !== <span class="hljs-number">201</span>) {
-                <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span>(<span class="hljs-string">`Unexpected status code <span class="hljs-subst">${response.status}</span>`</span>);
+                <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> z.errors.Error(
+                  <span class="hljs-string">`Unexpected status code <span class="hljs-subst">${response.status}</span>`</span>,
+                  <span class="hljs-string">&apos;CreateRecipeError&apos;</span>,
+                  response.status
+                );
               }
             });
         }
@@ -3432,8 +3436,14 @@ <h3 id="using-http-middleware">Using HTTP middleware</h3>
 
 <span class="hljs-keyword">const</span> mustBe200 = <span class="hljs-function">(<span class="hljs-params">response, z, bundle</span>) =&gt;</span> {
   <span class="hljs-keyword">if</span> (response.status !== <span class="hljs-number">200</span>) {
-    <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> <span class="hljs-built_in">Error</span>(<span class="hljs-string">`Unexpected status code <span class="hljs-subst">${response.status}</span>`</span>);
+    <span class="hljs-keyword">throw</span> <span class="hljs-keyword">new</span> z.errors.Error(
+      <span class="hljs-string">`Unexpected status code <span class="hljs-subst">${response.status}</span>`</span>,
+      <span class="hljs-string">&apos;UnexpectedStatus&apos;</span>,
+      response.status
+    );
   }
+  <span class="hljs-comment">// throw for standard error statuses</span>
+  response.throwForStatus();
   <span class="hljs-keyword">return</span> response;
 };
 

example-apps/babel/src/authentication.js

@@ -9,7 +9,11 @@ const test = async (z /*, bundle */) => {
   // This method can return any truthy value to indicate the credentials are valid.
   // Raise an error to show
   if (response.status === 401) {
-    throw new Error('The username and/or password you supplied is incorrect');
+    throw new z.errors.Error(
+      'The username and/or password you supplied is incorrect',
+      'AuthenticationError',
+      response.status
+    );
   }
   return response;
 };

example-apps/basic-auth/authentication.js

@@ -11,8 +11,10 @@ const test = (z /*, bundle */) => {
     })
     .then(response => {
       if (response.status === 401) {
-        throw new Error(
-          'The username and/or password you supplied is incorrect'
+        throw new z.errors.Error(
+          'The username and/or password you supplied is incorrect',
+          'AuthenticationError',
+          response.status
         );
       }
       return response;

example-apps/custom-auth/authentication.js

@@ -11,7 +11,11 @@ const testAuth = (z /*, bundle */) => {
     })
     .then(response => {
       if (response.status === 401) {
-        throw new Error('The API Key you supplied is invalid');
+        throw new z.errors.Error(
+          'The API Key you supplied is invalid',
+          'AuthenticationError',
+          response.status
+        );
       }
       return response.json;
     });

example-apps/digest-auth/authentication.js

@@ -1,4 +1,4 @@
-const test = (z /*, bundle*/) => {
+const test = (z /*, bundle */) => {
   // Normally you want to make a request to an endpoint that is either specifically designed to test auth, or one that
   // every user will have access to, such as an account or profile endpoint like /me.
   // In this example, we'll hit httpbin, which validates the Authorization Header against the arguments passed in the URL path
@@ -11,8 +11,10 @@ const test = (z /*, bundle*/) => {
     })
     .then(response => {
       if (response.status === 401) {
-        throw new Error(
-          'The username and/or password you supplied is incorrect'
+        throw new z.errors.Error(
+          'The username and/or password you supplied is incorrect',
+          'AuthenticationError',
+          response.status
         );
       }
       return response;

example-apps/github/index.js

@@ -5,7 +5,11 @@ const authentication = require('./authentication');
 
 const handleHTTPError = (response, z) => {
   if (response.status >= 400) {
-    throw new Error(`Unexpected status code ${response.status}`);
+    throw new z.errors.Error(
+      `Unexpected status code ${response.status}`,
+      'StatusError',
+      response.status
+    );
   }
   return response;
 };

example-apps/oauth2/authentication.js

@@ -17,7 +17,11 @@ const getAccessToken = (z, bundle) => {
   // Needs to return at minimum, `access_token`, and if your app also does refresh, then `refresh_token` too
   return promise.then(response => {
     if (response.status !== 200) {
-      throw new Error('Unable to fetch access token: ' + response.content);
+      throw new z.errors.Error(
+        'Unable to fetch access token: ' + response.content,
+        'GetAccessTokenError',
+        response.status
+      );
     }
 
     const result = JSON.parse(response.content);
@@ -46,7 +50,11 @@ const refreshAccessToken = (z, bundle) => {
   // return it here to update the user's auth on Zapier.
   return promise.then(response => {
     if (response.status !== 200) {
-      throw new Error('Unable to fetch access token: ' + response.content);
+      throw new z.errors.Error(
+        'Unable to fetch access token: ' + response.content,
+        'RefreshAccessTokenError',
+        response.status
+      );
     }
 
     const result = JSON.parse(response.content);
@@ -68,7 +76,11 @@ const testAuth = (z /*, bundle */) => {
   // Raise an error to show
   return promise.then(response => {
     if (response.status === 401) {
-      throw new Error('The access token you supplied is not valid');
+      throw new z.errors.Error(
+        'The access token you supplied is not valid',
+        'AuthenticationError',
+        response.status
+      );
     }
     return z.JSON.parse(response.content);
   });

example-apps/onedrive/authentication.js

@@ -51,7 +51,11 @@ const getAccessToken = (z, bundle) => {
 
   return promise.then((response) => {
     if (response.status !== 200) {
-      throw new Error('Unable to fetch access token: ' + response.content)
+      throw new z.errors.Error(
+        'Unable to fetch access token: ' + response.content,
+        'GetAccessTokenError',
+        response.status
+      )
     }
 
     const result = z.JSON.parse(response.content)
@@ -89,7 +93,11 @@ const refreshAccessToken = (z, bundle) => {
 
   return promise.then((response) => {
     if (response.status !== 200) {
-      throw new Error('Unable to fetch access token: ' + response.content)
+      throw new z.errors.Error(
+        'Unable to fetch access token: ' + response.content,
+        'RefreshAccessTokenError',
+        response.status
+      )
     }
 
     const result = z.JSON.parse(response.content)
@@ -112,7 +120,11 @@ const testAuth = (z) => {
 
   return promise.then((response) => {
     if (response.status === 401) {
-      throw new Error('The access token you supplied is not valid')
+      throw new z.errors.Error(
+        'The access token you supplied is not valid',
+        'AuthenticationError',
+        response.status
+      )
     }
     return z.JSON.parse(response.content)
   })

example-apps/onedrive/resources/base-item.js

@@ -20,7 +20,7 @@ const getItem = (itemType, z, bundle) => {
   }
   return z
     .request(options)
-    .then(_.partial(parseResponse, itemType))
+    .then(_.partial(parseResponse, z, itemType))
     .then((item) => cleanupPaths([item])[0])
     .then((item) => {
       if (item.file) {
@@ -47,7 +47,7 @@ const listItems = (itemType, z, bundle) => {
 
   return z
     .request(options)
-    .then(_.partial(parseResponse, itemType))
+    .then(_.partial(parseResponse, z, itemType))
     .then(cleanupPaths)
     .then((items) => {
       items.forEach((item) => {
@@ -78,7 +78,7 @@ const searchItem = (itemType, z, bundle) => {
 
   return z
     .request(options)
-    .then(_.partial(parseResponse, itemType))
+    .then(_.partial(parseResponse, z, itemType))
     .then(cleanupPaths)
     .catch(handleError)
 }
@@ -114,7 +114,11 @@ const handleCreateWithSession = (
     })
     .then((response) => {
       if (response.status >= 300) {
-        throw new Error('Unable to start an upload session.')
+        throw new z.errors.Error(
+          'Unable to start an upload session.',
+          'UploadSessionError',
+          response.status
+        )
       }
 
       const uploadUrl = z.JSON.parse(response.content).uploadUrl

example-apps/onedrive/resources/folder.js

@@ -45,7 +45,7 @@ const createFolder = (z, bundle) => {
         'content-type': 'application/json'
       }
     })
-    .then(_.partial(parseResponse, 'folder'))
+    .then(_.partial(parseResponse, z, 'folder'))
     .then(cleanupPaths)
     .catch(handleError)
 }

example-apps/onedrive/utils.js

@@ -8,7 +8,7 @@ const contentDisposition = require('content-disposition')
 // on the OneDrive API. We intentionally don't set it up as an `afterResposne`
 // handler because not *all* calls need it (i.e. the auth test and file create),
 // so we break it out and share the code this way instead.
-const parseResponse = (type, response) => {
+const parseResponse = (z, type, response) => {
   let results = []
 
   if (response.status >= 200 && response.status < 300) {
@@ -19,7 +19,7 @@ const parseResponse = (type, response) => {
       results = results.value
     }
   } else {
-    throw new Error(response.content)
+    throw new z.errors.Error(response.content, null, response.status)
   }
 
   // Only return files or folders, according to type

example-apps/session-auth/authentication.js

@@ -10,7 +10,11 @@ const testAuth = (z /*, bundle */) => {
   // Raise an error to show
   return promise.then(response => {
     if (response.status === 401) {
-      throw new Error('The Session Key you supplied is invalid');
+      throw new z.errors.Error(
+        'The Session Key you supplied is invalid',
+        'AuthenticationError',
+        response.status
+      );
     }
     return response;
   });
@@ -28,7 +32,11 @@ const getSessionKey = (z, bundle) => {
 
   return promise.then(response => {
     if (response.status === 401) {
-      throw new Error('The username/password you supplied is invalid');
+      throw new z.errors.Error(
+        'The username/password you supplied is invalid',
+        'GetSessionKeyError',
+        response.status
+      );
     }
     const json = JSON.parse(response.content);
     return {

example-apps/typescript/src/authentication.ts

@@ -11,7 +11,7 @@ const test = async (z: ZObject /*, bundle*/) => {
   // This method can return any truthy value to indicate the credentials are valid.
   // Raise an error to show
   if (response.status === 401) {
-    throw new Error("The username and/or password you supplied is incorrect");
+    throw new z.errors.Error("The username and/or password you supplied is incorrect", "AuthenticationError", response.status);
   }
   return response;
 };

examples/auth/basic.js

@@ -7,7 +7,11 @@ const test = async (z /*, bundle */) => {
 
   if (response.status === 401) {
     // This message is surfaced to the user
-    throw new Error('The username and/or password you supplied is incorrect');
+    throw new z.errors.Error(
+      'The username and/or password you supplied is incorrect',
+      'AuthenticationError',
+      response.status
+    );
   }
 
   // anything truthy indicates the credentials are valid. Data returned from this test is available to the connection label

examples/auth/custom.js

@@ -7,7 +7,11 @@ const test = async (z /*, bundle */) => {
 
   if (response.status === 401) {
     // This message is surfaced to the user
-    throw new Error('The API Key you supplied is invalid');
+    throw new z.errors.Error(
+      'The API Key you supplied is invalid',
+      'AuthenticationError',
+      response.status
+    );
   }
   return response;
 };

examples/auth/digest.js

@@ -9,7 +9,11 @@ const test = async (z /*, bundle */) => {
 
   if (response.status === 401) {
     // This message is surfaced to the user
-    throw new Error('The username and/or password you supplied is incorrect');
+    throw new z.errors.Error(
+      'The username and/or password you supplied is incorrect',
+      'AuthenticationError',
+      response.status
+    );
   }
 
   // anything truthy indicates the credentials are valid. Data returned from this test is available to the connection label

examples/auth/oauth2.js

@@ -20,7 +20,11 @@ const getAccessToken = async (z, bundle) => {
   // Needs to return `access_token`.
   // If your app does an app refresh, then `refresh_token` should be returned as well
   if (response.status !== 200) {
-    throw new Error('Unable to fetch access token: ' + response.content);
+    throw new z.error.Error(
+      'Unable to fetch access token: ' + response.content,
+      'GetAccessTokenError',
+      response.status
+    );
   }
 
   return {
@@ -50,7 +54,11 @@ const refreshAccessToken = async (z, bundle) => {
   // If the refresh token stays constant, no need to return it
   // If the refresh token changes, return it here to update the stored value in Zapier
   if (response.status !== 200) {
-    throw new Error('Unable to fetch access token: ' + response.content);
+    throw new z.errors.Error(
+      'Unable to fetch access token: ' + response.content,
+      'RefreshAccessTokenError',
+      response.status
+    );
   }
 
   return {
@@ -77,7 +85,11 @@ const testAuth = async (z /*, bundle */) => {
 
   if (response.status === 401) {
     // This message is surfaced to the user
-    throw new Error('The access token you supplied is not valid');
+    throw new z.errors.Error(
+      'The access token you supplied is not valid',
+      'AuthenticationError',
+      response.status
+    );
   }
 
   // This method can return any truthy value to indicate the credentials are valid.

examples/auth/session.js

@@ -7,7 +7,11 @@ const test = async (z /*, bundle */) => {
 
   if (response.status === 401) {
     // This message is surfaced to the user
-    throw new Error('The Session Key you supplied is invalid');
+    throw new z.errors.Error(
+      'The Session Key you supplied is invalid',
+      'AuthenticationError',
+      response.status
+    );
   }
 
   // This method can return any truthy value to indicate the credentials are valid.
@@ -26,7 +30,11 @@ const getSessionKey = async (z, bundle) => {
   });
 
   if (response.status === 401) {
-    throw new Error('The username/password you supplied is invalid');
+    throw new z.errors.Error(
+      'The username/password you supplied is invalid',
+      'GetSessionKeyError',
+      response.status
+    );
   }
 
   return {