@b1-road/types

Shared types and constants for every Road SDK — the single source of truth for the Road wire contract. Entities, the permission algebra, input shapes, hosted API URLs, and the API contract version live here; @b1-road/react, @b1-road/nestjs, and every other binding re-export from this package and never redefine.

Alpha. Road is pre-1.0. This package is published under the alpha dist-tag and its surface may change between minor versions until the API graduates its contract from alpha to v1.

Install

npm install @b1-road/types

Ships dual ESM/CJS builds with type declarations. Zero runtime dependencies.

What's inside

| Export | What it is | | --- | --- | | ROAD_API_CONTRACT | The API contract version ("alpha"). SDKs build their base path as `${host}/api/${ROAD_API_CONTRACT}`. | | ROAD_API_URLS | Hosted Road API base URLs (production, sandbox). | | Entities | The resource shapes returned on the wire (business units, members, roles, permissions, …). | | Inputs | The request-body shapes the API accepts. | | Permissions | The action:subject permission algebra and its constants. | | Webhooks | Webhook event types, per-event payloads, and the delivery envelope (RoadWebhookEvent, RoadWebhookPayloads, ROAD_WEBHOOK_EVENT_TYPES). | | @b1-road/types/iam | IAM control-plane types (scopes, assignments, authorization, sessions). |

import { ROAD_API_CONTRACT, ROAD_API_URLS } from "@b1-road/types";

const baseUrl = `${ROAD_API_URLS.production}/api/${ROAD_API_CONTRACT}`;
// → https://api.road.app/api/alpha

A contract package — the API is a consumer too

Every wire type, permission constant, and hosted URL has exactly one definition. SDKs import them; they never re-declare. The Road API depends on this package as well — not as "an SDK the API consumes," but as the contract both sides agree on: the API (the producer) declares the wire shapes here and conforms its DTOs to them, while the SDKs (the consumers) read the same shapes. The dependency direction API → @b1-road/types is correct and intended. If a binding or the API needs a shape this package doesn't yet expose, it contributes the shape back here in the same change — so the API, React, Nest, and Laravel definitions can never drift. This is the load-bearing principle of the ecosystem.

Versioning

@b1-road/types carries its own semantic version, independent of the Road API's release cadence. It tracks the API on the contract axis: while ROAD_API_CONTRACT is "alpha", this package stays pre-stable 0.x. The bump to 1.0.0 happens when the API cuts its first stable contract (v1).

License

MIT