@focusbc/bbs-lib

TypeScript library wrapping deck.gl and @focusbc/map-rendering for BBS map rendering.

The library exposes a high-level MapOverlay API that receives the BBS map context returned by the integration API and renders the corresponding static and dynamic map layers.

Installation

The package is published to npm under the @focusbc scope.

# Using yarn
yarn add @focusbc/bbs-lib

# Using npm
npm install @focusbc/bbs-lib

Because this package depends on @focusbc/map-rendering and deck.gl, consumers should use compatible deck.gl versions with the ones declared by the package.

Usage

<div id="map-overlay" style="position: relative; width: 100%; height: 100%;"></div>

import { MapOverlay, type MapContext } from '@focusbc/bbs-lib'

const context: MapContext = {
  // Context returned by the BBS/integration API
}

const overlay = MapOverlay.initialize(document.getElementById('map-overlay')!, context)

overlay.click().subscribe(({ shape, lat, lng }) => {
  console.log('left click', { shape, lat, lng })
})

overlay.doubleClick().subscribe(({ shape, lat, lng }) => {
  console.log('double click', { shape, lat, lng })
})

overlay.rightClick().subscribe(({ shape, lat, lng }) => {
  console.log('right click', { shape, lat, lng })
})

// Later, when the event/site changes:
overlay.setContext(newContext)

Development

Install dependencies and build the library from the bbs-lib/ directory:

yarn install
yarn build

From the repository root you can also run:

yarn bbs-lib build

The build output is generated under dist/. Only dist/**/* and this README are included in the published npm package. The demo/ and sandbox/ folders are not published (see package.json "files" and .npmignore).

Sandbox (local manual testing)

A small static page under sandbox/ can be used to test MapOverlay against the integration API BBS endpoints. Unlike demo/, the sandbox bundles the local library source from this repo.

1. Copy sandbox/config.example.ts to sandbox/config.ts and set:

   • INTEGRATION_API_BASE — for example, http://localhost:5016
   • BBS_API_KEY — must match Settings.BbsApiKey in your local integration-api config

2. Start integration-api locally.

3. Build and serve the sandbox:

cd bbs-lib
yarn install
yarn sandbox:build
npx --yes serve sandbox -p 5173

For continuous rebuild on save:

yarn sandbox:watch

Open http://localhost:5173, select an event, then a site. The overlay calls MapOverlay.initialize on first site selection and setContext on subsequent changes.

Client demo

The client-facing reference implementation lives in demo/. It is a static site (index.html + main.js) with no build step. See demo/README.md.

From this directory:

yarn demo:serve

Or from the repository root:

yarn bbs-demo:serve

To run the demo folder on its own, serve it statically — for example npx --yes serve . -p 5174 from demo/.

Releasing the library

The release process is handled by bbs-lib/scripts/release-lib.sh and can be started from inside bbs-lib/:

yarn release:lib

By default, this performs a patch release, for example 1.0.0 → 1.0.1.

You can also choose the version bump explicitly:

yarn release:lib patch
yarn release:lib minor
yarn release:lib major

From the repository root, the equivalent command is:

yarn release:bbs-lib

Release prerequisites

1. You must have access to publish @focusbc/bbs-lib under the @focusbc npm scope.
2. You must have the Google Cloud CLI installed and authenticated.
3. Your Google Cloud user must be able to decrypt/encrypt with the existing KMS key used by auxiliary/scripts/decrypt_file.sh and auxiliary/scripts/encrypt_file.sh.
4. bbs-lib/.npmrc.enc must exist. This is the encrypted version of the npm credentials file and is the only credential file that should be committed.

What happens during release

When you run yarn release:lib, the script:

1. Decrypts bbs-lib/.npmrc.enc into a temporary local bbs-lib/.npmrc.
2. Bumps package.json using npm version <patch|minor|major> --no-git-tag-version.
3. Builds the package with npm run build.
4. Publishes the package to https://registry.npmjs.org/ with npm publish --access public.
5. Uploads dist/browser/bbs-lib.js to Cloud Storage at gs://bbs-lib-bucket/bbs-lib (override with BBS_LIB_BUCKET_URI or BBS_LIB_BUCKET).
6. Re-encrypts the temporary .npmrc back into .npmrc.enc.
7. Removes the plaintext .npmrc from disk.

If the release fails after the version bump, review package.json before retrying because the version may already have been changed locally.