@springbrand/hr-cli 0.3.0 → 0.4.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.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: saas-hr-cli
3
- description: Use the `hr` command to work with SpringBrand HR (recruiting) on the user's behalf: jobs, the talent pool, screening, interview scheduling and approvals. Use when the user asks about candidates, resumes, open roles, screening or interviews.
3
+ description: Use the `hr` command to work with SpringBrand HR (recruiting) on the user's behalf: jobs, the talent pool, screening, booking interviews (then putting them on a calendar with another tool) and approvals. Use when the user asks about candidates, resumes, open roles, screening or interviews.
4
4
  ---
5
5
 
6
6
  # hr CLI
@@ -26,6 +26,14 @@ The rules below are what the help cannot tell you.
26
26
  - `APP_CONFLICT` means the state changed, for example the candidate was already screened. List again.
27
27
  - `APP_FORBIDDEN` means the caller lacks the permission and it cannot be approved. It is granted in IAM.
28
28
 
29
+ ## Interviews and calendars
30
+
31
+ - HR only records an interview's time, place and interviewers. It puts nothing on any calendar and invites nobody, the candidate included.
32
+ - When the user wants it on a calendar, first record it with `hr interviews schedule`, then create the event with the calendar tool you have for the user (for example Feishu). Put the candidate, job and `url` in the event. Keep the interview `id` with it.
33
+ - When an interview moves or is cancelled, change HR first (`reschedule`, `cancel`), then the calendar event.
34
+ - Pass times with the user's UTC offset. If you do not know their time zone, ask. Never let a bare "3 pm" be read in some other zone.
35
+ - Interviewers are people. An Agent must name them; when the user says "me", find the user with `hr people search`.
36
+
29
37
  ## Approvals
30
38
 
31
39
  Without the permission, a change waits for a person in IAM, and the command answers with `data.pendingApproval: { approvalId }`. **The action has not happened yet.** Do not say the candidate was rejected. Tell the user it is waiting for approval, then check when asked, or wait with `hr approvals status <approvalId> --wait`.
package/dist/hr.js CHANGED
@@ -88,6 +88,9 @@ var Hr = class {
88
88
  post(pathname, body) {
89
89
  return this.request(`${this.apiUrl}/api/v1${pathname}`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
90
90
  }
91
+ patch(pathname, body) {
92
+ return this.request(`${this.apiUrl}/api/v1${pathname}`, { method: "PATCH", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) });
93
+ }
91
94
  async request(url, init) {
92
95
  const token = await this.token();
93
96
  return unwrap(await this.send(url, { ...init, headers: { ...init.headers, Authorization: `Bearer ${token}` } }, "HR"), "HR");
@@ -181,6 +184,16 @@ var Commands = [
181
184
  { usage: "hr screening pass <name|id> [--job <job>]", does: "Pass a candidate waiting for screening to the next stage.", returns: "data: the updated application, or data.pendingApproval (see below)." },
182
185
  { usage: "hr screening reject <name|id> --reason <reason> [--job <job>]", does: "Reject a candidate waiting for screening. <reason> comes from `hr reasons list`.", returns: "data: the updated application, or data.pendingApproval (see below)." },
183
186
  { usage: "hr interviews to-schedule [--job <job>] [--page n] [--page-size n]", does: "Candidates in an interview stage with no interview booked.", returns: "data: { total, items: [{ id, talentName, jobTitle, stageName, url }] }" },
187
+ {
188
+ usage: "hr interviews schedule <name|id> --start <time> [--end <time> | --minutes n] [--location text] [--with <people>] [--job <job>]",
189
+ does: "Book an interview for a candidate waiting in `hr interviews to-schedule` (or an application id). <time> is ISO 8601 with its UTC offset, such as 2026-11-12T15:00+08:00. Length defaults to 60 minutes. <people> are interviewers, comma-separated names, emails or ids from `hr people search`; a person calling may leave it out to interview alone, an Agent must pass it. HR only records the interview: it puts nothing on any calendar.",
190
+ returns: "data: { id, applicationId, round, status, startsAt, endsAt, locationOrLink, participants: [{ principalId, submitted }], talentName, jobTitle, url }. Times are UTC.",
191
+ example: 'hr interviews schedule "Li Wei" --start 2026-11-12T15:00+08:00 --with "Rita Tan" --location "Room 3"'
192
+ },
193
+ { usage: "hr interviews list <application id>", does: "Every interview of one application, latest first.", returns: "data: [{ id, applicationId, round, status, startsAt, endsAt, locationOrLink, participants: [{ principalId, submitted }], url }]. Times are UTC." },
194
+ { usage: "hr interviews reschedule <interview id> [--start <time>] [--end <time> | --minutes n] [--location text]", does: "Move or relocate an interview. A new --start keeps the length unless --end or --minutes is given.", returns: "data: { id, applicationId, round, status, startsAt, endsAt, locationOrLink, participants: [{ principalId, submitted }], talentName, jobTitle, url }. Times are UTC." },
195
+ { usage: "hr interviews cancel <interview id>", does: "Cancel an interview.", returns: "data: { id, applicationId, round, status, startsAt, endsAt, locationOrLink, participants: [{ principalId, submitted }], talentName, jobTitle, url }. Times are UTC." },
196
+ { usage: "hr people search <name>", does: "People (not Agents) in the organization, to name interviewers.", returns: "data: [{ id, name, email, jobTitle }]" },
184
197
  { usage: "hr reasons list", does: "Reject reasons.", returns: "data: [{ id, name, category }]. Rejecting uses those with category we_rejected." },
185
198
  { usage: "hr approvals status <id> [--wait] [--timeout seconds]", does: "Where an approval stands; --wait polls until it is decided or the timeout (default 300) passes.", returns: "data: { status: pending | executed | rejected | failed, error? }" }
186
199
  ];
@@ -213,6 +226,11 @@ var options = {
213
226
  wait: { type: "boolean" },
214
227
  "no-browser": { type: "boolean" },
215
228
  timeout: { type: "string" },
229
+ start: { type: "string" },
230
+ end: { type: "string" },
231
+ minutes: { type: "string" },
232
+ location: { type: "string" },
233
+ with: { type: "string" },
216
234
  help: { type: "boolean", short: "h" }
217
235
  };
218
236
  async function linked(hr, records, page2) {
@@ -244,6 +262,46 @@ async function rejectReason(hr, reason) {
244
262
  const reasons = (await hr.get("/reject-reasons")).filter((entry) => entry.category === "we_rejected");
245
263
  return pickOne(reasons, reason, (entry) => [entry.name], (entry) => ({ id: entry.id, name: entry.name }), "reject reason").id;
246
264
  }
265
+ function time(value, flag) {
266
+ const date = new Date(value);
267
+ if (!/T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})$/i.test(value) || Number.isNaN(date.getTime())) {
268
+ throw new CliError("USAGE", `${flag} needs an ISO 8601 time with its UTC offset, such as 2026-11-12T15:00+08:00`);
269
+ }
270
+ return date;
271
+ }
272
+ function minutes(value) {
273
+ const length = Number(value);
274
+ if (!Number.isInteger(length) || length < 5 || length > 600) throw new CliError("USAGE", "--minutes is a whole number from 5 to 600");
275
+ return length;
276
+ }
277
+ function slot(values, current) {
278
+ if (values.end && values.minutes) throw new CliError("USAGE", "Pass --end or --minutes, not both");
279
+ const startsAt = values.start ? time(values.start, "--start") : current ? new Date(current.startsAt) : void 0;
280
+ if (!startsAt) throw new CliError("USAGE", "Pass --start");
281
+ const length = values.minutes ? minutes(values.minutes) : current ? (new Date(current.endsAt).getTime() - new Date(current.startsAt).getTime()) / 6e4 : 60;
282
+ const endsAt = values.end ? time(values.end, "--end") : new Date(startsAt.getTime() + length * 6e4);
283
+ return { startsAt: startsAt.toISOString(), endsAt: endsAt.toISOString() };
284
+ }
285
+ var people = async (hr) => (await hr.get("/people")).filter((person) => person.type === "human");
286
+ var describePerson = (person) => ({ id: person.id, name: person.displayName, email: person.email, jobTitle: person.jobTitle });
287
+ async function interviewers(hr, names) {
288
+ if (!names) {
289
+ const me = await hr.get("/me");
290
+ if (me.kind !== "human") throw new CliError("USAGE", "Say who interviews: pass --with with names from `hr people search`");
291
+ return [me.principalId];
292
+ }
293
+ const everyone = await people(hr);
294
+ return names.split(",").map((name) => name.trim()).filter(Boolean).map((name) => isId(name) ? name : pickOne(everyone, name, (person) => [person.displayName, person.email], describePerson, "person").id);
295
+ }
296
+ async function toScheduleApplication(hr, who, job) {
297
+ if (isId(who)) return who;
298
+ const queue = await hr.get("/applications", { queue: "to_schedule", jobId: await jobId(hr, job), pageSize: 200 });
299
+ return pickOne(queue.items, who, (item) => [item.talentName], (item) => ({ id: item.id, talent: item.talentName, job: item.jobTitle }), "candidate waiting for an interview").id;
300
+ }
301
+ async function described(hr, interview) {
302
+ const detail = await hr.get(`/applications/${interview.applicationId}`);
303
+ return { ...interview, talentName: detail.talent.displayName, jobTitle: detail.job.title, url: `${await hr.appOrigin()}/applications/${interview.applicationId}` };
304
+ }
247
305
  async function approvalStatus(hr, deps, id, wait, timeoutSeconds) {
248
306
  const deadline = Date.now() + timeoutSeconds * 1e3;
249
307
  for (; ; ) {
@@ -288,6 +346,30 @@ async function dispatch(args, deps) {
288
346
  }
289
347
  case "interviews to-schedule":
290
348
  return linkedPage(hr, await hr.get("/applications", { queue: "to_schedule", jobId: await jobId(hr, values.job), ...page2 }), "applications");
349
+ case "interviews schedule": {
350
+ const applicationId = await toScheduleApplication(hr, needed("a candidate", rest.join(" ")), values.job);
351
+ const body = { ...slot(values), participants: await interviewers(hr, values.with), ...values.location !== void 0 ? { locationOrLink: values.location } : {} };
352
+ return described(hr, await hr.post(`/applications/${applicationId}/interviews`, body));
353
+ }
354
+ case "interviews list": {
355
+ const applicationId = needed("an application id", rest[0]);
356
+ const url = `${await hr.appOrigin()}/applications/${applicationId}`;
357
+ return (await hr.get("/interviews", { applicationId })).map((interview) => ({ ...interview, url }));
358
+ }
359
+ case "interviews reschedule": {
360
+ const id = needed("an interview id", rest[0]);
361
+ if (!values.start && !values.end && !values.minutes && values.location === void 0) throw new CliError("USAGE", "Pass --start, --end, --minutes or --location");
362
+ const current = await hr.get(`/interviews/${id}`);
363
+ const times = values.start || values.end || values.minutes ? slot(values, current) : {};
364
+ return described(hr, await hr.patch(`/interviews/${id}`, { ...times, ...values.location !== void 0 ? { locationOrLink: values.location } : {} }));
365
+ }
366
+ case "interviews cancel":
367
+ return described(hr, await hr.patch(`/interviews/${needed("an interview id", rest[0])}`, { status: "cancelled" }));
368
+ case "people search": {
369
+ const everyone = await people(hr);
370
+ const wanted = rest.join(" ").trim().toLowerCase();
371
+ return everyone.filter((person) => !wanted || [person.displayName, person.email].some((value) => value?.toLowerCase().includes(wanted))).map(describePerson);
372
+ }
291
373
  case "reasons list":
292
374
  return hr.get("/reject-reasons");
293
375
  case "approvals status":
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@springbrand/hr-cli",
3
- "version": "0.3.0",
3
+ "version": "0.4.0",
4
4
  "description": "SpringBrand HR from the command line, for people and Agents.",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",
@@ -24,16 +24,15 @@
24
24
  "url": "git+ssh://git@github.com/springbrand-lab/saas-hr.git",
25
25
  "directory": "packages/cli"
26
26
  },
27
- "scripts": {
28
- "build": "esbuild src/bin.ts --bundle --platform=node --format=esm --target=node24 --outfile=dist/hr.js --banner:js=\"#!/usr/bin/env node\"",
29
- "check": "tsc --noEmit",
30
- "test": "vitest run",
31
- "prepublishOnly": "pnpm run build && pnpm run test"
32
- },
33
27
  "devDependencies": {
34
28
  "@types/node": "^24.13.3",
35
29
  "esbuild": "^0.27.4",
36
30
  "typescript": "^7.0.2",
37
31
  "vitest": "^4.1.10"
32
+ },
33
+ "scripts": {
34
+ "build": "esbuild src/bin.ts --bundle --platform=node --format=esm --target=node24 --outfile=dist/hr.js --banner:js=\"#!/usr/bin/env node\"",
35
+ "check": "tsc --noEmit",
36
+ "test": "vitest run"
38
37
  }
39
- }
38
+ }