@ovok/cli 0.0.0-stage → 0.1.0-dev.13

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @ovok/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+```bash
+printf %s "$SECRET" | ovok login --base-url https://api.sandbox.ovok.com --client-id <id> --client-secret-stdin
+ovok listen --fhir Observation --forward-to http://localhost:3000/fhir
+ovok listen --signals-url https://<your-tunnel>/signals --signals-event alert.triggered
+ovok webhooks list
+```
+
+- `listen` opens a FHIR WebSocket Subscription for each `--fhir` criteria and posts each resource to
+  `--forward-to`, signed with `X-Signature` the way a rest-hook Subscription is.
+- With `--signals-url` it also creates a temporary Signals webhook that reaches every resident,
+  or with `--signals-reach attached` only the residents attached to it.
+  Signals posts to that URL itself, so it must be public, such as a tunnel to your machine.
+- Ctrl+C removes everything `listen` created and names anything it could not remove. A second
+  Ctrl+C quits at once, leaving whatever was not removed yet.
+- `webhooks` lists, creates, deletes, tests, enables, disables and rotates Signals webhooks.
+- Signals routes need a manager app; FHIR Subscriptions need an app whose policy can create one.
+- Profiles live in `~/.config/ovok/profiles.json`, readable by you only. In CI, set
+  `OVOK_BASE_URL`, `OVOK_CLIENT_ID` and `OVOK_CLIENT_SECRET` instead of logging in.

package/dist/adapters/fhir-websocket-subscriptions.js

@@ -0,0 +1,120 @@
+import { OvokApiError } from "./ovok-api.js";
+import { bindMessage, readBinding, readNotification } from "./websocket-protocol.js";
+const SUBSCRIPTION_PATH = "fhir/R4/Subscription";
+const HANDSHAKE_TIMEOUT_MS = 10_000;
+const BINDING_RENEWAL_MARGIN_MS = 60_000;
+const NOT_FOUND = 404;
+/** FHIR WebSocket Subscriptions through Ovok's API host, as `ovok listen` opens them. */
+export class FhirWebSocketSubscriptions {
+    #api;
+    #openSocket;
+    constructor(api, openSocket = (url) => new WebSocket(url)) {
+        this.#api = api;
+        this.#openSocket = openSocket;
+    }
+    async open(criteria, listener) {
+        const created = await this.#api.request("POST", SUBSCRIPTION_PATH, websocketSubscription(criteria));
+        if (typeof created?.id !== "string")
+            throw new Error("Ovok's Subscription answer had no id.");
+        const subscription = new LiveSubscription(this.#api, created.id, listener);
+        try {
+            await subscription.connect(this.#openSocket);
+            return subscription;
+        }
+        catch (error) {
+            await subscription.close().catch(() => undefined);
+            throw error;
+        }
+    }
+}
+function websocketSubscription(criteria) {
+    return {
+        resourceType: "Subscription",
+        status: "active",
+        reason: "ovok listen",
+        criteria,
+        channel: { type: "websocket" },
+    };
+}
+class LiveSubscription {
+    id;
+    #api;
+    #listener;
+    #socket = null;
+    #renewal = null;
+    #closing = false;
+    constructor(api, id, listener) {
+        this.#api = api;
+        this.id = id;
+        this.#listener = listener;
+    }
+    async connect(openSocket) {
+        const binding = await this.#binding();
+        const socket = openSocket(binding.websocketUrl);
+        this.#socket = socket;
+        await handshake(socket, binding.token);
+        socket.addEventListener("message", (event) => this.#receive(event.data));
+        socket.addEventListener("close", (event) => this.#closed(event.code));
+        this.#scheduleRenewal(binding);
+    }
+    /** Medplum drops a websocket Subscription once its socket closes, so the delete may find nothing. */
+    async close() {
+        this.#closing = true;
+        if (this.#renewal !== null)
+            clearTimeout(this.#renewal);
+        this.#socket?.close();
+        await this.#api.request("DELETE", `${SUBSCRIPTION_PATH}/${this.id}`).catch(ignoreNotFound);
+    }
+    async #binding() {
+        const path = `${SUBSCRIPTION_PATH}/${this.id}/$get-ws-binding-token`;
+        return readBinding(await this.#api.request("GET", path));
+    }
+    #receive(data) {
+        const notification = readNotification(data);
+        if (notification?.type !== "event-notification")
+            return;
+        for (const resource of notification.resources)
+            this.#listener.onResource(resource);
+    }
+    #closed(code) {
+        if (!this.#closing)
+            this.#listener.onLost(`Ovok closed the subscription socket (code ${code}).`);
+    }
+    #scheduleRenewal(binding) {
+        if (Number.isNaN(binding.expiresAt))
+            return;
+        const delay = Math.max(binding.expiresAt - Date.now() - BINDING_RENEWAL_MARGIN_MS, 0);
+        this.#renewal = setTimeout(() => void this.#renew(), delay);
+    }
+    async #renew() {
+        try {
+            const binding = await this.#binding();
+            this.#socket?.send(bindMessage(binding.token));
+            this.#scheduleRenewal(binding);
+        }
+        catch (error) {
+            this.#listener.onLost(`The subscription binding could not be renewed: ${messageOf(error)}`);
+        }
+    }
+}
+function handshake(socket, token) {
+    const { promise, resolve, reject } = Promise.withResolvers();
+    const settled = new AbortController();
+    const timer = setTimeout(() => reject(new Error("Ovok did not confirm the subscription in time.")), HANDSHAKE_TIMEOUT_MS);
+    const options = { signal: settled.signal };
+    socket.addEventListener("open", () => socket.send(bindMessage(token)), options);
+    socket.addEventListener("message", (event) => readNotification(event.data)?.type === "handshake" && resolve(), options);
+    socket.addEventListener("error", () => reject(new Error("The subscription socket failed.")), options);
+    socket.addEventListener("close", () => reject(new Error("The subscription socket closed.")), options);
+    return promise.finally(() => {
+        clearTimeout(timer);
+        settled.abort();
+    });
+}
+function ignoreNotFound(error) {
+    if (!(error instanceof OvokApiError && error.status === NOT_FOUND))
+        throw error;
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/adapters/http-forwarder.js

@@ -0,0 +1,31 @@
+import { createHmac } from "node:crypto";
+const FORWARD_TIMEOUT_MS = 10_000;
+/** Posts each resource the way a FHIR rest-hook Subscription delivers it, signed with `X-Signature`. */
+export class HttpForwarder {
+    #target;
+    #secret;
+    #fetch;
+    constructor(target, secret, fetchImpl = fetch) {
+        this.#target = target;
+        this.#secret = secret;
+        this.#fetch = fetchImpl;
+    }
+    async forward(resource) {
+        const body = JSON.stringify(resource);
+        const response = await this.#fetch(this.#target, {
+            method: "POST",
+            headers: {
+                "content-type": "application/fhir+json",
+                "x-signature": signatureOf(body, this.#secret),
+            },
+            body,
+            signal: AbortSignal.timeout(FORWARD_TIMEOUT_MS),
+        });
+        await response.body?.cancel();
+        return { status: response.status };
+    }
+}
+/** Medplum's rest-hook signature: the hex HMAC-SHA256 of the body under the Subscription's secret. */
+export function signatureOf(body, secret) {
+    return createHmac("sha256", secret).update(body).digest("hex");
+}

package/dist/adapters/ovok-api.js

@@ -0,0 +1,99 @@
+const TOKEN_PATH = "oauth2/token";
+const TOKEN_RENEWAL_MARGIN_MS = 60_000;
+const FALLBACK_TOKEN_LIFETIME_SECONDS = 3600;
+const REQUEST_TIMEOUT_MS = 30_000;
+export class OvokApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+    }
+}
+/** Ovok's HTTP API as one client application, holding its token until shortly before it expires. */
+export class OvokApi {
+    #profile;
+    #fetch;
+    #now;
+    #token = null;
+    constructor(profile, fetchImpl = fetch, now = Date.now) {
+        this.#profile = profile;
+        this.#fetch = fetchImpl;
+        this.#now = now;
+    }
+    async verify() {
+        await this.accessToken();
+    }
+    async accessToken() {
+        if (this.#token === null || this.#now() >= this.#token.expiresAt - TOKEN_RENEWAL_MARGIN_MS) {
+            this.#token = await this.#requestToken();
+        }
+        return this.#token.value;
+    }
+    async request(method, path, body) {
+        const json = body !== undefined;
+        const response = await this.#fetch(this.#profile.baseUrl.resolve(path), {
+            method,
+            headers: {
+                authorization: `Bearer ${await this.accessToken()}`,
+                accept: "application/json, application/fhir+json",
+                ...(json ? { "content-type": "application/json" } : {}),
+            },
+            body: json ? JSON.stringify(body) : null,
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        return (await readJson(response, `${method} ${path}`));
+    }
+    async #requestToken() {
+        const response = await this.#fetch(this.#profile.baseUrl.resolve(TOKEN_PATH), {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "client_credentials",
+                client_id: this.#profile.clientId,
+                client_secret: this.#profile.clientSecret,
+            }),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        const token = (await readJson(response, "Sign-in"));
+        if (typeof token?.access_token !== "string") {
+            throw new OvokApiError(response.status, "Ovok's token answer had no access token.");
+        }
+        const lifetimeSeconds = typeof token.expires_in === "number" ? token.expires_in : FALLBACK_TOKEN_LIFETIME_SECONDS;
+        return { value: token.access_token, expiresAt: this.#now() + lifetimeSeconds * 1000 };
+    }
+}
+async function readJson(response, action) {
+    const text = await response.text();
+    const body = text === "" ? null : parseJson(text);
+    if (!response.ok) {
+        throw new OvokApiError(response.status, `${action} failed (${response.status}): ${detailOf(body)}`);
+    }
+    return body;
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+/** The readable part of an error body: problem+json, a FHIR OperationOutcome, an OAuth error or plain text. */
+export function detailOf(body) {
+    if (typeof body === "string")
+        return body;
+    if (typeof body !== "object" || body === null)
+        return "no details";
+    const fields = body;
+    const issue = Array.isArray(fields.issue) ? fields.issue[0] : null;
+    const candidates = [
+        fields.detail,
+        fields.error_description,
+        issue?.diagnostics,
+        issue?.details?.text,
+        fields.title,
+        fields.message,
+    ];
+    const found = candidates.find((candidate) => typeof candidate === "string");
+    return typeof found === "string" ? found : "no details";
+}

package/dist/adapters/profile-file-store.js

@@ -0,0 +1,60 @@
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ApiBaseUrl } from "../domain/api-base-url.js";
+const OWNER_ONLY_DIRECTORY = 0o700;
+const OWNER_ONLY_FILE = 0o600;
+export function configDirectory(env) {
+    return join(env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "ovok");
+}
+/** Profiles in one JSON file that only its owner can read, as client secrets are in it. */
+export class ProfileFileStore {
+    #directory;
+    #file;
+    constructor(directory) {
+        this.#directory = directory;
+        this.#file = join(directory, "profiles.json");
+    }
+    async find(name) {
+        const stored = (await this.#read()).profiles[name];
+        return stored === undefined ? null : toProfile(name, stored);
+    }
+    async save(profile) {
+        const all = await this.#read();
+        all.profiles[profile.name] = toStored(profile);
+        await this.#write(all);
+    }
+    async remove(name) {
+        const { profiles } = await this.#read();
+        if (!Object.hasOwn(profiles, name))
+            return false;
+        const remaining = Object.fromEntries(Object.entries(profiles).filter(([key]) => key !== name));
+        await this.#write({ profiles: remaining });
+        return true;
+    }
+    async #read() {
+        try {
+            return JSON.parse(await readFile(this.#file, "utf8"));
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return { profiles: {} };
+            throw error;
+        }
+    }
+    async #write(all) {
+        await mkdir(this.#directory, { recursive: true, mode: OWNER_ONLY_DIRECTORY });
+        await writeFile(this.#file, `${JSON.stringify(all, null, 2)}\n`, { mode: OWNER_ONLY_FILE });
+        await chmod(this.#file, OWNER_ONLY_FILE);
+    }
+}
+function toProfile(name, stored) {
+    return { ...stored, name, baseUrl: ApiBaseUrl.parse(stored.baseUrl) };
+}
+function toStored(profile) {
+    return {
+        baseUrl: profile.baseUrl.toString(),
+        clientId: profile.clientId,
+        clientSecret: profile.clientSecret,
+    };
+}

package/dist/adapters/signals-gateway-webhooks.js

@@ -0,0 +1,58 @@
+const USERS_PATH = "v1/signals/api/user";
+const SUBSCRIBER_PATH = "v1/signals/api/subscriber";
+const SUBSCRIBER_ROLE = "SUBSCRIBER";
+const LIST_PAGE_SIZE = 100;
+/** Signals subscribers through Ovok's Signals gateway, which only lets a manager touch subscribers. */
+export class SignalsGatewayWebhooks {
+    #api;
+    constructor(api) {
+        this.#api = api;
+    }
+    async list() {
+        const page = await this.#api.request("GET", `${USERS_PATH}?limit=${LIST_PAGE_SIZE}`);
+        return (page.items ?? []).filter(isSubscriber).map(toSubscriber);
+    }
+    async create(request) {
+        const created = await this.#api.request("POST", USERS_PATH, {
+            role: SUBSCRIBER_ROLE,
+            name: request.name,
+            webhookUrl: request.webhookUrl,
+            events: request.events,
+            reach: request.reach,
+        });
+        const signingSecret = typeof created.signingSecret === "string" ? created.signingSecret : null;
+        return { ...toSubscriber(created), signingSecret };
+    }
+    async remove(id) {
+        await this.#api.request("DELETE", `${USERS_PATH}/${encodeURIComponent(id)}`);
+    }
+    test(id) {
+        return this.#api.request("POST", webhookPath(id, "test"));
+    }
+    rotateSecret(id) {
+        return this.#api.request("POST", webhookPath(id, "rotate-secret"));
+    }
+    async enable(id) {
+        await this.#api.request("POST", webhookPath(id, "enable"));
+    }
+    async disable(id) {
+        await this.#api.request("POST", webhookPath(id, "disable"));
+    }
+}
+function webhookPath(id, action) {
+    return `${SUBSCRIBER_PATH}/${encodeURIComponent(id)}/webhook/${action}`;
+}
+function isSubscriber(user) {
+    return String(user.role).toUpperCase() === SUBSCRIBER_ROLE;
+}
+export function toSubscriber(user) {
+    if (typeof user.id !== "string")
+        throw new Error("Signals answered a subscriber without an id.");
+    return {
+        id: user.id,
+        name: typeof user.name === "string" ? user.name : null,
+        webhookUrl: typeof user.webhookUrl === "string" ? user.webhookUrl : null,
+        events: Array.isArray(user.events) ? user.events.map(String) : [],
+        reach: user.reach === "all" ? "all" : "attached",
+    };
+}

package/dist/adapters/terminal-listen-output.js

@@ -0,0 +1,36 @@
+/** One line per event, naming resources by type and id only: their bodies can carry health data. */
+export class TerminalListenOutput {
+    #print;
+    constructor(print) {
+        this.#print = print;
+    }
+    subscriptionOpened(subscription, criteria) {
+        this.#print(`Opened FHIR Subscription/${subscription.id} for "${criteria}".`);
+    }
+    signalsWebhookCreated(subscriber) {
+        this.#print(`Created Signals webhook ${subscriber.id} for ${subscriber.events.join(", ")} -> ${subscriber.webhookUrl ?? "no URL"}.`);
+        if (subscriber.signingSecret !== null) {
+            this.#print(`Signals signs each delivery (Standard Webhooks) with ${subscriber.signingSecret}.`);
+        }
+    }
+    forwarded(resource, delivery) {
+        this.#print(`${timestamp()}  ${referenceOf(resource)}  -> ${delivery.status}`);
+    }
+    forwardFailed(resource, error) {
+        this.#print(`${timestamp()}  ${referenceOf(resource)}  -> failed: ${messageOf(error)}`);
+    }
+    cleanedUp(outcome) {
+        this.#print(outcome.error === null
+            ? `Removed ${outcome.label}.`
+            : `Could not remove ${outcome.label}: ${messageOf(outcome.error)}. Remove it yourself.`);
+    }
+}
+function referenceOf(resource) {
+    return `${resource.resourceType}/${resource.id ?? "?"}`;
+}
+function timestamp() {
+    return new Date().toISOString().slice(11, 19);
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/adapters/websocket-protocol.js

@@ -0,0 +1,43 @@
+export function bindMessage(token) {
+    return JSON.stringify({ type: "bind-with-token", payload: { token } });
+}
+export function readBinding(parameters) {
+    const list = parameters?.parameter ?? [];
+    const parameterValue = (name) => {
+        const parameter = list.find((entry) => entry.name === name);
+        return parameter?.valueString ?? parameter?.valueUrl ?? parameter?.valueDateTime;
+    };
+    const [token, websocketUrl, expiration] = [
+        parameterValue("token"),
+        parameterValue("websocket-url"),
+        parameterValue("expiration"),
+    ];
+    if (typeof token !== "string" || typeof websocketUrl !== "string") {
+        throw new Error("Ovok's binding token answer had no token or websocket URL.");
+    }
+    const expiresAt = typeof expiration === "string" ? Date.parse(expiration) : Number.NaN;
+    return { token, websocketUrl, expiresAt };
+}
+export function readNotification(data) {
+    const message = typeof data === "string" ? parseObject(data) : null;
+    if (message?.resourceType !== "Bundle" || !Array.isArray(message.entry))
+        return null;
+    const [statusEntry, ...resourceEntries] = message.entry;
+    const status = statusEntry?.resource;
+    if (status?.resourceType !== "SubscriptionStatus" || typeof status.type !== "string")
+        return null;
+    return { type: status.type, resources: resourceEntries.flatMap(resourceOf) };
+}
+function resourceOf(entry) {
+    const resource = entry.resource;
+    return typeof resource?.resourceType === "string" ? [resource] : [];
+}
+function parseObject(text) {
+    try {
+        const value = JSON.parse(text);
+        return typeof value === "object" && value !== null ? value : null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/application/listen.js

@@ -0,0 +1,52 @@
+import { Cleanup } from "../domain/cleanup.js";
+/** Everything a listen session sets up on Ovok, and its removal when the session stops. */
+export class ListenSession {
+    #deps;
+    #cleanup = new Cleanup();
+    #lost = Promise.withResolvers();
+    #forwarding = Promise.resolve();
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    /** Settles when Ovok drops a subscription, so the session can stop instead of hearing nothing. */
+    get lost() {
+        return this.#lost.promise;
+    }
+    async openFhir(criteria, forwarder) {
+        const subscription = await this.#deps.fhir.open(criteria, {
+            onResource: (resource) => this.#enqueue(resource, forwarder),
+            onLost: (reason) => this.#lost.resolve(reason),
+        });
+        this.#cleanup.add({
+            label: `FHIR Subscription/${subscription.id}`,
+            run: () => subscription.close(),
+        });
+        this.#deps.output.subscriptionOpened(subscription, criteria);
+    }
+    /** Signals posts to the URL itself, so it must be one Signals can reach, such as a tunnel. */
+    async openSignals(request) {
+        const subscriber = await this.#deps.signals.create(request);
+        this.#cleanup.add({
+            label: `Signals webhook ${subscriber.id}`,
+            run: () => this.#deps.signals.remove(subscriber.id),
+        });
+        this.#deps.output.signalsWebhookCreated(subscriber);
+    }
+    async stop() {
+        for (const outcome of await this.#cleanup.run()) {
+            this.#deps.output.cleanedUp(outcome);
+        }
+        await this.#forwarding;
+    }
+    #enqueue(resource, forwarder) {
+        this.#forwarding = this.#forwarding.then(() => this.#forwardOne(resource, forwarder));
+    }
+    async #forwardOne(resource, forwarder) {
+        try {
+            this.#deps.output.forwarded(resource, await forwarder.forward(resource));
+        }
+        catch (error) {
+            this.#deps.output.forwardFailed(resource, error);
+        }
+    }
+}

package/dist/application/login.js

@@ -0,0 +1,5 @@
+/** Keeps a profile only once Ovok has accepted its credentials. */
+export async function login(profile, verifier, store) {
+    await verifier.verify();
+    await store.save(profile);
+}

package/dist/application/profiles.js

@@ -0,0 +1,23 @@
+import { ApiBaseUrl } from "../domain/api-base-url.js";
+export const ENVIRONMENT_PROFILE = "environment";
+export class NotSignedInError extends Error {
+}
+/** CI sets all three variables; anything less falls back to a saved profile. */
+export function profileFromEnvironment(env) {
+    const { OVOK_BASE_URL, OVOK_CLIENT_ID, OVOK_CLIENT_SECRET } = env;
+    if (!OVOK_BASE_URL || !OVOK_CLIENT_ID || !OVOK_CLIENT_SECRET)
+        return null;
+    return {
+        name: ENVIRONMENT_PROFILE,
+        baseUrl: ApiBaseUrl.parse(OVOK_BASE_URL),
+        clientId: OVOK_CLIENT_ID,
+        clientSecret: OVOK_CLIENT_SECRET,
+    };
+}
+export async function resolveProfile(name, store, env) {
+    const profile = profileFromEnvironment(env) ?? (await store.find(name));
+    if (profile === null) {
+        throw new NotSignedInError(`No profile "${name}". Run "ovok login" first.`);
+    }
+    return profile;
+}

package/dist/application/signals-webhooks.js

@@ -0,0 +1 @@
+export {};

package/dist/commands/command.js

@@ -0,0 +1,11 @@
+/** The caller asked for something the command cannot read; the exit code says so. */
+export class UsageError extends Error {
+}
+export async function readAll(input) {
+    const decoder = new TextDecoder();
+    let text = "";
+    for await (const chunk of input) {
+        text += typeof chunk === "string" ? chunk : decoder.decode(chunk, { stream: true });
+    }
+    return text.trim();
+}

package/dist/commands/listen.js

@@ -0,0 +1,94 @@
+import { randomBytes } from "node:crypto";
+import { parseArgs } from "node:util";
+import { FhirWebSocketSubscriptions } from "../adapters/fhir-websocket-subscriptions.js";
+import { HttpForwarder } from "../adapters/http-forwarder.js";
+import { SignalsGatewayWebhooks } from "../adapters/signals-gateway-webhooks.js";
+import { TerminalListenOutput } from "../adapters/terminal-listen-output.js";
+import { ListenSession } from "../application/listen.js";
+import { resolveProfile } from "../application/profiles.js";
+import { DEFAULT_PROFILE } from "../domain/profile.js";
+import { UsageError } from "./command.js";
+import { reachOf } from "./reach-option.js";
+const SIGNING_SECRET_BYTES = 32;
+const DEFAULT_SIGNALS_EVENTS = ["alert.*"];
+export const listenCommand = async (args, context) => {
+    const options = listenOptionsOf(args);
+    const api = context.connect(await resolveProfile(options.profile, context.profiles, context.env));
+    const session = new ListenSession({
+        fhir: new FhirWebSocketSubscriptions(api),
+        signals: new SignalsGatewayWebhooks(api),
+        output: new TerminalListenOutput(context.print),
+    });
+    const stop = context.stopSignal();
+    let lostReason = null;
+    try {
+        await openFhir(session, options, context);
+        await openSignals(session, options);
+        context.print("Ready. Press Ctrl+C to stop; what is listed above is removed then.");
+        lostReason = await Promise.race([stop.stopped.then(() => null), session.lost]);
+    }
+    finally {
+        await session.stop();
+        stop.dispose();
+    }
+    if (lostReason !== null)
+        throw new Error(lostReason);
+};
+function listenOptionsOf(args) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            profile: { type: "string", default: DEFAULT_PROFILE },
+            fhir: { type: "string", multiple: true, default: [] },
+            "forward-to": { type: "string" },
+            "signals-url": { type: "string" },
+            "signals-event": { type: "string", multiple: true, default: DEFAULT_SIGNALS_EVENTS },
+            "signals-reach": { type: "string", default: "all" },
+        },
+    });
+    const options = {
+        profile: values.profile,
+        fhir: values.fhir,
+        forwardTo: values["forward-to"] === undefined ? null : URL.parse(values["forward-to"]),
+        signalsUrl: values["signals-url"] ?? null,
+        signalsEvents: values["signals-event"],
+        signalsReach: reachOf(values["signals-reach"], "--signals-reach"),
+    };
+    assertListensToSomething(options);
+    return options;
+}
+function assertListensToSomething(options) {
+    if (options.fhir.length === 0 && options.signalsUrl === null) {
+        throw new UsageError("Pass --fhir <criteria> with --forward-to <url>, --signals-url <url>, or both.");
+    }
+    if (options.fhir.length > 0 && options.forwardTo === null) {
+        throw new UsageError("--fhir needs --forward-to <url>, such as http://localhost:3000/fhir.");
+    }
+}
+async function openFhir(session, options, context) {
+    if (options.forwardTo === null)
+        return;
+    const secret = signingSecretOf(context);
+    const forwarder = new HttpForwarder(options.forwardTo, secret.value);
+    for (const criteria of options.fhir)
+        await session.openFhir(criteria, forwarder);
+    context.print(`Forwarding FHIR events to ${options.forwardTo}, signed with X-Signature: ${secret.description}.`);
+}
+async function openSignals(session, options) {
+    if (options.signalsUrl === null)
+        return;
+    await session.openSignals({
+        name: `ovok listen ${new Date().toISOString()}`,
+        webhookUrl: options.signalsUrl,
+        events: options.signalsEvents,
+        reach: options.signalsReach,
+    });
+}
+function signingSecretOf(context) {
+    const fromEnvironment = context.env.OVOK_LISTEN_SECRET;
+    if (fromEnvironment) {
+        return { value: fromEnvironment, description: "the secret in OVOK_LISTEN_SECRET" };
+    }
+    const value = randomBytes(SIGNING_SECRET_BYTES).toString("hex");
+    return { value, description: `HMAC-SHA256 with secret ${value}` };
+}

package/dist/commands/login.js

@@ -0,0 +1,40 @@
+import { parseArgs } from "node:util";
+import { login } from "../application/login.js";
+import { ApiBaseUrl } from "../domain/api-base-url.js";
+import { DEFAULT_PROFILE } from "../domain/profile.js";
+import { readAll, UsageError } from "./command.js";
+const DEFAULT_BASE_URL = "https://api.sandbox.ovok.com";
+export const loginCommand = async (args, context) => {
+    const { values } = parseArgs({
+        args,
+        options: {
+            profile: { type: "string", default: DEFAULT_PROFILE },
+            "base-url": { type: "string", default: DEFAULT_BASE_URL },
+            "client-id": { type: "string" },
+            "client-secret-stdin": { type: "boolean", default: false },
+        },
+    });
+    const profile = {
+        name: values.profile,
+        baseUrl: ApiBaseUrl.parse(values["base-url"]),
+        clientId: clientIdOf(values["client-id"], context),
+        clientSecret: await clientSecretOf(values["client-secret-stdin"], context),
+    };
+    await login(profile, context.connect(profile), context.profiles);
+    context.print(`Signed in to ${profile.baseUrl} as ${profile.clientId}.`);
+    context.print(`Saved as profile "${profile.name}".`);
+};
+function clientIdOf(flag, context) {
+    const clientId = flag ?? context.env.OVOK_CLIENT_ID;
+    if (!clientId)
+        throw new UsageError("Pass --client-id, or set OVOK_CLIENT_ID.");
+    return clientId;
+}
+/** Never a flag value: those end up in shell history and process lists. */
+async function clientSecretOf(fromStdin, context) {
+    const secret = fromStdin ? await readAll(context.stdin) : context.env.OVOK_CLIENT_SECRET;
+    if (!secret) {
+        throw new UsageError("Pipe the client secret in with --client-secret-stdin, or set OVOK_CLIENT_SECRET.");
+    }
+    return secret;
+}

package/dist/commands/logout.js

@@ -0,0 +1,10 @@
+import { parseArgs } from "node:util";
+import { DEFAULT_PROFILE } from "../domain/profile.js";
+export const logoutCommand = async (args, context) => {
+    const { values } = parseArgs({
+        args,
+        options: { profile: { type: "string", default: DEFAULT_PROFILE } },
+    });
+    const removed = await context.profiles.remove(values.profile);
+    context.print(removed ? `Removed profile "${values.profile}".` : `There is no profile "${values.profile}".`);
+};

package/dist/commands/reach-option.js

@@ -0,0 +1,8 @@
+import { UsageError } from "./command.js";
+const REACHES = ["all", "attached"];
+export function reachOf(raw, flag) {
+    const reach = REACHES.find((candidate) => candidate === raw);
+    if (reach === undefined)
+        throw new UsageError(`${flag} is ${REACHES.join(" or ")}.`);
+    return reach;
+}

package/dist/commands/webhooks.js

@@ -0,0 +1,90 @@
+import { parseArgs } from "node:util";
+import { SignalsGatewayWebhooks } from "../adapters/signals-gateway-webhooks.js";
+import { resolveProfile } from "../application/profiles.js";
+import { DEFAULT_PROFILE } from "../domain/profile.js";
+import { UsageError } from "./command.js";
+import { reachOf } from "./reach-option.js";
+const DEFAULT_EVENTS = ["alert.*"];
+const ACTIONS = {
+    list: async (webhooks, _input, print) => {
+        const subscribers = await webhooks.list();
+        if (subscribers.length === 0)
+            print("No Signals webhooks.");
+        for (const subscriber of subscribers)
+            print(describe(subscriber));
+    },
+    create: async (webhooks, input, print) => {
+        const created = await webhooks.create({
+            name: input.name,
+            webhookUrl: required(input.url, "--url <url>"),
+            events: input.events,
+            reach: input.reach,
+        });
+        print(`Created ${describe(created)}`);
+        if (created.signingSecret !== null) {
+            print(`Signing secret, shown this once: ${created.signingSecret}`);
+        }
+    },
+    delete: async (webhooks, input, print) => {
+        const id = required(input.id, "<id>");
+        await webhooks.remove(id);
+        print(`Deleted Signals webhook ${id}.`);
+    },
+    test: async (webhooks, input, print) => {
+        const delivery = await webhooks.test(required(input.id, "<id>"));
+        const answer = delivery.statusCode ?? delivery.error ?? "no answer";
+        print(`${delivery.delivered ? "Delivered" : "Not delivered"}: ${answer} in ${delivery.durationMs} ms.`);
+    },
+    "rotate-secret": async (webhooks, input, print) => {
+        const rotated = await webhooks.rotateSecret(required(input.id, "<id>"));
+        print(`New signing secret, shown this once: ${rotated.secret}`);
+        if (rotated.previousSecretExpiresAt !== null) {
+            print(`The previous secret keeps signing until ${rotated.previousSecretExpiresAt}.`);
+        }
+    },
+    enable: async (webhooks, input, print) => {
+        await webhooks.enable(required(input.id, "<id>"));
+        print("Enabled.");
+    },
+    disable: async (webhooks, input, print) => {
+        await webhooks.disable(required(input.id, "<id>"));
+        print("Disabled.");
+    },
+};
+export const webhooksCommand = async (args, context) => {
+    const { values, positionals } = parseArgs({
+        args,
+        allowPositionals: true,
+        options: {
+            profile: { type: "string", default: DEFAULT_PROFILE },
+            url: { type: "string" },
+            event: { type: "string", multiple: true, default: DEFAULT_EVENTS },
+            name: { type: "string", default: "ovok webhooks create" },
+            reach: { type: "string", default: "all" },
+        },
+    });
+    const [actionName, id] = positionals;
+    const action = actionName === undefined ? undefined : ACTIONS[actionName];
+    if (action === undefined) {
+        throw new UsageError(`Name an action: ${Object.keys(ACTIONS).join(", ")}.`);
+    }
+    const input = {
+        id,
+        url: values.url,
+        events: values.event,
+        name: values.name,
+        reach: reachOf(values.reach, "--reach"),
+    };
+    const profile = await resolveProfile(values.profile, context.profiles, context.env);
+    const webhooks = new SignalsGatewayWebhooks(context.connect(profile));
+    await action(webhooks, input, context.print);
+};
+function required(value, name) {
+    if (value === undefined)
+        throw new UsageError(`This action needs ${name}.`);
+    return value;
+}
+function describe(subscriber) {
+    const url = subscriber.webhookUrl ?? "no URL";
+    return `${subscriber.id}  ${url}  [${subscriber.events.join(", ")}]  reach ${subscriber.reach}`;
+}

package/dist/domain/api-base-url.js

@@ -0,0 +1,28 @@
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+export class InvalidBaseUrlError extends Error {
+}
+/** Where an Ovok API lives; plain http only reaches this machine, so a client secret never crosses a network unencrypted. */
+export class ApiBaseUrl {
+    #url;
+    constructor(url) {
+        this.#url = url;
+    }
+    static parse(raw) {
+        const url = URL.parse(raw);
+        if (url === null)
+            throw new InvalidBaseUrlError(`"${raw}" is not a URL.`);
+        const encrypted = url.protocol === "https:";
+        const local = url.protocol === "http:" && LOCAL_HOSTS.has(url.hostname);
+        if (!encrypted && !local) {
+            throw new InvalidBaseUrlError(`${url.origin} must use https.`);
+        }
+        url.pathname = url.pathname.endsWith("/") ? url.pathname : `${url.pathname}/`;
+        return new ApiBaseUrl(url);
+    }
+    resolve(path) {
+        return new URL(path, this.#url);
+    }
+    toString() {
+        return this.#url.href;
+    }
+}

package/dist/domain/cleanup.js

@@ -0,0 +1,24 @@
+/** Undoes what a session set up, newest first; a failing step never stops the rest. */
+export class Cleanup {
+    #tasks = [];
+    add(task) {
+        this.#tasks.push(task);
+    }
+    async run() {
+        const pending = this.#tasks.splice(0).reverse();
+        const outcomes = [];
+        for (const task of pending) {
+            outcomes.push(await runTask(task));
+        }
+        return outcomes;
+    }
+}
+async function runTask(task) {
+    try {
+        await task.run();
+        return { label: task.label, error: null };
+    }
+    catch (error) {
+        return { label: task.label, error };
+    }
+}

package/dist/domain/profile.js

@@ -0,0 +1 @@
+export const DEFAULT_PROFILE = "default";

package/dist/main.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+import { OvokApi } from "./adapters/ovok-api.js";
+import { configDirectory, ProfileFileStore } from "./adapters/profile-file-store.js";
+import { UsageError } from "./commands/command.js";
+import { listenCommand } from "./commands/listen.js";
+import { loginCommand } from "./commands/login.js";
+import { logoutCommand } from "./commands/logout.js";
+import { webhooksCommand } from "./commands/webhooks.js";
+const EXIT_FAILURE = 1;
+const EXIT_USAGE = 2;
+const KEEP_ALIVE_INTERVAL_MS = 60_000;
+const COMMANDS = {
+    listen: listenCommand,
+    login: loginCommand,
+    logout: logoutCommand,
+    webhooks: webhooksCommand,
+};
+const USAGE = `Usage: ovok <command> [options]
+
+Commands:
+  login     Sign in as a client application and save it as a profile
+            --base-url <url> --client-id <id> --client-secret-stdin [--profile <name>]
+  logout    Forget a saved profile                      [--profile <name>]
+  listen    Until Ctrl+C, forward FHIR events to a local URL and point a temporary Signals
+            webhook at a URL Signals can reach; both are removed when it stops
+            [--fhir <criteria>... --forward-to <url>]
+            [--signals-url <url> --signals-event <type>... --signals-reach all|attached]
+  webhooks  Manage Signals webhooks (subscribers) through Ovok
+            list | create --url <url> [--event <type>...] [--reach all|attached] [--name <name>]
+            | delete <id> | test <id> | rotate-secret <id> | enable <id> | disable <id>
+
+Every command takes --profile <name> (default "default"). OVOK_BASE_URL, OVOK_CLIENT_ID and
+OVOK_CLIENT_SECRET, all three set, take the place of a saved profile.`;
+async function main(argv) {
+    const [name, ...args] = argv;
+    const command = name === undefined ? undefined : COMMANDS[name];
+    if (command === undefined) {
+        console.log(USAGE);
+        return name === undefined || name === "help" || name === "--help" ? 0 : EXIT_USAGE;
+    }
+    try {
+        await command(args, createContext());
+        return 0;
+    }
+    catch (error) {
+        return reportFailure(error);
+    }
+}
+function createContext() {
+    return {
+        env: process.env,
+        profiles: new ProfileFileStore(configDirectory(process.env)),
+        connect: (profile) => new OvokApi(profile),
+        stdin: process.stdin,
+        print: (line) => console.log(line),
+        stopSignal,
+    };
+}
+/** Signal listeners alone do not keep Node running, so an idle timer does until the stop. */
+function stopSignal() {
+    const { promise, resolve } = Promise.withResolvers();
+    const keepAlive = setInterval(() => { }, KEEP_ALIVE_INTERVAL_MS);
+    const stop = () => resolve();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    return {
+        stopped: promise,
+        dispose: () => {
+            clearInterval(keepAlive);
+            process.off("SIGINT", stop);
+            process.off("SIGTERM", stop);
+        },
+    };
+}
+function reportFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    return isUsageError(error) ? EXIT_USAGE : EXIT_FAILURE;
+}
+function isUsageError(error) {
+    const code = error.code;
+    return (error instanceof UsageError || (typeof code === "string" && code.startsWith("ERR_PARSE_ARGS")));
+}
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "@ovok/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-dev.13",
+  "description": "Work with Ovok from the terminal: listen to FHIR and Signals events and manage Signals webhooks.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "ovok": "dist/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "node --test \"src/**/*.test.ts\" \"test/**/*.test.ts\""
+  }
+}