Skip to content

Commit 8c9b3c4

Browse files
blakmatrixblakmatrix
committed
update docs
1 parent bcf3b81 commit 8c9b3c4

18 files changed

+367
-947
lines changed

‎ReadMe.md

+14-25
Original file line numberDiff line numberDiff line change
@@ -44,48 +44,37 @@
4444

4545
To use the API, just do the standard
4646

47-
$ npm install --save node-zendesk
47+
```shell
48+
npm install --save node-zendesk
49+
```
4850

4951

5052
## Example
5153

5254
```js
5355
var zendesk = require('node-zendesk');
56+
// or `import {createClient} from 'node-zendesk'` if using typescript
5457

5558
var client = zendesk.createClient({
5659
username: 'username',
5760
token: 'token',
58-
remoteUri: 'https://remote.zendesk.com/api/v2'
61+
subdomain: 'subdomain'
5962
});
6063

61-
client.users.list(function (err, req, result) {
62-
if (err) {
63-
console.log(err);
64-
return;
65-
}
66-
console.log(JSON.stringify(result[0], null, 2, true));//gets the first page
64+
client.users.list().then(users => {
65+
console.log('Total Users:', users.length);
66+
console.log('User Names:', users.map(user => user.name));
67+
}).catch(error => {
68+
console.error(`Failed to get list of users: ${error.message}`);
6769
});
6870
```
69-
or you can use `Promises`, you just need to skip the callback:
70-
```js
71-
var zendesk = require('node-zendesk');
7271

73-
var client = zendesk.createClient({
74-
username: 'username',
75-
token: 'token',
76-
remoteUri: 'https://remote.zendesk.com/api/v2'
77-
});
78-
79-
client.users.list()
80-
.then(function(result) {
81-
console.log(JSON.stringify(result[0], null, 2, true));//gets the first page
82-
})
83-
.catch(function(error) {
84-
console.log(error);
85-
});
86-
```
8772
Take a look in the `examples` folder for more examples.
8873

74+
## Getting Started
75+
76+
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.
77+
8978
## Contributions
9079

9180
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

+13-2
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,19 @@ import { defineConfig } from 'vitepress'
22
import { generateSidebar } from "vitepress-sidebar";
33

44

5+
56
const getSideBar = (): any => {
67
const generatedSidebar = generateSidebar([
8+
{
9+
documentRootPath: "docs",
10+
scanStartPath: "guide",
11+
resolvePath: "/guide/",
12+
useTitleFromFileHeading: true,
13+
hyphenToSpace: true,
14+
keepMarkdownSyntaxFromTitle: true,
15+
sortMenusByFrontmatterOrder: true,
16+
manualSortFileNameByPriority: [ "installation.md", "authentication.md", "final.md" , 'Advanced']
17+
},
718
{
819
documentRootPath: "docs",
920
//scanStartPath: 'api',
@@ -19,7 +30,7 @@ const getSideBar = (): any => {
1930
export default defineConfig({
2031
title: "node-zendesk",
2132
description: "A Zendesk API client wrapper",
22-
//base: "/node-zendesk/",
33+
base: "/node-zendesk/",
2334
themeConfig: {
2435
// https://vitepress.dev/reference/default-theme-config
2536
logo: '/Node_Zendesk_logo.svg',
@@ -43,5 +54,5 @@ export default defineConfig({
4354
message: 'Released under the MIT License.',
4455
copyright: 'Copyright © 2012-present | Made by Farrin A. Reid with ❤️'
4556
},
46-
}
57+
},
4758
})

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

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Custom Headers
2+
3+
You can provide additional custom headers for your requests:
4+
5+
```js
6+
const clientOptions = {
7+
customHeaders: {
8+
'X-Custom-Header': 'CustomValue'
9+
}
10+
};
11+
```

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

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Custom Logging
2+
3+
`node-zendesk` provides an option to log to your own logger object. By default, it uses its own `ConsoleLogger`. To use a custom logger:
4+
5+
```js
6+
const clientOptions = {
7+
username: 'your_username',
8+
token: 'your_token',
9+
subdomain: 'your_subdomain',
10+
logger: yourCustomLogger,
11+
debug: true
12+
};
13+
const client = zendesk.createClient(clientOptions);
14+
```

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

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Custom Transport Configuration
2+
3+
If you prefer not to use the default `cross-fetch`, you can configure a custom transport. Here's an example using `axios`:
4+
5+
```js
6+
const transportConfigUsingAxios = {
7+
async transportFn(uri, options) {
8+
// Convert the options to be compatible with axios
9+
const requestOptions = {
10+
...options,
11+
url: uri,
12+
method: options.method || 'GET',
13+
data: options.body,
14+
};
15+
16+
try {
17+
const response = await axios(requestOptions);
18+
return response;
19+
} catch (error) {
20+
if (error.response) {
21+
return error.response;
22+
}
23+
throw error;
24+
}
25+
},
26+
27+
responseAdapter(response) {
28+
return {
29+
json: () => Promise.resolve(response.data),
30+
status: response.status,
31+
headers: {
32+
get: (headerName) => response.headers[headerName.toLowerCase()],
33+
},
34+
statusText: response.statusText,
35+
};
36+
},
37+
};
38+
39+
const setupClient = (config) => {
40+
return zd.createClient({
41+
username: ZENDESK_USERNAME,
42+
subdomain: ZENDESK_SUBDOMAIN,
43+
token: ZENDESK_TOKEN,
44+
transportConfig: transportConfigUsingAxios,
45+
...config,
46+
});
47+
};
48+
49+
async function foo() {
50+
try {
51+
const client = setupClient({debug: false});
52+
const result = await client.users.list();
53+
console.dir(result);
54+
} catch (error) {
55+
console.error(`Failed: ${error.message}`);
56+
}
57+
}
58+
59+
foo();
60+
```
61+
62+
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

+9
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Debug Logging
2+
3+
Enable or disable debug logging using the `debug` property:
4+
5+
```js
6+
const clientOptions = {
7+
debug: true
8+
};
9+
```

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

+13
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Endpoint URI Override
2+
3+
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.
4+
5+
## Throttling
6+
7+
Enable request throttling by setting the `throttle` flag:
8+
9+
```js
10+
const clientOptions = {
11+
throttle: true
12+
};
13+
```

‎docs/guide/Guide/Advanced/index.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
---
2+
order:5
3+
---

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

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# API Types
2+
3+
`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:
4+
5+
```js
6+
client.helpdesk.categories.list();
7+
```
8+
9+
Currently, there are only `helpdesk`, `services`, and `voice` and you can use them all by including the upon client instantiation as follows:
10+
11+
```js
12+
const clientOptions = {
13+
username: 'your_username',
14+
token: 'your_token',
15+
subdomain: 'your_subdomain',
16+
apiType: ['core', 'helpdesk', 'services', 'voice'],
17+
};
18+
const client = zendesk.createClient(clientOptions);
19+
```

‎docs/guide/Guide/Advanced/pagination.md

+17
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Pagination
2+
3+
`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:
4+
5+
```js
6+
const clientOptions = {
7+
username: 'your_username',
8+
token: 'your_token',
9+
subdomain: 'your_subdomain',
10+
query: { page: { size: 1 } }
11+
};
12+
const client = zendesk.createClient(clientOptions);
13+
```
14+
15+
::: danger **Warning**
16+
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.
17+
:::

‎docs/guide/Guide/Advanced/sideload.md

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

‎docs/guide/Guide/Advanced/throttling.md

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Throttling
2+
3+
Enable request throttling by setting the `throttle` flag:
4+
5+
```js
6+
const clientOptions = {
7+
throttle: true
8+
};

‎docs/guide/Guide/authentication.md

+90
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
---
2+
order: 2
3+
---
4+
5+
# Authentication
6+
7+
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.
8+
9+
## Basic Authentication
10+
11+
Using a combination of your username, token, and subdomain, you can quickly set up basic authentication:
12+
13+
::: code-group
14+
15+
```js
16+
var zendesk = require('node-zendesk');
17+
18+
var client = zendesk.createClient({
19+
username: 'your_username',
20+
token: 'your_token',
21+
subdomain: 'your_subdomain'
22+
});
23+
```
24+
25+
```ts
26+
import {createClient} from 'node-zendesk'
27+
28+
var client = createClient({
29+
username: 'your_username',
30+
token: 'your_token',
31+
subdomain: 'your_subdomain'
32+
});
33+
```
34+
:::
35+
36+
## OAuth Authentication
37+
38+
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.
39+
40+
::: code-group
41+
```js
42+
var zendesk = require('node-zendesk');
43+
44+
var client = zendesk.createClient({
45+
token: 'your_oauth_token',
46+
oauth: true
47+
});
48+
```
49+
50+
```ts
51+
import {createClient} from 'node-zendesk'
52+
53+
var client = zendesk.createClient({
54+
token: 'your_oauth_token',
55+
oauth: true
56+
});
57+
```
58+
:::
59+
60+
## Impersonation
61+
62+
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:
63+
64+
::: code-group
65+
```js
66+
var zendesk = require('node-zendesk');
67+
68+
var client = createClient({
69+
username: 'your_username',
70+
token: 'your_oauth_token',
71+
subdomain: 'your_subdomain',
72+
oauth: true,
73+
asUser: 'end-user@example.com'
74+
});
75+
```
76+
77+
```ts
78+
import {createClient} from 'node-zendesk'
79+
80+
var client = createClient({
81+
username: 'your_username',
82+
token: 'your_oauth_token',
83+
subdomain: 'your_subdomain',
84+
oauth: true,
85+
asUser: 'end-user@example.com'
86+
});
87+
```
88+
:::
89+
90+
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.

0 commit comments

Comments
 (0)