@letterstory/cli 0.145.2 → 0.146.0

package/lib/cli.mjs

@@ -64,13 +64,16 @@ import {
 } from "./commands.mjs";
 
 // Matches cli/package.json; publish-cli.yml rewrites both to the published version.
-export const VERSION = "0.145.2";
+// Matches cli/package.json; publish-cli.yml rewrites both to the published version.
+export const VERSION = "0.146.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
 // `negate` spelling) in a command's ARGS map must be listed; boolean-flags.test.ts enforces it.
 export const BOOLEAN_FLAGS = new Set([
 	"remap",
+	// login: one-link device sign-in instead of the loopback browser flow.
+	"device",
 	"json",
 	// sim seed: make the new seed active; collections it doesn't cover start empty.
 	"activate",
@@ -366,6 +369,7 @@ Usage:
 
 Auth:
   login [--url <url>]                Sign in via your browser (default url: https://app.letterstory.com)
+  login --device [--url <url>]       Sign in with one link, opened in any browser (for agents and remote shells)
   login --key <ls_…> [--url <url>]   Save a static API key instead (for CI/automation)
   logout                             Forget saved credentials (revokes an OAuth session, if any)
   config                             Show the resolved url + credential source
@@ -932,6 +936,7 @@ Admin (STAFF key — --staff-key / LETTERSTORY_STAFF_API_KEY; acts before an org
           | 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]
+          | cap <org-id> <dollars|off> [--why "…"]
                                                        Usage billing on Lago: the plan catalog, an org's
                                                        plan and gifted ratio, Lago's tokens against ours,
                                                        forwarding usage now, failed payments and the
@@ -1089,6 +1094,10 @@ Seers (event-driven signals -> drafts):
   org export --split <dir>                             …as one file per record (for keeping config in git)
   org join <dir> [--file <path>]                       Rebuild the bundle from a --split directory
   org integrations                                     Every integration and whether it's connected
+  org billing [cap <dollars|off> [--why "…"] | request [--note "…"]]
+                                                       Usage billing: plan, this period against the
+                                                       allowance and spend cap, failed payments; set
+                                                       the cap (admins) or ask the admins for more
   org linear [teams [--team <id|key>] | set --team <id|key> [--project <id>|none] | disconnect]
                                                        Where Letter files Linear issues (connect in Settings)
   org diff <file|dir>                                  What applying a bundle would change (reads only)

package/lib/commands/admin.mjs

@@ -5089,7 +5089,8 @@ const LAGO_USAGE = `Usage: admin billing lago <command>
   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`;
+  signups [--status open|card_saved|provisioned|paid|abandoned]   new paying orgs on their way onto Lago
+  cap <org-id> <dollars|off> [--why "…"]  set an account's monthly spend cap on overage (off: no cap)`;
 
 /** admin billing lago … — staff operations on Lago (docs/billing/lago-integration.md). */
 async function cmdAdminBilling(ctx) {
@@ -5212,6 +5213,27 @@ async function cmdAdminBilling(ctx) {
 			);
 			return 0;
 		}
+		case "cap": {
+			const orgId = positionals[2];
+			const value = positionals[3];
+			if (!orgId || value === undefined) throw new CliError(LAGO_USAGE);
+			const off = ["off", "none", "null"].includes(value.toLowerCase());
+			const capUsd = off ? null : Number(value.replace(/^\$/, ""));
+			if (capUsd !== null && (!Number.isFinite(capUsd) || capUsd < 0))
+				throw new CliError(`Not a cap: ${value}. Give dollars (0 stops at the allowance) or off.`);
+			const result = await staffRequest(
+				ctx,
+				"POST",
+				`${LAGO}/cap`,
+				compact({ orgId, cap_usd: capUsd, reason: flagStr(flags.why) })
+			);
+			printResult(io, flags, result, (r) =>
+				r.spendCap
+					? `Spend cap: $${r.spendCap.usd} of overage a month (alerts: ${r.alert}).`
+					: "No spend cap: overage is on."
+			);
+			return 0;
+		}
 		default:
 			throw new CliError(LAGO_USAGE);
 	}

package/lib/commands/auth.mjs

@@ -8,7 +8,7 @@
 
 import { LetterstoryClient, resolveConfig, writeConfigFile, clearConfigFile, configPath } from "../client.mjs";
 import { flagStr } from "./shared.mjs";
-import { browserLogin, revokeToken } from "../oauth.mjs";
+import { browserLogin, deviceLogin, revokeToken } from "../oauth.mjs";
 
 export async function cmdLogin(ctx) {
 	const { flags, io } = ctx;
@@ -39,7 +39,7 @@ export async function cmdLogin(ctx) {
 		}
 	}
 
-	const tokens = await browserLogin({ url, io });
+	const tokens = flags.device ? await deviceLogin({ url, io }) : await browserLogin({ url, io });
 	const oauth = {
 		access_token: tokens.access_token,
 		refresh_token: tokens.refresh_token,

package/lib/commands/org.mjs

@@ -28,6 +28,11 @@ export const ARGS = {
 	describe_org_config_fields: {},
 	get_org_config_source: {},
 	get_billing_payments: {},
+	set_billing_spend_cap: {
+		cap_usd: { value: (_flags, positionals) => capFrom(requirePositional(positionals, 0, "dollars|off")) },
+		reason: { flag: "why" },
+	},
+	request_billing_tokens: { note: { flag: "note" } },
 	list_integrations: {},
 	get_linear_connection: {},
 	list_linear_targets: { team_id: { flag: "team" } },
@@ -90,9 +95,45 @@ 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). */
+/** A cap from the command line: dollars, or `off` (no cap). */
+function capFrom(value) {
+	if (["off", "none", "null"].includes(String(value).toLowerCase())) return null;
+	const usd = Number(String(value).replace(/^\$/, ""));
+	if (!Number.isFinite(usd) || usd < 0)
+		throw new CliError(`Not a cap: ${value}. Give dollars (0 stops at the allowance) or off.`);
+	return usd;
+}
+
+const usd = (n) => `$${Number(n).toFixed(2)}`;
+
+/**
+ * `org billing`: the org's plan on Lago, this period against its allowance and spend cap, whether
+ * it is past due, and its failed payments (get_billing_payments). `org billing cap <dollars|off>`
+ * sets the cap (set_billing_spend_cap, admins); `org billing request` asks the admins for more
+ * (request_billing_tokens).
+ */
 async function orgBilling(ctx) {
-	const { client, flags, io } = ctx;
+	const { client, flags, io, positionals } = ctx;
+	if (positionals[0] === "cap") {
+		refuseUnknownFlags(ctx, ARGS.set_billing_spend_cap, []);
+		const args = argsFromFlags(ARGS.set_billing_spend_cap, flags, positionals.slice(1));
+		const result = await client.callTool("set_billing_spend_cap", args);
+		printResult(io, flags, result, (r) =>
+			r.spendCap
+				? `Spend cap: ${usd(r.spendCap.usd)} of overage a month${r.spendCap.usd === 0 ? " (work stops at the allowance)" : ""}.${r.alert === "failed" ? " The alerts couldn't be moved; the cap holds." : ""}`
+				: "No spend cap: overage is on."
+		);
+		return 0;
+	}
+	if (positionals[0] === "request") {
+		refuseUnknownFlags(ctx, ARGS.request_billing_tokens, []);
+		const result = await client.callTool(
+			"request_billing_tokens",
+			argsFromFlags(ARGS.request_billing_tokens, flags, [])
+		);
+		printResult(io, flags, result, (r) => `Asked ${r.emailedTo} admin${r.emailedTo === 1 ? "" : "s"} for more.`);
+		return 0;
+	}
 	refuseUnknownFlags(ctx, {}, []);
 	const result = await client.callTool("get_billing_payments", {});
 	printResult(io, flags, result, (r) =>
@@ -100,6 +141,16 @@ async function orgBilling(ctx) {
 			r.plan
 				? `Plan: ${r.plan.name}${r.plan.ratio !== 1 ? ` (${r.plan.ratio}x)` : ""}`
 				: "Not billed by usage yet.",
+			...(r.usage
+				? [
+						`This period (${r.usage.periodFrom.slice(0, 10)} to ${r.usage.periodTo.slice(0, 10)}): ${r.usage.usedTokens} of ${r.usage.allowanceTokens} tokens included${r.usage.overageUsd > 0 ? `, ${usd(r.usage.overageUsd)} of overage` : ""}.`,
+					]
+				: []),
+			r.spendCap
+				? `Spend cap: ${usd(r.spendCap.usd)} of overage a month${r.usage?.availableTokens != null ? `, ${Math.max(0, r.usage.availableTokens)} tokens left under it` : ""}.`
+				: r.plan
+					? "No spend cap: overage is on."
+					: null,
 			...(r.pastDueAt ? [`Past due since ${r.pastDueAt}.`] : []),
 			...(r.payments.length
 				? r.payments.map(
@@ -107,7 +158,9 @@ async function orgBilling(ctx) {
 							`  ${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")
+		]
+			.filter((line) => line !== null)
+			.join("\n")
 	);
 	return 0;
 }

package/lib/oauth.mjs

@@ -186,6 +186,71 @@ export async function browserLogin({ url, io, fetchImpl = globalThis.fetch }) {
 	}
 }
 
+export const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+
+// RFC 8628 device sign-in: for a CLI whose browser is somewhere else (a cloud agent, a remote
+// box). Prints one link for the person to open and Allow, then polls /token until they do.
+export async function deviceLogin({
+	url,
+	io,
+	fetchImpl = globalThis.fetch,
+	sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+}) {
+	const base = url.replace(/\/+$/, "");
+	const endpoint = `${base}/api/oauth/device_authorization`;
+	let res;
+	try {
+		res = await fetchImpl(endpoint, {
+			method: "POST",
+			headers: { "content-type": "application/x-www-form-urlencoded" },
+			body: new URLSearchParams({ client_id: CLIENT_ID }).toString(),
+		});
+	} catch (err) {
+		throw new CliError(`Could not reach ${endpoint}: ${err.message}`);
+	}
+	const start = await res.json().catch(() => null);
+	if (!res.ok || !start?.device_code) {
+		const detail = start?.error_description || start?.error || `HTTP ${res.status}`;
+		throw new CliError(`Login failed: ${detail}`);
+	}
+
+	io.log(`Open this link, pick the organization and click Allow:\n  ${start.verification_uri_complete}\n`);
+	io.log(`Code: ${start.user_code} (the page shows the same one)`);
+	io.log("Waiting for approval…");
+
+	let intervalMs = (start.interval ?? 5) * 1000;
+	const deadline = Date.now() + (start.expires_in ?? 600) * 1000;
+	while (Date.now() < deadline) {
+		await sleep(intervalMs);
+		let poll;
+		try {
+			poll = await fetchImpl(`${base}/api/oauth/token`, {
+				method: "POST",
+				headers: { "content-type": "application/x-www-form-urlencoded" },
+				body: new URLSearchParams({
+					grant_type: DEVICE_GRANT_TYPE,
+					client_id: CLIENT_ID,
+					device_code: start.device_code,
+				}).toString(),
+			});
+		} catch {
+			continue;
+		}
+		const json = await poll.json().catch(() => null);
+		if (poll.ok && json?.access_token) return json;
+		const error = json?.error;
+		if (error === "authorization_pending") continue;
+		if (error === "slow_down") {
+			intervalMs += 5000;
+			continue;
+		}
+		if (error === "access_denied") throw new CliError("Sign-in was cancelled in the browser.");
+		if (error === "expired_token") throw new CliError("The link expired. Run `login --device` again.");
+		throw new CliError(`Login failed: ${json?.error_description || error || `HTTP ${poll.status}`}`);
+	}
+	throw new CliError("The link expired before it was approved. Run `login --device` again.");
+}
+
 export async function refreshAccessToken({ url, refreshToken, fetchImpl = globalThis.fetch }) {
 	return tokenRequest(
 		url,

package/package.json

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