From 86611453b5ac91ea8509f71f1fbc7800bba72d37 Mon Sep 17 00:00:00 2001 From: Moaaz Elsayed <65324805+moaazelsayed1@users.noreply.github.com> Date: Thu, 26 Oct 2023 13:47:13 +0300 Subject: [PATCH] feat(zendesk): add zendesk integration (#1385) * feat(zendesk): add zendesk integration * Add Zendesk connection documentation * docs(zendesk/connection): add missing steps * feat(zendesk): add more auth scopes for planned triggers/actions * fix(zendesk): fix instanceUrl --------- Co-authored-by: Ali BARIN --- .../src/apps/zendesk/assets/favicon.svg | 1 + .../apps/zendesk/auth/generate-auth-url.ts | 23 ++++++++ .../backend/src/apps/zendesk/auth/index.ts | 55 ++++++++++++++++++ .../apps/zendesk/auth/is-still-verified.ts | 9 +++ .../apps/zendesk/auth/verify-credentials.ts | 56 +++++++++++++++++++ .../apps/zendesk/common/add-auth-headers.ts | 17 ++++++ .../src/apps/zendesk/common/auth-scope.ts | 3 + .../apps/zendesk/common/get-current-user.ts | 10 ++++ packages/backend/src/apps/zendesk/index.d.ts | 0 packages/backend/src/apps/zendesk/index.ts | 16 ++++++ packages/docs/pages/.vitepress/config.js | 8 +++ .../docs/pages/apps/zendesk/connection.md | 21 +++++++ .../docs/pages/public/favicons/zendesk.svg | 1 + 13 files changed, 220 insertions(+) create mode 100644 packages/backend/src/apps/zendesk/assets/favicon.svg create mode 100644 packages/backend/src/apps/zendesk/auth/generate-auth-url.ts create mode 100644 packages/backend/src/apps/zendesk/auth/index.ts create mode 100644 packages/backend/src/apps/zendesk/auth/is-still-verified.ts create mode 100644 packages/backend/src/apps/zendesk/auth/verify-credentials.ts create mode 100644 packages/backend/src/apps/zendesk/common/add-auth-headers.ts create mode 100644 packages/backend/src/apps/zendesk/common/auth-scope.ts create mode 100644 packages/backend/src/apps/zendesk/common/get-current-user.ts create mode 100644 packages/backend/src/apps/zendesk/index.d.ts create mode 100644 packages/backend/src/apps/zendesk/index.ts create mode 100644 packages/docs/pages/apps/zendesk/connection.md create mode 100644 packages/docs/pages/public/favicons/zendesk.svg diff --git a/packages/backend/src/apps/zendesk/assets/favicon.svg b/packages/backend/src/apps/zendesk/assets/favicon.svg new file mode 100644 index 00000000..882b4516 --- /dev/null +++ b/packages/backend/src/apps/zendesk/assets/favicon.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/packages/backend/src/apps/zendesk/auth/generate-auth-url.ts b/packages/backend/src/apps/zendesk/auth/generate-auth-url.ts new file mode 100644 index 00000000..8432bc8f --- /dev/null +++ b/packages/backend/src/apps/zendesk/auth/generate-auth-url.ts @@ -0,0 +1,23 @@ +import { IField, IGlobalVariable } from '@automatisch/types'; +import { URLSearchParams } from 'url'; +import authScope from '../common/auth-scope'; + +export default async function generateAuthUrl($: IGlobalVariable) { + const oauthRedirectUrlField = $.app.auth.fields.find( + (field: IField) => field.key == 'oAuthRedirectUrl' + ); + + const redirectUri = oauthRedirectUrlField.value as string; + const searchParams = new URLSearchParams({ + response_type: 'code', + redirect_uri: redirectUri, + client_id: $.auth.data.clientId as string, + scope: authScope.join(' '), + }); + + await $.auth.set({ + url: `${ + $.auth.data.instanceUrl + }/oauth/authorizations/new?${searchParams.toString()}`, + }); +} diff --git a/packages/backend/src/apps/zendesk/auth/index.ts b/packages/backend/src/apps/zendesk/auth/index.ts new file mode 100644 index 00000000..d4ac580c --- /dev/null +++ b/packages/backend/src/apps/zendesk/auth/index.ts @@ -0,0 +1,55 @@ +import generateAuthUrl from './generate-auth-url'; +import verifyCredentials from './verify-credentials'; +import isStillVerified from './is-still-verified'; + +export default { + fields: [ + { + key: 'oAuthRedirectUrl', + label: 'OAuth Redirect URL', + type: 'string' as const, + required: true, + readOnly: true, + value: '{WEB_APP_URL}/app/zendesk/connections/add', + placeholder: null, + description: '', + clickToCopy: true, + }, + { + key: 'instanceUrl', + label: 'Zendesk Subdomain Url', + type: 'string' as const, + required: true, + readOnly: false, + value: null, + placeholder: 'https://{{subdomain}}.zendesk.com', + clickToCopy: false, + }, + { + key: 'clientId', + label: 'Client ID', + type: 'string' as const, + required: true, + readOnly: false, + value: null, + placeholder: null, + description: null, + clickToCopy: false, + }, + { + key: 'clientSecret', + label: 'Client Secret', + type: 'string' as const, + required: true, + readOnly: false, + value: null, + placeholder: null, + description: null, + clickToCopy: false, + }, + ], + + generateAuthUrl, + verifyCredentials, + isStillVerified, +}; diff --git a/packages/backend/src/apps/zendesk/auth/is-still-verified.ts b/packages/backend/src/apps/zendesk/auth/is-still-verified.ts new file mode 100644 index 00000000..86199fd2 --- /dev/null +++ b/packages/backend/src/apps/zendesk/auth/is-still-verified.ts @@ -0,0 +1,9 @@ +import { IGlobalVariable } from '@automatisch/types'; +import getCurrentUser from '../common/get-current-user'; + +const isStillVerified = async ($: IGlobalVariable) => { + await getCurrentUser($); + return true; +}; + +export default isStillVerified; diff --git a/packages/backend/src/apps/zendesk/auth/verify-credentials.ts b/packages/backend/src/apps/zendesk/auth/verify-credentials.ts new file mode 100644 index 00000000..a2d3750b --- /dev/null +++ b/packages/backend/src/apps/zendesk/auth/verify-credentials.ts @@ -0,0 +1,56 @@ +import { IGlobalVariable, IJSONValue, IField } from '@automatisch/types'; +import getCurrentUser from '../common/get-current-user'; +import scopes from '../common/auth-scope'; + +const verifyCredentials = async ($: IGlobalVariable) => { + await getAccessToken($); + + const user = await getCurrentUser($); + const subdomain = extractSubdomain($.auth.data.instanceUrl); + const name = user.name as string; + const screenName = [name, subdomain].filter(Boolean).join(' @ '); + + await $.auth.set({ + screenName, + apiToken: $.auth.data.apiToken, + instanceUrl: $.auth.data.instanceUrl, + email: $.auth.data.email, + }); +}; + +const getAccessToken = async ($: IGlobalVariable) => { + const oauthRedirectUrlField = $.app.auth.fields.find( + (field: IField) => field.key == 'oAuthRedirectUrl' + ); + const redirectUri = oauthRedirectUrlField.value as string; + + const response = await $.http.post(`/oauth/tokens`, { + redirect_uri: redirectUri, + code: $.auth.data.code, + grant_type: 'authorization_code', + scope: scopes.join(' '), + client_id: $.auth.data.clientId as string, + client_secret: $.auth.data.clientSecret as string, + }); + + const data = response.data; + + $.auth.data.accessToken = data.access_token; + + await $.auth.set({ + clientId: $.auth.data.clientId, + clientSecret: $.auth.data.clientSecret, + accessToken: data.access_token, + tokenType: data.token_type, + }); +}; + +function extractSubdomain(url: IJSONValue) { + const match = (url as string).match(/https:\/\/(.*?)\.zendesk\.com/); + if (match && match[1]) { + return match[1]; + } + return null; +} + +export default verifyCredentials; diff --git a/packages/backend/src/apps/zendesk/common/add-auth-headers.ts b/packages/backend/src/apps/zendesk/common/add-auth-headers.ts new file mode 100644 index 00000000..68e9b5e6 --- /dev/null +++ b/packages/backend/src/apps/zendesk/common/add-auth-headers.ts @@ -0,0 +1,17 @@ +import { TBeforeRequest } from '@automatisch/types'; + +const addAuthHeader: TBeforeRequest = ($, requestConfig) => { + const { instanceUrl, tokenType, accessToken } = $.auth.data; + + if (instanceUrl) { + requestConfig.baseURL = instanceUrl as string; + } + + if (tokenType && accessToken) { + requestConfig.headers.Authorization = `${tokenType} ${$.auth.data.accessToken}`; + } + + return requestConfig; +}; + +export default addAuthHeader; diff --git a/packages/backend/src/apps/zendesk/common/auth-scope.ts b/packages/backend/src/apps/zendesk/common/auth-scope.ts new file mode 100644 index 00000000..c0dd438f --- /dev/null +++ b/packages/backend/src/apps/zendesk/common/auth-scope.ts @@ -0,0 +1,3 @@ +const authScope: string[] = ['read', 'write']; + +export default authScope; diff --git a/packages/backend/src/apps/zendesk/common/get-current-user.ts b/packages/backend/src/apps/zendesk/common/get-current-user.ts new file mode 100644 index 00000000..90f9abb2 --- /dev/null +++ b/packages/backend/src/apps/zendesk/common/get-current-user.ts @@ -0,0 +1,10 @@ +import { IGlobalVariable, IJSONObject } from '@automatisch/types'; + +const getCurrentUser = async ($: IGlobalVariable): Promise => { + const response = await $.http.get('/api/v2/users/me'); + const currentUser = response.data.user; + + return currentUser; +}; + +export default getCurrentUser; diff --git a/packages/backend/src/apps/zendesk/index.d.ts b/packages/backend/src/apps/zendesk/index.d.ts new file mode 100644 index 00000000..e69de29b diff --git a/packages/backend/src/apps/zendesk/index.ts b/packages/backend/src/apps/zendesk/index.ts new file mode 100644 index 00000000..64655b35 --- /dev/null +++ b/packages/backend/src/apps/zendesk/index.ts @@ -0,0 +1,16 @@ +import defineApp from '../../helpers/define-app'; +import addAuthHeader from './common/add-auth-headers'; +import auth from './auth'; + +export default defineApp({ + name: 'Zendesk', + key: 'zendesk', + baseUrl: 'https://zendesk.com/', + apiBaseUrl: '', + iconUrl: '{BASE_URL}/apps/zendesk/assets/favicon.svg', + authDocUrl: 'https://automatisch.io/docs/apps/zendesk/connection', + primaryColor: '17494d', + supportsConnections: true, + beforeRequest: [addAuthHeader], + auth, +}); diff --git a/packages/docs/pages/.vitepress/config.js b/packages/docs/pages/.vitepress/config.js index 29b9b2fb..9cf6b113 100644 --- a/packages/docs/pages/.vitepress/config.js +++ b/packages/docs/pages/.vitepress/config.js @@ -435,6 +435,14 @@ export default defineConfig({ { text: 'Connection', link: '/apps/youtube/connection' }, ], }, + { + text: 'Zendesk', + collapsible: true, + collapsed: true, + items: [ + { text: 'Connection', link: '/apps/zendesk/connection' }, + ], + }, ], '/': [ { diff --git a/packages/docs/pages/apps/zendesk/connection.md b/packages/docs/pages/apps/zendesk/connection.md new file mode 100644 index 00000000..08d074dc --- /dev/null +++ b/packages/docs/pages/apps/zendesk/connection.md @@ -0,0 +1,21 @@ +# Zendesk + +:::info +This page explains the steps you need to follow to set up the Zendesk +connection in Automatisch. If any of the steps are outdated, please let us know! +::: + +1. Fill `Zendesk Subdomain URL` with your dashboard URL, for example: `https://yourcompany.zendesk.com`. +2. Go to your Zendesk dashboard. +3. Click on **Zendesk Products** at the top right corner and click **Admin Center** from the dropdown. +4. Enter **App and integrations** section. +5. Click on **Zendesk API** from the sidebar. +6. Click on **OAuth Clients** tab. +7. Click on **Add OAuth Client** button. +8. Enter necessary information in the form. +9. Copy **OAuth Redirect URL** from Automatisch to **Redirect URLs** field in the form. +10. Enter your preferred client ID value in **Unique Identifier** field. +11. Save the form to complete creating the OAuth client. +12. Copy the `Unique identifier` value from the page to the `Client ID` field on Automatisch. +13. Copy the `Secret` value from the page to the `Client Secret` field on Automatisch. +14. Now, you can start using the Zendesk connection with Automatisch. diff --git a/packages/docs/pages/public/favicons/zendesk.svg b/packages/docs/pages/public/favicons/zendesk.svg new file mode 100644 index 00000000..882b4516 --- /dev/null +++ b/packages/docs/pages/public/favicons/zendesk.svg @@ -0,0 +1 @@ + \ No newline at end of file