@velaro/cli 1.2.0 → 1.4.9

package/lib/commands/appointments.js

@@ -0,0 +1,198 @@
+import { messagingGet, messagingPost, messagingPut } from '../api.js';
+import { runCommand } from '../run.js';
+
+const STATUS_LABELS = { 0: 'Scheduled', 1: 'Confirmed', 2: 'Completed', 3: 'NoShow', 4: 'Cancelled' };
+function statusLabel(s) { return typeof s === 'number' ? (STATUS_LABELS[s] ?? String(s)) : s; }
+function fmtDate(d) { return d ? new Date(d).toISOString().replace('T', ' ').slice(0, 16) : '-'; }
+
+// ── velaro appointments ───────────────────────────────────────────────────────
+// CLI surface for Velaro Appointments (multi-calendar text-to-book scheduling).
+// Mirrors the appointments_* MCP tools. Endpoints live in velaro-messaging at
+// /Appointments/*  — they wrap FindOpenSlotsSkill / BookAppointmentSkill /
+// ManageAppointmentSkill and apply the caller's siteId from JWT.
+//
+// Marketing page: /appointments (admin app) and marketing/landing-pages/appointments.html.
+
+export const appointmentsCommand = {
+  command:  'appointments <subcommand>',
+  describe: 'Velaro Appointments — multi-calendar text-to-book scheduling',
+  builder:  yargs => yargs
+    .command({
+      command:  'list-slots',
+      describe: 'Find open slots across every connected calendar (Outlook / MS Bookings / Calendly)',
+      builder:  y => y
+        .option('from',     { type: 'string', demandOption: true,  describe: 'ISO date or datetime to check (YYYY-MM-DD)' })
+        .option('to',       { type: 'string', demandOption: false, describe: 'Optional end date — repeats list-slots for each day in range' })
+        .option('duration', { type: 'number', default: 30,         describe: 'Slot length in minutes (default 30)' }),
+      handler:  runCommand(async argv => {
+        const from = argv.from;
+        const to   = argv.to || argv.from;
+        const fromDate = new Date(from);
+        const toDate   = new Date(to);
+        if (Number.isNaN(fromDate.getTime()) || Number.isNaN(toDate.getTime())) {
+          throw new Error('Invalid --from or --to. Use YYYY-MM-DD.');
+        }
+        const days = [];
+        for (let d = new Date(fromDate); d <= toDate; d.setUTCDate(d.getUTCDate() + 1)) {
+          days.push(d.toISOString().slice(0, 10));
+        }
+        for (const day of days) {
+          const data = await messagingPost('/Appointments/FindOpenSlots', {
+            date: day,
+            durationMinutes: argv.duration,
+          });
+          if (!data?.success) {
+            console.log(`\n${day}: ${data?.message ?? '(no slots)'}`);
+            continue;
+          }
+          console.log(`\n${day} (${data.duration_minutes ?? argv.duration}-min slots) — calendars: ${(data.connected_calendars ?? []).join(', ') || '(none)'}`);
+          for (const s of data.available_slots ?? []) console.log(`  ${s}`);
+        }
+        console.log('');
+      }),
+    })
+    .command({
+      command:  'book',
+      describe: 'Book an appointment on the site\'s connected calendar',
+      builder:  y => y
+        .option('start',    { type: 'string', demandOption: true,  describe: 'ISO-8601 start time (e.g. 2026-06-01T15:00:00Z)' })
+        .option('duration', { type: 'number', default: 30,         describe: 'Duration in minutes' })
+        .option('summary',  { type: 'string', demandOption: true,  describe: 'Short title (e.g. "Cleaning - Jane Doe")' })
+        .option('email',    { type: 'string', demandOption: false, describe: 'Attendee email' })
+        .option('name',     { type: 'string', demandOption: false, describe: 'Attendee name' })
+        .option('location', { type: 'string', demandOption: false, describe: 'Physical or virtual location' })
+        .option('reason',   { type: 'string', demandOption: false, describe: 'Short category (cleaning, consult, etc.)' }),
+      handler:  runCommand(async argv => {
+        const data = await messagingPost('/Appointments/Book', {
+          start:           argv.start,
+          durationMinutes: argv.duration,
+          summary:         argv.summary,
+          attendeeEmail:   argv.email   ?? null,
+          attendeeName:    argv.name    ?? null,
+          location:        argv.location ?? null,
+          reason:          argv.reason  ?? null,
+        });
+        if (!data?.success) {
+          throw new Error(data?.message ?? 'Book failed');
+        }
+        console.log(`\n✓ Booked via ${data.provider}`);
+        console.log(`  event_id: ${data.event_id}`);
+        console.log(`  start:    ${data.start}`);
+        console.log(`  end:      ${data.end}`);
+        if (data.join_url) console.log(`  join:     ${data.join_url}`);
+        console.log('\n  Hand the provider+event_id to "velaro appointments manage" to reschedule or cancel.\n');
+      }),
+    })
+    .command({
+      command:  'manage',
+      describe: 'Reschedule or cancel an existing appointment',
+      builder:  y => y
+        .option('intent',   { type: 'string', demandOption: true,  choices: ['reschedule', 'cancel'], describe: 'reschedule or cancel' })
+        .option('provider', { type: 'string', demandOption: true,  describe: 'Provider slug returned by book (outlook | msbookings | calendly)' })
+        .option('event-id', { type: 'string', demandOption: true,  describe: 'Event id returned by book' })
+        .option('start',    { type: 'string', demandOption: false, describe: 'New ISO-8601 start (required when intent=reschedule)' })
+        .option('duration', { type: 'number', demandOption: false, describe: 'New duration in minutes' })
+        .option('summary',  { type: 'string', demandOption: false, describe: 'Optional new title' }),
+      handler:  runCommand(async argv => {
+        if (argv.intent === 'reschedule' && !argv.start) {
+          throw new Error('--start is required when --intent=reschedule');
+        }
+        const data = await messagingPost('/Appointments/Manage', {
+          intent:          argv.intent,
+          provider:        argv.provider,
+          eventId:         argv['event-id'],
+          start:           argv.start ?? null,
+          durationMinutes: argv.duration ?? null,
+          summary:         argv.summary ?? null,
+        });
+        if (!data?.success) {
+          throw new Error(data?.message ?? `${argv.intent} failed`);
+        }
+        console.log(`\n✓ ${data.message ?? `${argv.intent} ok`}`);
+        if (data.new_start) console.log(`  new_start: ${data.new_start}`);
+        if (data.new_end)   console.log(`  new_end:   ${data.new_end}`);
+        console.log('');
+      }),
+    })
+    .command({
+      command:  'install-template',
+      describe: 'Install the "Text-to-book appointments" starter workflow for the current site',
+      handler:  runCommand(async () => {
+        const data = await messagingPost('/Workflows/InstallStarterTemplate', {
+          templateKey: 'appointments-text-to-book',
+        });
+        if (data?.workflowId) {
+          console.log(`\n✓ Installed "Text-to-book appointments" starter workflow → workflow id ${data.workflowId}`);
+          console.log('  Open Admin → Workflows to activate it.\n');
+        } else {
+          console.log('\n✓ Install request accepted.\n' + JSON.stringify(data, null, 2) + '\n');
+        }
+      }),
+    })
+    .command({
+      // Distinct from `book` (AI-skill booking via FindOpenSlotsSkill/BookAppointmentSkill) --
+      // this is the staff-facing "log a phone-in caller" path, backed by the first-party
+      // Appointment entity (server/Velaro.Messaging/Controllers/AppointmentsController.cs POST
+      // Appointments/Manual). Reminders (if enabled) are scheduled automatically by the backend.
+      command:  'manual-book',
+      describe: 'Log a phone-in appointment on behalf of a caller (distinct from `book` -- this is the staff-entry path, not the AI-skill path)',
+      builder:  y => y
+        .option('name',         { describe: 'Caller name', type: 'string' })
+        .option('phone',        { describe: 'Caller phone number -- required', type: 'string', demandOption: true })
+        .option('email',        { describe: 'Caller email', type: 'string' })
+        .option('start',        { describe: 'Start time, ISO 8601 UTC -- required', type: 'string', demandOption: true })
+        .option('end',          { describe: 'End time, ISO 8601 UTC -- required', type: 'string', demandOption: true })
+        .option('timezone',     { describe: 'IANA timezone id (default America/Los_Angeles)', type: 'string' })
+        .option('notes',        { describe: 'Free-text notes', type: 'string' })
+        .option('write-target', { describe: 'Which connected calendar this is associated with', type: 'string' }),
+      handler: runCommand(async (argv) => {
+        const result = await messagingPost('/Appointments/Manual', {
+          customerName:    argv.name,
+          customerPhone:   argv.phone,
+          customerEmail:   argv.email,
+          startUtc:        argv.start,
+          endUtc:          argv.end,
+          timeZone:        argv.timezone,
+          notes:           argv.notes,
+          writeTargetSlug: argv.writeTarget,
+        });
+        console.log(`\n✓ Appointment logged (id ${result.id}) for ${result.customerName || result.customerPhone}.`);
+        console.log(`  ${fmtDate(result.startUtc)} - ${fmtDate(result.endUtc)} (${result.timeZone})\n`);
+      }),
+    })
+    .command({
+      command:  'list-appointments',
+      describe: 'List logged appointments (bot-booked and phone-in), optionally filtered by date range',
+      builder:  y => y
+        .option('from', { describe: 'Only include appointments starting at/after this ISO 8601 UTC timestamp', type: 'string' })
+        .option('to',   { describe: 'Only include appointments starting at/before this ISO 8601 UTC timestamp', type: 'string' }),
+      handler: runCommand(async (argv) => {
+        const params = new URLSearchParams();
+        if (argv.from) params.set('fromUtc', argv.from);
+        if (argv.to) params.set('toUtc', argv.to);
+        const qs = params.toString();
+        const appointments = await messagingGet(`/Appointments${qs ? `?${qs}` : ''}`);
+        if (!Array.isArray(appointments) || !appointments.length) {
+          console.log('\n  No appointments found.\n');
+          return;
+        }
+        console.log('\nAppointments\n');
+        for (const a of appointments) {
+          console.log(`  id:${a.id}  ${fmtDate(a.startUtc)}  ${a.customerName || a.customerPhone}  ${statusLabel(a.status)}`);
+        }
+        console.log('');
+      }),
+    })
+    .command({
+      command:  'set-status <appointmentId> <status>',
+      describe: 'Update a logged appointment\'s status (Scheduled | Confirmed | Completed | NoShow | Cancelled)',
+      builder:  y => y
+        .positional('appointmentId', { describe: 'Appointment ID', type: 'number' })
+        .positional('status',        { describe: 'New status', type: 'string' }),
+      handler: runCommand(async (argv) => {
+        const result = await messagingPut(`/Appointments/${argv.appointmentId}/status`, { status: argv.status });
+        console.log(`\n✓ Appointment ${argv.appointmentId} status set to ${statusLabel(result.status)}.\n`);
+      }),
+    })
+    .demandCommand(1, 'Specify a subcommand: list-slots | book | manage | install-template | manual-book | list-appointments | set-status'),
+};