@procyon-creative/harvest-sdk

TypeScript SDK for the Harvest API v2.

Installation

npm install @procyon-creative/harvest-sdk

Quick Start

import { Harvest } from "@procyon-creative/harvest-sdk";

const harvest = new Harvest({
  accountId: "123456",
  accessToken: "your-token-here",
});

// Get the authenticated user
const me = await harvest.users.me();

// List all active clients
const clients = await harvest.clients.list({ is_active: true });

// Create a time entry
await harvest.timeEntries.create({
  project_id: 12345,
  task_id: 678,
  spent_date: "2025-01-15",
  hours: 2.5,
});

// Auto-paginate through all time entries
for await (const entry of harvest.timeEntries.listAll()) {
  console.log(entry.spent_date, entry.hours);
}

Configuration

| Option | Required | Default | Description | |--------|----------|---------|-------------| | accountId | Yes | — | Your Harvest account ID | | accessToken | Yes | — | Personal access token or OAuth2 token | | baseUrl | No | https://api.harvestapp.com/v2 | API base URL | | userAgent | No | harvest-sdk-typescript | Custom User-Agent header |

Get your credentials at id.getharvest.com/developers.

Resources

| Property | Description | |----------|-------------| | harvest.clients | Client companies | | harvest.company | Your Harvest account | | harvest.contacts | Client contacts | | harvest.estimates | Estimates and estimate messages | | harvest.estimateItemCategories | Estimate line item categories | | harvest.expenses | Expense records | | harvest.expenseCategories | Expense categories | | harvest.invoices | Invoices and invoice messages | | harvest.invoiceItemCategories | Invoice line item categories | | harvest.projects | Projects, user assignments, task assignments | | harvest.reports | Time, expense, uninvoiced, and budget reports | | harvest.roles | User roles | | harvest.tasks | Task definitions | | harvest.taskAssignments | Task assignments across projects | | harvest.timeEntries | Time entries with timer controls | | harvest.users | Users, rates, teammates, project assignments | | harvest.userAssignments | User assignments across projects |

Pagination

Single page:

const page = await harvest.timeEntries.list({ page: 1, per_page: 25 });

Auto-paginate all results:

for await (const entry of harvest.timeEntries.listAll()) {
  console.log(entry);
}

// Or collect into an array
const all = await harvest.timeEntries.listAll().toArray();

Error Handling

import {
  HarvestNotFoundError,
  HarvestRateLimitError,
  HarvestUnprocessableError,
} from "@procyon-creative/harvest-sdk";

try {
  await harvest.clients.get(999);
} catch (error) {
  if (error instanceof HarvestNotFoundError) {
    // 404
  } else if (error instanceof HarvestRateLimitError) {
    // 429 — retry after error.retryAfter seconds
  } else if (error instanceof HarvestUnprocessableError) {
    // 422 — validation error, check error.body
  }
}

Documentation

Full API docs and guides are in the docs/ folder.

License

MIT