recess-cli 3.12.0 → 3.14.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/api.js CHANGED
@@ -233,6 +233,47 @@ export class RecessAdminApi {
233
233
  throw apiError(response.status, body);
234
234
  return body;
235
235
  }
236
+ /** The packet's tuition agreement as a PDF, to sign by hand. */
237
+ async downloadAdmissionContract(packetId, optionId) {
238
+ this.requireAuth();
239
+ const url = new URL(`/admin/admissions/${encodeURIComponent(packetId)}/contract`, this.config.apiOrigin);
240
+ if (optionId)
241
+ url.searchParams.set("option", optionId);
242
+ const response = await fetch(url, {
243
+ headers: cliRequestHeaders({ cookie: this.config.sessionCookie }, this.reason, this.clientTag),
244
+ });
245
+ noteServerCliVersions(response.headers);
246
+ if (!response.ok) {
247
+ const body = await readResponseBody(response);
248
+ throw apiError(response.status, body);
249
+ }
250
+ const disposition = response.headers.get("content-disposition") ?? "";
251
+ return {
252
+ bytes: new Uint8Array(await response.arrayBuffer()),
253
+ fileName: disposition.match(/filename="?([^";]+)"?/)?.[1] ??
254
+ `admission-${packetId}-agreement.pdf`,
255
+ optionId: response.headers.get("x-admission-option") ?? optionId ?? "",
256
+ };
257
+ }
258
+ /** Files a hand-signed agreement; fields go before the file. */
259
+ async uploadAdmissionSignedAgreement(packetId, pdf, fileName, fields) {
260
+ this.requireAuth();
261
+ const formData = new FormData();
262
+ if (fields.optionId)
263
+ formData.append("optionId", fields.optionId);
264
+ if (fields.note)
265
+ formData.append("note", fields.note);
266
+ const pdfBody = new Uint8Array(pdf.byteLength);
267
+ pdfBody.set(pdf);
268
+ formData.append("file", new Blob([pdfBody.buffer], { type: "application/pdf" }), fileName);
269
+ const headers = cliRequestHeaders({ cookie: this.config.sessionCookie }, this.reason, this.clientTag);
270
+ applyIdempotencyHeaders(headers);
271
+ const response = await fetch(new URL(`/admin/admissions/${encodeURIComponent(packetId)}/signed-agreement`, this.config.apiOrigin), { method: "POST", headers, body: formData });
272
+ const body = await readResponseBody(response);
273
+ if (!response.ok)
274
+ throw apiError(response.status, body);
275
+ return body;
276
+ }
236
277
  villageSession() {
237
278
  this.requireAuth();
238
279
  this.villageSessionPromise ??= (async () => {
package/dist/args.js CHANGED
@@ -19,6 +19,9 @@ export const REPEATABLE_FLAGS = new Set([
19
19
  */
20
20
  export const BOOLEAN_FLAGS = new Set([
21
21
  "keep-plan",
22
+ "custom-only",
23
+ "no-agreement",
24
+ "paywall-offline",
22
25
  "no-email",
23
26
  "no-paywall",
24
27
  "all",
package/dist/cli.js CHANGED
@@ -18,6 +18,7 @@ import { runRoomsCommand } from "./commands/rooms.js";
18
18
  import { runFeedCommand } from "./commands/feed.js";
19
19
  import { runFamiliesCommand } from "./commands/families.js";
20
20
  import { runStudentsTextsCommand, runUsersPhoneCommand, } from "./commands/phone-and-texts.js";
21
+ import { hasCommunityHour, runUsersCommunityHourCommand, } from "./commands/community-hour.js";
21
22
  import { runTuitionPlansCommand } from "./commands/tuition-plans.js";
22
23
  import { runReportsCommand } from "./commands/reports.js";
23
24
  import { runMasteryCommand } from "./commands/mastery.js";
@@ -2997,6 +2998,9 @@ export async function executeRecessCommand(argv, options = {}) {
2997
2998
  required: true,
2998
2999
  }),
2999
3000
  ...(tierId ? { tierId } : {}),
3001
+ ...(status === "WITHDRAWN" && flagString(parsed, "effective-at")
3002
+ ? { effectiveAt: flagString(parsed, "effective-at") }
3003
+ : {}),
3000
3004
  };
3001
3005
  return writeCommand(parsed, {
3002
3006
  action: status === "WITHDRAWN"
@@ -3102,6 +3106,9 @@ export async function executeRecessCommand(argv, options = {}) {
3102
3106
  if (noun === "users" && verb === "phone") {
3103
3107
  return runUsersPhoneCommand({ parsed, api, writeCommand });
3104
3108
  }
3109
+ if (noun === "users" && verb === "community-hour") {
3110
+ return runUsersCommunityHourCommand({ parsed, api, writeCommand });
3111
+ }
3105
3112
  if (noun === "users" && verb === "get") {
3106
3113
  const userId = positional(parsed, 2, "user ID");
3107
3114
  return unwrap(await api.client.GET("/admin/users/{userId}", {
@@ -3135,6 +3142,14 @@ export async function executeRecessCommand(argv, options = {}) {
3135
3142
  ...(target.role === "KID" ? [describe(target)] : []),
3136
3143
  ...(target.role === "KID" ? guardians.map(describe) : [describe(target)]),
3137
3144
  ];
3145
+ // Community Hour is a separate kid access role (`users community-hour`):
3146
+ // lock revokes it with the other kid roles, unlock does not grant it.
3147
+ const communityHourNow = target.role === "KID" ? hasCommunityHour(target.accessRoles) : null;
3148
+ const communityHourNote = locking && communityHourNow === true
3149
+ ? `Lock removes the kid's Community Hour access and "users unlock" will not restore it. Restore it with: recess users community-hour unlock ${target.id}`
3150
+ : !locking && communityHourNow === false
3151
+ ? `Account unlock does not grant Community Hour. To let the kid join Community Hour and enter the Village, also run: recess users community-hour unlock ${target.id}`
3152
+ : null;
3138
3153
  const preview = {
3139
3154
  userId: target.id,
3140
3155
  name: [target.firstName, target.lastName].filter(Boolean).join(" "),
@@ -3145,6 +3160,13 @@ export async function executeRecessCommand(argv, options = {}) {
3145
3160
  guardians.every((member) => isUnlocked(member.attributes))
3146
3161
  : isUnlocked(target.attributes),
3147
3162
  accountUnlockedAfter: !locking,
3163
+ ...(communityHourNow === null
3164
+ ? {}
3165
+ : {
3166
+ communityHourUnlockedNow: communityHourNow,
3167
+ communityHourUnlockedAfter: locking ? false : communityHourNow,
3168
+ }),
3169
+ ...(communityHourNote === null ? {} : { communityHourNote }),
3148
3170
  kidIds,
3149
3171
  guardianIds,
3150
3172
  affected,
@@ -3155,8 +3177,8 @@ export async function executeRecessCommand(argv, options = {}) {
3155
3177
  const body = { kidIds, guardianIds };
3156
3178
  return writeCommand(parsed, {
3157
3179
  action: locking
3158
- ? "lock the account: revoke the kid and guardian access roles, drop the kid from their Recess channels, and clear FLAG_ACCOUNT_UNLOCKED"
3159
- : "unlock the account: grant the kid and guardian access roles, restore the kid's Recess channel memberships, and set FLAG_ACCOUNT_UNLOCKED (the kid's clients are notified live)",
3180
+ ? "lock the account: revoke the kid and guardian access roles (including the kid's Community Hour access), drop the kid from their Recess channels, and clear FLAG_ACCOUNT_UNLOCKED"
3181
+ : "unlock the account: grant the kid and guardian access roles (not Community Hour; that is users community-hour unlock), restore the kid's Recess channel memberships, and set FLAG_ACCOUNT_UNLOCKED (the kid's clients are notified live)",
3160
3182
  target: { userId: target.id, kidIds, guardianIds },
3161
3183
  request: body,
3162
3184
  details: preview,
@@ -5865,6 +5887,20 @@ export async function executeRecessCommand(argv, options = {}) {
5865
5887
  },
5866
5888
  }));
5867
5889
  }
5890
+ if (verb === "math-academy") {
5891
+ const studentId = flagString(parsed, "student", { required: true });
5892
+ const startDate = flagString(parsed, "from");
5893
+ const endDate = flagString(parsed, "to");
5894
+ return unwrap(await api.client.GET("/tutor/students/{studentId}/math-academy", {
5895
+ params: {
5896
+ path: { studentId },
5897
+ query: {
5898
+ ...(startDate ? { startDate } : {}),
5899
+ ...(endDate ? { endDate } : {}),
5900
+ },
5901
+ },
5902
+ }));
5903
+ }
5868
5904
  if (verb === "issue-email") {
5869
5905
  const studentId = flagString(parsed, "student", { required: true });
5870
5906
  return writeCommand(parsed, {
@@ -155,6 +155,7 @@ const FAMILY_AI_COMMANDS = new Set([
155
155
  "skills guardian get",
156
156
  "skills guardian list",
157
157
  "students list",
158
+ "students math-academy",
158
159
  "students schedule",
159
160
  "students today",
160
161
  "students xp-history",
@@ -1,3 +1,6 @@
1
+ import { createHash } from "node:crypto";
2
+ import fs from "node:fs/promises";
3
+ import path from "node:path";
1
4
  import { unwrap } from "../api.js";
2
5
  import { flagList, flagString, hasFlag } from "../args.js";
3
6
  import { CliError } from "../errors.js";
@@ -17,13 +20,63 @@ const STEP_LABELS = {
17
20
  DONE: "done",
18
21
  };
19
22
  /** One packet as terminal text: who, where they are, and each kid's answers. */
20
- function renderPacket(packet, admissionUrl) {
23
+ /** One answer as text: yes/no, a confirmed checkbox, file names, a list. */
24
+ function answerText(value, type) {
25
+ if (typeof value === "boolean") {
26
+ return type === "checkbox"
27
+ ? value
28
+ ? "confirmed"
29
+ : ""
30
+ : value
31
+ ? "yes"
32
+ : "no";
33
+ }
34
+ if (value === null || value === undefined)
35
+ return "";
36
+ if (Array.isArray(value)) {
37
+ return value
38
+ .map((v) => typeof v === "object" && v && "fileName" in v
39
+ ? String(v.fileName)
40
+ : String(v))
41
+ .join("; ");
42
+ }
43
+ return typeof value === "object" ? JSON.stringify(value) : String(value);
44
+ }
45
+ /**
46
+ * A kid's answers under the questionnaire's sections, each line the question
47
+ * text. Keys the questionnaire doesn't know (an older version) print under
48
+ * "Other" by their raw key, so nothing is hidden.
49
+ */
50
+ function renderAnswers(responses, questions) {
51
+ const lines = [];
52
+ let section = null;
53
+ const push = (title, label, text) => {
54
+ if (!text)
55
+ return;
56
+ if (title !== section) {
57
+ lines.push(` ${title}`);
58
+ section = title;
59
+ }
60
+ lines.push(` ${label}`, ` ${text.replace(/\n/g, "\n ")}`);
61
+ };
62
+ for (const q of questions) {
63
+ if (q.id in responses)
64
+ push(q.section, q.label, answerText(responses[q.id], q.type));
65
+ }
66
+ const known = new Set(questions.map((q) => q.id));
67
+ for (const [key, value] of Object.entries(responses)) {
68
+ if (!known.has(key))
69
+ push("Other", key, answerText(value));
70
+ }
71
+ return lines;
72
+ }
73
+ function renderPacket(packet, admissionUrl, questions = []) {
21
74
  const when = (iso) => (iso ? iso.slice(0, 10) : "–");
22
75
  const out = [
23
76
  `ADMISSION PACKET ${packet.id}`,
24
77
  `${packet.parentFirstName} ${packet.parentLastName} <${packet.parentEmail}>${packet.parentPhone ? ` · ${packet.parentPhone}` : ""} · ${packet.stateCode}`,
25
- `${packet.enrollmentType === "PARTNER_SCHOOL" ? `Through ${packet.partnerSchool?.name ?? "partner school"}` : packet.enrollmentType === "PROGRAM" ? "Online learning program" : "Direct enrollment"} · ${packet.institution.name} · tier ${packet.tierId}${packet.paywallCents ? ` · paywall ${dollars(packet.paywallCents)}` : " · no paywall"}`,
26
- `Status: ${packet.status} (${STEP_LABELS[packet.step]})`,
78
+ `${packet.enrollmentType === "PARTNER_SCHOOL" ? `Through ${packet.partnerSchool?.name ?? "partner school"}` : packet.enrollmentType === "PROGRAM" ? "Online learning program" : "Direct enrollment"} · ${packet.institution.name} · tier ${packet.tierId}${packet.paywallOutOfBand ? ` · out-of-band paywall${packet.paywallCents ? ` ${dollars(packet.paywallCents)}` : " (the signed plan's first invoice)"}` : packet.paywallCents ? ` · paywall ${dollars(packet.paywallCents)}` : " · no paywall"}`,
79
+ `Status: ${packet.status} (${STEP_LABELS[packet.step]})${packet.noAgreement ? " · no tuition agreement" : ""}`,
27
80
  packet.financialAidApplication
28
81
  ? `Financial aid answers in the envelope: application ${packet.financialAidApplication.id} (${packet.financialAidApplication.createdAt.slice(0, 10)})`
29
82
  : "No financial aid application attached (nothing to initial).",
@@ -37,14 +90,24 @@ function renderPacket(packet, admissionUrl) {
37
90
  ],
38
91
  [
39
92
  " Signed",
40
- when(packet.signedAt),
41
- packet.chosenOptionId
42
- ? `option ${packet.chosenOptionId}${packet.documensoEnvelopeId ? ` · documenso ${packet.documensoEnvelopeId}` : ""}`
43
- : "",
93
+ packet.noAgreement ? "–" : when(packet.signedAt),
94
+ packet.noAgreement
95
+ ? "no agreement (skipped)"
96
+ : packet.chosenOptionId
97
+ ? `option ${packet.chosenOptionId}${packet.documensoEnvelopeId ? ` · documenso ${packet.documensoEnvelopeId}` : ""}`
98
+ : "",
44
99
  ],
45
100
  [" Consent", when(packet.consentedAt), ""],
46
101
  [" Questions", when(packet.questionsCompletedAt), ""],
47
- ...(packet.paywallCents ? [[" Paid", when(packet.paidAt), ""]] : []),
102
+ ...(packet.paywallCents || packet.paywallOutOfBand
103
+ ? [
104
+ [
105
+ " Paid",
106
+ when(packet.paidAt),
107
+ packet.paywallOutOfBand ? "out of band (staff mark it paid)" : "",
108
+ ],
109
+ ]
110
+ : []),
48
111
  [" Complete", when(packet.completedAt), ""],
49
112
  ]),
50
113
  ];
@@ -55,11 +118,19 @@ function renderPacket(packet, admissionUrl) {
55
118
  out.push("", "Agreed plan (as signed):");
56
119
  for (const kid of packet.agreedPlan) {
57
120
  out.push(` ${kid.studentName}: ${kid.term.label}, ${kid.payment.label.toLowerCase()} · ${kid.term.startDate} to ${kid.term.endDate} (${kid.term.instructionalDays} days) · total ${dollars(kid.payment.totalCents)}${kid.payment.discountCents ? ` (saves ${dollars(kid.payment.discountCents)})` : ""}`);
58
- for (const inst of kid.installments) {
121
+ for (const row of kid.customRows ?? []) {
122
+ out.push(` ${row.label}: ${row.amountText ?? dollars(row.amountCents ?? 0)} · ${row.whenText ?? `invoiced ${row.date}`}${row.note ? ` (${row.note})` : ""}`);
123
+ }
124
+ for (const inst of kid.customRows?.length ? [] : kid.installments) {
59
125
  out.push(` ${inst.label}: ${dollars(inst.amountCents)}${inst.award === "PENDING" ? " at most, set once the award is confirmed" : ""} · invoiced ${inst.invoiceDate} · due ${inst.dueDate}`);
60
126
  }
61
127
  }
62
128
  }
129
+ if (packet.status === "ACCOUNT_CREATED" &&
130
+ packet.chosenOptionId &&
131
+ !packet.documensoEnvelopeId) {
132
+ out.push("", `Waiting on a hand-signed contract (option ${packet.chosenOptionId}): download it with \`recess admissions contract ${packet.id}\`, then file the signed copy with \`recess admissions upload-signed ${packet.id} --file <pdf>\`.`);
133
+ }
63
134
  if (packet.signedAt) {
64
135
  out.push(packet.signedAgreementKey
65
136
  ? `Signed agreement archived ${when(packet.signedAgreementAt)}: ${packet.signedAgreementKey}`
@@ -70,23 +141,14 @@ function renderPacket(packet, admissionUrl) {
70
141
  out.push("", "Kids:");
71
142
  for (const kid of packet.kids) {
72
143
  out.push(` ${kid.firstName}${kid.lastName ? ` ${kid.lastName}` : ""}${kid.birthdate ? ` · born ${kid.birthdate}` : ""}${kid.grade ? ` · grade ${kid.grade}` : ""}${kid.gender ? ` · gender ${kid.gender}` : ""}${kid.ethnicity ? ` · ethnicity ${kid.ethnicity}` : ""}${kid.hispanicLatino ? ` · Hispanic/Latino ${kid.hispanicLatino}` : ""}${kid.kidUserId ? ` · user ${kid.kidUserId}` : ""}`);
73
- if (kid.responses) {
74
- for (const [key, value] of Object.entries(kid.responses)) {
75
- const shown = Array.isArray(value)
76
- ? value
77
- .map((v) => typeof v === "object" && v && "fileName" in v
78
- ? String(v.fileName)
79
- : String(v))
80
- .join("; ")
81
- : String(value);
82
- if (shown)
83
- out.push(` ${key}: ${shown}`);
84
- }
85
- }
144
+ if (kid.responses)
145
+ out.push(...renderAnswers(kid.responses, questions));
86
146
  }
87
- out.push("", `Plan spec: ${Object.entries(packet.planSpec)
88
- .map(([k, v]) => `${k}=${Array.isArray(v) ? v.join("|") : String(v)}`)
89
- .join(" ")}`);
147
+ out.push("", packet.noAgreement
148
+ ? "Plan spec: none (no tuition agreement)"
149
+ : `Plan spec: ${Object.entries(packet.planSpec)
150
+ .map(([k, v]) => `${k}=${Array.isArray(v) ? v.join("|") : String(v)}`)
151
+ .join(" ")}`);
90
152
  if (packet.staffNotes)
91
153
  out.push(`Staff notes: ${packet.staffNotes}`);
92
154
  if (admissionUrl)
@@ -105,6 +167,16 @@ const STATUSES = [
105
167
  export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
106
168
  const verb = parsed.positionals[1];
107
169
  const json = hasFlag(parsed, "json");
170
+ // Write responses carry the packet but not the questionnaire; fetch the
171
+ // labels only when there are answers to print.
172
+ const render = async (packet, admissionUrl) => {
173
+ const questions = packet.kids.some((k) => k.responses)
174
+ ? unwrap(await api.client.GET("/admin/admissions/{packetId}", {
175
+ params: { path: { packetId: packet.id } },
176
+ })).questions
177
+ : [];
178
+ return renderPacket(packet, admissionUrl, questions);
179
+ };
108
180
  if (verb === "list") {
109
181
  const status = flagString(parsed, "status");
110
182
  const { packets } = unwrap(await api.client.GET("/admin/admissions/", {
@@ -142,10 +214,12 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
142
214
  }
143
215
  if (verb === "get") {
144
216
  const packetId = positional(parsed, 2, "packet ID");
145
- const { packet } = unwrap(await api.client.GET("/admin/admissions/{packetId}", {
217
+ const { packet, questions } = unwrap(await api.client.GET("/admin/admissions/{packetId}", {
146
218
  params: { path: { packetId } },
147
219
  }));
148
- return json ? { packet } : { help: renderPacket(packet) };
220
+ return json
221
+ ? { packet }
222
+ : { help: renderPacket(packet, undefined, questions) };
149
223
  }
150
224
  if (verb === "create") {
151
225
  const parentName = flagString(parsed, "parent", { required: true })
@@ -186,12 +260,24 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
186
260
  if (paywall !== undefined && (!Number.isFinite(paywall) || paywall <= 0)) {
187
261
  throw new CliError("invalid_arguments", "--paywall must be a positive dollar amount (the family share to collect in the dashboard).");
188
262
  }
189
- const plan = parseTuitionPlanSpecFlags(parsed);
263
+ const noAgreement = hasFlag(parsed, "no-agreement");
264
+ if (noAgreement &&
265
+ (flagString(parsed, "start") || flagString(parsed, "annual"))) {
266
+ throw new CliError("invalid_arguments", "--no-agreement takes no tuition plan; drop --start/--annual and the other plan flags.");
267
+ }
268
+ const plan = noAgreement ? null : parseTuitionPlanSpecFlags(parsed);
269
+ const offline = hasFlag(parsed, "paywall-offline");
270
+ if (noAgreement && offline) {
271
+ throw new CliError("invalid_arguments", "--paywall-offline bills the signed plan's first invoice, so it needs an agreement. Use --paywall DOLLARS instead.");
272
+ }
273
+ if (offline && paywall !== undefined) {
274
+ throw new CliError("invalid_arguments", "Use --paywall DOLLARS (card) or --paywall-offline (the plan's first invoice, marked paid by staff), not both.");
275
+ }
190
276
  const warnings = [];
191
277
  if (paywall !== undefined && enrollment === "PARTNER_SCHOOL") {
192
278
  warnings.push("A paywall on a partner-school enrollment is unusual: the partner usually invoices.");
193
279
  }
194
- if (paywall !== undefined && plan.stateFunding === "true") {
280
+ if (paywall !== undefined && plan?.stateFunding === "true") {
195
281
  warnings.push("A paywall on an ESA-funded plan is unusual: those invoices are paid later from the award.");
196
282
  }
197
283
  const staffNotes = flagList(parsed, "staff-note")
@@ -219,15 +305,18 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
219
305
  ? { tierId: flagString(parsed, "tier") }
220
306
  : {}),
221
307
  kids,
222
- plan: plan,
308
+ ...(plan
309
+ ? { plan: plan }
310
+ : { noAgreement: true }),
223
311
  ...(paywall !== undefined
224
312
  ? { paywallCents: Math.round(paywall * 100) }
225
313
  : {}),
314
+ ...(offline ? { paywallOutOfBand: true } : {}),
226
315
  ...(staffNotes ? { staffNotes } : {}),
227
316
  sendEmail: !hasFlag(parsed, "no-email"),
228
317
  };
229
318
  return writeCommand(parsed, {
230
- action: `create an admission packet for ${body.parentEmail} (${kids.map((k) => k.firstName).join(", ")}) and ${body.sendEmail ? "email them the link" : "return the link without emailing"}`,
319
+ action: `create an admission packet${noAgreement ? " without a tuition agreement" : ""} for ${body.parentEmail} (${kids.map((k) => k.firstName).join(", ")}) and ${body.sendEmail ? "email them the link" : "return the link without emailing"}`,
231
320
  target: { parentEmail: body.parentEmail, school: body.institutionSlug },
232
321
  request: body,
233
322
  ...(warnings.length ? { details: { warnings } } : {}),
@@ -237,10 +326,16 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
237
326
  return result;
238
327
  return {
239
328
  help: [
240
- renderPacket(result.packet, result.admissionUrl),
329
+ await render(result.packet, result.admissionUrl),
241
330
  "",
242
- `Tuition plan: ${result.plan.introduction}`,
243
- ...result.plan.options.map((o) => ` ${o.id}: ${o.label} ${dollars(o.totalCents)}`),
331
+ ...(result.plan
332
+ ? [
333
+ `Tuition plan: ${result.plan.introduction}`,
334
+ ...result.plan.options.map((o) => ` ${o.id}: ${o.label} ${dollars(o.totalCents)}`),
335
+ ]
336
+ : [
337
+ "No tuition agreement: the parent goes from the account to consent.",
338
+ ]),
244
339
  "",
245
340
  result.emailed
246
341
  ? `Emailed ${result.packet.parentEmail}.`
@@ -264,7 +359,7 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
264
359
  }));
265
360
  return json
266
361
  ? result
267
- : { help: renderPacket(result.packet, result.admissionUrl) };
362
+ : { help: await render(result.packet, result.admissionUrl) };
268
363
  });
269
364
  }
270
365
  if (verb === "void") {
@@ -279,7 +374,7 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
279
374
  params: { path: { packetId } },
280
375
  body: { reason },
281
376
  }));
282
- return json ? result : { help: renderPacket(result.packet) };
377
+ return json ? result : { help: await render(result.packet) };
283
378
  });
284
379
  }
285
380
  if (verb === "mark-signed") {
@@ -295,7 +390,7 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
295
390
  params: { path: { packetId } },
296
391
  body: { optionId, ...(note ? { note } : {}) },
297
392
  }));
298
- return json ? result : { help: renderPacket(result.packet) };
393
+ return json ? result : { help: await render(result.packet) };
299
394
  });
300
395
  }
301
396
  if (verb === "requote") {
@@ -304,14 +399,23 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
304
399
  // wants monthly after signing pay in full); otherwise the plan flags
305
400
  // replace it.
306
401
  const keepPlan = hasFlag(parsed, "keep-plan");
307
- const plan = keepPlan ? null : parseTuitionPlanSpecFlags(parsed);
402
+ const dropAgreement = hasFlag(parsed, "no-agreement");
403
+ if (keepPlan && dropAgreement) {
404
+ throw new CliError("invalid_arguments", "Use --keep-plan, --no-agreement or new plan flags, not a mix.");
405
+ }
406
+ const plan = keepPlan || dropAgreement ? null : parseTuitionPlanSpecFlags(parsed);
308
407
  const paywallRaw = flagString(parsed, "paywall")?.replace(/[$,]/g, "");
309
408
  const paywall = paywallRaw === undefined ? undefined : Number(paywallRaw);
310
409
  if (paywall !== undefined && (!Number.isFinite(paywall) || paywall <= 0)) {
311
410
  throw new CliError("invalid_arguments", "--paywall must be a positive dollar amount; --no-paywall removes it.");
312
411
  }
313
- if (paywall !== undefined && hasFlag(parsed, "no-paywall")) {
314
- throw new CliError("invalid_arguments", "Use --paywall DOLLARS or --no-paywall, not both.");
412
+ const offlinePaywall = hasFlag(parsed, "paywall-offline");
413
+ if ([
414
+ paywall !== undefined,
415
+ hasFlag(parsed, "no-paywall"),
416
+ offlinePaywall,
417
+ ].filter(Boolean).length > 1) {
418
+ throw new CliError("invalid_arguments", "Use one of --paywall DOLLARS, --paywall-offline or --no-paywall.");
315
419
  }
316
420
  const note = flagString(parsed, "note")?.trim();
317
421
  // Undefined keeps the packet's paywall; null removes it.
@@ -322,11 +426,16 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
322
426
  : undefined;
323
427
  const body = {
324
428
  ...(plan ? { plan: plan } : {}),
325
- ...(paywallCents !== undefined ? { paywallCents } : {}),
429
+ ...(dropAgreement ? { noAgreement: true } : {}),
430
+ ...(offlinePaywall
431
+ ? { paywallOutOfBand: true }
432
+ : paywallCents !== undefined
433
+ ? { paywallCents }
434
+ : {}),
326
435
  ...(note ? { note } : {}),
327
436
  };
328
437
  return writeCommand(parsed, {
329
- action: `requote admission packet ${packetId}: ${keepPlan ? "reopen the payment choice on the same plan" : "replace its tuition plan"}${paywallCents === null ? " and remove the paywall" : paywallCents ? ` and set the paywall to ${dollars(paywallCents)}` : ""}; the family signs again from the same link`,
438
+ action: `requote admission packet ${packetId}: ${dropAgreement ? "drop the tuition agreement (no plan or signing)" : keepPlan ? "reopen the payment choice on the same plan" : "replace its tuition plan"}${offlinePaywall ? " and collect the first invoice out of band" : paywallCents === null ? " and remove the paywall" : paywallCents ? ` and set the paywall to ${dollars(paywallCents)}` : ""}; ${dropAgreement ? "the family continues from the same link without signing" : "the family signs again from the same link"}`,
330
439
  target: { packetId },
331
440
  request: body,
332
441
  }, async () => {
@@ -334,7 +443,7 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
334
443
  params: { path: { packetId } },
335
444
  body,
336
445
  }));
337
- return json ? result : { help: renderPacket(result.packet) };
446
+ return json ? result : { help: await render(result.packet) };
338
447
  });
339
448
  }
340
449
  if (verb === "archive-agreement") {
@@ -348,10 +457,79 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
348
457
  return json
349
458
  ? result
350
459
  : {
351
- help: `${result.archived ? "Archived." : "Nothing to archive yet: the envelope is not complete, or the packet was signed outside Documenso."}\n\n${renderPacket(result.packet)}`,
460
+ help: `${result.archived ? "Archived." : "Nothing to archive yet: the envelope is not complete, or the packet was signed outside Documenso."}\n\n${await render(result.packet)}`,
461
+ };
462
+ });
463
+ }
464
+ if (verb === "mark-paid") {
465
+ const packetId = positional(parsed, 2, "packet ID");
466
+ const note = flagString(parsed, "note")?.trim();
467
+ return writeCommand(parsed, {
468
+ action: `mark admission packet ${packetId}'s first invoice as paid out of band: this unblocks class registration and completes enrollment`,
469
+ target: { packetId },
470
+ request: note ? { note } : {},
471
+ }, async () => {
472
+ const result = unwrap(await api.client.POST("/admin/admissions/{packetId}/mark-paid", {
473
+ params: { path: { packetId } },
474
+ body: note ? { note } : {},
475
+ }));
476
+ return json ? result : { help: await render(result.packet) };
477
+ });
478
+ }
479
+ if (verb === "contract") {
480
+ const packetId = positional(parsed, 2, "packet ID");
481
+ const option = flagString(parsed, "option");
482
+ const contract = await api.downloadAdmissionContract(packetId, option);
483
+ const out = path.resolve(flagString(parsed, "out") ?? contract.fileName);
484
+ await fs.writeFile(out, contract.bytes);
485
+ const result = {
486
+ packetId,
487
+ optionId: contract.optionId,
488
+ path: out,
489
+ bytes: contract.bytes.byteLength,
490
+ };
491
+ return json
492
+ ? result
493
+ : {
494
+ help: `Saved the agreement for option ${contract.optionId} to ${out}. Once it's signed, file it with \`recess admissions upload-signed ${packetId} --file <pdf>\`.`,
495
+ };
496
+ }
497
+ if (verb === "upload-signed") {
498
+ const packetId = positional(parsed, 2, "packet ID");
499
+ const filePath = path.resolve(flagString(parsed, "file", { required: true }));
500
+ const optionId = flagString(parsed, "option");
501
+ const note = flagString(parsed, "note")?.trim();
502
+ let bytes;
503
+ try {
504
+ bytes = new Uint8Array(await fs.readFile(filePath));
505
+ }
506
+ catch {
507
+ throw new CliError("invalid_arguments", `Can't read --file ${filePath}.`);
508
+ }
509
+ if (Buffer.from(bytes.subarray(0, 5)).toString("latin1") !== "%PDF-") {
510
+ throw new CliError("invalid_arguments", `${filePath} isn't a PDF.`);
511
+ }
512
+ const fileName = path.basename(filePath);
513
+ const sha256 = createHash("sha256").update(bytes).digest("hex");
514
+ return writeCommand(parsed, {
515
+ action: `file ${fileName} as admission packet ${packetId}'s signed agreement; if the packet is waiting on signature this records the signature${optionId ? ` for option ${optionId}` : " for the option the parent chose"} and moves the family to consent`,
516
+ target: { packetId },
517
+ request: {
518
+ fileName,
519
+ bytes: bytes.byteLength,
520
+ sha256,
521
+ ...(optionId ? { optionId } : {}),
522
+ ...(note ? { note } : {}),
523
+ },
524
+ }, async () => {
525
+ const result = (await api.uploadAdmissionSignedAgreement(packetId, bytes, fileName, { ...(optionId ? { optionId } : {}), ...(note ? { note } : {}) }));
526
+ return json
527
+ ? result
528
+ : {
529
+ help: `${result.signed ? "Signed agreement filed and the signature recorded." : "Signed agreement filed (the packet was already past signing)."}\n\n${await render(result.packet)}`,
352
530
  };
353
531
  });
354
532
  }
355
- throw new CliError("invalid_arguments", "Usage: recess admissions create|get|list|resend|void|mark-signed|requote|archive-agreement. See `recess help`.");
533
+ throw new CliError("invalid_arguments", "Usage: recess admissions create|get|list|resend|void|mark-signed|upload-signed|contract|mark-paid|requote|archive-agreement. See `recess help`.");
356
534
  }
357
535
  //# sourceMappingURL=admissions.js.map
@@ -0,0 +1,55 @@
1
+ import { unwrap } from "../api.js";
2
+ import { CliError } from "../errors.js";
3
+ import { positional } from "./shared.js";
4
+ /**
5
+ * Community Hour access is this one access role (permission
6
+ * `recess:join-event`): the gate for joining Community Hour and entering the
7
+ * Village. Account unlock does not grant it; account lock revokes it.
8
+ */
9
+ const COMMUNITY_HOUR_ROLE = "recess:participant";
10
+ export function hasCommunityHour(accessRoles) {
11
+ return (accessRoles ?? []).some((role) => role.name === COMMUNITY_HOUR_ROLE);
12
+ }
13
+ /**
14
+ * `users community-hour get|unlock|lock` — the CLI twin of the "Unlock
15
+ * Community Hour" / "Lock Community Hour" button on the student admin page.
16
+ * One kid per run; the server's PATCH is a set-to, so a rerun is harmless.
17
+ */
18
+ export async function runUsersCommunityHourCommand({ parsed, api, writeCommand, }) {
19
+ const action = positional(parsed, 2, "users community-hour action");
20
+ if (!["get", "unlock", "lock"].includes(action)) {
21
+ throw new CliError("invalid_arguments", "Use users community-hour get|unlock|lock.");
22
+ }
23
+ const userId = positional(parsed, 3, "kid ID");
24
+ const { user } = unwrap(await api.client.GET("/admin/users/{userId}", {
25
+ params: { path: { userId } },
26
+ }));
27
+ const current = {
28
+ userId: user.id,
29
+ name: [user.firstName, user.lastName].filter(Boolean).join(" "),
30
+ role: user.role,
31
+ communityHourUnlocked: hasCommunityHour(user.accessRoles),
32
+ accountUnlocked: (user.attributes ?? []).some((attribute) => attribute.attribute === "FLAG_ACCOUNT_UNLOCKED"),
33
+ };
34
+ if (user.role !== "KID") {
35
+ throw new CliError("invalid_arguments", `${current.name || user.id} is a ${user.role}, not a KID. Community Hour access is per kid: pass the kid's user ID.`, 1, { current });
36
+ }
37
+ if (action === "get")
38
+ return current;
39
+ const enabled = action === "unlock";
40
+ return writeCommand(parsed, {
41
+ action: enabled
42
+ ? "unlock Community Hour for this kid: they can join Community Hour and enter the Village (the Village picks it up within about 30 seconds; the kid's open screens update on their next reload). A kid with no Community Hour group is assigned one first. Account unlock, app and chat access are unchanged"
43
+ : "lock Community Hour for this kid: they can no longer join Community Hour or enter the Village. Account unlock, app and chat access are unchanged",
44
+ target: { userId: user.id },
45
+ request: { enabled },
46
+ details: { current, communityHourUnlockedAfter: enabled },
47
+ }, async () => {
48
+ unwrap(await api.client.PATCH("/admin/users/{userId}/community-hour", {
49
+ params: { path: { userId: user.id } },
50
+ body: { enabled },
51
+ }));
52
+ return { ...current, communityHourUnlocked: enabled };
53
+ });
54
+ }
55
+ //# sourceMappingURL=community-hour.js.map
@@ -1,3 +1,4 @@
1
+ import { readFileSync } from "node:fs";
1
2
  import fs from "node:fs/promises";
2
3
  import path from "node:path";
3
4
  import { unwrap } from "../api.js";
@@ -66,16 +67,25 @@ function renderPlan(plan, webUrl, pdfPath) {
66
67
  for (const o of plan.options) {
67
68
  out.push("", `${o.label.toUpperCase()} (${o.startDate} → ${o.endDate}, ${o.instructionalDays} school days)`, ` ${o.description}`, renderColumns(o.paymentPlans.map((p) => [
68
69
  ` ${p.label}`,
69
- `${esa && p.kind !== "PAY_IN_FULL" ? "you pay at most " : ""}${dollars(p.totalCents)}`,
70
+ p.kind === "STAFF_CUSTOM"
71
+ ? "custom"
72
+ : `${esa && p.kind !== "PAY_IN_FULL" ? "you pay at most " : ""}${dollars(p.totalCents)}`,
70
73
  p.summary,
71
74
  p.scheduleLine,
72
75
  ])),
73
76
  // Award unknown: each payment is billed as is, or a ceiling for now.
74
77
  ...(esa
75
78
  ? o.paymentPlans
76
- .filter((p) => p.kind !== "PAY_IN_FULL")
79
+ .filter((p) => p.kind !== "PAY_IN_FULL" && p.kind !== "STAFF_CUSTOM")
77
80
  .flatMap((p) => p.installments.map((inst) => ` ${p.kind === "MONTHLY" ? `invoiced ${inst.invoiceDate}, due ${inst.dueDate}` : `${inst.serviceStart} → ${inst.serviceEnd}`} tuition ${dollars(inst.fullTuitionCents ?? inst.amountCents)} you pay ${inst.award === "NONE" ? dollars(inst.amountCents) : `up to ${dollars(inst.amountCents)}`}${inst.illustrativeNote ? ` (${inst.illustrativeNote})` : ""} ${inst.note ?? ""}`))
78
- : []));
81
+ : []),
82
+ // A staff-written option: every row as the family will see it.
83
+ ...o.paymentPlans
84
+ .filter((p) => p.kind === "STAFF_CUSTOM")
85
+ .flatMap((p) => [
86
+ ` ${p.label.toUpperCase()} (custom): ${p.description}`,
87
+ ...(p.customRows ?? []).map((r) => ` ${r.label} ${r.amountText ?? dollars(r.amountCents ?? 0)} ${r.whenText ?? `invoiced ${r.date}`}${r.note ? ` ${r.note}` : ""}`),
88
+ ]));
79
89
  }
80
90
  if (plan.staffNotes.length) {
81
91
  out.push("", "Notes:", ...plan.staffNotes.map((n) => ` ${n}`));
@@ -178,6 +188,32 @@ export function parseTuitionPlanSpecFlags(parsed) {
178
188
  throw new CliError("invalid_arguments", "--esa-scenarios takes up to six dollar amounts, comma-separated (e.g. 7300,14000,34000).");
179
189
  }
180
190
  }
191
+ // A staff-written option, as JSON inline or `@path/to/plan.json`; the
192
+ // server validates it (CustomPlanSpecSchema).
193
+ const customRaw = flagString(parsed, "custom-plan")?.trim();
194
+ let customPlan;
195
+ if (customRaw) {
196
+ const text = customRaw.startsWith("@")
197
+ ? (() => {
198
+ try {
199
+ return readFileSync(path.resolve(customRaw.slice(1)), "utf-8");
200
+ }
201
+ catch {
202
+ throw new CliError("invalid_arguments", `Can't read --custom-plan file ${customRaw.slice(1)}.`);
203
+ }
204
+ })()
205
+ : customRaw;
206
+ try {
207
+ customPlan = JSON.stringify(JSON.parse(text));
208
+ }
209
+ catch {
210
+ throw new CliError("invalid_arguments", "--custom-plan takes JSON (or @file.json): {label, summary?, clause?, continueFrom?, rows: [{label, note?, amount?, amountText?, date?, when?}]}.");
211
+ }
212
+ }
213
+ const customOnly = hasFlag(parsed, "custom-only");
214
+ if (customOnly && !customPlan) {
215
+ throw new CliError("invalid_arguments", "--custom-only needs --custom-plan.");
216
+ }
181
217
  const subsetQuery = {
182
218
  // Florida is refused as a direct enrollment without this.
183
219
  ...(hasFlag(parsed, "force-direct")
@@ -191,6 +227,8 @@ export function parseTuitionPlanSpecFlags(parsed) {
191
227
  ...(endDate ? { endDate } : {}),
192
228
  ...(terms ? { terms: terms.join(",") } : {}),
193
229
  ...(payments ? { payments: payments.join(",") } : {}),
230
+ ...(customPlan ? { customPlan } : {}),
231
+ ...(customOnly ? { customOnly: "true" } : {}),
194
232
  };
195
233
  return {
196
234
  startDate: requiredFlag(parsed, "start", ISO_DATE),
package/dist/help.js CHANGED
@@ -40,7 +40,7 @@ Usage:
40
40
  recess [--json] users school complete-action <user-id> <action-id> --note <text> [--confirm]
41
41
  recess [--json] users school status <user-id>
42
42
  recess [--json] users school history <user-id> [--limit 25] [--cursor <id>]
43
- recess [--json] users school withdraw <user-id> --note <text> --expected-updated-at <iso> [--confirm]
43
+ recess [--json] users school withdraw <user-id> --note <text> --expected-updated-at <iso> [--effective-at <iso>] [--confirm]
44
44
  recess [--json] users school restore <user-id> --tier <tier-id> --note <text> --expected-updated-at <iso> [--confirm]
45
45
  recess [--json] users enrollment history <user-id> [--limit 25] [--cursor <id>]
46
46
  recess [--json] users enrollment set-partner-school-cc <school-id-or-slug>
@@ -54,6 +54,9 @@ Usage:
54
54
  recess [--json] users phone clear <user-id> [--confirm]
55
55
  recess [--json] users lock <user-id> [--confirm]
56
56
  recess [--json] users unlock <user-id> [--confirm]
57
+ recess [--json] users community-hour get <kid-id>
58
+ recess [--json] users community-hour unlock <kid-id> [--confirm]
59
+ recess [--json] users community-hour lock <kid-id> [--confirm]
57
60
  recess [--json] users disable <user-id> [--whole-family] [--allow-billing] [--confirm]
58
61
  recess [--json] users restore <user-id> --role kid|guardian|guide|program [--confirm]
59
62
  recess [--json] users tier list-tiers
@@ -91,6 +94,8 @@ Usage:
91
94
  recess [--json] students analysis --todo <todo-id>
92
95
  recess [--json] students xp-history --student <kid-id>
93
96
  [--range week|month|quarter|year]
97
+ recess [--json] students math-academy --student <kid-id>
98
+ [--from YYYY-MM-DD] [--to YYYY-MM-DD]
94
99
  recess [--json] enrollments list --user <user-id>
95
100
  recess [--json] subscriptions list --family <family-id> [--kid <kid-id>]
96
101
  recess [--json] invoices list --subscription <subscription-id>
@@ -194,26 +199,31 @@ Usage:
194
199
  [--one-on-one-price DOLLARS] [--one-on-one-sessions N] [--end YYYY-MM-DD]
195
200
  [--terms full-year,school-year,custom] [--payments upfront,installments]
196
201
  [--note TEXT]... [--bill-date upfront|N=YYYY-MM-DD]... [--amount N=DOLLARS]... [--even-installments]
197
- [--esa-award-unknown [--esa-scenarios DOLLARS,...]] [--pdf <path>] [--open]
202
+ [--esa-award-unknown [--esa-scenarios DOLLARS,...]] [--custom-plan JSON|@file] [--custom-only]
203
+ [--pdf <path>] [--open]
198
204
  recess [--json] tuition-plans states
199
205
  recess [--json] admissions create --school <institution-slug> --enrollment direct|partner-school|program
200
206
  [--partner-school <slug|id>] --parent "First Last" --email EMAIL [--phone TEXT] --state XX
201
207
  --kid "First Last:YYYY-MM-DD[:grade]" (repeat per child) [--application <application-id>]
202
208
  [--financial-aid <financial-aid-application-id>|none]
203
- [--tier complete] [--paywall DOLLARS] [--staff-note TEXT]... [--no-email]
204
- --start YYYY-MM-DD --annual DOLLARS [--state-funding] [--end YYYY-MM-DD]
209
+ [--tier complete] [--paywall DOLLARS|--paywall-offline] [--staff-note TEXT]... [--no-email]
210
+ (--no-agreement | --start YYYY-MM-DD --annual DOLLARS) [--state-funding] [--end YYYY-MM-DD]
205
211
  [--terms full-year,school-year,custom] [--payments upfront,installments] [--note TEXT]...
206
212
  [--bill-date upfront|N=YYYY-MM-DD]... [--amount N=DOLLARS]... [--even-installments] [--force-direct]
207
- [--esa-award-unknown [--esa-scenarios DOLLARS,...]] [--elective-price DOLLARS]
213
+ [--esa-award-unknown [--esa-scenarios DOLLARS,...]] [--custom-plan JSON|@file] [--custom-only]
214
+ [--elective-price DOLLARS]
208
215
  [--one-on-one-price DOLLARS] [--one-on-one-sessions N] [--confirm]
209
216
  recess [--json] admissions get <packet-id>
210
217
  recess [--json] admissions list [--status SENT|ACCOUNT_CREATED|SIGNED|CONSENTED|QUESTIONS_DONE|COMPLETE|VOIDED] [--email TEXT] [--limit N]
211
218
  recess [--json] admissions resend <packet-id> [--no-email] [--confirm]
212
219
  recess [--json] admissions void <packet-id> --reason TEXT [--confirm]
213
220
  recess [--json] admissions mark-signed <packet-id> --option <term:payment> [--note TEXT] [--confirm]
214
- recess [--json] admissions requote <packet-id> (--keep-plan | --start YYYY-MM-DD --annual DOLLARS [plan flags as in create])
215
- [--paywall DOLLARS|--no-paywall] [--note TEXT] [--confirm]
221
+ recess [--json] admissions requote <packet-id> (--keep-plan | --no-agreement | --start YYYY-MM-DD --annual DOLLARS [plan flags as in create])
222
+ [--paywall DOLLARS|--paywall-offline|--no-paywall] [--note TEXT] [--confirm]
216
223
  recess [--json] admissions archive-agreement <packet-id> [--confirm]
224
+ recess [--json] admissions mark-paid <packet-id> [--note TEXT] [--confirm]
225
+ recess [--json] admissions contract <packet-id> [--option <term:payment>] [--out <file>]
226
+ recess [--json] admissions upload-signed <packet-id> --file <pdf> [--option <term:payment>] [--note TEXT] [--confirm]
217
227
  recess [--json] reports activity [--partner-school <slug|id>] [--guide <name|email|id>]
218
228
  [--cohort <cohort-id>] [--week YYYY-MM-DD] [--no-ai] [--out <dir>]
219
229
  recess [--json] cohorts get <cohort-id> [--events-tab ACTIVE|ENDED|CANCELED|ARCHIVED]
@@ -616,16 +626,30 @@ slot override; "users tier set" is the tier-driven path.
616
626
  recess.gg/ai/students/<kid-id>/admin. They act on the whole account, not one
617
627
  person: a KID target is locked or unlocked together with every GUARDIAN in
618
628
  their family, because an unlocked kid under a locked guardian is not actually
619
- unlocked. Unlock grants the kid and guardian access roles, restores the kid's
620
- Recess channel memberships, sets FLAG_ACCOUNT_UNLOCKED, and notifies the kid's
621
- live clients; lock is the exact inverse. Rerunning "unlock" on an already
622
- unlocked account is the "Refresh Unlock" button and is safe. The preview shows
623
- each affected person's current flag; "users get" is the read.
629
+ unlocked. Unlock grants the kid and guardian app and chat access roles, restores
630
+ the kid's Recess channel memberships, sets FLAG_ACCOUNT_UNLOCKED, and notifies
631
+ the kid's live clients; it does NOT grant Community Hour. Lock revokes those
632
+ roles plus the kid's Community Hour access, drops the kid from their Recess
633
+ channels, and clears the flag. Rerunning "unlock" on an already unlocked account
634
+ is the "Refresh Unlock" button and is safe. The preview shows each affected
635
+ person's current flag and, for a kid, Community Hour now and after; "users get"
636
+ is the read.
637
+
638
+ "users community-hour unlock|lock" is the CLI twin of the "Unlock Community
639
+ Hour"/"Lock Community Hour" button on recess.gg/ai/students/<kid-id>/admin.
640
+ Community Hour access (the kid's recess:participant access role) is separate
641
+ from account unlock: without it a kid cannot join Community Hour or enter the
642
+ Village at all. Kids only, one kid per run. Unlock first assigns a Community
643
+ Hour group if the kid has none, and fails with a conflict when no group has
644
+ room; the Village picks the change up within about 30 seconds. "users unlock"
645
+ does not grant it and "users lock" removes it. "users community-hour get" (or
646
+ "users get": accessRoles contains recess:participant) is the read.
624
647
 
625
648
  "users disable" is the harder stop, and a different mechanism: it sets
626
649
  User.role to DISABLED, so the account stops resolving in every dashboard,
627
650
  search, chat, and todo query at the database layer, and its coherent-feed
628
- personal data is purged. "users lock" only strips access roles. Disabling is
651
+ personal data is purged. "users lock" only strips access roles (Community Hour
652
+ included). Disabling is
629
653
  SOFT and reversible — "users restore <id> --role ..." puts the account back —
630
654
  and it is NOT a GDPR erasure; nothing is deleted. A read-only preflight resolves
631
655
  the whole family (including members already DISABLED, which ordinary reads hide)
@@ -703,6 +727,21 @@ the CSVs, and the per-student AI summaries JSON to --out (default
703
727
  10-30 seconds; AI summaries name the student and quote their work, so review
704
728
  them before sending a report outside Recess.
705
729
 
730
+ Custom plans (--custom-plan, generate/create/requote): for an arrangement the
731
+ computed options cannot express, e.g. a bridge payment until ESA funding
732
+ starts. JSON inline or @file: {"label", "summary"?, "clause"?, "continueFrom"?,
733
+ "rows": [{"label", "note"?, "amount"? (dollars), "amountText"?, "date"?
734
+ (invoice date), "when"?}]}. Each row needs an amount or amountText and a date or
735
+ when; the first row needs a date and an amount (the first invoice). Rows show
736
+ exactly as written; dated rows with amounts are real invoices. "continueFrom": N
737
+ then carries on with the computed installment plan from installment N (e.g. a
738
+ September bridge, then the regular quarters from 2). "continueOverrides": {"N":
739
+ {"amount"?, "note"?}} adjusts continued installment N: a precommitted amount
740
+ makes it firm (no "up to"); a note replaces "Set once your award is confirmed."
741
+ It is offered first on the
742
+ first term, gets its own page in the PDF and an agreement line, and "clause"
743
+ prints as "If I choose <label>: <clause>". --custom-only drops the computed
744
+ options; --payments upfront keeps pay in full beside it.
706
745
  Tuition-plan notes: "generate" computes a Recess Academy tuition plan (nothing is
707
746
  stored): a 180-instructional-day term at --annual (tuition net of Recess aid) and
708
747
  a term through the state's typical school-year end. Each is paid in full upfront
@@ -764,6 +803,19 @@ aid form, else the newest aid form under the parent's email ("none" leaves it ou
764
803
  it. "get" prints the agreed plan as signed (each child's option, term and every
765
804
  installment) and whether the signed agreement is archived in our storage; the
766
805
  copy is taken when the envelope completes, and "archive-agreement" retries it.
806
+ Without Documenso (signing by hand), the parent's choice still freezes the
807
+ plan: "contract" saves the agreement PDF they would sign (their option, or
808
+ --option), and "upload-signed" files the signed copy as the packet's agreement
809
+ and records the signature, moving the family to consent ("mark-signed" does the
810
+ same with no file). The admin dashboard at /admin/admissions does both.
811
+ --no-agreement (create or requote) skips the tuition agreement entirely: no
812
+ plan flags, no quote, no signing; the parent goes from the account straight to
813
+ consent and questions. A card --paywall still works; --paywall-offline needs a
814
+ plan. Requoting with plan flags adds an agreement back.
815
+ --paywall-offline (create or requote) collects the signed plan's first invoice
816
+ outside Recess instead of by card: after the questions the family sees the
817
+ amount and due date, class registration stays blocked, and "mark-paid"
818
+ records it received, lifts the block and completes the packet.
767
819
  "requote" replaces the tuition plan on a packet that has not been paid (same
768
820
  plan flags as create, or --keep-plan to reopen the payment choice on the plan
769
821
  as it is; --paywall/--no-paywall changes the family share): the Documenso
@@ -862,8 +914,11 @@ export const COMMAND_SUMMARIES = {
862
914
  "users phone get": "Read a user's phone number and verification.",
863
915
  "users phone set": "Set a user's phone number (stored E.164, unverified).",
864
916
  "users phone clear": "Remove a user's phone number.",
865
- "users lock": "Lock a kid's account (with their family's guardians).",
866
- "users unlock": "Unlock a kid's account with their guardians; rerun = Refresh Unlock.",
917
+ "users community-hour get": "Show whether a kid can join Community Hour.",
918
+ "users community-hour unlock": "Let a kid join Community Hour and enter the Village.",
919
+ "users community-hour lock": "Stop a kid joining Community Hour or the Village.",
920
+ "users lock": "Lock a kid's account with their guardians (removes Community Hour).",
921
+ "users unlock": "Unlock a kid's account with guardians (not Community Hour); rerun = refresh.",
867
922
  "users disable": "Soft-disable an account or whole family (reversible; refuses live billing).",
868
923
  "users restore": "Restore a disabled account to a named role.",
869
924
  "users tier list-tiers": "List membership tiers and their slots.",
@@ -890,6 +945,7 @@ export const COMMAND_SUMMARIES = {
890
945
  "students todos": "List a student's todos for a date (or recent), with statuses.",
891
946
  "students analysis": "Read the learning analysis for a completed todo.",
892
947
  "students xp-history": "Show a kid's XP history over a range.",
948
+ "students math-academy": "Show a linked kid's Math Academy course, league and task activity.",
893
949
  "enrollments list": "List a user's enrollments.",
894
950
  "subscriptions list": "List a family's Stripe subscriptions.",
895
951
  "invoices list": "List a subscription's invoices.",
@@ -1175,7 +1231,7 @@ export const NOUN_SUMMARIES = {
1175
1231
  jobs: "Local ledger of write operations by operation key.",
1176
1232
  feedback: "Send or list feedback about this CLI.",
1177
1233
  auth: "Sign in (browser or headless), session status, sign out.",
1178
- users: "Accounts: search/get, lock/unlock, disable/restore, phone, tier, school status.",
1234
+ users: "Accounts: search/get, lock/unlock, community-hour, disable/restore, phone, tier, school status.",
1179
1235
  guides: "Create and invite guide accounts.",
1180
1236
  guardians: "Invite guardians into a family.",
1181
1237
  students: "Kids: roster, today, schedule, todos, analysis, XP, SMS summaries, notes.",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "recess-cli",
3
- "version": "3.12.0",
3
+ "version": "3.14.0",
4
4
  "description": "Safe Recess administration and family AI tools from the command line.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {
@@ -26,6 +26,8 @@ Load the audience skill's `SKILL.md`, then only the reference it routes you to:
26
26
  recess --json skills guardian get recess-family
27
27
  # Research, author, or apply a goal or reusable goal template
28
28
  recess --json skills guardian get recess-goal-authoring
29
+ # Guide (guide_students): your students, class ops, Math Academy linking and activity
30
+ recess --json skills guardian get recess-guide
29
31
  # Staff operations (full_admin), then the one playbook its table names
30
32
  recess --json skills admin get recess-admin
31
33
  recess --json skills admin get recess-admin --reference billing