@pipedream/harvest 0.0.6 → 1.0.0

package/README.md

@@ -1,16 +1,11 @@
 # Overview
 
-The Harvest API allows developers to programmatically access data and objects
-in Harvest, a web-based time tracking application. With the API, developers can
-create applications that submit and retrieve time tracking data, as well as
-automate various aspects of the Harvest user experience.
+Harvest is a time tracking and invoicing tool that can streamline the way freelancers and businesses record time for various projects and tasks. By leveraging the Harvest API on Pipedream, you can automate complex workflows that integrate time tracking data with other business tools. Generate reports, sync project data, and manage invoices with minimal manual intervention. Pipedream's serverless platform lets you create these automations using simple, code-driven components, enabling a seamless connection between Harvest and a multitude of other apps.
 
-Some examples of what you can build using the Harvest API include:
+# Example Use Cases
 
-- A time tracking application that automatically submits time tracking data to
-  Harvest on behalf of the user
-- A reporting application that retrieves time tracking data from Harvest and
-  presents it in various charts and graphs
-- An integration with a third-party project management application that pulls
-  in time tracking data from Harvest to provide a more complete picture of
-  project progress
+- **Automated Invoicing Workflow**: Create an automation that triggers at the end of each billing cycle. It compiles timesheet data from Harvest and generates invoices automatically. Then, it sends these invoices to clients via email using a service like SendGrid or directly through accounting software like QuickBooks.
+
+- **Slack Time Tracking Reminders**: Set up a Pipedream workflow that sends reminders to a Slack channel or directly to team members. Reminders prompt users to submit their timesheets if they haven't been completed by a certain time each day or week. The Harvest API checks for unsubmitted timesheets and triggers the Slack notifications accordingly.
+
+- **Project Management Sync**: Build a workflow that synchronizes project and task updates between Harvest and a project management tool such as Trello or Asana. When a new project is created or a task is updated in Harvest, the corresponding card or task in the project management app is created or updated, keeping both systems in sync and up-to-date.

package/actions/create-invoice/create-invoice.mjs

@@ -0,0 +1,116 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-create-invoice",
+  name: "Create Invoice",
+  description: "Create a new free-form invoice for a client. Provide Line Items as a JSON array to itemize the invoice. Example: call with clientId set to InGen Corp's client ID, subject=\"Consulting Services\", lineItems=`[{\"kind\":\"Service\",\"description\":\"Genetics consulting\",\"unit_price\":2000,\"quantity\":1}]`. [See the documentation](https://help.getharvest.com/api-v2/invoices-api/invoices/invoices/#create-a-free-form-invoice).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    clientId: {
+      propDefinition: [
+        harvest,
+        "clientId",
+      ],
+      optional: false,
+    },
+    subject: {
+      propDefinition: [
+        harvest,
+        "subject",
+      ],
+    },
+    number: {
+      propDefinition: [
+        harvest,
+        "invoiceNumber",
+      ],
+      description: "The invoice number, e.g. `1000`. Defaults to the next sequential number if omitted.",
+    },
+    purchaseOrder: {
+      propDefinition: [
+        harvest,
+        "purchaseOrder",
+      ],
+    },
+    tax: {
+      propDefinition: [
+        harvest,
+        "tax",
+      ],
+    },
+    discount: {
+      propDefinition: [
+        harvest,
+        "discount",
+      ],
+    },
+    notes: {
+      propDefinition: [
+        harvest,
+        "invoiceNotes",
+      ],
+    },
+    currency: {
+      type: "string",
+      label: "Currency",
+      description: "The currency code, e.g. `USD`.",
+      optional: true,
+    },
+    issueDate: {
+      propDefinition: [
+        harvest,
+        "issueDate",
+      ],
+    },
+    dueDate: {
+      propDefinition: [
+        harvest,
+        "dueDate",
+      ],
+    },
+    lineItems: {
+      type: "string",
+      label: "Line Items",
+      description: "JSON array of line item objects. Example: `[{\"kind\":\"Service\",\"description\":\"Consulting\",\"unit_price\":100,\"quantity\":5}]`. Each item requires `kind` and `unit_price`.",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const lineItems = this.lineItems
+      ? JSON.parse(this.lineItems)
+      : undefined;
+    const response = await this.harvest.createInvoice({
+      $,
+      accountId: this.accountId,
+      data: {
+        client_id: this.clientId,
+        subject: this.subject,
+        number: this.number,
+        purchase_order: this.purchaseOrder,
+        tax: this.tax,
+        discount: this.discount,
+        notes: this.notes,
+        currency: this.currency,
+        issue_date: this.issueDate,
+        due_date: this.dueDate,
+        line_items: lineItems,
+      },
+    });
+    $.export("$summary", `Successfully created invoice ${response.id}`);
+    return response;
+  },
+};

package/actions/create-project/create-project.mjs

@@ -0,0 +1,138 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-create-project",
+  name: "Create Project",
+  description: "Create a new project. Example: call with clientId set to InGen Corp's client ID, projectName=\"Compound Perimeter Fence Upgrade\", isBillable=true, billBy=\"Project\", budgetBy=\"none\". [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/projects/#create-a-project).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    clientId: {
+      propDefinition: [
+        harvest,
+        "clientId",
+      ],
+      optional: false,
+    },
+    projectName: {
+      propDefinition: [
+        harvest,
+        "projectName",
+      ],
+      optional: false,
+    },
+    isBillable: {
+      propDefinition: [
+        harvest,
+        "isBillable",
+      ],
+      optional: false,
+    },
+    billBy: {
+      propDefinition: [
+        harvest,
+        "billBy",
+      ],
+      optional: false,
+    },
+    budgetBy: {
+      propDefinition: [
+        harvest,
+        "budgetBy",
+      ],
+      optional: false,
+    },
+    code: {
+      propDefinition: [
+        harvest,
+        "code",
+      ],
+    },
+    isActive: {
+      propDefinition: [
+        harvest,
+        "isActive",
+      ],
+      description: "Whether the project is active.",
+    },
+    isFixedFee: {
+      propDefinition: [
+        harvest,
+        "isFixedFee",
+      ],
+    },
+    hourlyRate: {
+      propDefinition: [
+        harvest,
+        "projectHourlyRate",
+      ],
+    },
+    budget: {
+      propDefinition: [
+        harvest,
+        "projectBudget",
+      ],
+    },
+    costBudget: {
+      propDefinition: [
+        harvest,
+        "costBudget",
+      ],
+    },
+    notes: {
+      propDefinition: [
+        harvest,
+        "projectNotes",
+      ],
+    },
+    startsOn: {
+      propDefinition: [
+        harvest,
+        "startsOn",
+      ],
+    },
+    endsOn: {
+      propDefinition: [
+        harvest,
+        "endsOn",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.harvest.createProject({
+      $,
+      accountId: this.accountId,
+      data: {
+        client_id: this.clientId,
+        name: this.projectName,
+        is_billable: this.isBillable,
+        bill_by: this.billBy,
+        budget_by: this.budgetBy,
+        code: this.code,
+        is_active: this.isActive,
+        is_fixed_fee: this.isFixedFee,
+        hourly_rate: this.hourlyRate,
+        budget: this.budget,
+        cost_budget: this.costBudget,
+        notes: this.notes,
+        starts_on: this.startsOn,
+        ends_on: this.endsOn,
+      },
+    });
+    $.export("$summary", `Successfully created project ${response.id}: ${response.name}`);
+    return response;
+  },
+};

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

@@ -0,0 +1,77 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-create-task-assignment",
+  name: "Create Task Assignment",
+  description: "Assign a task to a project. Use **Get Projects** to find a project ID and **List Tasks** to find a task ID. Example: call with projectId set to the Jurassic Park Construction project's ID and taskId set to the Genetics Research task's ID to put that task on the project. [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/task-assignments/#create-a-task-assignment).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    projectId: {
+      propDefinition: [
+        harvest,
+        "projectId",
+      ],
+    },
+    taskId: {
+      propDefinition: [
+        harvest,
+        "taskId",
+      ],
+    },
+    isActive: {
+      propDefinition: [
+        harvest,
+        "isActive",
+      ],
+      description: "Whether the task assignment is active.",
+    },
+    billable: {
+      propDefinition: [
+        harvest,
+        "billable",
+      ],
+    },
+    hourlyRate: {
+      propDefinition: [
+        harvest,
+        "taskAssignmentHourlyRate",
+      ],
+    },
+    budget: {
+      propDefinition: [
+        harvest,
+        "taskAssignmentBudget",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.harvest.createTaskAssignment({
+      $,
+      projectId: this.projectId,
+      accountId: this.accountId,
+      data: {
+        task_id: this.taskId,
+        is_active: this.isActive,
+        billable: this.billable,
+        hourly_rate: this.hourlyRate,
+        budget: this.budget,
+      },
+    });
+    $.export("$summary", `Successfully created task assignment ${response.id}`);
+    return response;
+  },
+};

package/actions/create-timesheet-entry/create-timesheet-entry.mjs

@@ -7,11 +7,15 @@ import {
 export default {
   key: "harvest-create-timesheet-entry",
   name: "Create Timesheet Entry",
-  description: `Creates a new time entry object. 
-  [Create a time entry via duration documentation](https://help.getharvest.com/api-v2/timesheets-api/timesheets/time-entries/#create-a-time-entry-via-duration),
-  [Create a time entry via start and end time documentation](https://help.getharvest.com/api-v2/timesheets-api/timesheets/time-entries/#create-a-time-entry-via-start-and-end-time)`,
-  version: "0.0.2",
+  description: "Create a new time entry. Two ways to log time, matching the account's Company setting: on **duration-based** accounts (`wants_timestamp_timers` is `false` — the common case) set **Hours** to log a completed entry directly. On **timestamp-based** accounts (`wants_timestamp_timers` is `true`) leave **Hours** blank and use **Started Time**/**Ended Time** instead — leave both time fields blank too to start a running timer now, or set both to log a completed entry with explicit start/end times. Passing Started/Ended Time on a duration-based account is silently ignored by Harvest (it starts a running timer instead) — if that happens, switch to **Hours**. Use **Get Projects** to find a Project ID, **List Tasks** to find a Task ID, and **List Users** to find a User ID. Example (duration-based): call with projectId, taskId, spentDate=\"2026-09-17\", hours=3.5. Example (timestamp-based): the same call with hours omitted and startedTime/endedTime set instead. [See the documentation](https://help.getharvest.com/api-v2/timesheets-api/timesheets/time-entries/#create-a-time-entry-via-duration) and [start/end time variant](https://help.getharvest.com/api-v2/timesheets-api/timesheets/time-entries/#create-a-time-entry-via-start-and-end-time).",
+  version: "1.0.0",
+  annotations: {
+    destructiveHint: false,
+    openWorldHint: true,
+    readOnlyHint: false,
+  },
   type: "action",
+  ai: "optimized",
   props: {
     harvest,
     accountId: {
@@ -24,57 +28,43 @@ export default {
       propDefinition: [
         harvest,
         "projectId",
-        (c) => ({
-          accountId: c.accountId,
-        }),
       ],
     },
     taskId: {
       propDefinition: [
         harvest,
         "taskId",
-        (c) => ({
-          accountId: c.accountId,
-        }),
       ],
     },
     spentDate: {
       type: "string",
       label: "Spent date (YYYY-MM-DD)",
-      description: "The ISO 8601 formatted date on which the time entry was spent. Example: 2019-07-26",
+      description: "The ISO 8601 formatted date on which the time entry was spent, e.g. `2019-07-26`.",
     },
     userId: {
       propDefinition: [
         harvest,
         "userId",
-        (c) => ({
-          accountId: c.accountId,
-        }),
       ],
     },
-    specifyStartEndTime: {
-      type: "boolean",
-      label: "Specify start and end time",
-      description: "Specify start and end time",
-      reloadProps: true,
+    hours: {
+      type: "string",
+      label: "Hours",
+      description: "Duration in hours, e.g. `3.5`. Use this on duration-based accounts (the common case) to log a completed entry in one call. Leave blank if using **Started Time**/**Ended Time** instead.",
+      optional: true,
+    },
+    startedTime: {
+      type: "string",
+      label: "Started time (H:MM am/pm)",
+      description: "Timestamp-based accounts only. The time the entry started, e.g. `8:00am`. Leave this and **Ended Time** blank to start a running timer now instead of logging a completed entry.",
+      optional: true,
+    },
+    endedTime: {
+      type: "string",
+      label: "Ended time (H:MM am/pm)",
+      description: "Timestamp-based accounts only. The time the entry ended, e.g. `5:00pm`. Only used when **Started Time** is also set.",
+      optional: true,
     },
-  },
-  async additionalProps() {
-    const props = {};
-    if (this.specifyStartEndTime === true) {
-      props.startedTime = {
-        type: "string",
-        label: "Start time(H:MM am/pm)",
-        description: "The time the entry started. Defaults to the current time. Example: 8:00am.",
-      };
-      props.endedTime = {
-        type: "string",
-        label: "End time(H:MM am/pm)",
-        description: "The time the entry ended. Defaults to the current time. Example: 8:00am.",
-        optional: true,
-      };
-    }
-    return props;
   },
   async run({ $ }) {
 
@@ -90,17 +80,28 @@ export default {
       throw new ConfigurationError("Invalid end time. Ensure format is (H:MM am/pm)");
     }
 
-    const params = removeNullEntries({
+    if (this.endedTime && !this.startedTime) {
+      throw new ConfigurationError("Started Time is required when Ended Time is set");
+    }
+
+    if (this.hours && (this.startedTime || this.endedTime)) {
+      throw new ConfigurationError("Set either Hours (duration-based accounts) or Started/Ended Time (timestamp-based accounts), not both");
+    }
+
+    const data = removeNullEntries({
       project_id: this.projectId,
       task_id: this.taskId,
       user_id: this.userId,
       spent_date: this.spentDate,
+      hours: this.hours !== undefined && this.hours !== null && this.hours !== ""
+        ? Number(this.hours)
+        : undefined,
       started_time: this.startedTime?.replace(/\s/g, ""),
       ended_time: this.endedTime?.replace(/\s/g, ""),
     });
     const response = await this.harvest.createTimeEntry({
       $,
-      params,
+      data,
       accountId: this.accountId,
     });
     response && $.export("$summary", "Successfully created time entry");

package/actions/create-user/create-user.mjs

@@ -0,0 +1,109 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-create-user",
+  name: "Create User",
+  description: "Create a new user in the Harvest account. Example: call with firstName=\"Ian\", lastName=\"Malcolm\", email=\"ian.malcolm@example.com\" to add a new team member. [See the documentation](https://help.getharvest.com/api-v2/users-api/users/users/#create-a-user).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    firstName: {
+      propDefinition: [
+        harvest,
+        "firstName",
+      ],
+      optional: false,
+    },
+    lastName: {
+      propDefinition: [
+        harvest,
+        "lastName",
+      ],
+      optional: false,
+    },
+    email: {
+      propDefinition: [
+        harvest,
+        "email",
+      ],
+      optional: false,
+    },
+    timezone: {
+      propDefinition: [
+        harvest,
+        "timezone",
+      ],
+      description: "The user's IANA timezone name, e.g. `America/Chicago`. Defaults to the company timezone if omitted.",
+    },
+    isContractor: {
+      propDefinition: [
+        harvest,
+        "isContractor",
+      ],
+    },
+    isActive: {
+      propDefinition: [
+        harvest,
+        "isActive",
+      ],
+      description: "Whether the user is active.",
+    },
+    weeklyCapacity: {
+      propDefinition: [
+        harvest,
+        "weeklyCapacity",
+      ],
+    },
+    defaultHourlyRate: {
+      propDefinition: [
+        harvest,
+        "defaultHourlyRate",
+      ],
+    },
+    costRate: {
+      type: "string",
+      label: "Cost Rate",
+      description: "Cost rate, decimal, e.g. `100` or `100.00`.",
+      optional: true,
+    },
+    accessRoles: {
+      propDefinition: [
+        harvest,
+        "accessRoles",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.harvest.createUser({
+      $,
+      accountId: this.accountId,
+      data: {
+        first_name: this.firstName,
+        last_name: this.lastName,
+        email: this.email,
+        timezone: this.timezone,
+        is_contractor: this.isContractor,
+        is_active: this.isActive,
+        weekly_capacity: this.weeklyCapacity,
+        default_hourly_rate: this.defaultHourlyRate,
+        cost_rate: this.costRate,
+        access_roles: this.accessRoles,
+      },
+    });
+    $.export("$summary", `Successfully created user ${response.id}: ${response.first_name} ${response.last_name}`);
+    return response;
+  },
+};

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

@@ -0,0 +1,85 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-create-user-assignment",
+  name: "Create User Assignment",
+  description: "Assign a user to a project. Use **Get Projects** to find a project ID, and **List Users** to find user IDs. Example: call with projectId and userId set to staff that person on the project. [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/user-assignments/#create-a-user-assignment).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    projectId: {
+      propDefinition: [
+        harvest,
+        "projectId",
+      ],
+    },
+    userId: {
+      propDefinition: [
+        harvest,
+        "userId",
+      ],
+      optional: false,
+    },
+    isActive: {
+      propDefinition: [
+        harvest,
+        "isActive",
+      ],
+      description: "Whether the user assignment is active.",
+    },
+    isProjectManager: {
+      propDefinition: [
+        harvest,
+        "isProjectManager",
+      ],
+    },
+    useDefaultRates: {
+      propDefinition: [
+        harvest,
+        "useDefaultRates",
+      ],
+    },
+    hourlyRate: {
+      propDefinition: [
+        harvest,
+        "userAssignmentHourlyRate",
+      ],
+    },
+    budget: {
+      propDefinition: [
+        harvest,
+        "userAssignmentBudget",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.harvest.createUserAssignment({
+      $,
+      projectId: this.projectId,
+      accountId: this.accountId,
+      data: {
+        user_id: this.userId,
+        is_active: this.isActive,
+        is_project_manager: this.isProjectManager,
+        use_default_rates: this.useDefaultRates,
+        hourly_rate: this.hourlyRate,
+        budget: this.budget,
+      },
+    });
+    $.export("$summary", `Successfully created user assignment ${response.id}`);
+    return response;
+  },
+};