@australiangreens/ag-backend-components

Shared backend components for Australian Greens applications that integrate with the CiviCRM API. This library provides the connection layer (API client, types, errors, and caching utilities) so multiple backends can reuse the same plumbing without duplicating code.

Installation

pnpm add @australiangreens/ag-backend-components

Or with npm:

npm install @australiangreens/ag-backend-components

Requires Node.js and TypeScript. The package is published to npmjs.

Usage

Create a CiviCRM API client at app startup by passing your config (the library does not read environment variables):

import {
  createCiviClient,
  PreloadDataCache,
  GenericPromiseCache,
} from '@australiangreens/ag-backend-components';

// One-time setup
const civiApiV4 = createCiviClient({
  civicrmApiBase: 'https://civi.example.org/civicrm/ajax/api4',
  civicrmApiKey: process.env.CIVICRM_API_KEY!,
  civicrmSiteKey: process.env.CIVICRM_SITE_KEY!,
  // Optional: only needed for user-authenticated (JWT) calls
  civicrmUserApiBase: 'https://civi-{domainCode}.example.org/civicrm/ajax/api4',
});

// Call the API (key-based auth)
const result = await civiApiV4('Contact', 'get', {
  select: ['id', 'display_name'],
  limit: 10,
});
console.log(result.values);

// Optional: user-scoped call with JWT
const userResult = await civiApiV4('Contact', 'get', {}, {
  userAuth: { jwt: userJwt, domainCode: 'wa' },
});

See ARCHITECTURE.md for full API details, error handling, and migration from existing backends.

Main exports

| Export | Description | | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | createCiviClient(config) | Factory that returns a civiApiV4(entity, action, params?, options?) function. | | CiviClientConfig, CiviUserAuth, CiviApiV4Options | Config and option types for the client. | | CiviEntity, CiviEntityAction, CiviApiJsonObj, RawCiviResponse | Types for API calls and responses. | | CiviApiError, CiviApiAxiosError, CiviApiAuth0JwtError, CiviApiAuthXRejectionError, CiviApiDomainUserPermissionError, CiviApiRawHTMLError | Error classes for handling CiviCRM and auth failures. | | PreloadDataCache<T> | Write-once cache for reference data, with lookup by id and optional extra key fields. | | GenericPromiseCache<T> | TTL cache that deduplicates in-flight requests for the same key. |

Minimal example

import { createCiviClient } from '@australiangreens/ag-backend-components';

const civiApiV4 = createCiviClient({
  civicrmApiBase: 'https://civi.example.org/civicrm/ajax/api4',
  civicrmApiKey: 'your-api-key',
  civicrmSiteKey: 'your-site-key',
});

const { values } = await civiApiV4('Event', 'get', { select: ['id', 'title'], limit: 5 });

Errors are thrown as subclasses of CiviApiError; you can catch and handle them by type (e.g. CiviApiAuthXRejectionError for 401, CiviApiDomainUserPermissionError for 403).