@rawdash/connector-zendesk 0.0.1

package/dist/index.js

@@ -0,0 +1,696 @@
+// ../../connector-shared/dist/index.js
+var HTTP_CLIENT_VERSION = "0.0.0";
+var DEFAULT_USER_AGENT = `rawdash-connector/${HTTP_CLIENT_VERSION} (+https://rawdash.dev)`;
+function connectorUserAgent(connectorId) {
+  return `rawdash-connector-${connectorId}/${HTTP_CLIENT_VERSION} (+https://rawdash.dev)`;
+}
+function parseEpoch(value, unit) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (unit === "iso") {
+    if (typeof value !== "string") {
+      return null;
+    }
+    const ms = new Date(value).getTime();
+    return Number.isFinite(ms) ? ms : null;
+  }
+  if (typeof value === "string" && value.trim() === "") {
+    return null;
+  }
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n)) {
+    return null;
+  }
+  const result = unit === "s" ? n * 1e3 : n;
+  return Number.isFinite(result) ? result : null;
+}
+
+// src/zendesk.ts
+import {
+  BaseConnector,
+  defineConfigFields,
+  defineConnectorDoc,
+  defineResources,
+  makeChunkedCursorGuard,
+  paginateChunked,
+  schemasFromResources,
+  selectActivePhases
+} from "@rawdash/core";
+import { z } from "zod";
+var configFields = defineConfigFields(
+  z.object({
+    subdomain: z.string().trim().min(1).regex(
+      /^[a-z0-9][a-z0-9-]*$/i,
+      'Use the subdomain only (e.g. "acme" for acme.zendesk.com), without the protocol or path.'
+    ).meta({
+      label: "Account subdomain",
+      description: 'Your Zendesk account subdomain, the "acme" in acme.zendesk.com.',
+      placeholder: "acme"
+    }),
+    email: z.string().trim().email().meta({
+      label: "Agent email",
+      description: "Email address of an agent (or admin) on the Zendesk account; paired with the API token for Basic auth.",
+      placeholder: "agent@acme.com"
+    }),
+    apiToken: z.object({ $secret: z.string() }).meta({
+      label: "API token",
+      description: "Zendesk API token. Create one in Admin Center -> Apps and integrations -> Zendesk API -> Settings -> Add API token.",
+      placeholder: "aB1c2D3...",
+      secret: true
+    }),
+    resources: z.array(
+      z.enum([
+        "users",
+        "groups",
+        "tickets",
+        "ticket_events",
+        "satisfaction_ratings"
+      ])
+    ).nonempty().optional().meta({
+      label: "Resources",
+      description: "Which Zendesk resources to sync. Omit to sync all of them. The API token only needs read scopes for the resources listed here."
+    })
+  })
+);
+var doc = defineConnectorDoc({
+  displayName: "Zendesk",
+  category: "support",
+  brandColor: "#03363D",
+  tagline: "Sync tickets, ticket state-change events, satisfaction ratings, users, and groups from Zendesk Support for queue depth, response time, and CSAT analytics.",
+  vendor: {
+    name: "Zendesk",
+    apiDocs: "https://developer.zendesk.com/api-reference/ticketing/introduction/",
+    website: "https://www.zendesk.com"
+  },
+  auth: {
+    summary: "HTTP Basic auth using an agent (or admin) email address paired with a Zendesk API token. The token must belong to an account with read access to tickets, users, and groups.",
+    setup: [
+      "Open Admin Center -> Apps and integrations -> Zendesk API.",
+      "On the Settings tab, enable Token access if it is not already on.",
+      "Click Add API token, give it a label, and copy the generated token value (you cannot view it again).",
+      'Store the token as a secret and reference it from config as `apiToken: secret("ZENDESK_API_TOKEN")`, alongside the agent email and your account subdomain (the "acme" in acme.zendesk.com).'
+    ]
+  },
+  rateLimit: "Zendesk Support API enforces per-account quotas (default ~700 requests/minute on Professional plans, higher on Enterprise) and signals throttling via 429 with a Retry-After header; the shared HTTP client honors Retry-After on backoff.",
+  limitations: [
+    "Ticket comment bodies and per-event audit transcripts are not synced.",
+    "Zendesk Chat, Talk (voice), and Sell are separate product lines and are out of scope.",
+    "Ticket state-change events are derived from each ticket\u2019s timestamps (created, updated, solved); full audit-event history is not synced."
+  ]
+});
+var zendeskCredentials = {
+  email: {
+    description: "Zendesk agent email",
+    auth: "required"
+  },
+  apiToken: {
+    description: "Zendesk API token",
+    auth: "required"
+  }
+};
+var PHASE_ORDER = [
+  "users",
+  "groups",
+  "tickets",
+  "ticket_events",
+  "satisfaction_ratings"
+];
+var isZendeskSyncCursor = makeChunkedCursorGuard(PHASE_ORDER);
+var PAGE_SIZE = 100;
+var INCREMENTAL_PAGE_SIZE = 1e3;
+var USER_ENTITY = "zendesk_user";
+var GROUP_ENTITY = "zendesk_group";
+var TICKET_ENTITY = "zendesk_ticket";
+var TICKET_STATE_EVENT = "zendesk_ticket_state_change";
+var SATISFACTION_RATING_ENTITY = "zendesk_satisfaction_rating";
+var idNumber = z.number();
+var isoString = z.string();
+var userSchema = z.object({
+  id: idNumber,
+  name: z.string().nullish(),
+  email: z.string().nullish(),
+  role: z.string().nullish(),
+  active: z.boolean().nullish(),
+  suspended: z.boolean().nullish(),
+  default_group_id: z.number().nullish(),
+  created_at: isoString.nullish(),
+  updated_at: isoString.nullish()
+});
+var groupSchema = z.object({
+  id: idNumber,
+  name: z.string().nullish(),
+  default: z.boolean().nullish(),
+  deleted: z.boolean().nullish(),
+  created_at: isoString.nullish(),
+  updated_at: isoString.nullish()
+});
+var ticketSchema = z.object({
+  id: idNumber,
+  subject: z.string().nullish(),
+  status: z.string().nullish(),
+  priority: z.string().nullish(),
+  type: z.string().nullish(),
+  channel: z.string().nullish(),
+  assignee_id: z.number().nullish(),
+  requester_id: z.number().nullish(),
+  submitter_id: z.number().nullish(),
+  group_id: z.number().nullish(),
+  organization_id: z.number().nullish(),
+  tags: z.array(z.string()).nullish(),
+  via: z.object({ channel: z.string().nullish() }).nullish(),
+  satisfaction_rating: z.object({ score: z.string().nullish() }).nullish(),
+  created_at: isoString.nullish(),
+  updated_at: isoString.nullish()
+});
+var satisfactionRatingSchema = z.object({
+  id: idNumber,
+  score: z.string().nullish(),
+  ticket_id: z.number().nullish(),
+  assignee_id: z.number().nullish(),
+  requester_id: z.number().nullish(),
+  group_id: z.number().nullish(),
+  comment: z.string().nullish(),
+  created_at: isoString.nullish(),
+  updated_at: isoString.nullish()
+});
+function numericIdOrNull(value) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  return String(value);
+}
+function isoToMs(value) {
+  return parseEpoch(value ?? null, "iso");
+}
+function isoToMsOrZero(value) {
+  return isoToMs(value) ?? 0;
+}
+function viaChannel(ticket) {
+  return ticket.via?.channel ?? ticket.channel ?? null;
+}
+function csatScore(ticket) {
+  return ticket.satisfaction_rating?.score ?? null;
+}
+var zendeskResources = defineResources({
+  [USER_ENTITY]: {
+    shape: "entity",
+    description: "Zendesk users (agents, admins, and end-users) with role and activity flags.",
+    endpoint: "GET /api/v2/users.json",
+    fields: [
+      { name: "name", description: "User display name." },
+      { name: "email", description: "User email address." },
+      {
+        name: "role",
+        description: "User role (end-user, agent, or admin)."
+      },
+      { name: "active", description: "Whether the user is active." },
+      { name: "suspended", description: "Whether the user is suspended." },
+      {
+        name: "defaultGroupId",
+        description: "Default group the user belongs to (agents only)."
+      },
+      {
+        name: "createdAt",
+        description: "When the user was created (Unix ms)."
+      }
+    ],
+    responses: { users: z.array(userSchema) }
+  },
+  [GROUP_ENTITY]: {
+    shape: "entity",
+    description: "Agent groups used to route tickets.",
+    endpoint: "GET /api/v2/groups.json",
+    fields: [
+      { name: "name", description: "Group name." },
+      {
+        name: "isDefault",
+        description: "Whether this is the account default group."
+      },
+      { name: "deleted", description: "Whether the group is soft-deleted." },
+      {
+        name: "createdAt",
+        description: "When the group was created (Unix ms)."
+      }
+    ],
+    responses: { groups: z.array(groupSchema) }
+  },
+  [TICKET_ENTITY]: {
+    shape: "entity",
+    description: "Tickets with status, priority, assignment, channel, and tags.",
+    endpoint: "GET /api/v2/incremental/tickets/cursor.json",
+    fields: [
+      { name: "subject", description: "Ticket subject line." },
+      {
+        name: "status",
+        description: "Ticket status (new, open, pending, hold, solved, closed)."
+      },
+      {
+        name: "priority",
+        description: "Ticket priority (low, normal, high, urgent)."
+      },
+      { name: "type", description: "Ticket type (question, incident, etc.)." },
+      {
+        name: "channel",
+        description: "Channel the ticket was created from (email, web, etc.)."
+      },
+      {
+        name: "assigneeId",
+        description: "Assigned agent id (null if unassigned)."
+      },
+      { name: "requesterId", description: "Requester (end-user) id." },
+      {
+        name: "groupId",
+        description: "Group the ticket is routed to (null if unrouted)."
+      },
+      {
+        name: "organizationId",
+        description: "Organization id (null if none)."
+      },
+      {
+        name: "tags",
+        description: "Flat list of tags applied to the ticket."
+      },
+      {
+        name: "satisfactionScore",
+        description: "Per-ticket CSAT score from the satisfaction_rating block (offered, good, bad, unoffered)."
+      },
+      {
+        name: "createdAt",
+        description: "When the ticket was created (Unix ms)."
+      }
+    ],
+    responses: { tickets: z.array(ticketSchema) }
+  },
+  [TICKET_STATE_EVENT]: {
+    shape: "event",
+    description: "Ticket state-change events (created / solved) derived from each ticket.",
+    endpoint: "GET /api/v2/incremental/tickets/cursor.json",
+    notes: "Derived from each ticket\u2019s timestamps; the scope is cleared and rewritten on every sync.",
+    fields: [
+      {
+        name: "ticketId",
+        description: "The ticket the event belongs to."
+      },
+      {
+        name: "transition",
+        description: "created or solved."
+      },
+      {
+        name: "status",
+        description: "Ticket status at sync time."
+      },
+      {
+        name: "priority",
+        description: "Ticket priority at sync time."
+      },
+      {
+        name: "assigneeId",
+        description: "Assigned agent id at sync time (null if unassigned)."
+      },
+      {
+        name: "groupId",
+        description: "Group id at sync time (null if unrouted)."
+      },
+      { name: "channel", description: "Channel the ticket was created from." }
+    ],
+    responses: { ticket_events: z.array(ticketSchema) }
+  },
+  [SATISFACTION_RATING_ENTITY]: {
+    shape: "entity",
+    description: "Per-ticket customer satisfaction (CSAT) ratings with score and free-text comment.",
+    endpoint: "GET /api/v2/satisfaction_ratings.json",
+    fields: [
+      { name: "score", description: "Rating score (good, bad, offered)." },
+      { name: "ticketId", description: "The ticket the rating is for." },
+      {
+        name: "assigneeId",
+        description: "Agent assigned at the time of rating."
+      },
+      { name: "requesterId", description: "Requester (end-user) id." },
+      { name: "groupId", description: "Group id at the time of rating." },
+      {
+        name: "hasComment",
+        description: "Whether a free-text comment is set."
+      },
+      {
+        name: "createdAt",
+        description: "When the rating was submitted (Unix ms)."
+      }
+    ],
+    responses: { satisfaction_ratings: z.array(satisfactionRatingSchema) }
+  }
+});
+var id = "zendesk";
+var ZendeskConnector = class _ZendeskConnector extends BaseConnector {
+  static id = id;
+  static resources = zendeskResources;
+  static schemas = schemasFromResources(zendeskResources);
+  static create(input, ctx) {
+    const parsed = configFields.parse(input);
+    return new _ZendeskConnector(
+      {
+        subdomain: parsed.subdomain,
+        resources: parsed.resources
+      },
+      { email: parsed.email, apiToken: parsed.apiToken },
+      ctx
+    );
+  }
+  id = id;
+  credentials = zendeskCredentials;
+  get baseUrl() {
+    return `https://${this.settings.subdomain}.zendesk.com`;
+  }
+  buildHeaders() {
+    return {
+      Authorization: encodeBasicAuth(
+        `${this.creds.email}/token`,
+        this.creds.apiToken
+      ),
+      Accept: "application/json",
+      "User-Agent": connectorUserAgent("zendesk")
+    };
+  }
+  apiGet(url, resource, signal) {
+    return this.get(url, {
+      resource,
+      headers: this.buildHeaders(),
+      signal
+    });
+  }
+  // -------------------------------------------------------------------------
+  // users — GET /api/v2/users.json (cursor pagination)
+  // -------------------------------------------------------------------------
+  buildUserListUrl(cursor) {
+    const params = new URLSearchParams({ "page[size]": String(PAGE_SIZE) });
+    if (cursor) {
+      params.set("page[after]", cursor);
+    }
+    return `${this.baseUrl}/api/v2/users.json?${params.toString()}`;
+  }
+  async fetchUsers(page, signal) {
+    const res = await this.apiGet(
+      this.buildUserListUrl(page),
+      "users",
+      signal
+    );
+    return {
+      items: res.body.users ?? [],
+      next: res.body.meta?.has_more ? res.body.meta?.after_cursor ?? null : null
+    };
+  }
+  async writeUsers(storage, items) {
+    for (const user of items) {
+      await storage.entity({
+        type: USER_ENTITY,
+        id: String(user.id),
+        attributes: {
+          name: user.name ?? null,
+          email: user.email ?? null,
+          role: user.role ?? null,
+          active: user.active ?? null,
+          suspended: user.suspended ?? null,
+          defaultGroupId: numericIdOrNull(user.default_group_id),
+          createdAt: isoToMs(user.created_at)
+        },
+        updated_at: isoToMsOrZero(user.updated_at ?? user.created_at)
+      });
+    }
+  }
+  // -------------------------------------------------------------------------
+  // groups — GET /api/v2/groups.json (cursor pagination)
+  // -------------------------------------------------------------------------
+  buildGroupListUrl(cursor) {
+    const params = new URLSearchParams({ "page[size]": String(PAGE_SIZE) });
+    if (cursor) {
+      params.set("page[after]", cursor);
+    }
+    return `${this.baseUrl}/api/v2/groups.json?${params.toString()}`;
+  }
+  async fetchGroups(page, signal) {
+    const res = await this.apiGet(
+      this.buildGroupListUrl(page),
+      "groups",
+      signal
+    );
+    return {
+      items: res.body.groups ?? [],
+      next: res.body.meta?.has_more ? res.body.meta?.after_cursor ?? null : null
+    };
+  }
+  async writeGroups(storage, items) {
+    for (const group of items) {
+      await storage.entity({
+        type: GROUP_ENTITY,
+        id: String(group.id),
+        attributes: {
+          name: group.name ?? null,
+          isDefault: group.default ?? null,
+          deleted: group.deleted ?? null,
+          createdAt: isoToMs(group.created_at)
+        },
+        updated_at: isoToMsOrZero(group.updated_at ?? group.created_at)
+      });
+    }
+  }
+  // -------------------------------------------------------------------------
+  // tickets — GET /api/v2/incremental/tickets/cursor.json (cursor pagination)
+  // -------------------------------------------------------------------------
+  buildIncrementalTicketsUrl(cursor, options) {
+    const params = new URLSearchParams({
+      per_page: String(INCREMENTAL_PAGE_SIZE)
+    });
+    if (cursor) {
+      params.set("cursor", cursor);
+    } else {
+      params.set("start_time", String(sinceUnixSec(options) ?? 0));
+    }
+    return `${this.baseUrl}/api/v2/incremental/tickets/cursor.json?${params.toString()}`;
+  }
+  async fetchTickets(page, resource, options, signal) {
+    const fetchOptions = resource === "ticket_events" ? { ...options, since: void 0 } : options;
+    const res = await this.apiGet(
+      this.buildIncrementalTicketsUrl(page, fetchOptions),
+      resource,
+      signal
+    );
+    const next = res.body.end_of_stream ? null : res.body.after_cursor ?? null;
+    return { items: res.body.tickets ?? [], next };
+  }
+  async writeTickets(storage, items) {
+    for (const ticket of items) {
+      const attributes = {
+        subject: ticket.subject ?? null,
+        status: ticket.status ?? null,
+        priority: ticket.priority ?? null,
+        type: ticket.type ?? null,
+        channel: viaChannel(ticket),
+        assigneeId: numericIdOrNull(ticket.assignee_id),
+        requesterId: numericIdOrNull(ticket.requester_id),
+        submitterId: numericIdOrNull(ticket.submitter_id),
+        groupId: numericIdOrNull(ticket.group_id),
+        organizationId: numericIdOrNull(ticket.organization_id),
+        tags: ticket.tags ?? [],
+        satisfactionScore: csatScore(ticket),
+        createdAt: isoToMs(ticket.created_at)
+      };
+      await storage.entity({
+        type: TICKET_ENTITY,
+        id: String(ticket.id),
+        attributes,
+        updated_at: isoToMsOrZero(ticket.updated_at ?? ticket.created_at)
+      });
+    }
+  }
+  // -------------------------------------------------------------------------
+  // ticket_events — derived from the same /incremental/tickets payload
+  // -------------------------------------------------------------------------
+  async writeTicketEvents(storage, items) {
+    for (const ticket of items) {
+      const baseAttrs = {
+        ticketId: String(ticket.id),
+        status: ticket.status ?? null,
+        priority: ticket.priority ?? null,
+        assigneeId: numericIdOrNull(ticket.assignee_id),
+        groupId: numericIdOrNull(ticket.group_id),
+        channel: viaChannel(ticket)
+      };
+      const createdMs = isoToMs(ticket.created_at);
+      if (createdMs !== null) {
+        await storage.event({
+          name: TICKET_STATE_EVENT,
+          start_ts: createdMs,
+          end_ts: null,
+          attributes: { ...baseAttrs, transition: "created" }
+        });
+      }
+      if ((ticket.status === "solved" || ticket.status === "closed") && ticket.updated_at) {
+        const solvedMs = isoToMs(ticket.updated_at);
+        if (solvedMs !== null) {
+          await storage.event({
+            name: TICKET_STATE_EVENT,
+            start_ts: solvedMs,
+            end_ts: null,
+            attributes: { ...baseAttrs, transition: "solved" }
+          });
+        }
+      }
+    }
+  }
+  // -------------------------------------------------------------------------
+  // satisfaction_ratings — GET /api/v2/satisfaction_ratings.json
+  // -------------------------------------------------------------------------
+  buildSatisfactionRatingsUrl(cursor, options) {
+    const params = new URLSearchParams({ "page[size]": String(PAGE_SIZE) });
+    if (cursor) {
+      params.set("page[after]", cursor);
+    } else {
+      const startTime = sinceUnixSec(options);
+      if (startTime !== null) {
+        params.set("start_time", String(startTime));
+      }
+    }
+    return `${this.baseUrl}/api/v2/satisfaction_ratings.json?${params.toString()}`;
+  }
+  async fetchSatisfactionRatings(page, options, signal) {
+    const res = await this.apiGet(
+      this.buildSatisfactionRatingsUrl(page, options),
+      "satisfaction_ratings",
+      signal
+    );
+    return {
+      items: res.body.satisfaction_ratings ?? [],
+      next: res.body.meta?.has_more ? res.body.meta?.after_cursor ?? null : null
+    };
+  }
+  async writeSatisfactionRatings(storage, items) {
+    for (const rating of items) {
+      await storage.entity({
+        type: SATISFACTION_RATING_ENTITY,
+        id: String(rating.id),
+        attributes: {
+          score: rating.score ?? null,
+          ticketId: numericIdOrNull(rating.ticket_id),
+          assigneeId: numericIdOrNull(rating.assignee_id),
+          requesterId: numericIdOrNull(rating.requester_id),
+          groupId: numericIdOrNull(rating.group_id),
+          hasComment: typeof rating.comment === "string" && rating.comment !== "",
+          createdAt: isoToMs(rating.created_at)
+        },
+        updated_at: isoToMsOrZero(rating.updated_at ?? rating.created_at)
+      });
+    }
+  }
+  // -------------------------------------------------------------------------
+  // Scope clearing (idempotency)
+  // -------------------------------------------------------------------------
+  async clearScopeOnFirstPage(storage, phase, isFull) {
+    if (phase === "ticket_events") {
+      await storage.events([], { names: [TICKET_STATE_EVENT] });
+      return;
+    }
+    if (!isFull) {
+      return;
+    }
+    const entityType = ENTITY_TYPE_BY_PHASE[phase];
+    if (entityType) {
+      await storage.entities([], { types: [entityType] });
+    }
+  }
+  async writePhase(storage, phase, items) {
+    switch (phase) {
+      case "users":
+        await this.writeUsers(storage, items);
+        return;
+      case "groups":
+        await this.writeGroups(storage, items);
+        return;
+      case "tickets":
+        await this.writeTickets(storage, items);
+        return;
+      case "ticket_events":
+        await this.writeTicketEvents(storage, items);
+        return;
+      case "satisfaction_ratings":
+        await this.writeSatisfactionRatings(
+          storage,
+          items
+        );
+        return;
+    }
+  }
+  async sync(options, storage, signal) {
+    const cursor = isZendeskSyncCursor(options.cursor) ? options.cursor : void 0;
+    const isFull = options.mode === "full";
+    const phases = selectActivePhases(
+      (r) => r,
+      PHASE_ORDER,
+      this.settings.resources
+    );
+    return paginateChunked({
+      phases,
+      cursor,
+      signal,
+      logger: this.logger,
+      fetchPage: async (phase, page, sig) => {
+        switch (phase) {
+          case "users":
+            return this.fetchUsers(page, sig);
+          case "groups":
+            return this.fetchGroups(page, sig);
+          case "tickets":
+          case "ticket_events":
+            return this.fetchTickets(page, phase, options, sig);
+          case "satisfaction_ratings":
+            return this.fetchSatisfactionRatings(page, options, sig);
+        }
+      },
+      writeBatch: async (phase, items, page) => {
+        if (page === null) {
+          await this.clearScopeOnFirstPage(storage, phase, isFull);
+        }
+        await this.writePhase(storage, phase, items);
+      }
+    });
+  }
+};
+var ENTITY_TYPE_BY_PHASE = {
+  users: USER_ENTITY,
+  groups: GROUP_ENTITY,
+  tickets: TICKET_ENTITY,
+  satisfaction_ratings: SATISFACTION_RATING_ENTITY
+};
+function sinceUnixSec(options) {
+  if (!options.since) {
+    return null;
+  }
+  const ms = new Date(options.since).getTime();
+  if (!Number.isFinite(ms)) {
+    return null;
+  }
+  return Math.floor(ms / 1e3);
+}
+function encodeBasicAuth(username, secret) {
+  const raw = `${username}:${secret}`;
+  if (typeof btoa === "function") {
+    return `Basic ${btoa(raw)}`;
+  }
+  const bufferCtor = globalThis.Buffer;
+  if (bufferCtor) {
+    return `Basic ${bufferCtor.from(raw).toString("base64")}`;
+  }
+  throw new Error("No base64 encoder available in this runtime");
+}
+
+// src/index.ts
+var index_default = ZendeskConnector;
+export {
+  ZendeskConnector,
+  configFields,
+  index_default as default,
+  doc,
+  id,
+  zendeskResources as resources
+};
+//# sourceMappingURL=index.js.map