@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, ResidentialRebuildClient, ScheduleOfRatesClient } from '@bcis/sdk';

const auth = new AuthManager({
  flow: 'client-credentials',
  clientId: 'YOUR_CLIENT_ID',
  clientSecret: 'YOUR_CLIENT_SECRET',
  tokenUrl: 'https://auth.bcis.co.uk/oauth/token',
  scopes: ['openid'],  // optional
});

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',
  tokenUrl: 'https://auth.bcis.co.uk/oauth/token',
  authorizationUrl: 'https://auth.bcis.co.uk/authorize',
  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

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);

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

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);

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);

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,
  CalculationResponse,
  UsageResponse,
  EditionsDto,
  GetRateResponseDto,
  GetResourceResponseDto,
  GetBuildUpResponseDto,
} from '@bcis/sdk';