@divyacon/piece-clickup 0.0.0-stage → 0.1.0

package/src/lib/actions/tasks/filter-workspace-time-entries.ts

@@ -0,0 +1,98 @@
+import { HttpMethod, getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import dayjs from 'dayjs';
+import qs from 'qs';
+import { clickupAuth } from '../../auth';
+import { callClickUpApi, clickupCommon } from '../../common';
+import { ClickupTask } from '../../common/models';
+import { filterTimeEntriesOutputSchema } from '../../output-schemas';
+
+export const filterClickupWorkspaceTimeEntries = createAction({
+  auth: clickupAuth,
+  name: 'list_workspace_time_entries',
+  displayName: 'List Time Entries',
+  description: 'Retrieves time entries filtered by start and end date.',
+  audience: 'human',
+  aiMetadata: { description: 'List tracked time entries across a ClickUp workspace, optionally narrowed by date range, assignee, and a single scope (task, list, folder, or space). Pick this to report on or audit logged time; it is read-only and idempotent. Scope filters are mutually exclusive, with task taking precedence over list, folder, then space.', idempotent: true },
+  props: {
+    workspace_id: clickupCommon.workspace_id(true),
+
+    start_date: Property.DateTime({
+      displayName: 'Start date',
+      description: '',
+      required: false,
+    }),
+    end_date: Property.DateTime({
+      displayName: 'End date',
+      required: false,
+    }),
+
+    space_id: clickupCommon.space_id(false),
+    folder_id: clickupCommon.folder_id(false),
+    list_id: clickupCommon.list_id(false),
+    task_id: clickupCommon.task_id(false, 'Task'),
+
+    assignee: clickupCommon.assignee_id(
+      false,
+      'Assignee Id',
+      'ID of assignee for Clickup Task'
+    ),
+
+    include_task_tags: Property.Checkbox({
+      displayName: 'Include task tags',
+      description:
+        'Include task tags in the response for time entries associated with tasks.',
+      required: false,
+      defaultValue: false,
+    }),
+    include_location_names: Property.Checkbox({
+      displayName: 'Include location names',
+      description:
+        'Include the names of the List, Folder, and Space along with the list_id, folder_id, and space_id.',
+      required: false,
+      defaultValue: false,
+    }),
+  },
+  outputSchema: filterTimeEntriesOutputSchema,
+  async run(context) {
+    const { task_id, list_id, folder_id, space_id, workspace_id, ...params } =
+      context.propsValue;
+    const auth = getAccessTokenOrThrow(context.auth);
+
+    const query: Record<string, unknown> = {
+      assignee: params.assignee?.join(','),
+      include_task_tags: params.include_task_tags,
+      include_location_names: params.include_location_names,
+    };
+
+    if (params.start_date)
+      query['start_date'] = dayjs(params.start_date).valueOf();
+
+    if (params.end_date) query['end_date'] = dayjs(params.end_date).valueOf();
+
+    if (task_id) {
+      query['task_id'] = task_id;
+    } else if (list_id) {
+      query['list_id'] = list_id;
+    } else if (folder_id) {
+      query['project_id'] = folder_id;
+    } else if (space_id) {
+      query['space_id'] = space_id;
+    }
+
+    return (
+      await callClickUpApi<ClickupTask>(
+        HttpMethod.GET,
+        `team/${workspace_id}/time_entries?${decodeURIComponent(
+          qs.stringify(query)
+        )}`,
+        auth,
+        undefined,
+        undefined,
+        {
+          'Content-Type': 'application/json',
+        }
+      )
+    ).body;
+  },
+});

package/src/lib/actions/tasks/get-task-by-name.ts

@@ -0,0 +1,61 @@
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { HttpMethod, getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { callClickUpApi, clickupCommon } from '../../common';
+import { clickupAuth } from '../../auth';
+import { taskOutputSchema } from '../../output-schemas';
+
+export const getClickupTaskByName = createAction({
+  auth: clickupAuth,
+  name: 'get_task_by_name',
+  description: 'Fetches a task by name in a ClickUp list',
+  audience: 'both',
+  aiMetadata: { description: 'Look up a single ClickUp task by its exact name within a specific list, paging through the list until the first exact-name match is found. Pick this when you know a task name but not its ID; use Get Task if you already have the ID. Read-only and idempotent; matching is exact and case-sensitive, and it errors if no task with that name exists in the list.', idempotent: true },
+  displayName: 'Get Task by Name',
+  props: {
+    workspace_id: clickupCommon.workspace_id(),
+    space_id: clickupCommon.space_id(),
+    list_id: clickupCommon.list_id(),
+    task_name: Property.ShortText({
+      description: 'The name of the task to find',
+      displayName: 'Task Name',
+      required: true,
+    }),
+  },
+  outputSchema: taskOutputSchema,
+  async run(configValue) {
+    const { list_id, task_name } = configValue.propsValue;
+    const accessToken = getAccessTokenOrThrow(configValue.auth);
+
+    let page = 0;
+    const pageSize = 100;
+    let hasMorePages = true;
+
+    while (hasMorePages) {
+      const response = await callClickUpApi(
+        HttpMethod.GET,
+        `list/${list_id}/task`,
+        accessToken,
+        undefined,
+        { page, limit: pageSize }
+      );
+
+
+      const tasks = response.body.tasks;
+
+      if (!tasks || tasks.length === 0) {
+        hasMorePages = false;
+        break;
+      }
+
+      const matchingTask = tasks.find((task: any) => task.name === task_name);
+
+      if (matchingTask) {
+        return matchingTask;
+      }
+
+      page++;
+    }
+
+    throw new Error(`Task with name "${task_name}" not found in list "${list_id}".`);
+  },
+});

package/src/lib/actions/tasks/get-task.ts

@@ -0,0 +1,40 @@
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { HttpMethod, getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { callClickUpApi } from '../../common';
+import { clickupAuth } from '../../auth';
+import { taskOutputSchema } from '../../output-schemas';
+
+export const getClickupTask = createAction({
+  auth: clickupAuth,
+  name: 'get_list_task',
+  description: 'Gets a task in a ClickUp list',
+  audience: 'human',
+  aiMetadata: { description: 'Retrieve a single ClickUp task by its task ID, optionally including subtasks. Pick this when you already know the task ID; use Get Task by Name to resolve a name within a list or List Team Tasks to search broadly. Read-only and idempotent.', idempotent: true },
+  displayName: 'Get Task',
+  props: {
+    task_id: Property.ShortText({
+      description: 'The ID of the task to get',
+      displayName: 'Task ID',
+      required: true,
+    }),
+    include_subtasks: Property.Checkbox({
+      description: 'Include subtasks in the response',
+      displayName: 'Include Subtasks',
+      required: false,
+      defaultValue: false,
+    }),
+  },
+  outputSchema: taskOutputSchema,
+  async run(configValue) {
+    const { task_id } = configValue.propsValue;
+
+    const response = await callClickUpApi(
+      HttpMethod.GET,
+      `task/${task_id}`,
+      getAccessTokenOrThrow(configValue.auth),
+      undefined
+    );
+
+    return response.body;
+  },
+});

package/src/lib/actions/tasks/update-task.ts

@@ -0,0 +1,72 @@
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { HttpMethod, getAccessTokenOrThrow } from '@agnocon/pieces-common';
+
+import { clickupCommon, callClickUpApi } from '../../common';
+import { clickupAuth } from '../../auth';
+import { taskOutputSchema } from '../../output-schemas';
+
+export const updateClickupTask = createAction({
+  auth: clickupAuth,
+  name: 'update_task',
+  description: 'Update task in a ClickUp workspace and list',
+  audience: 'human',
+  aiMetadata: { description: 'Modify fields of an existing ClickUp task identified by its task ID, including name, description, status, priority, and adding or removing assignees. Pick this to change a task you already have the ID for; use Create Task to make a new one. Only the fields you supply are changed, so repeating the same update produces the same end state.', idempotent: false },
+  displayName: 'Update Task',
+  props: {
+    workspace_id: clickupCommon.workspace_id(),
+    space_id: clickupCommon.space_id(),
+    list_id: clickupCommon.list_id(),
+    task_id: clickupCommon.task_id(),
+    name: Property.ShortText({
+      description: 'The name of the task to update',
+      displayName: 'Task Name',
+      required: false,
+    }),
+    description: Property.LongText({
+      description: 'The description of the task to update',
+      displayName: 'Task Description',
+      required: false,
+    }),
+    status_id: clickupCommon.status_id(),
+    priority_id: clickupCommon.priority_id(),
+    add_assignee: clickupCommon.assignee_id(
+      false,
+      'Add Assignees',
+      'assignee(s) you want to add for the task'
+    ),
+    rem_assignee: clickupCommon.assignee_id(
+      false,
+      'Remove Assignees',
+      'assignee(s) you want to remove from the task'
+    ),
+  },
+  outputSchema: taskOutputSchema,
+  async run(configValue) {
+    const {
+      task_id,
+      name,
+      description,
+      status_id,
+      priority_id,
+      add_assignee,
+      rem_assignee,
+    } = configValue.propsValue;
+    const response = await callClickUpApi(
+      HttpMethod.PUT,
+      `task/${task_id}`,
+      getAccessTokenOrThrow(configValue.auth),
+      {
+        name: name,
+        description: description,
+        status: status_id,
+        priority: priority_id,
+        assignees: {
+          add: add_assignee,
+          rem: rem_assignee,
+        },
+      }
+    );
+
+    return response.body;
+  },
+});

package/src/lib/actions/time-tracking/create-time-entry.ts

@@ -0,0 +1,73 @@
+import { HttpMethod, getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import dayjs from 'dayjs';
+import { clickupAuth } from '../../auth';
+import { callClickUpApi, clickupCommon } from '../../common';
+import { timeEntryOutputSchema } from '../../output-schemas';
+
+export const clickupCreateTimeEntry = createAction({
+  auth: clickupAuth,
+  name: 'clickup_create_time_entry',
+  displayName: 'Create Time Entry',
+  description: 'Create a completed time entry in a ClickUp workspace.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Log a completed (historical) block of tracked time in a ClickUp workspace, given a start time and a duration in milliseconds. Pick this to record time already spent; use Start Time Entry / Stop Time Entry instead to run a live timer. Each call creates a new entry, so retries duplicate (not idempotent). Optionally attach it to a task via its task ID.',
+    idempotent: false,
+  },
+  outputSchema: timeEntryOutputSchema,
+  props: {
+    workspace_id: clickupCommon.workspace_id(true),
+    start: Property.DateTime({
+      displayName: 'Start',
+      description: 'When the tracked block started.',
+      required: true,
+    }),
+    duration: Property.Number({
+      displayName: 'Duration (ms)',
+      description:
+        'Length of the time entry in milliseconds (e.g. 3600000 for one hour).',
+      required: true,
+    }),
+    description: Property.LongText({
+      displayName: 'Description',
+      description: 'Optional note describing the time entry.',
+      required: false,
+    }),
+    space_id: clickupCommon.space_id(false),
+    list_id: clickupCommon.list_id(false),
+    task_id: clickupCommon.task_id(
+      false,
+      'Task to attach the time entry to'
+    ),
+    billable: Property.Checkbox({
+      displayName: 'Billable',
+      description: 'Mark the time entry as billable.',
+      required: false,
+      defaultValue: false,
+    }),
+  },
+  async run(context) {
+    const { workspace_id, start, duration, description, task_id, billable } =
+      context.propsValue;
+    const auth = getAccessTokenOrThrow(context.auth);
+
+    const body: Record<string, unknown> = {
+      start: dayjs(start).valueOf(),
+      duration,
+      billable,
+    };
+    if (description) body['description'] = description;
+    if (task_id) body['tid'] = task_id;
+
+    const response = await callClickUpApi(
+      HttpMethod.POST,
+      `team/${workspace_id}/time_entries`,
+      auth,
+      body
+    );
+
+    return response.body;
+  },
+});

package/src/lib/actions/time-tracking/delete-time-entry.ts

@@ -0,0 +1,41 @@
+import { HttpMethod, getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { clickupAuth } from '../../auth';
+import { callClickUpApi, clickupCommon } from '../../common';
+import { listTimeEntriesOutputSchema } from '../../output-schemas';
+
+export const clickupDeleteTimeEntry = createAction({
+  auth: clickupAuth,
+  name: 'clickup_delete_time_entry',
+  displayName: 'Delete Time Entry',
+  description: 'Delete a time entry by its ID.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Permanently delete a tracked time entry by its time entry ID within a workspace. This is destructive and cannot be undone; a repeated call on an already-deleted entry errors (not idempotent). Use List Time Entries to confirm the entry ID before deleting.',
+    idempotent: false,
+  },
+  outputSchema: listTimeEntriesOutputSchema,
+  props: {
+    workspace_id: clickupCommon.workspace_id(true),
+    timer_id: Property.ShortText({
+      displayName: 'Time Entry ID',
+      description:
+        'The ID of the time entry to delete. Obtain it from List Time Entries.',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { workspace_id, timer_id } = context.propsValue;
+    const auth = getAccessTokenOrThrow(context.auth);
+
+    const response = await callClickUpApi(
+      HttpMethod.DELETE,
+      `team/${workspace_id}/time_entries/${timer_id}`,
+      auth,
+      undefined
+    );
+
+    return response.body;
+  },
+});

package/src/lib/actions/time-tracking/get-running-time-entry.ts

@@ -0,0 +1,35 @@
+import { HttpMethod, getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { createAction } from '@agnocon/pieces-framework';
+import { clickupAuth } from '../../auth';
+import { callClickUpApi, clickupCommon } from '../../common';
+import { timeEntryOutputSchema } from '../../output-schemas';
+
+export const clickupGetRunningTimeEntry = createAction({
+  auth: clickupAuth,
+  name: 'clickup_get_running_time_entry',
+  displayName: 'Get Running Time Entry',
+  description: 'Retrieve the time entry currently being tracked.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      "Retrieve the time entry whose timer is currently running for the authenticated user in a workspace. Pick this to check whether a timer is active before calling Stop Time Entry; use Get Time Entry for a specific completed entry by ID. Read-only and idempotent; returns empty when no timer is running.",
+    idempotent: true,
+  },
+  outputSchema: timeEntryOutputSchema,
+  props: {
+    workspace_id: clickupCommon.workspace_id(true),
+  },
+  async run(context) {
+    const { workspace_id } = context.propsValue;
+    const auth = getAccessTokenOrThrow(context.auth);
+
+    const response = await callClickUpApi(
+      HttpMethod.GET,
+      `team/${workspace_id}/time_entries/current`,
+      auth,
+      undefined
+    );
+
+    return response.body;
+  },
+});

package/src/lib/actions/time-tracking/get-time-entry.ts

@@ -0,0 +1,41 @@
+import { HttpMethod, getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { clickupAuth } from '../../auth';
+import { callClickUpApi, clickupCommon } from '../../common';
+import { timeEntryOutputSchema } from '../../output-schemas';
+
+export const clickupGetTimeEntry = createAction({
+  auth: clickupAuth,
+  name: 'clickup_get_time_entry',
+  displayName: 'Get Time Entry',
+  description: 'Retrieve a single time entry by its ID.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Retrieve one tracked time entry by its time entry (timer) ID within a workspace. Pick this when you already know the entry ID; use List Time Entries to find entries by date or scope, or Get Running Time Entry for the timer currently in progress. Read-only and idempotent.',
+    idempotent: true,
+  },
+  outputSchema: timeEntryOutputSchema,
+  props: {
+    workspace_id: clickupCommon.workspace_id(true),
+    timer_id: Property.ShortText({
+      displayName: 'Time Entry ID',
+      description:
+        'The ID of the time entry to retrieve. Obtain it from List Time Entries.',
+      required: true,
+    }),
+  },
+  async run(context) {
+    const { workspace_id, timer_id } = context.propsValue;
+    const auth = getAccessTokenOrThrow(context.auth);
+
+    const response = await callClickUpApi(
+      HttpMethod.GET,
+      `team/${workspace_id}/time_entries/${timer_id}`,
+      auth,
+      undefined
+    );
+
+    return response.body;
+  },
+});

package/src/lib/actions/time-tracking/list-time-entries.ts

@@ -0,0 +1,112 @@
+import { HttpMethod, getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import dayjs from 'dayjs';
+import qs from 'qs';
+import { clickupAuth } from '../../auth';
+import { callClickUpApi, clickupCommon } from '../../common';
+import { ClickupTask } from '../../common/models';
+import { listTimeEntriesOutputSchema } from '../../output-schemas';
+
+export const clickupListTimeEntries = createAction({
+  auth: clickupAuth,
+  name: 'clickup_list_time_entries',
+  displayName: 'List Time Entries',
+  description: 'Retrieves time entries filtered by start and end date.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'List tracked time entries across a ClickUp workspace, optionally narrowed by date range, assignee, and a single scope (task, list, folder, or space). Pick this to report on or audit logged time over a period; use Get Time Entry for one known entry ID or Get Running Time Entry for the timer in progress. Read-only and idempotent; scope filters are mutually exclusive (task takes precedence over list, folder, then space).',
+    idempotent: true,
+  },
+  outputSchema: listTimeEntriesOutputSchema,
+  props: {
+    workspace_id: clickupCommon.workspace_id(true),
+
+    start_date: Property.DateTime({
+      displayName: 'Start date',
+      description: '',
+      required: false,
+    }),
+    end_date: Property.DateTime({
+      displayName: 'End date',
+      required: false,
+    }),
+
+    space_id: clickupCommon.space_id(false),
+    folder_id: clickupCommon.folder_id(false),
+    list_id: clickupCommon.list_id(false),
+    task_id: clickupCommon.task_id(false, 'Task'),
+
+    assignee: clickupCommon.assignee_id(
+      false,
+      'Assignee Id',
+      'ID of assignee for Clickup Task'
+    ),
+
+    include_task_tags: Property.Checkbox({
+      displayName: 'Include task tags',
+      description:
+        'Include task tags in the response for time entries associated with tasks.',
+      required: false,
+      defaultValue: false,
+    }),
+    include_location_names: Property.Checkbox({
+      displayName: 'Include location names',
+      description:
+        'Include the names of the List, Folder, and Space along with the list_id, folder_id, and space_id.',
+      required: false,
+      defaultValue: false,
+    }),
+  },
+  async run(context) {
+    const { task_id, list_id, folder_id, space_id, workspace_id, ...params } =
+      context.propsValue;
+    const auth = getAccessTokenOrThrow(context.auth);
+
+    // `assignee` is a multi-select (array), but an agent may pass a single
+    // scalar id. Normalize to an array before joining so a scalar input does
+    // not crash with `.join is not a function`.
+    const assigneeList =
+      params.assignee == null
+        ? undefined
+        : Array.isArray(params.assignee)
+        ? params.assignee
+        : [params.assignee];
+
+    const query: Record<string, unknown> = {
+      assignee: assigneeList?.join(','),
+      include_task_tags: params.include_task_tags,
+      include_location_names: params.include_location_names,
+    };
+
+    if (params.start_date)
+      query['start_date'] = dayjs(params.start_date).valueOf();
+
+    if (params.end_date) query['end_date'] = dayjs(params.end_date).valueOf();
+
+    if (task_id) {
+      query['task_id'] = task_id;
+    } else if (list_id) {
+      query['list_id'] = list_id;
+    } else if (folder_id) {
+      query['project_id'] = folder_id;
+    } else if (space_id) {
+      query['space_id'] = space_id;
+    }
+
+    return (
+      await callClickUpApi<ClickupTask>(
+        HttpMethod.GET,
+        `team/${workspace_id}/time_entries?${decodeURIComponent(
+          qs.stringify(query)
+        )}`,
+        auth,
+        undefined,
+        undefined,
+        {
+          'Content-Type': 'application/json',
+        }
+      )
+    ).body;
+  },
+});

package/src/lib/actions/time-tracking/start-time-entry.ts

@@ -0,0 +1,53 @@
+import { HttpMethod, getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { Property, createAction } from '@agnocon/pieces-framework';
+import { clickupAuth } from '../../auth';
+import { callClickUpApi, clickupCommon } from '../../common';
+import { timeEntryOutputSchema } from '../../output-schemas';
+
+export const clickupStartTimeEntry = createAction({
+  auth: clickupAuth,
+  name: 'clickup_start_time_entry',
+  displayName: 'Start Time Entry',
+  description: 'Start a running timer in a ClickUp workspace.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Start a live running timer in a ClickUp workspace, optionally attached to a task. Pick this to begin tracking time now and later call Stop Time Entry; use Create Time Entry instead to log a completed block with a known duration. Starting a timer is stateful and fails if one is already running, so it is not idempotent.',
+    idempotent: false,
+  },
+  outputSchema: timeEntryOutputSchema,
+  props: {
+    workspace_id: clickupCommon.workspace_id(true),
+    description: Property.LongText({
+      displayName: 'Description',
+      description: 'Optional note for the running timer.',
+      required: false,
+    }),
+    space_id: clickupCommon.space_id(false),
+    list_id: clickupCommon.list_id(false),
+    task_id: clickupCommon.task_id(false, 'Task to track time against'),
+    billable: Property.Checkbox({
+      displayName: 'Billable',
+      description: 'Mark the tracked time as billable.',
+      required: false,
+      defaultValue: false,
+    }),
+  },
+  async run(context) {
+    const { workspace_id, description, task_id, billable } = context.propsValue;
+    const auth = getAccessTokenOrThrow(context.auth);
+
+    const body: Record<string, unknown> = { billable };
+    if (description) body['description'] = description;
+    if (task_id) body['tid'] = task_id;
+
+    const response = await callClickUpApi(
+      HttpMethod.POST,
+      `team/${workspace_id}/time_entries/start`,
+      auth,
+      body
+    );
+
+    return response.body;
+  },
+});

package/src/lib/actions/time-tracking/stop-time-entry.ts

@@ -0,0 +1,35 @@
+import { HttpMethod, getAccessTokenOrThrow } from '@agnocon/pieces-common';
+import { createAction } from '@agnocon/pieces-framework';
+import { clickupAuth } from '../../auth';
+import { callClickUpApi, clickupCommon } from '../../common';
+import { timeEntryOutputSchema } from '../../output-schemas';
+
+export const clickupStopTimeEntry = createAction({
+  auth: clickupAuth,
+  name: 'clickup_stop_time_entry',
+  displayName: 'Stop Time Entry',
+  description: 'Stop the currently running timer in a ClickUp workspace.',
+  audience: 'ai',
+  aiMetadata: {
+    description:
+      'Stop the timer that is currently running for the authenticated user in a workspace, finalizing it into a completed time entry. Pick this to end a timer previously begun with Start Time Entry; call Get Running Time Entry first to confirm a timer is active, since stopping when none is running errors (not idempotent).',
+    idempotent: false,
+  },
+  outputSchema: timeEntryOutputSchema,
+  props: {
+    workspace_id: clickupCommon.workspace_id(true),
+  },
+  async run(context) {
+    const { workspace_id } = context.propsValue;
+    const auth = getAccessTokenOrThrow(context.auth);
+
+    const response = await callClickUpApi(
+      HttpMethod.POST,
+      `team/${workspace_id}/time_entries/stop`,
+      auth,
+      {}
+    );
+
+    return response.body;
+  },
+});