@fluid-app/fluid-cli-droplets 0.1.257 → 0.1.258

package/dist/index.mjs

@@ -621,6 +621,13 @@ function apiStatus$1(error) {
 	const status = error.status;
 	return typeof status === "number" ? status : void 0;
 }
+/** Turn a 404 or 403 from a droplet read (`what` is "health" or "status"; `notFound` replaces the 404 text)
+*  into a plain message; throws any other failure as it came. */
+function rethrowDropletReadError(error, dropletUuid, what, notFound = `${dropletUuid} is not a droplet this company publishes or has installed. List what is installed with \`fluid droplets installed\`.`) {
+	if (apiStatus$1(error) === 404) throw new DropletsCliError(notFound);
+	if (apiStatus$1(error) === 403) throw new DropletsCliError(`Reading droplet ${what} needs the developer.view permission.`);
+	throw error;
+}
 /** Read the window from `--window`, refusing one the API would. */
 function parseWindowHours(value) {
 	if (value === void 0) return void 0;
@@ -636,9 +643,23 @@ 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;
+		return rethrowDropletReadError(error, dropletUuid, "health");
+	}
+}
+//#endregion
+//#region src/status/api.ts
+function statusPath(dropletUuid) {
+	return `/api/company/v2026-10/droplets/${encodeURIComponent(dropletUuid)}/status`;
+}
+/**
+* The droplet's status for this company over the window (the API's default,
+* 24 hours, when left out).
+*/
+async function getDropletStatus(client, dropletUuid, windowHours) {
+	try {
+		return (await client.get(statusPath(dropletUuid), windowHours === void 0 ? void 0 : { window_hours: windowHours })).droplet_status;
+	} catch (error) {
+		return rethrowDropletReadError(error, dropletUuid, "status", `${dropletUuid} has no installation for this company, or is not a droplet it can see. List what is installed with \`fluid droplets installed\`.`);
 	}
 }
 //#endregion
@@ -686,7 +707,7 @@ async function dropletsClient$1(ctx) {
 	return await ctx.getClient();
 }
 /**
-* `fluid droplets install|uninstall|installed|health`: friendly commands over
+* `fluid droplets install|uninstall|installed|health|status`: friendly commands over
 * the v2026-10 company API, next to the generated `installations` commands.
 */
 function registerInstallCommands(parent, ctx) {
@@ -715,6 +736,10 @@ function registerInstallCommands(parent, ctx) {
 		const windowHours = parseWindowHours(opts.window);
 		ctx.output(await getDropletHealth(await dropletsClient$1(ctx), dropletUuid, windowHours));
 	}));
+	parent.command("status <droplet_uuid>").description("A droplet's operating status for this company's installation: deployment, install, lifecycle, health, metrics and webhook health, each section marked available or not (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 getDropletStatus(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.257",
+  "version": "0.1.258",
   "description": "Fluid CLI commands for droplet management",
   "type": "module",
   "main": "./dist/index.mjs",
@@ -17,7 +17,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@fluid-app/fluid-cli": "0.1.256",
+    "@fluid-app/fluid-cli": "0.1.257",
     "ajv": "8.17.1",
     "commander": "^12.0.0"
   },

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

@@ -0,0 +1,127 @@
+import { Command } from "commander";
+import type { CommandContext } from "@fluid-app/fluid-cli";
+
+import { registerInstallCommands } from "../commands/install";
+import { type DropletsClient } from "../install/api";
+import { getDropletStatus, statusPath } from "../status/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 unavailable = {
+  available: false,
+  error: { type: "unavailable", description: "Try again later." },
+  data: null,
+};
+
+const status = {
+  generated_at: "2026-10-22T10:00:00Z",
+  window_hours: 24,
+  installation: null,
+  history: [],
+  sections: {
+    health: { available: true, error: null, data: { verdict: "brand_new" } },
+    metrics: unavailable,
+    reconcile: unavailable,
+    connect: unavailable,
+  },
+};
+
+describe("getDropletStatus", () => {
+  it("returns the status as sent, unavailable sections and unknown verdicts included", async () => {
+    const { client, calls } = fakeClient({ droplet_status: status });
+
+    await expect(getDropletStatus(client, "drp_1")).resolves.toEqual(status);
+    expect(calls).toEqual([
+      { endpoint: statusPath("drp_1"), params: undefined },
+    ]);
+  });
+
+  it("asks for the window given", async () => {
+    const { client, calls } = fakeClient({ droplet_status: status });
+
+    await getDropletStatus(client, "drp_1", 168);
+
+    expect(calls[0]?.params).toEqual({ window_hours: 168 });
+  });
+
+  it("explains a 404 and a 403", async () => {
+    await expect(
+      getDropletStatus(fakeClient(apiError(404)).client, "drp_1"),
+    ).rejects.toThrow(/has no installation for this company/);
+    await expect(
+      getDropletStatus(fakeClient(apiError(403)).client, "drp_1"),
+    ).rejects.toThrow(/developer.view/);
+  });
+
+  it("passes other failures on", async () => {
+    await expect(
+      getDropletStatus(fakeClient(apiError(500)).client, "drp_1"),
+    ).rejects.toMatchObject({ status: 500 });
+  });
+});
+
+describe("fluid droplets status", () => {
+  function setup(answer: unknown) {
+    const { client, calls } = fakeClient(answer);
+    const output = jest.fn();
+    const ctx = {
+      getClient: async () => client,
+      output,
+    } as unknown as CommandContext;
+    const program = new Command();
+    program.exitOverride();
+    registerInstallCommands(program, ctx);
+    return { program, calls, output };
+  }
+
+  it("prints the droplet_status object for the window given", async () => {
+    const { program, calls, output } = setup({ droplet_status: status });
+
+    await program.parseAsync(["status", "drp_1", "--window", "6"], {
+      from: "user",
+    });
+
+    expect(calls).toEqual([
+      { endpoint: statusPath("drp_1"), params: { window_hours: 6 } },
+    ]);
+    expect(output).toHaveBeenCalledWith(status);
+  });
+
+  it("refuses a window outside the API's bounds before calling it", async () => {
+    const { program, calls, output } = setup({ droplet_status: status });
+    const stderr = jest
+      .spyOn(process.stderr, "write")
+      .mockImplementation(() => true);
+
+    await program.parseAsync(["status", "drp_1", "--window", "169"], {
+      from: "user",
+    });
+
+    expect(calls).toEqual([]);
+    expect(output).not.toHaveBeenCalled();
+    expect(String(stderr.mock.calls[0]?.[0])).toMatch(/--window must be/);
+    stderr.mockRestore();
+    process.exitCode = undefined;
+  });
+});

package/src/commands/install.ts

@@ -13,6 +13,7 @@ import {
   type DropletsClient,
 } from "../install/api.js";
 import { getDropletHealth, parseWindowHours } from "../health/api.js";
+import { getDropletStatus } from "../status/api.js";
 
 /** Asks a yes/no question; true means yes. */
 export type Ask = (question: string) => Promise<boolean>;
@@ -88,7 +89,7 @@ async function dropletsClient(ctx: CommandContext): Promise<DropletsClient> {
 }
 
 /**
- * `fluid droplets install|uninstall|installed|health`: friendly commands over
+ * `fluid droplets install|uninstall|installed|health|status`: friendly commands over
  * the v2026-10 company API, next to the generated `installations` commands.
  */
 export function registerInstallCommands(
@@ -169,6 +170,28 @@ export function registerInstallCommands(
       }),
     );
 
+  parent
+    .command("status <droplet_uuid>")
+    .description(
+      "A droplet's operating status for this company's installation: deployment, install, lifecycle, health, metrics and webhook health, each section marked available or not (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 getDropletStatus(
+            await dropletsClient(ctx),
+            dropletUuid,
+            windowHours,
+          ),
+        );
+      }),
+    );
+
   parent
     .command("installed")
     .description(

package/src/health/api.ts

@@ -33,6 +33,22 @@ function apiStatus(error: unknown): number | undefined {
   return typeof status === "number" ? status : undefined;
 }
 
+/** Turn a 404 or 403 from a droplet read (`what` is "health" or "status"; `notFound` replaces the 404 text)
+ *  into a plain message; throws any other failure as it came. */
+export function rethrowDropletReadError(
+  error: unknown,
+  dropletUuid: string,
+  what: string,
+  notFound = `${dropletUuid} is not a droplet this company publishes or has installed. List what is installed with \`fluid droplets installed\`.`,
+): never {
+  if (apiStatus(error) === 404) throw new DropletsCliError(notFound);
+  if (apiStatus(error) === 403)
+    throw new DropletsCliError(
+      `Reading droplet ${what} needs the developer.view permission.`,
+    );
+  throw error;
+}
+
 /** Read the window from `--window`, refusing one the API would. */
 export function parseWindowHours(
   value: string | undefined,
@@ -67,14 +83,6 @@ export async function getDropletHealth(
     );
     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;
+    return rethrowDropletReadError(error, dropletUuid, "health");
   }
 }

package/src/status/api.ts

@@ -0,0 +1,57 @@
+/**
+ * A droplet's operating status for the signed-in company's own installation,
+ * through the v2026-10 company droplets API
+ * (apps/rails/docs/openapi/v2026-10/company-droplets.yaml,
+ * `CompanyDropletStatus`).
+ */
+
+import { type DropletsClient } from "../install/api.js";
+import { rethrowDropletReadError } from "../health/api.js";
+
+/** One part of the status. Where `available` is false, `data` is null and
+ *  `error` says why; a verdict string inside `data` may be one this client
+ *  does not know. */
+export interface DropletStatusSection {
+  available: boolean;
+  error: { type: string; description: string } | null;
+  data: Record<string, unknown> | null;
+}
+
+/** The status as the API returns it. `reconcile` and `connect` are always
+ *  unavailable for now. */
+export interface DropletStatus {
+  generated_at: string;
+  window_hours: number;
+  installation: Record<string, unknown> | null;
+  history: unknown;
+  sections: Record<string, DropletStatusSection>;
+}
+
+export function statusPath(dropletUuid: string): string {
+  return `/api/company/v2026-10/droplets/${encodeURIComponent(dropletUuid)}/status`;
+}
+
+/**
+ * The droplet's status for this company over the window (the API's default,
+ * 24 hours, when left out).
+ */
+export async function getDropletStatus(
+  client: DropletsClient,
+  dropletUuid: string,
+  windowHours?: number,
+): Promise<DropletStatus> {
+  try {
+    const response = await client.get<{ droplet_status: DropletStatus }>(
+      statusPath(dropletUuid),
+      windowHours === undefined ? undefined : { window_hours: windowHours },
+    );
+    return response.droplet_status;
+  } catch (error) {
+    return rethrowDropletReadError(
+      error,
+      dropletUuid,
+      "status",
+      `${dropletUuid} has no installation for this company, or is not a droplet it can see. List what is installed with \`fluid droplets installed\`.`,
+    );
+  }
+}