Skip to content

Migrating from 0.x

Move from the 0.x PcoPeople client to the 1.0 PlanningCenter client.

Updated

Version 1.0 is a ground-up rewrite. The 0.x releases exposed a single hand-written PcoPeople class; 1.0 generates a typed client for every resource in all 11 Planning Center products. Nothing from the 0.x API is kept, but the mapping is mechanical.

At a glance

0.x 1.0
import { PcoPeople } from '@mackenly/planningcenterkit' import { PlanningCenter } from '@mackenly/planningcenterkit'
new PcoPeople({ appId, personalAccessToken }) new PlanningCenter({ auth: { applicationId, secret } })
new PcoPeople({ token, clientId, clientSecret, refreshToken, expiresAt }) new PlanningCenter({ auth: { accessToken, clientId, clientSecret, refreshToken, expiresAt, onTokenRefresh } })
customApiBaseUrl baseUrl
version (one version for everything, default 2024-06-09) Each product pinned to its own documented version; override with versions: { people: '...' }
client.getPerson() pco.people.people.list() (one page) or .all() (every page)
.include(['emails', 'addresses']) .include('emails', 'addresses')
.where('first_name', '=', 'Ada') .where('first_name', 'Ada')
.where('created_at', '[gte]=', '2026-01-01') .where('created_at', 'gte', '2026-01-01')
.orderBy('last_name', 'desc') .order('-last_name')
.orderBy('last_name', 'asc') .order('last_name')
.paginate(limit, offset) .perPage(n).offset(n), or let all() paginate
client.get('/people/v2/...') pco.request({ method: 'GET', path: '/people/v2/...' })
client.post(endpoint, body) / patch / delete pco.request({ method: 'POST', path, body }), or the typed create(), update(), delete()
PcoClient.getExpiration(expiresIn) tokens.expiresAt from the OAuth helpers, or normalizeTokens(raw).expiresAt
throw new Error('API request failed with status 404 ...') PcoNotFoundError and the other typed error classes

Client setup

Before:

import { PcoPeople } from '@mackenly/planningcenterkit';

const client = new PcoPeople({ appId: process.env.PCO_APP_ID, personalAccessToken: process.env.PCO_SECRET });

After:

import { PlanningCenter } from '@mackenly/planningcenterkit';

const pco = new PlanningCenter({
    auth: { applicationId: process.env.PCO_APP_ID!, secret: process.env.PCO_SECRET! },
});

appId is now applicationId, and personalAccessToken is secret (the token’s secret).

For OAuth, token is now accessToken. The new client refreshes tokens itself, and because Planning Center refresh tokens rotate, you should add onTokenRefresh to save the new ones; see Authentication.

Queries

The old client kept query state on the instance, so a where or include leaked into the next call. Builders are now immutable and start from the collection you query:

Before:

const people = await client
    .include(['emails'])
    .where('search_name_or_email', '=', 'ada@example.com')
    .orderBy('created_at', 'desc')
    .paginate(25, 0)
    .getPerson();
// people.data, people.included, people.meta

After:

const people = await pco.people.people
    .include('emails')
    .where('search_name_or_email', 'ada@example.com')
    .order('-created_at')
    .perPage(25)
    .list();
// people.data, people.included, people.meta, plus people.related(), people.totalCount, people.nextOffset

Differences to watch for:

  • Order direction. In 0.x, orderBy(field, 'asc') sent -field, which Planning Center treats as descending, and 'desc' sent field (ascending). 1.0 uses Planning Center’s own syntax: order('field') is ascending and order('-field') is descending. Check any sorted queries.
  • Defaults. 0.x always sent order=created_at, limit=10, and offset=0. 1.0 sends only what you set, so Planning Center’s defaults apply (25 per page; all() uses 100).
  • Operators. 0.x pasted the operator string into the URL. 1.0 takes 'gt' | 'gte' | 'lt' | 'lte' and only on fields that support comparison.
  • Every product. getPerson() covered only /people/v2/people. Now every collection and nested edge has its own typed builder: pco.people.households, pco.services.service_types.id('1').plans, pco.checkIns.check_ins, and so on. See Querying.

Raw requests

get, post, patch, and delete on the client become one request() that is authenticated, rate limited, and retried. Query parameters go in query instead of the URL, and the body is a plain object (it’s serialized for you):

const doc = await pco.request({ method: 'GET', path: '/people/v2/people', query: { 'where[first_name]': 'Ada' } });
await pco.request({
    method: 'PATCH',
    path: '/people/v2/people/123',
    body: { data: { type: 'Person', id: '123', attributes: { nickname: 'Ada' } } },
});

Raw requests don’t send an API version header unless you pass version. Prefer the typed methods where they exist:

await pco.people.people.id('123').update({ nickname: 'Ada' });

Errors

0.x threw a plain Error with the status in the message. 1.0 throws typed errors with the parsed response:

import { PcoApiError, PcoNotFoundError, PcoValidationError } from '@mackenly/planningcenterkit';

try {
    await pco.people.people.id('123').update({ first_name: '' });
} catch (err) {
    if (err instanceof PcoNotFoundError) console.log('gone');
    else if (err instanceof PcoValidationError) console.log(err.fieldErrors);
    else if (err instanceof PcoApiError) console.log(err.status, err.errors);
    else throw err;
}

See Errors and retries.

Packaging

  • Node.js 22 or newer is required (or Bun, Deno, Workers).
  • The package ships ESM and CommonJS builds with exports; deep imports into dist/ are no longer supported. Use the documented subpaths (/people, /webhooks, /oauth, …) instead.
  • The package has no runtime dependencies.

Type to search…

↑↓ navigate↵ selectEsc close