@rawdash/connector-clickup 0.0.1

package/dist/index.js

@@ -0,0 +1,673 @@
+// ../../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 standardRateLimitPolicy(config) {
+  const { remainingHeader, resetHeader, resetUnit, resetFallbackMs } = config;
+  const multiplier = resetUnit === "s" ? 1e3 : 1;
+  return {
+    parse(h) {
+      const remainingRaw = h.get(remainingHeader);
+      if (remainingRaw === null || remainingRaw.trim() === "") {
+        return null;
+      }
+      const remaining = Number(remainingRaw);
+      if (!Number.isFinite(remaining)) {
+        return null;
+      }
+      const resetRaw = h.get(resetHeader);
+      if (resetRaw === null) {
+        if (resetFallbackMs === void 0) {
+          return null;
+        }
+        return {
+          remaining,
+          resetAt: new Date(Date.now() + resetFallbackMs)
+        };
+      }
+      if (resetRaw.trim() === "") {
+        return null;
+      }
+      const reset = Number(resetRaw);
+      if (!Number.isFinite(reset) || reset < 0) {
+        return null;
+      }
+      const resetMs = reset * multiplier;
+      if (!Number.isFinite(resetMs)) {
+        return null;
+      }
+      return { remaining, resetAt: new Date(resetMs) };
+    }
+  };
+}
+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/clickup.ts
+import {
+  BaseConnector,
+  defineConfigFields,
+  defineConnectorDoc,
+  defineResources,
+  makeChunkedCursorGuard,
+  paginateChunked,
+  schemasFromResources,
+  selectActivePhases
+} from "@rawdash/core";
+import { z } from "zod";
+var configFields = defineConfigFields(
+  z.object({
+    apiToken: z.object({ $secret: z.string() }).meta({
+      label: "API Token",
+      description: "ClickUp personal API token. Create one at ClickUp -> Settings -> Apps -> API Token.",
+      placeholder: "pk_...",
+      secret: true
+    }),
+    teamId: z.string().min(1).meta({
+      label: "Workspace ID",
+      description: "ClickUp Workspace (team) ID to sync. Find it in the URL: app.clickup.com/<workspace_id>/home.",
+      placeholder: "9000000000"
+    }),
+    resources: z.array(z.enum(["spaces", "folders", "lists", "tasks", "task_events"])).nonempty().optional().meta({
+      label: "Resources",
+      description: "Which ClickUp resources to sync. Omit to sync all of them. 'task_events' derives created / closed lifecycle events from each task's timestamps and shares the task query with 'tasks'."
+    })
+  })
+);
+var doc = defineConnectorDoc({
+  displayName: "ClickUp",
+  category: "product",
+  brandColor: "#7B68EE",
+  tagline: "Sync spaces, folders, lists, tasks, and task lifecycle events from a ClickUp workspace for throughput, open-work, and status-distribution analytics.",
+  vendor: {
+    name: "ClickUp",
+    domain: "clickup.com",
+    apiDocs: "https://clickup.com/api",
+    website: "https://clickup.com"
+  },
+  auth: {
+    summary: "Authenticates with a ClickUp personal API token sent in the Authorization header. The token scopes the sync to the workspaces, spaces, and tasks the issuing user can access.",
+    setup: [
+      "Open ClickUp -> Settings -> Apps.",
+      "Under API Token, click Generate (or copy the existing personal token). It starts with pk_.",
+      'Store it as a secret and reference it from the connector config as `apiToken: secret("CLICKUP_API_TOKEN")`, alongside your Workspace ID.'
+    ]
+  },
+  rateLimit: "ClickUp rate-limits per token (100 requests/minute on the Free Forever / Unlimited plans, higher on Business+) and exposes X-RateLimit-Remaining / X-RateLimit-Reset headers; the shared HTTP client backs off on 429.",
+  limitations: [
+    "Personal API token auth only (OAuth app installs are out of scope).",
+    "Task lifecycle events (created / closed) are derived from each task's own date_created / date_closed fields rather than the per-task activity feed, which avoids an N+1 sync; the event scope is cleared and rewritten from a full task scan on every sync.",
+    "Custom fields, comments, time tracking, and goals are out of scope."
+  ]
+});
+var clickupCredentials = {
+  apiToken: {
+    description: "ClickUp personal API token",
+    auth: "required"
+  }
+};
+var clickupRateLimit = standardRateLimitPolicy({
+  remainingHeader: "x-ratelimit-remaining",
+  resetHeader: "x-ratelimit-reset",
+  resetUnit: "s",
+  resetFallbackMs: 6e4
+});
+var PHASE_ORDER = [
+  "spaces",
+  "folders",
+  "lists",
+  "tasks",
+  "task_events"
+];
+var isClickUpSyncCursor = makeChunkedCursorGuard(PHASE_ORDER);
+var SPACE_ENTITY = "clickup_space";
+var FOLDER_ENTITY = "clickup_folder";
+var LIST_ENTITY = "clickup_list";
+var TASK_ENTITY = "clickup_task";
+var TASK_EVENT = "clickup_task_event";
+var API_BASE = "https://api.clickup.com/api/v2";
+var TASKS_PER_PAGE = 100;
+var idString = z.string().min(1);
+var spaceSchema = z.object({
+  id: idString,
+  name: z.string(),
+  private: z.boolean().nullish(),
+  archived: z.boolean().nullish()
+});
+var spacesResponseSchema = z.object({
+  spaces: z.array(spaceSchema).nullish()
+});
+var folderSchema = z.object({
+  id: idString,
+  name: z.string(),
+  hidden: z.boolean().nullish(),
+  archived: z.boolean().nullish(),
+  task_count: z.union([z.string(), z.number()]).nullish(),
+  space: z.object({ id: idString, name: z.string().nullish() }).nullish()
+});
+var foldersResponseSchema = z.object({
+  folders: z.array(folderSchema).nullish()
+});
+var listSchema = z.object({
+  id: idString,
+  name: z.string(),
+  archived: z.boolean().nullish(),
+  task_count: z.number().nullish(),
+  status: z.object({ status: z.string().nullish() }).nullish(),
+  folder: z.object({ id: idString, name: z.string().nullish() }).nullish(),
+  space: z.object({ id: idString, name: z.string().nullish() }).nullish()
+});
+var listsResponseSchema = z.object({
+  lists: z.array(listSchema).nullish()
+});
+var taskSchema = z.object({
+  id: idString,
+  name: z.string(),
+  status: z.object({ status: z.string().nullish(), type: z.string().nullish() }).nullish(),
+  priority: z.object({ priority: z.string().nullish() }).nullish(),
+  date_created: z.string().nullish(),
+  date_updated: z.string().nullish(),
+  date_closed: z.string().nullish(),
+  date_done: z.string().nullish(),
+  due_date: z.string().nullish(),
+  time_estimate: z.number().nullish(),
+  creator: z.object({ id: z.union([z.string(), z.number()]) }).nullish(),
+  assignees: z.array(z.object({ id: z.union([z.string(), z.number()]) })).nullish(),
+  tags: z.array(z.object({ name: z.string() })).nullish(),
+  url: z.string().nullish(),
+  list: z.object({ id: idString, name: z.string().nullish() }).nullish(),
+  folder: z.object({ id: idString, name: z.string().nullish() }).nullish(),
+  space: z.object({ id: idString }).nullish()
+});
+var tasksResponseSchema = z.object({
+  tasks: z.array(taskSchema).nullish(),
+  last_page: z.boolean().nullish()
+});
+var clickupResources = defineResources({
+  [SPACE_ENTITY]: {
+    shape: "entity",
+    filterable: [],
+    description: "Workspace spaces with their name and privacy flag.",
+    endpoint: "GET /team/{team_id}/space",
+    fields: [
+      { name: "name", description: "Space name." },
+      { name: "private", description: "Whether the space is private." },
+      { name: "archived", description: "Whether the space is archived." }
+    ],
+    responses: { spaces: spacesResponseSchema }
+  },
+  [FOLDER_ENTITY]: {
+    shape: "entity",
+    filterable: [{ field: "spaceId", ops: ["eq"] }],
+    description: "Folders within each space, with their parent space.",
+    endpoint: "GET /space/{space_id}/folder",
+    fields: [
+      { name: "name", description: "Folder name." },
+      { name: "spaceId", description: "Parent space id." },
+      {
+        name: "taskCount",
+        description: "Number of tasks across the folder at sync time."
+      },
+      { name: "archived", description: "Whether the folder is archived." }
+    ],
+    responses: { folders: foldersResponseSchema }
+  },
+  [LIST_ENTITY]: {
+    shape: "entity",
+    filterable: [{ field: "spaceId", ops: ["eq"] }],
+    description: "Lists (folder-scoped and folderless) with their parent folder and space.",
+    endpoint: "GET /space/{space_id}/list and GET /folder/{folder_id}/list",
+    fields: [
+      { name: "name", description: "List name." },
+      {
+        name: "folderId",
+        description: "Parent folder id (null if folderless)."
+      },
+      { name: "spaceId", description: "Parent space id." },
+      {
+        name: "taskCount",
+        description: "Number of tasks in the list at sync time."
+      },
+      { name: "archived", description: "Whether the list is archived." }
+    ],
+    responses: { lists: listsResponseSchema }
+  },
+  [TASK_ENTITY]: {
+    shape: "entity",
+    filterable: [
+      {
+        field: "statusType",
+        ops: ["eq"],
+        values: ["open", "custom", "closed", "done"]
+      },
+      { field: "status", ops: ["eq"] },
+      { field: "listId", ops: ["eq"] }
+    ],
+    description: "Tasks with their status, priority, assignees, parent list / folder / space, tags, and lifecycle timestamps.",
+    endpoint: "GET /team/{team_id}/task",
+    fields: [
+      { name: "name", description: "Task name." },
+      {
+        name: "status",
+        description: 'Current status name (e.g. "in progress").'
+      },
+      {
+        name: "statusType",
+        description: "Status category: open, custom, closed, or done."
+      },
+      {
+        name: "priority",
+        description: "Priority label (urgent / high / normal / low), or null."
+      },
+      { name: "listId", description: "Parent list id." },
+      { name: "folderId", description: "Parent folder id." },
+      { name: "spaceId", description: "Parent space id." },
+      { name: "assignees", description: "Assignee user ids." },
+      { name: "assigneeCount", description: "Number of assignees." },
+      { name: "tags", description: "Tag names on the task." },
+      {
+        name: "createdAt",
+        description: "When the task was created (Unix ms)."
+      },
+      {
+        name: "closedAt",
+        description: "When the task was closed (Unix ms; null if open)."
+      },
+      {
+        name: "dueDate",
+        description: "Task due date (Unix ms; null if unset)."
+      }
+    ],
+    responses: { tasks: tasksResponseSchema }
+  },
+  [TASK_EVENT]: {
+    shape: "event",
+    filterable: [
+      { field: "kind", ops: ["eq"], values: ["created", "closed"] },
+      { field: "listId", ops: ["eq"] }
+    ],
+    description: "Task lifecycle events (created / closed) derived from each task's date_created and date_closed. The scope is cleared and rewritten from a full task scan on every sync (including incremental runs).",
+    endpoint: "GET /team/{team_id}/task",
+    notes: "Derived from each task's own date_created / date_closed timestamps, not from a separate per-task activity call. Drives created-per-day and closed-per-day throughput timeseries.",
+    fields: [
+      { name: "kind", description: '"created" or "closed".' },
+      { name: "taskId", description: "Task the event belongs to." },
+      { name: "listId", description: "Parent list id, denormalised." },
+      { name: "spaceId", description: "Parent space id, denormalised." },
+      { name: "status", description: "Task status name at sync time." }
+    ],
+    responses: { task_events: tasksResponseSchema }
+  }
+});
+var id = "clickup";
+function epochMs(value) {
+  return parseEpoch(value ?? null, "ms");
+}
+function tagNames(tags) {
+  if (!tags) {
+    return [];
+  }
+  return tags.map((t) => t.name).filter((n) => typeof n === "string" && n !== "");
+}
+function assigneeIds(assignees) {
+  if (!assignees) {
+    return [];
+  }
+  return assignees.map((a) => String(a.id));
+}
+function pushableEq(filter, field) {
+  if (!filter) {
+    return null;
+  }
+  for (const clause of filter) {
+    if ("field" in clause && clause.field === field && clause.op === "eq" && typeof clause.value === "string") {
+      return clause.value;
+    }
+  }
+  return null;
+}
+var ClickUpConnector = class _ClickUpConnector extends BaseConnector {
+  static id = id;
+  static resources = clickupResources;
+  static schemas = schemasFromResources(clickupResources);
+  static create(input, ctx) {
+    const parsed = configFields.parse(input);
+    return new _ClickUpConnector(
+      { teamId: parsed.teamId, resources: parsed.resources },
+      { apiToken: parsed.apiToken },
+      ctx
+    );
+  }
+  id = id;
+  credentials = clickupCredentials;
+  spacesCache;
+  buildHeaders() {
+    return {
+      Authorization: this.creds.apiToken,
+      Accept: "application/json",
+      "User-Agent": connectorUserAgent("clickup")
+    };
+  }
+  apiGet(url, resource, signal) {
+    return this.get(url, {
+      resource,
+      headers: this.buildHeaders(),
+      signal,
+      rateLimit: clickupRateLimit
+    });
+  }
+  get teamPath() {
+    return `/team/${encodeURIComponent(this.settings.teamId)}`;
+  }
+  async getSpaces(signal) {
+    if (this.spacesCache) {
+      return this.spacesCache;
+    }
+    const res = await this.apiGet(
+      `${API_BASE}${this.teamPath}/space?archived=false`,
+      "spaces",
+      signal
+    );
+    this.spacesCache = res.body.spaces ?? [];
+    return this.spacesCache;
+  }
+  async getFolders(spaceId, signal) {
+    const res = await this.apiGet(
+      `${API_BASE}/space/${encodeURIComponent(spaceId)}/folder?archived=false`,
+      "folders",
+      signal
+    );
+    return res.body.folders ?? [];
+  }
+  async getFolderlessLists(spaceId, signal) {
+    const res = await this.apiGet(
+      `${API_BASE}/space/${encodeURIComponent(spaceId)}/list?archived=false`,
+      "lists",
+      signal
+    );
+    return res.body.lists ?? [];
+  }
+  async getFolderLists(folderId, signal) {
+    const res = await this.apiGet(
+      `${API_BASE}/folder/${encodeURIComponent(folderId)}/list?archived=false`,
+      "lists",
+      signal
+    );
+    return res.body.lists ?? [];
+  }
+  buildTasksUrl(page, options, applySince) {
+    const url = new URL(`${API_BASE}${this.teamPath}/task`);
+    url.searchParams.set("page", String(page));
+    url.searchParams.set("include_closed", "true");
+    url.searchParams.set("subtasks", "true");
+    url.searchParams.set("order_by", "updated");
+    const listId = pushableEq(
+      this.singleSpec(options, TASK_ENTITY)?.filter,
+      "listId"
+    );
+    if (listId !== null) {
+      url.searchParams.append("list_ids[]", listId);
+    }
+    if (applySince && options.since) {
+      const sinceMs = parseEpoch(options.since, "iso");
+      if (sinceMs !== null) {
+        url.searchParams.set("date_updated_gt", String(sinceMs));
+      }
+    }
+    return url.toString();
+  }
+  singleSpec(options, resource) {
+    const specs = options.fetchSpecs?.[resource];
+    return specs && specs.length === 1 ? specs[0] : void 0;
+  }
+  async fetchSpacesPage(signal) {
+    const spaces = await this.getSpaces(signal);
+    return { items: spaces, next: null };
+  }
+  async fetchFoldersPage(signal) {
+    const spaces = await this.getSpaces(signal);
+    const folders = [];
+    for (const space of spaces) {
+      const spaceFolders = await this.getFolders(space.id, signal);
+      for (const folder of spaceFolders) {
+        folders.push({ ...folder, space: folder.space ?? { id: space.id } });
+      }
+    }
+    return { items: folders, next: null };
+  }
+  async fetchListsPage(signal) {
+    const spaces = await this.getSpaces(signal);
+    const lists = [];
+    for (const space of spaces) {
+      const folderless = await this.getFolderlessLists(space.id, signal);
+      for (const list of folderless) {
+        lists.push({ ...list, space: list.space ?? { id: space.id } });
+      }
+      const folders = await this.getFolders(space.id, signal);
+      for (const folder of folders) {
+        const folderLists = await this.getFolderLists(folder.id, signal);
+        for (const list of folderLists) {
+          lists.push({
+            ...list,
+            folder: list.folder ?? { id: folder.id, name: folder.name },
+            space: list.space ?? { id: space.id }
+          });
+        }
+      }
+    }
+    return { items: lists, next: null };
+  }
+  async fetchTasksPage(phase, page, options, signal) {
+    const pageNum = page === null ? 0 : Number(page);
+    const safePage = Number.isFinite(pageNum) && pageNum >= 0 ? pageNum : 0;
+    const url = this.buildTasksUrl(safePage, options, phase === "tasks");
+    const res = await this.apiGet(url, phase, signal);
+    const tasks = res.body.tasks ?? [];
+    const lastPage = res.body.last_page;
+    const exhausted = tasks.length === 0 || (typeof lastPage === "boolean" ? lastPage : tasks.length < TASKS_PER_PAGE);
+    return { items: tasks, next: exhausted ? null : String(safePage + 1) };
+  }
+  async writeSpaces(storage, spaces) {
+    for (const space of spaces) {
+      await storage.entity({
+        type: SPACE_ENTITY,
+        id: space.id,
+        attributes: {
+          name: space.name,
+          private: space.private ?? null,
+          archived: space.archived ?? null
+        },
+        updated_at: 0
+      });
+    }
+  }
+  async writeFolders(storage, folders) {
+    for (const folder of folders) {
+      await storage.entity({
+        type: FOLDER_ENTITY,
+        id: folder.id,
+        attributes: {
+          name: folder.name,
+          spaceId: folder.space?.id ?? null,
+          taskCount: folder.task_count === null || folder.task_count === void 0 ? null : Number(folder.task_count),
+          archived: folder.archived ?? null
+        },
+        updated_at: 0
+      });
+    }
+  }
+  async writeLists(storage, lists) {
+    for (const list of lists) {
+      await storage.entity({
+        type: LIST_ENTITY,
+        id: list.id,
+        attributes: {
+          name: list.name,
+          folderId: list.folder?.id ?? null,
+          spaceId: list.space?.id ?? null,
+          taskCount: list.task_count ?? null,
+          archived: list.archived ?? null
+        },
+        updated_at: 0
+      });
+    }
+  }
+  async writeTasks(storage, tasks) {
+    for (const task of tasks) {
+      const attributes = {
+        name: task.name,
+        status: task.status?.status ?? null,
+        statusType: task.status?.type ?? null,
+        priority: task.priority?.priority ?? null,
+        listId: task.list?.id ?? null,
+        folderId: task.folder?.id ?? null,
+        spaceId: task.space?.id ?? null,
+        assignees: assigneeIds(task.assignees),
+        assigneeCount: task.assignees?.length ?? 0,
+        tags: tagNames(task.tags),
+        creatorId: task.creator?.id === null || task.creator?.id === void 0 ? null : String(task.creator.id),
+        url: task.url ?? null,
+        timeEstimate: task.time_estimate ?? null,
+        dueDate: epochMs(task.due_date),
+        createdAt: epochMs(task.date_created),
+        closedAt: epochMs(task.date_closed),
+        doneAt: epochMs(task.date_done)
+      };
+      await storage.entity({
+        type: TASK_ENTITY,
+        id: task.id,
+        attributes,
+        updated_at: epochMs(task.date_updated) ?? epochMs(task.date_created) ?? 0
+      });
+    }
+  }
+  async writeTaskEvents(storage, tasks) {
+    for (const task of tasks) {
+      const base = {
+        taskId: task.id,
+        listId: task.list?.id ?? null,
+        spaceId: task.space?.id ?? null,
+        status: task.status?.status ?? null
+      };
+      const createdMs = epochMs(task.date_created);
+      if (createdMs !== null) {
+        await storage.event({
+          name: TASK_EVENT,
+          start_ts: createdMs,
+          end_ts: null,
+          attributes: { ...base, kind: "created" }
+        });
+      }
+      const closedMs = epochMs(task.date_closed);
+      if (closedMs !== null) {
+        await storage.event({
+          name: TASK_EVENT,
+          start_ts: closedMs,
+          end_ts: null,
+          attributes: { ...base, kind: "closed" }
+        });
+      }
+    }
+  }
+  async clearScopeOnFirstPage(storage, phase, isFull) {
+    if (phase === "task_events") {
+      await storage.events([], { names: [TASK_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 "spaces":
+        return this.writeSpaces(storage, items);
+      case "folders":
+        return this.writeFolders(storage, items);
+      case "lists":
+        return this.writeLists(storage, items);
+      case "tasks":
+        return this.writeTasks(storage, items);
+      case "task_events":
+        return this.writeTaskEvents(storage, items);
+    }
+  }
+  async sync(options, storage, signal) {
+    this.spacesCache = void 0;
+    const cursor = isClickUpSyncCursor(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 "spaces":
+            return this.fetchSpacesPage(sig);
+          case "folders":
+            return this.fetchFoldersPage(sig);
+          case "lists":
+            return this.fetchListsPage(sig);
+          case "tasks":
+          case "task_events":
+            return this.fetchTasksPage(phase, 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 = {
+  spaces: SPACE_ENTITY,
+  folders: FOLDER_ENTITY,
+  lists: LIST_ENTITY,
+  tasks: TASK_ENTITY
+};
+
+// src/index.ts
+var index_default = ClickUpConnector;
+export {
+  ClickUpConnector,
+  configFields,
+  index_default as default,
+  doc,
+  id,
+  clickupResources as resources
+};
+//# sourceMappingURL=index.js.map