open-index/open-npm huggingface dataset:
npm package: @open-operational-state/core
Description: Core model logic: normalization, validation, and aggregation for Open Operational State
Latest version: 0.3.0

# @open-operational-state/core

Core model logic for [Open Operational State](https://github.com/open-operational-state). Depends only on `@open-operational-state/types`.

## Installation

```bash
bun add @open-operational-state/core
```

## API

### `normalizeSnapshot( raw )`

Coerce a raw JSON object into a typed `Snapshot` with spec defaults applied.

```js
import { normalizeSnapshot } from '@open-operational-state/core';

const snapshot = normalizeSnapshot({
    condition: 'operational',
    profiles: ['health'],
    subject: { id: 'my-service' },
});
```

### `validateSnapshot( snapshot )`

Validate a `Snapshot` against required fields, vocabulary rules, and profile constraints. Returns `{ valid, errors, warnings }`.

```js
import { validateSnapshot } from '@open-operational-state/core';

const result = validateSnapshot( snapshot );
if ( !result.valid ) {
    console.error( result.errors );
}
```

### `worstOf( conditions )`

Return the worst (highest severity) condition from an array, using the orderable severity ranking.

```js
import { worstOf } from '@open-operational-state/core';

worstOf([ 'operational', 'degraded', 'down' ]); // 'down'
```

### `deriveParentConditionFromChecks( checks )`

Derive a parent condition from flat check entries using worst-of aggregation.

### `deriveParentConditionFromComponents( components )`

Derive a parent condition from nested component entries using worst-of aggregation.

## Dependencies

- `@open-operational-state/types`
npm package: @open-operational-state/discovery
Description: Discovery client for locating Open Operational State resources
Latest version: 0.3.0

# @open-operational-state/discovery

Discovery client for [Open Operational State](https://github.com/open-operational-state). Find and validate operational-state endpoints using HTTP Link headers and well-known paths.

## Installation

```bash
bun add @open-operational-state/discovery
```

## API

### `discover( baseUrl, options? )`

Discover operational-state resources following the priority hierarchy:

1. Link-based discovery (HTTP `Link` headers with `rel="operational-state"`)
2. Well-known path (`/.well-known/operational-state`)

```js
import { discover } from '@open-operational-state/discovery';

const result = await discover( 'https://api.example.com' );

switch ( result.method ) {
    case 'link-header':
        console.log( 'Found via Link header:', result.links );
        break;
    case 'well-known':
        console.log( 'Found via well-known:', result.document );
        break;
    case 'none':
        console.log( 'No operational-state resources found' );
        break;
}
```

### `parseLinkHeaders( headers )`

Parse HTTP `Link` headers and extract `rel="operational-state"` entries.

```js
import { parseLinkHeaders } from '@open-operational-state/discovery';

const links = parseLinkHeaders(
    '<https://api.example.com/health>; rel="operational-state"; profile="health"'
);
// [{ href: 'https://api.example.com/health', profile: 'health' }]
```

### `fetchDiscoveryDocument( baseUrl )`

Fetch and validate the discovery document from `/.well-known/operational-state`.

### `validateDiscoveryDocument( doc )`

Validate the structure of a discovery document.

```js
import { validateDiscoveryDocument } from '@open-operational-state/discovery';

const result = validateDiscoveryDocument( doc );
// { valid: true, errors: [], warnings: [] }
```

## Dependencies

- `@open-operational-state/types`
npm package: @open-operational-state/emitter
Description: Serialization emitters for Open Operational State wire formats
Latest version: 0.3.0

# @open-operational-state/emitter

Serialization emitters for [Open Operational State](https://github.com/open-operational-state). Convert core model `Snapshot` objects to spec-conformant wire formats.

## Installation

```bash
bun add @open-operational-state/emitter
```

## API

### `emitHealthResponse( snapshot )`

Convert a `Snapshot` to an `application/health+json` payload.

```js
import { emitHealthResponse } from '@open-operational-state/emitter';

const payload = emitHealthResponse( snapshot );
// Serve as: Content-Type: application/health+json
```

### `emitServiceStatus( snapshot )`

Convert a `Snapshot` to an `application/status+json` payload.

```js
import { emitServiceStatus } from '@open-operational-state/emitter';

const payload = emitServiceStatus( snapshot );
// Serve as: Content-Type: application/status+json
```

### `suggestHttpStatus( condition )`

Get the recommended HTTP status code for a condition value.

```js
import { suggestHttpStatus } from '@open-operational-state/emitter';

suggestHttpStatus( 'operational' ); // 200
suggestHttpStatus( 'degraded' );    // 200
suggestHttpStatus( 'down' );        // 503
suggestHttpStatus( 'maintenance' ); // 503
```

### `suggestHeaders( snapshot, serialization )`

Get recommended HTTP headers for a response.

```js
import { suggestHeaders } from '@open-operational-state/emitter';

const headers = suggestHeaders( snapshot, 'application/health+json' );
// { 'Content-Type': 'application/health+json', 'Cache-Control': 'no-cache, ...' }
```

### Round-Trip Guarantee

The emitter maintains the round-trip invariant:

```
parse → normalize → emit → parse → normalize
```

No semantic drift, no loss of required data, no illegal state introduced. This is enforced by golden round-trip tests.

## Dependencies

- `@open-operational-state/types`
- `@open-operational-state/core`
npm package: @open-operational-state/oos
Description: Open Operational State — serve and probe operational state endpoints
Latest version: 0.3.0

# @open-operational-state/oos

The developer-facing package for [Open Operational State](https://github.com/open-operational-state). Install this one package to get the CLI and the programmatic API.

[![npm](https://img.shields.io/npm/v/@open-operational-state/oos)](https://www.npmjs.com/package/@open-operational-state/oos)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](../../LICENSE)

## Install

```bash
npm install @open-operational-state/oos
```

## CLI

After local install, the `oos` binary is available:

```bash
npx oos probe https://api.example.com/health
npx oos validate snapshot.json
npx oos fixtures ./conformance-fixtures --format=table
npx oos inspect snapshot.json
```

Or run without installing:

```bash
npx @open-operational-state/oos probe https://api.example.com/health
```

Or install globally:

```bash
npm i -g @open-operational-state/oos
oos probe https://api.example.com/health
```

### Commands

| Command | Description |
|---|---|
| `probe <url>` | Fetch a URL, auto-detect format, parse to core model |
| `validate <file>` | Validate a JSON file against conformance levels |
| `fixtures <dir>` | Run all conformance fixtures in a directory |
| `inspect <file>` | Parse a JSON file, pretty-print core model |

### Options

| Option | Description |
|---|---|
| `--format=json\|table` | Output format (default: json) |
| `--help` | Show help |

## Programmatic API

```js
import { probe } from '@open-operational-state/oos';

const result = await probe( 'https://api.example.com/health' );

console.log( result.snapshot.condition );  // 'operational'
console.log( result.httpStatus );          // 200
console.log( result.validation.valid );    // true
```

## What this package includes

`@open-operational-state/oos` is an umbrella package that bundles:

- **`probe`** — programmatic endpoint probing
- **`validator`** — conformance validation, fixture runner, CLI implementation

You don't need to install the lower-level packages separately.

## License

Licensed under [Apache 2.0](../../LICENSE).
npm package: @open-operational-state/parser
Description: Format detection and parsing adapters for Open Operational State
Latest version: 0.3.0

# @open-operational-state/parser

Response parsers and format adapters for [Open Operational State](https://github.com/open-operational-state). Auto-detects response formats and converts them to the canonical core model.

## Installation

```bash
bun add @open-operational-state/parser
```

## API

### `parse( input )`

Auto-detect format and parse an HTTP response into a `Snapshot`.

```js
import { parse } from '@open-operational-state/parser';

const snapshot = parse({
    contentType: 'application/json',
    body: { status: 'pass', serviceId: 'my-api' },
    url: 'https://api.example.com/health',
    httpStatus: 200,
    headers: { 'content-type': 'application/json' },
});
```

### `detectFormat( contentType, body )`

Identify which adapter to apply based on content-type and structural markers.

```js
import { detectFormat } from '@open-operational-state/parser';

detectFormat( 'application/health+json', body ); // 'native-health-response'
detectFormat( 'application/status+json', body ); // 'native-service-status'
detectFormat( 'application/json', { status: 'pass' } ); // 'health-check-draft'
detectFormat( 'application/json', { status: 'UP', components: {} } ); // 'spring-boot'
detectFormat( 'text/plain', 'OK' ); // 'plain-http'
```

### Individual Adapters

| Adapter | Function | Input |
|---|---|---|
| **Plain HTTP** | `parsePlainHttp( input )` | HTTP status code + connection result |
| **Health Check Draft** | `parseHealthCheckDraft( body, options? )` | [draft-inadarei](https://datatracker.ietf.org/doc/html/draft-inadarei-api-health-check) response |
| **Spring Boot** | `parseSpringBoot( body, options? )` | Spring Boot Actuator `/actuator/health` response |
| **Native** | `parseHealthResponse( body )` | OOS `application/health+json` response |

### Format Detection Priority

1. Content-type header (`application/status+json`, `application/health+json`)
2. Structural markers (OOS native: `profiles` + `condition`)
3. Structural markers (Spring Boot: `status` ∈ {UP,DOWN,OUT_OF_SERVICE} + `components`)
4. Structural markers (draft-inadarei: `status` ∈ {pass,fail,warn})
5. Fallback to plain-http

## Dependencies

- `@open-operational-state/types`
- `@open-operational-state/core`
npm package: @open-operational-state/probe
Description: Probe any operational-state endpoint — fetch, detect, parse, normalize
Latest version: 0.3.0

# @open-operational-state/probe

Probe any operational-state endpoint — fetch, detect, parse, and normalize in a single call.

[![npm](https://img.shields.io/npm/v/@open-operational-state/probe)](https://www.npmjs.com/package/@open-operational-state/probe)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](../../LICENSE)

## Install

```bash
npm install @open-operational-state/probe
```

## Usage

```js
import { probe } from '@open-operational-state/probe';

const result = await probe( 'https://api.example.com/health' );

console.log( result.snapshot.condition );  // 'operational'
console.log( result.httpStatus );          // 200
console.log( result.validation.valid );    // true
```

### With discovery

```js
const result = await probe( 'https://api.example.com', {
    followDiscovery: true,
} );

// Follows Link headers or /.well-known/operational-state
// before probing the discovered endpoint
```

## API

### `probe( url, options? )`

Returns a `ProbeResult`:

| Field | Type | Description |
|---|---|---|
| `url` | `string` | The URL that was probed |
| `httpStatus` | `number \| null` | HTTP status, or null on connection failure |
| `contentType` | `string \| null` | Content-Type header |
| `connectionError` | `boolean` | True if the connection itself failed |
| `snapshot` | `Snapshot` | Parsed and normalized core model |
| `validation` | `ValidationResult` | Core model validation result |
| `discovery` | `DiscoverResult \| null` | Discovery result (if enabled) |

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `followDiscovery` | `boolean` | `false` | Follow OOS discovery before probing |
| `headers` | `Record<string, string>` | — | Custom request headers |
| `signal` | `AbortSignal` | — | Cancellation signal |

## Architecture

`probe` sits above the lower-level packages and orchestrates them:

```
probe → parser → core → types
      → discovery → types
```

This package is used by the `oos` CLI and is the recommended programmatic entrypoint for probing endpoints.

## License

Licensed under [Apache 2.0](../../LICENSE).
npm package: @open-operational-state/types
Description: Canonical TypeScript interfaces for the Open Operational State core model
Latest version: 0.3.0

# @open-operational-state/types

Canonical TypeScript interfaces for the [Open Operational State](https://github.com/open-operational-state) core model.

This package is the shared contract surface for all tooling packages. It contains zero runtime logic — only type declarations, constants, and type guards.

## Installation

```bash
bun add @open-operational-state/types
```

## API

### Core Interfaces

| Interface | Description |
|---|---|
| `Snapshot` | Root operational-state document |
| `Subject` | Identity and metadata for the observed service |
| `Timing` | Observation, reporting, and state-change timestamps |
| `Evidence` | Supporting data for a condition assessment |
| `Scope` | Geographic or environmental scope |
| `CheckEntry` | Flat check (used in `health-response` format) |
| `ComponentEntry` | Nested component (used in `service-status` format) |
| `DependencyEntry` | Nested dependency (used in `service-status` format) |
| `DiscoveryDocument` | `/.well-known/operational-state` document |
| `ResourceEntry` | Single resource in a discovery document |
| `ValidationResult` | Validation output with errors and warnings |
| `ConformanceResult` | Conformance level assessment |

### Condition Vocabulary

```js
import { LIVENESS_CONDITIONS, READINESS_CONDITIONS, HEALTH_CONDITIONS } from '@open-operational-state/types';
import { isHealthCondition, isExtensionCondition, conditionSeverity } from '@open-operational-state/types';

isHealthCondition( 'operational' );       // true
isExtensionCondition( 'x-acme-drain' );   // true

conditionSeverity( 'operational' );  // 1 (lowest orderable)
conditionSeverity( 'down' );         // 5 (highest orderable)
```

### Profile Helpers

```js
import { PROFILE_REQUIREMENTS, isProfileId, satisfiedProfiles } from '@open-operational-state/types';

isProfileId( 'health' );  // true
isProfileId( 'custom' );  // false

satisfiedProfiles( 'status' );  // ['liveness', 'readiness', 'health', 'status']
```

## Dependencies

None. This package has zero external dependencies.
npm package: @open-operational-state/validator
Description: Conformance validation, fixture runner, and CLI implementation for Open Operational State
Latest version: 0.3.0

# @open-operational-state/validator

Conformance validation and CLI for [Open Operational State](https://github.com/open-operational-state).

## Installation

```bash
bun add @open-operational-state/validator
```

## CLI

The `oos` CLI is included in this package.

### Commands

```bash
# Validate a JSON file against conformance levels
oos validate <file>

# Fetch a URL, auto-detect format, parse to core model
oos probe <url>

# Run all conformance fixtures in a directory
oos fixtures <dir>

# Parse a JSON file, pretty-print core model
oos inspect <file>
```

### Options

```bash
--format=json|table    Output format (default: json)
--help                 Show help
```

### Examples

```bash
# Validate a health response
oos validate response.json

# Probe a live endpoint
oos probe https://api.example.com/health

# Run conformance test suite
oos fixtures ../status-conformance/fixtures/core --format=table
#   ✓ /positive-minimal-snapshot.json
#   ✓ /negative-missing-condition.json
#   ✓ /negative-invalid-condition.json
#   3 passed, 0 failed
```

## Programmatic API

### `checkConformanceLevel( snapshot )`

Assess which conformance tier a `Snapshot` satisfies.

```js
import { checkConformanceLevel } from '@open-operational-state/validator';

const result = checkConformanceLevel( snapshot );
// { level: 'standard', basic: true, standard: true, extended: false }
```

### `loadFixture( path )` / `runFixture( fixture )`

Load and execute conformance fixtures.

```js
import { loadFixture, runFixture } from '@open-operational-state/validator';

const fixture = loadFixture( './fixtures/core/positive-minimal-snapshot.json' );
const result = runFixture( fixture );
// { passed: true, diagnostics: [] }
```

### `runFixtureDir( dirPath )`

Recursively find and execute all fixtures in a directory.

## Dependencies

- `@open-operational-state/types`
- `@open-operational-state/core`
- `@open-operational-state/parser`