@letterstory/cli 0.176.98 → 0.176.100

package/lib/cli.mjs

@@ -87,7 +87,7 @@ import {
 import { fetchParkedSections, withoutParked } from "./parked.mjs";
 
 // Matches cli/package.json; publish-cli.yml rewrites both to the published version.
-export const VERSION = "0.176.98";
+export const VERSION = "0.176.100";
 
 /** The exit code for a gate refusal (CARD_REQUIRED, PAYMENT_FAILED, OUT_OF_TOKENS): 1 is a plain error. */
 export const EXIT_PAYMENT_REQUIRED = 3;
@@ -119,6 +119,8 @@ export const BOOLEAN_FLAGS = new Set([
 	"no-disclosure",
 	// replicate show: list only the pages below the bar.
 	"failing",
+	// replicate forms: read the site's forms key (admins) instead of its submissions.
+	"show-key",
 	// sim create / resample / sample-key: keep the customer's sample key, or delete it now.
 	"keep-key",
 	"delete-key",
@@ -1990,6 +1992,7 @@ Domains (the domains you hold, and free ones that match what people search):
 Vary (A/B tests of a page's words and images on your own site):
   vary [list] [--status running] [--site <id>]         Your variationals and how many visitors each has seen
   vary create --page <url> [--name <n>] [--goals-file <path>]
+  vary launch [--brief <words>] [--page <url>]         An A/B test Letter writes from the page and starts
   vary get <id>                                        Variants, their changes, and the results against the original
   vary page <id>                                       The page's copy as changes need it, and whether each variant still applies
   vary save-variant <id> --deltas-file <path> [--key b] [--name <n>]
@@ -2069,6 +2072,9 @@ Replicate (the Replicator: a website rebuilt as a native Next.js repo, page for
                                                        --again replicates from the start; --preview deploys its staging link again;
                                                        --extend-preview keeps the preview up longer (Letter's team only)
   replicate archive <id>                               Stop it and take its preview down; the project stays in storage and in the repo
+  replicate forms [<id>] [--form <f>] [--limit <n>] [--before <iso>]
+                                                       What people sent through the replicated sites' forms, newest first;
+                                                       --show-key (admins): LETTER_FORMS_URL and LETTER_FORMS_KEY to host it yourself
 
 Evals (how the pipeline is doing on your posts, and the regression cases captured from them):
   evals scoreboard [--collection <id>] [--days N]      Every measure by stage: posts, failing, rate

package/lib/commands/replicate.mjs

@@ -3,8 +3,8 @@
 // Who may use it is one switch in the app (lib/replicator/access.ts): until it opens, the tools answer
 // only a key an @letterstory.com person made. Free, within fair-use limits. Thin wrappers over the
 // replicator tools (create_replication, list_replications, get_replication,
-// attach_replication_repo, advance_replication, archive_replication), the same lib functions the
-// app calls.
+// attach_replication_repo, advance_replication, archive_replication, list_form_submissions), the
+// same lib functions the app calls.
 //
 //   letterstory replicate https://example.com [--max-pages 300] [--refine-budget 25] [--repo-name example-site] [--repo-owner <account>]
 //   letterstory replicate list
@@ -12,6 +12,8 @@
 //   letterstory replicate attach <id> <repo-name> [--repo-owner <account>]
 //   letterstory replicate advance <id> [--retry] [--again] [--preview] [--extend-preview <days>]
 //   letterstory replicate archive <id>
+//   letterstory replicate forms [<id>] [--form <form>] [--limit <n>] [--before <iso>]
+//   letterstory replicate forms <id> --show-key  (admins: LETTER_FORMS_URL and LETTER_FORMS_KEY to host it yourself)
 
 import { CliError } from "../client.mjs";
 import { argsFromFlags, printResult, refuseUnknownFlags } from "./shared.mjs";
@@ -44,6 +46,13 @@ export const ARGS = {
 		extend_preview_days: { flag: "extend-preview", type: "num" },
 	},
 	archive_replication: { replication_id: replicationId },
+	get_replication_forms_key: { replication_id: replicationId },
+	list_form_submissions: {
+		replication_id: { positional: 0, label: "replication-id" },
+		form: "form",
+		limit: { flag: "limit", type: "num" },
+		before: "before",
+	},
 };
 
 function call(ctx, tool) {
@@ -75,8 +84,15 @@ export async function cmdReplicate(ctx) {
 			return replicationShow(rest, await call(rest, "advance_replication"));
 		case "archive":
 			return replicationShow(rest, await call(rest, "archive_replication"));
+		case "forms":
+			if (rest.flags["show-key"] === true) {
+				refuseUnknownFlags(rest, ARGS.get_replication_forms_key, ["show-key"]);
+				return formsKey(rest, await call(rest, "get_replication_forms_key"));
+			}
+			refuseUnknownFlags(rest, ARGS.list_form_submissions, []);
+			return formSubmissions(rest, await call(rest, "list_form_submissions"));
 		default:
-			throw new CliError("Usage: replicate <https://site> | replicate [list|show|attach|advance|archive]");
+			throw new CliError("Usage: replicate <https://site> | replicate [list|show|attach|advance|archive|forms]");
 	}
 }
 
@@ -201,6 +217,37 @@ function previewLines(x) {
 	return [];
 }
 
+// The two values the site's forms send to Letter with, to set where it is hosted (never in its repo).
+function formsKey(ctx, result) {
+	printResult(ctx.io, ctx.flags, result, (r) =>
+		[
+			`LETTER_FORMS_URL=${r.url}`,
+			`LETTER_FORMS_KEY=${r.secret_key}`,
+			"",
+			"Set these where the site is hosted, the key as a secret. Never commit the key.",
+		].join("\n")
+	);
+	return 0;
+}
+
+// What people sent through the replicated sites' forms (Letter's default destination), newest first.
+function formSubmissions(ctx, result) {
+	printResult(ctx.io, ctx.flags, result, (r) => {
+		if (!r.submissions?.length) return "No form submissions yet.";
+		const lines = [];
+		for (const s of r.submissions) {
+			lines.push(
+				`${s.received_at}  ${s.host}${s.page ?? ""}  ${s.form_name ?? s.form}${s.notified ? "" : `  (not emailed${s.notify_error ? `: ${s.notify_error}` : ""})`}`
+			);
+			for (const [name, value] of Object.entries(s.fields))
+				lines.push(`    ${name}: ${Array.isArray(value) ? value.join(", ") : value}`);
+		}
+		if (r.next_before) lines.push("", `More: replicate forms --before ${r.next_before}`);
+		return lines.join("\n");
+	});
+	return 0;
+}
+
 function replicationShow(ctx, result) {
 	printResult(ctx.io, ctx.flags, result, (r) =>
 		[...headline(r.replication), ...(r.notice ? [`  Note    ${r.notice}`] : []), ...limitsLines(r.limits)].join(

package/lib/commands/vary.mjs

@@ -1,10 +1,12 @@
 // `vary` — Variationals from a terminal: A/B tests of a page's words and images on your own site
 // (docs/architecture/variationals.md). Thin wrappers over the variationals tools (list_variationals,
-// get_variational, create_variational, update_variational, save_variational_variant,
+// get_variational, create_variational, launch_variational_test, update_variational, save_variational_variant,
 // remove_variational_variant, delete_variational, ship_variational_winner), the same lib functions the app calls.
 //
 //   letterstory vary list [--status running]
 //   letterstory vary create --page https://acme.com/pricing [--name "Pricing headline"] [--goals-file goals.json]
+//   letterstory vary launch [--brief "Test the hero button"] [--page https://acme.com/] [--name <n>]
+//     made, given a challenger Letter writes from the page, and started (Ideas' A/B test row)
 //   letterstory vary get <id>
 //   letterstory vary page <id>          the page's blocks, as a change's tag/before/occurrence
 //   letterstory vary save-variant <id> --deltas-file b.json [--key b] [--name "Shorter headline"]
@@ -74,6 +76,12 @@ export const ARGS = {
 		name: "name",
 		goals: jsonFile("goals-file", "goals"),
 	},
+	launch_variational_test: {
+		brief: "brief",
+		page_url: "page",
+		site_id: "site",
+		name: "name",
+	},
 	ship_variational_winner: {
 		variational_id: variationalId,
 		variant: "variant",
@@ -135,6 +143,12 @@ export async function cmdVary(ctx) {
 		case "create":
 			refuseUnknownFlags(rest, ARGS.create_variational, ["goals-file"]);
 			return varyShow(rest, await call(rest, "create_variational"));
+		case "launch": {
+			refuseUnknownFlags(rest, ARGS.launch_variational_test, []);
+			const result = await call(rest, "launch_variational_test");
+			printResult(rest.io, rest.flags, result, (r) => `${r.message}\n${r.variational.edit_url}`);
+			return 0;
+		}
 		case "update":
 		case "weights":
 		case "goals":
@@ -170,7 +184,7 @@ export async function cmdVary(ctx) {
 		}
 		default:
 			throw new CliError(
-				"Usage: vary [list|get|page|create|update|weights|goals|start|pause|end|save-variant|remove-variant|ship|delete]"
+				"Usage: vary [list|get|page|create|launch|update|weights|goals|start|pause|end|save-variant|remove-variant|ship|delete]"
 			);
 	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@letterstory/cli",
-	"version": "0.176.98",
+	"version": "0.176.100",
 	"description": "Spin up and manage Letter phantom blogs from your terminal.",
 	"type": "module",
 	"license": "UNLICENSED",