@solera-bl/packages

@solera-bl/packages is a public npm façade for a selected, pinned set of BuffrLabs packages. It bundles the private implementation at release time, so consumers use the npm registry only and never need GitHub Packages configuration or a GitHub token.

The repository may remain private. The published npm tarball is public and distributed under the MIT license.

Install

npm install @solera-bl/packages

Use explicit subpaths

The package intentionally has no root export. Import the capability needed by the application:

import { CoreError } from '@solera-bl/packages/core-error';
import { JWTManager } from '@solera-bl/packages/jwt-manager';
import { ResponseManager } from '@solera-bl/packages/response-manager';

The package exposes these subpaths:

• core-error
• core-helpers
• core-logger
• email-manager
• encryption-manager
• jwt-manager
• kysely-mysql-helper
• mysql-core-error-resolver
• openapi-manager
• push-notification-manager
• request-manager
• response-manager
• x12-manager
• zod-core-error-resolver

Dependency model

The exact @buffrlabs/* versions are pinned in devDependencies. They are build-time inputs only: tsdown bundles their runtime code and declaration types into the published subpaths. External runtime dependencies remain regular dependencies, while external contracts that BuffrLabs packages declare as peers remain façade peer dependencies.

For local installation, copy .npmrc.example to .npmrc, then provide a GitHub Packages token through NODE_AUTH_TOKEN. The ignored .npmrc references the environment variable and must never contain a literal token.

Before publishing, the smoke test creates a packed tarball, installs it in a clean consumer with public npm registry configuration only, and imports every public subpath. It fails if any built JavaScript or declaration file still references @buffrlabs/*.

Updating bundled packages

Updates are intentional Solera releases; this repository does not synchronize automatically with BuffrLabs.

1. Update the selected pinned @buffrlabs/* development dependency versions in package.json.
2. Run pnpm install with GitHub Packages read access to update pnpm-lock.yaml.
3. Update the public package version in package.json.
4. Run pnpm run format:check, pnpm run lint, pnpm run typecheck, and pnpm run test.
5. Merge the reviewed change.
6. Manually dispatch Publish Package from the exact revision to release, entering publish as confirmation.

The workflow refuses to republish an existing version and publishes only the stable latest package.

First release and trusted publishing

The first release is a local, manual process because npm can configure a trusted publisher only after the package exists. It uses a normal npm token and your interactive two-factor authentication; it does not require a token that bypasses two-factor authentication and does not run in GitHub Actions.

1. Create the ignored local file from the template:

   cp .env.example .env

2. Set NPM_TOKEN in .env to a short-lived npm token that has publish access to the @solera-bl organization.

3. Confirm package.json contains the intended first version, then run:

   pnpm run release:bootstrap

   The command runs formatting, linting, type checks, the packed-consumer smoke test, and the unpublished-version check. It then invokes npm publish in your terminal. Complete npm's interactive two-factor authentication when prompted.

4. After @solera-bl/packages exists on npm, open its Settings page and add a Trusted Publisher:

   • Provider: GitHub Actions
   • GitHub organization or user: solera-bl
   • Repository: solera-packages
   • Workflow filename: release.yml
   • Environment: leave blank unless this repository later adds a GitHub Environment
   • Allowed action: npm publish

5. Bump the version for a small follow-up release and dispatch Publish Package to verify trusted publishing. The workflow requests GitHub's id-token: write permission and runs npm publish without an npm token secret.

6. Once that release succeeds, delete the repository's NPM_TOKEN action secret, revoke the bootstrap token, and enable npm's package setting that requires two-factor authentication and disallows token publishing.

The npm package can be public while this GitHub repository remains private. npm provenance is not available for a public package published from a private GitHub repository.

Required GitHub Actions secret

• BUFFRLABS_PACKAGES_TOKEN: a GitHub token with read access to the private @buffrlabs/* packages.

The @solera-bl organization must exist on npm. The bootstrap token's identity needs publish access to it; later GitHub Action releases authenticate through the configured trusted publisher instead.