npm package: @nospt/backstage-plugin-tech-radar-ng-common
Description: Common functionalities for the tech-radar-ng plugin
Author: NOS SGPS, S.A.
Latest version: 0.9.7

<div align="center">

<img src="https://raw.githubusercontent.com/nosportugal/backstage-plugin-tech-radar-ng/main/images/logo-common.png" alt="Tech Radar NG — Common" width="50%" />

# @nospt/backstage-plugin-tech-radar-ng-common

**Shared library for the Tech Radar NG suite.**

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](../../LICENSE) [![Backstage](https://img.shields.io/badge/role-common--library-blueviolet)](https://backstage.io) [![Beta](https://img.shields.io/badge/status-beta-orange)](#)

</div>

> [!WARNING] > **BETA** — This package is under active development. Types, schemas, and enums may change between versions.

---

## Overview

This package contains the **shared types, enums, and Zod validation schemas** used by both the frontend and backend plugins of the Tech Radar NG suite. It is the foundation that keeps the contract between client and server in sync.

---

## Installation

```bash
yarn add @nospt/backstage-plugin-tech-radar-ng-common
```

> **Note:** This package is automatically installed as a dependency of both `@nospt/backstage-plugin-tech-radar-ng` and `@nospt/backstage-plugin-tech-radar-ng-backend`. You typically do not need to install it directly.

---

## Exports

### Enums

| Enum               | Values                                                        | Description                        |
| ------------------ | ------------------------------------------------------------- | ---------------------------------- |
| `RingValues`       | `adopt`, `trial`, `assess`, `hold`                            | Radar ring identifiers             |
| `Platform`         | `github`                                                      | Discovery source platforms         |
| `CandidateOrderBy` | `name`, `popularity_score`, `usage_score`, `last_activity_at` | Sort options for candidate queries |

### Types

| Type                    | Description                                                     |
| ----------------------- | --------------------------------------------------------------- |
| `Segment`               | Radar segment with name and search params                       |
| `Ring`                  | Radar ring with name and color                                  |
| `Candidate`             | Discovered technology candidate with metrics and classification |
| `PaginatedResult<T>`    | Generic paginated response wrapper                              |
| `CandidateQueryOptions` | Input type for candidate list queries                           |
| `CandidatesPatch`       | Batch candidate classification payload                          |
| `RingPatch`             | Ring update payload                                             |
| `SegmentPatch`          | Segment update payload                                          |

### Zod Schemas

| Schema                 | Description                                                                     |
| ---------------------- | ------------------------------------------------------------------------------- |
| `candidateQuerySchema` | Validates and coerces candidate query parameters (pagination, filters, sorting) |
| `candidatePatchSchema` | Validates batch candidate classification requests                               |
| `segmentPatchSchema`   | Validates segment update payloads                                               |
| `ringPatchSchema`      | Validates ring update payloads                                                  |

All schemas use **Zod v4** with `safeParse` + `z.treeifyError` for structured error responses.

---

## Usage

```ts
import { RingValues, Platform, candidateQuerySchema, type Candidate } from '@nospt/backstage-plugin-tech-radar-ng-common';

// Validate query params
const result = candidateQuerySchema.safeParse(req.query);
if (!result.success) {
  const errors = z.treeifyError(result.error);
  // handle errors
}

// Use types
const candidate: Candidate = {
  id: 'uuid',
  name: 'langchain',
  url: 'https://github.com/langchain-ai/langchain',
  popularity_score: 12500,
  usage_score: 3400,
  popularity_score_variation: 5.2,
  usage_score_variation: 3.1,
  in_radar: true,
  is_active: true,
  platform: Platform.GITHUB,
};
```

---

## Development

```bash
cd plugins/tech-radar-ng-common
yarn build       # Build (must be built before frontend/backend)
yarn test        # Run tests
yarn lint        # Lint
```

> **Important:** This package must be built before building the frontend or backend packages, as they depend on it.

---

## Related Packages

| Package                                                                     | Description                                       |
| --------------------------------------------------------------------------- | ------------------------------------------------- |
| [`@nospt/backstage-plugin-tech-radar-ng`](../tech-radar-ng)                 | Frontend — Radar visualization and Back Office UI |
| [`@nospt/backstage-plugin-tech-radar-ng-backend`](../tech-radar-ng-backend) | Backend — Discovery engine, metrics, REST API     |

---

## License

[Apache License 2.0](../../LICENSE)