@greatwait/cli 0.1.0-alpha.7 → 0.2.0

package/README.md

@@ -6,7 +6,6 @@ against a receiver you control.
 ```sh
 npm install --global @greatwait/cli
 greatwait login --api-url https://api.greatwait.dev
-greatwait journey
 ```
 
 ## What it is
@@ -44,18 +43,59 @@ directory, readable by you and nobody else. A staging credential is never
 presented to production, because the two are separate entries rather than one
 current context.
 
-## First value
+## First callback
 
-`greatwait journey` prints the published first-value sequence — the same nine
-steps the website and the quickstarts walk — with the command for each one.
+Use a public HTTPS receiver you control. Once signed in, schedule directly to
+its URL and wait for the first delivery:
 
 ```sh
-greatwait destinations create --url https://your-receiver.example.com/greatwait
-greatwait schedules create --endpoint ep_… --in 30s --data '{"greeting":"first value"}'
-greatwait occurrences wait sch_… occ_…
-greatwait attempts list sch_… occ_…
+greatwait schedules create --url https://your-receiver.example.com/greatwait --in 30s --data '{"hello":"world"}' --wait
 ```
 
+GreatWait uses your project's destination at that URL or creates one. The
+answer includes the schedule and occurrence ids; copy them into the read:
+
+```sh
+greatwait attempts list <schedule> <occurrence>
+```
+
+Look for `state: succeeded` and the status your receiver returned. `--wait`
+stops after three minutes by default; a settled failure is also an outcome,
+so inspect the attempt. If it times out, use
+`greatwait occurrences wait <schedule> <occurrence>` and read the attempts
+again. The timeout does not cancel the scheduled call.
+
+For a signed receiver, first add your URL in
+[Settings → Endpoints](https://app.greatwait.dev/settings/endpoints), reveal its
+signing secret, and configure the receiver. The direct-URL schedule reuses that
+destination. If the schedule already created it, reveal the secret and configure
+the receiver before its due time; use a longer `--in` if needed. Direct-URL
+scheduling never prints the signing secret. Verify the signature over the exact request bytes
+before parsing, as described in the
+[CLI quickstart](https://docs.greatwait.dev/guides/cli).
+
+## Clean up
+
+Archive the finished schedule. Read it to find its destination id:
+
+```sh
+greatwait schedules read <schedule>
+greatwait schedules archive <schedule>
+```
+
+If this walkthrough created the destination and no other schedule uses it,
+disable it:
+
+```sh
+greatwait destinations disable <destination> --yes
+```
+
+If you stop before delivery, cancel the schedule with
+`greatwait schedules cancel <schedule> --yes` first. Revoke a walkthrough API
+key in the dashboard, or use `greatwait credentials revoke <credential> --yes`
+while signed in through OAuth. Finish with `greatwait logout` to revoke the CLI
+grant and remove local credentials.
+
 ## Output and exit codes
 
 `--json` is a versioned machine shape, not a serialization of the human text.

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",

package/dist/operate.js

@@ -1,5 +1,5 @@
 import { writeFile } from "node:fs/promises";
-import { autoPauseAfterFailuresSchema, httpRequestSchema, sanitizedDiagnosticText, diagnosticBodyText, responseBodySentence, requestCaptureSentence, attemptStatusGuidance, endpointHeaderChangesSchema, billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingNotificationSettingsUpdateRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, } from "@greatwait/contracts";
+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";
@@ -1621,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,10 +7,10 @@
     "url": "https://github.com/flowxo/greatwait/issues"
   },
   "dependencies": {
-    "@greatwait/api-client": "0.1.0-alpha.7",
-    "@greatwait/contracts": "0.1.0-alpha.7"
+    "@greatwait/api-client": "0.2.0",
+    "@greatwait/contracts": "0.2.0"
   },
-  "description": "The GreatWait command line: sign in, create a destination and a one-shot schedule, and wait for the callback, over the public API.",
+  "description": "The GreatWait command line: sign in, schedule a call to a URL, and read its delivery outcome over the public API.",
   "engines": {
     "node": ">=22.13.0"
   },
@@ -48,5 +48,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.1.0-alpha.7"
+  "version": "0.2.0"
 }