update docs

ReadMe.md

@@ -44,48 +44,37 @@
 
 To use the API, just do the standard
 
-    $ npm install --save node-zendesk
+```shell
+npm install --save node-zendesk
+```
 
 
 ## Example
 
 ```js
 var zendesk = require('node-zendesk');
+// or `import {createClient} from 'node-zendesk'` if using typescript
 
 var client = zendesk.createClient({
   username:  'username',
   token:     'token',
-  remoteUri: 'https://remote.zendesk.com/api/v2'
+  subdomain: 'subdomain'
 });
 
-client.users.list(function (err, req, result) {
-  if (err) {
-    console.log(err);
-    return;
-  }
-  console.log(JSON.stringify(result[0], null, 2, true));//gets the first page
+client.users.list().then(users => {
+  console.log('Total Users:', users.length);
+  console.log('User Names:', users.map(user => user.name));
+}).catch(error => {
+  console.error(`Failed to get list of users: ${error.message}`);
 });
 ```
-or you can use `Promises`, you just need to skip the callback:
-```js
-var zendesk = require('node-zendesk');
 
-var client = zendesk.createClient({
-  username:  'username',
-  token:     'token',
-  remoteUri: 'https://remote.zendesk.com/api/v2'
-});
-
-client.users.list()
-  .then(function(result) {
-    console.log(JSON.stringify(result[0], null, 2, true));//gets the first page
-  })
-  .catch(function(error) {
-    console.log(error);
-  });
-```
 Take a look in the `examples` folder for more examples.
 
+## Getting Started
+
+If you're new to `node-zendesk`, we recommend checking out our [Getting Started Guide](https://blakmatrix.github.io/node-zendesk/guide) to help you set up and familiarize yourself with the library.
+
 ## Contributions
 
 If you're looking to contribute, please refer to the [API Coverage Document](https://github.com/blakmatrix/node-zendesk/blob/master/doc/api-coverage.md), open an issue, or make a PR!

docs/.vitepress/config.mts

@@ -2,8 +2,19 @@ import { defineConfig } from 'vitepress'
 import { generateSidebar } from "vitepress-sidebar";
 
 
+
 const getSideBar = (): any => {
   const generatedSidebar = generateSidebar([
+    {
+      documentRootPath: "docs",
+      scanStartPath: "guide",
+      resolvePath: "/guide/",
+      useTitleFromFileHeading: true,
+      hyphenToSpace: true,
+      keepMarkdownSyntaxFromTitle: true,
+      sortMenusByFrontmatterOrder: true,
+      manualSortFileNameByPriority: [ "installation.md", "authentication.md", "final.md" , 'Advanced']
+    },
     {
       documentRootPath: "docs",
       //scanStartPath: 'api',
@@ -19,7 +30,7 @@ const getSideBar = (): any => {
 export default defineConfig({
   title: "node-zendesk",
   description: "A Zendesk API client wrapper",
-  //base: "/node-zendesk/",
+  base: "/node-zendesk/",
   themeConfig: {
     // https://vitepress.dev/reference/default-theme-config
     logo: '/Node_Zendesk_logo.svg',
@@ -43,5 +54,5 @@ export default defineConfig({
       message: 'Released under the MIT License.',
       copyright: 'Copyright © 2012-present | Made by Farrin A. Reid with ❤️'
     },
-  }
+  },
 })

docs/guide/Guide/Advanced/custom-headers.md

@@ -0,0 +1,11 @@
+# Custom Headers
+
+You can provide additional custom headers for your requests:
+
+```js
+const clientOptions = {
+  customHeaders: {
+    'X-Custom-Header': 'CustomValue'
+  }
+};
+```

docs/guide/Guide/Advanced/custom-logging.md

@@ -0,0 +1,14 @@
+# Custom Logging
+
+`node-zendesk` provides an option to log to your own logger object. By default, it uses its own `ConsoleLogger`. To use a custom logger:
+
+```js
+const clientOptions = {
+  username: 'your_username',
+  token: 'your_token',
+  subdomain: 'your_subdomain',
+  logger: yourCustomLogger,
+  debug: true
+};
+const client = zendesk.createClient(clientOptions);
+```

docs/guide/Guide/Advanced/custom-transport.md

@@ -0,0 +1,62 @@
+# Custom Transport Configuration
+
+If you prefer not to use the default `cross-fetch`, you can configure a custom transport. Here's an example using `axios`:
+
+```js
+const transportConfigUsingAxios = {
+  async transportFn(uri, options) {
+    // Convert the options to be compatible with axios
+    const requestOptions = {
+      ...options,
+      url: uri,
+      method: options.method || 'GET',
+      data: options.body,
+    };
+
+    try {
+      const response = await axios(requestOptions);
+      return response;
+    } catch (error) {
+      if (error.response) {
+        return error.response;
+      }
+      throw error;
+    }
+  },
+
+  responseAdapter(response) {
+    return {
+      json: () => Promise.resolve(response.data),
+      status: response.status,
+      headers: {
+        get: (headerName) => response.headers[headerName.toLowerCase()],
+      },
+      statusText: response.statusText,
+    };
+  },
+};
+
+const setupClient = (config) => {
+  return zd.createClient({
+    username: ZENDESK_USERNAME,
+    subdomain: ZENDESK_SUBDOMAIN,
+    token: ZENDESK_TOKEN,
+    transportConfig: transportConfigUsingAxios,
+    ...config,
+  });
+};
+
+async function foo() {
+  try {
+    const client = setupClient({debug: false});
+    const result = await client.users.list();
+    console.dir(result);
+  } catch (error) {
+    console.error(`Failed: ${error.message}`);
+  }
+}
+
+foo();
+```
+
+This example demonstrates how to set up a client using `axios` as the transport mechanism instead of the default `cross-fetch`.

docs/guide/Guide/Advanced/debugging.md

@@ -0,0 +1,9 @@
+# Debug Logging
+
+Enable or disable debug logging using the `debug` property:
+
+```js
+const clientOptions = {
+  debug: true
+};
+```

docs/guide/Guide/Advanced/endpoint-override.md

@@ -0,0 +1,13 @@
+# Endpoint URI Override
+
+If you have a middleware service or a proxy in front of the Zendesk API, you can override the default `endpointUri`. This can be useful for custom routing or handling of requests. Note that using this override will disable the `subdomain` option.
+
+## Throttling
+
+Enable request throttling by setting the `throttle` flag:
+
+```js
+const clientOptions = {
+  throttle: true
+};
+```

docs/guide/Guide/Advanced/index.md

@@ -0,0 +1,3 @@
+---
+order:5
+---

docs/guide/Guide/Advanced/manage-apis.md

@@ -0,0 +1,19 @@
+# API Types
+
+`node-zendesk` supports different types of Zendesk APIs. By default, it uses the 'core' API. If you want to access the helpdesk API, you need to call it explicitly:
+
+```js
+client.helpdesk.categories.list();
+```
+
+Currently, there are only `helpdesk`, `services`, and `voice` and you can use them all by including the upon client instantiation as follows:
+
+```js
+const clientOptions = {
+  username: 'your_username',
+  token: 'your_token',
+  subdomain: 'your_subdomain',
+  apiType: ['core', 'helpdesk', 'services', 'voice'],
+};
+const client = zendesk.createClient(clientOptions);
+```

docs/guide/Guide/Advanced/pagination.md

@@ -0,0 +1,17 @@
+# Pagination
+
+`node-zendesk` optimizes pagination by default, ensuring efficient retrieval of large datasets. However, if you wish to override the default pagination mechanism, you can do so during client instantiation:
+
+```js
+const clientOptions = {
+  username: 'your_username',
+  token: 'your_token',
+  subdomain: 'your_subdomain',
+  query: { page: { size: 1 } }
+};
+const client = zendesk.createClient(clientOptions);
+```
+
+::: danger **Warning**
+Overriding the default pagination mechanism is not recommended. Additionally, cursor-based pagination in the Zendesk API does not support more than 100 items for most cursor-based endpoints.
+:::

docs/guide/Guide/Advanced/sideload.md

@@ -0,0 +1,7 @@
+# Side-Loading
+
+Side-loading allows you to retrieve related records along with the primary records you're querying. To set side-loading, use the `setSideLoad` method:
+
+```js
+client.users.setSideLoad(['group', 'role']);
+```

docs/guide/Guide/Advanced/throttling.md

@@ -0,0 +1,8 @@
+# Throttling
+
+Enable request throttling by setting the `throttle` flag:
+
+```js
+const clientOptions = {
+  throttle: true
+};

docs/guide/Guide/authentication.md

@@ -0,0 +1,90 @@
+---
+order: 2
+---
+
+# Authentication
+
+To interact with the Zendesk API using `node-zendesk`, you'll need to authenticate your requests. This section will guide you through the different authentication methods supported by the library.
+
+## Basic Authentication
+
+Using a combination of your username, token, and subdomain, you can quickly set up basic authentication:
+
+::: code-group
+
+```js
+var zendesk = require('node-zendesk');
+
+var client = zendesk.createClient({
+  username:  'your_username',
+  token:     'your_token',
+  subdomain: 'your_subdomain'
+});
+```
+
+```ts
+import {createClient} from 'node-zendesk'
+
+var client = createClient({
+  username:  'your_username',
+  token:     'your_token',
+  subdomain: 'your_subdomain'
+});
+```
+:::
+
+## OAuth Authentication
+
+If you prefer to use an OAuth token for authentication, set the oauth key to true when creating the client. You can learn more about obtaining OAuth tokens from Zendesk's developer site.
+
+::: code-group
+```js
+var zendesk = require('node-zendesk');
+
+var client = zendesk.createClient({
+  token:     'your_oauth_token',
+  oauth: true
+});
+```
+
+```ts
+import {createClient} from 'node-zendesk'
+
+var client = zendesk.createClient({
+  token:     'your_oauth_token',
+  oauth: true
+});
+```
+:::
+
+## Impersonation
+
+To make API requests on behalf of end users, you can use the impersonation feature. Ensure you've granted the impersonate scope and then pass the end-user's email when creating the client:
+
+::: code-group
+```js
+var zendesk = require('node-zendesk');
+
+var client = createClient({
+  username:  'your_username',
+  token:     'your_oauth_token',
+  subdomain: 'your_subdomain',
+  oauth: true,
+  asUser: 'end-user@example.com'
+});
+```
+
+```ts
+import {createClient} from 'node-zendesk'
+
+var client = createClient({
+  username:  'your_username',
+  token:     'your_oauth_token',
+  subdomain: 'your_subdomain',
+  oauth: true,
+  asUser: 'end-user@example.com'
+});
+```
+:::
+
+With authentication set up, you're ready to start making requests to the Zendesk API. In the following sections, we'll delve into more advanced features and usage patterns of node-zendesk.