@studiometa/productive-api

Productive.io API client, TypeScript types, and response formatters. Zero internal dependencies — this is the foundation package for all @studiometa/productive-* packages.

Installation

npm install @studiometa/productive-api

Usage

API Client

import { ProductiveApi } from '@studiometa/productive-api';

const api = new ProductiveApi({
  config: {
    apiToken: 'your-api-token',
    organizationId: 'your-org-id',
  },
});

const projects = await api.getProjects({ page: 1, perPage: 50 });
console.log(projects.data);

Response Formatters

Transform raw JSON:API responses into clean, flat objects:

import { formatListResponse, formatSingleResponse } from '@studiometa/productive-api';

const formatted = formatListResponse(projects.data, projects.meta, {
  compact: true,
  included: projects.included,
});

Configuration

Read credentials from environment variables or a JSON config file:

import { getConfig, setConfig } from '@studiometa/productive-api';

// Read from env (PRODUCTIVE_API_TOKEN, PRODUCTIVE_ORG_ID, PRODUCTIVE_USER_ID)
const config = getConfig();

// Or set programmatically
setConfig('apiToken', 'your-token');

Exports

| Export | Description | | ------------------------- | ---------------------------------------------------------------------------------------- | | ProductiveApi | API client class with methods for all resources | | ProductiveApiError | Typed error class for API failures | | getConfig / setConfig | Configuration helpers (env vars + JSON file) | | format* | Response formatters for each resource type | | Type definitions | ProductiveProject, ProductiveTimeEntry, ProductiveTask, ProductiveActivity, etc. |

API Methods

The ProductiveApi class provides methods for:

• Projects — getProjects, getProject
• Time entries — getTimeEntries, getTimeEntry, createTimeEntry, updateTimeEntry, deleteTimeEntry
• Tasks — getTasks, getTask, createTask, updateTask
• People — getPeople, getPerson
• Services — getServices
• Companies — getCompanies, getCompany, createCompany, updateCompany
• Comments — getComments, getComment, createComment, updateComment
• Timers — getTimers, getTimer, startTimer, stopTimer
• Deals — getDeals, getDeal, createDeal, updateDeal
• Bookings — getBookings, getBooking, createBooking, updateBooking
• Reports — getReport (time, project, budget, person, invoice, payment, service, task, company, deal, timesheet)
• Activities — getActivities

License

MIT © Studio Meta