recess-cli 3.37.0 → 3.39.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
@@ -1248,6 +1248,35 @@ const PAYOUT_STATUS_SIDE_EFFECTS = {
1248
1248
  PAID: "marks the invoice paid and deducts its total from the recipient's account balance",
1249
1249
  CANCELED: "cancels the invoice and reverses any balance items carried on it",
1250
1250
  };
1251
+ // One pay run step at a time, in order; `from` is the run status it needs.
1252
+ const PAYRUN_STEPS = {
1253
+ draft: {
1254
+ api: "draft",
1255
+ from: "UPCOMING",
1256
+ effect: "generates each recipient's DRAFT invoice for this cycle",
1257
+ },
1258
+ review: {
1259
+ api: "review",
1260
+ from: "DRAFT",
1261
+ effect: "moves the run and its DRAFT invoices to IN_REVIEW",
1262
+ },
1263
+ finalize: {
1264
+ api: "finalize",
1265
+ from: "IN_REVIEW",
1266
+ effect: "approves the run and FINALIZES its invoices to OPEN, adding each total to the recipient's account balance",
1267
+ },
1268
+ pay: {
1269
+ api: "pay",
1270
+ from: "APPROVED",
1271
+ effect: "MOVES MONEY: creates a Mercury send-money request for every OPEN invoice",
1272
+ },
1273
+ "mark-paid": {
1274
+ api: "mark_paid",
1275
+ from: "APPROVED",
1276
+ effect: "marks the run PAID and closes it; invoice statuses are not changed",
1277
+ },
1278
+ };
1279
+ const PAYRUN_STEP_NAMES = Object.keys(PAYRUN_STEPS);
1251
1280
  const SCHOOL_TIER_OPTIONS = [
1252
1281
  { id: "social", name: "Social", defaultClassSlots: 2 },
1253
1282
  { id: "academics", name: "Academics", defaultClassSlots: 0 },
@@ -3815,6 +3844,117 @@ export async function executeRecessCommand(argv, options = {}) {
3815
3844
  },
3816
3845
  }));
3817
3846
  }
3847
+ if (area === "payruns" && action === "advance") {
3848
+ const payrunId = positional(parsed, 3, "payrun ID");
3849
+ const stepName = assertChoice(flagString(parsed, "step", { required: true }), PAYRUN_STEP_NAMES, "--step");
3850
+ const step = PAYRUN_STEPS[stepName];
3851
+ const sendEmail = hasFlag(parsed, "send-email");
3852
+ const emails = stepName === "review" || stepName === "finalize";
3853
+ if (sendEmail && !emails) {
3854
+ throw new CliError("invalid_arguments", "--send-email only applies to --step review or finalize.");
3855
+ }
3856
+ const readRun = async () => unwrap(await api.client.GET("/admin/payout/payrun/payrun/", {
3857
+ params: { query: { id: payrunId } },
3858
+ })).payRuns[0];
3859
+ const countByStatus = (run) => {
3860
+ const counts = {};
3861
+ for (const invoice of run.payoutInvoices) {
3862
+ counts[invoice.status] = (counts[invoice.status] ?? 0) + 1;
3863
+ }
3864
+ return counts;
3865
+ };
3866
+ const summarize = (invoices) => invoices.map((invoice) => ({
3867
+ invoiceId: invoice.id,
3868
+ recipient: invoice.recipient.name,
3869
+ mercuryUserId: invoice.recipient.mercuryUserId,
3870
+ totalAmountCents: invoice.totalAmountCents,
3871
+ }));
3872
+ const run = await readRun();
3873
+ if (run.status !== step.from) {
3874
+ throw new CliError("invalid_arguments", `--step ${stepName} needs a ${step.from} pay run; this one is ${run.status}.`);
3875
+ }
3876
+ const open = run.payoutInvoices.filter((i) => i.status === "OPEN");
3877
+ const openTotalCents = open.reduce((sum, invoice) => sum + invoice.totalAmountCents, 0);
3878
+ if (stepName === "pay" && !open.length) {
3879
+ throw new CliError("invalid_arguments", "This pay run has no OPEN invoices to pay.");
3880
+ }
3881
+ if (stepName === "mark-paid") {
3882
+ // The run's status is all this writes, and a PAID run can no longer be
3883
+ // paid: closing it over an unsent invoice would strand that invoice.
3884
+ const unsent = run.payoutInvoices.filter((i) => ["DRAFT", "IN_REVIEW", "OPEN"].includes(i.status));
3885
+ if (unsent.length) {
3886
+ throw new CliError("invalid_arguments", `${unsent.length} invoice(s) have not been sent for payment. Run --step pay, or settle each with \`payout invoices set-status\`, before marking the run paid.`, 1, { invoices: summarize(unsent) });
3887
+ }
3888
+ }
3889
+ const emailEffect = emails
3890
+ ? sendEmail
3891
+ ? " and emails the guides"
3892
+ : " WITHOUT emailing the guides (pass --send-email to notify)"
3893
+ : "";
3894
+ return writeCommand(parsed, {
3895
+ action: `advance pay run ${run.name ?? payrunId}: ${step.effect}${emailEffect}`,
3896
+ target: { payrunId },
3897
+ // The approval key hashes this whole preview, so a confirm that reads
3898
+ // different invoices needs a fresh one; `expectedInvoices` below then
3899
+ // holds the server to what was read, up to the moment it pays.
3900
+ request: {
3901
+ step: stepName,
3902
+ fromStatus: run.status,
3903
+ ...(emails ? { sendEmail } : {}),
3904
+ ...(stepName === "pay"
3905
+ ? { openInvoiceCount: open.length, openTotalCents }
3906
+ : {}),
3907
+ },
3908
+ details: {
3909
+ invoicesByStatus: countByStatus(run),
3910
+ ...(stepName === "pay" ? { invoices: summarize(open) } : {}),
3911
+ },
3912
+ }, async () => {
3913
+ const { invoiceResults } = unwrap(await api.client.POST("/admin/payout/payrun/advance-payrun/", {
3914
+ body: {
3915
+ payrunId,
3916
+ action: step.api,
3917
+ sendEmail,
3918
+ ...(stepName === "pay"
3919
+ ? {
3920
+ expectedInvoices: open.map((invoice) => ({
3921
+ id: invoice.id,
3922
+ totalAmountCents: invoice.totalAmountCents,
3923
+ mercuryUserId: invoice.recipient.mercuryUserId,
3924
+ })),
3925
+ }
3926
+ : {}),
3927
+ },
3928
+ }));
3929
+ const after = await readRun();
3930
+ // The route answers ok over per-invoice failures. An invoice left OPEN
3931
+ // isn't proof nothing was sent: Mercury can accept a request before
3932
+ // the write recording it fails.
3933
+ const outcomes = new Map(invoiceResults?.map((r) => [r.invoiceId, r.outcome]));
3934
+ const notConfirmed = stepName === "pay"
3935
+ ? after.payoutInvoices.filter((i) => i.status === "OPEN")
3936
+ : [];
3937
+ return {
3938
+ payrunId,
3939
+ step: stepName,
3940
+ status: after.status,
3941
+ invoicesByStatus: countByStatus(after),
3942
+ ...(stepName === "pay"
3943
+ ? {
3944
+ notConfirmed: summarize(notConfirmed).map((invoice) => ({
3945
+ ...invoice,
3946
+ reason: outcomes.get(invoice.invoiceId) ?? "UNKNOWN",
3947
+ })),
3948
+ ...(notConfirmed.length
3949
+ ? {
3950
+ warning: `${notConfirmed.length} invoice(s) were not confirmed as sent. PAYMENT_ERROR or UNKNOWN may still have reached Mercury, so check there. INVOICE_CHANGED needs a fresh preview. Rerunning --step pay retries only these.`,
3951
+ }
3952
+ : {}),
3953
+ }
3954
+ : {}),
3955
+ };
3956
+ });
3957
+ }
3818
3958
  if (area === "recipients" && action === "list") {
3819
3959
  const search = flagString(parsed, "search");
3820
3960
  const userId = flagString(parsed, "user");
@@ -4047,7 +4187,7 @@ export async function executeRecessCommand(argv, options = {}) {
4047
4187
  params: { path: { id: itemId } },
4048
4188
  })));
4049
4189
  }
4050
- throw new CliError("invalid_arguments", "Use payout payruns list, payout recipients list, payout invoices list|get|set-status, or payout items add|edit|delete.");
4190
+ throw new CliError("invalid_arguments", "Use payout payruns list|advance, payout recipients list, payout invoices list|get|set-status, or payout items add|edit|delete.");
4051
4191
  }
4052
4192
  if (noun === "cohorts" && verb === "get") {
4053
4193
  const cohortId = positional(parsed, 2, "cohort ID");
@@ -459,6 +459,7 @@ const STAFF_COMMANDS = new Set([
459
459
  "math-curricula unlink",
460
460
  "reading-checks passages list",
461
461
  "reading-checks passages set-text",
462
+ "reading-checks passages set-pdf",
462
463
  "students mastery",
463
464
  "apps link",
464
465
  "apps links",
@@ -539,6 +540,7 @@ const STAFF_COMMANDS = new Set([
539
540
  "payout items add",
540
541
  "payout items delete",
541
542
  "payout items edit",
543
+ "payout payruns advance",
542
544
  "payout payruns list",
543
545
  "payout recipients list",
544
546
  "placement give",
@@ -418,7 +418,20 @@ export async function runAdmissionsCommand({ parsed, api, writeCommand, }) {
418
418
  params: { path: { packetId } },
419
419
  body: { reason },
420
420
  }));
421
- return json ? result : { help: await render(result.packet) };
421
+ if (json)
422
+ return result;
423
+ const outcome = [
424
+ result.kidsDisabled.length
425
+ ? `Disabled: ${result.kidsDisabled.join(", ")}`
426
+ : "Disabled: no kids",
427
+ ...result.kidsKept.map((kid) => `Kept ${kid.firstName}: ${kid.reason}`),
428
+ result.chargesCanceled
429
+ ? "Canceled the unpaid charge."
430
+ : "No unpaid charge to cancel.",
431
+ ];
432
+ return {
433
+ help: `${await render(result.packet)}\n\n${outcome.join("\n")}`,
434
+ };
422
435
  });
423
436
  }
424
437
  if (verb === "mark-signed") {
@@ -58,6 +58,37 @@ export async function runReadingChecksCommand(context) {
58
58
  body,
59
59
  })));
60
60
  }
61
- throw new CliError("invalid_arguments", "Use reading-checks passages list|set-text.");
61
+ if (group === "passages" && verb === "set-pdf") {
62
+ const passageId = positional(parsed, 3, "passage ID");
63
+ const file = flagString(parsed, "file");
64
+ const clear = hasFlag(parsed, "clear");
65
+ if (Boolean(file) === clear) {
66
+ throw new CliError("invalid_arguments", "Pass exactly one of --file <path> or --clear.");
67
+ }
68
+ if (file && !/\.pdf$/i.test(file)) {
69
+ throw new CliError("invalid_arguments", `${file} isn't a .pdf file.`);
70
+ }
71
+ const body = {
72
+ base64: file
73
+ ? (await fs.readFile(path.resolve(file))).toString("base64")
74
+ : null,
75
+ };
76
+ return writeCommand(parsed, {
77
+ action: file
78
+ ? "set the book pages a kid sees for a reading-check passage"
79
+ : "drop a reading-check passage's book pages",
80
+ target: { passageId, file: file ?? null },
81
+ request: { pdf: file ? path.basename(file) : null },
82
+ details: {
83
+ consequence: file
84
+ ? "Checks on this passage show these pages and score the read against the text on them."
85
+ : "Kids see the page text instead of the book pages.",
86
+ },
87
+ }, async () => unwrap(await api.client.PUT("/reading-checks/passages/{passageId}/pdf", {
88
+ params: { path: { passageId } },
89
+ body,
90
+ })));
91
+ }
92
+ throw new CliError("invalid_arguments", "Use reading-checks passages list|set-text|set-pdf.");
62
93
  }
63
94
  //# sourceMappingURL=reading-checks.js.map
package/dist/help.js CHANGED
@@ -184,6 +184,7 @@ Usage:
184
184
  recess [--json] payout recipients remove-schedule <account-id> --schedule <id> [--zero-balance [--zero-balance-reason TEXT]] [--confirm]
185
185
  recess [--json] payout recipients add-schedule <account-id> --schedule <id> [--confirm]
186
186
  recess [--json] payout payruns remove-account <payrun-id> --recipient <account-id> [--zero-balance [--zero-balance-reason TEXT]] [--confirm]
187
+ recess [--json] payout payruns advance <payrun-id> --step draft|review|finalize|pay|mark-paid [--send-email] [--confirm]
187
188
  recess [--json] payout invoices get <invoice-id>
188
189
  recess [--json] payout invoices set-status <invoice-id>
189
190
  --status IN_REVIEW|OPEN|PAID|CANCELED [--send-email] [--confirm]
@@ -735,6 +736,7 @@ Usage:
735
736
  recess [--json] math-curricula unlink <curriculum> <template-id> [--confirm]
736
737
  recess [--json] reading-checks passages list
737
738
  recess [--json] reading-checks passages set-text <passage-id> (--file <path> | --clear) [--confirm]
739
+ recess [--json] reading-checks passages set-pdf <passage-id> (--file <path.pdf> | --clear) [--confirm]
738
740
  recess [--json] challenge-of-the-week list [--past N] [--ahead N]
739
741
  recess [--json] challenge-of-the-week show <week>
740
742
  recess [--json] challenge-of-the-week queue <template> --week <week> [--note TEXT] [--confirm]
@@ -1141,6 +1143,9 @@ with no paywall completes when the questions are in.
1141
1143
  Payout notes: amounts are integer cents. "payout items add" without --date
1142
1144
  defaults the item date to the penultimate day of the invoice's cycle (its
1143
1145
  endDate minus one day) and shows the computed date in the preview.
1146
+ "payout payruns advance" moves a run one step: draft (UPCOMING), review (DRAFT),
1147
+ finalize (IN_REVIEW), pay (APPROVED; creates Mercury send-money requests),
1148
+ mark-paid (APPROVED; refused while any invoice is unsent). Admin only.
1144
1149
 
1145
1150
  Auth notes: "auth login" runs the browser loopback flow for ADMIN, GUIDE, a GUARDIAN with
1146
1151
  access:ai, or a KID using only Village home building. Guardian sessions are family-scoped and
@@ -1330,6 +1335,7 @@ export const COMMAND_SUMMARIES = {
1330
1335
  "payout recipients remove-schedule": "Remove a recipient from a payout schedule.",
1331
1336
  "payout recipients add-schedule": "Add a recipient to a payout schedule.",
1332
1337
  "payout payruns remove-account": "Remove a recipient from a payout run.",
1338
+ "payout payruns advance": "Move a payout run one step, through paying it in Mercury.",
1333
1339
  "payout invoices get": "Read one payout invoice and its items.",
1334
1340
  "payout invoices set-status": "Change a payout invoice's status.",
1335
1341
  "payout items add": "Add a line item to a payout invoice (cents).",
@@ -1683,6 +1689,7 @@ export const COMMAND_SUMMARIES = {
1683
1689
  "math-curricula unlink": "Unlink a goal template from a math curriculum.",
1684
1690
  "reading-checks passages list": "Each reading-check passage, its stage, and whether its page text is set.",
1685
1691
  "reading-checks passages set-text": "Set the page a kid reads aloud for a passage, from a text, Word (.docx) or PDF file (scans are OCR'd); --clear goes back to reading from the book.",
1692
+ "reading-checks passages set-pdf": "Show kids the book pages themselves from a PDF (up to 5 pages); the text on them is saved for scoring. --clear drops the pages and keeps the text.",
1686
1693
  "challenge-of-the-week list": "List Challenge of the Week picks: past, this week, upcoming, and the bench.",
1687
1694
  "challenge-of-the-week show": "Read one week's Challenge of the Week pick and note.",
1688
1695
  "challenge-of-the-week queue": "Queue a challenge for an empty week, with an optional note for kids.",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "recess-cli",
3
- "version": "3.37.0",
3
+ "version": "3.39.0",
4
4
  "description": "Safe Recess administration and family AI tools from the command line.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {