@greatwait/cli 0.3.0 → 0.3.1

package/README.md

@@ -43,6 +43,13 @@ 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.
 
+For a short script that needs a bearer token, `greatwait token` prints the
+credential for the selected API origin, refreshing an expiring OAuth sign-in
+first. Add `--api-url <origin>` to choose an origin explicitly. `--json` prints
+`{token, origin, expiresAt}`; an API key is returned unchanged with `null` expiry.
+This output is a secret: keep it out of logs, shell tracing and shared files.
+Use a scoped API key for unattended automation.
+
 ## First callback
 
 Use a public HTTPS receiver you control. Once signed in, schedule directly to
@@ -99,6 +106,8 @@ grant and remove local credentials.
 ## Output and exit codes
 
 `--json` is a versioned machine shape, not a serialization of the human text.
+The deliberate secret-output command `token --json` returns the credential object
+described above.
 The exit status is a class rather than a code per failure:
 
 | code | meaning                                                                |

package/dist/catalog.js

@@ -493,6 +493,14 @@ export const COMMAND_CATALOG = [
         summary: "Sign out, and forget the credential stored on this machine.",
         words: "logout",
     },
+    {
+        group: "Session",
+        operations: [],
+        options: [API_URL],
+        positionals: [],
+        summary: "Print the credential for the selected origin, refreshing OAuth first when needed. Output is a secret: keep it out of logs and shell tracing. --json prints token, origin and expiresAt (null for API keys).",
+        words: "token",
+    },
     {
         group: "Session",
         operations: ["context.read"],
@@ -831,10 +839,20 @@ export const COMMAND_CATALOG = [
                 summary: "JSON your receiver gets with the call. Inline, @file.json, or - for standard input.",
                 value: "<json>",
             },
+            {
+                flag: "--completion",
+                value: "<response|callback>",
+                summary: "How work finishes: response or callback. Defaults to response on create; replace keeps the stored value when omitted.",
+            },
+            {
+                flag: "--on-overlap",
+                value: "<skip|queue>",
+                summary: "When the next run is due before work finishes: skip or queue. Defaults to skip on create; replace keeps the stored value when omitted.",
+            },
             {
                 flag: "--delivery-timeout",
                 value: "<duration>",
-                summary: "How long the receiver may take, such as 20s or 5m (whole seconds). Defaults to 5s on create; replace keeps the stored timeout. Response completion allows up to 30m; longer needs existing callback completion. Separate from --timeout for --wait.",
+                summary: "How long the receiver may take, such as 20s or 5m (whole seconds). Defaults to 5s on create; replace keeps the stored timeout. Response completion allows up to 30m; callback completion allows up to 24h. Separate from --timeout for --wait.",
             },
             IDEMPOTENCY,
             {
@@ -918,6 +936,16 @@ export const COMMAND_CATALOG = [
                 summary: "JSON your receiver gets with the call. Inline, @file.json, or - for standard input.",
                 value: "<json>",
             },
+            {
+                flag: "--completion",
+                value: "<response|callback>",
+                summary: "How work finishes: response or callback. Defaults to response on create; replace keeps the stored value when omitted.",
+            },
+            {
+                flag: "--on-overlap",
+                value: "<skip|queue>",
+                summary: "When the next run is due before work finishes: skip or queue. Defaults to skip on create; replace keeps the stored value when omitted.",
+            },
             {
                 flag: "--delivery-timeout",
                 value: "<duration>",

package/dist/commands.js

@@ -10,7 +10,7 @@ import { awaitRedirect, buildAuthorization, codeFrom, discover, exchangeCode, re
 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 { anonymousClient, ENVIRONMENT_NAMES, openCredential, openSession, resolveOrigin, storeFor, } from "./session.js";
 import { OPERATE_COMMANDS, destinationLines, scheduleRequest } from "./operate.js";
 import { apiUrlOption, expectNoExtraArguments, parseResponse, positionals, } from "./support.js";
 /* -------------------------------------------------------------------------- */
@@ -317,6 +317,13 @@ const CREDENTIAL_LABELS = {
     "environment-key": `an API credential from ${ENVIRONMENT_NAMES.apiKey}`,
     oauth: "an OAuth grant",
 };
+const token = async (runtime, args) => {
+    expectNoExtraArguments(args, 0, `${runtime.programName} token [--api-url <origin>]`);
+    const { token, origin, expiresAt } = await openCredential(runtime, {
+        apiUrl: apiUrlOption(args),
+    });
+    return { human: token, data: { token, origin, expiresAt } };
+};
 const whoami = async (runtime, args) => {
     expectNoExtraArguments(args, 0, `${runtime.programName} whoami [--api-url <origin>]`);
     const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
@@ -677,6 +684,7 @@ const schedulesCreate = async (runtime, args) => {
     const schedule = created.schedule.id;
     const occurrence = created.occurrence.id;
     const data = {
+        delivery: created.schedule.delivery,
         ...(created.endpointSigningSecret === undefined
             ? {}
             : {
@@ -1052,6 +1060,7 @@ const IMPLEMENTATIONS = {
     "occurrences wait": occurrencesWait,
     "schedules create": schedulesCreate,
     "schedules read": schedulesRead,
+    token,
     whoami,
 };
 /**

package/dist/operate.d.ts

@@ -34,7 +34,7 @@ type Command = (runtime: CliRuntime, args: ParsedArguments) => Promise<CommandRe
  * machine's would make the same expression mean different things on a laptop
  * and on a build runner.
  */
-declare function scheduleRequest(runtime: CliRuntime, args: ParsedArguments, usage: string): Promise<Readonly<Record<string, unknown>>>;
+declare function scheduleRequest(runtime: CliRuntime, args: ParsedArguments, usage: string, mode?: "create" | "replace"): Promise<Readonly<Record<string, unknown>>>;
 /**
  * Where a schedule written with `--url` delivers, and where its signing
  * secret is.

package/dist/operate.js

@@ -1,6 +1,6 @@
 import { BULK_COMMANDS } from "./bulk.js";
 import { writeFile } from "node:fs/promises";
-import { projectNotificationSettingsUpdateRequestSchema, statusSigningKeyRequestSchema, autoPauseAfterFailuresSchema, deliveryDurationSecondsSchema, httpRequestSchema, externalIdentifierSchema, scheduleTagsSchema, scheduleTagSchema, scheduleSelectionSchema, normalizeScheduleSelection, projectAttemptSearchRequestSchema, normalizeAttemptSelection, sanitizedDiagnosticText, diagnosticBodyText, responseBodySentence, requestCaptureSentence, attemptStatusGuidance, endpointHeaderChangesSchema, billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingNotificationSettingsUpdateRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, billingRedeemRequestSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, } from "@greatwait/contracts";
+import { projectNotificationSettingsUpdateRequestSchema, statusSigningKeyRequestSchema, autoPauseAfterFailuresSchema, deliveryDurationSecondsSchema, deliveryCompletionModeSchema, deliveryOverlapPolicySchema, scheduleRequestSchema, httpRequestSchema, externalIdentifierSchema, scheduleTagsSchema, scheduleTagSchema, scheduleSelectionSchema, normalizeScheduleSelection, projectAttemptSearchRequestSchema, normalizeAttemptSelection, sanitizedDiagnosticText, diagnosticBodyText, responseBodySentence, requestCaptureSentence, attemptStatusGuidance, endpointHeaderChangesSchema, billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingNotificationSettingsUpdateRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, billingRedeemRequestSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, } from "@greatwait/contracts";
 import { parseDuration } from "./args.js";
 import { confirmChange } from "./confirm.js";
 import { redactSecret } from "./output.js";
@@ -80,7 +80,7 @@ const RECURRENCE_FLAGS = ["--in", "--at", "--every", "--cron"];
  * machine's would make the same expression mean different things on a laptop
  * and on a build runner.
  */
-async function scheduleRequest(runtime, args, usage) {
+async function scheduleRequest(runtime, args, usage, mode = "create") {
     const given = RECURRENCE_FLAGS.filter((flag) => args.options[flag] !== undefined);
     if (given.length !== 1) {
         throw new CliError(given.length === 0
@@ -132,6 +132,27 @@ async function scheduleRequest(runtime, args, usage) {
         : deliveryDurationSecondsSchema.safeParse(parseDuration(timeoutInput));
     if (timeout !== undefined && !timeout.success)
         throw new CliError("--delivery-timeout is invalid", "usage", timeout.error.issues.map((issue) => issue.message).join("; "));
+    const completionInput = args.options["--completion"];
+    const completion = completionInput === undefined
+        ? undefined
+        : deliveryCompletionModeSchema.safeParse(completionInput);
+    if (completion !== undefined && !completion.success)
+        throw new CliError('--completion (delivery.completion) must be "response" or "callback"', "usage");
+    const overlapInput = args.options["--on-overlap"];
+    const overlap = overlapInput === undefined
+        ? undefined
+        : deliveryOverlapPolicySchema.safeParse(overlapInput);
+    if (overlap !== undefined && !overlap.success)
+        throw new CliError('--on-overlap (delivery.onOverlap) must be "skip" or "queue"', "usage");
+    const delivery = {
+        ...(timeout?.success ? { maxDurationSeconds: timeout.data } : {}),
+        ...(completion?.success ? { completion: completion.data } : {}),
+        ...(overlap?.success ? { onOverlap: overlap.data } : {}),
+    };
+    // Replacement validates the resulting pair after reading the stored settings.
+    // An omitted completion there can mean a retained callback, not response.
+    if (mode === "create")
+        validateDelivery(delivery);
     const external_identifier = args.options["--external-identifier"];
     if (external_identifier !== undefined &&
         !externalIdentifierSchema.safeParse(external_identifier).success)
@@ -145,9 +166,7 @@ async function scheduleRequest(runtime, args, usage) {
         ...(external_identifier === undefined ? {} : { external_identifier }),
         ...(parsedTags?.success ? { tags: parsedTags.data } : {}),
         ...(http?.success ? { http: http.data } : {}),
-        ...(timeout?.success
-            ? { delivery: { maxDurationSeconds: timeout.data } }
-            : {}),
+        ...(Object.keys(delivery).length === 0 ? {} : { delivery }),
         ...(endpoint === undefined ? {} : { endpoint }),
         ...(url === undefined ? {} : { url }),
         ...(latencyClass === undefined ? {} : { latencyClass }),
@@ -157,6 +176,14 @@ async function scheduleRequest(runtime, args, usage) {
         ...recurrence,
     };
 }
+/** Use the canonical contract's relation between completion and timeout. */
+function validateDelivery(delivery) {
+    const parsed = scheduleRequestSchema.safeParse({ delaySeconds: 1, delivery });
+    if (!parsed.success)
+        throw new CliError(parsed.error.issues
+            .map((issue) => `${issue.path.join(".")}: ${issue.message}`)
+            .join("; "), "usage");
+}
 /**
  * Where a schedule written with `--url` delivers, and where its signing
  * secret is.
@@ -518,35 +545,30 @@ async function scheduleChange(runtime, args, options) {
 const schedulesReplace = async (runtime, args) => {
     const usage = `${runtime.programName} schedules replace <schedule> (--endpoint <destination> | --url <https url>) (--in <duration> | --at <instant> | --every <duration> | --cron <expression>)`;
     const [id] = positionals(args, ["<schedule>"], usage);
-    const request = await scheduleRequest(runtime, args, usage);
+    const request = await scheduleRequest(runtime, args, usage, "replace");
     return scheduleChange(runtime, args, {
         act: (active, scheduleId, current) => {
             if (current === undefined)
                 throw new CliError("Replacement needs its schedule read", "internal");
-            const delivery = current.schedule.delivery;
-            const timeout = args.options["--delivery-timeout"];
-            if (timeout !== undefined &&
+            const delivery = {
+                ...current.schedule.delivery,
+                ...request["delivery"],
+            };
+            const changesDelivery = request["delivery"] !== undefined;
+            validateDelivery(delivery);
+            if (changesDelivery &&
                 current.schedule.endpoint === undefined &&
                 request["endpoint"] === undefined &&
                 request["url"] === undefined)
-                throw new CliError("--delivery-timeout needs a callback destination", "usage", "Give --endpoint or --url when attaching a callback to a timer-only schedule.");
+                throw new CliError("Delivery settings need a callback destination", "usage", "Give --endpoint or --url when attaching a callback to a timer-only schedule.");
             // The API replaces delivery settings with defaults when callback fields
             // are supplied. Carry all stored settings, including completion/overlap.
-            // Naming the retained endpoint also makes a timeout-only change reach
+            // Naming the retained endpoint also makes a delivery-only change reach
             // that callback replacement path. Fence the read against concurrent edits.
             return active.client.requestDetailed("schedules_replace", scheduleId, {
                 ...request,
-                ...(delivery === undefined
-                    ? {}
-                    : {
-                        delivery: {
-                            ...delivery,
-                            ...(timeout === undefined
-                                ? {}
-                                : { maxDurationSeconds: parseDuration(timeout) }),
-                        },
-                    }),
-                ...(timeout !== undefined &&
+                ...(Object.keys(delivery).length === 0 ? {} : { delivery }),
+                ...(changesDelivery &&
                     request["endpoint"] === undefined &&
                     request["url"] === undefined &&
                     current.schedule.endpoint !== undefined

package/dist/output.js

@@ -27,6 +27,9 @@ export function renderResult(command, result, json) {
             ? `${result.human}\n`
             : `${result.human}\n\n${result.nextMove}\n`;
     }
+    // The token command is a shell credential primitive with a bare JSON shape.
+    if (command === "token")
+        return `${JSON.stringify(result.data)}\n`;
     return `${JSON.stringify({
         command,
         data: result.data,

package/dist/session.d.ts

@@ -49,9 +49,20 @@ export declare function anonymousClient(runtime: CliRuntime, origin: string): De
  * reason nothing on their machine explains. Persisting first costs one write
  * and removes the whole failure.
  */
+export interface SessionCredential {
+    readonly token: string;
+    readonly expiresAt: string | null;
+    readonly credentialKind: Session["credentialKind"];
+    readonly origin: string;
+    readonly originSource: ResolvedOrigin["source"];
+}
 export declare function openSession(runtime: CliRuntime, options: {
     readonly apiUrl?: string | undefined;
 }): Promise<Session>;
+/** Resolve the exact credential used by commands, persisting refresh before use. */
+export declare function openCredential(runtime: CliRuntime, options: {
+    readonly apiUrl?: string | undefined;
+}): Promise<SessionCredential>;
 /**
  * How long before expiry a grant is refreshed rather than presented.
  *

package/dist/session.js

@@ -69,31 +69,28 @@ export function anonymousClient(runtime, origin) {
         fetch: runtime.fetch,
     });
 }
-/**
- * An authenticated session, refreshing an expired grant on the way.
- *
- * **The rotated pair is written back before the token is used.** A refresh
- * exchange invalidates the refresh token it was given, so a process that
- * refreshed, made its call, and crashed would leave a stored refresh token the
- * service no longer honours — and the person would have to sign in again for a
- * reason nothing on their machine explains. Persisting first costs one write
- * and removes the whole failure.
- */
 export async function openSession(runtime, options) {
+    const credential = await openCredential(runtime, options);
+    return {
+        client: createGreatwaitClient({
+            baseUrl: credential.origin,
+            credential: credential.token,
+            fetch: runtime.fetch,
+        }),
+        credentialKind: credential.credentialKind,
+        origin: credential.origin,
+        originSource: credential.originSource,
+    };
+}
+/** Resolve the exact credential used by commands, persisting refresh before use. */
+export async function openCredential(runtime, options) {
     const store = storeFor(runtime);
     const resolved = await resolveOrigin(runtime, store, options.apiUrl);
-    // **The environment wins, and only for an API key.** Non-interactive
-    // automation is the case this exists for, and the journey's own variable is
-    // the one it already exports. A stored OAuth grant is a person's, and a cron
-    // job that silently used one would be acting as them.
     const fromEnvironment = runtime.env[ENVIRONMENT_NAMES.apiKey];
     if (fromEnvironment !== undefined && fromEnvironment !== "") {
         return {
-            client: createGreatwaitClient({
-                baseUrl: resolved.origin,
-                credential: fromEnvironment,
-                fetch: runtime.fetch,
-            }),
+            token: fromEnvironment,
+            expiresAt: null,
             credentialKind: "environment-key",
             origin: resolved.origin,
             originSource: resolved.source,
@@ -101,15 +98,11 @@ export async function openSession(runtime, options) {
     }
     const stored = await store.read(resolved.origin);
     if (stored === undefined) {
-        throw new CliError(`no credential is stored for ${resolved.origin}`, "authentication", `Sign in — ${runtime.programName} login --api-url ${resolved.origin} — or export ${ENVIRONMENT_NAMES.apiKey} for a non-interactive run.`);
+        throw new CliError(`no credential is stored for ${resolved.origin}`, "authentication", `Sign in with ${runtime.programName} login --api-url ${resolved.origin} — or export ${ENVIRONMENT_NAMES.apiKey} for a non-interactive run.`);
     }
-    const credential = await presentableSecret(runtime, store, resolved.origin, stored);
+    const secret = await presentableSecret(runtime, store, resolved.origin, stored);
     return {
-        client: createGreatwaitClient({
-            baseUrl: resolved.origin,
-            credential,
-            fetch: runtime.fetch,
-        }),
+        ...secret,
         credentialKind: stored.kind,
         origin: resolved.origin,
         originSource: resolved.source,
@@ -132,26 +125,35 @@ async function presentableSecret(runtime, store, origin, stored) {
         if (stored.secret === undefined) {
             throw new CliError(`the stored credential for ${origin} carries no secret`, "authentication", `Sign in again: ${runtime.programName} login --api-url ${origin} --api-key`);
         }
-        return stored.secret;
+        return { token: stored.secret, expiresAt: null };
     }
     const { accessToken, clientId, expiresAtMs, refreshToken } = stored;
     if (accessToken === undefined || clientId === undefined) {
         throw new CliError(`the stored grant for ${origin} is incomplete`, "authentication", `Sign in again: ${runtime.programName} login --api-url ${origin}`);
     }
     if (expiresAtMs === undefined ||
-        expiresAtMs - REFRESH_MARGIN_MS > runtime.now() ||
-        refreshToken === undefined) {
-        return accessToken;
+        expiresAtMs - REFRESH_MARGIN_MS > runtime.now()) {
+        return {
+            token: accessToken,
+            expiresAt: expiresAtMs === undefined ? null : new Date(expiresAtMs).toISOString(),
+        };
+    }
+    if (refreshToken === undefined) {
+        throw new CliError(`the stored grant for ${origin} needs refreshing but carries no refresh token`, "authentication", `Sign in with ${runtime.programName} login --api-url ${origin}`);
     }
     const server = await discover(runtime, origin);
     const rotated = await refresh(runtime, server, { clientId, refreshToken });
+    const refreshedExpiresAtMs = runtime.now() + rotated.expiresInSeconds * 1000;
     await store.write(origin, {
         accessToken: rotated.accessToken,
         clientId,
-        expiresAtMs: runtime.now() + rotated.expiresInSeconds * 1000,
+        expiresAtMs: refreshedExpiresAtMs,
         kind: "oauth",
         refreshToken: rotated.refreshToken,
         scope: rotated.scope,
     });
-    return rotated.accessToken;
+    return {
+        token: rotated.accessToken,
+        expiresAt: new Date(refreshedExpiresAtMs).toISOString(),
+    };
 }

package/package.json

@@ -7,8 +7,8 @@
     "url": "https://github.com/flowxo/greatwait/issues"
   },
   "dependencies": {
-    "@greatwait/api-client": "0.3.0",
-    "@greatwait/contracts": "0.3.0"
+    "@greatwait/api-client": "0.3.1",
+    "@greatwait/contracts": "0.3.1"
   },
   "description": "The GreatWait command line: sign in, schedule a call to a URL, and read its delivery outcome over the public API.",
   "engines": {
@@ -48,5 +48,5 @@
   },
   "sideEffects": false,
   "type": "module",
-  "version": "0.3.0"
+  "version": "0.3.1"
 }