recess-cli 3.43.0 → 3.44.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,37 @@ export class RecessAdminApi {
233
233
  throw apiError(response.status, body);
234
234
  return body;
235
235
  }
236
+ /** File a full MAP report PDF (e.g. Learning Statements) for one season. */
237
+ async uploadMapTestReport(studentId, query, pdf, fileName) {
238
+ this.requireAuth();
239
+ const formData = new FormData();
240
+ const pdfBody = new Uint8Array(pdf.byteLength);
241
+ pdfBody.set(pdf);
242
+ formData.append("file", new Blob([pdfBody.buffer], { type: "application/pdf" }), fileName);
243
+ const headers = cliRequestHeaders({ cookie: this.config.sessionCookie }, this.reason, this.clientTag);
244
+ applyIdempotencyHeaders(headers);
245
+ const url = new URL(`/tutor/students/${encodeURIComponent(studentId)}/map-test-reports`, this.config.apiOrigin);
246
+ for (const [key, value] of Object.entries(query)) {
247
+ if (value !== undefined)
248
+ url.searchParams.set(key, String(value));
249
+ }
250
+ const response = await fetch(url, {
251
+ method: "POST",
252
+ headers,
253
+ body: formData,
254
+ });
255
+ const text = await response.text();
256
+ let body = text;
257
+ try {
258
+ body = text ? JSON.parse(text) : null;
259
+ }
260
+ catch {
261
+ // Preserve a non-JSON API response as text.
262
+ }
263
+ if (!response.ok)
264
+ throw apiError(response.status, body);
265
+ return body;
266
+ }
236
267
  /** The packet's tuition agreement as a PDF, to sign by hand. */
237
268
  async downloadAdmissionContract(packetId, optionId) {
238
269
  this.requireAuth();
package/dist/cli.js CHANGED
@@ -1290,6 +1290,8 @@ const SCHOOL_TIER_IDS = SCHOOL_TIER_OPTIONS.map((tier) => tier.id);
1290
1290
  // own paths. The server's POST /admin/users/change-role/ enforces the same set.
1291
1291
  const RESTORABLE_ROLES = ["KID", "GUARDIAN", "GUIDE", "PROGRAM"];
1292
1292
  const MAX_MAP_PDF_BYTES = 15 * 1024 * 1024;
1293
+ /** `students map-reports upload`: the report route + MAP_REPORT policy cap. */
1294
+ const MAX_MAP_REPORT_PDF_BYTES = 32 * 1024 * 1024;
1293
1295
  const GOAL_TEMPLATE_KINDS = ["SIMPLE", "BLUEPRINT"];
1294
1296
  const GOAL_TEMPLATE_SETUP_AUDIENCES = ["KID_FRIENDLY", "PARENT_SETUP"];
1295
1297
  const STORE_ITEM_STATUSES = ["ACTIVE", "INACTIVE", "COMING_SOON"];
@@ -1943,7 +1945,16 @@ async function resolveExpectedTemplateVersion(api, parsed, templateId, recovered
1943
1945
  return { expectedVersion: current.version, pinnedFrom: "current" };
1944
1946
  }
1945
1947
  const PINNED_VERSION_NOTE = "--expected-version was omitted, so the version read at preview is pinned: a template change before confirm changes this preview and the confirm is refused. Retrying after a landed write needs --expected-version <the previewed version>.";
1946
- async function readMapScorePdf(filePath) {
1948
+ const MAP_REPORT_SUBJECTS = [
1949
+ "MATH",
1950
+ "READING",
1951
+ "LANGUAGE_USAGE",
1952
+ "SCIENCE",
1953
+ "OTHER",
1954
+ ];
1955
+ const MAP_REPORT_SEASONS = ["FALL", "WINTER", "SPRING", "SUMMER"];
1956
+ const MAP_REPORT_KINDS = ["LEARNING_STATEMENTS", "OTHER"];
1957
+ async function readMapScorePdf(filePath, maxBytes = MAX_MAP_PDF_BYTES) {
1947
1958
  const absolutePath = path.resolve(filePath);
1948
1959
  if (path.extname(absolutePath).toLowerCase() !== ".pdf") {
1949
1960
  throw new CliError("invalid_arguments", "--file must point to a PDF report.");
@@ -1964,8 +1975,8 @@ async function readMapScorePdf(filePath) {
1964
1975
  if (stat.size === 0) {
1965
1976
  throw new CliError("invalid_arguments", "MAP score PDF is empty.");
1966
1977
  }
1967
- if (stat.size > MAX_MAP_PDF_BYTES) {
1968
- throw new CliError("invalid_arguments", "MAP score PDF exceeds the 15 MB upload limit.");
1978
+ if (stat.size > maxBytes) {
1979
+ throw new CliError("invalid_arguments", `MAP PDF exceeds the ${Math.round(maxBytes / 1024 / 1024)} MB upload limit.`);
1969
1980
  }
1970
1981
  const bytes = await fs.readFile(absolutePath);
1971
1982
  return {
@@ -3571,6 +3582,48 @@ export async function executeRecessCommand(argv, options = {}) {
3571
3582
  },
3572
3583
  }, () => api.uploadMapTestScores(studentId, pdf.bytes, pdf.fileName));
3573
3584
  }
3585
+ if (noun === "students" && verb === "map-reports") {
3586
+ const action = parsed.positionals[2];
3587
+ const studentId = flagString(parsed, "student", { required: true });
3588
+ if (action === "list") {
3589
+ return unwrap(await api.client.GET("/tutor/students/{studentId}/map-test-reports", {
3590
+ params: { path: { studentId } },
3591
+ }));
3592
+ }
3593
+ if (action === "upload") {
3594
+ const subject = assertChoice(flagString(parsed, "subject", { required: true }).toUpperCase(), MAP_REPORT_SUBJECTS, "--subject");
3595
+ const season = assertChoice(flagString(parsed, "season", { required: true }).toUpperCase(), MAP_REPORT_SEASONS, "--season");
3596
+ const schoolYear = flagString(parsed, "school-year", { required: true });
3597
+ if (!/^\d{4}-\d{4}$/.test(schoolYear)) {
3598
+ throw new CliError("invalid_arguments", '--school-year must look like "2025-2026".');
3599
+ }
3600
+ const kind = assertChoice((flagString(parsed, "kind") ?? "learning-statements")
3601
+ .toUpperCase()
3602
+ .replace(/-/g, "_"), MAP_REPORT_KINDS, "--kind");
3603
+ const pdf = await readMapScorePdf(flagString(parsed, "file", { required: true }), MAX_MAP_REPORT_PDF_BYTES);
3604
+ const query = { kind, subject, season, schoolYear };
3605
+ return writeCommand(parsed, {
3606
+ action: "file a full MAP report PDF beside this season's scores (parents, the kid, and their guides can open it; replaces any existing report for the same subject + season)",
3607
+ target: { studentId },
3608
+ request: {
3609
+ ...query,
3610
+ file: pdf.absolutePath,
3611
+ fileName: pdf.fileName,
3612
+ sizeBytes: pdf.bytes.byteLength,
3613
+ sha256: pdf.sha256,
3614
+ },
3615
+ }, () => api.uploadMapTestReport(studentId, query, pdf.bytes, pdf.fileName));
3616
+ }
3617
+ if (action === "delete") {
3618
+ const reportId = flagString(parsed, "report", { required: true });
3619
+ return writeCommand(parsed, {
3620
+ action: "remove a filed MAP report PDF from the kid's dashboard",
3621
+ target: { studentId, reportId },
3622
+ request: {},
3623
+ }, async () => unwrap(await api.client.DELETE("/tutor/students/{studentId}/map-test-reports/{reportId}", { params: { path: { studentId, reportId } } })));
3624
+ }
3625
+ throw new CliError("invalid_arguments", "Use students map-reports list|upload|delete.");
3626
+ }
3574
3627
  if (noun === "enrollments" && verb === "list") {
3575
3628
  const userId = flagString(parsed, "user", { required: true });
3576
3629
  const data = unwrap(await api.client.GET("/admin/users/operations-search", {
@@ -6524,7 +6577,7 @@ export async function executeRecessCommand(argv, options = {}) {
6524
6577
  return { studentId, flashcardReviewEnabled: on };
6525
6578
  });
6526
6579
  }
6527
- throw new CliError("invalid_arguments", "Use students list|today|schedule|todos|analysis|xp-history|mastery|upload-map-scores|issue-email|goblins|web-todos|flashcards.");
6580
+ throw new CliError("invalid_arguments", "Use students list|today|schedule|todos|analysis|xp-history|mastery|upload-map-scores|map-reports|issue-email|goblins|web-todos|flashcards.");
6528
6581
  }
6529
6582
  if (noun === "todos") {
6530
6583
  if (verb === "create") {
@@ -585,6 +585,9 @@ const STAFF_COMMANDS = new Set([
585
585
  "school update",
586
586
  "store-items list",
587
587
  "students upload-map-scores",
588
+ "students map-reports list",
589
+ "students map-reports upload",
590
+ "students map-reports delete",
588
591
  "students issue-email",
589
592
  "students goblins",
590
593
  "students web-todos",
@@ -971,10 +971,6 @@ export async function runKidCommand({ parsed, api, writeCommand, }) {
971
971
  },
972
972
  wins: today.insights.wins,
973
973
  struggles: today.insights.struggles,
974
- // Adaptive coins: a required to-do pays 10 × its subject's multiplier.
975
- ...(today.coinMultipliers && {
976
- coinMultipliers: today.coinMultipliers,
977
- }),
978
974
  };
979
975
  }
980
976
  if (verb === "goals") {
@@ -1903,7 +1899,7 @@ export async function runKidCommand({ parsed, api, writeCommand, }) {
1903
1899
  target: { ...kidTarget(kid), goalId },
1904
1900
  request: { coins },
1905
1901
  details: {
1906
- consequence: "Its open and future to-dos pay this (default: required 20, optional 5; undo: family undo).",
1902
+ consequence: "Its open and future to-dos pay this (default: by subject, math 20, reading 10, else 5; undo: family undo).",
1907
1903
  },
1908
1904
  }, async () => {
1909
1905
  const result = unwrap(await api.client.PATCH("/parent-v2/kid/{kidId}/challenges/{goalId}/coins/", { params: { path: { kidId, goalId } }, body: { coins } }));
@@ -1945,7 +1941,7 @@ export async function runKidCommand({ parsed, api, writeCommand, }) {
1945
1941
  params: { path: { kidId } },
1946
1942
  }));
1947
1943
  return {
1948
- challenges: goals.map((goal) => `${goal.id} · ${goal.title} · ${goal.required ? "required" : "optional"} · ${goal.todoCoins ?? (goal.required ? 20 : 5)} coins/to-do · ${goal.status.toLowerCase()}`),
1944
+ challenges: goals.map((goal) => `${goal.id} · ${goal.title} · ${goal.required ? "required" : "optional"} · ${goal.todoCoins ?? "subject-priced"} coins/to-do · ${goal.status.toLowerCase()}`),
1949
1945
  page: `${api.config.webOrigin}/ai?kid=${encodeURIComponent(kidId)}&tab=challenges`,
1950
1946
  browse: `${api.config.webOrigin}/activity/challenges`,
1951
1947
  };
package/dist/help.js CHANGED
@@ -79,6 +79,13 @@ Usage:
79
79
  [--focus <text> | --clear-focus] [--confirm]
80
80
  recess [--json] students upload-map-scores --student <kid-id>
81
81
  --file </path/to/map-report.pdf> [--confirm]
82
+ recess [--json] students map-reports list --student <kid-id>
83
+ recess [--json] students map-reports upload --student <kid-id>
84
+ --file </path/to/report.pdf> --subject math|reading|language_usage|science|other
85
+ --season fall|winter|spring|summer --school-year <YYYY-YYYY>
86
+ [--kind learning-statements|other] [--confirm]
87
+ recess [--json] students map-reports delete --student <kid-id> --report <report-id>
88
+ [--confirm]
82
89
  recess [--json] students issue-email --student <kid-id> [--confirm]
83
90
  recess [--json] students goblins --student <kid-id> [--course <slug>] [--search TEXT]
84
91
  [--confirm]
@@ -1270,6 +1277,9 @@ export const COMMAND_SUMMARIES = {
1270
1277
  "students texts set": "Change a kid's SMS summary switch or send hour.",
1271
1278
  "students texts set-guardian": "Change one adult's SMS frequency, focus, or on/off.",
1272
1279
  "students upload-map-scores": "Upload a NWEA MAP score report PDF for a kid.",
1280
+ "students map-reports list": "List the full MAP report PDFs filed for a kid, by subject and season.",
1281
+ "students map-reports upload": "File a full MAP report PDF (e.g. Learning Statements) beside that season's scores for parents, the kid, and guides.",
1282
+ "students map-reports delete": "Remove a filed MAP report PDF.",
1273
1283
  "students issue-email": "Issue a Recess email address for a kid.",
1274
1284
  "students goblins": "Roster a kid into Goblins so their Goblins todos sign them straight in.",
1275
1285
  "students web-todos": "Show or set whether a kid's todos run on web (off: they open in the desktop app).",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "recess-cli",
3
- "version": "3.43.0",
3
+ "version": "3.44.0",
4
4
  "description": "Safe Recess administration and family AI tools from the command line.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {
@@ -46,8 +46,8 @@
46
46
  "oxlint-tsgolint": "^0.6.0",
47
47
  "typescript": "^5.9.2",
48
48
  "vitest": "^1.6.0",
49
- "@tryrecess/typescript-config": "0.0.0",
50
- "@tryrecess/api-types": "0.0.0"
49
+ "@tryrecess/api-types": "0.0.0",
50
+ "@tryrecess/typescript-config": "0.0.0"
51
51
  },
52
52
  "scripts": {
53
53
  "build": "node node_modules/@tryrecess/typescript-config/bin/tsc-fast.mjs",
@@ -30,7 +30,7 @@ recess --json skills guardian get recess-family
30
30
  recess --json skills guardian get recess-challenge-design
31
31
  # Research, author, or apply a goal or reusable goal template
32
32
  recess --json skills guardian get recess-goal-authoring
33
- # Guide (guide_students): your students, class ops, Math Academy linking and activity
33
+ # Guide (guide_students): your students, class ops, Math Academy, Goblins math practice
34
34
  recess --json skills guardian get recess-guide
35
35
  # Staff operations (full_admin), then the one playbook its table names
36
36
  recess --json skills admin get recess-admin