basecamp-client

Basecamp API client and contract built with ts-rest. The package exposes a fully typed contract, a ready-to-use client builder, and OAuth helpers so teams can share a single source of truth across services, CLIs, and tests.

Installation

npm install basecamp-client
# or
yarn add basecamp-client

Usage

Create a client

import { buildClient } from 'basecamp-client';

const client = buildClient({
  bearerToken: process.env.BASECAMP_ACCESS_TOKEN!,
  accountId: process.env.BASECAMP_ACCOUNT_ID!,
  userAgent: process.env.BASECAMP_USER_AGENT!,
});

const projects = await client.projects.list({ query: {} });
console.log(projects.body);

Iterate through paginated endpoints

for await (const project of asyncPagedIterator({
  fetchPage: client.projects.list,
  request: { query: {} },
})) {
  console.log(project.name);
}

asyncPagedIterator follows the Link response headers emitted by Basecamp collection routes, automatically fetching page=2, page=3, and beyond until the API signals the final page. The helper yields each item returned by the underlying endpoint or lets you define a custom extractItems function for non-array responses.

Refresh OAuth tokens

import { getBearerToken } from 'basecamp-client';

const bearerToken = await getBearerToken({
  clientId: process.env.BASECAMP_CLIENT_ID!,
  clientSecret: process.env.BASECAMP_CLIENT_SECRET!,
  refreshToken: process.env.BASECAMP_REFRESH_TOKEN!,
  userAgent: process.env.BASECAMP_USER_AGENT!,
});

const client = buildClient({
  bearerToken: bearerToken,
  accountId: process.env.BASECAMP_ACCOUNT_ID!,
  userAgent: process.env.BASECAMP_USER_AGENT!,
});

Contract access

import { contract } from 'basecamp-client';
import { initClient } from '@ts-rest/core';

const client = initClient(contract, { /* custom fetcher config */ });

Development

npm install

Scripts

• npm run build – bundle the package with tsup (CJS + ESM + types).
• npm run contract:check – type-check the contract with tsc --noEmit.
• npm test – execute the Vitest live smoke suite (requires Basecamp credentials and hits the real API).
• npm run format / npm run lint / npm run check – Biome formatting and linting utilities.

Environment variables

Live tests and manual scripts expect the following variables (see tests/utils.ts):

BASECAMP_CLIENT_ID
BASECAMP_CLIENT_SECRET
BASECAMP_REFRESH_TOKEN
BASECAMP_USER_AGENT
BASECAMP_ACCOUNT_ID
BASECAMP_BUCKET_ID

Populate them via .env (ignored from git) or your shell environment before running tests.

Running live tests

The Vitest suite provisions, updates, and trashes real Basecamp resources in a dedicated sandbox project. To execute the tests:

npm test

These tests are not mocked. Ensure your credentials target an account that is safe for automated writes.

Publishing

prepublishOnly runs npm run build, producing artifacts in dist/ via tsup. After verifying the bundle and contract typings, publish as usual:

npm publish