@pipedream/harvest 0.1.0 → 1.0.0

package/actions/list-clients/list-clients.mjs

@@ -0,0 +1,57 @@
+import harvest from "../../harvest.app.mjs";
+import constants from "../../common/constants.mjs";
+
+export default {
+  key: "harvest-list-clients",
+  name: "List Clients",
+  description: `List clients in the Harvest account, automatically following pagination up to ${constants.MAX_AUTO_PAGINATE_RECORDS} clients. Use this to discover client IDs for **Create Invoice**, **Create Project**, and other tools that accept a Client ID. Example: to find InGen Corp's client ID, call with no filters and look for the client named "InGen Corp" in the results. [See the documentation](https://help.getharvest.com/api-v2/clients-api/clients/clients/#list-all-clients).`,
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    isActive: {
+      propDefinition: [
+        harvest,
+        "isActive",
+      ],
+      description: "Only return active or inactive clients.",
+    },
+    updatedSince: {
+      propDefinition: [
+        harvest,
+        "updatedSince",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const clients = [];
+    const pages = this.harvest.listClientsPaginated({
+      page: 1,
+      $,
+      accountId: this.accountId,
+      isActive: this.isActive,
+      updatedSince: this.updatedSince,
+    });
+    for await (const client of pages) {
+      clients.push(client);
+      if (clients.length >= constants.MAX_AUTO_PAGINATE_RECORDS) break;
+    }
+    const count = clients.length;
+    $.export("$summary", `Successfully retrieved ${count} client${count === 1
+      ? ""
+      : "s"}`);
+    return clients;
+  },
+};

package/actions/list-invoices/list-invoices.mjs

@@ -0,0 +1,86 @@
+import harvest from "../../harvest.app.mjs";
+import constants from "../../common/constants.mjs";
+
+export default {
+  key: "harvest-list-invoices",
+  name: "List Invoices",
+  description: `List invoices with optional filters, automatically following pagination up to ${constants.MAX_AUTO_PAGINATE_RECORDS} invoices. Use this to discover invoice IDs for **Get Invoice**, **Update Invoice**, or **Delete Invoice**. Example: call with clientId set to InGen Corp's client ID and state="open" to find their unpaid invoices. [See the documentation](https://help.getharvest.com/api-v2/invoices-api/invoices/invoices/#list-all-invoices).`,
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    clientId: {
+      propDefinition: [
+        harvest,
+        "clientId",
+      ],
+    },
+    projectId: {
+      propDefinition: [
+        harvest,
+        "projectId",
+      ],
+      optional: true,
+    },
+    updatedSince: {
+      propDefinition: [
+        harvest,
+        "updatedSince",
+      ],
+    },
+    from: {
+      type: "string",
+      label: "From",
+      description: "Only return invoices with an issue_date on or after this date, `YYYY-MM-DD`, e.g. `2026-09-01`.",
+      optional: true,
+    },
+    to: {
+      type: "string",
+      label: "To",
+      description: "Only return invoices with an issue_date on or before this date, `YYYY-MM-DD`, e.g. `2026-09-30`.",
+      optional: true,
+    },
+    state: {
+      type: "string",
+      label: "State",
+      description: "Filter by state. One of: `draft`, `open`, `paid`, `closed`.",
+      optional: true,
+      options: constants.INVOICE_STATE_OPTIONS,
+    },
+  },
+  async run({ $ }) {
+    const invoices = [];
+    const pages = this.harvest.listInvoicesPaginated({
+      page: 1,
+      $,
+      accountId: this.accountId,
+      client_id: this.clientId,
+      project_id: this.projectId,
+      updated_since: this.updatedSince,
+      from: this.from,
+      to: this.to,
+      state: this.state,
+    });
+    for await (const invoice of pages) {
+      invoices.push(invoice);
+      if (invoices.length >= constants.MAX_AUTO_PAGINATE_RECORDS) break;
+    }
+    const count = invoices.length;
+    $.export("$summary", `Successfully retrieved ${count} invoice${count === 1
+      ? ""
+      : "s"}`);
+    return invoices;
+  },
+};

package/actions/list-task-assignments/list-task-assignments.mjs

@@ -0,0 +1,66 @@
+import harvest from "../../harvest.app.mjs";
+import constants from "../../common/constants.mjs";
+
+export default {
+  key: "harvest-list-task-assignments",
+  name: "List Task Assignments",
+  description: `List task assignments, automatically following pagination up to ${constants.MAX_AUTO_PAGINATE_RECORDS}. Omit Project ID to use the global endpoint; provide a Project ID to list assignments for a single project. Example: call with projectId set to the Jurassic Park Construction project's ID to see which tasks are billable on it. [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/task-assignments/).`,
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    projectId: {
+      propDefinition: [
+        harvest,
+        "projectId",
+      ],
+      description: "Optional free-form project ID, e.g. `14308069`. When set, routes to the per-project endpoint `/projects/{project_id}/task_assignments`; when omitted uses the global `/task_assignments`. Run **Get Projects** first to find valid IDs.",
+      optional: true,
+    },
+    isActive: {
+      propDefinition: [
+        harvest,
+        "isActive",
+      ],
+      description: "Only return active or inactive task assignments.",
+    },
+    updatedSince: {
+      propDefinition: [
+        harvest,
+        "updatedSince",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const assignments = [];
+    const pages = this.harvest.listTaskAssignmentsPaginated({
+      page: 1,
+      $,
+      projectId: this.projectId,
+      accountId: this.accountId,
+      is_active: this.isActive,
+      updated_since: this.updatedSince,
+    });
+    for await (const assignment of pages) {
+      assignments.push(assignment);
+      if (assignments.length >= constants.MAX_AUTO_PAGINATE_RECORDS) break;
+    }
+    const count = assignments.length;
+    $.export("$summary", `Successfully retrieved ${count} task assignment${count === 1
+      ? ""
+      : "s"}`);
+    return assignments;
+  },
+};

package/actions/list-tasks/list-tasks.mjs

@@ -0,0 +1,57 @@
+import harvest from "../../harvest.app.mjs";
+import constants from "../../common/constants.mjs";
+
+export default {
+  key: "harvest-list-tasks",
+  name: "List Tasks",
+  description: `List tasks in the Harvest account, automatically following pagination up to ${constants.MAX_AUTO_PAGINATE_RECORDS} tasks. Use this to discover task IDs for **Create Task Assignment**, **Create Timesheet Entry**, and other tools that accept a Task ID. Example: call with isActive=true to find the ID for the "Fence Maintenance" task before assigning it to a project. [See the documentation](https://help.getharvest.com/api-v2/tasks-api/tasks/tasks/#list-all-tasks).`,
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    isActive: {
+      propDefinition: [
+        harvest,
+        "isActive",
+      ],
+      description: "Only return active or inactive tasks.",
+    },
+    updatedSince: {
+      propDefinition: [
+        harvest,
+        "updatedSince",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const tasks = [];
+    const pages = this.harvest.listTasksPaginated({
+      page: 1,
+      $,
+      accountId: this.accountId,
+      isActive: this.isActive,
+      updatedSince: this.updatedSince,
+    });
+    for await (const task of pages) {
+      tasks.push(task);
+      if (tasks.length >= constants.MAX_AUTO_PAGINATE_RECORDS) break;
+    }
+    const count = tasks.length;
+    $.export("$summary", `Successfully retrieved ${count} task${count === 1
+      ? ""
+      : "s"}`);
+    return tasks;
+  },
+};

package/actions/list-time-entries/list-time-entries.mjs

@@ -0,0 +1,150 @@
+import harvest from "../../harvest.app.mjs";
+import constants from "../../common/constants.mjs";
+
+export default {
+  key: "harvest-list-time-entries",
+  name: "List Time Entries",
+  description: `Retrieve a list of time entries from Harvest, with optional filters, automatically following pagination up to ${constants.MAX_AUTO_PAGINATE_RECORDS} entries. Use this to discover time entry IDs for **Get Time Entry**, **Update Time Entry**, or **Delete Time Entry**. For a pure "how many entries are there" question, set \`countOnly\` to skip fetching any entries and just return the true total — safe even on a huge, unfiltered result set that would otherwise exceed the response-size limit. Pass \`notes\` to filter results to entries whose notes contain that text (client-side, case-insensitive substring) — useful for finding one entry inside a large result set without hitting the output-size limit. Example: call with projectId set to a project's ID and from/to set to a date range to total up hours logged that week. [See the documentation](https://help.getharvest.com/api-v2/timesheets-api/timesheets/time-entries/#list-all-time-entries).`,
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    userId: {
+      propDefinition: [
+        harvest,
+        "userId",
+      ],
+    },
+    clientId: {
+      propDefinition: [
+        harvest,
+        "clientId",
+      ],
+    },
+    projectId: {
+      propDefinition: [
+        harvest,
+        "projectId",
+      ],
+      optional: true,
+    },
+    taskId: {
+      propDefinition: [
+        harvest,
+        "taskId",
+      ],
+      optional: true,
+    },
+    isBilled: {
+      type: "boolean",
+      label: "Is Billed",
+      description: "Only return entries that have or have not been invoiced.",
+      optional: true,
+    },
+    isRunning: {
+      type: "boolean",
+      label: "Is Running",
+      description: "Only return running or non-running entries.",
+      optional: true,
+    },
+    updatedSince: {
+      propDefinition: [
+        harvest,
+        "updatedSince",
+      ],
+    },
+    from: {
+      type: "string",
+      label: "From",
+      description: "Only return entries with a spent_date on or after this date, format `YYYY-MM-DD`, e.g. `2026-09-01`.",
+      optional: true,
+    },
+    to: {
+      type: "string",
+      label: "To",
+      description: "Only return entries with a spent_date on or before this date, format `YYYY-MM-DD`, e.g. `2026-09-10`.",
+      optional: true,
+    },
+    notes: {
+      type: "string",
+      label: "Notes Contains",
+      description: "Only return entries whose notes contain this text (case-insensitive substring match, applied client-side). Use this to find a specific entry inside a large result set instead of paging through everything.",
+      optional: true,
+    },
+    countOnly: {
+      type: "boolean",
+      label: "Count Only",
+      description: "Skip fetching entries entirely and just return the true total for the given filters (via Harvest's own count). Use this for \"how many\" questions — safe on any result size, since it never fetches the entries themselves.",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const filterParams = {
+      accountId: this.accountId,
+      user_id: this.userId,
+      client_id: this.clientId,
+      project_id: this.projectId,
+      task_id: this.taskId,
+      is_billed: this.isBilled,
+      is_running: this.isRunning,
+      updated_since: this.updatedSince,
+      from: this.from,
+      to: this.to,
+    };
+
+    // A single per_page=1 lookup so $summary can report the account's true total for
+    // these filters even when the full result set is capped or notes-filtered down.
+    const totalsResponse = await this.harvest.listTimeEntries({
+      $,
+      per_page: 1,
+      page: 1,
+      ...filterParams,
+    });
+    const totalEntries = totalsResponse.total_entries ?? null;
+
+    if (this.countOnly) {
+      $.export("$summary", `${totalEntries ?? 0} time entr${totalEntries === 1
+        ? "y"
+        : "ies"} match the filters`);
+      return [];
+    }
+
+    const entries = [];
+    const notesFilter = this.notes?.toLowerCase();
+    let scanned = 0;
+    const pages = this.harvest.listTimeEntriesPaginated({
+      page: 1,
+      $,
+      ...filterParams,
+    });
+    for await (const entry of pages) {
+      scanned += 1;
+      if (notesFilter && !entry.notes?.toLowerCase().includes(notesFilter)) {
+        if (scanned >= constants.MAX_AUTO_PAGINATE_RECORDS * 10) break;
+        continue;
+      }
+      entries.push(entry);
+      if (entries.length >= constants.MAX_AUTO_PAGINATE_RECORDS) break;
+    }
+    const count = entries.length;
+    const totalSuffix = totalEntries !== null && totalEntries !== count
+      ? ` (${totalEntries} total match the filters)`
+      : "";
+    $.export("$summary", `Successfully retrieved ${count} time entr${count === 1
+      ? "y"
+      : "ies"}${totalSuffix}`);
+    return entries;
+  },
+};

package/actions/list-user-assignments/list-user-assignments.mjs

@@ -0,0 +1,74 @@
+import harvest from "../../harvest.app.mjs";
+import constants from "../../common/constants.mjs";
+
+export default {
+  key: "harvest-list-user-assignments",
+  name: "List User Assignments",
+  description: `List user assignments, automatically following pagination up to ${constants.MAX_AUTO_PAGINATE_RECORDS}. Omit Project ID to use the global endpoint; provide a Project ID to list assignments for a single project. Example: call with projectId set to the Isla Sorna Genetics Lab project's ID to see who is staffed on it. [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/user-assignments/).`,
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    projectId: {
+      propDefinition: [
+        harvest,
+        "projectId",
+      ],
+      description: "Optional free-form project ID, e.g. `14308069`. When set, routes to `/projects/{project_id}/user_assignments`; when omitted uses global `/user_assignments`. Run **Get Projects** first to find valid IDs.",
+      optional: true,
+    },
+    userId: {
+      propDefinition: [
+        harvest,
+        "userId",
+      ],
+      description: "Free-form user ID filter, applies whether using the global `/user_assignments` endpoint or a project-scoped `/projects/{project_id}/user_assignments` endpoint, e.g. `1782959`. Run **List Users** first to find valid IDs.",
+    },
+    isActive: {
+      propDefinition: [
+        harvest,
+        "isActive",
+      ],
+      description: "Only return active or inactive user assignments.",
+    },
+    updatedSince: {
+      propDefinition: [
+        harvest,
+        "updatedSince",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const assignments = [];
+    const pages = this.harvest.listUserAssignmentsPaginated({
+      page: 1,
+      $,
+      projectId: this.projectId,
+      accountId: this.accountId,
+      user_id: this.userId,
+      is_active: this.isActive,
+      updated_since: this.updatedSince,
+    });
+    for await (const assignment of pages) {
+      assignments.push(assignment);
+      if (assignments.length >= constants.MAX_AUTO_PAGINATE_RECORDS) break;
+    }
+    const count = assignments.length;
+    $.export("$summary", `Successfully retrieved ${count} user assignment${count === 1
+      ? ""
+      : "s"}`);
+    return assignments;
+  },
+};

package/actions/list-users/list-users.mjs

@@ -0,0 +1,57 @@
+import harvest from "../../harvest.app.mjs";
+import constants from "../../common/constants.mjs";
+
+export default {
+  key: "harvest-list-users",
+  name: "List Users",
+  description: `List users in the Harvest account, automatically following pagination up to ${constants.MAX_AUTO_PAGINATE_RECORDS} users. Use this to discover user IDs for **Create User Assignment**, **Create Timesheet Entry**, and other tools that accept a User ID. Example: call with isActive=true to find Alan Grant's user ID before logging time on his behalf. [See the documentation](https://help.getharvest.com/api-v2/users-api/users/users/#list-all-users).`,
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    isActive: {
+      propDefinition: [
+        harvest,
+        "isActive",
+      ],
+      description: "Only return active or inactive users.",
+    },
+    updatedSince: {
+      propDefinition: [
+        harvest,
+        "updatedSince",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const users = [];
+    const pages = this.harvest.listUsersPaginated({
+      page: 1,
+      $,
+      accountId: this.accountId,
+      isActive: this.isActive,
+      updatedSince: this.updatedSince,
+    });
+    for await (const user of pages) {
+      users.push(user);
+      if (users.length >= constants.MAX_AUTO_PAGINATE_RECORDS) break;
+    }
+    const count = users.length;
+    $.export("$summary", `Successfully retrieved ${count} user${count === 1
+      ? ""
+      : "s"}`);
+    return users;
+  },
+};

package/actions/start-timer/start-timer.mjs

@@ -3,14 +3,15 @@ import harvest from "../../harvest.app.mjs";
 export default {
   key: "harvest-start-timer",
   name: "Start Time Entry",
-  description: "Restart a stopped timer entry. [See docs here](https://help.getharvest.com/api-v2/timesheets-api/timesheets/time-entries/#restart-a-stopped-time-entry)",
-  version: "0.0.3",
+  description: "Restart a stopped time entry so it resumes running. Use **List Time Entries** with Is Running set to false to find a stopped entry to restart. Example: call with timeEntryId set to a stopped entry's ID to resume tracking time on it. [See the documentation](https://help.getharvest.com/api-v2/timesheets-api/timesheets/time-entries/#restart-a-stopped-time-entry).",
+  version: "0.0.4",
   annotations: {
-    destructiveHint: true,
+    destructiveHint: false,
     openWorldHint: true,
     readOnlyHint: false,
   },
   type: "action",
+  ai: "optimized",
   props: {
     harvest,
     accountId: {
@@ -23,11 +24,8 @@ export default {
       propDefinition: [
         harvest,
         "timeEntryId",
-        (c) => ({
-          isRunning: false,
-          accountId: c.accountId,
-        }),
       ],
+      description: "Free-form ID of a stopped time entry to restart, e.g. `636708723`. Run **List Time Entries** with Is Running set to false to find valid IDs.",
     },
   },
   async run({ $ }) {

package/actions/stop-timer/stop-timer.mjs

@@ -3,14 +3,15 @@ import harvest from "../../harvest.app.mjs";
 export default {
   key: "harvest-stop-timer",
   name: "Stop Time Entry",
-  description: "Stop a timer entry. [See docs here](https://help.getharvest.com/api-v2/timesheets-api/timesheets/time-entries/#stop-a-running-time-entry)",
-  version: "0.0.4",
+  description: "Stop a currently running time entry. Use **List Time Entries** with Is Running set to true to find a running entry to stop. Example: call with timeEntryId set to a currently running entry's ID to stop the clock on it. [See the documentation](https://help.getharvest.com/api-v2/timesheets-api/timesheets/time-entries/#stop-a-running-time-entry).",
+  version: "0.0.5",
   annotations: {
-    destructiveHint: true,
+    destructiveHint: false,
     openWorldHint: true,
     readOnlyHint: false,
   },
   type: "action",
+  ai: "optimized",
   props: {
     harvest,
     accountId: {
@@ -23,11 +24,8 @@ export default {
       propDefinition: [
         harvest,
         "timeEntryId",
-        (c) => ({
-          isRunning: true,
-          accountId: c.accountId,
-        }),
       ],
+      description: "Free-form ID of a running time entry to stop, e.g. `636708723`. Run **List Time Entries** with Is Running set to true to find valid IDs.",
     },
   },
   async run({ $ }) {