recess-cli 3.38.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");
@@ -540,6 +540,7 @@ const STAFF_COMMANDS = new Set([
540
540
  "payout items add",
541
541
  "payout items delete",
542
542
  "payout items edit",
543
+ "payout payruns advance",
543
544
  "payout payruns list",
544
545
  "payout recipients list",
545
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") {
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]
@@ -1142,6 +1143,9 @@ with no paywall completes when the questions are in.
1142
1143
  Payout notes: amounts are integer cents. "payout items add" without --date
1143
1144
  defaults the item date to the penultimate day of the invoice's cycle (its
1144
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.
1145
1149
 
1146
1150
  Auth notes: "auth login" runs the browser loopback flow for ADMIN, GUIDE, a GUARDIAN with
1147
1151
  access:ai, or a KID using only Village home building. Guardian sessions are family-scoped and
@@ -1331,6 +1335,7 @@ export const COMMAND_SUMMARIES = {
1331
1335
  "payout recipients remove-schedule": "Remove a recipient from a payout schedule.",
1332
1336
  "payout recipients add-schedule": "Add a recipient to a payout schedule.",
1333
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.",
1334
1339
  "payout invoices get": "Read one payout invoice and its items.",
1335
1340
  "payout invoices set-status": "Change a payout invoice's status.",
1336
1341
  "payout items add": "Add a line item to a payout invoice (cents).",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "recess-cli",
3
- "version": "3.38.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": {