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 <ali.barin53@gmail.com>

packages/backend/src/apps/zendesk/assets/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="363" height="259" fill="#03363d"><path d="M173.82 40.5v112.86H80.34L173.82 40.5zm0-40.5a46.74 46.74 0 1 1-93.48 0h93.48zm15.4 153.37a46.74 46.74 0 0 1 93.48 0h-93.48zm0-40.5V0h93.5l-93.5 112.86zm52.28 137.06a18.22 18.22 0 0 0 12.95-5l6.42 6.93c-4.24 4.36-10.12 7.6-19.26 7.6-15.67 0-25.8-10.4-25.8-24.46a24 24 0 0 1 24.37-24.47c15.56 0 24.38 11.84 23.6 28.26H227c1.3 6.82 6.1 11.17 14.47 11.17m11.2-19c-1-6.37-4.8-11.06-12.4-11.06-7.07 0-12 4-13.27 11.06h25.68zM0 249.4l28.3-28.76H.67v-9.02h40.76v9.2l-28.3 28.75h28.7v9.03H0v-9.2zm73.6.52a18.22 18.22 0 0 0 12.95-5l6.42 6.93c-4.24 4.36-10.12 7.6-19.26 7.6-15.67 0-25.8-10.4-25.8-24.46a24 24 0 0 1 24.37-24.47c15.56 0 24.38 11.84 23.6 28.26H59.12c1.3 6.82 6.1 11.17 14.47 11.17m11.2-19c-1-6.37-4.8-11.06-12.4-11.06-7.07 0-12 4-13.27 11.06H84.8zm72.23 4.03c0-15 11.23-24.44 23.6-24.44a20.34 20.34 0 0 1 15.67 7.05v-27.72h10v68.6h-10V252a20.1 20.1 0 0 1-15.76 7.42c-12 0-23.5-9.5-23.5-24.43m39.82-.1a14.92 14.92 0 1 0-14.91 15.32c8.6 0 14.9-6.86 14.9-15.32m73.48 13.6l9.06-4.7a13.44 13.44 0 0 0 12.08 6.86c5.66 0 8.6-2.9 8.6-6.2 0-3.76-5.47-4.6-11.42-5.83-8-1.7-16.33-4.33-16.33-14 0-7.43 7.07-14.3 18.2-14.2 8.77 0 15.3 3.48 19 9.1l-8.4 4.6a12.19 12.19 0 0 0-10.57-5.36c-5.38 0-8.12 2.63-8.12 5.64 0 3.38 4.34 4.32 11.14 5.83 7.74 1.7 16.5 4.23 16.5 14 0 6.48-5.66 15.22-19.06 15.13-9.8 0-16.7-3.95-20.67-10.9m66.9-10.87l-7.93 8.65v12.2h-10v-68.6h10v44.93l21.23-23.3h12.18l-18.4 20.1 18.88 26.88h-11.32l-14.63-20.86zM126.8 210.53c-11.9 0-21.85 7.7-21.85 20.5v27.45h10.2V232.3c0-7.7 4.43-12.32 12-12.32s11.33 4.6 11.33 12.32v26.18h10.14v-27.45c0-12.78-10-20.5-21.85-20.5"/></svg>

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()}`,
+  });
+}

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,
+};

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;

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;

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;

packages/backend/src/apps/zendesk/common/auth-scope.ts

@@ -0,0 +1,3 @@
+const authScope: string[] = ['read', 'write'];
+
+export default authScope;

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<IJSONObject> => {
+  const response = await $.http.get('/api/v2/users/me');
+  const currentUser = response.data.user;
+
+  return currentUser;
+};
+
+export default getCurrentUser;

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,
+});

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' },
+          ],
+        },
       ],
       '/': [
         {

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.

packages/docs/pages/public/favicons/zendesk.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="363" height="259" fill="#03363d"><path d="M173.82 40.5v112.86H80.34L173.82 40.5zm0-40.5a46.74 46.74 0 1 1-93.48 0h93.48zm15.4 153.37a46.74 46.74 0 0 1 93.48 0h-93.48zm0-40.5V0h93.5l-93.5 112.86zm52.28 137.06a18.22 18.22 0 0 0 12.95-5l6.42 6.93c-4.24 4.36-10.12 7.6-19.26 7.6-15.67 0-25.8-10.4-25.8-24.46a24 24 0 0 1 24.37-24.47c15.56 0 24.38 11.84 23.6 28.26H227c1.3 6.82 6.1 11.17 14.47 11.17m11.2-19c-1-6.37-4.8-11.06-12.4-11.06-7.07 0-12 4-13.27 11.06h25.68zM0 249.4l28.3-28.76H.67v-9.02h40.76v9.2l-28.3 28.75h28.7v9.03H0v-9.2zm73.6.52a18.22 18.22 0 0 0 12.95-5l6.42 6.93c-4.24 4.36-10.12 7.6-19.26 7.6-15.67 0-25.8-10.4-25.8-24.46a24 24 0 0 1 24.37-24.47c15.56 0 24.38 11.84 23.6 28.26H59.12c1.3 6.82 6.1 11.17 14.47 11.17m11.2-19c-1-6.37-4.8-11.06-12.4-11.06-7.07 0-12 4-13.27 11.06H84.8zm72.23 4.03c0-15 11.23-24.44 23.6-24.44a20.34 20.34 0 0 1 15.67 7.05v-27.72h10v68.6h-10V252a20.1 20.1 0 0 1-15.76 7.42c-12 0-23.5-9.5-23.5-24.43m39.82-.1a14.92 14.92 0 1 0-14.91 15.32c8.6 0 14.9-6.86 14.9-15.32m73.48 13.6l9.06-4.7a13.44 13.44 0 0 0 12.08 6.86c5.66 0 8.6-2.9 8.6-6.2 0-3.76-5.47-4.6-11.42-5.83-8-1.7-16.33-4.33-16.33-14 0-7.43 7.07-14.3 18.2-14.2 8.77 0 15.3 3.48 19 9.1l-8.4 4.6a12.19 12.19 0 0 0-10.57-5.36c-5.38 0-8.12 2.63-8.12 5.64 0 3.38 4.34 4.32 11.14 5.83 7.74 1.7 16.5 4.23 16.5 14 0 6.48-5.66 15.22-19.06 15.13-9.8 0-16.7-3.95-20.67-10.9m66.9-10.87l-7.93 8.65v12.2h-10v-68.6h10v44.93l21.23-23.3h12.18l-18.4 20.1 18.88 26.88h-11.32l-14.63-20.86zM126.8 210.53c-11.9 0-21.85 7.7-21.85 20.5v27.45h10.2V232.3c0-7.7 4.43-12.32 12-12.32s11.33 4.6 11.33 12.32v26.18h10.14v-27.45c0-12.78-10-20.5-21.85-20.5"/></svg>