recess-cli 3.53.0 → 3.55.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/cli.js CHANGED
@@ -27,12 +27,14 @@ import { runStudentsTextsCommand, runUsersPhoneCommand, runUsersTextCommand, run
27
27
  import { hasCommunityHour, runUsersCommunityHourCommand, } from "./commands/community-hour.js";
28
28
  import { runUsersBirthdayCommand } from "./commands/birthday.js";
29
29
  import { runTuitionPlansCommand } from "./commands/tuition-plans.js";
30
+ import { runTuitionCommand } from "./commands/tuition.js";
30
31
  import { runReportsCommand } from "./commands/reports.js";
31
32
  import { runMasteryCommand } from "./commands/mastery.js";
32
33
  import { runOnboardingCommand } from "./commands/onboarding.js";
33
34
  import { runScheduleCommand, runMemoryFilesCommand, } from "./commands/safe-staff-operations.js";
34
35
  import { runPlacementCommand } from "./commands/placement.js";
35
36
  import { runFlagsCommand } from "./commands/flags.js";
37
+ import { runIssuesCommand } from "./commands/issues.js";
36
38
  import { runRockyFreeCommand } from "./commands/rocky-free.js";
37
39
  import { runSchoolCommand } from "./commands/school.js";
38
40
  import { runVillageEventsCommand } from "./commands/village-events.js";
@@ -3929,6 +3931,9 @@ export async function executeRecessCommand(argv, options = {}) {
3929
3931
  if (noun === "admissions") {
3930
3932
  return runAdmissionsCommand({ parsed, api, writeCommand });
3931
3933
  }
3934
+ if (noun === "tuition") {
3935
+ return runTuitionCommand({ parsed, api, writeCommand });
3936
+ }
3932
3937
  if (noun === "apps") {
3933
3938
  return runAppsCommand({
3934
3939
  parsed,
@@ -7340,6 +7345,9 @@ export async function executeRecessCommand(argv, options = {}) {
7340
7345
  if (noun === "flags") {
7341
7346
  return runFlagsCommand({ parsed, api, writeCommand });
7342
7347
  }
7348
+ if (noun === "issues") {
7349
+ return runIssuesCommand({ parsed, api, writeCommand });
7350
+ }
7343
7351
  if (noun === "rocky") {
7344
7352
  const studentId = flagString(parsed, "student", { required: true });
7345
7353
  if (verb === "get") {
@@ -0,0 +1,169 @@
1
+ import { fs } from "../in-app.js";
2
+ import path from "node:path";
3
+ import { unwrap } from "../api.js";
4
+ import { flagString } from "../args.js";
5
+ import { CliError } from "../errors.js";
6
+ import { assertChoice, flagInteger, positional, } from "./shared.js";
7
+ const TYPES = ["bug", "feature", "request", "task"];
8
+ const SEVERITIES = ["minor", "major", "blocking"];
9
+ const STATUSES = ["open", "in_progress", "done", "wont_do"];
10
+ const SEARCH_STATUSES = ["active", "all", "archived", ...STATUSES];
11
+ /** R-1691, r-1691 or 1691 → "1691" (the route takes either). */
12
+ function issueNumber(context) {
13
+ const raw = positional(context.parsed, 2, "issue number (R-####)");
14
+ if (!/^(R-)?\d+$/i.test(raw)) {
15
+ throw new CliError("invalid_arguments", `${raw} is not an issue number: pass R-1691 or 1691.`);
16
+ }
17
+ return raw.replace(/^R-/i, "");
18
+ }
19
+ /** --body TEXT or --body-file <path>; undefined when neither is passed. */
20
+ async function bodyFlag(context) {
21
+ const text = flagString(context.parsed, "body");
22
+ const file = flagString(context.parsed, "body-file");
23
+ if (text !== undefined && file !== undefined) {
24
+ throw new CliError("invalid_arguments", "Pass --body or --body-file, not both.");
25
+ }
26
+ if (file === undefined)
27
+ return text;
28
+ const absolutePath = path.resolve(file);
29
+ const contents = await fs.readFile(absolutePath, "utf8").catch(() => null);
30
+ if (contents === null) {
31
+ throw new CliError("invalid_arguments", `--body-file is not readable: ${absolutePath}`);
32
+ }
33
+ return contents;
34
+ }
35
+ function choice(context, name, values) {
36
+ const raw = flagString(context.parsed, name);
37
+ return raw === undefined ? undefined : assertChoice(raw, values, `--${name}`);
38
+ }
39
+ /**
40
+ * `recess issues` — Recess Issues (issues.recess.gg), the team tracker, for admins: search, read,
41
+ * create, edit, set status, archive. Writes land as you, through the tracker's own actions, so a
42
+ * group's children follow its status and the issue's history names you.
43
+ */
44
+ export async function runIssuesCommand(context) {
45
+ const { parsed, api, writeCommand } = context;
46
+ const verb = parsed.positionals[1];
47
+ if (verb === "search") {
48
+ const q = parsed.positionals.slice(2).join(" ").trim() || undefined;
49
+ return unwrap(await api.client.GET("/admin/issues/", {
50
+ params: {
51
+ query: {
52
+ q,
53
+ status: choice(context, "status", SEARCH_STATUSES) ?? "active",
54
+ type: choice(context, "type", TYPES),
55
+ limit: flagInteger(parsed, "limit") ?? 25,
56
+ },
57
+ },
58
+ }));
59
+ }
60
+ if (verb === "get") {
61
+ return unwrap(await api.client.GET("/admin/issues/{number}", {
62
+ params: { path: { number: issueNumber(context) } },
63
+ }));
64
+ }
65
+ if (verb === "create") {
66
+ const title = flagString(parsed, "title", { required: true }).trim();
67
+ const body = (await bodyFlag(context)) ?? "";
68
+ const type = choice(context, "type", TYPES) ?? "bug";
69
+ const severity = choice(context, "severity", SEVERITIES) ?? null;
70
+ const request = { title, body, type, severity };
71
+ // The person decides whether it's new: show what already looks like it.
72
+ const { issues: similar } = unwrap(await api.client.GET("/admin/issues/", {
73
+ params: { query: { q: `${title}\n${body}`, status: "all", limit: 5 } },
74
+ }));
75
+ return writeCommand(parsed, {
76
+ action: `create ${type} "${title}" in the Recess Issues Backlog, as you`,
77
+ target: { tracker: "issues.recess.gg" },
78
+ request,
79
+ details: {
80
+ similar: similar.map((i) => `${i.key} [${i.archived ? "archived" : i.status}] ${i.title}`),
81
+ consequences: [
82
+ similar.length > 0
83
+ ? "Check `similar`: if one is the same thing, update it instead of creating a duplicate."
84
+ : "Nothing similar found.",
85
+ ],
86
+ reverse: "`issues archive <R-number>`",
87
+ },
88
+ }, async () => unwrap(await api.client.POST("/admin/issues/", { body: request })));
89
+ }
90
+ if (verb === "update" || verb === "archive" || verb === "unarchive") {
91
+ const number = issueNumber(context);
92
+ const { issue: before, children } = unwrap(await api.client.GET("/admin/issues/{number}", {
93
+ params: { path: { number } },
94
+ }));
95
+ const patch = {};
96
+ if (verb === "update") {
97
+ const title = flagString(parsed, "title")?.trim();
98
+ if (title)
99
+ patch.title = title;
100
+ const body = await bodyFlag(context);
101
+ if (body !== undefined)
102
+ patch.body = body;
103
+ const type = choice(context, "type", TYPES);
104
+ if (type)
105
+ patch.type = type;
106
+ const severity = choice(context, "severity", [...SEVERITIES, "none"]);
107
+ if (severity)
108
+ patch.severity = severity === "none" ? null : severity;
109
+ const status = choice(context, "status", STATUSES);
110
+ if (status)
111
+ patch.status = status;
112
+ if (Object.keys(patch).length === 0) {
113
+ throw new CliError("invalid_arguments", "Pass at least one of --title, --body, --body-file, --type, --severity, --status.");
114
+ }
115
+ }
116
+ else if (verb === "archive") {
117
+ if (before.archived)
118
+ return { issue: before, status: "unchanged" };
119
+ patch.status = "archived";
120
+ }
121
+ else {
122
+ if (!before.archived)
123
+ return { issue: before, status: "unchanged" };
124
+ // Picking its own status again brings an archived issue back.
125
+ patch.status = before.status;
126
+ }
127
+ const group = !!patch.status && before.status !== patch.status && children.length > 0;
128
+ const consequences = [
129
+ ...(patch.status === "archived"
130
+ ? ["Hidden from every list; a new matching report brings it back."]
131
+ : []),
132
+ ...(patch.status === "done"
133
+ ? [
134
+ "Done: kids who reported a fixed bug (or posted a built idea) are paid coins on Friday, unless it's archived first.",
135
+ ]
136
+ : []),
137
+ ...(group
138
+ ? [
139
+ "This is a group: its children (except safety reports) get the same status.",
140
+ ]
141
+ : []),
142
+ ];
143
+ return writeCommand(parsed, {
144
+ action: verb === "archive"
145
+ ? `archive ${before.key}, as you`
146
+ : verb === "unarchive"
147
+ ? `bring ${before.key} back from the archive, as you`
148
+ : `update ${before.key}, as you`,
149
+ target: { issue: before.key, url: before.url },
150
+ request: patch,
151
+ details: {
152
+ current: {
153
+ title: before.title,
154
+ type: before.type,
155
+ status: before.status,
156
+ severity: before.severity,
157
+ archived: before.archived,
158
+ ...(patch.body !== undefined ? { body: before.body } : {}),
159
+ },
160
+ ...(consequences.length > 0 ? { consequences } : {}),
161
+ },
162
+ }, async () => unwrap(await api.client.PATCH("/admin/issues/{number}", {
163
+ params: { path: { number } },
164
+ body: patch,
165
+ })));
166
+ }
167
+ throw new CliError("invalid_arguments", "Use issues search|get|create|update|archive|unarchive.");
168
+ }
169
+ //# sourceMappingURL=issues.js.map
@@ -0,0 +1,517 @@
1
+ import { unwrap } from "../api.js";
2
+ import { flagString, hasFlag } from "../args.js";
3
+ import { CliError } from "../errors.js";
4
+ import { assertChoice, positional, renderColumns, } from "./shared.js";
5
+ const STATUSES = [
6
+ "NEEDS_REVIEW",
7
+ "SCHEDULED",
8
+ "DRAFTED",
9
+ "SENT",
10
+ "PAID",
11
+ "PAID_OUT_OF_BAND",
12
+ "VOID",
13
+ ];
14
+ const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
15
+ const dollars = (cents) => `$${(cents / 100).toLocaleString("en-US", {
16
+ minimumFractionDigits: cents % 100 === 0 ? 0 : 2,
17
+ maximumFractionDigits: 2,
18
+ })}`;
19
+ /** The next row still owed, by invoice date. */
20
+ function nextOpen(schedule) {
21
+ return schedule.installments
22
+ .filter((row) => ["NEEDS_REVIEW", "SCHEDULED", "DRAFTED", "SENT"].includes(row.status))
23
+ .sort((a, b) => a.invoiceDate.localeCompare(b.invoiceDate))[0];
24
+ }
25
+ function renderSchedule({ schedule, signed, events, revisions, }) {
26
+ const out = [
27
+ `${schedule.kidName} · ${schedule.parentName} <${schedule.parentEmail}> · ${schedule.stateCode}`,
28
+ `Schedule ${schedule.id} · packet ${schedule.packetId}`,
29
+ `Payer ${schedule.payer} · collection ${schedule.defaultCollection} · automatic invoicing ${schedule.autoInvoice ? "on" : "OFF"} · option ${schedule.sourceOptionId}`,
30
+ `Signed ${dollars(schedule.agreedTotalCents)} · scheduled ${dollars(schedule.scheduledCents)} · paid ${dollars(schedule.paidCents)} · open ${dollars(schedule.openCents)}`,
31
+ ];
32
+ if (schedule.scheduledCents !== schedule.agreedTotalCents) {
33
+ out.push(`!! The rows add up to ${dollars(schedule.scheduledCents)}, not the signed ${dollars(schedule.agreedTotalCents)}.`);
34
+ }
35
+ if (schedule.held)
36
+ out.push(`!! Held: ${schedule.held}`);
37
+ if (schedule.recordOnly)
38
+ out.push(`Record only: ${schedule.recordOnly}`);
39
+ out.push(`Family last consented ${schedule.lastConsentAt.slice(0, 10)}${schedule.changesWithoutConsent
40
+ ? `; ${schedule.changesWithoutConsent} change(s) applied since without their consent`
41
+ : ""}.`);
42
+ if (schedule.pendingRevision) {
43
+ out.push(`!! Change ${schedule.pendingRevision.id} waits for the family (sent ${schedule.pendingRevision.requestedAt.slice(0, 10)}${schedule.pendingRevision.emailSentAt ? "" : ", email NOT sent"}). The rows it touches are held.`);
44
+ }
45
+ if (schedule.pausedAt) {
46
+ out.push(`!! Paused ${schedule.pausedAt.slice(0, 10)}${schedule.pausedNote ? `: ${schedule.pausedNote}` : ""}`);
47
+ }
48
+ out.push("", renderColumns([
49
+ ["#", "Status", "Amount", "Invoice", "Due", "Collection", "Label", "ID"],
50
+ ...schedule.installments.map((row) => [
51
+ String(row.sequence),
52
+ row.status,
53
+ `${dollars(row.amountCents)}${row.creditedCents ? ` (${dollars(row.amountCents - row.creditedCents)} after credit)` : ""}${row.refundedCents ? ` (${dollars(row.refundedCents)} refunded)` : ""}`,
54
+ row.invoiceDate,
55
+ row.dueDate,
56
+ row.collection,
57
+ `${row.label}${row.paidNote ? ` (${row.paidNote})` : ""}`,
58
+ row.id,
59
+ ]),
60
+ ]));
61
+ if (signed.length) {
62
+ out.push("", "As signed:", renderColumns([
63
+ ["Row", "Amount", "Invoice", "Due", "Label"],
64
+ ...signed.map((row) => [
65
+ String(row.sourceIndex + 1),
66
+ `${row.award === "PENDING" ? "up to " : ""}${dollars(row.amountCents)}`,
67
+ row.invoiceDate || "none",
68
+ row.dueDate || "none",
69
+ row.label,
70
+ ]),
71
+ ]));
72
+ }
73
+ if (events.length) {
74
+ out.push(...(revisions.length
75
+ ? [
76
+ "",
77
+ "Change record:",
78
+ ...revisions.flatMap((revision) => [
79
+ ` ${revision.createdAt.slice(0, 16).replace("T", " ")} ${revision.id} ${revision.status === "PENDING"
80
+ ? "WAITING FOR FAMILY"
81
+ : revision.status === "APPLYING"
82
+ ? "STOPPED PARTWAY: `recess tuition retry-change`"
83
+ : revision.status === "CANCELED"
84
+ ? `WITHDRAWN${revision.cancelReason ? `: ${revision.cancelReason}` : ""}`
85
+ : revision.consentedAt
86
+ ? `FAMILY CONSENTED (${revision.consentMethod === "PARENT_ONLINE" ? `online as "${revision.consentName}"` : `recorded: ${revision.consentName}`})`
87
+ : "APPLIED WITHOUT FAMILY CONSENT"}${revision.createdByName ? ` · by ${revision.createdByName}` : ""}${revision.reason ? ` · ${revision.reason}` : ""}`,
88
+ ...revision.operations.map((op) => ` ${op.op === "add"
89
+ ? `add ${op.label} ${dollars(op.amountCents)} due ${op.dueDate}`
90
+ : op.op === "void"
91
+ ? `remove #${op.sequence} ${op.label} ${dollars(op.amountCents)}${op.voidsInvoice ? " (invoice voided)" : ""}`
92
+ : `#${op.sequence} ${op.label}: ${JSON.stringify(op.before)} -> ${JSON.stringify(op.after)}${op.reissue ? " (invoice reissued)" : ""}`}`),
93
+ ]),
94
+ ]
95
+ : []), "", "History:", ...events.map((event) => ` ${event.at.slice(0, 16).replace("T", " ")} ${event.sequence === null ? "schedule" : `#${event.sequence}`} ${event.kind}${event.actorName ? ` by ${event.actorName}` : ""}${typeof event.detail?.reason === "string"
96
+ ? `: ${event.detail.reason}`
97
+ : ""}`));
98
+ }
99
+ return out.join("\n");
100
+ }
101
+ const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
102
+ const COLLECTIONS = {
103
+ invoice: "EMAIL_INVOICE",
104
+ "auto-charge": "AUTO_CHARGE",
105
+ "out-of-band": "OUT_OF_BAND",
106
+ };
107
+ const PAYERS = {
108
+ family: "FAMILY",
109
+ "az-esa": "AZ_ESA_CLASSWALLET",
110
+ "fl-scholarship": "FL_SCHOLARSHIP",
111
+ "partner-school": "PARTNER_SCHOOL",
112
+ };
113
+ /** `--ask-family [--family-note TEXT]`: hold the change for the family's approval. */
114
+ function askFamily(parsed) {
115
+ if (!hasFlag(parsed, "ask-family"))
116
+ return {};
117
+ const familyNote = flagString(parsed, "family-note")?.trim();
118
+ return { askFamily: true, ...(familyNote ? { familyNote } : {}) };
119
+ }
120
+ /** `--amount 1750` or `--amount 1750.50`, as cents. */
121
+ function centsFlag(parsed, name) {
122
+ const raw = flagString(parsed, name)
123
+ ?.trim()
124
+ .replace(/^\$/, "")
125
+ .replaceAll(",", "");
126
+ if (raw === undefined)
127
+ return undefined;
128
+ if (!/^\d+(\.\d{1,2})?$/.test(raw) || Number(raw) <= 0) {
129
+ throw new CliError("invalid_arguments", `--${name} takes dollars, e.g. --${name} 1750 or --${name} 1750.50.`);
130
+ }
131
+ return Math.round(Number(raw) * 100);
132
+ }
133
+ function dateFlag(parsed, name) {
134
+ const raw = flagString(parsed, name)?.trim();
135
+ if (raw === undefined)
136
+ return undefined;
137
+ if (!ISO_DATE.test(raw)) {
138
+ throw new CliError("invalid_arguments", `--${name} must be YYYY-MM-DD.`);
139
+ }
140
+ return raw;
141
+ }
142
+ function choiceFlag(parsed, name, values) {
143
+ const raw = flagString(parsed, name)?.trim().toLowerCase();
144
+ if (raw === undefined)
145
+ return undefined;
146
+ const value = values[raw];
147
+ if (!value) {
148
+ throw new CliError("invalid_arguments", `--${name} must be one of: ${Object.keys(values).join(", ")}.`);
149
+ }
150
+ return value;
151
+ }
152
+ function textFlag(parsed, name, required = false) {
153
+ const value = flagString(parsed, name)?.trim();
154
+ if (!value && required) {
155
+ throw new CliError("invalid_arguments", `Missing required --${name}.`);
156
+ }
157
+ return value || undefined;
158
+ }
159
+ /**
160
+ * `recess tuition`: the tuition schedules built from signed admission
161
+ * packets, and staff changes to installments no invoice has gone out for.
162
+ */
163
+ export async function runTuitionCommand({ parsed, api, writeCommand, }) {
164
+ const verb = parsed.positionals[1];
165
+ const json = hasFlag(parsed, "json");
166
+ if (verb === "list") {
167
+ const status = flagString(parsed, "status");
168
+ const family = flagString(parsed, "family");
169
+ const packet = flagString(parsed, "packet");
170
+ for (const [name, value] of [
171
+ ["family", family],
172
+ ["packet", packet],
173
+ ]) {
174
+ if (value && !UUID.test(value)) {
175
+ throw new CliError("invalid_arguments", `--${name} must be an ID.`);
176
+ }
177
+ }
178
+ const { schedules, counts } = unwrap(await api.client.GET("/admin/tuition-billing/", {
179
+ params: {
180
+ query: {
181
+ ...(status
182
+ ? {
183
+ status: assertChoice(status.toUpperCase().replaceAll("-", "_"), STATUSES, "--status"),
184
+ }
185
+ : {}),
186
+ ...(family ? { familyId: family } : {}),
187
+ ...(packet ? { packetId: packet } : {}),
188
+ ...(flagString(parsed, "q") ? { q: flagString(parsed, "q") } : {}),
189
+ limit: Number(flagString(parsed, "limit") ?? 100),
190
+ },
191
+ },
192
+ }));
193
+ if (json)
194
+ return { schedules, counts };
195
+ if (!schedules.length)
196
+ return { help: "No tuition schedules." };
197
+ return {
198
+ help: [
199
+ renderColumns([
200
+ ["Schedule", "Student", "Parent", "Payer", "Open", "Next", "Flags"],
201
+ ...schedules.map((s) => {
202
+ const next = nextOpen(s);
203
+ return [
204
+ s.id,
205
+ s.kidName,
206
+ `${s.parentName} <${s.parentEmail}>`,
207
+ s.payer,
208
+ dollars(s.openCents),
209
+ next
210
+ ? `${next.invoiceDate} ${dollars(next.amountCents)} ${next.status}`
211
+ : "nothing open",
212
+ [
213
+ s.needsReviewCount ? `${s.needsReviewCount} to review` : null,
214
+ s.pausedAt ? "paused" : null,
215
+ s.held ? "held" : null,
216
+ ]
217
+ .filter(Boolean)
218
+ .join(", "),
219
+ ];
220
+ }),
221
+ ]),
222
+ "",
223
+ `Installments: ${STATUSES.map((s) => `${counts[s] ?? 0} ${s}`).join(" · ")}`,
224
+ ].join("\n"),
225
+ };
226
+ }
227
+ if (verb === "show") {
228
+ const scheduleId = positional(parsed, 2, "schedule ID");
229
+ const detail = unwrap(await api.client.GET("/admin/tuition-billing/{scheduleId}", {
230
+ params: { path: { scheduleId } },
231
+ }));
232
+ return json ? detail : { help: renderSchedule(detail) };
233
+ }
234
+ /** After a change: the schedule as it now stands, with its history. */
235
+ const shown = async (schedule) => {
236
+ if (json)
237
+ return { schedule };
238
+ const detail = unwrap(await api.client.GET("/admin/tuition-billing/{scheduleId}", {
239
+ params: { path: { scheduleId: schedule.id } },
240
+ }));
241
+ return { help: renderSchedule(detail) };
242
+ };
243
+ if (verb === "edit") {
244
+ const installmentId = positional(parsed, 2, "installment ID");
245
+ const collection = flagString(parsed, "collection")?.trim().toLowerCase();
246
+ const body = {
247
+ ...(textFlag(parsed, "label")
248
+ ? { label: textFlag(parsed, "label") }
249
+ : {}),
250
+ ...(centsFlag(parsed, "amount") !== undefined
251
+ ? { amountCents: centsFlag(parsed, "amount") }
252
+ : {}),
253
+ ...(dateFlag(parsed, "invoice-date")
254
+ ? { invoiceDate: dateFlag(parsed, "invoice-date") }
255
+ : {}),
256
+ ...(dateFlag(parsed, "due-date")
257
+ ? { dueDate: dateFlag(parsed, "due-date") }
258
+ : {}),
259
+ ...(textFlag(parsed, "note") ? { note: textFlag(parsed, "note") } : {}),
260
+ ...askFamily(parsed),
261
+ // "default" clears the row's own method.
262
+ ...(collection === undefined
263
+ ? {}
264
+ : collection === "default"
265
+ ? { collection: null }
266
+ : { collection: choiceFlag(parsed, "collection", COLLECTIONS) }),
267
+ };
268
+ if (Object.keys(body).filter((key) => !["note", "askFamily", "familyNote"].includes(key)).length === 0) {
269
+ throw new CliError("invalid_arguments", "Nothing to change. Use --amount, --invoice-date, --due-date, --label or --collection.");
270
+ }
271
+ return writeCommand(parsed, {
272
+ action: body.askFamily
273
+ ? `propose a change to tuition installment ${installmentId} and EMAIL the family to approve it (nothing changes until they do)`
274
+ : `change tuition installment ${installmentId} now, without the family's consent (an invoiced installment is voided and reissued)`,
275
+ target: { installmentId },
276
+ request: body,
277
+ }, async () => shown(unwrap(await api.client.PATCH("/admin/tuition-billing/installments/{installmentId}", { params: { path: { installmentId } }, body })).schedule));
278
+ }
279
+ if (verb === "add") {
280
+ const scheduleId = positional(parsed, 2, "schedule ID");
281
+ const amountCents = centsFlag(parsed, "amount");
282
+ const invoiceDate = dateFlag(parsed, "invoice-date");
283
+ const dueDate = dateFlag(parsed, "due-date");
284
+ if (amountCents === undefined || !invoiceDate || !dueDate) {
285
+ throw new CliError("invalid_arguments", "Use --label TEXT --amount DOLLARS --invoice-date YYYY-MM-DD --due-date YYYY-MM-DD.");
286
+ }
287
+ const collection = choiceFlag(parsed, "collection", COLLECTIONS);
288
+ const note = textFlag(parsed, "note");
289
+ const body = {
290
+ label: textFlag(parsed, "label", true),
291
+ amountCents,
292
+ invoiceDate,
293
+ dueDate,
294
+ ...(collection ? { collection } : {}),
295
+ ...(note ? { note } : {}),
296
+ ...askFamily(parsed),
297
+ };
298
+ return writeCommand(parsed, {
299
+ action: `add a ${dollars(amountCents)} installment to tuition schedule ${scheduleId}`,
300
+ target: { scheduleId },
301
+ request: body,
302
+ }, async () => shown(unwrap(await api.client.POST("/admin/tuition-billing/{scheduleId}/installments", { params: { path: { scheduleId } }, body })).schedule));
303
+ }
304
+ if (verb === "release") {
305
+ const installmentId = positional(parsed, 2, "installment ID");
306
+ const note = textFlag(parsed, "note");
307
+ const body = note ? { note } : {};
308
+ return writeCommand(parsed, {
309
+ action: `release tuition installment ${installmentId} from review: it is still owed and will be scheduled`,
310
+ target: { installmentId },
311
+ request: body,
312
+ }, async () => shown(unwrap(await api.client.POST("/admin/tuition-billing/installments/{installmentId}/release", { params: { path: { installmentId } }, body })).schedule));
313
+ }
314
+ if (verb === "void" || verb === "reopen") {
315
+ const installmentId = positional(parsed, 2, "installment ID");
316
+ const body = {
317
+ reason: textFlag(parsed, "reason", true),
318
+ ...(verb === "void" ? askFamily(parsed) : {}),
319
+ };
320
+ return writeCommand(parsed, {
321
+ action: verb === "void"
322
+ ? "askFamily" in body
323
+ ? `propose voiding tuition installment ${installmentId} and EMAIL the family to approve it`
324
+ : `void tuition installment ${installmentId} now, without the family's consent (a sent invoice is voided in Stripe)`
325
+ : `reopen tuition installment ${installmentId}: it goes back to review and any staff-recorded payment is cleared`,
326
+ target: { installmentId },
327
+ request: body,
328
+ }, async () => shown(unwrap(verb === "void"
329
+ ? await api.client.POST("/admin/tuition-billing/installments/{installmentId}/void", { params: { path: { installmentId } }, body })
330
+ : await api.client.POST("/admin/tuition-billing/installments/{installmentId}/reopen", {
331
+ params: { path: { installmentId } },
332
+ body: { reason: body.reason },
333
+ })).schedule));
334
+ }
335
+ if (verb === "mark-paid") {
336
+ const installmentId = positional(parsed, 2, "installment ID");
337
+ const paidCents = centsFlag(parsed, "paid");
338
+ const paidOn = dateFlag(parsed, "paid-on");
339
+ const body = {
340
+ note: textFlag(parsed, "note", true),
341
+ ...(paidCents !== undefined ? { paidCents } : {}),
342
+ ...(paidOn ? { paidOn } : {}),
343
+ };
344
+ return writeCommand(parsed, {
345
+ action: `mark tuition installment ${installmentId} as paid outside Recess`,
346
+ target: { installmentId },
347
+ request: body,
348
+ }, async () => shown(unwrap(await api.client.POST("/admin/tuition-billing/installments/{installmentId}/mark-paid", { params: { path: { installmentId } }, body })).schedule));
349
+ }
350
+ if (verb === "pause" || verb === "resume" || verb === "set") {
351
+ const scheduleId = positional(parsed, 2, "schedule ID");
352
+ const note = textFlag(parsed, "note");
353
+ const payer = choiceFlag(parsed, "payer", PAYERS);
354
+ const defaultCollection = choiceFlag(parsed, "collection", COLLECTIONS);
355
+ const auto = choiceFlag(parsed, "auto-invoice", {
356
+ on: "on",
357
+ off: "off",
358
+ });
359
+ const body = verb === "pause"
360
+ ? { paused: true, ...(note ? { pausedNote: note } : {}) }
361
+ : verb === "resume"
362
+ ? { paused: false }
363
+ : {
364
+ ...(payer ? { payer } : {}),
365
+ ...(defaultCollection ? { defaultCollection } : {}),
366
+ ...(auto ? { autoInvoice: auto === "on" } : {}),
367
+ };
368
+ if (Object.keys(body).length === 0) {
369
+ throw new CliError("invalid_arguments", "Nothing to change. Use --payer family|az-esa|fl-scholarship|partner-school, --collection invoice|auto-charge|out-of-band, or --auto-invoice on|off.");
370
+ }
371
+ return writeCommand(parsed, {
372
+ action: verb === "pause"
373
+ ? `pause tuition schedule ${scheduleId}: nothing on it is drafted or sent while paused`
374
+ : verb === "resume"
375
+ ? `resume tuition schedule ${scheduleId}`
376
+ : `change tuition schedule ${scheduleId}'s settings${"autoInvoice" in body ? ` (automatic invoicing ${body.autoInvoice ? "ON: the daily run drafts, sends and chases its invoices" : "OFF"})` : ""}`,
377
+ target: { scheduleId },
378
+ request: body,
379
+ }, async () => shown(unwrap(await api.client.PATCH("/admin/tuition-billing/{scheduleId}", {
380
+ params: { path: { scheduleId } },
381
+ body,
382
+ })).schedule));
383
+ }
384
+ if (verb === "summary") {
385
+ const summary = unwrap(await api.client.GET("/admin/tuition-billing/summary"));
386
+ if (json)
387
+ return summary;
388
+ const t = summary.totals;
389
+ const a = summary.attention;
390
+ return [
391
+ `Tuition billing as of ${summary.today} (automatic invoicing ${summary.invoicingEnabled ? "on" : "off"} on this server)`,
392
+ "",
393
+ `Sold ${dollars(t.contracted.cents)} (${t.contracted.count} installments)`,
394
+ `Collected ${dollars(t.collected.cents)}`,
395
+ `Invoiced, open ${dollars(t.invoicedOpen.cents)} (${t.invoicedOpen.count})`,
396
+ `Past due ${dollars(t.pastDue.cents)} (${t.pastDue.count})`,
397
+ `Not yet invoiced ${dollars(t.notYetInvoiced.cents)} (${t.notYetInvoiced.count})`,
398
+ `Due in 30 days ${dollars(t.dueNext30Days.cents)} (${t.dueNext30Days.count})`,
399
+ `Earned ${dollars(t.earnedCents)} (uncollected ${dollars(t.earnedUncollectedCents)}, collected ahead ${dollars(t.collectedAheadCents)})`,
400
+ `Partner schools ${dollars(summary.partner.received.cents)} received of ${dollars(summary.partner.contracted.cents)}, ${dollars(summary.partner.overdue.cents)} overdue`,
401
+ "",
402
+ `Needs review ${a.needsReview} · invoiced by hand ${a.manualInvoicing} · changes waiting for family ${a.awaitingFamily} · applied without consent ${a.appliedWithoutConsent} · written notice due ${a.formalNoticeDue} · failed payments ${a.paymentFailed} · paused ${a.paused}`,
403
+ ...(summary.pastDue.length
404
+ ? [
405
+ "",
406
+ "Past due:",
407
+ renderColumns([
408
+ ["Due", "Days late", "Student", "Parent", "Owed", "Schedule"],
409
+ ...summary.pastDue.map((row) => [
410
+ row.dueDate,
411
+ String(row.daysPastDue),
412
+ row.kidName,
413
+ row.parentEmail,
414
+ dollars(row.outstandingCents),
415
+ row.scheduleId,
416
+ ]),
417
+ ]),
418
+ ]
419
+ : []),
420
+ ].join("\n");
421
+ }
422
+ if (verb === "draft" || verb === "send" || verb === "pull-back") {
423
+ const installmentId = positional(parsed, 2, "installment ID");
424
+ const path = { installmentId };
425
+ if (verb === "pull-back") {
426
+ const body = { reason: textFlag(parsed, "reason", true) };
427
+ return writeCommand(parsed, {
428
+ action: `pull back the Stripe draft for tuition installment ${installmentId}: the draft is deleted and the installment can be edited again`,
429
+ target: path,
430
+ request: body,
431
+ }, async () => shown(unwrap(await api.client.POST("/admin/tuition-billing/installments/{installmentId}/pull-back", { params: { path }, body })).schedule));
432
+ }
433
+ return writeCommand(parsed, {
434
+ action: verb === "draft"
435
+ ? `create the Stripe draft invoice for tuition installment ${installmentId}`
436
+ : `finalize the invoice for tuition installment ${installmentId} and EMAIL the family the payment request now`,
437
+ target: path,
438
+ request: {},
439
+ }, async () => shown(unwrap(verb === "draft"
440
+ ? await api.client.POST("/admin/tuition-billing/installments/{installmentId}/draft", { params: { path } })
441
+ : await api.client.POST("/admin/tuition-billing/installments/{installmentId}/send", { params: { path } })).schedule));
442
+ }
443
+ if (verb === "email") {
444
+ const installmentId = positional(parsed, 2, "installment ID");
445
+ const kind = choiceFlag(parsed, "kind", {
446
+ request: "REQUEST",
447
+ reminder: "REMINDER",
448
+ "past-due": "PAST_DUE",
449
+ }) ?? "REQUEST";
450
+ const body = { kind };
451
+ return writeCommand(parsed, {
452
+ action: `EMAIL the family about sent tuition installment ${installmentId} again (${kind.toLowerCase().replace("_", "-")})`,
453
+ target: { installmentId },
454
+ request: body,
455
+ }, async () => shown(unwrap(await api.client.POST("/admin/tuition-billing/installments/{installmentId}/email", { params: { path: { installmentId } }, body })).schedule));
456
+ }
457
+ if (verb === "retry-change") {
458
+ const revisionId = positional(parsed, 2, "change (revision) ID");
459
+ return writeCommand(parsed, {
460
+ action: `finish plan change ${revisionId}, which stopped partway (may cancel and reissue Stripe invoices and EMAIL the family new ones)`,
461
+ target: { revisionId },
462
+ request: {},
463
+ }, async () => shown(unwrap(await api.client.POST("/admin/tuition-billing/revisions/{revisionId}/retry", { params: { path: { revisionId } } })).schedule));
464
+ }
465
+ if (verb === "resend-approval" ||
466
+ verb === "record-consent" ||
467
+ verb === "withdraw") {
468
+ const revisionId = positional(parsed, 2, "change (revision) ID");
469
+ const path = { revisionId };
470
+ if (verb === "resend-approval") {
471
+ return writeCommand(parsed, {
472
+ action: `EMAIL the family the approval link for plan change ${revisionId} again`,
473
+ target: path,
474
+ request: {},
475
+ }, async () => shown(unwrap(await api.client.POST("/admin/tuition-billing/revisions/{revisionId}/resend", { params: { path } })).schedule));
476
+ }
477
+ if (verb === "record-consent") {
478
+ const body = { note: textFlag(parsed, "note", true) };
479
+ return writeCommand(parsed, {
480
+ action: `record the family's consent to plan change ${revisionId} (a change waiting for them is applied now)`,
481
+ target: path,
482
+ request: body,
483
+ }, async () => shown(unwrap(await api.client.POST("/admin/tuition-billing/revisions/{revisionId}/consent", { params: { path }, body })).schedule));
484
+ }
485
+ const body = { reason: textFlag(parsed, "reason", true) };
486
+ return writeCommand(parsed, {
487
+ action: `withdraw plan change ${revisionId}: nothing on the plan changes`,
488
+ target: path,
489
+ request: body,
490
+ }, async () => shown(unwrap(await api.client.POST("/admin/tuition-billing/revisions/{revisionId}/cancel", { params: { path }, body })).schedule));
491
+ }
492
+ if (verb === "auto-invoice") {
493
+ const mode = positional(parsed, 2, "on|off");
494
+ if (mode !== "on" && mode !== "off") {
495
+ throw new CliError("invalid_arguments", "Use `recess tuition auto-invoice on|off`.");
496
+ }
497
+ const scheduleIds = parsed.positionals.slice(3);
498
+ const all = hasFlag(parsed, "all");
499
+ if (!all && scheduleIds.length === 0) {
500
+ throw new CliError("invalid_arguments", "Name schedule IDs, or pass --all for every live schedule set the other way.");
501
+ }
502
+ const body = {
503
+ enabled: mode === "on",
504
+ ...(all ? { all: true } : { scheduleIds }),
505
+ };
506
+ const preview = unwrap(await api.client.POST("/admin/tuition-billing/auto-invoice", {
507
+ body: { ...body, dryRun: true },
508
+ }));
509
+ return writeCommand(parsed, {
510
+ action: `turn automatic invoicing ${mode.toUpperCase()} for ${preview.count} tuition schedule(s)${mode === "on" ? ": the daily run will draft, send and chase their invoices" : ""}`,
511
+ target: { scheduleIds: preview.scheduleIds },
512
+ request: body,
513
+ }, async () => unwrap(await api.client.POST("/admin/tuition-billing/auto-invoice", { body })));
514
+ }
515
+ throw new CliError("invalid_arguments", "Usage: recess tuition summary|list|show|edit|add|release|void|reopen|mark-paid|draft|send|pull-back|email|resend-approval|record-consent|withdraw|retry-change|auto-invoice|pause|resume|set. See `recess help`.");
516
+ }
517
+ //# sourceMappingURL=tuition.js.map
package/dist/help.js CHANGED
@@ -387,6 +387,27 @@ Usage:
387
387
  [--esa-award DOLLARS | --esa-award-unknown [--esa-scenarios DOLLARS,...]] [--custom-plan JSON|@file] [--custom-only]
388
388
  [--pdf <path>] [--open]
389
389
  recess [--json] tuition-plans states
390
+ recess [--json] tuition summary
391
+ recess [--json] tuition list [--status NEEDS_REVIEW|SCHEDULED|DRAFTED|SENT|PAID|PAID_OUT_OF_BAND|VOID] [--family <family-id>] [--packet <packet-id>] [--q TEXT] [--limit N]
392
+ recess [--json] tuition show <schedule-id>
393
+ recess [--json] tuition edit <installment-id> [--amount DOLLARS] [--invoice-date YYYY-MM-DD] [--due-date YYYY-MM-DD] [--label TEXT] [--collection invoice|auto-charge|out-of-band|default] [--note TEXT] [--ask-family [--family-note TEXT]] [--confirm]
394
+ recess [--json] tuition add <schedule-id> --label TEXT --amount DOLLARS --invoice-date YYYY-MM-DD --due-date YYYY-MM-DD [--collection invoice|auto-charge|out-of-band] [--note TEXT] [--ask-family [--family-note TEXT]] [--confirm]
395
+ recess [--json] tuition release <installment-id> [--note TEXT] [--confirm]
396
+ recess [--json] tuition void <installment-id> --reason TEXT [--ask-family [--family-note TEXT]] [--confirm]
397
+ recess [--json] tuition reopen <installment-id> --reason TEXT [--confirm]
398
+ recess [--json] tuition mark-paid <installment-id> --note TEXT [--paid DOLLARS] [--paid-on YYYY-MM-DD] [--confirm]
399
+ recess [--json] tuition draft <installment-id> [--confirm]
400
+ recess [--json] tuition send <installment-id> [--confirm]
401
+ recess [--json] tuition pull-back <installment-id> --reason TEXT [--confirm]
402
+ recess [--json] tuition email <installment-id> [--kind request|reminder|past-due] [--confirm]
403
+ recess [--json] tuition resend-approval <change-id> [--confirm]
404
+ recess [--json] tuition record-consent <change-id> --note TEXT [--confirm]
405
+ recess [--json] tuition withdraw <change-id> --reason TEXT [--confirm]
406
+ recess [--json] tuition retry-change <change-id> [--confirm]
407
+ recess [--json] tuition auto-invoice on|off (<schedule-id>... | --all) [--confirm]
408
+ recess [--json] tuition pause <schedule-id> [--note TEXT] [--confirm]
409
+ recess [--json] tuition resume <schedule-id> [--confirm]
410
+ recess [--json] tuition set <schedule-id> [--payer family|az-esa|fl-scholarship|partner-school] [--collection invoice|auto-charge|out-of-band] [--auto-invoice on|off] [--confirm]
390
411
  recess [--json] admissions create --school <institution-slug> --enrollment direct|partner-school|program
391
412
  [--partner-school <slug|id>] --parent "First Last" --email EMAIL [--phone TEXT] --state XX
392
413
  --kid "First Last:YYYY-MM-DD[:grade]" (repeat per child) [--existing-kid USER_ID[:grade]]...
@@ -751,6 +772,16 @@ Usage:
751
772
  recess [--json] flags remove <key> [--user <id,...>] [--email <email,...>] [--role <ROLE,...>]
752
773
  [--confirm]
753
774
  recess [--json] flags delete <key> [--confirm]
775
+ recess [--json] issues search [<text>...] [--status active|all|archived|open|in_progress|done|wont_do]
776
+ [--type bug|feature|request|task] [--limit N]
777
+ recess [--json] issues get <R-number>
778
+ recess [--json] issues create --title TEXT [--body TEXT] [--body-file <path.md>]
779
+ [--type bug|feature|request|task] [--severity minor|major|blocking] [--confirm]
780
+ recess [--json] issues update <R-number> [--title TEXT] [--body TEXT] [--body-file <path.md>]
781
+ [--type bug|feature|request|task] [--severity minor|major|blocking|none]
782
+ [--status open|in_progress|done|wont_do] [--confirm]
783
+ recess [--json] issues archive <R-number> [--confirm]
784
+ recess [--json] issues unarchive <R-number> [--confirm]
754
785
  recess [--json] tutor-templates list [--q TEXT] [--subject TEXT] [--grade N]
755
786
  recess [--json] tutor-templates get <slug>
756
787
  recess [--json] tutor-templates assign <slug> [--student <kid-id>] [--confirm]
@@ -929,6 +960,16 @@ account — the confirmed write's own response is the record of what changed.
929
960
  without +country is read as US), rejects invalid or already-taken numbers, and
930
961
  marks the new number unverified until the user's next phone sign-in.
931
962
 
963
+ Recess Issues (issues.recess.gg), admins only: "issues search" matches keywords
964
+ and meaning (no text lists the newest open and in-progress issues); --status
965
+ active is the default. "issues get" adds reports, the latest comments and
966
+ changes, and a group's children. Writes land as you, through the tracker's own
967
+ actions: "create" goes to the Backlog and never merges (its preview lists
968
+ similar issues, so update one instead of filing a duplicate); "update --status"
969
+ on a group moves its children too (never safety reports); done pays reporting
970
+ kids coins on Friday; "archive" hides it from every list until a new matching
971
+ report brings it back.
972
+
932
973
  "users birthday set" corrects any kid's birthday, e.g. a wrong-century year that
933
974
  makes "users get" show age 115 ("kid set-profile" reaches only your own kids).
934
975
  The preview shows the age before and after, and warns outside ages 3 to 21. The
@@ -1551,6 +1592,27 @@ export const COMMAND_SUMMARIES = {
1551
1592
  "channels members remove": "Remove members from a channel (soft).",
1552
1593
  "tuition-plans generate": "Compute a tuition plan sheet (web URL, optional PDF); stores nothing.",
1553
1594
  "tuition-plans states": "List states supported by tuition plans.",
1595
+ "tuition summary": "Billing totals (sold, collected, past due, earned) and the past-due list.",
1596
+ "tuition list": "List tuition schedules built from signed admission packets.",
1597
+ "tuition show": "One tuition schedule: its installments, the signed plan, the history.",
1598
+ "tuition edit": "Change an installment now (invoiced: void and reissue), or --ask-family first.",
1599
+ "tuition add": "Add an installment that was not on the signed plan.",
1600
+ "tuition release": "Release a past-dated installment from review.",
1601
+ "tuition void": "Void an installment (a Stripe draft is deleted, a sent invoice voided).",
1602
+ "tuition draft": "Create an installment's Stripe draft invoice now.",
1603
+ "tuition send": "Finalize an installment's invoice and email the family the payment request.",
1604
+ "tuition pull-back": "Delete an installment's Stripe draft so it can be edited.",
1605
+ "tuition email": "Email the family about a sent installment again (request, reminder, past-due).",
1606
+ "tuition resend-approval": "Email the family the approval link for a plan change waiting for them again.",
1607
+ "tuition record-consent": "Record a family's consent to a plan change (applies one still waiting).",
1608
+ "tuition withdraw": "Withdraw a plan change waiting for the family.",
1609
+ "tuition retry-change": "Finish a plan change that stopped partway.",
1610
+ "tuition auto-invoice": "Turn automatic invoicing on/off for schedules (--all: every one set the other way).",
1611
+ "tuition reopen": "Undo a void or a staff-recorded payment (back to review).",
1612
+ "tuition mark-paid": "Record an installment paid outside Recess.",
1613
+ "tuition pause": "Hold everything on a tuition schedule.",
1614
+ "tuition resume": "Resume a paused tuition schedule.",
1615
+ "tuition set": "Change a schedule's payer, default collection or automatic invoicing.",
1554
1616
  "placement give": "Give a kid the math or reading placement quest as a todo.",
1555
1617
  "placement show": "One kid's placement answers, mistakes, timing and sounds check.",
1556
1618
  "placement results": "Kids' placement quest results beside their latest MAP score.",
@@ -1760,6 +1822,12 @@ export const COMMAND_SUMMARIES = {
1760
1822
  "flags add": "Turn a flag on for more users, emails or roles.",
1761
1823
  "flags remove": "Stop targeting users, emails or roles with a flag.",
1762
1824
  "flags delete": "Delete a feature flag.",
1825
+ "issues search": "Search or list Recess Issues (issues.recess.gg).",
1826
+ "issues get": "Read one issue: reports, comments, changes, children.",
1827
+ "issues create": "File an issue in the Backlog, as you.",
1828
+ "issues update": "Edit an issue or set its status, as you.",
1829
+ "issues archive": "Archive an issue (hidden from every list).",
1830
+ "issues unarchive": "Bring an archived issue back.",
1763
1831
  "tutor-templates list": "List tutor templates.",
1764
1832
  "tutor-templates get": "Read one tutor template.",
1765
1833
  "tutor-templates assign": "Assign a tutor template to a kid.",
@@ -1830,6 +1898,7 @@ export const NOUN_SUMMARIES = {
1830
1898
  me: "Your own to-dos and challenges (a parent learning too).",
1831
1899
  channels: "Community channels and their members.",
1832
1900
  "tuition-plans": "Compute tuition plan sheets (stores nothing).",
1901
+ tuition: "Tuition billing: totals, schedules, invoices, and family approval of changes.",
1833
1902
  placement: "Give placement quests, one kid's results, results vs MAP, question bank, mastery sync.",
1834
1903
  feed: "Post messages to users' feeds.",
1835
1904
  changelog: "Preview, test and send changelog posts, and read past sends.",
@@ -1850,6 +1919,7 @@ export const NOUN_SUMMARIES = {
1850
1919
  memories: "Kid memory files and the context Rocky sees.",
1851
1920
  rocky: "A kid's Rocky personality settings; free Rocky grants and budgets.",
1852
1921
  flags: "Feature flags: on/off, everyone, and who they target by user, email or role.",
1922
+ issues: "Recess Issues (issues.recess.gg): search, get, create, update, archive.",
1853
1923
  "tutor-templates": "Tutor templates and their assignment to kids.",
1854
1924
  "library-books": "Book library: search the web, add and delete books, read status, reader stages, tags.",
1855
1925
  "math-curricula": "Math curricula and the goals a math review assigns (ADMIN, GUIDE).",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "recess-cli",
3
- "version": "3.53.0",
3
+ "version": "3.55.0",
4
4
  "description": "Safe Recess administration and family AI tools from the command line.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {