@hasna/connectors 0.3.16 → 0.4.1

package/connectors/connect-zendesk/src/api/index.test.ts

@@ -0,0 +1,111 @@
+import { describe, test, expect } from 'bun:test';
+import { Zendesk } from './index';
+import { TicketsApi } from './tickets';
+import { UsersApi } from './users';
+import { OrganizationsApi } from './organizations';
+import { GroupsApi } from './groups';
+import { TicketFieldsApi } from './ticket-fields';
+import { ViewsApi } from './views';
+import { TriggersApi } from './triggers';
+import { AutomationsApi } from './automations';
+import { SlaPoliciesApi } from './slas';
+import { WebhooksApi } from './webhooks';
+import { MacrosApi } from './macros';
+import { BrandsApi } from './brands';
+
+describe('Zendesk', () => {
+  const mockConfig = {
+    email: 'test@example.com',
+    apiToken: 'test-api-token-12345',
+    baseUrl: 'https://test.zendesk.com/api/v2',
+  };
+
+  describe('constructor', () => {
+    test('creates instance with all API modules', () => {
+      const zendesk = new Zendesk(mockConfig);
+
+      // Core APIs
+      expect(zendesk.tickets).toBeInstanceOf(TicketsApi);
+      expect(zendesk.users).toBeInstanceOf(UsersApi);
+      expect(zendesk.organizations).toBeInstanceOf(OrganizationsApi);
+      expect(zendesk.groups).toBeInstanceOf(GroupsApi);
+
+      // Configuration APIs
+      expect(zendesk.ticketFields).toBeInstanceOf(TicketFieldsApi);
+      expect(zendesk.brands).toBeInstanceOf(BrandsApi);
+
+      // Business Rules APIs
+      expect(zendesk.views).toBeInstanceOf(ViewsApi);
+      expect(zendesk.triggers).toBeInstanceOf(TriggersApi);
+      expect(zendesk.automations).toBeInstanceOf(AutomationsApi);
+      expect(zendesk.slaPolicies).toBeInstanceOf(SlaPoliciesApi);
+      expect(zendesk.macros).toBeInstanceOf(MacrosApi);
+
+      // Integration APIs
+      expect(zendesk.webhooks).toBeInstanceOf(WebhooksApi);
+    });
+  });
+
+  describe('fromEnv', () => {
+    test('throws error when environment variables are missing', () => {
+      const originalEmail = process.env.ZENDESK_EMAIL;
+      const originalToken = process.env.ZENDESK_API_TOKEN;
+
+      delete process.env.ZENDESK_EMAIL;
+      delete process.env.ZENDESK_API_TOKEN;
+
+      expect(() => Zendesk.fromEnv()).toThrow('ZENDESK_EMAIL and ZENDESK_API_TOKEN environment variables are required');
+
+      // Restore
+      if (originalEmail) process.env.ZENDESK_EMAIL = originalEmail;
+      if (originalToken) process.env.ZENDESK_API_TOKEN = originalToken;
+    });
+
+    test('creates instance from environment variables', () => {
+      const originalEmail = process.env.ZENDESK_EMAIL;
+      const originalToken = process.env.ZENDESK_API_TOKEN;
+      const originalUrl = process.env.ZENDESK_BASE_URL;
+
+      process.env.ZENDESK_EMAIL = 'env@example.com';
+      process.env.ZENDESK_API_TOKEN = 'env-token-12345';
+      process.env.ZENDESK_BASE_URL = 'https://env.zendesk.com/api/v2';
+
+      const zendesk = Zendesk.fromEnv();
+
+      expect(zendesk).toBeInstanceOf(Zendesk);
+      expect(zendesk.getEmail()).toBe('env@example.com');
+
+      // Restore
+      if (originalEmail) process.env.ZENDESK_EMAIL = originalEmail;
+      else delete process.env.ZENDESK_EMAIL;
+      if (originalToken) process.env.ZENDESK_API_TOKEN = originalToken;
+      else delete process.env.ZENDESK_API_TOKEN;
+      if (originalUrl) process.env.ZENDESK_BASE_URL = originalUrl;
+      else delete process.env.ZENDESK_BASE_URL;
+    });
+  });
+
+  describe('getApiTokenPreview', () => {
+    test('returns masked token', () => {
+      const zendesk = new Zendesk(mockConfig);
+      const preview = zendesk.getApiTokenPreview();
+      expect(preview).toBe('test-a...2345');
+    });
+  });
+
+  describe('getEmail', () => {
+    test('returns configured email', () => {
+      const zendesk = new Zendesk(mockConfig);
+      expect(zendesk.getEmail()).toBe('test@example.com');
+    });
+  });
+
+  describe('getClient', () => {
+    test('returns the underlying client', () => {
+      const zendesk = new Zendesk(mockConfig);
+      const client = zendesk.getClient();
+      expect(client).toBeDefined();
+      expect(client.getEmail()).toBe('test@example.com');
+    });
+  });
+});

package/connectors/connect-zendesk/src/api/index.ts

@@ -0,0 +1,131 @@
+import type { ZendeskConfig } from '../types';
+import { ZendeskClient } from './client';
+import { TicketsApi } from './tickets';
+import { UsersApi } from './users';
+import { OrganizationsApi } from './organizations';
+import { GroupsApi } from './groups';
+import { TicketFieldsApi } from './ticket-fields';
+import { ViewsApi } from './views';
+import { TriggersApi } from './triggers';
+import { AutomationsApi } from './automations';
+import { SlaPoliciesApi } from './slas';
+import { WebhooksApi } from './webhooks';
+import { MacrosApi } from './macros';
+import { BrandsApi } from './brands';
+import { BulkApi } from './bulk';
+
+export class Zendesk {
+  private readonly client: ZendeskClient;
+
+  // Core APIs
+  public readonly tickets: TicketsApi;
+  public readonly users: UsersApi;
+  public readonly organizations: OrganizationsApi;
+  public readonly groups: GroupsApi;
+
+  // Configuration APIs
+  public readonly ticketFields: TicketFieldsApi;
+  public readonly brands: BrandsApi;
+
+  // Business Rules APIs
+  public readonly views: ViewsApi;
+  public readonly triggers: TriggersApi;
+  public readonly automations: AutomationsApi;
+  public readonly slaPolicies: SlaPoliciesApi;
+  public readonly macros: MacrosApi;
+
+  // Integration APIs
+  public readonly webhooks: WebhooksApi;
+
+  // Bulk Operations API
+  public readonly bulk: BulkApi;
+
+  constructor(config: ZendeskConfig) {
+    this.client = new ZendeskClient(config);
+
+    // Core APIs
+    this.tickets = new TicketsApi(this.client);
+    this.users = new UsersApi(this.client);
+    this.organizations = new OrganizationsApi(this.client);
+    this.groups = new GroupsApi(this.client);
+
+    // Configuration APIs
+    this.ticketFields = new TicketFieldsApi(this.client);
+    this.brands = new BrandsApi(this.client);
+
+    // Business Rules APIs
+    this.views = new ViewsApi(this.client);
+    this.triggers = new TriggersApi(this.client);
+    this.automations = new AutomationsApi(this.client);
+    this.slaPolicies = new SlaPoliciesApi(this.client);
+    this.macros = new MacrosApi(this.client);
+
+    // Integration APIs
+    this.webhooks = new WebhooksApi(this.client);
+
+    // Bulk Operations API
+    this.bulk = new BulkApi(this.client, this.tickets, this.users, this.ticketFields);
+  }
+
+  /**
+   * Create a Zendesk client from environment variables
+   * Looks for ZENDESK_EMAIL and ZENDESK_API_TOKEN
+   */
+  static fromEnv(): Zendesk {
+    const email = process.env.ZENDESK_EMAIL;
+    const apiToken = process.env.ZENDESK_API_TOKEN;
+    const baseUrl = process.env.ZENDESK_BASE_URL;
+
+    if (!email || !apiToken) {
+      throw new Error('ZENDESK_EMAIL and ZENDESK_API_TOKEN environment variables are required');
+    }
+
+    return new Zendesk({ email, apiToken, baseUrl });
+  }
+
+  /**
+   * Get a preview of the API token (for debugging)
+   */
+  getApiTokenPreview(): string {
+    return this.client.getApiTokenPreview();
+  }
+
+  /**
+   * Get the email address used for authentication
+   */
+  getEmail(): string {
+    return this.client.getEmail();
+  }
+
+  /**
+   * Get the underlying client for direct API access
+   */
+  getClient(): ZendeskClient {
+    return this.client;
+  }
+}
+
+export { ZendeskClient } from './client';
+export { TicketsApi } from './tickets';
+export { UsersApi } from './users';
+export { OrganizationsApi } from './organizations';
+export { GroupsApi } from './groups';
+export { TicketFieldsApi } from './ticket-fields';
+export { ViewsApi } from './views';
+export { TriggersApi } from './triggers';
+export { AutomationsApi } from './automations';
+export { SlaPoliciesApi } from './slas';
+export { WebhooksApi } from './webhooks';
+export { MacrosApi } from './macros';
+export { BrandsApi } from './brands';
+export { BulkApi, FilterParser } from './bulk';
+export type {
+  BulkUpdateOptions,
+  BulkUpdateResult,
+  BulkPreviewResult,
+  BulkSchema,
+  BulkResourceType,
+  ParsedFilter,
+  ParsedUpdate,
+  FieldSchema,
+} from './bulk';

package/connectors/connect-zendesk/src/api/macros.ts

@@ -0,0 +1,124 @@
+import type { ZendeskClient } from './client';
+import type {
+  ZendeskMacro,
+  ZendeskMacroResponse,
+  ZendeskMacrosResponse,
+  CreateMacroRequest,
+  UpdateMacroRequest,
+  MacroListParams,
+} from '../types';
+
+/**
+ * Zendesk Macros API
+ * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/
+ */
+export class MacrosApi {
+  constructor(private readonly client: ZendeskClient) {}
+
+  /**
+   * List all macros
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#list-macros
+   */
+  async list(params?: MacroListParams): Promise<ZendeskMacro[]> {
+    const response = await this.client.get<ZendeskMacrosResponse>('/macros.json', {
+      page: params?.page,
+      per_page: params?.per_page,
+      active: params?.active,
+      category: params?.category,
+      group_id: params?.group_id,
+      sort_by: params?.sort_by,
+      sort_order: params?.sort_order,
+    });
+    return response.macros;
+  }
+
+  /**
+   * List active macros
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#list-active-macros
+   */
+  async listActive(params?: MacroListParams): Promise<ZendeskMacro[]> {
+    const response = await this.client.get<ZendeskMacrosResponse>('/macros/active.json', {
+      page: params?.page,
+      per_page: params?.per_page,
+      category: params?.category,
+      group_id: params?.group_id,
+      sort_by: params?.sort_by,
+      sort_order: params?.sort_order,
+    });
+    return response.macros;
+  }
+
+  /**
+   * Get a macro by ID
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#show-macro
+   */
+  async get(macroId: number): Promise<ZendeskMacro> {
+    const response = await this.client.get<ZendeskMacroResponse>(`/macros/${macroId}.json`);
+    return response.macro;
+  }
+
+  /**
+   * Create a new macro
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#create-macro
+   */
+  async create(data: CreateMacroRequest): Promise<ZendeskMacro> {
+    const response = await this.client.post<ZendeskMacroResponse>('/macros.json', data);
+    return response.macro;
+  }
+
+  /**
+   * Update a macro
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#update-macro
+   */
+  async update(macroId: number, data: UpdateMacroRequest): Promise<ZendeskMacro> {
+    const response = await this.client.put<ZendeskMacroResponse>(`/macros/${macroId}.json`, data);
+    return response.macro;
+  }
+
+  /**
+   * Delete a macro
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#delete-macro
+   */
+  async delete(macroId: number): Promise<void> {
+    await this.client.delete(`/macros/${macroId}.json`);
+  }
+
+  /**
+   * Apply a macro to a ticket (preview)
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#show-changes-to-ticket
+   */
+  async apply(macroId: number, ticketId: number): Promise<{ result: { ticket: unknown; comment: unknown } }> {
+    return this.client.get(`/macros/${macroId}/apply.json`, { ticket_id: ticketId });
+  }
+
+  /**
+   * Search macros by title
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#search-macros
+   */
+  async search(query: string, params?: MacroListParams): Promise<ZendeskMacro[]> {
+    const response = await this.client.get<ZendeskMacrosResponse>('/macros/search.json', {
+      query,
+      page: params?.page,
+      per_page: params?.per_page,
+      active: params?.active,
+    });
+    return response.macros;
+  }
+
+  /**
+   * List macro categories
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#list-macro-categories
+   */
+  async listCategories(): Promise<{ categories: string[] }> {
+    return this.client.get('/macros/categories.json');
+  }
+
+  /**
+   * List macros applicable to a ticket
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/macros/#list-macros-applicable-to-a-ticket
+   */
+  async listApplicable(ticketId: number): Promise<ZendeskMacro[]> {
+    const response = await this.client.get<ZendeskMacrosResponse>(`/tickets/${ticketId}/macros.json`);
+    return response.macros;
+  }
+}

package/connectors/connect-zendesk/src/api/organizations.ts

@@ -0,0 +1,85 @@
+import type { ZendeskClient } from './client';
+import type {
+  ZendeskOrganization,
+  ZendeskOrganizationResponse,
+  ZendeskOrganizationsResponse,
+  CreateOrganizationRequest,
+  OrganizationListParams,
+} from '../types';
+
+/**
+ * Zendesk Organizations API
+ * @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/
+ */
+export class OrganizationsApi {
+  constructor(private readonly client: ZendeskClient) {}
+
+  /**
+   * List all organizations
+   * @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#list-organizations
+   */
+  async list(params?: OrganizationListParams): Promise<ZendeskOrganization[]> {
+    const response = await this.client.get<ZendeskOrganizationsResponse>('/organizations.json', {
+      page: params?.page,
+      per_page: params?.per_page,
+    });
+    return response.organizations;
+  }
+
+  /**
+   * Get an organization by ID
+   * @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#show-organization
+   */
+  async get(organizationId: number): Promise<ZendeskOrganization> {
+    const response = await this.client.get<ZendeskOrganizationResponse>(`/organizations/${organizationId}.json`);
+    return response.organization;
+  }
+
+  /**
+   * Create a new organization
+   * @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#create-organization
+   */
+  async create(data: CreateOrganizationRequest): Promise<ZendeskOrganization> {
+    const response = await this.client.post<ZendeskOrganizationResponse>('/organizations.json', data);
+    return response.organization;
+  }
+
+  /**
+   * Update an organization
+   * @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#update-organization
+   */
+  async update(organizationId: number, data: Partial<CreateOrganizationRequest>): Promise<ZendeskOrganization> {
+    const response = await this.client.put<ZendeskOrganizationResponse>(`/organizations/${organizationId}.json`, data);
+    return response.organization;
+  }
+
+  /**
+   * Delete an organization
+   * @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#delete-organization
+   */
+  async delete(organizationId: number): Promise<void> {
+    await this.client.delete(`/organizations/${organizationId}.json`);
+  }
+
+  /**
+   * Search organizations
+   * @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#autocomplete-organizations
+   */
+  async search(name: string): Promise<ZendeskOrganization[]> {
+    const response = await this.client.get<ZendeskOrganizationsResponse>('/organizations/autocomplete.json', {
+      name,
+    });
+    return response.organizations;
+  }
+
+  /**
+   * Get organization by external ID
+   * @see https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#show-organization
+   */
+  async getByExternalId(externalId: string): Promise<ZendeskOrganization[]> {
+    const response = await this.client.get<ZendeskOrganizationsResponse>('/organizations/search.json', {
+      external_id: externalId,
+    });
+    return response.organizations;
+  }
+}

package/connectors/connect-zendesk/src/api/slas.ts

@@ -0,0 +1,80 @@
+import type { ZendeskClient } from './client';
+import type {
+  ZendeskSlaPolicy,
+  ZendeskSlaPolicyResponse,
+  ZendeskSlaPoliciesResponse,
+  CreateSlaPolicyRequest,
+  UpdateSlaPolicyRequest,
+  SlaListParams,
+} from '../types';
+
+/**
+ * Zendesk SLA Policies API
+ * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/sla_policies/
+ */
+export class SlaPoliciesApi {
+  constructor(private readonly client: ZendeskClient) {}
+
+  /**
+   * List all SLA policies
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/sla_policies/#list-sla-policies
+   */
+  async list(params?: SlaListParams): Promise<ZendeskSlaPolicy[]> {
+    const response = await this.client.get<ZendeskSlaPoliciesResponse>('/slas/policies.json', {
+      page: params?.page,
+      per_page: params?.per_page,
+    });
+    return response.sla_policies;
+  }
+
+  /**
+   * Get an SLA policy by ID
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/sla_policies/#show-sla-policy
+   */
+  async get(slaPolicyId: number): Promise<ZendeskSlaPolicy> {
+    const response = await this.client.get<ZendeskSlaPolicyResponse>(`/slas/policies/${slaPolicyId}.json`);
+    return response.sla_policy;
+  }
+
+  /**
+   * Create a new SLA policy
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/sla_policies/#create-sla-policy
+   */
+  async create(data: CreateSlaPolicyRequest): Promise<ZendeskSlaPolicy> {
+    const response = await this.client.post<ZendeskSlaPolicyResponse>('/slas/policies.json', data);
+    return response.sla_policy;
+  }
+
+  /**
+   * Update an SLA policy
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/sla_policies/#update-sla-policy
+   */
+  async update(slaPolicyId: number, data: UpdateSlaPolicyRequest): Promise<ZendeskSlaPolicy> {
+    const response = await this.client.put<ZendeskSlaPolicyResponse>(`/slas/policies/${slaPolicyId}.json`, data);
+    return response.sla_policy;
+  }
+
+  /**
+   * Delete an SLA policy
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/sla_policies/#delete-sla-policy
+   */
+  async delete(slaPolicyId: number): Promise<void> {
+    await this.client.delete(`/slas/policies/${slaPolicyId}.json`);
+  }
+
+  /**
+   * Reorder SLA policies
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/sla_policies/#reorder-sla-policies
+   */
+  async reorder(slaPolicyIds: number[]): Promise<void> {
+    await this.client.put('/slas/policies/reorder.json', { sla_policy_ids: slaPolicyIds });
+  }
+
+  /**
+   * Get SLA policy filter definitions
+   * @see https://developer.zendesk.com/api-reference/ticketing/business-rules/sla_policies/#retrieve-supported-filter-definition-items
+   */
+  async getFilterDefinitions(): Promise<{ definitions: { conditions_all: unknown[]; conditions_any: unknown[] } }> {
+    return this.client.get('/slas/policies/definitions.json');
+  }
+}

package/connectors/connect-zendesk/src/api/ticket-fields.ts

@@ -0,0 +1,98 @@
+import type { ZendeskClient } from './client';
+import type {
+  ZendeskTicketField,
+  ZendeskTicketFieldResponse,
+  ZendeskTicketFieldsResponse,
+  CreateTicketFieldRequest,
+  UpdateTicketFieldRequest,
+  TicketFieldListParams,
+} from '../types';
+
+/**
+ * Zendesk Ticket Fields API
+ * @see https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/
+ */
+export class TicketFieldsApi {
+  constructor(private readonly client: ZendeskClient) {}
+
+  /**
+   * List all ticket fields
+   * @see https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#list-ticket-fields
+   */
+  async list(params?: TicketFieldListParams): Promise<ZendeskTicketField[]> {
+    const response = await this.client.get<ZendeskTicketFieldsResponse>('/ticket_fields.json', {
+      page: params?.page,
+      per_page: params?.per_page,
+    });
+    return response.ticket_fields;
+  }
+
+  /**
+   * Get a ticket field by ID
+   * @see https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#show-ticket-field
+   */
+  async get(ticketFieldId: number): Promise<ZendeskTicketField> {
+    const response = await this.client.get<ZendeskTicketFieldResponse>(`/ticket_fields/${ticketFieldId}.json`);
+    return response.ticket_field;
+  }
+
+  /**
+   * Create a new ticket field
+   * @see https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#create-ticket-field
+   */
+  async create(data: CreateTicketFieldRequest): Promise<ZendeskTicketField> {
+    const response = await this.client.post<ZendeskTicketFieldResponse>('/ticket_fields.json', data);
+    return response.ticket_field;
+  }
+
+  /**
+   * Update a ticket field
+   * @see https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#update-ticket-field
+   */
+  async update(ticketFieldId: number, data: UpdateTicketFieldRequest): Promise<ZendeskTicketField> {
+    const response = await this.client.put<ZendeskTicketFieldResponse>(`/ticket_fields/${ticketFieldId}.json`, data);
+    return response.ticket_field;
+  }
+
+  /**
+   * Delete a ticket field
+   * @see https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#delete-ticket-field
+   */
+  async delete(ticketFieldId: number): Promise<void> {
+    await this.client.delete(`/ticket_fields/${ticketFieldId}.json`);
+  }
+
+  /**
+   * List ticket field options (for dropdown fields)
+   * @see https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#list-ticket-field-options
+   */
+  async listOptions(ticketFieldId: number): Promise<Array<{ id: number; name: string; value: string }>> {
+    const response = await this.client.get<{ custom_field_options: Array<{ id: number; name: string; value: string }> }>(
+      `/ticket_fields/${ticketFieldId}/options.json`
+    );
+    return response.custom_field_options;
+  }
+
+  /**
+   * Create or update a ticket field option
+   * @see https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#create-or-update-ticket-field-option
+   */
+  async createOrUpdateOption(
+    ticketFieldId: number,
+    option: { name: string; value: string }
+  ): Promise<{ id: number; name: string; value: string }> {
+    const response = await this.client.post<{ custom_field_option: { id: number; name: string; value: string } }>(
+      `/ticket_fields/${ticketFieldId}/options.json`,
+      { custom_field_option: option }
+    );
+    return response.custom_field_option;
+  }
+
+  /**
+   * Delete a ticket field option
+   * @see https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_fields/#delete-ticket-field-option
+   */
+  async deleteOption(ticketFieldId: number, optionId: number): Promise<void> {
+    await this.client.delete(`/ticket_fields/${ticketFieldId}/options/${optionId}.json`);
+  }
+}