recess-cli 2.1.0 → 2.3.0

package/dist/commands/school.js

@@ -0,0 +1,727 @@
+import { createHash } from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { unwrap } from "../api.js";
+import { flagList, flagString, hasFlag } from "../args.js";
+import { CliError } from "../errors.js";
+import { assertChoice, flagInteger, flagIsoInstant, positional, readJsonFile, } from "./shared.js";
+const SCHOOL_TIERS = [
+    "social",
+    "academics",
+    "lite",
+    "complete",
+    "platform",
+];
+const PROGRAM_TYPES = ["PARTNER", "SCHOOL"];
+const RESOLVE_ACTIONS = ["waive", "cancel"];
+const RECONCILIATION_OUTCOMES = ["refunded", "kept", "written_off"];
+/** post.start-memberships.ts caps the body at ten kids per call. */
+const MEMBERSHIP_KID_LIMIT = 10;
+function dollars(cents) {
+    return `$${(cents / 100).toFixed(2)}`;
+}
+/** The exact type set post.partner-logo-upload.ts accepts, keyed by extension. */
+const LOGO_MIME_BY_EXT = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".svg": "image/svg+xml",
+};
+async function readLogoFile(filePath) {
+    const absolutePath = path.resolve(filePath);
+    const mimeType = LOGO_MIME_BY_EXT[path.extname(absolutePath).toLowerCase()];
+    if (!mimeType) {
+        throw new CliError("invalid_arguments", "--file must be a .png, .jpg, .jpeg, .gif, .webp, or .svg image.");
+    }
+    let bytes;
+    try {
+        bytes = await fs.readFile(absolutePath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new CliError("invalid_arguments", `Logo file does not exist: ${absolutePath}`);
+        }
+        throw error;
+    }
+    return {
+        bytes,
+        fileName: path.basename(absolutePath),
+        mimeType,
+        sha256: createHash("sha256").update(bytes).digest("hex"),
+    };
+}
+function kidName(firstName, lastName, fallback) {
+    return [firstName, lastName].filter(Boolean).join(" ") || fallback;
+}
+/**
+ * `"<kid-id>:<tier>[:<slots>[:<enrollment-cents>]]"` — the same
+ * colon-delimited per-kid spec `applications enroll --kid` uses. The 4th field
+ * is the child's own first-month charge (":0" = free); OMITTING it inherits the
+ * family-level default, and when neither is given the server refuses the whole
+ * conversion as PRICE_UNDECIDED rather than guessing a price.
+ */
+function parseKidTierSpec(spec) {
+    const [kidId, tier, slots, cents, ...rest] = spec.split(":");
+    if (!kidId || !tier || rest.length > 0) {
+        throw new CliError("invalid_arguments", `--kid "${spec}" must be "<kid-id>:<tier>[:<slots>[:<enrollment-cents>]]".`);
+    }
+    const number = (value, label) => {
+        const parsed = Number(value);
+        if (!Number.isInteger(parsed) || parsed < 0) {
+            throw new CliError("invalid_arguments", `--kid "${spec}": ${label} must be a nonnegative integer.`);
+        }
+        return parsed;
+    };
+    return {
+        kidId,
+        tierId: assertChoice(tier, SCHOOL_TIERS, `--kid "${spec}" tier`),
+        ...(slots ? { slotsPerKid: number(slots, "slots") } : {}),
+        ...(cents
+            ? { enrollmentPaymentCents: number(cents, "enrollment cents") }
+            : {}),
+    };
+}
+export async function runSchoolCommand({ parsed, api, writeCommand, }) {
+    const verb = parsed.positionals[1] ?? "";
+    /**
+     * The school roster is the ONE read behind every command here: it carries the
+     * institution, each family's stage/account state and kids, the live
+     * enrollment payment, and the open reconciliation items. Every write below
+     * previews from this same response, so the approval names the same facts the
+     * dashboard shows rather than a second, differently-shaped guess.
+     */
+    const roster = async (slug) => unwrap(await api.client.GET("/admin/partner/{slug}/families", {
+        params: { path: { slug } },
+    }));
+    const requireSlug = () => flagString(parsed, "school", { required: true });
+    if (verb === "families") {
+        return roster(requireSlug());
+    }
+    if (verb === "list") {
+        return unwrap(await api.client.GET("/admin/partner/"));
+    }
+    if (verb === "family-search") {
+        const search = flagString(parsed, "query", { required: true });
+        const limit = flagInteger(parsed, "limit", { min: 1, max: 100 });
+        return unwrap(await api.client.GET("/admin/partner/{slug}/family-search", {
+            params: {
+                path: { slug: requireSlug() },
+                query: { search, ...(limit !== undefined ? { limit } : {}) },
+            },
+        }));
+    }
+    if (verb === "convert") {
+        const familyId = positional(parsed, 2, "family ID");
+        const slug = requireSlug();
+        const kids = flagList(parsed, "kid").map(parseKidTierSpec);
+        if (kids.length === 0) {
+            throw new CliError("invalid_arguments", '--kid is required, once per kid: "<kid-id>:<tier>[:<slots>[:<enrollment-cents>]]". Every kid in the family must be assigned a tier, same rule as enrollment.');
+        }
+        const creditAmountCents = flagInteger(parsed, "credit-cents", {
+            min: 0,
+            max: 1_000_000,
+        });
+        const enrollmentPaymentCentsPerKid = flagInteger(parsed, "enrollment-payment-cents", { min: 0 });
+        const note = flagString(parsed, "note");
+        const body = {
+            familyId,
+            kids,
+            ...(creditAmountCents !== undefined ? { creditAmountCents } : {}),
+            ...(enrollmentPaymentCentsPerKid !== undefined
+                ? { enrollmentPaymentCentsPerKid }
+                : {}),
+            ...(note ? { note } : {}),
+        };
+        const unpriced = kids.filter((kid) => kid.enrollmentPaymentCents === undefined &&
+            enrollmentPaymentCentsPerKid === undefined);
+        if (unpriced.length > 0) {
+            throw new CliError("invalid_arguments", `No first-month price decided for ${unpriced
+                .map((kid) => kid.kidId)
+                .join(", ")}. Give each kid a 4th spec field (":0" for free) or pass --enrollment-payment-cents for the family; the server refuses an undecided price (PRICE_UNDECIDED).`);
+        }
+        // Read-only preflight on the family's own state — the roster cannot help
+        // here, because a family being converted INTO the program is not on it yet.
+        const status = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+            params: { path: { familyId } },
+        }));
+        const familyKidIds = new Set(status.kids.map((kid) => kid.id));
+        const foreign = kids
+            .map((kid) => kid.kidId)
+            .filter((id) => !familyKidIds.has(id));
+        if (foreign.length > 0) {
+            throw new CliError("invalid_arguments", `Not kids in this family: ${foreign.join(", ")}.`);
+        }
+        const missing = status.kids.filter((kid) => !kids.some((k) => k.kidId === kid.id));
+        return writeCommand(parsed, {
+            action: "convert this marketplace family INTO the school program (links the institution, funds tokens, cancels live memberships)",
+            target: { familyId, slug, familyName: status.familyName },
+            request: body,
+            details: {
+                kids: kids.map((kid) => ({
+                    kid: status.kids.find((row) => row.id === kid.kidId)?.firstName ??
+                        kid.kidId,
+                    tier: kid.tierId,
+                    slots: kid.slotsPerKid ?? "the tier default",
+                    firstMonth: kid.enrollmentPaymentCents === undefined
+                        ? enrollmentPaymentCentsPerKid === undefined
+                            ? "undecided"
+                            : `${dollars(enrollmentPaymentCentsPerKid)} (family default)`
+                        : dollars(kid.enrollmentPaymentCents),
+                })),
+                ...(missing.length > 0
+                    ? {
+                        unassignedKids: missing.map((kid) => kid.firstName ?? kid.id),
+                        unassignedWarning: "These kids of the family were NOT given a tier here. They come out unassigned with 0 slots until an admin picks one.",
+                    }
+                    : {}),
+                consequences: [
+                    "Cancels live membership subscriptions at period end and turns off membership credits.",
+                    "Funds each kid top-up-to-target for the month; a lower --credit-cents is NOT topped back up until the next UTC month (it shares the cron's idempotency key).",
+                    "Existing cohort-enrollment subscriptions are deliberately left running — they migrate to token rails at their next renewal.",
+                    "Any nonzero total holds the family at PENDING_PAYMENT and gates them out of the parent app until they pay at /school/pay.",
+                    "ADMIN-only (exact-admin): a GUIDE or PROGRAM session gets 403.",
+                ],
+                reverse: `The inverse is \`school revert ${familyId} --school ${slug}\`, which is fenced off in production.`,
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/convert-family", {
+            params: { path: { slug } },
+            body,
+        })));
+    }
+    if (verb === "revert") {
+        const familyId = positional(parsed, 2, "family ID");
+        const slug = requireSlug();
+        const revokeTokens = !hasFlag(parsed, "keep-tokens");
+        const note = flagString(parsed, "note");
+        const { institution, families } = await roster(slug);
+        const family = families.find((row) => row.id === familyId);
+        if (!family) {
+            throw new CliError("invalid_arguments", `Family ${familyId} is not in ${institution.name} (${slug}). Revert only applies to a family currently in that school program.`);
+        }
+        return writeCommand(parsed, {
+            action: "convert this family OUT of the school program and back to marketplace billing",
+            target: { familyId, slug, familyName: family.name },
+            request: { familyId, revokeTokens, ...(note ? { note } : {}) },
+            details: {
+                institution: institution.name,
+                accountState: family.accountState,
+                onboardingStage: family.onboardingStage,
+                kids: family.kids.map((kid) => ({
+                    id: kid.id,
+                    name: kidName(kid.firstName, kid.lastName, kid.id),
+                    creditBalance: kid.creditBalance,
+                })),
+                revokeTokens,
+                liveEnrollmentPayment: family.liveEnrollmentPayment
+                    ? {
+                        id: family.liveEnrollmentPayment.id,
+                        status: family.liveEnrollmentPayment.status,
+                        amountDue: dollars(family.liveEnrollmentPayment.amountDueCents),
+                    }
+                    : null,
+                consequences: [
+                    revokeTokens
+                        ? "Revokes each kid's remaining school token balance (shown above)."
+                        : "LEAVES each kid's school token balance in place (--keep-tokens).",
+                    "Cancels the family's program membership; kids come out with NO membership. The follow-up is `school start-memberships`, which charges their card.",
+                    "Class registrations keep running on purpose — they start billing the family's own card at renewal.",
+                    "ADMIN-only (exact-admin): a GUIDE or PROGRAM session gets 403.",
+                ],
+                fence: "Gated on SCHOOL_REVERT_ENABLED, which is fail-closed and unset in every deployed environment — production refuses until settlement ships. A 409 here is that door, not a bad request.",
+                retry: "A 409 `revert_in_flight` means an earlier attempt is still settling; rerun the unchanged command with the SAME operation key rather than minting a new one.",
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/revert-family", {
+            params: { path: { slug } },
+            // Announce that this client reads the two-phase union; without the
+            // header the server sends the pre-union façade, which reports a
+            // still-settling revert as finished (revert-wire.ts).
+            headers: { "x-recess-revert-union": "1" },
+            body: { familyId, revokeTokens, ...(note ? { note } : {}) },
+        })));
+    }
+    if (verb === "start-memberships") {
+        const familyId = positional(parsed, 2, "family ID");
+        // --kid is REPEATABLE: read every occurrence, not just the last one.
+        const kidIds = flagList(parsed, "kid");
+        if (kidIds.length === 0) {
+            throw new CliError("invalid_arguments", "--kid is required: name each kid whose membership should start.");
+        }
+        if (kidIds.length > MEMBERSHIP_KID_LIMIT) {
+            throw new CliError("invalid_arguments", `--kid accepts at most ${MEMBERSHIP_KID_LIMIT} kids per call.`);
+        }
+        // Family-scoped, not slug-scoped: by the time this runs the family is no
+        // longer linked to a partner institution, so the roster read above cannot
+        // see it. The onboarding status is the read that still resolves.
+        const status = unwrap(await api.client.GET("/admin/onboarding/families/{familyId}/status", {
+            params: { path: { familyId } },
+        }));
+        const known = new Map(status.kids.map((kid) => [kid.id, kid]));
+        const unknown = kidIds.filter((id) => !known.has(id));
+        if (unknown.length > 0) {
+            throw new CliError("invalid_arguments", `Not kids in this family: ${unknown.join(", ")}. The server refuses the whole call when one id is foreign.`);
+        }
+        return writeCommand(parsed, {
+            action: "start a paid membership subscription for these kids, CHARGING the family's card on file",
+            target: { familyId, familyName: status.familyName },
+            request: { familyId, kidIds },
+            details: {
+                kids: kidIds.map((id) => kidName(known.get(id)?.firstName ?? null, null, id)),
+                billing: "Default membership price unless the family is grandfathered onto one, with a 1-day trial, confirmed against the customer's saved default payment method.",
+                note: "A kid whose membership is already ACTIVE comes back `skipped_active` rather than being charged twice; per-kid failures are reported in `results`, not thrown.",
+            },
+        }, async () => unwrap(await api.client.POST("/admin/memberships/start", {
+            body: { familyId, kidIds },
+        })));
+    }
+    if (verb === "resolve-payment") {
+        const paymentId = positional(parsed, 2, "enrollment payment ID");
+        const slug = requireSlug();
+        const action = assertChoice(flagString(parsed, "action", { required: true }), RESOLVE_ACTIONS, "--action");
+        const note = flagString(parsed, "note");
+        const { institution, families } = await roster(slug);
+        const family = families.find((row) => row.liveEnrollmentPayment?.id === paymentId);
+        const payment = family?.liveEnrollmentPayment;
+        if (!family || !payment) {
+            throw new CliError("invalid_arguments", `No live enrollment payment ${paymentId} under ${institution.name} (${slug}). Run \`school families --school ${slug}\` and read \`liveEnrollmentPayment\`; a payment already resolved is not resolvable again.`);
+        }
+        return writeCommand(parsed, {
+            action: action === "waive"
+                ? "WAIVE this enrollment charge — record it as collected off-platform and lift the paywall"
+                : "CANCEL this enrollment charge — drop the requirement entirely and lift the paywall",
+            target: {
+                paymentId,
+                slug,
+                familyId: family.id,
+                familyName: family.name,
+            },
+            request: { action, ...(note ? { note } : {}) },
+            details: {
+                institution: institution.name,
+                status: payment.status,
+                amountDue: dollars(payment.amountDueCents),
+                lines: payment.lines.map((line) => ({
+                    kid: line.firstName ?? line.kidId ?? "unassigned",
+                    amount: dollars(line.amountCents),
+                })),
+                stripeInvoiceId: payment.stripeInvoiceId,
+                effect: "The family stops being redirected to /school/pay and class registration reopens — but ONLY if no other PENDING enrollment payment remains on the family.",
+                accountState: "PENDING_PAYMENT is walked back; a family separately set to PAUSED or BOOTED keeps that state.",
+                ...(action === "cancel"
+                    ? {
+                        cancelCaveat: "If a charge already landed, compensation is unproven and the wire status comes back CANCEL_REQUESTED — the row is still live and still blocking. That is not a failed call.",
+                    }
+                    : {}),
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/enrollment-payments/{paymentId}/resolve", {
+            params: { path: { slug, paymentId } },
+            body: { action, ...(note ? { note } : {}) },
+        })));
+    }
+    if (verb === "close-reconciliation") {
+        const paymentId = positional(parsed, 2, "enrollment payment ID");
+        const slug = requireSlug();
+        const outcome = assertChoice(flagString(parsed, "outcome", { required: true }), RECONCILIATION_OUTCOMES, "--outcome");
+        const note = flagString(parsed, "note");
+        const { institution, families } = await roster(slug);
+        const family = families.find((row) => row.reconciliationItems.some((item) => item.paymentId === paymentId));
+        const item = family?.reconciliationItems.find((row) => row.paymentId === paymentId);
+        if (!family || !item) {
+            throw new CliError("invalid_arguments", `No reconciliation item for payment ${paymentId} under ${institution.name} (${slug}). Run \`school families --school ${slug}\` and read \`reconciliationItems\`.`);
+        }
+        if (item.resolution) {
+            throw new CliError("invalid_arguments", `That reconciliation item was already closed as ${item.resolution.outcome} at ${item.resolution.resolvedAt}. The close is conditional and irreversible — a second one 409s.`);
+        }
+        return writeCommand(parsed, {
+            action: `close this reconciliation item as ${outcome} (a money decision, and irreversible)`,
+            target: {
+                paymentId,
+                slug,
+                familyId: family.id,
+                familyName: family.name,
+            },
+            request: { outcome, ...(note ? { note } : {}) },
+            details: {
+                institution: institution.name,
+                amountPaid: dollars(item.amountPaidCents),
+                openedBecause: item.reason,
+                openedAt: item.openedAt,
+                paymentStatus: item.status,
+                invoiceId: item.invoiceId,
+                meaning: {
+                    refunded: "the money was returned to the family",
+                    kept: "the family genuinely owed it, so the charge stands",
+                    written_off: "neither — the business absorbed it",
+                }[outcome],
+                scope: "Bookkeeping only: this annotates the item, never deletes it, and does NOT settle a debt, unblock a family, or move the payment's status.",
+                irreversible: "The write is conditional on the item still being open, so every later attempt 409s and the item drops out of triage.",
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/enrollment-payments/{paymentId}/close-reconciliation", {
+            params: { path: { slug, paymentId } },
+            body: { outcome, ...(note ? { note } : {}) },
+        })));
+    }
+    if (verb === "codes") {
+        const subverb = parsed.positionals[2] ?? "";
+        const slug = requireSlug();
+        const codeId = () => positional(parsed, 3, "invite code ID");
+        if (subverb === "list") {
+            return unwrap(await api.client.GET("/admin/partner/{slug}/codes", {
+                params: { path: { slug } },
+            }));
+        }
+        if (subverb === "get") {
+            return unwrap(await api.client.GET("/admin/partner/{slug}/codes/{id}", {
+                params: { path: { slug, id: codeId() } },
+            }));
+        }
+        if (subverb === "create") {
+            const count = flagInteger(parsed, "count", { min: 1 });
+            const expiresAt = flagIsoInstant(parsed, "expires-at");
+            const note = flagString(parsed, "note");
+            const creditAmountCents = flagInteger(parsed, "credit-cents", { min: 0 });
+            const tierRaw = flagString(parsed, "tier");
+            const slotsPerKid = flagInteger(parsed, "slots", { min: 0, max: 20 });
+            const enrollmentPaymentCentsPerKid = flagInteger(parsed, "enrollment-payment-cents", { min: 0 });
+            const dataFile = flagString(parsed, "data-file");
+            // The preconfigured-invite `family` block (parent identity + the kid
+            // roster with per-kid tier and price) is a nested object, so it arrives
+            // as JSON the way `quotes create` takes its body. Without it this mints
+            // blank codes; with it, one addressed invite that emails the parent.
+            const family = dataFile
+                ? (await readJsonFile(dataFile, "Preconfigured invite file"))
+                : undefined;
+            const body = {
+                ...(count !== undefined ? { count } : {}),
+                ...(expiresAt ? { expiresAt } : {}),
+                ...(note ? { note } : {}),
+                ...(creditAmountCents !== undefined ? { creditAmountCents } : {}),
+                ...(tierRaw
+                    ? { tierId: assertChoice(tierRaw, SCHOOL_TIERS, "--tier") }
+                    : {}),
+                ...(slotsPerKid !== undefined ? { slotsPerKid } : {}),
+                ...(enrollmentPaymentCentsPerKid !== undefined
+                    ? { enrollmentPaymentCentsPerKid }
+                    : {}),
+                ...(family ? { family } : {}),
+            };
+            return writeCommand(parsed, {
+                action: family
+                    ? "mint a preconfigured school invite for this family and EMAIL the parent their claim link"
+                    : `mint ${count ?? 1} blank school invite code(s)`,
+                target: { slug },
+                request: body,
+                details: {
+                    expiresAt: expiresAt ?? "the institution default",
+                    firstMonthPerKid: enrollmentPaymentCentsPerKid === undefined
+                        ? "not set at the family level — each kid in --data-file must carry its own price"
+                        : dollars(enrollmentPaymentCentsPerKid),
+                    ...(family
+                        ? {
+                            duplicateGuard: "The create 409s when the parent email already has a Recess account or another live invite. That is the guard, not a transient failure.",
+                        }
+                        : {
+                            blank: "No --data-file, so these are blank codes: nobody is emailed and no roster is preconfigured.",
+                        }),
+                },
+            }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/codes", {
+                params: { path: { slug } },
+                body,
+            })));
+        }
+        if (subverb === "set-kids") {
+            const id = codeId();
+            const body = (await readJsonFile(flagString(parsed, "data-file", { required: true }), "Invite roster file"));
+            return writeCommand(parsed, {
+                action: "edit an UNREDEEMED invite's roster in place — the parent's existing link keeps working",
+                target: { slug, codeId: id },
+                request: body,
+                details: {
+                    semantics: "The body is the FULL roster, not a diff: a student absent from the list is removed. `enrollmentPaymentCents` is required per student (null or 0 = that student enrolls free) so the paywall cannot be dropped by omission.",
+                    outOfScope: "Parent identity, note, credit and expiry are not editable here — changing WHO the invite is for is `codes replace`.",
+                    refusal: "Editing after redemption is refused outright; the accounts and the charge already exist.",
+                },
+            }, async () => unwrap(await api.client.PATCH("/admin/partner/{slug}/codes/{id}", {
+                params: { path: { slug, id } },
+                body,
+            })));
+        }
+        if (subverb === "replace") {
+            const id = codeId();
+            const body = (await readJsonFile(flagString(parsed, "data-file", { required: true }), "Replacement invite file"));
+            return writeCommand(parsed, {
+                action: "REPLACE this unredeemed invite: delete the old code and mint a new one, emailing the parent a fresh link",
+                target: { slug, codeId: id },
+                request: body,
+                details: {
+                    atomicity: "Delete and create run in ONE transaction, so a failure rolls back and the OLD invite survives — a failed replace is plainly retryable and never leaves the family with no invite.",
+                    whenToUse: "Use replace when the parent's identity or email changes; use `codes set-kids` to edit the roster without invalidating the link the parent already holds.",
+                    inherits: "Fields omitted from the body (note, credit) inherit from the old row read inside the transaction.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/codes/{id}/replace", {
+                params: { path: { slug, id } },
+                body,
+            })));
+        }
+        if (subverb === "resend") {
+            const id = codeId();
+            return writeCommand(parsed, {
+                action: "re-email this invite's claim link to the parent on file",
+                target: { slug, codeId: id },
+                request: {},
+                details: {
+                    outwardEmail: "This sends mail to a real family. The code itself is unchanged — use `codes replace` to mint a new one.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/codes/{id}/resend", {
+                params: { path: { slug, id } },
+            })));
+        }
+        if (subverb === "revoke") {
+            const id = codeId();
+            const existing = unwrap(await api.client.GET("/admin/partner/{slug}/codes/{id}", {
+                params: { path: { slug, id } },
+            }));
+            return writeCommand(parsed, {
+                action: "HARD-DELETE this unredeemed invite code",
+                target: { slug, codeId: id },
+                request: {},
+                details: {
+                    code: existing,
+                    irreversible: "The row is REMOVED, not soft-deleted: there is no deletedAt on TalentSchoolInviteCode and no undo. The parent's link stops working immediately.",
+                },
+            }, async () => unwrap(await api.client.DELETE("/admin/partner/{slug}/codes/{id}", {
+                params: { path: { slug, id } },
+            })));
+        }
+        throw new CliError("invalid_arguments", "Use school codes list|get|create|set-kids|replace|resend|revoke.");
+    }
+    if (verb === "create") {
+        const slug = flagString(parsed, "slug", { required: true });
+        const name = flagString(parsed, "name", { required: true });
+        const logoUrl = flagString(parsed, "logo-url");
+        const creditGrant = flagInteger(parsed, "credit-grant", {
+            required: true,
+            min: 0,
+        });
+        const programTypeRaw = flagString(parsed, "program-type");
+        const programType = programTypeRaw
+            ? assertChoice(programTypeRaw, PROGRAM_TYPES, "--program-type")
+            : undefined;
+        const tokenTopUpCents = flagInteger(parsed, "token-topup-cents", {
+            min: 0,
+            max: 10_000_000,
+        });
+        if (programType === "SCHOOL" && tokenTopUpCents !== creditGrant) {
+            throw new CliError("invalid_arguments", "SCHOOL programs require --token-topup-cents equal to --credit-grant (the server enforces the same rule).");
+        }
+        const body = {
+            slug,
+            name,
+            defaultInitialCreditGrant: creditGrant,
+            ...(logoUrl ? { logoUrl } : {}),
+            ...(programType ? { programType } : {}),
+            ...(tokenTopUpCents !== undefined
+                ? { monthlyTokenTopUpCents: tokenTopUpCents }
+                : {}),
+        };
+        return writeCommand(parsed, {
+            action: `create the ${programType ?? "PARTNER"}-program institution "${name}" (${slug})`,
+            target: { slug },
+            request: body,
+            details: {
+                moneyLevers: {
+                    defaultInitialCreditGrant: creditGrant,
+                    monthlyTokenTopUpCents: tokenTopUpCents ?? null,
+                    warning: "For SCHOOL programs the monthly target tops EVERY kid in the institution up to it on the next cron run — these numbers spend real money at scale.",
+                },
+                duplicateGuard: "A taken slug 409s; pick another rather than retrying.",
+            },
+        }, async () => unwrap(await api.client.POST("/admin/partner/", { body })));
+    }
+    if (verb === "update") {
+        const institutionId = positional(parsed, 2, "institution ID");
+        const slug = flagString(parsed, "slug");
+        const name = flagString(parsed, "name");
+        const logoUrl = flagString(parsed, "logo-url");
+        const creditGrant = flagInteger(parsed, "credit-grant", { min: 0 });
+        const programTypeRaw = flagString(parsed, "program-type");
+        const programType = programTypeRaw
+            ? assertChoice(programTypeRaw, PROGRAM_TYPES, "--program-type")
+            : undefined;
+        const tokenTopUpRaw = flagString(parsed, "token-topup-cents");
+        const tokenTopUpCents = tokenTopUpRaw === undefined
+            ? undefined
+            : tokenTopUpRaw === "none"
+                ? null
+                : flagInteger(parsed, "token-topup-cents", {
+                    min: 0,
+                    max: 10_000_000,
+                });
+        const body = {
+            ...(slug ? { slug } : {}),
+            ...(name ? { name } : {}),
+            ...(logoUrl ? { logoUrl } : {}),
+            ...(creditGrant !== undefined
+                ? { defaultInitialCreditGrant: creditGrant }
+                : {}),
+            ...(programType ? { programType } : {}),
+            ...(tokenTopUpCents !== undefined
+                ? { monthlyTokenTopUpCents: tokenTopUpCents }
+                : {}),
+        };
+        if (Object.keys(body).length === 0) {
+            throw new CliError("invalid_arguments", "Pass at least one field to change (--slug, --name, --logo-url, --credit-grant, --program-type, --token-topup-cents).");
+        }
+        const touchesMoney = creditGrant !== undefined ||
+            tokenTopUpCents !== undefined ||
+            programType !== undefined;
+        return writeCommand(parsed, {
+            action: touchesMoney
+                ? "edit this institution INCLUDING a money lever or the program type (exact-ADMIN only)"
+                : "edit this institution's descriptive metadata (name/slug/logo)",
+            target: { institutionId },
+            request: body,
+            details: {
+                ...(touchesMoney
+                    ? {
+                        moneyWarning: "defaultInitialCreditGrant / monthlyTokenTopUpCents / programType are money levers: the monthly target tops EVERY kid up to it on the next cron. A GUIDE or PROGRAM session gets 403 for these fields.",
+                    }
+                    : {}),
+                ...(programType
+                    ? {
+                        programTypeGuard: "A type flip is refused while families are attached or unused invite codes exist — resolve those first.",
+                    }
+                    : {}),
+            },
+        }, async () => unwrap(await api.client.PATCH("/admin/partner/{id}", {
+            params: { path: { id: institutionId } },
+            body,
+        })));
+    }
+    if (verb === "representatives") {
+        const subverb = parsed.positionals[2] ?? "";
+        if (subverb === "list") {
+            return unwrap(await api.client.GET("/admin/partner/{slug}/representatives", {
+                params: { path: { slug: requireSlug() } },
+            }));
+        }
+        if (subverb === "search") {
+            const q = flagString(parsed, "query", { required: true });
+            return unwrap(await api.client.GET("/admin/partner/representatives/search", {
+                params: { query: { q } },
+            }));
+        }
+        if (subverb === "add") {
+            const slug = requireSlug();
+            const userId = flagString(parsed, "user", { required: true });
+            // Resolve the exact person first so the approval names who gains the
+            // representative surface, not a bare id.
+            const { user } = unwrap(await api.client.GET("/admin/users/{userId}", {
+                params: { path: { userId } },
+            }));
+            return writeCommand(parsed, {
+                action: "add this GUIDE/ADMIN as a representative of the institution",
+                target: {
+                    slug,
+                    userId,
+                    name: kidName(user.firstName, user.lastName, userId),
+                    role: user.role,
+                },
+                request: { userId },
+                details: {
+                    refusal: "Non-GUIDE/ADMIN users are refused by the server.",
+                },
+            }, async () => unwrap(await api.client.POST("/admin/partner/{slug}/representatives", {
+                params: { path: { slug } },
+                body: { userId },
+            })));
+        }
+        if (subverb === "remove") {
+            const slug = requireSlug();
+            const userId = flagString(parsed, "user", { required: true });
+            return writeCommand(parsed, {
+                action: "remove this representative from the institution",
+                target: { slug, userId },
+                request: {},
+            }, async () => unwrap(await api.client.DELETE("/admin/partner/{slug}/representatives/{userId}", { params: { path: { slug, userId } } })));
+        }
+        throw new CliError("invalid_arguments", "Use school representatives list|search|add|remove.");
+    }
+    if (verb === "credit-transactions") {
+        const slug = requireSlug();
+        const page = flagInteger(parsed, "page", { min: 0 });
+        const limit = flagInteger(parsed, "limit", { min: 1, max: 100 });
+        return unwrap(await api.client.GET("/admin/partner/{slug}/credit-transactions", {
+            params: {
+                path: { slug },
+                query: {
+                    ...(page !== undefined ? { page } : {}),
+                    ...(limit !== undefined ? { limit } : {}),
+                },
+            },
+        }));
+    }
+    if (verb === "kid-slots") {
+        const kidId = positional(parsed, 2, "kid ID");
+        const slug = requireSlug();
+        const slotsRaw = flagString(parsed, "slots", { required: true });
+        const concurrentClassSlots = slotsRaw === "unlimited"
+            ? null
+            : flagInteger(parsed, "slots", { min: 0 });
+        const premiumClassSlots = flagInteger(parsed, "premium-slots", {
+            min: 0,
+            max: 20,
+        });
+        const body = {
+            concurrentClassSlots,
+            ...(premiumClassSlots !== undefined ? { premiumClassSlots } : {}),
+        };
+        return writeCommand(parsed, {
+            action: "set this school kid's concurrent class slots directly (the raw slot override — `users tier set` is the tier-driven path)",
+            target: { kidId, slug },
+            request: body,
+            details: {
+                slots: concurrentClassSlots ?? "unlimited",
+                ...(premiumClassSlots !== undefined
+                    ? { premiumSlots: premiumClassSlots }
+                    : {}),
+                note: "SCHOOL-program kids only; the write re-checks membership under the family lock so it cannot race a concurrent revert.",
+            },
+        }, async () => unwrap(await api.client.PATCH("/admin/partner/{slug}/kids/{kidId}/slots", {
+            params: { path: { slug, kidId } },
+            body,
+        })));
+    }
+    if (verb === "partner-family") {
+        const familyId = positional(parsed, 2, "family ID");
+        const slug = requireSlug();
+        const enabledRaw = flagString(parsed, "enabled", { required: true });
+        const enabled = assertChoice(enabledRaw, ["true", "false"], "--enabled") ===
+            "true";
+        return writeCommand(parsed, {
+            action: enabled
+                ? "attach this family to the PARTNER institution"
+                : "detach this family from the PARTNER institution",
+            target: { familyId, slug },
+            request: { enabled },
+            details: {
+                scope: "PARTNER programs only — the server refuses SCHOOL institutions here, because school families carry entitlements this generic toggle cannot safely provision or remove (use `school convert`/`school revert`).",
+            },
+        }, async () => unwrap(await api.client.PATCH("/admin/partner/{slug}/families/{familyId}", {
+            params: { path: { slug, familyId } },
+            body: { enabled },
+        })));
+    }
+    if (verb === "logo-upload") {
+        const filePath = flagString(parsed, "file", { required: true });
+        const { bytes, fileName, mimeType, sha256 } = await readLogoFile(filePath);
+        return writeCommand(parsed, {
+            action: "upload this image to the assets CDN as a partner-institution logo (returns a URL for `school create/update --logo-url`)",
+            target: { fileName },
+            request: { fileName, mimeType, bytes: bytes.byteLength, sha256 },
+        }, async () => api.uploadPartnerLogo(bytes, fileName, mimeType));
+    }
+    throw new CliError("invalid_arguments", "Unknown school command. Run `recess school --help` for the current command list.");
+}
+//# sourceMappingURL=school.js.map