frontpage-host 0.1.18 → 0.1.20

package/AGENTS.md

@@ -2,6 +2,8 @@
 
 This file ships inside the `frontpage-host` npm package. Prefer it over scraping the product website.
 
+The public CLI operates on Scale, Enterprise, and Internal sites. Site-scoped commands return 403 on lower tiers (`The CLI is included on Scale.`). `frontpage sites` still lists sites the key owner belongs to.
+
 ## Install and invoke
 
 | Item | Value |
@@ -125,7 +127,8 @@ Sites are Astro 6 + Tailwind v4. More detail: `frontpage help site-building` or
 - Media: `frontpage media upload <file>` — images/PDF ≤25 MB, video (MP4/WebM/MOV) ≤50 MB, SVG/text ≤4 MB (sanitizing proxy). Human output prints `sitePath:` first (use that in markup — never raw blob hosts), then optional `url:`. Optional `?w=` on rasters only. **Text/CSV** uploads are inline only — **not** added to the media library and **cannot** be linked via `/__media` (`media upload --json` omits full `content`; use `inbox … --csv` for submission exports).
 - Generated images: `frontpage images generate --prompt "…"` `[--count N]` — one prompt, 1–4 variations of that same picture. Prints `sitePath:` first. Counts against AI $ and storage. Flag-off environments return 404 (`Image generation is not enabled.`). Do not call xAI / Imagine yourself.
 - Analytics: bare `frontpage analytics` = dashboard; also `summary|query|funnel|timeseries|compare|sql` for structured reads (SQL is guard + RLS site-scoped).
-- People: `frontpage people list|get|add|set|note|rm-note|follow-up|hide|unhide`. Site-scoped person graph (email or phone). Inbox stays the raw ledger. Hide is not forget.
+- People CRM: `frontpage people list|get|add|set|note|rm-note|follow-up|hide|unhide|tag|export`. Site-scoped person graph (email or phone). Inbox stays the raw ledger. Hide is not forget. List export is CSV (not a one-person legal dump). Full guide: https://frontpage.host/developers/people
+- Store catalog: `frontpage shop items|variants|categories|settings|orders|payments`. Integer cents only (`$49.99` is `4999`). Stock `--add` / `--remove` become signed delta (`added 5` / `removed 5` / `set to 20` / `stockNow`). Create a category before assigning it (`categories create hats --label Hats`, then `items create … --categories hats`). Connect stays `frontpage modules shop|payments connect`. Square `ordering` is a different module. Full guide: https://frontpage.host/developers/shop
 
 ## Agent prompt loop
 

package/dist/bin.js

@@ -29,6 +29,8 @@ import { runInbox } from "./commands/inbox.js";
 import { runSeo } from "./commands/seo.js";
 import { runRedirects } from "./commands/redirects.js";
 import { runPeople } from "./commands/people.js";
+import { runShop } from "./commands/shop.js";
+import { runMail } from "./commands/mail.js";
 import { runArticles } from "./commands/articles.js";
 import { runSettings } from "./commands/settings.js";
 import { runEdit } from "./commands/edit.js";
@@ -116,6 +118,10 @@ async function main() {
             return runInbox(args);
         case "people":
             return runPeople(args);
+        case "shop":
+            return runShop(args);
+        case "mail":
+            return runMail(args);
         case "seo":
             return runSeo(args);
         case "redirects":

package/dist/commands/mail.d.ts

@@ -0,0 +1 @@
+export declare function runMail(args: string[]): Promise<number>;

package/dist/commands/mail.js

@@ -0,0 +1,482 @@
+import { readFile } from "node:fs/promises";
+import { resolveSlug } from "../site.js";
+import { CliHttpError, EXIT_OK, EXIT_USAGE, exitCodeForError, v1Delete, v1Get, v1Patch, v1Post, v1Put, } from "../http/client.js";
+import { assertNoUnknownFlags, hasFlag, takeFlag } from "../argv.js";
+import { emitErr, emitOk, isJson } from "../runtime.js";
+const USAGE = "Usage: frontpage mail settings|email|template|series|send|sends|enrolments|suppress … [--site <slug>] [--json]";
+const ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function requireId(work, kind) {
+    const fromFlag = takeFlag(work, "--id");
+    const positional = work.find((a) => !a.startsWith("-"));
+    const raw = fromFlag ?? (positional ? work.splice(work.indexOf(positional), 1)[0] : undefined);
+    if (!raw || !ID_RE.test(raw)) {
+        throw new CliHttpError(`${kind} not found.`, EXIT_USAGE, 404, "not_found");
+    }
+    return raw;
+}
+function takeAll(work, name) {
+    const out = [];
+    let v = takeFlag(work, name);
+    while (v !== undefined) {
+        out.push(v);
+        v = takeFlag(work, name);
+    }
+    return out;
+}
+function parseVars(pairs) {
+    const vars = {};
+    for (const pair of pairs) {
+        const eq = pair.indexOf("=");
+        if (eq <= 0)
+            continue;
+        vars[pair.slice(0, eq)] = pair.slice(eq + 1);
+    }
+    return vars;
+}
+function parseRecipients(work) {
+    const tos = takeAll(work, "--to").flatMap((v) => v.split(",").map((s) => s.trim()).filter(Boolean));
+    const name = takeFlag(work, "--name");
+    const vars = parseVars(takeAll(work, "--var"));
+    if (tos.length === 0) {
+        throw new CliHttpError("Usage: --to a@x.com", EXIT_USAGE, 0, "bad_request");
+    }
+    return tos.map((email) => ({
+        email,
+        ...(name ? { name } : {}),
+        ...(Object.keys(vars).length ? { vars } : {}),
+    }));
+}
+async function readJsonFile(path) {
+    const raw = await readFile(path, "utf8");
+    try {
+        const parsed = JSON.parse(raw);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("not an object");
+        }
+        return parsed;
+    }
+    catch {
+        throw new CliHttpError("File must be a JSON object.", EXIT_USAGE, 0, "bad_request");
+    }
+}
+function parseStepFlag(raw) {
+    const parts = raw.split(",").map((s) => s.trim());
+    let templateId = "";
+    let delay = 0;
+    for (const part of parts) {
+        const [k, v] = part.split("=");
+        if (k === "template" || k === "templateId")
+            templateId = v ?? "";
+        if (k === "delay")
+            delay = v ?? 0;
+    }
+    if (!templateId) {
+        throw new CliHttpError("Each --step needs template=<id>.", EXIT_USAGE, 0, "bad_request");
+    }
+    return { templateId, delayMinutes: delay };
+}
+export async function runMail(args) {
+    try {
+        const { slug, rest } = await resolveSlug(args);
+        const group = rest[0];
+        const base = `/api/v1/sites/${encodeURIComponent(slug)}/mail`;
+        if (group === "settings") {
+            const sub = rest[1] ?? "get";
+            const work = rest.slice(2);
+            if (sub === "get") {
+                assertNoUnknownFlags(work, "mail");
+                const data = await v1Get(`${base}/settings`);
+                if (isJson()) {
+                    emitOk("mail", data);
+                    return EXIT_OK;
+                }
+                const s = (data.settings ?? {});
+                console.log(`${s.timezone ?? "UTC"}  ${s.postalLine ?? "(no postal)"}  ${s.replyTo ?? ""}`);
+                return EXIT_OK;
+            }
+            if (sub === "set") {
+                const postal = takeFlag(work, "--postal") ?? takeFlag(work, "--postal-line");
+                const replyTo = takeFlag(work, "--reply-to");
+                const fromName = takeFlag(work, "--from-name");
+                const timezone = takeFlag(work, "--timezone");
+                assertNoUnknownFlags(work, "mail");
+                const data = await v1Patch(`${base}/settings`, {
+                    postalLine: postal,
+                    replyTo,
+                    fromName,
+                    timezone,
+                });
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log("Settings saved.");
+                return EXIT_OK;
+            }
+        }
+        if (group === "email" || group === "template") {
+            const noun = group;
+            const plural = group === "email" ? "emails" : "templates";
+            const sub = rest[1] ?? "list";
+            const work = rest.slice(2);
+            if (sub === "list") {
+                const q = takeFlag(work, "--q");
+                const limit = takeFlag(work, "--limit");
+                const cursor = takeFlag(work, "--cursor");
+                assertNoUnknownFlags(work, "mail");
+                const params = new URLSearchParams();
+                if (q)
+                    params.set("q", q);
+                if (limit)
+                    params.set("limit", limit);
+                if (cursor)
+                    params.set("cursor", cursor);
+                const qs = params.toString();
+                const data = await v1Get(qs ? `${base}/${plural}?${qs}` : `${base}/${plural}`);
+                if (isJson()) {
+                    emitOk("mail", data);
+                    return EXIT_OK;
+                }
+                const rows = data[plural] ?? [];
+                if (rows.length === 0) {
+                    console.log(group === "email" ? "No drafts." : "No templates.");
+                    return EXIT_OK;
+                }
+                for (const row of rows)
+                    console.log(`${row.id}  ${row.name ?? ""}  ${row.subject ?? ""}`);
+                return EXIT_OK;
+            }
+            if (sub === "get") {
+                const id = requireId(work, "Document");
+                assertNoUnknownFlags(work, "mail");
+                const data = await v1Get(`${base}/${plural}/${id}`);
+                if (isJson())
+                    emitOk("mail", data);
+                else {
+                    const doc = (data[noun] ?? data.document);
+                    console.log(`${doc?.id}  ${doc?.subject ?? ""}`);
+                }
+                return EXIT_OK;
+            }
+            if (sub === "create") {
+                const file = takeFlag(work, "--file");
+                const name = takeFlag(work, "--name");
+                const subject = takeFlag(work, "--subject");
+                const preheader = takeFlag(work, "--preheader");
+                assertNoUnknownFlags(work, "mail");
+                if (!file)
+                    throw new CliHttpError("Usage: --file email.json", EXIT_USAGE, 0, "bad_request");
+                const body = await readJsonFile(file);
+                if (name)
+                    body.name = name;
+                if (subject)
+                    body.subject = subject;
+                if (preheader)
+                    body.preheader = preheader;
+                const data = await v1Post(`${base}/${plural}`, body);
+                if (isJson())
+                    emitOk("mail", data);
+                else {
+                    const doc = (data[noun] ?? data.document);
+                    console.log(doc?.id ?? "");
+                }
+                return EXIT_OK;
+            }
+            if (sub === "set") {
+                const id = requireId(work, "Document");
+                const file = takeFlag(work, "--file");
+                const name = takeFlag(work, "--name");
+                const subject = takeFlag(work, "--subject");
+                const preheader = takeFlag(work, "--preheader");
+                assertNoUnknownFlags(work, "mail");
+                const body = file ? await readJsonFile(file) : {};
+                if (name)
+                    body.name = name;
+                if (subject)
+                    body.subject = subject;
+                if (preheader)
+                    body.preheader = preheader;
+                const data = await v1Patch(`${base}/${plural}/${id}`, body);
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log("Saved.");
+                return EXIT_OK;
+            }
+            if (sub === "rm") {
+                const id = requireId(work, "Document");
+                assertNoUnknownFlags(work, "mail");
+                const data = await v1Delete(`${base}/${plural}/${id}`);
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log("Deleted.");
+                return EXIT_OK;
+            }
+            if (sub === "preview") {
+                const id = requireId(work, "Document");
+                assertNoUnknownFlags(work, "mail");
+                const data = await v1Post(`${base}/${plural}/${id}/preview`, {});
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log((data.preview ?? {}).subject ?? "Preview ready.");
+                return EXIT_OK;
+            }
+        }
+        if (group === "series") {
+            const sub = rest[1] ?? "list";
+            const work = rest.slice(2);
+            if (sub === "list") {
+                assertNoUnknownFlags(work, "mail");
+                const data = await v1Get(`${base}/series`);
+                if (isJson()) {
+                    emitOk("mail", data);
+                    return EXIT_OK;
+                }
+                const rows = data.series ?? [];
+                for (const row of rows)
+                    console.log(`${row.id}  ${row.status ?? ""}  ${row.name ?? ""}`);
+                return EXIT_OK;
+            }
+            if (sub === "get") {
+                const id = requireId(work, "Series");
+                assertNoUnknownFlags(work, "mail");
+                const data = await v1Get(`${base}/series/${id}`);
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log((data.series ?? {}).id ?? "");
+                return EXIT_OK;
+            }
+            if (sub === "create") {
+                const name = takeFlag(work, "--name");
+                assertNoUnknownFlags(work, "mail");
+                if (!name)
+                    throw new CliHttpError("Usage: frontpage mail series create --name …", EXIT_USAGE, 0, "bad_request");
+                const data = await v1Post(`${base}/series`, { name });
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log((data.series ?? {}).id ?? "");
+                return EXIT_OK;
+            }
+            if (sub === "set") {
+                const id = requireId(work, "Series");
+                const name = takeFlag(work, "--name");
+                const status = takeFlag(work, "--status");
+                assertNoUnknownFlags(work, "mail");
+                const data = await v1Patch(`${base}/series/${id}`, { name, status });
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log("Saved.");
+                return EXIT_OK;
+            }
+            if (sub === "rm") {
+                const id = requireId(work, "Series");
+                assertNoUnknownFlags(work, "mail");
+                const data = await v1Delete(`${base}/series/${id}`);
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log("Deleted.");
+                return EXIT_OK;
+            }
+            if (sub === "activate" || sub === "pause") {
+                const id = requireId(work, "Series");
+                assertNoUnknownFlags(work, "mail");
+                const data = await v1Patch(`${base}/series/${id}`, {
+                    status: sub === "activate" ? "active" : "paused",
+                });
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log(sub === "activate" ? "Active." : "Paused.");
+                return EXIT_OK;
+            }
+            if (sub === "steps") {
+                const verb = work[0];
+                const restSteps = work.slice(1);
+                if (verb !== "set") {
+                    throw new CliHttpError("Usage: frontpage mail series steps set <id> --file steps.json", EXIT_USAGE, 0, "bad_request");
+                }
+                const id = requireId(restSteps, "Series");
+                const file = takeFlag(restSteps, "--file");
+                const stepFlags = takeAll(restSteps, "--step");
+                assertNoUnknownFlags(restSteps, "mail");
+                let steps = [];
+                if (file) {
+                    const body = await readJsonFile(file);
+                    steps = Array.isArray(body.steps) ? body.steps : Array.isArray(body) ? body : [];
+                }
+                else {
+                    steps = stepFlags.map(parseStepFlag);
+                }
+                const data = await v1Put(`${base}/series/${id}/steps`, { steps });
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log("Steps saved.");
+                return EXIT_OK;
+            }
+        }
+        if (group === "send") {
+            const work = rest.slice(1);
+            const file = takeFlag(work, "--file");
+            const wait = hasFlag(work, "--wait");
+            const test = hasFlag(work, "--test");
+            const kind = work[0];
+            if (file) {
+                const recipients = parseRecipients(work);
+                assertNoUnknownFlags(work, "mail");
+                const body = await readJsonFile(file);
+                const data = await v1Post(`${base}/send`, {
+                    ...body,
+                    recipients,
+                    wait,
+                    test,
+                });
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log(data.batchId ?? "Queued.");
+                return EXIT_OK;
+            }
+            if (kind === "email" || kind === "template" || kind === "series") {
+                const restKind = work.slice(1);
+                const id = requireId(restKind, kind === "series" ? "Series" : "Document");
+                const recipients = parseRecipients(restKind);
+                assertNoUnknownFlags(restKind, "mail");
+                const path = kind === "series" ? `${base}/series/${id}/send` : `${base}/${kind === "email" ? "emails" : "templates"}/${id}/send`;
+                const data = await v1Post(path, { recipients, wait, test });
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log(data.batchId ?? "Queued.");
+                return EXIT_OK;
+            }
+            throw new CliHttpError("Usage: frontpage mail send --file email.json --to a@x.com | send email|template|series <id> --to a@x.com", EXIT_USAGE, 0, "bad_request");
+        }
+        if (group === "sends") {
+            const sub = rest[1] ?? "list";
+            const work = rest.slice(2);
+            if (sub === "list") {
+                const batchId = takeFlag(work, "--batch");
+                const limit = takeFlag(work, "--limit");
+                const cursor = takeFlag(work, "--cursor");
+                assertNoUnknownFlags(work, "mail");
+                const params = new URLSearchParams();
+                if (batchId)
+                    params.set("batchId", batchId);
+                if (limit)
+                    params.set("limit", limit);
+                if (cursor)
+                    params.set("cursor", cursor);
+                const qs = params.toString();
+                const data = await v1Get(qs ? `${base}/sends?${qs}` : `${base}/sends`);
+                if (isJson()) {
+                    emitOk("mail", data);
+                    return EXIT_OK;
+                }
+                const rows = data.sends ?? [];
+                for (const row of rows)
+                    console.log(`${row.id}  ${row.status ?? ""}  ${row.email ?? ""}`);
+                return EXIT_OK;
+            }
+            if (sub === "get") {
+                const id = requireId(work, "Send");
+                assertNoUnknownFlags(work, "mail");
+                const data = await v1Get(`${base}/sends/${id}`);
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log((data.send ?? {}).status ?? "");
+                return EXIT_OK;
+            }
+        }
+        if (group === "enrolments") {
+            const sub = rest[1] ?? "list";
+            const work = rest.slice(2);
+            if (sub === "list") {
+                const seriesId = takeFlag(work, "--series");
+                assertNoUnknownFlags(work, "mail");
+                const params = new URLSearchParams();
+                if (seriesId)
+                    params.set("seriesId", seriesId);
+                const qs = params.toString();
+                const data = await v1Get(qs ? `${base}/enrolments?${qs}` : `${base}/enrolments`);
+                if (isJson())
+                    emitOk("mail", data);
+                else {
+                    const rows = data.enrolments ?? [];
+                    for (const row of rows)
+                        console.log(`${row.id}  ${row.status ?? ""}  ${row.email ?? ""}`);
+                }
+                return EXIT_OK;
+            }
+            if (sub === "cancel") {
+                const id = requireId(work, "Enrolment");
+                assertNoUnknownFlags(work, "mail");
+                const data = await v1Post(`${base}/enrolments/${id}/cancel`, {});
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log("Cancelled.");
+                return EXIT_OK;
+            }
+        }
+        if (group === "suppress") {
+            const sub = rest[1] ?? "list";
+            const work = rest.slice(2);
+            if (sub === "list") {
+                assertNoUnknownFlags(work, "mail");
+                const data = await v1Get(`${base}/suppressions`);
+                if (isJson())
+                    emitOk("mail", data);
+                else {
+                    const rows = data.suppressions ?? [];
+                    for (const row of rows)
+                        console.log(`${row.email ?? ""}  ${row.reason ?? ""}`);
+                }
+                return EXIT_OK;
+            }
+            if (sub === "add") {
+                const email = takeFlag(work, "--email") ?? work.find((a) => !a.startsWith("-"));
+                if (email && !email.startsWith("-") && !takeFlag(work, "--email")) {
+                    work.splice(work.indexOf(email), 1);
+                }
+                assertNoUnknownFlags(work, "mail");
+                if (!email)
+                    throw new CliHttpError("Usage: frontpage mail suppress add --email a@x.com", EXIT_USAGE, 0, "bad_request");
+                const data = await v1Post(`${base}/suppressions`, { email });
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log("Suppressed.");
+                return EXIT_OK;
+            }
+            if (sub === "rm") {
+                const email = takeFlag(work, "--email") ?? work.find((a) => !a.startsWith("-"));
+                if (email && !email.startsWith("-") && work.includes(email))
+                    work.splice(work.indexOf(email), 1);
+                assertNoUnknownFlags(work, "mail");
+                if (!email)
+                    throw new CliHttpError("Usage: frontpage mail suppress rm --email a@x.com", EXIT_USAGE, 0, "bad_request");
+                const data = await v1Delete(`${base}/suppressions/${encodeURIComponent(email)}`);
+                if (isJson())
+                    emitOk("mail", data);
+                else
+                    console.log("Removed.");
+                return EXIT_OK;
+            }
+        }
+        console.error(USAGE);
+        return EXIT_USAGE;
+    }
+    catch (err) {
+        if (isJson())
+            return emitErr("mail", err);
+        console.error(err instanceof Error ? err.message : String(err));
+        return exitCodeForError(err);
+    }
+}