@open-operational-state/probe 0.2.0

package/README.md

@@ -0,0 +1,74 @@
+# @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).

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @open-operational-state/probe
+ *
+ * Probe any operational-state endpoint — fetch, detect, parse, normalize.
+ *
+ * Depends on @open-operational-state/types, core, parser, and discovery.
+ */
+export { probe } from './probe.js';
+export type { ProbeResult, ProbeOptions } from './probe.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @open-operational-state/probe
+ *
+ * Probe any operational-state endpoint — fetch, detect, parse, normalize.
+ *
+ * Depends on @open-operational-state/types, core, parser, and discovery.
+ */
+export { probe } from './probe.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/probe.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Probe — fetch, detect, parse, normalize an operational-state endpoint.
+ *
+ * This is the programmatic API.  The CLI probe command delegates here.
+ */
+import type { Snapshot, ValidationResult } from '@open-operational-state/types';
+import type { DiscoverResult } from '@open-operational-state/discovery';
+export interface ProbeOptions {
+    /** Follow OOS discovery (Link headers / well-known) before probing. */
+    followDiscovery?: boolean;
+    /** Custom headers to send with the probe request. */
+    headers?: Record<string, string>;
+    /** AbortSignal for cancellation. */
+    signal?: AbortSignal;
+}
+export interface ProbeResult {
+    /** The URL that was probed. */
+    url: string;
+    /** HTTP status code, or null if connection failed. */
+    httpStatus: number | null;
+    /** Content-Type header value. */
+    contentType: string | null;
+    /** True if the connection itself failed (DNS, timeout, etc.). */
+    connectionError: boolean;
+    /** The parsed and normalized Snapshot. */
+    snapshot: Snapshot;
+    /** Core-model validation result. */
+    validation: ValidationResult;
+    /** Discovery result, if followDiscovery was enabled. */
+    discovery: DiscoverResult | null;
+}
+/**
+ * Probe an operational-state endpoint.
+ *
+ * Fetches the URL, auto-detects the response format, parses to the canonical
+ * core model, normalizes, and validates.
+ *
+ * @example
+ * ```js
+ * import { probe } from '@open-operational-state/probe';
+ *
+ * const result = await probe( 'https://api.example.com/health' );
+ * console.log( result.snapshot.condition ); // 'operational'
+ * ```
+ */
+export declare function probe(url: string, options?: ProbeOptions): Promise<ProbeResult>;
+//# sourceMappingURL=probe.d.ts.map

package/dist/probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../src/probe.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAIhF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAC;AAMxE,MAAM,WAAW,YAAY;IACzB,uEAAuE;IACvE,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,oCAAoC;IACpC,MAAM,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IACxB,+BAA+B;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,sDAAsD;IACtD,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iCAAiC;IACjC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,iEAAiE;IACjE,eAAe,EAAE,OAAO,CAAC;IACzB,0CAA0C;IAC1C,QAAQ,EAAE,QAAQ,CAAC;IACnB,oCAAoC;IACpC,UAAU,EAAE,gBAAgB,CAAC;IAC7B,wDAAwD;IACxD,SAAS,EAAE,cAAc,GAAG,IAAI,CAAC;CACpC;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,KAAK,CAAE,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAI,OAAO,CAAC,WAAW,CAAC,CA+FvF"}

package/dist/probe.js

@@ -0,0 +1,116 @@
+/**
+ * Probe — fetch, detect, parse, normalize an operational-state endpoint.
+ *
+ * This is the programmatic API.  The CLI probe command delegates here.
+ */
+import { normalizeSnapshot, validateSnapshot } from '@open-operational-state/core';
+import { parse } from '@open-operational-state/parser';
+import { discover } from '@open-operational-state/discovery';
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Probe an operational-state endpoint.
+ *
+ * Fetches the URL, auto-detects the response format, parses to the canonical
+ * core model, normalizes, and validates.
+ *
+ * @example
+ * ```js
+ * import { probe } from '@open-operational-state/probe';
+ *
+ * const result = await probe( 'https://api.example.com/health' );
+ * console.log( result.snapshot.condition ); // 'operational'
+ * ```
+ */
+export async function probe(url, options) {
+    // ── Optional discovery ─────────────────────────────────────────────
+    let discoveryResult = null;
+    let probeUrl = url;
+    if (options?.followDiscovery) {
+        discoveryResult = await discover(url, {
+            headers: options?.headers,
+        });
+        // If discovery found links, probe the first one instead
+        if (discoveryResult.method === 'link-header' && discoveryResult.links.length > 0) {
+            probeUrl = new URL(discoveryResult.links[0].href, url).toString();
+        }
+        else if (discoveryResult.method === 'well-known' && discoveryResult.document?.resources) {
+            const resources = discoveryResult.document.resources;
+            // Prefer health profile, fall back to first available
+            const resource = resources.find((r) => r.profiles.includes('health')) || resources[0];
+            if (resource?.href) {
+                probeUrl = new URL(resource.href, url).toString();
+            }
+        }
+    }
+    // ── Fetch ──────────────────────────────────────────────────────────
+    let response;
+    try {
+        const fetchOptions = {};
+        if (options?.headers) {
+            fetchOptions.headers = options.headers;
+        }
+        if (options?.signal) {
+            fetchOptions.signal = options.signal;
+        }
+        response = await fetch(probeUrl, fetchOptions);
+    }
+    catch (err) {
+        // Re-throw AbortError so callers can distinguish cancellation
+        if (err instanceof DOMException && err.name === 'AbortError') {
+            throw err;
+        }
+        // ── Connection failure (DNS, timeout, refused, etc.) ──────────
+        const parsed = parse({
+            url: probeUrl,
+            connectionError: true,
+        });
+        const snapshot = normalizeSnapshot(parsed);
+        const validation = validateSnapshot(snapshot);
+        return {
+            url: probeUrl,
+            httpStatus: null,
+            contentType: null,
+            connectionError: true,
+            snapshot,
+            validation,
+            discovery: discoveryResult,
+        };
+    }
+    // ── Parse & normalize (outside catch so parse errors propagate) ────
+    const contentType = response.headers.get('content-type') || '';
+    let body;
+    const rawText = await response.text();
+    try {
+        body = JSON.parse(rawText);
+    }
+    catch {
+        body = rawText;
+    }
+    const headers = {};
+    response.headers.forEach((value, key) => {
+        headers[key] = value;
+    });
+    const parsed = parse({
+        contentType,
+        body,
+        url: probeUrl,
+        httpStatus: response.status,
+        headers,
+    });
+    // parse() returns Snapshot, normalizeSnapshot() expects Record<string, unknown>.
+    // The cast is safe — Snapshot is a plain object that satisfies Record<string, unknown>.
+    const snapshot = normalizeSnapshot(parsed);
+    const validation = validateSnapshot(snapshot);
+    return {
+        url: probeUrl,
+        httpStatus: response.status,
+        contentType,
+        connectionError: false,
+        snapshot,
+        validation,
+        discovery: discoveryResult,
+    };
+}
+//# sourceMappingURL=probe.js.map

package/dist/probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../src/probe.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@open-operational-state/probe",
+  "version": "0.2.0",
+  "description": "Probe any operational-state endpoint — fetch, detect, parse, normalize",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-operational-state/status-tooling-js.git",
+    "directory": "packages/probe"
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@open-operational-state/types": "^0.2.0",
+    "@open-operational-state/core": "^0.2.0",
+    "@open-operational-state/parser": "^0.2.0",
+    "@open-operational-state/discovery": "^0.2.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.0"
+  }
+}