@letterstory/cli 0.142.0 → 0.143.0

package/README.md

@@ -481,6 +481,7 @@ letterstory admin crm onboarding <account-id>          # step-by-step progress (
 letterstory admin crm retry-onboarding <onboarding-id> # re-run only the failed steps
 letterstory admin crm onboard-plan <account-id>        # what the calls say: sites, Slack/app people, paid?
 letterstory admin crm payment-link <account-id>        # Stripe Payment Link at the deal amount (billing:write)
+letterstory admin crm payment-link <account-id> --plan growth   # with Lago signups on: a card-only start link, Lago bills the plan
 ```
 
 `onboard` runs org → link → phantom sites → Slack channel → checklist → app invites →
@@ -490,7 +491,10 @@ disclosure ("safe mode") for that site, and `--disclose-note "…"` records the
 as the reason; `onboard-plan` flags the sites whose calls asked for it. `onboard-plan` reads the account's recorded calls
 (newest first, cached per set of calls; `--refresh` re-reads) and says how many sites, what each
 is about, who to invite, and whether they've paid. `payment-link` stamps the account's org on
-the Stripe subscription, so paying through it binds and marks the account paid by itself.
+the Stripe subscription, so paying through it binds and marks the account paid by itself. With
+Lago signups on (`LETTERBRACE_LAGO_SIGNUP`), it is a start link of ours instead: the client saves a
+card, Lago charges the plan (`--plan`, default the one priced at the deal amount; `--ratio`, `--why`
+as for `admin billing lago provision`), and no Stripe subscription is made. The account needs an org.
 
 Every trigger — Cal.com bookings, Circleback recordings, Letterhome dinner RSVPs, RB2B
 visits, and what an agent records here — goes through one intake (`ingestSignal`,

package/lib/cli.mjs

@@ -64,7 +64,7 @@ import {
 } from "./commands.mjs";
 
 // Keep in sync with cli/package.json.
-export const VERSION = "0.142.0";
+export const VERSION = "0.143.0";
 
 // Flags that never take a value. Listing them explicitly means `deploy get --json <id>`
 // can't accidentally swallow the id as --json's value. Every `type: "bool"` flag (and its
@@ -297,6 +297,9 @@ export const BOOLEAN_FLAGS = new Set([
 	"nested",
 	// admin billing lago catalog --apply --include-drafts
 	"include-drafts",
+	// admin billing lago payments --open / payments run --dry
+	"open",
+	"dry",
 ]);
 
 // Tiny argv parser: `--flag value`, `--flag=value`, boolean `--flag`, and positionals.
@@ -926,10 +929,14 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
   admin billing lago catalog [--apply] [--include-drafts]
           | provision <org-id> --plan starter|growth|scale [--ratio 1|2|4|8 (8 needs --why "…")] [--complimentary N] [--stripe-customer cus_…] [--start ISO] [--review D]
           | reconcile [--org <org-id>] | forward
+          | payments [--org <org-id>] [--open] | payments retry <lago-invoice-id> | payments run [--dry]
+          | signups [--status open|card_saved|provisioned|paid|abandoned]
                                                        Usage billing on Lago: the plan catalog, an org's
                                                        plan and gifted ratio, Lago's tokens against ours,
-                                                       and forwarding usage now. Needs spend:read (reads)
-                                                       / billing:write (writes).
+                                                       forwarding usage now, failed payments and the
+                                                       retry loop, and new signups on their way onto
+                                                       Lago. Needs spend:read (reads) / billing:write
+                                                       (writes).
   admin crm import <file.csv> [--source <name>] [--tag "…"] [--dry-run]
           | capture [shot.png …] [--text "…" | --text-file f] [--context "this is for acme.com"]
                     [--account <id>] [--dry-run] [--retry]   screenshots / a thread / a note → a lead
@@ -960,7 +967,7 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
                    [--slack a@acme.com,b@acme.com] [--invite a@acme.com[:admin]]… [--no-checklist]
           | onboarding <account-id> | retry-onboarding <onboarding-id>
           | onboard-plan <account-id> [--refresh]
-          | payment-link <account-id> [--amount-cents N] [--description "…"]
+          | payment-link <account-id> [--amount-cents N] [--description "…"] [--plan starter] [--ratio N] [--why "…"]
                                                        The staff CRM's pipeline: bulk-importing a
                                                        CSV of leads, the inbound signal
                                                        feed, recording a signal with no webhook

package/lib/commands/admin.mjs

@@ -3719,14 +3719,24 @@ async function cmdAdminCrm(ctx) {
 		}
 		case "payment-link": {
 			// admin crm payment-link <account-id> [--amount-cents N] [--description "…"] — a Stripe
-			// Payment Link for the monthly subscription (default: the deal amount). The key needs
-			// crm:write + billing:write.
+			// Payment Link for the monthly subscription (default: the deal amount). With Lago signups on,
+			// a start link that saves a card and puts the org on a Lago plan instead: [--plan starter]
+			// (default: the plan priced at the deal) [--ratio 2] [--why "…" under the price floor].
+			// The key needs crm:write + billing:write.
 			if (!id)
-				throw new CliError('Usage: admin crm payment-link <account-id> [--amount-cents N] [--description "…"]');
+				throw new CliError(
+					'Usage: admin crm payment-link <account-id> [--amount-cents N] [--description "…"] [--plan starter] [--ratio 1|2|4|8] [--why "…"]'
+				);
 			const r = await staffPost(
 				ctx,
 				`${CRM}/accounts/${id}/payment-link`,
-				compact({ amountCents: flagNum(flags["amount-cents"]), description: flagStr(flags.description) })
+				compact({
+					amountCents: flagNum(flags["amount-cents"]),
+					description: flagStr(flags.description),
+					planCode: flagStr(flags.plan),
+					ratio: flagNum(flags.ratio),
+					exceptionReason: flagStr(flags.why),
+				})
 			);
 			return out(
 				r,
@@ -5001,7 +5011,11 @@ const LAGO_USAGE = `Usage: admin billing lago <command>
   catalog [--apply] [--include-drafts]   what the plan catalog would change in Lago; --apply makes it so
   provision <org-id> --plan starter [--ratio 4] [--why "…" above 4x] [--complimentary 20000] [--stripe-customer cus_…] [--start 2026-11-02T00:00:00Z] [--review 2027-05-01]
   reconcile [--org <org-id>]             Lago's tokens this period against what we rated and forwarded
-  forward                                forward billable usage to Lago now (the cron's pass)`;
+  forward                                forward billable usage to Lago now (the cron's pass)
+  payments [--org <org-id>] [--open]     failed payments and what the retry loop did about each
+  payments retry <lago-invoice-id>       charge one failed invoice again now
+  payments run [--dry]                   one pass of the failed-payment loop now (--dry: report only)
+  signups [--status open|card_saved|provisioned|paid|abandoned]   new paying orgs on their way onto Lago`;
 
 /** admin billing lago … — staff operations on Lago (docs/billing/lago-integration.md). */
 async function cmdAdminBilling(ctx) {
@@ -5066,6 +5080,64 @@ async function cmdAdminBilling(ctx) {
 			printResult(io, flags, result);
 			return 0;
 		}
+		case "payments": {
+			const action = positionals[2];
+			if (action === "retry") {
+				const invoiceId = requirePositional(positionals, 3, "lago-invoice-id");
+				const result = await staffPost(ctx, `${LAGO}/payments/retry`, { invoiceId });
+				ok(ctx, `Charging ${invoiceId} again; the loop reads the result within the hour.`);
+				printResult(io, flags, result);
+				return 0;
+			}
+			if (action === "run") {
+				const result = await staffPost(
+					ctx,
+					`${LAGO}/payments/run`,
+					compact({ dry: flagBool(flags.dry) || undefined })
+				);
+				ok(
+					ctx,
+					result.mode === "dry"
+						? `Would: ${result.actions.length ? result.actions.join("; ") : "nothing"}.`
+						: `Opened ${result.opened}, resolved ${result.resolved}, emailed ${result.emails}, retried ${result.retries}, gave up ${result.gaveUp}.`
+				);
+				printResult(io, flags, result);
+				return result.errors?.length ? 1 : 0;
+			}
+			if (action !== undefined) throw new CliError(LAGO_USAGE);
+			const params = new URLSearchParams(
+				compact({ orgId: flagStr(flags.org), open: flagBool(flags.open) ? "true" : undefined })
+			);
+			const result = await staffRequest(ctx, "GET", `${LAGO}/payments${params.size ? `?${params}` : ""}`);
+			printResult(io, flags, result, (r) =>
+				[
+					`Failed-payment loop: ${r.mode}`,
+					...(r.payments.length
+						? r.payments.map(
+								(p) =>
+									`  ${p.invoiceNumber ?? p.invoiceId}  ${p.orgName ?? p.orgId}  $${(p.amountCents / 100).toFixed(2)}  ${p.status}  tries ${p.attempts}, emails ${p.emailsSent}${p.nextAttemptAt ? `, next ${p.nextAttemptAt}` : ""}${p.lastError ? `  (${p.lastError})` : ""}`
+							)
+						: ["  No failed payments."]),
+				].join("\n")
+			);
+			return 0;
+		}
+		case "signups": {
+			const params = new URLSearchParams(compact({ status: flagStr(flags.status) }));
+			const result = await staffRequest(ctx, "GET", `${LAGO}/signups${params.size ? `?${params}` : ""}`);
+			printResult(io, flags, result, (r) =>
+				[
+					`Lago signups: ${r.active ? "on" : "off"}${r.from ? ` (from ${r.from})` : ""}`,
+					...(r.signups.length
+						? r.signups.map(
+								(x) =>
+									`  ${x.orgName ?? x.orgId}  ${x.planCode}${x.ratio !== 1 ? ` ${x.ratio}x` : ""}  ${x.status}  ${x.source}${x.lastError ? `  (${x.lastError})` : ""}`
+							)
+						: ["  None."]),
+				].join("\n")
+			);
+			return 0;
+		}
 		default:
 			throw new CliError(LAGO_USAGE);
 	}

package/lib/commands/org.mjs

@@ -27,6 +27,7 @@ export const ARGS = {
 	},
 	describe_org_config_fields: {},
 	get_org_config_source: {},
+	get_billing_payments: {},
 	list_integrations: {},
 	get_linear_connection: {},
 	list_linear_targets: { team_id: { flag: "team" } },
@@ -68,9 +69,11 @@ export async function cmdOrg(ctx) {
 			return orgFields(rest);
 		case "linear":
 			return orgLinear(rest);
+		case "billing":
+			return orgBilling(rest);
 		default:
 			throw new CliError(
-				`Unknown org subcommand: ${sub ?? "(none)"}. Try: export, join, diff, apply, git, integrations, linear, fields`
+				`Unknown org subcommand: ${sub ?? "(none)"}. Try: export, join, diff, apply, git, integrations, linear, fields, billing`
 			);
 	}
 }
@@ -87,6 +90,28 @@ async function orgIntegrations(ctx) {
 	return 0;
 }
 
+/** `org billing`: the org's plan on Lago, whether it is past due, and its failed payments (get_billing_payments). */
+async function orgBilling(ctx) {
+	const { client, flags, io } = ctx;
+	refuseUnknownFlags(ctx, {}, []);
+	const result = await client.callTool("get_billing_payments", {});
+	printResult(io, flags, result, (r) =>
+		[
+			r.plan
+				? `Plan: ${r.plan.name}${r.plan.ratio !== 1 ? ` (${r.plan.ratio}x)` : ""}`
+				: "Not billed by usage yet.",
+			...(r.pastDueAt ? [`Past due since ${r.pastDueAt}.`] : []),
+			...(r.payments.length
+				? r.payments.map(
+						(p) =>
+							`  ${p.invoiceNumber ?? p.invoiceId}  $${(p.amountCents / 100).toFixed(2)}  ${p.status}${p.nextAttemptAt ? `, next try ${p.nextAttemptAt}` : ""}${p.payUrl ? `  pay: ${p.payUrl}` : ""}`
+					)
+				: ["No failed payments."]),
+		].join("\n")
+	);
+	return 0;
+}
+
 /** `org fields [section]`: what each setting in the bundle means (describe_org_config_fields). */
 async function orgFields(ctx) {
 	const { client, flags, io, positionals } = ctx;

package/package.json

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