@bcis/sdk 0.0.1 → 0.1.1

package/README.md

@@ -1 +1,268 @@
-# sdk-typescript
+# @bcis/sdk
+
+Type-safe TypeScript SDK for the [BCIS (Building Cost Information Service)](https://bcis.co.uk) APIs.
+Supports both **ESM** and **CommonJS** environments with full TypeScript declarations.
+
+---
+
+## Installation
+
+```bash
+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.
+
+```typescript
+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.
+
+```typescript
+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:**
+
+```typescript
+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
+
+| Parameter | Type | Required | Description |
+|-----------|------|:--------:|-------------|
+| `include-data-for-graph` | boolean |  | When true, returns additional data for graph plotting. Default false. |
+| `include-subclasses` | boolean |  | When true, includes sub-divided categories (e.g., size bands) in results. Default false. |
+| `building-function` | string[] | ✓ | A comma-separated list of building function codes used to filter study results. [See the Codes Update API](/docs/bcis-gr |
+| `type-of-work` | string[] | ✓ | A list of type of work codes to filter the results by, the example contains all valid codes. |
+| `abp-study` | `'ABPBUI'` \| `'ABPFUN'` \| `'ABPGRP'` \| `'ABPEM2'` \| `'ABPEUR'` \| `'ABPEXT'` | ✓ | A six-character code identifying the BCIS study |
+
+#### `indicesRetrieve(params: IndicesRetrieveParams): Promise<IndicesResponseDto>`
+
+Returns index figures from one or more index series
+
+| Parameter | Type | Required | Description |
+|-----------|------|:--------:|-------------|
+| `base-of-series` | string |  | Restricts the index series by year e.g. `1985` or description `1985 mean = 100`. Ignored if a series number is provided. |
+| `regularity` | string[] |  | Restricts index series by `regularity` (`monthly`, `quarterly`, `annual`). Ignored if a series number is used. Defaults  |
+| `end-date` | string |  | Restricts index figures up to a specific month `yyyy-mm`, or leave blank for latest available. |
+| `start-date` | string |  | Restricts index figures to a specific month `yyyy-mm`, or leave blank for earliest available. |
+| `series-identification` | string[] | ✓ | Comma-delimited list of short names (e.g. `BCISTPI:AllIn`) or series numbers. [See the Codes Update API](/docs/bcis-grac |
+
+#### `tpsRetrieve(params: TpsRetrieveParams): Promise<TpsResponseDto>`
+
+Returns results from one of the BCIS Average prices studies
+
+| Parameter | Type | Required | Description |
+|-----------|------|:--------:|-------------|
+| `short-tps-name` | string | ✓ | Supports suffixes to filter or refine the study data:    - Level Filters:       - `:region`, `:county`, `:district`      |
+
+#### `codesUpdate(params: CodesUpdateParams): Promise<CodesResponseDto>`
+
+Returns codes lists or other supporting data
+
+| Parameter | Type | Required | Description |
+|-----------|------|:--------:|-------------|
+| `if-changed-since` | string |  | A date in `yyyy-mm-dd` format. Returns only codes added or modified since this date. Not supported for all code types. L |
+| `version` | string |  | A version string to select relevant code tables. |
+| `code-type` | `'shortTPSName'` \| `'ABPStudy'` \| `'BuildingFunction'` \| `'BuildingFunction:Categories'` \| `'BuildingFunction:[1-9]'` \| `'BuildingFunction:Duration'` \| `'BuildingFunction:Duration:Categories'` \| `'BuildingFunction:Duration:[1-9]'` \| `'BuildingFunction:ABP'` \| `'SimplifiedTypeOfWork'` | ✓ |    A string to select the code list required. The supported values are:    - `seriesIdentification`: All regularity name |
+
+---
+
+### `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:**
+
+```typescript
+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
+
+| Parameter | Type | Required | Description |
+|-----------|------|:--------:|-------------|
+| `postCode` | string | ✓ | Postcode of the property |
+| `type` | string | ✓ | Type of the property |
+| `storeys` | string | ✓ | Number of storeys in the property |
+| `style` | string | ✓ | Style of the property: detached, terraced, etc |
+| `wallType` | string | ✓ | Type of the walls of the property |
+| `roofType` | string |  | Type of the roof of the property |
+| `yearBuilt` | number | ✓ | Year the property was built |
+| `noOfFlats` | number |  | Number of flats |
+| `area` | number |  | Area of the property in sq.m. |
+| `noOfRooms` | number |  | Number of rooms in the property |
+| `noOfBedrooms` | number |  | Number of bedrooms in the property |
+| `noOfGarageSpaces` | number |  | Number of garage spaces in the property |
+| `noOfBathrooms` | number |  | Number of bathrooms in the property |
+| `specialFeatures` | string |  | Special features of the property, Must be blank, or a comma delimited list containing one or more of 'cellar' or 'noexte |
+
+#### `reportUsage(params: ReportUsageParams): Promise<UsageResponse>`
+
+Usage of the calculations endpoint within a specified date range
+
+| Parameter | Type | Required | Description |
+|-----------|------|:--------:|-------------|
+| `startMonth` | string |  | First month of the usage report |
+| `endMonth` | string |  | Last month of the usage report |
+
+---
+
+### `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:**
+
+```typescript
+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
+
+| Parameter | Type | Required | Description |
+|-----------|------|:--------:|-------------|
+| `selected-node-id` | string |  | node id, returned data are for the selected node |
+| `filter-text` | string |  | filter term, returned nodes contain the text somewhere in that branch |
+| `edition-id` | string | ✓ | id obtained from get-books-edition |
+
+#### `getResources(params: GetResourcesParams): Promise<GetResourceResponseDto>`
+
+Lists matching resources
+
+| Parameter | Type | Required | Description |
+|-----------|------|:--------:|-------------|
+| `selected-node-id` | string |  | node id, returned data are for the selected node |
+| `filter-text` | string |  | filter term, returned nodes contain the text somewhere in that branch |
+| `edition-id` | string | ✓ | id obtained from get-books-edition |
+
+#### `getBuildUp(params: GetBuildUpParams): Promise<GetBuildUpResponseDto>`
+
+Lists components of a rate or buildUp
+
+| Parameter | Type | Required | Description |
+|-----------|------|:--------:|-------------|
+| `entity-id` | string | ✓ | Id as returned from GetRates or GetResources |
+
+
+---
+
+## Error Handling
+
+`BcisApiError` is thrown for any non-2xx HTTP response.
+
+```typescript
+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:
+
+```typescript
+import type {
+  // Auth
+  AuthConfig,
+  ClientCredentialsConfig,
+  AuthorizationCodeConfig,
+  // Response types (one per API)
+  AbpResponseDto,
+  IndicesResponseDto,
+  TpsResponseDto,
+  CodesResponseDto,
+  CalculationResponse,
+  UsageResponse,
+  EditionsDto,
+  GetRateResponseDto,
+  GetResourceResponseDto,
+  GetBuildUpResponseDto,
+} from '@bcis/sdk';
+```