Merge pull request #289 from prezly/feature/dev-12883-tag-creator-las…

…t_modified_user-created_at-updated_at

[DEV-12883] Feature - Declare Contact Tags API + extend it

src/Client.ts

@@ -1,12 +1,13 @@
 import type { DeferredJobsApiClient } from './api';
 import { createApiClient, createDeferredJobsApiClient, type Fetch } from './api';
-import { Contacts } from './endpoints';
 import {
     Accounts,
     Billing,
     NewsroomSubscriptions,
     Campaigns,
     CampaignRecipients,
+    Contacts,
+    ContactTags,
     ContactsExports,
     Coverage,
     Jobs,
@@ -47,6 +48,7 @@ export interface Client {
     campaigns: Campaigns.Client;
     campaignRecipients: CampaignRecipients.Client;
     contacts: Contacts.Client;
+    contactTags: ContactTags.Client;
     contactsExports: ContactsExports.Client;
     coverage: Coverage.Client;
     jobs: Jobs.Client;
@@ -93,6 +95,7 @@ export function createClient({
         campaigns: Campaigns.createClient(api),
         campaignRecipients: CampaignRecipients.createClient(api),
         contacts: Contacts.createClient(api),
+        contactTags: ContactTags.createClient(api),
         contactsExports: ContactsExports.createClient(api),
         coverage: Coverage.createClient(api),
         jobs: Jobs.createClient(api),

src/endpoints/ContactTags/Client.ts

@@ -0,0 +1,138 @@
+import type { DeferredJobsApiClient } from '../../api';
+import { routing } from '../../routing';
+import { type Contact, type ContactTag, Query } from '../../types';
+import { SortOrder } from '../../types';
+
+import type {
+    CreateOptions,
+    CreateRequest,
+    CreateResponse,
+    ListOptions,
+    ListResponse,
+    MergeRequest,
+    MergeResponse,
+    SearchOptions,
+    SearchResponse,
+    UpdateOptions,
+    UpdateRequest,
+    UpdateResponse,
+} from './types';
+
+export type Client = ReturnType<typeof createClient>;
+
+// Not putting these into the `./types` module to keep it local.
+type RawModificationResponse = {
+    tag: ContactTag;
+    deleted_tags_ids: ContactTag['id'][];
+};
+type RawDeleteResponse = {
+    deleted_tags_ids: ContactTag['id'][];
+};
+
+export function createClient(api: DeferredJobsApiClient) {
+    async function list(options: ListOptions = {}): Promise<ListResponse> {
+        const { sortOrder } = options;
+        const { tags } = await api.get<{
+            tags: ContactTag[];
+        }>(routing.contactsTagsUrl, {
+            query: {
+                sort: SortOrder.stringify(sortOrder),
+            },
+        });
+
+        return { tags };
+    }
+
+    async function search(options: SearchOptions = {}): Promise<SearchResponse> {
+        const { query, sortOrder } = options;
+        const { tags } = await api.post<{
+            tags: ContactTag[];
+        }>(routing.contactsTagsUrl, {
+            query: {
+                sort: SortOrder.stringify(sortOrder),
+                query: Query.stringify(query),
+            },
+        });
+
+        return { tags };
+    }
+
+    async function get(id: ContactTag['id']): Promise<ContactTag> {
+        const url = `${routing.contactsTagsUrl}/${id}`;
+        const { tag } = await api.get<{ tag: ContactTag }>(url);
+
+        return tag;
+    }
+
+    async function create(
+        payload: CreateRequest,
+        { force = false }: CreateOptions = {},
+    ): Promise<CreateResponse> {
+        const data = await api.post<RawModificationResponse>(routing.contactsTagsUrl, {
+            payload,
+            query: {
+                force: force || undefined, // Convert `false` to `undefined`
+            },
+        });
+        return {
+            tag: data.tag,
+            deleted: data.deleted_tags_ids,
+        };
+    }
+
+    async function update(
+        id: Contact['id'],
+        payload: UpdateRequest,
+        { force = false }: UpdateOptions = {},
+    ): Promise<UpdateResponse> {
+        const url = `${routing.contactsTagsUrl}/${id}`;
+        const data = await api.patch<RawModificationResponse>(url, {
+            payload,
+            query: {
+                force: force || undefined, // Convert `false` to `undefined`
+            },
+        });
+        return {
+            tag: data.tag,
+            deleted: data.deleted_tags_ids,
+        };
+    }
+
+    async function merge({ name, tags }: MergeRequest): Promise<MergeResponse> {
+        const url = `${routing.contactsTagsUrl}/merge`;
+        const data = await api.post<RawModificationResponse>(url, {
+            payload: { name, tags },
+        });
+        return {
+            tag: data.tag,
+            deleted: data.deleted_tags_ids,
+        };
+    }
+
+    async function doDelete(id: ContactTag['id']) {
+        const url = `${routing.contactsTagsUrl}/${id}`;
+        const data = await api.delete<RawDeleteResponse>(url);
+        return { deleted: data.deleted_tags_ids };
+    }
+
+    async function doDeleteUnused() {
+        const data = await api.delete<RawDeleteResponse>(routing.contactsTagsUrl, {
+            query: {
+                filter: 'unused',
+            },
+        });
+
+        return { deleted: data.deleted_tags_ids };
+    }
+
+    return {
+        list,
+        search,
+        get,
+        create,
+        update,
+        merge,
+        delete: doDelete,
+        deleteUnused: doDeleteUnused,
+    };
+}

src/endpoints/ContactTags/index.ts

@@ -0,0 +1,2 @@
+export * from './Client';
+export * from './types';

src/endpoints/ContactTags/types.ts

@@ -0,0 +1,52 @@
+import type { ContactTag, Query } from '../../types';
+import type { SortOrder } from '../../types';
+
+export interface ListOptions {
+    sortOrder?: SortOrder | string;
+}
+
+export interface ListResponse {
+    tags: ContactTag[];
+}
+
+export interface SearchOptions extends ListOptions {
+    query?: Query;
+}
+
+export type SearchResponse = ListResponse;
+
+export interface CreateRequest {
+    name: string;
+}
+
+export interface CreateOptions {
+    force?: boolean;
+}
+
+export interface CreateResponse {
+    tag: ContactTag;
+    deleted: ContactTag['id'][];
+}
+
+export interface UpdateRequest {
+    name: string;
+}
+
+export interface UpdateOptions {
+    force?: boolean;
+}
+
+export interface UpdateResponse {
+    tag: ContactTag;
+    deleted: ContactTag['id'][];
+}
+
+export interface MergeRequest {
+    name: string;
+    tags: ContactTag.Identifier[];
+}
+
+export interface MergeResponse {
+    tag: ContactTag;
+    deleted: ContactTag['id'][];
+}

src/endpoints/Contacts/Client.ts

@@ -2,7 +2,7 @@ import type { ProgressPromise } from '@prezly/progress-promise';
 
 import type { DeferredJobsApiClient } from '../../api';
 import { routing } from '../../routing';
-import type { Contact, Pagination } from '../../types';
+import type { ContactTag, Contact, Pagination } from '../../types';
 import { SortOrder } from '../../types';
 
 import type {
@@ -16,16 +16,13 @@ import type {
     UpdateRequest,
 } from './types';
 
-type TagId = number;
-type TagName = string;
-
 export type Client = ReturnType<typeof createClient>;
 
 export function createClient(api: DeferredJobsApiClient) {
     /**
      * List Contacts Exports with sorting, and pagination.
      */
-    async function list(options: ListOptions): Promise<ListResponse> {
+    async function list(options: ListOptions = {}): Promise<ListResponse> {
         const { limit, offset, sortOrder } = options;
         const { contacts, pagination, sort } = await api.get<{
             contacts: Contact[];
@@ -45,7 +42,7 @@ export function createClient(api: DeferredJobsApiClient) {
     /**
      * List Contacts Exports with sorting, pagination, and filtering.
      */
-    async function search(options: SearchOptions): Promise<SearchResponse> {
+    async function search(options: SearchOptions = {}): Promise<SearchResponse> {
         const { limit, offset, query, sortOrder } = options;
         const url = `${routing.contactsUrl}/search`;
         const { contacts, pagination, sort } = await api.post<{
@@ -95,7 +92,7 @@ export function createClient(api: DeferredJobsApiClient) {
         return contact;
     }
 
-    async function tag(id: Contact['id'], tags: (TagId | TagName)[]): Promise<Contact> {
+    async function tag(id: Contact['id'], tags: ContactTag.Identifier[]): Promise<Contact> {
         const url = `${routing.contactsUrl}/${id}`;
         const { contact } = await api.patch<{ contact: Contact }>(url, {
             payload: {
@@ -105,7 +102,7 @@ export function createClient(api: DeferredJobsApiClient) {
         return contact;
     }
 
-    async function untag(id: Contact['id'], tags: (TagId | TagName)[]): Promise<Contact> {
+    async function untag(id: Contact['id'], tags: ContactTag.Identifier[]): Promise<Contact> {
         const url = `${routing.contactsUrl}/${id}`;
         const { contact } = await api.patch<{ contact: Contact }>(url, {
             payload: {
@@ -117,7 +114,7 @@ export function createClient(api: DeferredJobsApiClient) {
 
     async function bulkTag(
         selector: BulkSelector,
-        tags: (TagId | TagName)[],
+        tags: ContactTag.Identifier[],
     ): ProgressPromise<undefined> {
         const { scope, query } = selector;
         return api.patch(routing.contactsUrl, {
@@ -127,7 +124,7 @@ export function createClient(api: DeferredJobsApiClient) {
 
     async function bulkUntag(
         selector: BulkSelector,
-        tags: (TagId | TagName)[],
+        tags: ContactTag.Identifier[],
     ): ProgressPromise<undefined> {
         const { query, scope } = selector;
         return api.patch(routing.contactsUrl, {

src/endpoints/index.ts

@@ -2,6 +2,7 @@ export * as Accounts from './Accounts';
 export * as Billing from './Billing';
 export * as CampaignRecipients from './CampaignRecipients';
 export * as Campaigns from './Campaigns';
+export * as ContactTags from './ContactTags';
 export * as Contacts from './Contacts';
 export * as ContactsExports from './ContactsExports';
 export * as Coverage from './Coverage';

src/routing.ts

@@ -5,6 +5,7 @@ export const routing = {
     campaignRecipientsUrl: '/v2/campaigns/:campaign_id/recipients',
     contactsExportsUrl: '/v2/contacts/exports',
     contactsUrl: '/v2/contacts',
+    contactsTagsUrl: '/v2/contacts-tags',
     coverageUrl: '/v2/coverage',
     jobsUrl: '/v2/jobs',
     licenseUrl: '/v2/licenses',

src/types/ContactTag.ts

@@ -0,0 +1,18 @@
+import type { UserRef } from './User';
+
+type Iso8601DateTime = string;
+
+export interface ContactTag {
+    id: number;
+    name: string;
+    contacts_number: number;
+    contacts_url: string;
+    created_at: Iso8601DateTime | undefined; // May be undefined for older tags
+    updated_at: Iso8601DateTime | undefined; // May be undefined for older tags
+    creator: UserRef | undefined; // May be undefined for older tags
+    last_updated_by_user: UserRef | undefined; // May be undefined for older tags
+}
+
+export namespace ContactTag {
+    export type Identifier = ContactTag['id'] | ContactTag['name'];
+}

src/types/index.ts

@@ -6,6 +6,7 @@ export * from './Campaign';
 export * from './Category';
 export * from './Contact';
 export * from './ContactDuplicateSuggestion';
+export * from './ContactTag';
 export * from './ContactsBulkSelector';
 export * from './ContactsExport';
 export * from './ContactsScope';