recess-cli 3.5.0 → 3.6.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
@@ -12,8 +12,10 @@ import { runAppsCommand } from "./commands/apps.js";
12
12
  import { readAssignmentSelection, runGoalCurriculumCommand, } from "./commands/goal-curriculum.js";
13
13
  import { runChannelsCommand } from "./commands/channels.js";
14
14
  import { runChatLogsCommand } from "./commands/chat-logs.js";
15
+ import { runDbCommand } from "./commands/db.js";
15
16
  import { runRoomsCommand } from "./commands/rooms.js";
16
17
  import { runFamiliesCommand } from "./commands/families.js";
18
+ import { runStudentsTextsCommand, runUsersPhoneCommand, } from "./commands/phone-and-texts.js";
17
19
  import { runMasteryCommand } from "./commands/mastery.js";
18
20
  import { runOnboardingCommand } from "./commands/onboarding.js";
19
21
  import { runScheduleCommand, runMemoryFilesCommand, } from "./commands/safe-staff-operations.js";
@@ -2674,6 +2676,9 @@ export async function executeRecessCommand(argv, options = {}) {
2674
2676
  body,
2675
2677
  })));
2676
2678
  }
2679
+ if (noun === "users" && verb === "phone") {
2680
+ return runUsersPhoneCommand({ parsed, api, writeCommand });
2681
+ }
2677
2682
  if (noun === "users" && verb === "get") {
2678
2683
  const userId = positional(parsed, 2, "user ID");
2679
2684
  return unwrap(await api.client.GET("/admin/users/{userId}", {
@@ -5092,9 +5097,15 @@ export async function executeRecessCommand(argv, options = {}) {
5092
5097
  if (noun === "chat-logs") {
5093
5098
  return runChatLogsCommand({ parsed, api, writeCommand });
5094
5099
  }
5100
+ if (noun === "db") {
5101
+ return runDbCommand({ parsed, api, writeCommand });
5102
+ }
5095
5103
  if (noun === "rooms") {
5096
5104
  return runRoomsCommand({ parsed, api, writeCommand });
5097
5105
  }
5106
+ if (noun === "students" && verb === "texts") {
5107
+ return runStudentsTextsCommand({ parsed, api, writeCommand });
5108
+ }
5098
5109
  if (noun === "students") {
5099
5110
  if (verb === "list") {
5100
5111
  const requestedScope = flagString(parsed, "scope");
@@ -13,6 +13,8 @@ const BOOLEAN_FLAGS = new Set([
13
13
  "archived",
14
14
  "cancel-subscriptions",
15
15
  "clear",
16
+ "clear-focus",
17
+ "clear-send-hour",
16
18
  "confirm",
17
19
  "confirm-destructive-changes",
18
20
  "disable-applet-follow-ups",
@@ -0,0 +1,78 @@
1
+ import fs from "node:fs/promises";
2
+ import path from "node:path";
3
+ import { unwrap } from "../api.js";
4
+ import { flagNumber, flagString } from "../args.js";
5
+ import { CliError } from "../errors.js";
6
+ import { positional } from "./shared.js";
7
+ const MAX_ROW_LIMIT = 5000;
8
+ async function readSql(parsed) {
9
+ const inline = parsed.positionals[2];
10
+ const file = flagString(parsed, "file");
11
+ if ((inline === undefined) === (file === undefined)) {
12
+ throw new CliError("invalid_arguments", "Pass the SQL either as one quoted argument or with --file <path>, not both.");
13
+ }
14
+ if (inline !== undefined)
15
+ return { sql: inline };
16
+ const absolutePath = path.resolve(file);
17
+ const sql = await fs.readFile(absolutePath, "utf8").catch(() => {
18
+ throw new CliError("invalid_arguments", `Cannot read ${absolutePath}.`);
19
+ });
20
+ return { sql, file: absolutePath };
21
+ }
22
+ /**
23
+ * `recess db query` — one read-only SQL query against the product database,
24
+ * for ADMINs holding `cli:db-query`; `recess db access` — list/grant/revoke
25
+ * that access, for `cli:db-query:grant` holders. The server owns every check
26
+ * (live role + access role, restricted Postgres login); a query is a read, so
27
+ * it needs no confirmation.
28
+ */
29
+ export async function runDbCommand({ parsed, api, writeCommand, }) {
30
+ const verb = parsed.positionals[1];
31
+ if (verb === "query") {
32
+ const { sql, file } = await readSql(parsed);
33
+ const rowLimit = flagNumber(parsed, "limit") ?? 100;
34
+ if (!Number.isInteger(rowLimit) ||
35
+ rowLimit < 1 ||
36
+ rowLimit > MAX_ROW_LIMIT) {
37
+ throw new CliError("invalid_arguments", `--limit must be an integer from 1 to ${MAX_ROW_LIMIT}.`);
38
+ }
39
+ const result = unwrap(await api.client.POST("/admin/db-query/query/", {
40
+ body: { sql, rowLimit },
41
+ }));
42
+ return file ? { file, ...result } : result;
43
+ }
44
+ if (verb === "access") {
45
+ const action = positional(parsed, 2, "access action (list|grant|revoke)");
46
+ if (action === "list") {
47
+ return unwrap(await api.client.GET("/admin/db-query/grants/"));
48
+ }
49
+ if (action !== "grant" && action !== "revoke") {
50
+ throw new CliError("invalid_arguments", "Use db access list|grant|revoke.");
51
+ }
52
+ const userId = flagString(parsed, "user", { required: true });
53
+ // Read-only preflight: the approval must name the exact person gaining or
54
+ // losing global database read access.
55
+ const { user } = unwrap(await api.client.GET("/admin/users/{userId}", {
56
+ params: { path: { userId } },
57
+ }));
58
+ if (action === "grant" && user.role !== "ADMIN") {
59
+ throw new CliError("invalid_arguments", `User ${userId} has role ${user.role}; database query access is ADMIN-only.`);
60
+ }
61
+ const body = { userId, action };
62
+ return writeCommand(parsed, {
63
+ action: action === "grant"
64
+ ? "grant global read-only database query access (recess db query) to this admin"
65
+ : "revoke this user's database query access",
66
+ target: { userId },
67
+ request: body,
68
+ details: {
69
+ email: user.email,
70
+ firstName: user.firstName,
71
+ lastName: user.lastName,
72
+ role: user.role,
73
+ },
74
+ }, async () => unwrap(await api.client.POST("/admin/db-query/grants/", { body })));
75
+ }
76
+ throw new CliError("invalid_arguments", "Use db query|access.");
77
+ }
78
+ //# sourceMappingURL=db.js.map
@@ -0,0 +1,167 @@
1
+ import { unwrap } from "../api.js";
2
+ import { flagString, hasFlag } from "../args.js";
3
+ import { CliError } from "../errors.js";
4
+ import { assertChoice, flagBooleanValue, flagInteger, positional, } from "./shared.js";
5
+ const TEXT_FREQUENCIES = ["all", "daily", "important"];
6
+ function fullName(user) {
7
+ return [user.firstName, user.lastName].filter(Boolean).join(" ");
8
+ }
9
+ /**
10
+ * `users phone get|set|clear` — a user's SMS/login phone number. The server
11
+ * normalizes whatever is typed to E.164 (bare numbers read as US) and rejects
12
+ * invalid or already-taken numbers, so the preview shows the raw input.
13
+ */
14
+ export async function runUsersPhoneCommand({ parsed, api, writeCommand, }) {
15
+ const action = positional(parsed, 2, "users phone action");
16
+ if (!["get", "set", "clear"].includes(action)) {
17
+ throw new CliError("invalid_arguments", "Use users phone get|set|clear.");
18
+ }
19
+ const userId = positional(parsed, 3, "user ID");
20
+ const phoneNumber = action === "set" ? flagString(parsed, "phone", { required: true }) : null;
21
+ const { user } = unwrap(await api.client.GET("/admin/users/{userId}", {
22
+ params: { path: { userId } },
23
+ }));
24
+ const current = {
25
+ userId: user.id,
26
+ name: fullName(user),
27
+ role: user.role,
28
+ phoneNumber: user.phoneNumber ?? null,
29
+ };
30
+ if (action === "get")
31
+ return current;
32
+ return writeCommand(parsed, {
33
+ action: phoneNumber === null
34
+ ? "remove the user's phone number (they stop receiving SMS and can't sign in by phone)"
35
+ : "set the user's phone number (stored as E.164 and marked unverified until their next phone sign-in)",
36
+ target: { userId: user.id },
37
+ request: { phoneNumber },
38
+ details: { current },
39
+ }, async () => {
40
+ const result = unwrap(await api.client.PATCH("/admin/users/{userId}", {
41
+ params: { path: { userId: user.id } },
42
+ body: { phoneNumber },
43
+ }));
44
+ return { ...current, phoneNumber: result.phoneNumber ?? null };
45
+ });
46
+ }
47
+ /**
48
+ * `students texts get|set|set-guardian` — the parent SMS activity-summary
49
+ * controls. Student-level: summary on/off and the end-of-day send hour (in the
50
+ * student's timezone). Per guardian: texts on/off, frequency, and the custom
51
+ * focus instructions that steer that guardian's summaries.
52
+ */
53
+ export async function runStudentsTextsCommand({ parsed, api, writeCommand, }) {
54
+ const action = positional(parsed, 2, "students texts action");
55
+ if (!["get", "set", "set-guardian"].includes(action)) {
56
+ throw new CliError("invalid_arguments", "Use students texts get|set|set-guardian.");
57
+ }
58
+ const studentId = positional(parsed, 3, "student ID");
59
+ // Validate every flag before the first request.
60
+ const studentBody = action === "set" ? studentTextsBody(parsed) : undefined;
61
+ const guardianId = action === "set-guardian" ? positional(parsed, 4, "guardian ID") : "";
62
+ const guardianBody = action === "set-guardian" ? guardianTextsBody(parsed) : undefined;
63
+ const readSettings = async () => {
64
+ const [profile, focuses] = await Promise.all([
65
+ api.client.GET("/tutor/students/{studentId}/profile", {
66
+ params: { path: { studentId } },
67
+ }),
68
+ api.client.GET("/admin/browser/students/{userId}/guardian-focuses/", {
69
+ params: { path: { userId: studentId } },
70
+ }),
71
+ ]);
72
+ const student = unwrap(profile);
73
+ return {
74
+ studentId,
75
+ timezone: student.timezone,
76
+ summaryEnabled: student.dailySummaryEnabled,
77
+ sendHour: student.dailySummarySendHour,
78
+ recipients: unwrap(focuses).guardians.map((guardian) => ({
79
+ guardianId: guardian.guardianId,
80
+ name: fullName(guardian),
81
+ email: guardian.email,
82
+ phoneNumber: guardian.phoneNumber,
83
+ isFamilyMember: guardian.isFamilyMember,
84
+ hasSubscription: guardian.hasSubscription,
85
+ textsEnabled: guardian.textsEnabled,
86
+ textFrequency: guardian.textFrequency,
87
+ focus: guardian.dailySummaryFocus,
88
+ })),
89
+ };
90
+ };
91
+ const current = await readSettings();
92
+ if (action === "get")
93
+ return current;
94
+ if (studentBody) {
95
+ return writeCommand(parsed, {
96
+ action: "update the student's parent SMS summary settings (applies to every recipient)",
97
+ target: { studentId },
98
+ request: studentBody,
99
+ details: {
100
+ current: {
101
+ summaryEnabled: current.summaryEnabled,
102
+ sendHour: current.sendHour,
103
+ timezone: current.timezone,
104
+ },
105
+ },
106
+ }, async () => {
107
+ unwrap(await api.client.PATCH("/tutor/students/{studentId}/profile", {
108
+ params: { path: { studentId } },
109
+ body: studentBody,
110
+ }));
111
+ return readSettings();
112
+ });
113
+ }
114
+ const recipient = current.recipients.find((r) => r.guardianId === guardianId) ?? null;
115
+ return writeCommand(parsed, {
116
+ action: recipient
117
+ ? "update this recipient's SMS settings for the student"
118
+ : "subscribe a new recipient to the student's SMS summaries (only ADMINs may be subscribed across families)",
119
+ target: { studentId, guardianId },
120
+ request: guardianBody,
121
+ details: { current: recipient },
122
+ }, async () => unwrap(await api.client.PATCH("/admin/browser/students/{userId}/guardian-focuses/{guardianId}/", {
123
+ params: { path: { userId: studentId, guardianId } },
124
+ body: guardianBody,
125
+ })));
126
+ }
127
+ function studentTextsBody(parsed) {
128
+ const summaryEnabled = flagBooleanValue(parsed, "summary-enabled");
129
+ const clearSendHour = hasFlag(parsed, "clear-send-hour");
130
+ const sendHour = flagInteger(parsed, "send-hour", { min: 0, max: 23 });
131
+ if (clearSendHour && sendHour !== undefined) {
132
+ throw new CliError("invalid_arguments", "Pass --send-hour or --clear-send-hour, not both.");
133
+ }
134
+ const body = {
135
+ ...(summaryEnabled !== undefined && {
136
+ dailySummaryEnabled: summaryEnabled,
137
+ }),
138
+ ...(sendHour !== undefined && { dailySummarySendHour: sendHour }),
139
+ ...(clearSendHour && { dailySummarySendHour: null }),
140
+ };
141
+ if (Object.keys(body).length === 0) {
142
+ throw new CliError("invalid_arguments", "Pass at least one of --summary-enabled, --send-hour, --clear-send-hour.");
143
+ }
144
+ return body;
145
+ }
146
+ function guardianTextsBody(parsed) {
147
+ const textsEnabled = flagBooleanValue(parsed, "texts-enabled");
148
+ const frequency = flagString(parsed, "frequency");
149
+ const focus = flagString(parsed, "focus");
150
+ const clearFocus = hasFlag(parsed, "clear-focus");
151
+ if (focus !== undefined && clearFocus) {
152
+ throw new CliError("invalid_arguments", "Pass --focus or --clear-focus, not both.");
153
+ }
154
+ const body = {
155
+ ...(textsEnabled !== undefined && { textsEnabled }),
156
+ ...(frequency !== undefined && {
157
+ textFrequency: assertChoice(frequency, TEXT_FREQUENCIES, "--frequency").toUpperCase(),
158
+ }),
159
+ ...(focus !== undefined && { dailySummaryFocus: focus }),
160
+ ...(clearFocus && { dailySummaryFocus: null }),
161
+ };
162
+ if (Object.keys(body).length === 0) {
163
+ throw new CliError("invalid_arguments", "Pass at least one of --texts-enabled, --frequency, --focus, --clear-focus.");
164
+ }
165
+ return body;
166
+ }
167
+ //# sourceMappingURL=phone-and-texts.js.map
package/dist/help.js CHANGED
@@ -47,6 +47,9 @@ Usage:
47
47
  recess [--json] users enrollment set <user-id>
48
48
  --entity online-learning-program|recess-academy-school|partner-school|unset
49
49
  [--partner-school <school-id-or-slug>] [--confirm]
50
+ recess [--json] users phone get <user-id>
51
+ recess [--json] users phone set <user-id> --phone <number> [--confirm]
52
+ recess [--json] users phone clear <user-id> [--confirm]
50
53
  recess [--json] users lock <user-id> [--confirm]
51
54
  recess [--json] users unlock <user-id> [--confirm]
52
55
  recess [--json] users disable <user-id> [--whole-family] [--allow-billing] [--confirm]
@@ -62,6 +65,12 @@ Usage:
62
65
  recess [--json] guides invite --user <user-id> [--confirm]
63
66
  recess [--json] guardians invite --family <family-id> --email <email>
64
67
  --first-name TEXT [--last-name TEXT] [--no-invite] [--confirm]
68
+ recess [--json] students texts get <kid-id>
69
+ recess [--json] students texts set <kid-id> [--summary-enabled true|false]
70
+ [--send-hour <0-23> | --clear-send-hour] [--confirm]
71
+ recess [--json] students texts set-guardian <kid-id> <guardian-id>
72
+ [--texts-enabled true|false] [--frequency all|daily|important]
73
+ [--focus <text> | --clear-focus] [--confirm]
65
74
  recess [--json] students upload-map-scores --student <kid-id>
66
75
  --file </path/to/map-report.pdf> [--confirm]
67
76
  recess [--json] chat-logs list --student <user-id> [--limit 100] [--cursor <cursor>]
@@ -352,6 +361,10 @@ Usage:
352
361
  [--sort-order asc|desc]
353
362
  recess [--json] store-items set-status <village-store-item-id>
354
363
  --status ACTIVE|INACTIVE|COMING_SOON [--confirm]
364
+ recess [--json] db query [sql] [--file <path.sql>] [--limit 100]
365
+ recess [--json] db access list
366
+ recess [--json] db access grant --user <user-id> [--confirm]
367
+ recess [--json] db access revoke --user <user-id> [--confirm]
355
368
  recess [--json] content-library search <query> [--limit 8]
356
369
  recess [--json] content-library status <gem-id-or-url>
357
370
  recess [--json] content-library set-stage [<gem-id-or-url>...] [--file <path>]
@@ -584,6 +597,19 @@ what the account was; ADMIN and MODERATOR are not restorable from the CLI.
584
597
  Note that after a disable "users get" and "users search" no longer resolve the
585
598
  account — the confirmed write's own response is the record of what changed.
586
599
 
600
+ "users phone set" accepts any common format; the server stores E.164 (a number
601
+ without +country is read as US), rejects invalid or already-taken numbers, and
602
+ marks the new number unverified until the user's next phone sign-in.
603
+
604
+ Parent SMS summary notes: "students texts get" shows the kid-level switch and
605
+ end-of-day send hour (0-23 in the kid's timezone; unset = 18) plus every
606
+ recipient's phone, texts on/off, frequency, and focus. "set" changes the
607
+ kid-level switch/hour for all recipients. "set-guardian" changes one adult's
608
+ settings: --frequency all = per-todo texts + daily summary, daily = the daily
609
+ summary only, important = only non-routine summaries; --focus is that adult's
610
+ custom instructions for what the summary should emphasize. A recipient with no
611
+ phone number receives nothing, so check "users phone get" too.
612
+
587
613
  Onboarding notes: "status" and "intake-session" are reads — "intake-session"
588
614
  looks up the current IN_PROGRESS session without creating one (prints a "none
589
615
  yet" result when absent). "intake-session-create" is the explicit write that
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "recess-cli",
3
- "version": "3.5.0",
3
+ "version": "3.6.0",
4
4
  "description": "Safe Recess administration and family AI tools from the command line.",
5
5
  "license": "UNLICENSED",
6
6
  "repository": {