@pipedream/harvest 0.1.0 → 1.0.0

package/actions/update-invoice/update-invoice.mjs

@@ -0,0 +1,114 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-update-invoice",
+  name: "Update Invoice",
+  description: "Update an existing invoice. Use **List Invoices** to find a valid ID. Example: call with invoiceId set to a draft invoice's ID and subject set to a new value to revise it before sending. [See the documentation](https://help.getharvest.com/api-v2/invoices-api/invoices/invoices/#update-an-invoice).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    invoiceId: {
+      propDefinition: [
+        harvest,
+        "invoiceId",
+      ],
+    },
+    clientId: {
+      propDefinition: [
+        harvest,
+        "clientId",
+      ],
+    },
+    subject: {
+      propDefinition: [
+        harvest,
+        "subject",
+      ],
+    },
+    number: {
+      propDefinition: [
+        harvest,
+        "invoiceNumber",
+      ],
+    },
+    purchaseOrder: {
+      propDefinition: [
+        harvest,
+        "purchaseOrder",
+      ],
+    },
+    tax: {
+      propDefinition: [
+        harvest,
+        "tax",
+      ],
+    },
+    discount: {
+      propDefinition: [
+        harvest,
+        "discount",
+      ],
+    },
+    notes: {
+      propDefinition: [
+        harvest,
+        "invoiceNotes",
+      ],
+    },
+    issueDate: {
+      propDefinition: [
+        harvest,
+        "issueDate",
+      ],
+    },
+    dueDate: {
+      propDefinition: [
+        harvest,
+        "dueDate",
+      ],
+    },
+    lineItems: {
+      type: "string",
+      label: "Line Items",
+      description: "JSON array of line item objects. Omit `id` to add a new line item, e.g. `[{\"kind\":\"Service\",\"description\":\"Consulting\",\"unit_price\":100,\"quantity\":5}]`. Include an existing line item's `id` (from the invoice's `line_items` in a prior response, e.g. from **Get Invoice**) plus any fields to change, e.g. `[{\"id\":53341928,\"description\":\"Consulting Phase 2\",\"unit_price\":150}]`, to update it. Include that `id` with `_destroy` set to `true`, e.g. `[{\"id\":53341928,\"_destroy\":true}]`, to delete it.",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const lineItems = this.lineItems
+      ? JSON.parse(this.lineItems)
+      : undefined;
+    const response = await this.harvest.updateInvoice({
+      $,
+      invoiceId: this.invoiceId,
+      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,
+        issue_date: this.issueDate,
+        due_date: this.dueDate,
+        line_items: lineItems,
+      },
+    });
+    $.export("$summary", `Successfully updated invoice ${response.id}`);
+    return response;
+  },
+};

package/actions/update-project/update-project.mjs

@@ -0,0 +1,140 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-update-project",
+  name: "Update Project",
+  description: "Update an existing project. Use **Get Projects** to find a project ID. Example: call with projectId set to a project's ID and projectName set to a new name to rename it. [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/projects/#update-a-project).",
+  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",
+      ],
+    },
+    clientId: {
+      propDefinition: [
+        harvest,
+        "clientId",
+      ],
+    },
+    projectName: {
+      propDefinition: [
+        harvest,
+        "projectName",
+      ],
+    },
+    isBillable: {
+      propDefinition: [
+        harvest,
+        "isBillable",
+      ],
+    },
+    billBy: {
+      propDefinition: [
+        harvest,
+        "billBy",
+      ],
+    },
+    budgetBy: {
+      propDefinition: [
+        harvest,
+        "budgetBy",
+      ],
+    },
+    code: {
+      propDefinition: [
+        harvest,
+        "code",
+      ],
+    },
+    isActive: {
+      propDefinition: [
+        harvest,
+        "isActive",
+      ],
+      description: "Whether the project is active.",
+    },
+    notes: {
+      propDefinition: [
+        harvest,
+        "projectNotes",
+      ],
+    },
+    isFixedFee: {
+      propDefinition: [
+        harvest,
+        "isFixedFee",
+      ],
+    },
+    hourlyRate: {
+      propDefinition: [
+        harvest,
+        "projectHourlyRate",
+      ],
+    },
+    budget: {
+      propDefinition: [
+        harvest,
+        "projectBudget",
+      ],
+    },
+    costBudget: {
+      propDefinition: [
+        harvest,
+        "costBudget",
+      ],
+    },
+    startsOn: {
+      propDefinition: [
+        harvest,
+        "startsOn",
+      ],
+    },
+    endsOn: {
+      propDefinition: [
+        harvest,
+        "endsOn",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.harvest.updateProject({
+      $,
+      projectId: this.projectId,
+      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,
+        notes: this.notes,
+        is_fixed_fee: this.isFixedFee,
+        hourly_rate: this.hourlyRate,
+        budget: this.budget,
+        cost_budget: this.costBudget,
+        starts_on: this.startsOn,
+        ends_on: this.endsOn,
+      },
+    });
+    $.export("$summary", `Successfully updated project ${response.id}: ${response.name}`);
+    return response;
+  },
+};

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

@@ -0,0 +1,77 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-update-task-assignment",
+  name: "Update Task Assignment",
+  description: "Update a task assignment on a project. Use **List Task Assignments** to find IDs. Example: call with projectId, taskAssignmentId, and billable=false to stop billing that task on the project. [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/task-assignments/#update-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",
+      ],
+    },
+    taskAssignmentId: {
+      propDefinition: [
+        harvest,
+        "taskAssignmentId",
+      ],
+    },
+    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.updateTaskAssignment({
+      $,
+      projectId: this.projectId,
+      taskAssignmentId: this.taskAssignmentId,
+      accountId: this.accountId,
+      data: {
+        is_active: this.isActive,
+        billable: this.billable,
+        hourly_rate: this.hourlyRate,
+        budget: this.budget,
+      },
+    });
+    $.export("$summary", `Successfully updated task assignment ${response.id}`);
+    return response;
+  },
+};

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

@@ -0,0 +1,92 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-update-time-entry",
+  name: "Update Time Entry",
+  description: "Update an existing time entry. Use **List Time Entries** to find a valid ID. Example: call with timeEntryId set to a logged entry's ID and hours set to a corrected value to fix a mistaken time entry. [See the documentation](https://help.getharvest.com/api-v2/timesheets-api/timesheets/time-entries/#update-a-time-entry).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    timeEntryId: {
+      propDefinition: [
+        harvest,
+        "timeEntryId",
+      ],
+    },
+    projectId: {
+      propDefinition: [
+        harvest,
+        "projectId",
+      ],
+      optional: true,
+    },
+    taskId: {
+      propDefinition: [
+        harvest,
+        "taskId",
+      ],
+      optional: true,
+    },
+    spentDate: {
+      type: "string",
+      label: "Spent Date",
+      description: "Date of the entry, format `YYYY-MM-DD`, e.g. `2026-09-17`.",
+      optional: true,
+    },
+    startedTime: {
+      type: "string",
+      label: "Started Time",
+      description: "Start time, e.g. `8:00am`.",
+      optional: true,
+    },
+    endedTime: {
+      type: "string",
+      label: "Ended Time",
+      description: "End time, e.g. `9:00am`.",
+      optional: true,
+    },
+    hours: {
+      type: "string",
+      label: "Hours",
+      description: "Decimal hours, e.g. `3.5`.",
+      optional: true,
+    },
+    notes: {
+      type: "string",
+      label: "Notes",
+      description: "Notes for the entry.",
+      optional: true,
+    },
+  },
+  async run({ $ }) {
+    const response = await this.harvest.updateTimeEntry({
+      $,
+      id: this.timeEntryId,
+      accountId: this.accountId,
+      data: {
+        project_id: this.projectId,
+        task_id: this.taskId,
+        spent_date: this.spentDate,
+        started_time: this.startedTime,
+        ended_time: this.endedTime,
+        hours: this.hours,
+        notes: this.notes,
+      },
+    });
+    $.export("$summary", `Successfully updated time entry ${response.id}`);
+    return response;
+  },
+};

package/actions/update-user/update-user.mjs

@@ -0,0 +1,106 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-update-user",
+  name: "Update User",
+  description: "Update an existing user. Use **List Users** to find a valid ID. Example: call with userId set to a user's ID and lastName set to a new value to update their name. [See the documentation](https://help.getharvest.com/api-v2/users-api/users/users/#update-a-user).",
+  version: "0.0.1",
+  type: "action",
+  ai: "optimized",
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    openWorldHint: true,
+  },
+  props: {
+    harvest,
+    accountId: {
+      propDefinition: [
+        harvest,
+        "accountId",
+      ],
+    },
+    userId: {
+      propDefinition: [
+        harvest,
+        "userId",
+      ],
+      optional: false,
+    },
+    firstName: {
+      propDefinition: [
+        harvest,
+        "firstName",
+      ],
+    },
+    lastName: {
+      propDefinition: [
+        harvest,
+        "lastName",
+      ],
+    },
+    email: {
+      propDefinition: [
+        harvest,
+        "email",
+      ],
+    },
+    timezone: {
+      propDefinition: [
+        harvest,
+        "timezone",
+      ],
+    },
+    isContractor: {
+      propDefinition: [
+        harvest,
+        "isContractor",
+      ],
+    },
+    isActive: {
+      propDefinition: [
+        harvest,
+        "isActive",
+      ],
+      description: "Whether the user is active.",
+    },
+    weeklyCapacity: {
+      propDefinition: [
+        harvest,
+        "weeklyCapacity",
+      ],
+    },
+    defaultHourlyRate: {
+      propDefinition: [
+        harvest,
+        "defaultHourlyRate",
+      ],
+    },
+    accessRoles: {
+      propDefinition: [
+        harvest,
+        "accessRoles",
+      ],
+    },
+  },
+  async run({ $ }) {
+    const response = await this.harvest.updateUser({
+      $,
+      userId: this.userId,
+      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,
+        access_roles: this.accessRoles,
+      },
+    });
+    $.export("$summary", `Successfully updated user ${response.id}: ${response.first_name} ${response.last_name}`);
+    return response;
+  },
+};

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

@@ -0,0 +1,84 @@
+import harvest from "../../harvest.app.mjs";
+
+export default {
+  key: "harvest-update-user-assignment",
+  name: "Update User Assignment",
+  description: "Update a user assignment on a project. Use **List User Assignments** to find IDs. Example: call with projectId, userAssignmentId, and hourlyRate=\"150\" to set that person's custom billing rate on the project. [See the documentation](https://help.getharvest.com/api-v2/projects-api/projects/user-assignments/#update-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",
+      ],
+    },
+    userAssignmentId: {
+      propDefinition: [
+        harvest,
+        "userAssignmentId",
+      ],
+    },
+    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.updateUserAssignment({
+      $,
+      projectId: this.projectId,
+      userAssignmentId: this.userAssignmentId,
+      accountId: this.accountId,
+      data: {
+        is_active: this.isActive,
+        is_project_manager: this.isProjectManager,
+        use_default_rates: this.useDefaultRates,
+        hourly_rate: this.hourlyRate,
+        budget: this.budget,
+      },
+    });
+    $.export("$summary", `Successfully updated user assignment ${response.id}`);
+    return response;
+  },
+};

package/common/constants.mjs

@@ -3,10 +3,60 @@ export default {
   BASE_URL: "api.harvestapp.com",
   VERSION_PATH: "/v2",
   PAGE_SIZE: 100,
-  retriableStatusCodes: [
+  // Cap for tools that auto-paginate to completion (list-time-entries, list-invoices, etc.) —
+  // bounds worst-case wall clock and result size instead of fetching an account's entire
+  // history unbounded. Documented in each such tool's description. Kept modest rather than
+  // Harvest's own page-size ceiling (2000) because these tools return full, unshaped objects
+  // (nested project/task/user/client sub-objects) with no field-selection param — a large
+  // cap here produces a response too big for the calling agent to usefully read in one call.
+  MAX_AUTO_PAGINATE_RECORDS: 200,
+  // Paces per-item lookups (e.g. get-projects with explicit Project IDs) well under Harvest's
+  // account-wide rate limit of 100 requests per 15 seconds, leaving headroom for other
+  // concurrent API usage on the same account instead of racing right up to the ceiling.
+  RATE_LIMIT_BATCH_SIZE: 8,
+  RATE_LIMIT_BATCH_DELAY_MS: 1500,
+  RETRIABLE_STATUS_CODES: [
     408,
     429,
     500,
   ],
   DB_LAST_DATE_CHECK: "DB_LAST_DATE_CHECK",
+  REPORT_BY_OPTIONS: Object.freeze([
+    "clients",
+    "projects",
+    "tasks",
+    "team",
+  ]),
+  BILL_BY_OPTIONS: Object.freeze([
+    "Project",
+    "Tasks",
+    "People",
+    "none",
+  ]),
+  BUDGET_BY_OPTIONS: Object.freeze([
+    "project",
+    "project_cost",
+    "task",
+    "task_fees",
+    "person",
+    "none",
+  ]),
+  INVOICE_STATE_OPTIONS: Object.freeze([
+    "draft",
+    "open",
+    "paid",
+    "closed",
+  ]),
+  ACCESS_ROLE_OPTIONS: Object.freeze([
+    "member",
+    "manager",
+    "administrator",
+    "project_creator",
+    "billable_rates_manager",
+    "managed_projects_invoice_drafter",
+    "managed_projects_invoice_manager",
+    "client_and_task_manager",
+    "time_and_expenses_manager",
+    "estimates_manager",
+  ]),
 };