@greatwait/cli 0.1.0-alpha.6 → 0.1.0-alpha.8

package/dist/catalog.js

@@ -255,6 +255,77 @@ export const MEMBER_COMMANDS = [
     },
 ];
 export const COMMAND_CATALOG = [
+    {
+        group: "Planning",
+        words: "notifications show",
+        summary: "Show this project and environment's delivery notification settings.",
+        operations: ["projectnotifications.read"],
+        positionals: [
+            {
+                name: "<project>",
+                summary: "The project identifier in this credential's authority.",
+            },
+        ],
+        options: [API_URL],
+    },
+    {
+        group: "Planning",
+        words: "notifications update",
+        summary: "Change failure email and failed-event webhook preferences at the revision you read.",
+        confirms: true,
+        operations: ["projectnotifications.update"],
+        positionals: [
+            {
+                name: "<project>",
+                summary: "The project identifier in this credential's authority.",
+            },
+        ],
+        options: [
+            API_URL,
+            {
+                flag: "--settings",
+                value: "<json|@file|->",
+                summary: "JSON expectedRevision and email/statusWebhook settings; null statusWebhook disables it. No signing secret is accepted.",
+            },
+            IDEMPOTENCY,
+            CONFIRM,
+        ],
+    },
+    {
+        group: "Planning",
+        words: "notifications signing-key",
+        summary: "Mint or rotate a failed-event webhook signing secret, shown once.",
+        confirms: true,
+        operations: ["projectnotifications.rotateSigningKey"],
+        positionals: [
+            {
+                name: "<project>",
+                summary: "The project identifier in this credential's authority.",
+            },
+        ],
+        options: [
+            API_URL,
+            {
+                flag: "--expected-revision",
+                value: "<revision>",
+                summary: "The current revision from notifications show; a stale retry is refused.",
+            },
+            CONFIRM,
+        ],
+    },
+    {
+        group: "Planning",
+        words: "notifications deliveries",
+        summary: "List failed-event webhook deliveries and retries.",
+        operations: ["statusdeliveries.list"],
+        positionals: [
+            {
+                name: "<project>",
+                summary: "The project identifier in this credential's authority.",
+            },
+        ],
+        options: [API_URL, ...PAGE_OPTIONS],
+    },
     /* --- Session ---------------------------------------------------------- */
     {
         group: "Session",
@@ -529,6 +600,11 @@ export const COMMAND_CATALOG = [
                 summary: "Your own label, such as a customer id. Each label is paced on its own, so one busy label can't hold up the rest. Can't be changed later.",
                 value: "<key>",
             },
+            {
+                flag: "--auto-pause-after-failures",
+                summary: 'Pause a recurring schedule after 1–100 consecutive failed runs, or "never". Defaults to 5 on create; omission on replace keeps the setting. Resume resets the count.',
+                value: "<count|never>",
+            },
             {
                 flag: "--latency-class",
                 summary: "realtime or bulk. realtime goes first when both are due. By default a call due within two minutes is realtime, and a repeating one is bulk.",
@@ -605,6 +681,11 @@ export const COMMAND_CATALOG = [
                 summary: "Your own label, such as a customer id. Each label is paced on its own, so one busy label can't hold up the rest. Can't be changed later.",
                 value: "<key>",
             },
+            {
+                flag: "--auto-pause-after-failures",
+                summary: 'Pause a recurring schedule after 1–100 consecutive failed runs, or "never". Defaults to 5 on create; omission on replace keeps the setting. Resume resets the count.',
+                value: "<count|never>",
+            },
             {
                 flag: "--latency-class",
                 summary: "realtime or bulk. realtime goes first when both are due. By default a call due within two minutes is realtime, and a repeating one is bulk.",
@@ -834,7 +915,14 @@ export const COMMAND_CATALOG = [
     {
         group: "Occurrences and attempts",
         operations: ["attempts.read"],
-        options: [API_URL],
+        options: [
+            API_URL,
+            {
+                flag: "--response-file",
+                value: "path",
+                summary: "Save the captured response body in a new private file.",
+            },
+        ],
         positionals: [
             {
                 name: "<schedule>",

package/dist/commands.js

@@ -805,11 +805,21 @@ const schedulesRead = async (runtime, args) => {
             recurrence: view.schedule.recurrence.kind,
             schedule: view.schedule.id,
             status: view.schedule.status,
+            autoPauseAfterFailures: view.schedule.autoPauseAfterFailures,
+            consecutiveFailedRuns: view.schedule.consecutiveFailedRuns,
+            autoPauseReason: view.schedule.autoPauseReason,
             version: view.schedule.version,
         },
         human: [
             `Schedule     ${view.schedule.id}`,
             `Status       ${view.schedule.status}`,
+            `Auto-pause   ${String(view.schedule.autoPauseAfterFailures ?? 5)}`,
+            `Failed runs  ${String(view.schedule.consecutiveFailedRuns ?? 0)}`,
+            ...(view.schedule.autoPauseReason == null
+                ? []
+                : [
+                    `Paused       ${String(view.schedule.autoPauseReason.failedRuns)} failed runs; ${view.schedule.autoPauseReason.status === undefined ? "no HTTP response" : `HTTP ${String(view.schedule.autoPauseReason.status)}`} (${view.schedule.autoPauseReason.diagnostic}) at ${view.schedule.autoPauseReason.pausedAt}`,
+                ]),
             `Recurrence   ${view.schedule.recurrence.kind}`,
             `Version      ${String(view.schedule.version)}`,
             ...(etag === undefined ? [] : [`ETag         ${etag}`]),

package/dist/operate.js

@@ -1,4 +1,5 @@
-import { httpRequestSchema, endpointHeaderChangesSchema, billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingNotificationSettingsUpdateRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, } from "@greatwait/contracts";
+import { writeFile } from "node:fs/promises";
+import { projectNotificationSettingsUpdateRequestSchema, statusSigningKeyRequestSchema, autoPauseAfterFailuresSchema, httpRequestSchema, sanitizedDiagnosticText, diagnosticBodyText, responseBodySentence, requestCaptureSentence, attemptStatusGuidance, endpointHeaderChangesSchema, billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingNotificationSettingsUpdateRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, } from "@greatwait/contracts";
 import { parseDuration } from "./args.js";
 import { confirmChange } from "./confirm.js";
 import { redactSecret } from "./output.js";
@@ -116,6 +117,12 @@ async function scheduleRequest(runtime, args, usage) {
         : httpRequestSchema.safeParse(httpInput);
     if (http !== undefined && !http.success)
         throw new CliError("--http settings are invalid", "usage", http.error.issues.map((issue) => issue.message).join("; "));
+    const pauseInput = args.options["--auto-pause-after-failures"];
+    const pause = pauseInput === undefined
+        ? undefined
+        : autoPauseAfterFailuresSchema.safeParse(pauseInput === "never" ? pauseInput : Number(pauseInput));
+    if (pause !== undefined && !pause.success)
+        throw new CliError('--auto-pause-after-failures must be a whole number from 1 to 100, or "never"', "usage");
     const latencyClass = args.options["--latency-class"];
     const partitionKey = args.options["--partition-key"];
     return {
@@ -124,6 +131,7 @@ async function scheduleRequest(runtime, args, usage) {
         ...(endpoint === undefined ? {} : { endpoint }),
         ...(url === undefined ? {} : { url }),
         ...(latencyClass === undefined ? {} : { latencyClass }),
+        ...(pause?.success ? { autoPauseAfterFailures: pause.data } : {}),
         ...(partitionKey === undefined ? {} : { partitionKey }),
         ...(timeZone === undefined ? {} : { timeZone }),
         ...recurrence,
@@ -494,9 +502,52 @@ const attemptsRead = async (runtime, args) => {
     const active = await session(runtime, args);
     const view = parseResponse("attempts.read", await active.client.request("attempts_read", schedule, occurrence, attempt));
     const found = view.attempt;
+    const responseFile = args.options["--response-file"];
+    if (responseFile !== undefined) {
+        if (found.response?.body === undefined)
+            throw new CliError(responseBodySentence(found.response?.bodyState ?? "not_captured", found.responseStatus === undefined), "validation");
+        const body = found.response.body;
+        try {
+            await writeFile(responseFile, body.encoding === "base64"
+                ? Buffer.from(body.content, "base64")
+                : Buffer.from(body.content, "utf8"), { mode: 0o600, flag: "wx" });
+        }
+        catch {
+            throw new CliError("The response file could not be created. Choose a path that does not already exist.", "usage");
+        }
+    }
+    const diagnosticLines = [];
+    if (found.response !== undefined) {
+        const response = found.response;
+        diagnosticLines.push(`Server response ${String(found.responseStatus ?? "")} ${response.statusText}`, ...response.headers.map((h) => `${h.name}: ${h.value}`));
+        if (response.body === undefined)
+            diagnosticLines.push(responseBodySentence(response.bodyState, found.responseStatus === undefined));
+        else {
+            const body = response.body;
+            if (body.incomplete)
+                diagnosticLines.push("The response stream stopped during capture; this is a partial answer.");
+            if (body.truncated)
+                diagnosticLines.push(`Response cut at 10 KiB (10,240 bytes)${body.originalBytes === undefined ? "" : `; original length ${String(body.originalBytes)} bytes`}.`);
+            diagnosticLines.push(diagnosticBodyText(body) !== undefined
+                ? diagnosticBodyText(body)
+                : `Binary response (${String(body.capturedBytes)} bytes). Download with --response-file <path>.`);
+        }
+    }
+    diagnosticLines.push("What we sent");
+    if (found.request === undefined)
+        diagnosticLines.push(requestCaptureSentence(found.requestState, found.state === undefined));
+    else
+        diagnosticLines.push(`${found.request.method} ${found.request.url}`, ...found.request.headers.map((h) => `${h.name}: ${h.value}`), found.request.body === "" ? "We sent no body." : found.request.body);
+    const guidance = attemptStatusGuidance(found.responseStatus);
+    if (guidance !== undefined)
+        diagnosticLines.push(guidance);
     return {
         data: { attempt: found, freshness: freshnessOf(view) },
         human: [
+            ...diagnosticLines.map(sanitizedDiagnosticText),
+            ...(responseFile === undefined
+                ? []
+                : [`Response saved to ${sanitizedDiagnosticText(responseFile)}`]),
             `Attempt      ${found.id}`,
             `Number       ${String(found.attemptNumber)}`,
             ...(found.state === undefined ? [] : [`State        ${found.state}`]),
@@ -1570,11 +1621,104 @@ const sinksDelivery = async (runtime, args) => {
         ].join("\n"),
     };
 };
+function notificationPreferenceResult(settings) {
+    const webhook = settings.statusWebhook;
+    return {
+        data: settings,
+        human: [
+            `Project    ${settings.project}`,
+            `Revision   ${String(settings.revision)}`,
+            `Email      ${settings.email.enabled ? "enabled" : "disabled"}; ${settings.email.scheduleKinds}`,
+            `Recipients ${settings.email.recipients.kind === "admins" ? "organization admins" : settings.email.recipients.memberIds.join(", ")}`,
+            `Webhook    ${webhook === undefined ? "disabled" : webhook.url}`,
+            ...(webhook === undefined
+                ? []
+                : [
+                    `Events     ${webhook.events.join(", ")}`,
+                    `Signing key ${webhook.signingKey?.id ?? "not provisioned"}`,
+                ]),
+        ].join("\n"),
+    };
+}
 /* -------------------------------------------------------------------------- */
 /* Dispatch                                                                   */
 /* -------------------------------------------------------------------------- */
 /** The operate-and-diagnose commands, keyed by the words that select them. */
 export const OPERATE_COMMANDS = {
+    "notifications show": async (runtime, args) => {
+        const [project] = positionals(args, ["<project>"], `${runtime.programName} notifications show <project>`);
+        const active = await session(runtime, args);
+        const settings = parseResponse("projectnotifications.read", await active.client.request("projectnotifications_read", project));
+        return notificationPreferenceResult(settings);
+    },
+    "notifications update": async (runtime, args) => {
+        const [project] = positionals(args, ["<project>"], `${runtime.programName} notifications update <project> --settings <json|@file|->`);
+        const parsed = projectNotificationSettingsUpdateRequestSchema.safeParse(await readJsonOption(runtime, "--settings", args.options["--settings"]));
+        if (!parsed.success)
+            throw new CliError("--settings must contain expectedRevision and valid email/statusWebhook preferences", "usage");
+        const confirmation = await confirmChange(runtime, args, {
+            action: `Update delivery notifications for ${project}.`,
+            effect: [
+                "Changes failure email recipients and/or failed-event webhook destination.",
+                "Failed-event hooks are included and free, including retries.",
+                "The signing secret is never returned by this settings change.",
+            ],
+        });
+        const active = await session(runtime, args);
+        const key = idempotencyKey(runtime, args);
+        runtime.stderr(`Retry key ${key}; retain it if the response is lost.\n`);
+        const settings = parseResponse("projectnotifications.update", await active.client.request("projectnotifications_update", project, parsed.data, { "Idempotency-Key": key }));
+        return {
+            ...notificationPreferenceResult(settings),
+            data: { settings, confirmation, idempotencyKey: key },
+        };
+    },
+    "notifications signing-key": async (runtime, args) => {
+        const [project] = positionals(args, ["<project>"], `${runtime.programName} notifications signing-key <project> --expected-revision <revision>`);
+        const request = statusSigningKeyRequestSchema.safeParse({
+            expectedRevision: expectedRevision(args),
+        });
+        if (!request.success)
+            throw new CliError("--expected-revision must be a positive whole number", "usage");
+        const confirmation = await confirmChange(runtime, args, {
+            action: `Mint or rotate the status signing key for ${project}.`,
+            effect: [
+                "The previous key is replaced; queued notifications using that old key are suppressed.",
+                "The secret is shown once in this response and cannot be read back. A lost response needs a fresh revision read and a new rotation.",
+            ],
+        });
+        const active = await session(runtime, args);
+        const result = parseResponse("projectnotifications.rotateSigningKey", await active.client.request("projectnotifications_rotateSigningKey", project, request.data));
+        return {
+            data: { ...result, confirmation },
+            human: [
+                `Signing key ${result.keyId}`,
+                `Secret      ${result.secret}`,
+                `Revision    ${String(result.settings.revision)}`,
+                "Save this secret now. It will not be returned again.",
+            ].join("\n"),
+        };
+    },
+    "notifications deliveries": async (runtime, args) => {
+        const [project] = positionals(args, ["<project>"], `${runtime.programName} notifications deliveries <project>`);
+        const active = await session(runtime, args);
+        return listing(runtime, args, {
+            columns: ["Event", "State", "Calls", "Delivery"],
+            command: `${runtime.programName} notifications deliveries ${project}`,
+            empty: "No status notifications have been queued.",
+            read: async (request) => {
+                const result = parseResponse("statusdeliveries.list", await active.client.request("statusdeliveries_list", project, request));
+                return {
+                    data: result.data,
+                    freshness: { kind: "authoritative" },
+                    ...(result.nextCursor === undefined
+                        ? {}
+                        : { nextCursor: result.nextCursor }),
+                };
+            },
+            row: (row) => [row.event, row.state, String(row.attempts), row.id],
+        });
+    },
     "limits show": limitsShow,
     "attempts read": attemptsRead,
     billing,

package/package.json

@@ -7,8 +7,8 @@
     "url": "https://github.com/flowxo/greatwait/issues"
   },
   "dependencies": {
-    "@greatwait/api-client": "0.1.0-alpha.6",
-    "@greatwait/contracts": "0.1.0-alpha.6"
+    "@greatwait/api-client": "0.1.0-alpha.8",
+    "@greatwait/contracts": "0.1.0-alpha.8"
   },
   "description": "The GreatWait command line: sign in, create a destination and a one-shot schedule, and wait for the callback, over the public API.",
   "engines": {
@@ -48,5 +48,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.1.0-alpha.6"
+  "version": "0.1.0-alpha.8"
 }