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

package/dist/cli.js

@@ -27,7 +27,7 @@ import { CliError, InterruptedError } from "./runtime.js";
  * that exists appears here, and one that does not, cannot.
  */
 function usage(programName) {
-    return `${programName} — the Greatwait command line
+    return `${programName} — the GreatWait command line
 
 ${overview()}
 
@@ -102,7 +102,9 @@ function classify(error, programName) {
         return {
             exit: classifyStatus(error.status, problem?.code),
             human: problem === undefined
-                ? `The service answered ${String(error.status)}.`
+                ? error.status === 0
+                    ? "The service could not be reached."
+                    : `The service answered ${String(error.status)}.`
                 : `${problem.title} (${problem.code})`,
             // **Every published code, not the two that were spelled out here.** This
             // was a two-branch conditional naming `authentication_required` and

package/dist/commands.js

@@ -1,5 +1,7 @@
+import { readPrivateJsonOption } from "./support.js";
+import { MEMBER_IMPLEMENTATIONS } from "./member-commands.js";
 import { GreatwaitClientError, createGreatwaitClient, } from "@greatwait/api-client";
-import { isTerminalOccurrenceState, responseSchemaFor, } from "@greatwait/contracts";
+import { endpointHeaderChangesSchema, isTerminalOccurrenceState, responseSchemaFor, } from "@greatwait/contracts";
 import { parseDuration } from "./args.js";
 import { COMMAND_CATALOG, REQUESTED_SCOPES } from "./catalog.js";
 import { confirmChange } from "./confirm.js";
@@ -9,7 +11,7 @@ import { redactSecret } from "./output.js";
 import { CliError, sleepOrAbort } from "./runtime.js";
 import { publishedWait, recoveryFor, renderJourney, STEP_COMMANDS, } from "./journey.js";
 import { anonymousClient, ENVIRONMENT_NAMES, openSession, resolveOrigin, storeFor, } from "./session.js";
-import { OPERATE_COMMANDS, scheduleRequest } from "./operate.js";
+import { OPERATE_COMMANDS, destinationLines, scheduleRequest } from "./operate.js";
 import { apiUrlOption, expectNoExtraArguments, parseResponse, positionals, } from "./support.js";
 /* -------------------------------------------------------------------------- */
 /* Signing in                                                                 */
@@ -203,7 +205,9 @@ async function describeThrough(client, origin, programName) {
         };
     }
     catch (error) {
-        if (!(error instanceof GreatwaitClientError)) {
+        if (!(error instanceof GreatwaitClientError) || error.status === 0) {
+            // The SDK uses status 0 when its transport retries are exhausted; older
+            // adapters may still throw the original network error.
             // **A transport failure is not an answer about the credential.** The
             // request never reached the service — no DNS, no TLS, a reset — so it
             // says nothing about what was just issued, and it does not carry a
@@ -395,7 +399,7 @@ const doctor = async (runtime, args) => {
             checks.push({
                 detail: error instanceof Error
                     ? error.message
-                    : "the origin did not answer as a Greatwait API",
+                    : "the origin did not answer as a GreatWait API",
                 name: "reachable",
                 outcome: "failed",
             });
@@ -569,8 +573,17 @@ const destinationsCreate = async (runtime, args) => {
     if (url === undefined) {
         throw new CliError(`${runtime.programName} destinations create needs --url`, "usage", `Usage: ${runtime.programName} destinations create --url https://your-receiver.example.com/greatwait`);
     }
+    const headerInput = await readPrivateJsonOption(runtime, "--headers", args.options["--headers"]);
+    const headers = headerInput === undefined
+        ? undefined
+        : endpointHeaderChangesSchema.safeParse(headerInput);
+    if (headers !== undefined && !headers.success)
+        throw new CliError("--headers settings are invalid", "usage", headers.error.issues.map((issue) => issue.message).join("; "));
     const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
-    const created = responseSchemaFor("endpoints.create")?.parse(await session.client.request("endpoints_create", { url }));
+    const created = responseSchemaFor("endpoints.create")?.parse(await session.client.request("endpoints_create", {
+        url,
+        ...(headers?.success ? { headers: headers.data } : {}),
+    }));
     return {
         // **The secret is here and in no later output.** The service returns it
         // from this call and from no other, which is the product behaviour rather
@@ -583,9 +596,11 @@ const destinationsCreate = async (runtime, args) => {
             ``,
             `Signing key  ${created.secret}`,
             ``,
-            `This key is shown once and is not recoverable. Store it now — your receiver`,
+            `This is the only call that returns the key. Store it now — your receiver`,
             `verifies every callback with it, and reading this destination back will show`,
-            `${redactSecret(created.secret)} instead.`,
+            `${redactSecret(created.secret)} instead. If you lose it, a signed-in member`,
+            `can read it again on this destination's page in the dashboard; no command`,
+            `here can, because the reveal accepts a member session and not a grant.`,
         ].join("\n"),
         nextMove: `Next: ${runtime.programName} schedules create --endpoint ${created.id} --in 30s`,
     };
@@ -624,16 +639,27 @@ const destinationsDisable = async (runtime, args) => {
 /* Schedules                                                                  */
 /* -------------------------------------------------------------------------- */
 const schedulesCreate = async (runtime, args) => {
-    const usage = `${runtime.programName} schedules create --endpoint <destination> (--in <duration> | --at <instant> | --every <duration> | --cron <expression>)`;
-    if (args.options["--endpoint"] === undefined) {
-        throw new CliError(`${runtime.programName} schedules create needs --endpoint`, "usage", `Usage: ${usage}`);
+    const usage = `${runtime.programName} schedules create (--endpoint <destination> | --url <https url>) (--in <duration> | --at <instant> | --every <duration> | --cron <expression>) [--wait]`;
+    if (args.options["--endpoint"] === undefined &&
+        args.options["--url"] === undefined) {
+        throw new CliError(`${runtime.programName} schedules create needs --url or --endpoint`, "usage", `Usage: ${usage}`);
+    }
+    const wait = args.booleans.has("--wait");
+    // Parsed before anything is sent: a typo in --timeout found after the create
+    // would exit without the schedule's id or retry key, and the corrected rerun
+    // would make a second schedule.
+    const timeoutMs = wait ? waitTimeoutMs(args) : undefined;
+    if (!wait && args.options["--timeout"] !== undefined) {
+        // Refused rather than ignored: somebody who passed a timeout believes the
+        // command will wait for something.
+        throw new CliError("--timeout only means something with --wait", "usage", `Usage: ${usage} [--timeout <duration>]`);
     }
     expectNoExtraArguments(args, 0, usage);
     const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
     // **The same builder `schedules replace` uses.** The two send the identical
     // definition — a replace is a create with an identifier — and writing the
     // recurrence rules out twice is how one of them comes to accept a cron
-    // expression the other does not.
+    // expression the other does not. It also refuses `--url` with `--endpoint`.
     const request = await scheduleRequest(runtime, args, usage);
     // **Generated when it is not given, and printed either way.** A create that
     // silently invented a fresh key on every run would make a retry a second
@@ -644,30 +670,125 @@ const schedulesCreate = async (runtime, args) => {
     const answer = await session.client.requestDetailed("schedules_create", request, { "Idempotency-Key": idempotencyKey });
     const created = parseResponse("schedules.create", answer.body);
     const replayed = answer.headers["Idempotency-Replayed"] === "true";
+    const schedule = created.schedule.id;
+    const occurrence = created.occurrence.id;
+    const data = {
+        ...(created.endpointSigningSecret === undefined
+            ? {}
+            : {
+                endpoint: created.schedule.endpoint,
+                endpointSigningSecret: created.endpointSigningSecret,
+            }),
+        idempotencyKey,
+        occurrence,
+        plannedFor: created.occurrence.plannedFor,
+        replayed,
+        schedule,
+    };
+    const human = [
+        `Schedule     ${schedule}`,
+        `Occurrence   ${occurrence}`,
+        `Planned for  ${created.occurrence.plannedFor}`,
+        `Retry key    ${idempotencyKey}`,
+        ...destinationLines(created.schedule, created.endpointSigningSecret, args.options["--url"]),
+        ...(replayed
+            ? [
+                ``,
+                `This key had already been used for this exact request, so nothing was`,
+                `created a second time and no second callback will be delivered.`,
+            ]
+            : []),
+    ];
+    const watchLater = `${runtime.programName} occurrences wait ${schedule} ${occurrence}`;
+    if (!wait) {
+        return {
+            data,
+            human: human.join("\n"),
+            nextMove: `Next: ${watchLater}`,
+        };
+    }
+    const repeats = created.schedule.recurrence.kind !== "at";
+    if (timeoutMs === undefined)
+        throw new CliError("--wait lost its timeout", "internal");
+    const dueInMs = Date.parse(created.occurrence.plannedFor) - runtime.now();
+    if (dueInMs > timeoutMs) {
+        // **Said at once rather than discovered at the deadline.** Polling for
+        // three minutes towards a call due tomorrow would end in the same timeout
+        // with nothing learned; the schedule exists either way.
+        return {
+            data: {
+                ...data,
+                wait: { settled: false, state: created.occurrence.state },
+            },
+            exit: "timeout",
+            human: [
+                ...human,
+                ``,
+                `Not waiting: the first call is due at ${created.occurrence.plannedFor}, after the wait would end.`,
+            ].join("\n"),
+            nextMove: `Watch it nearer the time: ${watchLater}`,
+        };
+    }
+    // The schedule's identifiers before the wait, so a person who interrupts it
+    // still has them. A machine reads them from the JSON at the end.
+    if (!args.booleans.has("--json")) {
+        runtime.stderr(`${human.join("\n")}\n\n`);
+    }
+    const watched = await watchOccurrence(runtime, session, schedule, occurrence, timeoutMs);
+    const repeating = repeats
+        ? [
+            ``,
+            `This schedule repeats. Only its first call was waited for, and it keeps running.`,
+        ]
+        : [];
+    if (!watched.settled) {
+        return {
+            data: { ...data, wait: { settled: false, state: watched.state } },
+            exit: "timeout",
+            human: [
+                `The first call was still ${watched.state} when the wait ended.`,
+                ...repeating,
+            ].join("\n"),
+            ...(() => {
+                const nextMove = recoveryFor("await-occurrence", "not-settled");
+                return nextMove === undefined ? {} : { nextMove };
+            })(),
+        };
+    }
+    const attempts = parseResponse("attempts.list", await session.client.request("attempts_list", schedule, occurrence)).data;
+    const delivered = watched.occurrence.state === "succeeded";
     return {
         data: {
-            idempotencyKey,
-            occurrence: created.occurrence.id,
-            plannedFor: created.occurrence.plannedFor,
-            replayed,
-            schedule: created.schedule.id,
+            ...data,
+            wait: { attempts, occurrence: watched.occurrence, settled: true },
         },
         human: [
-            `Schedule     ${created.schedule.id}`,
-            `Occurrence   ${created.occurrence.id}`,
-            `Planned for  ${created.occurrence.plannedFor}`,
-            `Retry key    ${idempotencyKey}`,
-            ...(replayed
-                ? [
-                    ``,
-                    `This key had already been used for this exact request, so nothing was`,
-                    `created a second time and no second callback will be delivered.`,
-                ]
-                : []),
+            delivered
+                ? `Delivered. ${outcomeOf(attempts.find((attempt) => attempt.state === "succeeded"))}`
+                : `Not delivered: the first call settled ${watched.occurrence.state}.`,
+            // The attempt rows only when they explain something: a delivered call
+            // has said all it needs to in the line above.
+            ...(delivered || attempts.length === 0
+                ? []
+                : [``, ...attempts.map(attemptLine)]),
+            ...repeating,
         ].join("\n"),
-        nextMove: `Next: ${runtime.programName} occurrences wait ${created.schedule.id} ${created.occurrence.id}`,
+        ...(delivered
+            ? {}
+            : (() => {
+                const nextMove = recoveryFor("read-attempt", "attempt-failed");
+                return nextMove === undefined ? {} : { nextMove };
+            })()),
     };
 };
+function attemptLine(attempt) {
+    return `${attempt.state.padEnd(20)}${attempt.responseStatus === undefined ? "no response" : `answered ${String(attempt.responseStatus)}`}${attempt.diagnostic === undefined ? "" : `  ${attempt.diagnostic}`}${attempt.remediation === undefined ? "" : ` / ${attempt.remediation}`}`;
+}
+function outcomeOf(attempt) {
+    return attempt?.responseStatus === undefined
+        ? "Your receiver accepted the call."
+        : `Your receiver answered ${String(attempt.responseStatus)}.`;
+}
 const schedulesRead = async (runtime, args) => {
     const id = args.command[0];
     if (id === undefined) {
@@ -763,21 +884,28 @@ const exportsCancel = async (runtime, args) => {
 /* -------------------------------------------------------------------------- */
 /* Waiting                                                                    */
 /* -------------------------------------------------------------------------- */
-const occurrencesWait = async (runtime, args) => {
-    const schedule = args.command[0];
-    const occurrence = args.command[1];
-    if (schedule === undefined || occurrence === undefined) {
-        throw new CliError(`${runtime.programName} occurrences wait needs a schedule and an occurrence`, "usage", `Usage: ${runtime.programName} occurrences wait <schedule> <occurrence>`);
-    }
-    expectNoExtraArguments(args, 2, `${runtime.programName} occurrences wait <schedule> <occurrence>`);
-    const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
-    // The interval and the deadline come from the published journey. A number
-    // here would be a fourth answer to a question the website, the curl page and
-    // the JavaScript page already answer identically.
-    const { intervalMs, timeoutMs } = publishedWait();
+/**
+ * How long a wait lasts: `--timeout`, or the published journey's deadline.
+ *
+ * The interval and the deadline come from the published journey. A number
+ * here would be a fourth answer to a question the website, the curl page and
+ * the JavaScript page already answer identically.
+ */
+function waitTimeoutMs(args) {
     const override = args.options["--timeout"];
-    const deadline = runtime.now() +
-        (override === undefined ? timeoutMs : parseDuration(override) * 1000);
+    return override === undefined
+        ? publishedWait().timeoutMs
+        : parseDuration(override) * 1000;
+}
+/**
+ * Reads one occurrence until it settles or the deadline passes, reporting each
+ * new state on standard error. Shared by `occurrences wait` and `schedules
+ * create --wait`, so the two cannot come to disagree about what settled means
+ * or how long the wait lasts.
+ */
+async function watchOccurrence(runtime, session, schedule, occurrence, timeoutMs) {
+    const { intervalMs } = publishedWait();
+    const deadline = runtime.now() + timeoutMs;
     const seen = [];
     for (;;) {
         const view = responseSchemaFor("occurrences.read")?.parse(await session.client.request("occurrences_read", schedule, occurrence));
@@ -787,24 +915,43 @@ const occurrencesWait = async (runtime, args) => {
             runtime.stderr(`  ${state}\n`);
         }
         if (isTerminalOccurrenceState(state)) {
-            return {
-                data: {
-                    attempts: view.occurrence.attemptCount,
-                    occurrence,
-                    schedule,
-                    settled: true,
-                    state,
-                    states: seen,
-                },
-                human: `Occurrence ${occurrence} settled ${state} after ${String(view.occurrence.attemptCount)} ${view.occurrence.attemptCount === 1 ? "attempt" : "attempts"}.`,
-                nextMove: `Next: ${runtime.programName} attempts list ${schedule} ${occurrence}`,
-            };
+            return { occurrence: view.occurrence, settled: true, states: seen };
         }
-        if (runtime.now() >= deadline) {
-            throw new CliError(`occurrence ${occurrence} was still ${state} when the deadline passed`, "timeout", recoveryFor("await-occurrence", "not-settled"));
+        const remaining = deadline - runtime.now();
+        if (remaining <= 0) {
+            return { settled: false, state, states: seen };
         }
-        await sleepOrAbort(runtime, intervalMs);
+        // Cut to the time left, so the last read happens at the deadline rather
+        // than an interval past it — a --timeout that is not a multiple of the
+        // interval means what it says.
+        await sleepOrAbort(runtime, Math.min(intervalMs, remaining));
+    }
+}
+const occurrencesWait = async (runtime, args) => {
+    const schedule = args.command[0];
+    const occurrence = args.command[1];
+    if (schedule === undefined || occurrence === undefined) {
+        throw new CliError(`${runtime.programName} occurrences wait needs a schedule and an occurrence`, "usage", `Usage: ${runtime.programName} occurrences wait <schedule> <occurrence>`);
     }
+    expectNoExtraArguments(args, 2, `${runtime.programName} occurrences wait <schedule> <occurrence>`);
+    const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
+    const watched = await watchOccurrence(runtime, session, schedule, occurrence, waitTimeoutMs(args));
+    if (!watched.settled) {
+        throw new CliError(`occurrence ${occurrence} was still ${watched.state} when the deadline passed`, "timeout", recoveryFor("await-occurrence", "not-settled"));
+    }
+    const { attemptCount, state } = watched.occurrence;
+    return {
+        data: {
+            attempts: attemptCount,
+            occurrence,
+            schedule,
+            settled: true,
+            state,
+            states: watched.states,
+        },
+        human: `Occurrence ${occurrence} settled ${state} after ${String(attemptCount)} ${attemptCount === 1 ? "attempt" : "attempts"}.`,
+        nextMove: `Next: ${runtime.programName} attempts list ${schedule} ${occurrence}`,
+    };
 };
 const attemptsList = async (runtime, args) => {
     const schedule = args.command[0];
@@ -820,9 +967,7 @@ const attemptsList = async (runtime, args) => {
         data: { attempts: page.data, occurrence, schedule },
         human: page.data.length === 0
             ? "No attempt has been made yet."
-            : page.data
-                .map((attempt) => `${attempt.state.padEnd(20)}${attempt.responseStatus === undefined ? "no response" : `answered ${String(attempt.responseStatus)}`}${attempt.diagnostic === undefined ? "" : `  ${attempt.diagnostic}`}${attempt.remediation === undefined ? "" : ` / ${attempt.remediation}`}`)
-                .join("\n"),
+            : page.data.map(attemptLine).join("\n"),
         // **The journey's own sentence, not a paraphrase of the code.**
         // `diagnostic` and `remediation` are closed vocabularies rather than prose
         // — the step's `observe` says to read them, and its recovery entry is the
@@ -850,6 +995,7 @@ const attemptsList = async (runtime, args) => {
  */
 const IMPLEMENTATIONS = {
     ...OPERATE_COMMANDS,
+    ...MEMBER_IMPLEMENTATIONS,
     "attempts list": attemptsList,
     context,
     "destinations create": destinationsCreate,

package/dist/exit.d.ts

@@ -33,6 +33,18 @@ export declare const EXIT_CLASSES: {
     readonly retryable: 6;
     /** A deadline this command was given passed before the answer arrived. */
     readonly timeout: 7;
+    /**
+     * The service is not configured to do this, and repeating will not change
+     * that.
+     *
+     * **A separate number from `retryable` because a script must not loop on
+     * it.** Both are 5xx and both mean "the service, not you" — but one clears
+     * on its own and the other waits on somebody changing the deployment. Until
+     * FXO-2497 these shared class 6, so a client told "the identical request is
+     * safe to repeat" would retry a condition that is permanent, and a customer
+     * was offered a "Try again" control that could never work.
+     */
+    readonly unconfigured: 8;
     /**
      * Interrupted.
      *
@@ -60,8 +72,9 @@ export declare const EXIT_CLASS_MEANINGS: Readonly<Record<ExitClass, string>>;
  * A refusal from an edge proxy carries no problem document at all — there is no
  * code to read — and a client that branched on the code first would classify
  * every one of those as internal. The code refines the answer where it
- * disagrees with the status, which is exactly once: `scope_missing` is a `403`
- * and belongs in `authorization`, and everything else in the 4xx range that is
+ * disagrees with the status, which is exactly twice: `scope_missing` is a `403`
+ * and belongs in `authorization`, `capability_not_configured` is a `503` that
+ * must not be called retryable, and everything else in the 4xx range that is
  * not authentication is the caller's request to fix.
  */
 export declare function classifyStatus(status: number, problemCode?: string): ExitClass;

package/dist/exit.js

@@ -33,6 +33,18 @@ export const EXIT_CLASSES = {
     retryable: 6,
     /** A deadline this command was given passed before the answer arrived. */
     timeout: 7,
+    /**
+     * The service is not configured to do this, and repeating will not change
+     * that.
+     *
+     * **A separate number from `retryable` because a script must not loop on
+     * it.** Both are 5xx and both mean "the service, not you" — but one clears
+     * on its own and the other waits on somebody changing the deployment. Until
+     * FXO-2497 these shared class 6, so a client told "the identical request is
+     * safe to repeat" would retry a condition that is permanent, and a customer
+     * was offered a "Try again" control that could never work.
+     */
+    unconfigured: 8,
     /**
      * Interrupted.
      *
@@ -59,6 +71,7 @@ export const EXIT_CLASS_MEANINGS = {
     ok: "It did what it was asked.",
     retryable: "The service could not answer now. The identical request may work later.",
     timeout: "A deadline this command was given passed before the answer arrived.",
+    unconfigured: "The service is not configured to do this. Repeating will not help; it needs somebody to change the service.",
     usage: "The command line was wrong.",
     validation: "The request was refused on its merits: invalid, missing, or conflicting.",
 };
@@ -69,13 +82,23 @@ export const EXIT_CLASS_MEANINGS = {
  * A refusal from an edge proxy carries no problem document at all — there is no
  * code to read — and a client that branched on the code first would classify
  * every one of those as internal. The code refines the answer where it
- * disagrees with the status, which is exactly once: `scope_missing` is a `403`
- * and belongs in `authorization`, and everything else in the 4xx range that is
+ * disagrees with the status, which is exactly twice: `scope_missing` is a `403`
+ * and belongs in `authorization`, `capability_not_configured` is a `503` that
+ * must not be called retryable, and everything else in the 4xx range that is
  * not authentication is the caller's request to fix.
  */
 export function classifyStatus(status, problemCode) {
     if (problemCode === "scope_missing")
         return "authorization";
+    // Without this the status alone decides, and a 503 falls through to
+    // `retryable` below — which is the defect: a permanent configuration refusal
+    // telling a script that repeating it is safe.
+    if (problemCode === "capability_not_configured")
+        return "unconfigured";
+    // The SDK uses zero when no HTTP answer survives its transport retries.
+    // This is a failed exchange, not a successful command.
+    if (status === 0)
+        return "retryable";
     if (status === 401)
         return "authentication";
     if (status === 403)

package/dist/member-catalog.d.ts

@@ -0,0 +1 @@
+export { MEMBER_COMMANDS } from "./catalog.js";

package/dist/member-catalog.js

@@ -0,0 +1 @@
+export { MEMBER_COMMANDS } from "./catalog.js";

package/dist/member-commands.d.ts

@@ -0,0 +1,6 @@
+import type { ParsedArguments } from "./args.js";
+import type { CommandResult } from "./output.js";
+import { type CliRuntime } from "./runtime.js";
+export declare const MEMBER_IMPLEMENTATIONS: {
+    [k: string]: (runtime: CliRuntime, args: ParsedArguments) => Promise<CommandResult>;
+};