Merge pull request #278 from zendesk/victor.piolin/views

feat: Implement zendesk views in toolbox

Author: Vico1993

__tests__/services/zendesk-api-service.spec.ts

@@ -977,4 +977,194 @@ describe("ZendeskService", () => {
             expect(requestMock).toHaveBeenCalledTimes(1);
         });
     });
+
+    describe("getActiveViews", () => {
+        const viewSample = {
+            active: true,
+            conditions: {
+                group_id: 1
+            },
+            created_at: "2023-01-01T00:00:00Z",
+            default: false,
+            description: "Test View",
+            execution: {
+                group_by: "group_by",
+                sort_by: "sort_by",
+                group_order: "asc",
+                sort_order: "asc"
+            }
+        };
+
+        it("should fetch active views with the correct data", async () => {
+            requestMock.mockResolvedValueOnce({ views: [viewSample] });
+
+            const result = await service.getActiveViews();
+
+            expect(requestMock).toHaveBeenCalledWith({
+                url: `/api/v2/views/active`
+            });
+            expect(result).toEqual([viewSample]);
+        });
+    });
+
+    describe("getViews", () => {
+        const viewSample = {
+            active: true,
+            conditions: {
+                group_id: 1
+            },
+            created_at: "2023-01-01T00:00:00Z",
+            default: false,
+            description: "Test View",
+            execution: {
+                group_by: "group_by",
+                sort_by: "sort_by",
+                group_order: "asc",
+                sort_order: "asc"
+            }
+        };
+
+        it("should fetch views with the correct data", async () => {
+            requestMock.mockResolvedValueOnce({ views: [viewSample] });
+
+            const result = await service.getViews();
+
+            expect(requestMock).toHaveBeenCalledWith({
+                url: `/api/v2/views`
+            });
+            expect(result).toEqual([viewSample]);
+        });
+    });
+
+    describe("searchViews", () => {
+        const viewSample = {
+            active: true,
+            conditions: {},
+            created_at: "2023-01-01T00:00:00Z",
+            default: false,
+            description: "View for recent tickets",
+            execution: {},
+            id: 25,
+            position: 3,
+            restriction: {},
+            title: "Tickets updated less than 12 Hours",
+            updated_at: "2023-01-01T00:00:00Z"
+        };
+
+        const inactiveViewSample = {
+            active: false,
+            conditions: {},
+            created_at: "2023-01-01T00:00:00Z",
+            default: false,
+            description: "View for tickets that are not assigned",
+            execution: {},
+            id: 23,
+            position: 7,
+            restriction: {},
+            title: "Unassigned tickets",
+            updated_at: "2023-01-01T00:00:00Z"
+        };
+
+        it("should search views with query string", async () => {
+            requestMock.mockResolvedValueOnce({ views: [viewSample] });
+
+            const result = await service.searchViews("tickets");
+
+            expect(requestMock).toHaveBeenCalledWith({
+                url: `/api/v2/views/search?query=tickets`
+            });
+            expect(result).toEqual([viewSample]);
+        });
+
+        it("should search views with query string and access filter", async () => {
+            requestMock.mockResolvedValueOnce({ views: [viewSample] });
+
+            const result = await service.searchViews("tickets", { access: "shared" });
+
+            expect(requestMock).toHaveBeenCalledWith({
+                url: `/api/v2/views/search?query=tickets&access=shared`
+            });
+            expect(result).toEqual([viewSample]);
+        });
+
+        it("should search views with query string and active filter", async () => {
+            requestMock.mockResolvedValueOnce({ views: [viewSample] });
+
+            const result = await service.searchViews("tickets", { active: true });
+
+            expect(requestMock).toHaveBeenCalledWith({
+                url: `/api/v2/views/search?query=tickets&active=true`
+            });
+            expect(result).toEqual([viewSample]);
+        });
+
+        it("should search views with query string and group_id filter", async () => {
+            requestMock.mockResolvedValueOnce({ views: [viewSample] });
+
+            const result = await service.searchViews("tickets", { group_id: 123 });
+
+            expect(requestMock).toHaveBeenCalledWith({
+                url: `/api/v2/views/search?query=tickets&group_id=123`
+            });
+            expect(result).toEqual([viewSample]);
+        });
+
+        it("should search views with query string and sort parameters", async () => {
+            requestMock.mockResolvedValueOnce({ views: [viewSample] });
+
+            const result = await service.searchViews("tickets", { sort_by: "alphabetical", sort_order: "asc" });
+
+            expect(requestMock).toHaveBeenCalledWith({
+                url: `/api/v2/views/search?query=tickets&sort_by=alphabetical&sort_order=asc`
+            });
+            expect(result).toEqual([viewSample]);
+        });
+
+        it("should search views with all options", async () => {
+            requestMock.mockResolvedValueOnce({ views: [viewSample, inactiveViewSample] });
+
+            const result = await service.searchViews("tickets", {
+                access: "personal",
+                active: false,
+                group_id: 456,
+                include: "sideload",
+                sort_by: "updated_at",
+                sort_order: "desc"
+            });
+
+            expect(requestMock).toHaveBeenCalledWith({
+                url: `/api/v2/views/search?query=tickets&access=personal&active=false&group_id=456&include=sideload&sort_by=updated_at&sort_order=desc`
+            });
+            expect(result).toEqual([viewSample, inactiveViewSample]);
+        });
+
+        it("should continue calling the API until next_page disappears", async () => {
+            requestMock
+                .mockResolvedValueOnce({ views: [viewSample], next_page: "next_page" })
+                .mockResolvedValueOnce({ views: [inactiveViewSample] });
+
+            const result = await service.searchViews("tickets");
+
+            expect(requestMock).toHaveBeenCalledTimes(2);
+            expect(requestMock).toHaveBeenNthCalledWith(1, {
+                url: `/api/v2/views/search?query=tickets`
+            });
+            expect(requestMock).toHaveBeenNthCalledWith(2, {
+                url: "next_page"
+            });
+            expect(result).toEqual([viewSample, inactiveViewSample]);
+        });
+
+        it("should only call the API one time when fetchAllViews is false", async () => {
+            requestMock.mockResolvedValueOnce({ views: [viewSample], next_page: "next_page" });
+
+            const result = await service.searchViews("tickets", undefined, false);
+
+            expect(requestMock).toHaveBeenCalledTimes(1);
+            expect(requestMock).toHaveBeenCalledWith({
+                url: `/api/v2/views/search?query=tickets`
+            });
+            expect(result).toEqual([viewSample]);
+        });
+    });
 });

package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zendesk/zaf-toolbox",
-    "version": "1.3.1",
+    "version": "1.4.0",
     "description": "A toolbox for ZAF application built with 🩷 by Zendesk Labs",
     "main": "lib/src/index.js",
     "types": "lib/src/index.d.ts",

src/models/index.ts

@@ -9,3 +9,4 @@ export * from "@models/whats-app-template";
 export * from "@models/zendesk-user";
 export * from "@models/custom-objects";
 export * from "@models/zendesk-api";
+export * from "@models/zendesk-view";

src/models/zendesk-view.ts

@@ -0,0 +1,65 @@
+import { IZendeskResponse } from "./zendesk-api";
+
+interface IViewCondition {
+    field: string;
+    operator: string;
+    value: string | number | boolean;
+}
+
+export interface IViewConditions {
+    all?: IViewCondition[];
+    // eslint-disable-next-line id-denylist
+    any?: IViewCondition[];
+}
+
+export interface IViewColumn {
+    id: number | string;
+    title: string;
+    type: string;
+    url?: string;
+}
+
+export interface IViewGroup {
+    id: string;
+    title: string;
+    order: "asc" | "desc";
+}
+
+export interface IViewSort {
+    id: string;
+    title: string;
+    order: "asc" | "desc";
+}
+
+export interface IViewExecution {
+    group_by?: string;
+    sort_by?: string;
+    group_order?: "asc" | "desc";
+    sort_order?: "asc" | "desc";
+    columns: IViewColumn[];
+    group: IViewGroup;
+    sort: IViewSort;
+}
+
+export interface IViewRestriction {
+    type: string;
+    id: number;
+}
+
+export interface IZendeskView {
+    active: boolean;
+    conditions: IViewConditions;
+    created_at: string;
+    default: boolean;
+    description: string;
+    execution: IViewExecution;
+    id: number;
+    position: number;
+    restriction: IViewRestriction | null;
+    title: string;
+    updated_at: string;
+}
+
+export interface IViewsResponse extends IZendeskResponse {
+    views: IZendeskView[];
+}

src/services/zendesk-api-service.ts

@@ -30,8 +30,11 @@ import {
     ICreateAccessTokenResponse,
     IZendeskTicket,
     IBulkJobResponse,
-    ITicketsResults
+    ITicketsResults,
+    IZendeskView,
+    IViewsResponse
 } from "@models/index";
+import { buildUrlParams } from "@utils/build-url-params";
 import {
     ICreateConnectionResponse,
     ICreateInboundWebhookResponse,
@@ -615,4 +618,109 @@ export class ZendeskApiService {
             data: JSON.stringify(bundle)
         });
     }
+
+    /**
+     * VIEWS SECTION
+     */
+
+    /**
+     * Fetch views with optional filters
+     *
+     * @param options Query parameters for filtering views
+     * @param options.access Only views with given access. May be "personal", "shared", or "account"
+     * @param options.active Only active views if true, inactive views if false
+     * @param options.group_id Only views belonging to given group
+     * @param options.sort The sort parameter used with cursor pagination. Defaults to "created_at". Prefix with '-' for descending order
+     * @param options.sort_by The sort_by parameter used with offset pagination. Possible values are "alphabetical", "created_at", or "updated_at". Defaults to "position"
+     * @param options.sort_order The sort_order parameter used with offset pagination. One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others
+     * @param fetchAllViews Whether to fetch all pages or just the first. Defaults to true
+     * @returns Promise resolving to array of views
+     */
+    public async getViews(
+        options?: {
+            access?: "personal" | "shared" | "account";
+            active?: boolean;
+            group_id?: number;
+            sort?: string;
+            sort_by?: "alphabetical" | "created_at" | "updated_at";
+            sort_order?: "asc" | "desc";
+        },
+        fetchAllViews = true
+    ): Promise<IZendeskView[]> {
+        const queryParams = options ? buildUrlParams(options) : "";
+        const url = `/api/v2/views${queryParams ? `?${queryParams}` : ""}`;
+
+        return this.fetchAllPaginatedResults<IViewsResponse, IZendeskView>(
+            url,
+            fetchAllViews,
+            (response) => response.views
+        );
+    }
+
+    /**
+     * Fetch active views with optional filters
+     *
+     * @param options Query parameters for filtering active views
+     * @param options.access Only views with given access. May be "personal", "shared", or "account"
+     * @param options.group_id Only views belonging to given group
+     * @param options.sort_by Possible values are "alphabetical", "created_at", or "updated_at". Defaults to "position"
+     * @param options.sort_order One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others
+     * @param fetchAllViews Whether to fetch all pages or just the first. Defaults to true
+     * @returns Promise resolving to array of active views
+     */
+    public async getActiveViews(
+        options?: {
+            access?: "personal" | "shared" | "account";
+            group_id?: number;
+            sort_by?: "alphabetical" | "created_at" | "updated_at";
+            sort_order?: "asc" | "desc";
+        },
+        fetchAllViews = true
+    ): Promise<IZendeskView[]> {
+        const queryParams = options ? buildUrlParams(options) : "";
+        const url = `/api/v2/views/active${queryParams ? `?${queryParams}` : ""}`;
+
+        return this.fetchAllPaginatedResults<IViewsResponse, IZendeskView>(
+            url,
+            fetchAllViews,
+            (response) => response.views
+        );
+    }
+
+    /**
+     * Search views by query string with optional filters
+     *
+     * @param query Query string used to find all views with matching title
+     * @param options Query parameters for filtering search results
+     * @param options.access Filter views by access. May be "personal", "shared", or "account"
+     * @param options.active Filter by active views if true or inactive views if false
+     * @param options.group_id Filter views by group
+     * @param options.include A sideload to include in the response
+     * @param options.sort_by Possible values are "alphabetical", "created_at", "updated_at", and "position". If unspecified, views are sorted by relevance
+     * @param options.sort_order One of "asc" or "desc". Defaults to "asc" for alphabetical and position sort, "desc" for all others
+     * @param fetchAllViews Whether to fetch all pages or just the first. Defaults to true
+     * @returns Promise resolving to array of views matching the search query
+     */
+    public async searchViews(
+        query: string,
+        options?: {
+            access?: "personal" | "shared" | "account";
+            active?: boolean;
+            group_id?: number;
+            include?: string;
+            sort_by?: "alphabetical" | "created_at" | "updated_at" | "position";
+            sort_order?: "asc" | "desc";
+        },
+        fetchAllViews = true
+    ): Promise<IZendeskView[]> {
+        const params = { query, ...options };
+        const queryParams = buildUrlParams(params);
+        const url = `/api/v2/views/search?${queryParams}`;
+
+        return this.fetchAllPaginatedResults<IViewsResponse, IZendeskView>(
+            url,
+            fetchAllViews,
+            (response) => response.views
+        );
+    }
 }