@honua/app-platform 0.0.20-alpha.0

package/operate/client.js

@@ -0,0 +1,361 @@
+import { honuaCacheValidatorFromHeaders } from "../core/cache-state.js";
+import { HonuaHttpError } from "../core/errors.js";
+import { trimTrailingSlashes } from "../core/path-utils.js";
+import { HONUA_OPERATE_BASE_PATH, } from "./types.js";
+export function createHonuaOperate(options) {
+    return new HonuaOperateClient(options);
+}
+/**
+ * Experimental Operate observability client.
+ *
+ * Exposes telemetry status, the event/log viewers, alerts and realtime alert
+ * rules, geofence zones, investigations, and the job viewer over `/api/v1/operate`.
+ * Missing providers degrade to typed {@link HonuaOperateUnsupported} results.
+ */
+export class HonuaOperateClient {
+    #client;
+    #basePath;
+    telemetry;
+    events;
+    logs;
+    alerts;
+    alertRules;
+    geofences;
+    investigations;
+    jobs;
+    constructor(options) {
+        this.#client = options.client;
+        this.#basePath = normalizeBasePath(options.basePath ?? HONUA_OPERATE_BASE_PATH);
+        this.telemetry = new HonuaTelemetryClient(this);
+        this.events = new HonuaEventsClient(this);
+        this.logs = new HonuaLogsClient(this);
+        this.alerts = new HonuaAlertsClient(this);
+        this.alertRules = new HonuaAlertRulesClient(this);
+        this.geofences = new HonuaGeofencesClient(this);
+        this.investigations = new HonuaInvestigationsClient(this);
+        this.jobs = new HonuaJobsClient(this);
+    }
+    get basePath() {
+        return this.#basePath;
+    }
+    async raw(request) {
+        return this.requestJson("raw", request.method ?? "GET", request.path, request.body, {
+            signal: request.signal,
+            headers: request.headers,
+            okStatuses: request.okStatuses,
+        });
+    }
+    async requestJson(capability, method, path, body, options = {}) {
+        try {
+            const response = await this.#client.pipelineFetch(method, this.resolvePath(path), {
+                headers: jsonHeaders(options.headers),
+                body: body === undefined ? null : JSON.stringify(body),
+            }, options.signal, options.okStatuses ? { okStatuses: options.okStatuses } : {});
+            if (response.status === 204)
+                return supported(undefined);
+            const value = (await readJson(response));
+            return supported(value);
+        }
+        catch (error) {
+            return unsupportedFromError(capability, error);
+        }
+    }
+    async requestPage(capability, path, options = {}) {
+        try {
+            const hasValidator = Boolean(options.validator?.etag || options.validator?.lastModified);
+            const response = await this.#client.pipelineFetch("GET", this.resolvePath(withListQuery(path, options)), { headers: listHeaders(options) }, options.signal, { okStatuses: hasValidator ? [304, 404, 501] : [404, 501] });
+            if (response.status === 404 || response.status === 501) {
+                return unsupportedFromStatus(capability, response.status, await readJson(response));
+            }
+            const value = normalizePage(response.status === 304 ? undefined : await readJson(response), response, {
+                fallbackValidator: options.validator,
+            });
+            return supported(value);
+        }
+        catch (error) {
+            return unsupportedFromError(capability, error);
+        }
+    }
+    resolvePath(path) {
+        if (path.startsWith("http://") || path.startsWith("https://"))
+            return path;
+        const normalized = path.startsWith("/") ? path : `/${path}`;
+        if (normalized === this.#basePath || normalized.startsWith(`${this.#basePath}/`))
+            return normalized;
+        return `${this.#basePath}${normalized}`;
+    }
+}
+export class HonuaTelemetryClient {
+    #operate;
+    constructor(operate) {
+        this.#operate = operate;
+    }
+    listTargets(options = {}) {
+        return this.#operate.requestPage("telemetry", "/targets", options);
+    }
+    status(targetId, options = {}) {
+        return this.#operate.requestJson("telemetry", "GET", `/targets/${encodeURIComponent(targetId)}/telemetry`, undefined, options);
+    }
+}
+export class HonuaEventsClient {
+    #operate;
+    constructor(operate) {
+        this.#operate = operate;
+    }
+    query(options = {}) {
+        return this.#operate.requestPage("events", "/events", options);
+    }
+}
+export class HonuaLogsClient {
+    #operate;
+    constructor(operate) {
+        this.#operate = operate;
+    }
+    query(options = {}) {
+        return this.#operate.requestPage("logs", "/logs", options);
+    }
+}
+export class HonuaAlertsClient {
+    #operate;
+    constructor(operate) {
+        this.#operate = operate;
+    }
+    query(options = {}) {
+        return this.#operate.requestPage("alerts", "/alerts", options);
+    }
+    get(alertId, options = {}) {
+        return this.#operate.requestJson("alerts", "GET", `/alerts/${encodeURIComponent(alertId)}`, undefined, options);
+    }
+    act(alertId, request, options = {}) {
+        const { ifMatch, ...body } = request;
+        return this.#operate.requestJson("alerts", "POST", `/alerts/${encodeURIComponent(alertId)}/actions`, body, {
+            ...options,
+            headers: withIfMatch(options.headers, ifMatch),
+        });
+    }
+}
+export class HonuaAlertRulesClient {
+    #operate;
+    constructor(operate) {
+        this.#operate = operate;
+    }
+    list(options = {}) {
+        return this.#operate.requestPage("alert-rules", "/alert-rules", options);
+    }
+    get(ruleId, options = {}) {
+        return this.#operate.requestJson("alert-rules", "GET", `/alert-rules/${encodeURIComponent(ruleId)}`, undefined, options);
+    }
+    create(request, options = {}) {
+        const { ifMatch, ...body } = request;
+        return this.#operate.requestJson("alert-rules", "POST", "/alert-rules", body, {
+            ...options,
+            headers: withIfMatch(options.headers, ifMatch),
+        });
+    }
+    update(ruleId, request, options = {}) {
+        const { ifMatch, ...body } = request;
+        return this.#operate.requestJson("alert-rules", "PUT", `/alert-rules/${encodeURIComponent(ruleId)}`, body, {
+            ...options,
+            headers: withIfMatch(options.headers, ifMatch),
+        });
+    }
+    delete(ruleId, options = {}) {
+        return this.#operate.requestJson("alert-rules", "DELETE", `/alert-rules/${encodeURIComponent(ruleId)}`, undefined, {
+            ...options,
+            okStatuses: [204],
+        });
+    }
+    test(ruleId, options = {}) {
+        return this.#operate.requestJson("alert-rules", "POST", `/alert-rules/${encodeURIComponent(ruleId)}/test`, {}, options);
+    }
+}
+export class HonuaGeofencesClient {
+    #operate;
+    constructor(operate) {
+        this.#operate = operate;
+    }
+    list(options = {}) {
+        return this.#operate.requestPage("geofences", "/geofences", options);
+    }
+    get(zoneId, options = {}) {
+        return this.#operate.requestJson("geofences", "GET", `/geofences/${encodeURIComponent(zoneId)}`, undefined, options);
+    }
+    create(request, options = {}) {
+        const { ifMatch, ...body } = request;
+        return this.#operate.requestJson("geofences", "POST", "/geofences", body, {
+            ...options,
+            headers: withIfMatch(options.headers, ifMatch),
+        });
+    }
+    update(zoneId, request, options = {}) {
+        const { ifMatch, ...body } = request;
+        return this.#operate.requestJson("geofences", "PUT", `/geofences/${encodeURIComponent(zoneId)}`, body, {
+            ...options,
+            headers: withIfMatch(options.headers, ifMatch),
+        });
+    }
+    delete(zoneId, options = {}) {
+        return this.#operate.requestJson("geofences", "DELETE", `/geofences/${encodeURIComponent(zoneId)}`, undefined, {
+            ...options,
+            okStatuses: [204],
+        });
+    }
+}
+export class HonuaInvestigationsClient {
+    #operate;
+    constructor(operate) {
+        this.#operate = operate;
+    }
+    list(options = {}) {
+        return this.#operate.requestPage("investigations", "/investigations", options);
+    }
+    get(investigationId, options = {}) {
+        return this.#operate.requestJson("investigations", "GET", `/investigations/${encodeURIComponent(investigationId)}`, undefined, options);
+    }
+    create(request, options = {}) {
+        return this.#operate.requestJson("investigations", "POST", "/investigations", request, options);
+    }
+    pin(investigationId, request, options = {}) {
+        const { ifMatch, ...body } = request;
+        return this.#operate.requestJson("investigations", "POST", `/investigations/${encodeURIComponent(investigationId)}/pins`, body, { ...options, headers: withIfMatch(options.headers, ifMatch) });
+    }
+}
+export class HonuaJobsClient {
+    #operate;
+    constructor(operate) {
+        this.#operate = operate;
+    }
+    query(options = {}) {
+        return this.#operate.requestPage("jobs", "/jobs", options);
+    }
+    get(jobId, options = {}) {
+        return this.#operate.requestJson("jobs", "GET", `/jobs/${encodeURIComponent(jobId)}`, undefined, options);
+    }
+    logs(jobId, options = {}) {
+        return this.#operate.requestPage("jobs", `/jobs/${encodeURIComponent(jobId)}/logs`, options);
+    }
+    artifacts(jobId, options = {}) {
+        return this.#operate.requestPage("jobs", `/jobs/${encodeURIComponent(jobId)}/artifacts`, options);
+    }
+    act(jobId, request, options = {}) {
+        const { ifMatch, ...body } = request;
+        return this.#operate.requestJson("jobs", "POST", `/jobs/${encodeURIComponent(jobId)}/actions`, body, {
+            ...options,
+            headers: withIfMatch(options.headers, ifMatch),
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function normalizeBasePath(basePath) {
+    const normalized = basePath.startsWith("/") ? basePath : `/${basePath}`;
+    return trimTrailingSlashes(normalized);
+}
+function supported(value) {
+    return { supported: true, value };
+}
+function unsupportedFromError(capability, error) {
+    if (error instanceof HonuaHttpError && (error.statusCode === 404 || error.statusCode === 501)) {
+        return unsupportedFromStatus(capability, error.statusCode, error.body);
+    }
+    throw error;
+}
+function unsupportedFromStatus(capability, statusCode, body) {
+    const problem = toProblemDetails(body);
+    return {
+        supported: false,
+        capability,
+        statusCode,
+        reason: problem?.detail ?? problem?.title ?? `Operate capability "${capability}" is not available on this deployment.`,
+        ...(problem ? { problem } : {}),
+    };
+}
+function withListQuery(path, options) {
+    const params = new URLSearchParams();
+    if (options.cursor)
+        params.set("cursor", options.cursor);
+    if (options.limit !== undefined)
+        params.set("limit", String(options.limit));
+    if (options.targetId)
+        params.set("targetId", options.targetId);
+    if (options.q)
+        params.set("q", options.q);
+    if (options.since)
+        params.set("since", options.since);
+    if (options.until)
+        params.set("until", options.until);
+    const query = params.toString();
+    return query ? `${path}${path.includes("?") ? "&" : "?"}${query}` : path;
+}
+function jsonHeaders(headers) {
+    return {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+        ...headersToRecord(headers),
+    };
+}
+function listHeaders(options) {
+    const headers = {
+        Accept: "application/json",
+        ...headersToRecord(options.headers),
+    };
+    if (options.validator?.etag)
+        headers["If-None-Match"] = options.validator.etag;
+    if (options.validator?.lastModified)
+        headers["If-Modified-Since"] = options.validator.lastModified;
+    return headers;
+}
+function withIfMatch(headers, ifMatch) {
+    if (!ifMatch)
+        return headers;
+    return { ...headersToRecord(headers), "If-Match": ifMatch };
+}
+function headersToRecord(headers) {
+    if (!headers)
+        return {};
+    if (headers instanceof Headers)
+        return Object.fromEntries(headers.entries());
+    if (Array.isArray(headers))
+        return Object.fromEntries(headers);
+    return { ...headers };
+}
+async function readJson(response) {
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    return JSON.parse(text);
+}
+function normalizePage(body, response, options = {}) {
+    const value = isRecord(body) ? body : {};
+    const items = (Array.isArray(value.items) ? value.items : Array.isArray(value.data) ? value.data : []);
+    const pagination = isRecord(value.pagination) ? value.pagination : value;
+    const validator = honuaCacheValidatorFromHeaders(response.headers) ?? options.fallbackValidator;
+    const sourceUpdatedAt = response.headers.get("last-modified") ?? undefined;
+    return {
+        items,
+        pagination: {
+            nextCursor: stringValue(pagination.nextCursor ?? pagination.next),
+            previousCursor: stringValue(pagination.previousCursor ?? pagination.previous),
+            limit: numberValue(pagination.limit),
+            total: numberValue(pagination.total),
+        },
+        ...(validator ? { validator } : {}),
+        ...(sourceUpdatedAt ? { sourceUpdatedAt } : {}),
+    };
+}
+function toProblemDetails(body) {
+    if (!isRecord(body))
+        return undefined;
+    const candidate = isRecord(body.problem) ? body.problem : body;
+    return candidate;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}

package/operate/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Experimental Operate observability client and contracts.
+ *
+ * Shared, protocol-neutral SDK surface for the Console / MCP / Studio "Operate"
+ * screens: server telemetry status, the event and log viewers, alerts and
+ * realtime alert rules, geofence zones, delivery channel bindings,
+ * investigations, and the job viewer (runs, stages, logs, artifacts).
+ *
+ * Designed so fixture data can drive Console Operate screens before live
+ * endpoints land. Missing providers (no OTLP, no logs, no realtime, no alert
+ * delivery, no job controls, no investigation store) degrade to typed
+ * {@link HonuaOperateUnsupported} results instead of empty data or thrown errors.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver contract
+ *   — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+export { HonuaAlertRulesClient, HonuaAlertsClient, HonuaEventsClient, HonuaGeofencesClient, HonuaInvestigationsClient, HonuaJobsClient, HonuaLogsClient, HonuaOperateClient, HonuaTelemetryClient, createHonuaOperate, } from "./client.js";
+export type { HonuaOperateClientOptions } from "./client.js";
+export { HONUA_OPERATE_BASE_PATH } from "./types.js";
+export type { HonuaAlert, HonuaAlertAction, HonuaAlertActionRequest, HonuaAlertDeliveryStatus, HonuaAlertRule, HonuaAlertRuleKind, HonuaAlertRuleTestResult, HonuaAlertRuleWriteRequest, HonuaAlertSeverity, HonuaAlertStatus, HonuaDeliveryChannelBinding, HonuaGeofenceZone, HonuaGeofenceZoneWriteRequest, HonuaInvestigation, HonuaInvestigationCreateRequest, HonuaInvestigationPinRequest, HonuaInvestigationTimelineEntry, HonuaJobAction, HonuaJobActionRequest, HonuaJobArtifact, HonuaJobLog, HonuaJobRunDetail, HonuaJobRunSummary, HonuaJobStage, HonuaJobState, HonuaLogLevel, HonuaLogRecord, HonuaMetricSnapshot, HonuaObservabilityTarget, HonuaOperateCapability, HonuaOperateEntityValidators, HonuaOperateLinks, HonuaOperateListOptions, HonuaOperatePage, HonuaOperateRawRequest, HonuaOperateRequestOptions, HonuaOperateResult, HonuaOperateSuccess, HonuaOperateUnsupported, HonuaOperationalEvent, HonuaOperationalEventSeverity, HonuaProblemDetails, HonuaServerTelemetryStatus, HonuaTelemetryHealth, HonuaTelemetryProviderStatus, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/operate/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/operate/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,iBAAiB,EACjB,oBAAoB,EACpB,yBAAyB,EACzB,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,kBAAkB,GACnB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AACrD,YAAY,EACV,UAAU,EACV,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,cAAc,EACd,kBAAkB,EAClB,wBAAwB,EACxB,0BAA0B,EAC1B,kBAAkB,EAClB,gBAAgB,EAChB,2BAA2B,EAC3B,iBAAiB,EACjB,6BAA6B,EAC7B,kBAAkB,EAClB,+BAA+B,EAC/B,4BAA4B,EAC5B,+BAA+B,EAC/B,cAAc,EACd,qBAAqB,EACrB,gBAAgB,EAChB,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,aAAa,EACb,cAAc,EACd,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,EACtB,4BAA4B,EAC5B,iBAAiB,EACjB,uBAAuB,EACvB,gBAAgB,EAChB,sBAAsB,EACtB,0BAA0B,EAC1B,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,qBAAqB,EACrB,6BAA6B,EAC7B,mBAAmB,EACnB,0BAA0B,EAC1B,oBAAoB,EACpB,4BAA4B,GAC7B,MAAM,YAAY,CAAC"}

package/operate/index.js

@@ -0,0 +1,19 @@
+/**
+ * Experimental Operate observability client and contracts.
+ *
+ * Shared, protocol-neutral SDK surface for the Console / MCP / Studio "Operate"
+ * screens: server telemetry status, the event and log viewers, alerts and
+ * realtime alert rules, geofence zones, delivery channel bindings,
+ * investigations, and the job viewer (runs, stages, logs, artifacts).
+ *
+ * Designed so fixture data can drive Console Operate screens before live
+ * endpoints land. Missing providers (no OTLP, no logs, no realtime, no alert
+ * delivery, no job controls, no investigation store) degrade to typed
+ * {@link HonuaOperateUnsupported} results instead of empty data or thrown errors.
+ *
+ * @experimental This entrypoint is not yet covered by the SDK's semver contract
+ *   — the surface may change in any minor release prior to `1.0.0`.
+ * @module
+ */
+export { HonuaAlertRulesClient, HonuaAlertsClient, HonuaEventsClient, HonuaGeofencesClient, HonuaInvestigationsClient, HonuaJobsClient, HonuaLogsClient, HonuaOperateClient, HonuaTelemetryClient, createHonuaOperate, } from "./client.js";
+export { HONUA_OPERATE_BASE_PATH } from "./types.js";