@focusbc/bbs-lib 0.0.2

package/readme.md

@@ -0,0 +1,154 @@
+# `@focusbc/bbs-lib`
+
+TypeScript library wrapping `deck.gl` and [`@focusbc/map-rendering`](https://www.npmjs.com/package/@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.
+
+```bash
+# 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
+
+```html
+<div id="map-overlay" style="position: relative; width: 100%; height: 100%;"></div>
+```
+
+```ts
+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)
+
+// Later, when the event/site changes:
+overlay.setContext(newContext)
+```
+
+---
+
+## Development
+
+Install dependencies and build the library from the `bbs-lib/` directory:
+
+```bash
+yarn install
+yarn build
+```
+
+From the repository root you can also run:
+
+```bash
+yarn bbs-lib build
+```
+
+The build output is generated under `dist/`. Only `dist/**/*` and this README are included in the published npm package.
+
+---
+
+## Sandbox (local manual testing)
+
+A small static page under `sandbox/` can be used to test `MapOverlay` against the integration API BBS endpoints.
+
+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:
+
+```bash
+cd bbs-lib
+yarn install
+yarn sandbox:build
+npx --yes serve sandbox -p 5173
+```
+
+For continuous rebuild on save:
+
+```bash
+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.
+
+---
+
+## Releasing the library
+
+The release process is handled by `bbs-lib/scripts/release-lib.sh` and can be started from inside `bbs-lib/`:
+
+```bash
+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:
+
+```bash
+yarn release:lib patch
+yarn release:lib minor
+yarn release:lib major
+```
+
+From the repository root, the equivalent command is:
+
+```bash
+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.
+
+### Creating `bbs-lib/.npmrc.enc` for the first time
+
+Create a temporary plaintext `bbs-lib/.npmrc` file:
+
+```ini
+//registry.npmjs.org/:_authToken=<NPM_TOKEN>
+```
+
+Then encrypt it using the repository KMS helper and remove the plaintext file:
+
+```bash
+cd bbs-lib
+bash ../auxiliary/scripts/encrypt_file.sh .npmrc .npmrc.enc
+rm .npmrc
+```
+
+Commit `bbs-lib/.npmrc.enc`. Do **not** commit `bbs-lib/.npmrc`.
+
+### 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. Re-encrypts the temporary `.npmrc` back into `.npmrc.enc`.
+6. 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.