@pipedream/harvest 0.1.0 → 1.0.0

package/actions/delete-project/delete-project.mjs

@@ -0,0 +1,38 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-delete-project",
+  name: "Delete Project",
+  description: "Permanently delete a project and all time entries and expenses tracked to it (invoices are not deleted). Use **Get Projects** to find a project ID. Example: call with projectId set to a project's ID to permanently remove it. [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/projects/#delete-a-project).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    projectId: {
+      propDefinition: [
+        harvest,
+        "projectId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    await this.harvest.deleteProject({
+      $,
+      projectId: this.projectId,
+      accountId: this.accountId,
+    });
+    $.export("$summary", `Successfully deleted project ${this.projectId}`);
+  },
+};

package/actions/delete-task-assignment/delete-task-assignment.mjs

@@ -0,0 +1,45 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-delete-task-assignment",
+  name: "Delete Task Assignment",
+  description: "Delete a task assignment from a project (only possible if it has no time entries). Use **List Task Assignments** to find IDs. Example: call with projectId and taskAssignmentId to remove that task from the project. [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/task-assignments/#delete-a-task-assignment).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    projectId: {
+      propDefinition: [
+        harvest,
+        "projectId",
+      ],
+    },
+    taskAssignmentId: {
+      propDefinition: [
+        harvest,
+        "taskAssignmentId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    await this.harvest.deleteTaskAssignment({
+      $,
+      projectId: this.projectId,
+      taskAssignmentId: this.taskAssignmentId,
+      accountId: this.accountId,
+    });
+    $.export("$summary", `Successfully deleted task assignment ${this.taskAssignmentId}`);
+  },
+};

package/actions/delete-time-entry/delete-time-entry.mjs

@@ -0,0 +1,38 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-delete-time-entry",
+  name: "Delete Time Entry",
+  description: "Permanently delete a time entry. Use **List Time Entries** to find a valid ID. Example: call with timeEntryId set to a mistakenly logged entry's ID to remove it. [See the documentation](https://help.getharvest.com/api-v2/timesheets-api/timesheets/time-entries/#delete-a-time-entry).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    timeEntryId: {
+      propDefinition: [
+        harvest,
+        "timeEntryId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    await this.harvest.deleteTimeEntry({
+      $,
+      id: this.timeEntryId,
+      accountId: this.accountId,
+    });
+    $.export("$summary", `Successfully deleted time entry ${this.timeEntryId}`);
+  },
+};

package/actions/delete-user/delete-user.mjs

@@ -0,0 +1,39 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-delete-user",
+  name: "Delete User",
+  description: "Permanently delete a user (only possible if they have no time entries or expenses). Use **List Users** to find a valid ID. Example: call with userId set to a departed team member's ID to remove their Harvest access. [See the documentation](https://help.getharvest.com/api-v2/users-api/users/users/#delete-a-user).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    userId: {
+      propDefinition: [
+        harvest,
+        "userId",
+      ],
+      optional: false,
+    },
+  },
+  async run({ $ }) {
+    await this.harvest.deleteUser({
+      $,
+      userId: this.userId,
+      accountId: this.accountId,
+    });
+    $.export("$summary", `Successfully deleted user ${this.userId}`);
+  },
+};

package/actions/delete-user-assignment/delete-user-assignment.mjs

@@ -0,0 +1,45 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-delete-user-assignment",
+  name: "Delete User Assignment",
+  description: "Delete a user assignment from a project (only possible if it has no time entries or expenses). Use **List User Assignments** to find IDs. Example: call with projectId and userAssignmentId to unstaff that person from the project. [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/user-assignments/#delete-a-user-assignment).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    projectId: {
+      propDefinition: [
+        harvest,
+        "projectId",
+      ],
+    },
+    userAssignmentId: {
+      propDefinition: [
+        harvest,
+        "userAssignmentId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    await this.harvest.deleteUserAssignment({
+      $,
+      projectId: this.projectId,
+      userAssignmentId: this.userAssignmentId,
+      accountId: this.accountId,
+    });
+    $.export("$summary", `Successfully deleted user assignment ${this.userAssignmentId}`);
+  },
+};

package/actions/get-invoice/get-invoice.mjs

@@ -0,0 +1,39 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-get-invoice",
+  name: "Get Invoice",
+  description: "Retrieve a single invoice by ID. Use **List Invoices** to find a valid ID. Example: call with invoiceId set to a known invoice's ID to check its amount and payment state. [See the documentation](https://help.getharvest.com/api-v2/invoices-api/invoices/invoices/#retrieve-an-invoice).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    invoiceId: {
+      propDefinition: [
+        harvest,
+        "invoiceId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.harvest.getInvoice({
+      $,
+      invoiceId: this.invoiceId,
+      accountId: this.accountId,
+    });
+    $.export("$summary", `Successfully retrieved invoice ${response.id}`);
+    return response;
+  },
+};

package/actions/get-me/get-me.mjs

@@ -0,0 +1,32 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-get-me",
+  name: "Get Me",
+  description: "Retrieve the currently authenticated user from `GET /users/me`. Takes no ID input. Example: call with no parameters to answer \"who am I logged in as in Harvest?\". [See the documentation](https://help.getharvest.com/api-v2/users-api/users/users/#retrieve-the-currently-authenticated-user).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.harvest.getMe({
+      $,
+      accountId: this.accountId,
+    });
+    $.export("$summary", `Successfully retrieved authenticated user ${response.id}: ${response.first_name} ${response.last_name}`);
+    return response;
+  },
+};

package/actions/get-project/get-project.mjs

@@ -0,0 +1,39 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-get-project",
+  name: "Get Project",
+  description: "Retrieve a single project by ID. Example: call with projectId set to a known project's ID to see its client, budget, and billing method. [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/projects/#retrieve-a-project).",
+  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",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.harvest.getProject({
+      $,
+      projectId: this.projectId,
+      accountId: this.accountId,
+    });
+    $.export("$summary", `Successfully retrieved project ${response.id}: ${response.name}`);
+    return response;
+  },
+};

package/actions/get-projects/get-projects.mjs

@@ -1,17 +1,22 @@
 import harvest from "../../harvest.app.mjs";
+import constants from "../../common/constants.mjs";
 import { ConfigurationError } from "@pipedream/platform";
+import {
+  mapWithRateLimit, withRetryAfter,
+} from "../../common/utils.mjs";
 
 export default {
   key: "harvest-get-projects",
   name: "Get Projects",
-  description: "Retrieve data for a project or projects. [See docs here](https://help.getharvest.com/api-v2/projects-api/projects/projects/#list-all-projects)",
-  version: "0.0.2",
+  description: `Retrieve one or more projects. Omit Project IDs to list every project in the account (up to ${constants.MAX_AUTO_PAGINATE_RECORDS}) — use this to discover project IDs for other Harvest tools. Provide Project IDs to fetch specific projects instead. Example: call with no Project IDs to find the ID for "Jurassic Park Construction" before creating a task assignment on it. [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/projects/#list-all-projects).`,
+  version: "0.1.0",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
     readOnlyHint: true,
   },
   type: "action",
+  ai: "optimized",
   props: {
     harvest,
     accountId: {
@@ -24,12 +29,9 @@ export default {
       propDefinition: [
         harvest,
         "projectId",
-        (c) => ({
-          accountId: c.accountId,
-        }),
       ],
       type: "string[]",
-      description: "Array of project IDs",
+      description: "Array of free-form project IDs, e.g. `[\"14308069\"]`. Omit this parameter to retrieve every project instead.",
       optional: true,
     },
   },
@@ -42,24 +44,25 @@ export default {
       throw new ConfigurationError("Project IDs must be an array");
     }
 
-    const results = [];
+    let results;
 
     if (projectIds) {
-      for (const projectId of projectIds) {
-        const project = await this.harvest.getProject({
+      results = await mapWithRateLimit(projectIds, (projectId) =>
+        withRetryAfter(() => this.harvest.getProject({
           $,
           projectId,
           accountId,
-        });
-        results.push(project);
-      }
+        })));
     } else {
+      results = [];
       const projects = await this.harvest.listProjectsPaginated({
         page: 1,
+        $,
         accountId,
       });
       for await (const project of projects) {
         results.push(project);
+        if (results.length >= constants.MAX_AUTO_PAGINATE_RECORDS) break;
       }
     }
 

package/actions/get-task-assignment/get-task-assignment.mjs

@@ -0,0 +1,46 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-get-task-assignment",
+  name: "Get Task Assignment",
+  description: "Retrieve a single task assignment on a project. Use **List Task Assignments** to find IDs. Example: call with projectId and taskAssignmentId to check whether that task is billable on the project. [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/task-assignments/#retrieve-a-task-assignment).",
+  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",
+      ],
+    },
+    taskAssignmentId: {
+      propDefinition: [
+        harvest,
+        "taskAssignmentId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.harvest.getTaskAssignment({
+      $,
+      projectId: this.projectId,
+      taskAssignmentId: this.taskAssignmentId,
+      accountId: this.accountId,
+    });
+    $.export("$summary", `Successfully retrieved task assignment ${response.id}`);
+    return response;
+  },
+};

package/actions/get-time-entry/get-time-entry.mjs

@@ -0,0 +1,39 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-get-time-entry",
+  name: "Get Time Entry",
+  description: "Retrieve a single time entry by ID. Use **List Time Entries** to find a valid ID. Example: call with timeEntryId set to a known entry's ID to see its hours, project, and task. [See the documentation](https://help.getharvest.com/api-v2/timesheets-api/timesheets/time-entries/#retrieve-a-time-entry).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    timeEntryId: {
+      propDefinition: [
+        harvest,
+        "timeEntryId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.harvest.getTimeEntry({
+      $,
+      id: this.timeEntryId,
+      accountId: this.accountId,
+    });
+    $.export("$summary", `Successfully retrieved time entry ${response.id}`);
+    return response;
+  },
+};

package/actions/get-time-report/get-time-report.mjs

@@ -0,0 +1,80 @@
+import harvest from "../../harvest.app.mjs";
+import constants from "../../common/constants.mjs";
+
+export default {
+  key: "harvest-get-time-report",
+  name: "Get Time Report",
+  description: `Retrieve total hours logged, aggregated by a chosen dimension (clients, projects, tasks, or team) over a date range, automatically following pagination up to ${constants.MAX_AUTO_PAGINATE_RECORDS} results. Use when the user asks "how many hours were logged/worked on X", "how much time did the team spend on Y", or wants a time report/summary/breakdown — this is the only tool that returns aggregated totals; **List Time Entries** returns individual raw entries you would have to sum yourself. The Report By value selects which \`/reports/time/{dimension}\` endpoint is called. Example: call with reportBy="projects", from="20260901", to="20260930" to see total hours logged per project for the month. [See the documentation](https://help.getharvest.com/api-v2/reports-api/reports/time-reports/)`,
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    reportBy: {
+      type: "string",
+      label: "Report By",
+      description: "The dimension to group the report by. One of: `clients`, `projects`, `tasks`, `team`.",
+      options: constants.REPORT_BY_OPTIONS,
+    },
+    from: {
+      type: "string",
+      label: "From",
+      description: "Start of the report range, format `YYYYMMDD`, e.g. `20260901`.",
+    },
+    to: {
+      type: "string",
+      label: "To",
+      description: "End of the report range, format `YYYYMMDD`, e.g. `20260910`.",
+    },
+    includeFixedFee: {
+      type: "boolean",
+      label: "Include Fixed Fee",
+      description: "Whether to include fixed-fee projects in the report.",
+      optional: true,
+    },
+    includeForecast: {
+      type: "boolean",
+      label: "Include Forecast",
+      description: "Whether to include forecast data (only supported when Report By is `projects` or `team`).",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const results = [];
+    let page = 1;
+    do {
+      const response = await this.harvest.getTimeReport({
+        $,
+        reportBy: this.reportBy,
+        accountId: this.accountId,
+        from: this.from,
+        to: this.to,
+        include_fixed_fee: this.includeFixedFee,
+        include_forecast: this.includeForecast,
+        per_page: constants.PAGE_SIZE,
+        page,
+      });
+      if (!response.results?.length) break;
+      const remaining = constants.MAX_AUTO_PAGINATE_RECORDS - results.length;
+      results.push(...response.results.slice(0, remaining));
+      if (!response.next_page || remaining <= response.results.length) break;
+      page += 1;
+    } while (true);
+    const count = results.length;
+    $.export("$summary", `Successfully retrieved time report by ${this.reportBy} with ${count} result${count === 1
+      ? ""
+      : "s"}`);
+    return results;
+  },
+};

package/actions/get-user/get-user.mjs

@@ -0,0 +1,40 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-get-user",
+  name: "Get User",
+  description: "Retrieve a single user by ID. Use **List Users** to find a valid ID. To fetch the authenticated user, use **Get Me** instead. Example: call with userId set to a known user's ID to see their name, email, and role. [See the documentation](https://help.getharvest.com/api-v2/users-api/users/users/#retrieve-a-user).",
+  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",
+      ],
+      optional: false,
+    },
+  },
+  async run({ $ }) {
+    const response = await this.harvest.getUser({
+      $,
+      userId: this.userId,
+      accountId: this.accountId,
+    });
+    $.export("$summary", `Successfully retrieved user ${response.id}: ${response.first_name} ${response.last_name}`);
+    return response;
+  },
+};

package/actions/get-user-assignment/get-user-assignment.mjs

@@ -0,0 +1,46 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-get-user-assignment",
+  name: "Get User Assignment",
+  description: "Retrieve a single user assignment on a project. Use **List User Assignments** to find IDs. Example: call with projectId and userAssignmentId to check that person's hourly rate on the project. [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/user-assignments/#retrieve-a-user-assignment).",
+  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",
+      ],
+    },
+    userAssignmentId: {
+      propDefinition: [
+        harvest,
+        "userAssignmentId",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.harvest.getUserAssignment({
+      $,
+      projectId: this.projectId,
+      userAssignmentId: this.userAssignmentId,
+      accountId: this.accountId,
+    });
+    $.export("$summary", `Successfully retrieved user assignment ${response.id}`);
+    return response;
+  },
+};

package/actions/list-account-id-options/list-account-id-options.mjs

@@ -3,9 +3,10 @@ import harvest from "../../harvest.app.mjs";
 export default {
   key: "harvest-list-account-id-options",
   name: "List Account ID Options",
-  description: "Retrieves available options for the Account ID field.",
-  version: "0.0.1",
+  description: "List the Harvest accounts (companies) the authenticated user has access to, each with its Account ID. Use this first to find the Account ID required by every other Harvest tool. Example: call with no parameters, then pass the returned id as Account ID on any other Harvest tool call. [See the documentation](https://help.getharvest.com/api-v2/accounts-api/accounts/accounts/#list-all-accounts-for-a-user).",
+  version: "0.0.2",
   type: "action",
+  ai: "optimized",
   annotations: {
     destructiveHint: false,
     openWorldHint: true,
@@ -15,7 +16,15 @@ export default {
     harvest,
   },
   async run({ $ }) {
-    const options = await harvest.propDefinitions.accountId.options.call(this.harvest);
+    const { accounts } = await this.harvest.listAccounts({
+      $,
+    });
+    const options = accounts.map(({
+      id, name, product,
+    }) => ({
+      label: `${name} (${product})`,
+      value: id,
+    }));
     $.export("$summary", `Successfully retrieved ${options.length} option${options.length === 1
       ? ""
       : "s"}`);