@bcis/sdk

Type-safe TypeScript SDK for the BCIS (Building Cost Information Service) APIs. Supports both ESM and CommonJS environments with full TypeScript declarations.

Installation

npm install @bcis/sdk

Authentication

All BCIS APIs require a Bearer JWT obtained via OAuth2. The AuthManager class handles token acquisition, caching, and renewal automatically.

Client Credentials (server-to-server)

Use this flow for back-end or machine-to-machine integrations. Tokens are fetched and renewed automatically — no user interaction required.

import { AuthManager, CoreApiClient, DurationCalculatorClient, ResidentialRebuildClient, ScheduleOfRatesClient } from '@bcis/sdk';

const auth = new AuthManager({
  flow: 'client-credentials',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  // scopes: ['openid'],  // optional
});

OAuth2 endpoints are resolved automatically via OpenID Connect discovery (see Custom endpoints below).

Authorization Code + PKCE (user-facing applications)

Use this flow when your application acts on behalf of a logged-in user.

import { AuthManager } from '@bcis/sdk';

const auth = new AuthManager({
  flow: 'authorization-code',
  clientId: 'YOUR_CLIENT_ID',
  redirectUri: 'https://yourapp.com/callback',
  scopes: ['openid', 'profile'],
});

// Step 1 — redirect the user
const { url, codeVerifier } = await auth.getAuthorizationUrl();
// persist codeVerifier (e.g. in session), then redirect browser to url

// Step 2 — handle the callback (after user authenticates)
await auth.handleCallback(code, codeVerifier);

// Step 3 — the SDK will now attach the token to every request automatically

Custom OAuth2 endpoints

By default the SDK fetches tokenUrl and authorizationUrl from the BCIS OpenID Connect discovery document at https://id.bcis.co.uk/.well-known/openid-configuration. The result is cached in memory for the lifetime of the process.

You can override individual URLs or point to a different discovery document:

const auth = new AuthManager({
  flow: 'client-credentials',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',

  // Option A — supply a custom discovery URL (e.g. staging):
  discoveryUrl: 'https://id.staging.bcis.co.uk/.well-known/openid-configuration',

  // Option B — provide endpoint URLs directly (skips discovery entirely):
  tokenUrl: 'https://id.bcis.co.uk/oauth/token',
});

Available Clients

CoreApiClient

Base URL: https://api.bcis.co.uk/core-apis

Core APIs Documentation

Instantiation:

import { AuthManager, CoreApiClient } from '@bcis/sdk';

const client = new CoreApiClient(auth);

// Override the base URL (e.g. for a staging environment):
// const client = new CoreApiClient(auth, { baseUrl: 'https://api.bcis.co.uk/core-apis' });

Methods:

abpRetrieve(params: AbpRetrieveParams): Promise<AbpResponseDto>

Returns results from one of the BCIS Average prices studies

indicesRetrieve(params: IndicesRetrieveParams): Promise<IndicesResponseDto>

Returns index figures from one or more index series

tpsRetrieve(params: TpsRetrieveParams): Promise<TpsResponseDto>

Returns results from one of the BCIS Average prices studies

codesUpdate(params: CodesUpdateParams): Promise<CodesResponseDto>

Returns codes lists or other supporting data

DurationCalculatorClient

Base URL: https://api.bcis.co.uk/rebuild-core

Duration calculator API Documentation

Instantiation:

import { AuthManager, DurationCalculatorClient } from '@bcis/sdk';

const client = new DurationCalculatorClient(auth);

// Override the base URL (e.g. for a staging environment):
// const client = new DurationCalculatorClient(auth, { baseUrl: 'https://api.bcis.co.uk/rebuild-core' });

Methods:

getModels(params: GetModelsParams): Promise<DurationModelsDto>

This endpoint provides a list of models, quarters, and locations. Parameters from these lists will be used to perform duration calculations.

getOptions(params: GetOptionsParams): Promise<DurationModelOptionsDto>

This endpoint provides a list of: building functions, procurements, selection of contractor, and client organisations. Parameters from these lists will be used to perform duration calculations.

calculateDuration(params: CalculateDurationParams): Promise<CalculationResultDto>

This endpoint provides the calculated construction duration based on the minimal details that might be available at the feasibility stage of a construction project. For each estimate we provide two interval measures:

• Confidence interval: quantifies the uncertainty around the estimated mean duration. It gives a range that is likely to contain the true mean duration for projects with the same predictor values.
• Prediction interval: quantifies the likely range of outcomes for an individual project. It is wider than the confidence interval because it accounts both for uncertainty in the mean estimate and for the natural variability between individual projects. Example: a CI of 5–13 weeks means the expected mean is likely in that range; a PI of 3–20 weeks means an individual project's duration is likely to fall somewhere in that wider range.

ResidentialRebuildClient

Base URL: https://api.bcis.co.uk/residential-rebuild-calculator

The BCIS Rebuild Lookup Service calculates the reinstatement cost of a house or flat using minimal information. The target audience includes insurance companies and brokers that require rebuilding costs when quoting a policy on a website or using software.

Instantiation:

import { AuthManager, ResidentialRebuildClient } from '@bcis/sdk';

const client = new ResidentialRebuildClient(auth);

// Override the base URL (e.g. for a staging environment):
// const client = new ResidentialRebuildClient(auth, { baseUrl: 'https://api.bcis.co.uk/residential-rebuild-calculator' });

Methods:

calculate(params: CalculateParams): Promise<CalculationResponse>

Calculate the reinstatement cost of a house or flat

reportUsage(params: ReportUsageParams): Promise<UsageResponse>

Usage of the calculations endpoint within a specified date range

ScheduleOfRatesClient

Base URL: https://api.bcis.co.uk/schedule-of-rates

The BCIS Schedule of Rates API is designed for integration with your applications and workflows, the API enables you to retrieve and analyse comprehensive pricing information to support accurate project estimation and cost management.

Instantiation:

import { AuthManager, ScheduleOfRatesClient } from '@bcis/sdk';

const client = new ScheduleOfRatesClient(auth);

// Override the base URL (e.g. for a staging environment):
// const client = new ScheduleOfRatesClient(auth, { baseUrl: 'https://api.bcis.co.uk/schedule-of-rates' });

Methods:

getBooksEdition(): Promise<EditionsDto>

Lists books and editions available to user

getRates(params: GetRatesParams): Promise<GetRateResponseDto>

Lists matching rates

getResources(params: GetResourcesParams): Promise<GetResourceResponseDto>

Lists matching resources

getBuildUp(params: GetBuildUpParams): Promise<GetBuildUpResponseDto>

Lists components of a rate or buildUp

Error Handling

BcisApiError is thrown for any non-2xx HTTP response.

import { BcisApiError, CoreApiClient } from '@bcis/sdk';

try {
  const result = await coreApi.abpRetrieve({ ... });
} catch (err) {
  if (err instanceof BcisApiError) {
    console.error(err.status, err.statusText, err.body);
  }
}

TypeScript

All parameter and response types are exported from the package root:

import type {
  // Auth
  AuthConfig,
  ClientCredentialsConfig,
  AuthorizationCodeConfig,
  // Response types (one per API)
  AbpResponseDto,
  IndicesResponseDto,
  TpsResponseDto,
  CodesResponseDto,
  DurationModelsDto,
  DurationModelOptionsDto,
  CalculationResultDto,
  CalculationResponse,
  UsageResponse,
  EditionsDto,
  GetRateResponseDto,
  GetResourceResponseDto,
  GetBuildUpResponseDto,
} from '@bcis/sdk';