@greatwait/cli 0.2.1 → 0.2.3

package/dist/catalog.js

@@ -83,6 +83,30 @@ const API_URL = {
     summary: "The GreatWait API to use, such as https://api.greatwait.dev. Defaults to the one you signed in to.",
     value: "<origin>",
 };
+const CORRELATION_FILTER_OPTIONS = [
+    {
+        flag: "--external-identifier",
+        value: "<id>",
+        summary: "Exact host application identifier, such as a request ID.",
+    },
+    {
+        flag: "--tag",
+        value: "<tag>",
+        summary: "Exact membership of one schedule tag.",
+    },
+];
+const CORRELATION_WRITE_OPTIONS = [
+    {
+        flag: "--external-identifier",
+        value: "<id>",
+        summary: "Searchable host application identifier; at most 256 UTF-8 bytes. Do not include secrets.",
+    },
+    {
+        flag: "--tags",
+        value: "<json>",
+        summary: "JSON array of up to 16 distinct tags, each at most 64 UTF-8 bytes. Inline or @file.json.",
+    },
+];
 const PAGE_OPTIONS = [
     {
         flag: "--limit",
@@ -525,12 +549,21 @@ export const COMMAND_CATALOG = [
         summary: "Start calling a disabled destination again.",
         words: "destinations enable",
     },
+    {
+        group: "Schedules",
+        operations: ["executions.list"],
+        options: [API_URL, ...CORRELATION_FILTER_OPTIONS, ...PAGE_OPTIONS],
+        positionals: [],
+        summary: "Find retained runs, newest first, by host identifier or tag.",
+        words: "executions list",
+    },
     /* --- Schedules -------------------------------------------------------- */
     {
         group: "Schedules",
         operations: ["schedules.list"],
         options: [
             API_URL,
+            ...CORRELATION_FILTER_OPTIONS,
             {
                 flag: "--endpoint",
                 summary: "Only the schedules that call this destination. Its id starts ep_.",
@@ -560,6 +593,7 @@ export const COMMAND_CATALOG = [
         operations: ["schedules.create"],
         options: [
             API_URL,
+            ...CORRELATION_WRITE_OPTIONS,
             {
                 flag: "--endpoint",
                 summary: "The destination to call, by id, starting ep_. Or use --url instead.",
@@ -641,6 +675,7 @@ export const COMMAND_CATALOG = [
         operations: ["schedules.replace"],
         options: [
             API_URL,
+            ...CORRELATION_WRITE_OPTIONS,
             {
                 flag: "--endpoint",
                 summary: "The destination to call, by id, starting ep_. Or use --url instead.",
@@ -1372,6 +1407,34 @@ export const COMMAND_CATALOG = [
         summary: "Remove your saved card. Project fees stop renewing when the paid period ends, and automatic top-up turns off.",
         words: "billing remove-card",
     },
+    {
+        group: "Planning",
+        operations: ["billing.promotions"],
+        options: [API_URL],
+        positionals: [],
+        summary: "List your promotions: promotional credit, complimentary projects, perks and discounts, with their end dates.",
+        words: "billing promotions",
+    },
+    {
+        confirms: true,
+        group: "Planning",
+        operations: ["billing.redeem"],
+        options: [
+            API_URL,
+            {
+                flag: "--target-project",
+                summary: "The project a complimentary-project code should cover.",
+                value: "<project-id>",
+            },
+            IDEMPOTENCY,
+            CONFIRM,
+        ],
+        positionals: [
+            { name: "<code>", summary: "The promotion code, as you received it." },
+        ],
+        summary: "Redeem a promotion code. Nothing is charged.",
+        words: "billing redeem",
+    },
     {
         group: "Planning",
         operations: ["billing.ledger"],
@@ -1626,11 +1689,6 @@ export const OPERATION_OMISSIONS = [
         ground: "declared",
         operation: "projects.delete",
     },
-    {
-        because: "The Executions page is the accepted project-wide history surface in this story. The generated SDK and MCP expose the operation to automation; adding a second interactive CLI design is outside it.",
-        ground: "declared",
-        operation: "executions.list",
-    },
     {
         because: "Grants are what a person gave to an application, and only that person may read them.",
         ground: "principal-unreachable",

package/dist/commands.js

@@ -812,6 +812,10 @@ const schedulesRead = async (runtime, args) => {
             autoPauseAfterFailures: view.schedule.autoPauseAfterFailures,
             consecutiveFailedRuns: view.schedule.consecutiveFailedRuns,
             autoPauseReason: view.schedule.autoPauseReason,
+            ...(view.schedule.external_identifier === undefined
+                ? {}
+                : { external_identifier: view.schedule.external_identifier }),
+            ...(view.schedule.tags === undefined ? {} : { tags: view.schedule.tags }),
             version: view.schedule.version,
         },
         human: [
@@ -825,6 +829,12 @@ const schedulesRead = async (runtime, args) => {
                     `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}`,
+            ...(view.schedule.external_identifier === undefined
+                ? []
+                : [`External ID  ${view.schedule.external_identifier}`]),
+            ...(view.schedule.tags === undefined || view.schedule.tags.length === 0
+                ? []
+                : [`Tags         ${view.schedule.tags.join(", ")}`]),
             `Version      ${String(view.schedule.version)}`,
             ...(etag === undefined ? [] : [`ETag         ${etag}`]),
         ].join("\n"),

package/dist/operate.js

@@ -1,5 +1,5 @@
 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 { projectNotificationSettingsUpdateRequestSchema, statusSigningKeyRequestSchema, autoPauseAfterFailuresSchema, httpRequestSchema, externalIdentifierSchema, scheduleTagsSchema, scheduleTagSchema, 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";
@@ -125,8 +125,18 @@ async function scheduleRequest(runtime, args, usage) {
         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"];
+    const external_identifier = args.options["--external-identifier"];
+    if (external_identifier !== undefined &&
+        !externalIdentifierSchema.safeParse(external_identifier).success)
+        throw new CliError("--external-identifier must contain 1–256 UTF-8 bytes and no NUL characters", "usage");
+    const tags = await readJsonOption(runtime, "--tags", args.options["--tags"]);
+    const parsedTags = tags === undefined ? undefined : scheduleTagsSchema.safeParse(tags);
+    if (parsedTags !== undefined && !parsedTags.success)
+        throw new CliError("--tags must be up to 16 distinct strings, each 1–64 UTF-8 bytes", "usage");
     return {
         ...(data === undefined ? {} : { data }),
+        ...(external_identifier === undefined ? {} : { external_identifier }),
+        ...(parsedTags?.success ? { tags: parsedTags.data } : {}),
         ...(http?.success ? { http: http.data } : {}),
         ...(endpoint === undefined ? {} : { endpoint }),
         ...(url === undefined ? {} : { url }),
@@ -311,18 +321,55 @@ const destinationsRotateKey = async (runtime, args) => {
 /* -------------------------------------------------------------------------- */
 /* Schedules                                                                  */
 /* -------------------------------------------------------------------------- */
+function correlationFilters(args) {
+    const external_identifier = args.options["--external-identifier"];
+    const tag = args.options["--tag"];
+    if (external_identifier !== undefined &&
+        !externalIdentifierSchema.safeParse(external_identifier).success)
+        throw new CliError("--external-identifier must contain 1–256 UTF-8 bytes", "usage");
+    if (tag !== undefined && !scheduleTagSchema.safeParse(tag).success)
+        throw new CliError("--tag must contain 1–64 UTF-8 bytes", "usage");
+    return {
+        ...(external_identifier === undefined ? {} : { external_identifier }),
+        ...(tag === undefined ? {} : { tag }),
+    };
+}
+function correlationCommand(args) {
+    return ["--external-identifier", "--tag"]
+        .flatMap((flag) => args.options[flag] === undefined
+        ? []
+        : [` ${flag} ${`'${args.options[flag].replaceAll("'", "'\"'\"'")}'`}`])
+        .join("");
+}
+const executionsList = async (runtime, args) => {
+    const filters = correlationFilters(args);
+    const active = await session(runtime, args);
+    return listing(runtime, args, {
+        columns: ["STATE", "PLANNED FOR", "SCHEDULE", "RUN"],
+        command: `${runtime.programName} executions list${correlationCommand(args)}`,
+        empty: "No retained runs match these filters.",
+        read: (request) => page("executions.list", () => active.client.request("executions_list", { ...request, ...filters })),
+        row: (run) => [run.state, run.plannedFor, run.schedule, run.id],
+    });
+};
 const schedulesList = async (runtime, args) => {
+    const filters = correlationFilters(args);
     const active = await session(runtime, args);
     const endpoint = args.options["--endpoint"];
     return listing(runtime, args, {
         columns: ["STATUS", "NAME", "RECURRENCE", "DELIVERS TO", "SCHEDULE"],
-        command: `${runtime.programName} schedules list${endpoint === undefined ? "" : ` --endpoint ${endpoint}`}`,
-        empty: endpoint === undefined
-            ? "This project has no schedules yet."
-            : "No schedule delivers to that destination.",
+        command: `${runtime.programName} schedules list${endpoint === undefined ? "" : ` --endpoint ${endpoint}`}${correlationCommand(args)}`,
+        // An empty filtered page answers the filter, not the project: "no
+        // schedules yet" read as the project being empty when nothing matched.
+        empty: Object.keys(filters).length > 0
+            ? "No schedule matches these filters."
+            : endpoint === undefined
+                ? "This project has no schedules yet."
+                : "No schedule delivers to that destination.",
         read: (request) => page("schedules.list", () => active.client.request("schedules_list", {
             ...request,
             ...(endpoint === undefined ? {} : { endpoint }),
+            ...filters,
         })),
         row: (schedule) => [
             schedule.status,
@@ -735,6 +782,16 @@ const billing = async (runtime, args) => {
             ...(view.trialExpiresAt === undefined
                 ? []
                 : [`Trial ends   ${view.trialExpiresAt}`]),
+            ...(view.credit.byKind === undefined
+                ? []
+                : ["purchased", "trial", "promotional"].flatMap((kind) => {
+                    const balance = view.credit.byKind[kind];
+                    return balance.granted.microdollars === "0"
+                        ? []
+                        : [
+                            `${kind.padEnd(12)} ${money(balance.available)} available, ${money(balance.reserved)} reserved, ${money(balance.consumed)} used${balance.forfeited.microdollars === "0" ? "" : `, ${money(balance.forfeited)} expired`}${balance.expiresAt === undefined ? "" : `; ends ${balance.expiresAt}`}`,
+                        ];
+                })),
             ...(view.activation.mode === "shadow" || view.blockingReasons.length === 0
                 ? []
                 : [`Blocked      ${view.blockingReasons.join(", ")}`]),
@@ -1050,6 +1107,63 @@ const billingAutoTopUpApply = async (runtime, args) => {
         data: { confirmation, idempotencyKey: key, ...view },
     };
 };
+function promotionGrantLine(grant) {
+    const benefit = grant.benefit;
+    const what = benefit.kind === "credit"
+        ? `${money(benefit.amount)} promotional credit`
+        : benefit.kind === "project-slot"
+            ? `complimentary project ${benefit.project}`
+            : benefit.kind === "perk"
+                ? `perk ${benefit.perk}`
+                : `${benefit.percentOff !== undefined ? `${String(benefit.percentOff)}%` : money(benefit.amountOff)} off project fees, ${benefit.duration === "once" ? "one invoice" : `${String(benefit.durationInMonths)} invoices`}`;
+    return `${grant.id}: ${what} (${grant.state}, from ${grant.source}${grant.endsAt === undefined ? "" : `, ends ${grant.endsAt}`}${grant.revokedAt === undefined ? "" : `, revoked ${grant.revokedAt}`})`;
+}
+function promotionsLines(view) {
+    return [
+        `Projects: ${String(view.projectCapacity.included)} included, ${String(view.projectCapacity.paid)} paid, ${String(view.projectCapacity.complimentary)} complimentary`,
+        ...(view.grants.length === 0
+            ? ["No promotions."]
+            : view.grants.map(promotionGrantLine)),
+        ...view.restrictions,
+    ];
+}
+const billingPromotions = async (runtime, args) => {
+    const active = await session(runtime, args);
+    const view = parseResponse("billing.promotions", await active.client.request("billing_promotions"));
+    return { data: view, human: promotionsLines(view).join("\n") };
+};
+const billingRedeem = async (runtime, args) => {
+    const parsed = billingRedeemRequestSchema.safeParse({
+        code: positionals(args, ["<code>"], `${runtime.programName} billing redeem <code> [--target-project <project-id>]`)[0],
+        confirmed: true,
+        ...(args.options["--target-project"] === undefined
+            ? {}
+            : { project: args.options["--target-project"] }),
+    });
+    if (!parsed.success)
+        throw new CliError("Provide the code, and --target-project when the code covers a project.", "usage");
+    const confirmation = await confirmChange(runtime, args, {
+        action: "Redeem this promotion code for your organization.",
+        effect: [
+            ...(parsed.data.project === undefined
+                ? []
+                : [`project ${parsed.data.project}`]),
+            "Nothing is charged. Promotional value expires, has no cash value and cannot be refunded.",
+        ],
+    });
+    const active = await session(runtime, args);
+    const key = idempotencyKey(runtime, args);
+    const view = parseResponse("billing.redeem", await active.client.request("billing_redeem", parsed.data, {
+        "Idempotency-Key": key,
+    }));
+    return {
+        data: { confirmation, idempotencyKey: key, ...view },
+        human: [
+            `Redeemed ${promotionGrantLine(view.grant)}`,
+            ...promotionsLines(view.promotions),
+        ].join("\n"),
+    };
+};
 const billingRefundRequest = async (runtime, args) => {
     const parsed = billingRefundRequestCreateSchema.safeParse({
         amount: budgetMoney(args, "--amount"),
@@ -1139,8 +1253,13 @@ function projectBillingResult(view) {
         human: [
             `Monthly project fees ${money(view.recurringProjectFees)}`,
             `Policy desired r${String(view.desiredRevision)}, effective r${String(view.effectiveRevision)}${view.pending ? " (pending)" : ""}`,
-            ...view.projects.map((project) => `${project.name} (${project.project}): ${project.access}${project.paidThroughAt ? `, paid through ${project.paidThroughAt}` : ""}${project.cancellationAt ? `, cancels ${project.cancellationAt}` : ""}${project.renewalGraceUntil ? `, renewal grace until ${project.renewalGraceUntil}` : ""}`),
+            ...view.projects.map((project) => `${project.name} (${project.project}): ${project.complimentary ? `complimentary until ${project.complimentary.endsAt}` : project.access}${project.paidThroughAt ? `, paid through ${project.paidThroughAt}` : ""}${project.cancellationAt ? `, cancels ${project.cancellationAt}` : ""}${project.renewalGraceUntil ? `, renewal grace until ${project.renewalGraceUntil}` : ""}`),
             ...view.pendingOperations.map((operation) => `${operation.project}: ${operation.state}${operation.reason ? ` (${operation.reason})` : ""}${operation.paymentUrl ? ` ${operation.paymentUrl}` : ""}`),
+            ...(view.discount === undefined
+                ? []
+                : [
+                    `Discount ${view.discount.percentOff !== undefined ? `${String(view.discount.percentOff)}% off` : `${money(view.discount.amountOff)} off`} ${view.discount.duration === "once" ? "one invoice" : `${String(view.discount.durationInMonths)} monthly invoices`} (${view.discount.state})`,
+                ]),
         ].join("\n"),
     };
 }
@@ -1151,6 +1270,11 @@ const billingProjects = async (runtime, args) => {
 function projectQuoteLines(quote) {
     return [
         `Project ${quote.project}${quote.fromProject ? `; former included ${quote.fromProject}` : ""}`,
+        ...(quote.discount === undefined
+            ? []
+            : [
+                `Before discount ${money(quote.discount.gross)}; discount ${money(quote.discount.amount)} for ${quote.discount.duration === "once" ? "this invoice" : `${String(quote.discount.durationInMonths)} monthly invoices`}`,
+            ]),
         `Charge ${money(quote.charge)}; monthly project fees ${money(quote.monthlyProjectFees)}`,
         `Effective ${quote.effectiveAt}; quote expires ${quote.expiresAt}`,
         ...(quote.formerIncludedWillBlock
@@ -1730,6 +1854,8 @@ export const OPERATE_COMMANDS = {
     "billing notification-settings": billingNotificationSettings,
     "billing update-notifications": billingNotificationSettingsUpdate,
     "billing ledger": billingLedger,
+    "billing promotions": billingPromotions,
+    "billing redeem": billingRedeem,
     "billing projects": billingProjects,
     "billing purchase": billingPurchase,
     "billing quote-funding": billingQuoteFunding,
@@ -1760,6 +1886,7 @@ export const OPERATE_COMMANDS = {
     "schedules archive": schedulesArchive,
     "schedules cancel": schedulesCancel,
     "schedules list": schedulesList,
+    "executions list": executionsList,
     "schedules pause": schedulesPause,
     "schedules replace": schedulesReplace,
     "schedules resume": schedulesResume,

package/package.json

@@ -7,8 +7,8 @@
     "url": "https://github.com/flowxo/greatwait/issues"
   },
   "dependencies": {
-    "@greatwait/api-client": "0.2.1",
-    "@greatwait/contracts": "0.2.1"
+    "@greatwait/api-client": "0.2.3",
+    "@greatwait/contracts": "0.2.3"
   },
   "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.2.1"
+  "version": "0.2.3"
 }