@fluid-app/fluid-cli-droplets 0.1.125 → 0.1.127

package/dist/index.mjs

@@ -17,7 +17,7 @@ function dropletInstallationsPath(dropletUuid) {
 function installationPath(installationUuid) {
 	return `${INSTALLATIONS_PATH}/${encodeURIComponent(installationUuid)}`;
 }
-function apiStatus$1(error) {
+function apiStatus$2(error) {
 	const status = error.status;
 	return typeof status === "number" ? status : void 0;
 }
@@ -34,7 +34,7 @@ async function installDroplet(client, dropletUuid, roleUuid) {
 			installation: (await client.post(dropletInstallationsPath(dropletUuid), { installation })).droplet_installation
 		};
 	} catch (error) {
-		if (apiStatus$1(error) === 409) return {
+		if (apiStatus$2(error) === 409) return {
 			installed: true,
 			alreadyInstalled: true,
 			dropletUuid
@@ -77,7 +77,7 @@ async function resolveInstallation(client, uuid) {
 	try {
 		return (await findInstallation(client, uuid))?.uuid ?? null;
 	} catch (error) {
-		if (apiStatus$1(error) === 403) throw new DropletsCliError(`Finding the installation of ${uuid} needs the droplets.view permission. Pass the installation's uuid (dri_…) instead.`);
+		if (apiStatus$2(error) === 403) throw new DropletsCliError(`Finding the installation of ${uuid} needs the droplets.view permission. Pass the installation's uuid (dri_…) instead.`);
 		throw error;
 	}
 }
@@ -90,7 +90,7 @@ async function preflightInstallation(client, dropletUuid) {
 	try {
 		return await findInstallation(client, dropletUuid);
 	} catch (error) {
-		if (apiStatus$1(error) === 403) return void 0;
+		if (apiStatus$2(error) === 403) return void 0;
 		throw error;
 	}
 }
@@ -114,13 +114,40 @@ async function uninstallDroplet(client, installationUuid) {
 			installation: (await client.delete(installationPath(installationUuid))).droplet_installation
 		};
 	} catch (error) {
-		if (apiStatus$1(error) === 404) throw notInstalled(installationUuid);
+		if (apiStatus$2(error) === 404) throw notInstalled(installationUuid);
 		throw error;
 	}
 }
 function notInstalled(uuid) {
 	return new DropletsCliError(`${uuid} is not installed for this company. List what is installed with \`fluid droplets installed\`.`);
 }
+function healthPath(dropletUuid) {
+	return `/api/company/v2026-10/droplets/${encodeURIComponent(dropletUuid)}/health`;
+}
+function apiStatus$1(error) {
+	const status = error.status;
+	return typeof status === "number" ? status : void 0;
+}
+/** Read the window from `--window`, refusing one the API would. */
+function parseWindowHours(value) {
+	if (value === void 0) return void 0;
+	const hours = Number(value);
+	if (!Number.isInteger(hours) || hours < 1 || hours > 168) throw new DropletsCliError(`--window must be a whole number of hours from 1 to 168.`);
+	return hours;
+}
+/**
+* How the droplet's callbacks have behaved for this company over the window
+* (the API's default, 24 hours, when left out).
+*/
+async function getDropletHealth(client, dropletUuid, windowHours) {
+	try {
+		return (await client.get(healthPath(dropletUuid), windowHours === void 0 ? void 0 : { window_hours: windowHours })).droplet_health;
+	} catch (error) {
+		if (apiStatus$1(error) === 404) throw new DropletsCliError(`${dropletUuid} is not a droplet this company publishes or has installed. List what is installed with \`fluid droplets installed\`.`);
+		if (apiStatus$1(error) === 403) throw new DropletsCliError("Reading droplet health needs the developer.view permission.");
+		throw error;
+	}
+}
 //#endregion
 //#region src/commands/install.ts
 async function askOnTerminal(question) {
@@ -166,8 +193,8 @@ async function dropletsClient$1(ctx) {
 	return await ctx.getClient();
 }
 /**
-* `fluid droplets install|uninstall|installed`: friendly commands over the
-* v2026-10 company API, next to the generated `installations` commands.
+* `fluid droplets install|uninstall|installed|health`: friendly commands over
+* the v2026-10 company API, next to the generated `installations` commands.
 */
 function registerInstallCommands(parent, ctx) {
 	parent.command("install <droplet_uuid>").description("Install a droplet for this company; it receives the scopes it requests (changes live config)").option("--role <role_uuid>", "The role the droplet acts with, by its uuid; a new role is made when left out").option("--yes", "Confirm without a prompt", false).action((dropletUuid, opts) => run$1(async () => {
@@ -191,6 +218,10 @@ function registerInstallCommands(parent, ctx) {
 		await confirmChange(`Uninstall ${installationUuid} from this company?`, opts.yes);
 		ctx.output(await uninstallDroplet(client, installationUuid));
 	}));
+	parent.command("health <droplet_uuid>").description("How a droplet's callbacks have behaved for this company's installation: calls, failures, timeouts and latency per callback, and whether a checkout waits on it (read-only)").option("--window <hours>", "Trailing window in hours, 1 to 168 (default 24)").action((dropletUuid, opts) => run$1(async () => {
+		const windowHours = parseWindowHours(opts.window);
+		ctx.output(await getDropletHealth(await dropletsClient$1(ctx), dropletUuid, windowHours));
+	}));
 	parent.command("installed").description("List the droplets this company has installed; --full for full installation rows, every page").option("--full", "Full rows (status, scopes, role), including installations being removed", false).option("--category <slug>", "With --full, only droplets in this category").action((opts) => run$1(async () => {
 		if (opts.category && !opts.full) throw new DropletsCliError("--category needs --full.");
 		ctx.output(await listInstallations(await dropletsClient$1(ctx), opts));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-droplets",
-  "version": "0.1.125",
+  "version": "0.1.127",
   "description": "Fluid CLI commands for droplet management",
   "type": "module",
   "main": "./dist/index.mjs",

package/src/__tests__/health-api.test.ts

@@ -0,0 +1,82 @@
+import { DropletsCliError, type DropletsClient } from "../install/api";
+import { getDropletHealth, healthPath, parseWindowHours } from "../health/api";
+
+type Call = { endpoint: string; params?: unknown };
+
+function fakeClient(answer: unknown) {
+  const calls: Call[] = [];
+  const client: DropletsClient = {
+    get: async <T>(endpoint: string, params?: Record<string, unknown>) => {
+      calls.push({ endpoint, params });
+      if (answer instanceof Error) throw answer;
+      return answer as T;
+    },
+    post: async () => {
+      throw new Error("not used");
+    },
+    delete: async () => {
+      throw new Error("not used");
+    },
+  };
+  return { client, calls };
+}
+
+const apiError = (status: number) =>
+  Object.assign(new Error(`HTTP ${status}`), { status });
+
+const report = {
+  window_hours: 24,
+  generated_at: "2026-10-22T10:00:00Z",
+  metrics_available: false,
+  metrics_error: { type: "unavailable", description: "Try again later." },
+  droplet: { uuid: "drp_1", name: "Tax Sync", status: "published" },
+  installation: null,
+};
+
+describe("getDropletHealth", () => {
+  it("returns the report, leaving the window to the API by default", async () => {
+    const { client, calls } = fakeClient({ droplet_health: report });
+
+    await expect(getDropletHealth(client, "drp_1")).resolves.toEqual(report);
+    expect(calls).toEqual([
+      { endpoint: healthPath("drp_1"), params: undefined },
+    ]);
+  });
+
+  it("asks for the window given", async () => {
+    const { client, calls } = fakeClient({ droplet_health: report });
+
+    await getDropletHealth(client, "drp_1", 168);
+
+    expect(calls[0]?.params).toEqual({ window_hours: 168 });
+  });
+
+  it("explains a 404 and a 403", async () => {
+    await expect(
+      getDropletHealth(fakeClient(apiError(404)).client, "drp_1"),
+    ).rejects.toThrow(/not a droplet this company publishes or has installed/);
+    await expect(
+      getDropletHealth(fakeClient(apiError(403)).client, "drp_1"),
+    ).rejects.toThrow(/developer.view/);
+  });
+
+  it("passes other failures on", async () => {
+    await expect(
+      getDropletHealth(fakeClient(apiError(500)).client, "drp_1"),
+    ).rejects.toMatchObject({ status: 500 });
+  });
+});
+
+describe("parseWindowHours", () => {
+  it("accepts whole hours from 1 to 168 and nothing", () => {
+    expect(parseWindowHours(undefined)).toBeUndefined();
+    expect(parseWindowHours("1")).toBe(1);
+    expect(parseWindowHours("168")).toBe(168);
+  });
+
+  it("refuses anything the API would", () => {
+    for (const value of ["0", "169", "1.5", "day"]) {
+      expect(() => parseWindowHours(value)).toThrow(DropletsCliError);
+    }
+  });
+});

package/src/commands/install.ts

@@ -12,6 +12,7 @@ import {
   uninstallDroplet,
   type DropletsClient,
 } from "../install/api.js";
+import { getDropletHealth, parseWindowHours } from "../health/api.js";
 
 /** Asks a yes/no question; true means yes. */
 export type Ask = (question: string) => Promise<boolean>;
@@ -87,8 +88,8 @@ async function dropletsClient(ctx: CommandContext): Promise<DropletsClient> {
 }
 
 /**
- * `fluid droplets install|uninstall|installed`: friendly commands over the
- * v2026-10 company API, next to the generated `installations` commands.
+ * `fluid droplets install|uninstall|installed|health`: friendly commands over
+ * the v2026-10 company API, next to the generated `installations` commands.
  */
 export function registerInstallCommands(
   parent: Command,
@@ -146,6 +147,28 @@ export function registerInstallCommands(
       }),
     );
 
+  parent
+    .command("health <droplet_uuid>")
+    .description(
+      "How a droplet's callbacks have behaved for this company's installation: calls, failures, timeouts and latency per callback, and whether a checkout waits on it (read-only)",
+    )
+    .option(
+      "--window <hours>",
+      "Trailing window in hours, 1 to 168 (default 24)",
+    )
+    .action((dropletUuid: string, opts: { window?: string }) =>
+      run(async () => {
+        const windowHours = parseWindowHours(opts.window);
+        ctx.output(
+          await getDropletHealth(
+            await dropletsClient(ctx),
+            dropletUuid,
+            windowHours,
+          ),
+        );
+      }),
+    );
+
   parent
     .command("installed")
     .description(

package/src/health/api.ts

@@ -0,0 +1,80 @@
+/**
+ * A droplet's callback health for the signed-in company's own installation,
+ * through the v2026-10 company droplets API
+ * (apps/rails/docs/openapi/v2026-10/company-droplets.yaml,
+ * `companyDropletHealth`).
+ */
+
+import { DropletsCliError, type DropletsClient } from "../install/api.js";
+
+/** The trailing window the API accepts, in hours. */
+export const MIN_WINDOW_HOURS = 1;
+export const MAX_WINDOW_HOURS = 168;
+
+/** The health report as the API returns it. `metrics` is null wherever the
+ *  figures could not be read (`metrics_available` false); a zero count is a
+ *  real reading. `installation` is null when the company publishes the
+ *  droplet but has not installed it. */
+export interface DropletHealth {
+  window_hours: number;
+  generated_at: string;
+  metrics_available: boolean;
+  metrics_error: { type: string; description: string } | null;
+  droplet: { uuid: string; name: string | null; status: string };
+  installation: Record<string, unknown> | null;
+}
+
+export function healthPath(dropletUuid: string): string {
+  return `/api/company/v2026-10/droplets/${encodeURIComponent(dropletUuid)}/health`;
+}
+
+function apiStatus(error: unknown): number | undefined {
+  const status = (error as { status?: unknown }).status;
+  return typeof status === "number" ? status : undefined;
+}
+
+/** Read the window from `--window`, refusing one the API would. */
+export function parseWindowHours(
+  value: string | undefined,
+): number | undefined {
+  if (value === undefined) return undefined;
+  const hours = Number(value);
+  if (
+    !Number.isInteger(hours) ||
+    hours < MIN_WINDOW_HOURS ||
+    hours > MAX_WINDOW_HOURS
+  ) {
+    throw new DropletsCliError(
+      `--window must be a whole number of hours from ${MIN_WINDOW_HOURS} to ${MAX_WINDOW_HOURS}.`,
+    );
+  }
+  return hours;
+}
+
+/**
+ * How the droplet's callbacks have behaved for this company over the window
+ * (the API's default, 24 hours, when left out).
+ */
+export async function getDropletHealth(
+  client: DropletsClient,
+  dropletUuid: string,
+  windowHours?: number,
+): Promise<DropletHealth> {
+  try {
+    const response = await client.get<{ droplet_health: DropletHealth }>(
+      healthPath(dropletUuid),
+      windowHours === undefined ? undefined : { window_hours: windowHours },
+    );
+    return response.droplet_health;
+  } catch (error) {
+    if (apiStatus(error) === 404)
+      throw new DropletsCliError(
+        `${dropletUuid} is not a droplet this company publishes or has installed. List what is installed with \`fluid droplets installed\`.`,
+      );
+    if (apiStatus(error) === 403)
+      throw new DropletsCliError(
+        "Reading droplet health needs the developer.view permission.",
+      );
+    throw error;
+  }
+}

package/src/index.ts

@@ -16,7 +16,7 @@ const plugin: FluidPlugin = {
         (parent, cmdCtx) => {
           registerAllCommands(parent, cmdCtx);
           // Hand-written commands on top of the generated OpenAPI surface:
-          // `install`, `uninstall` and `installed`, over the v2026-10
+          // `install`, `uninstall`, `installed` and `health`, over the v2026-10
           // company API, and asking Fluid to publish a droplet (with the
           // root admin's review of those requests).
           registerInstallCommands(parent, cmdCtx);