@vellumai/assistant 0.10.2-dev.202606250318.5e7cfb0 → 0.10.2

package/src/onboarding/checkin-event.test.ts

@@ -1,222 +0,0 @@
-import { describe, expect, test } from "bun:test";
-
-import {
-  buildCheckinDescription,
-  buildCheckinTitle,
-  type BusyInterval,
-  checkinAvailabilityWindow,
-  chooseCheckinSlot,
-  extractBusyFromEvents,
-  findFirstOpenSlot,
-  type GcalEvent,
-  tomorrowInTimeZone,
-  zonedWallTimeToUtcMs,
-} from "./checkin-event.js";
-
-const TZ = "America/New_York";
-const MIN = 60 * 1000;
-const HOUR = 60 * MIN;
-
-// A fixed "now": 2024-01-15 18:00 UTC (= 1pm EST). Tomorrow is 2024-01-16.
-const NOW = Date.parse("2024-01-15T18:00:00Z");
-
-/** Helper: epoch ms for tomorrow (2024-01-16) at a given EST hour. */
-function estTomorrow(hour: number, minute = 0): number {
-  return zonedWallTimeToUtcMs(2024, 1, 16, hour, minute, TZ);
-}
-
-describe("buildCheckinTitle", () => {
-  test("both names", () => {
-    expect(
-      buildCheckinTitle({ userName: "Alex", assistantName: "Jarvis" }),
-    ).toBe("Alex <> Jarvis: Day 2 Check-in");
-  });
-  test("user only", () => {
-    expect(buildCheckinTitle({ userName: "Alex" })).toBe(
-      "Alex: Day 2 Check-in",
-    );
-  });
-  test("assistant only", () => {
-    expect(buildCheckinTitle({ assistantName: "Jarvis" })).toBe(
-      "Jarvis: Day 2 Check-in",
-    );
-  });
-  test("neither (blank strings dropped)", () => {
-    expect(buildCheckinTitle({ userName: "  ", assistantName: "" })).toBe(
-      "Day 2 Check-in",
-    );
-  });
-});
-
-describe("buildCheckinDescription", () => {
-  test("embeds the uuid + fixed first-week prompt in the CTA link", () => {
-    const html = buildCheckinDescription("uuid-123");
-    expect(html).toContain(
-      "https://www.vellum.ai/assistant/conversations/uuid-123?prompt=What%20would%20you%20recommend",
-    );
-    // Carries onboarding attribution for the calendar-event CTA.
-    expect(html).toContain("&utm_source=onboarding&utm_medium=calendar_event");
-    // Only sanitization-safe tags; the CTA is a bold link, not a styled button.
-    expect(html).toContain("<a href=");
-    expect(html).toContain("<strong>");
-    expect(html).not.toContain("style=");
-  });
-});
-
-describe("findFirstOpenSlot", () => {
-  const windowStart = 0;
-  const windowEnd = 60 * MIN;
-  const dur = 15 * MIN;
-
-  test("empty calendar → start of window", () => {
-    expect(findFirstOpenSlot(windowStart, windowEnd, [], dur)).toBe(
-      windowStart,
-    );
-  });
-
-  test("busy at start → first gap after it", () => {
-    const busy: BusyInterval[] = [{ start: 0, end: 20 * MIN }];
-    expect(findFirstOpenSlot(windowStart, windowEnd, busy, dur)).toBe(20 * MIN);
-  });
-
-  test("finds a gap between two meetings", () => {
-    const busy: BusyInterval[] = [
-      { start: 0, end: 10 * MIN },
-      { start: 30 * MIN, end: 60 * MIN },
-    ];
-    // gap [10,30) is 20min >= 15min → slot at 10min.
-    expect(findFirstOpenSlot(windowStart, windowEnd, busy, dur)).toBe(10 * MIN);
-  });
-
-  test("skips a gap too small to fit", () => {
-    const busy: BusyInterval[] = [
-      { start: 0, end: 10 * MIN },
-      { start: 20 * MIN, end: 60 * MIN }, // gap [10,20) only 10min
-    ];
-    expect(findFirstOpenSlot(windowStart, windowEnd, busy, dur)).toBeNull();
-  });
-
-  test("fully booked → null", () => {
-    const busy: BusyInterval[] = [{ start: -MIN, end: windowEnd + MIN }];
-    expect(findFirstOpenSlot(windowStart, windowEnd, busy, dur)).toBeNull();
-  });
-
-  test("ignores out-of-window busy intervals", () => {
-    const busy: BusyInterval[] = [{ start: -2 * HOUR, end: -HOUR }];
-    expect(findFirstOpenSlot(windowStart, windowEnd, busy, dur)).toBe(
-      windowStart,
-    );
-  });
-});
-
-describe("tomorrowInTimeZone", () => {
-  test("advances to the next local calendar day", () => {
-    expect(tomorrowInTimeZone(NOW, TZ)).toEqual({
-      year: 2024,
-      month: 1,
-      day: 16,
-    });
-  });
-
-  test("late-evening local time still maps to the correct next day", () => {
-    // 2024-01-16 02:00 UTC = 2024-01-15 21:00 EST → tomorrow is the 16th.
-    const lateLocal = Date.parse("2024-01-16T02:00:00Z");
-    expect(tomorrowInTimeZone(lateLocal, TZ)).toEqual({
-      year: 2024,
-      month: 1,
-      day: 16,
-    });
-  });
-});
-
-describe("chooseCheckinSlot", () => {
-  test("empty calendar → 12:00 (start of primary window)", () => {
-    const slot = chooseCheckinSlot(NOW, TZ, []);
-    expect(slot.window).toBe("primary");
-    expect(slot.startMs).toBe(estTomorrow(12));
-    expect(slot.endMs).toBe(estTomorrow(12, 15));
-  });
-
-  test("noon booked → next open slot inside the primary window", () => {
-    const busy: BusyInterval[] = [
-      { start: estTomorrow(12), end: estTomorrow(13) },
-    ];
-    const slot = chooseCheckinSlot(NOW, TZ, busy);
-    expect(slot.window).toBe("primary");
-    expect(slot.startMs).toBe(estTomorrow(13));
-  });
-
-  test("primary window full → widens to 8am–8pm and takes earliest slot", () => {
-    // Block all of 12pm–5pm; leave the morning open.
-    const busy: BusyInterval[] = [
-      { start: estTomorrow(12), end: estTomorrow(17) },
-    ];
-    const slot = chooseCheckinSlot(NOW, TZ, busy);
-    expect(slot.window).toBe("wide");
-    // Earliest free slot in 8am–8pm is 8:00am.
-    expect(slot.startMs).toBe(estTomorrow(8));
-  });
-
-  test("entire 8am–8pm full → fallback books at noon anyway", () => {
-    const busy: BusyInterval[] = [
-      { start: estTomorrow(8), end: estTomorrow(20) },
-    ];
-    const slot = chooseCheckinSlot(NOW, TZ, busy);
-    expect(slot.window).toBe("fallback");
-    expect(slot.startMs).toBe(estTomorrow(12));
-  });
-});
-
-describe("extractBusyFromEvents", () => {
-  const a = "2024-01-16T13:00:00Z";
-  const b = "2024-01-16T13:30:00Z";
-
-  test("timed event → busy interval", () => {
-    const events: GcalEvent[] = [
-      { start: { dateTime: a }, end: { dateTime: b } },
-    ];
-    expect(extractBusyFromEvents(events)).toEqual([
-      { start: Date.parse(a), end: Date.parse(b) },
-    ]);
-  });
-
-  test("skips cancelled, transparent, all-day, and declined events", () => {
-    const events: GcalEvent[] = [
-      { status: "cancelled", start: { dateTime: a }, end: { dateTime: b } },
-      {
-        transparency: "transparent",
-        start: { dateTime: a },
-        end: { dateTime: b },
-      },
-      { start: { date: "2024-01-16" }, end: { date: "2024-01-17" } },
-      {
-        start: { dateTime: a },
-        end: { dateTime: b },
-        attendees: [{ self: true, responseStatus: "declined" }],
-      },
-    ];
-    expect(extractBusyFromEvents(events)).toEqual([]);
-  });
-
-  test("keeps an accepted event even with another attendee declined", () => {
-    const events: GcalEvent[] = [
-      {
-        start: { dateTime: a },
-        end: { dateTime: b },
-        attendees: [
-          { self: true, responseStatus: "accepted" },
-          { responseStatus: "declined" },
-        ],
-      },
-    ];
-    expect(extractBusyFromEvents(events)).toHaveLength(1);
-  });
-});
-
-describe("checkinAvailabilityWindow", () => {
-  test("spans the full 8am–8pm fallback window tomorrow", () => {
-    const { timeMinMs, timeMaxMs } = checkinAvailabilityWindow(NOW, TZ);
-    expect(timeMinMs).toBe(estTomorrow(8));
-    expect(timeMaxMs).toBe(estTomorrow(20));
-  });
-});

package/src/onboarding/checkin-event.ts

@@ -1,321 +0,0 @@
-/**
- * Pure helpers for the onboarding "Day 2 Check-in" meeting: choosing the slot
- * and building the event's title and HTML description.
- *
- * The check-in is booked into the first open 15-minute slot in the user's local
- * afternoon tomorrow. The title uses fixed typography and the description uses a
- * sanitization-safe HTML body (Google Calendar strips most styling) with
- * default first-run substitutions and a deep-link CTA back into the app.
- *
- * Everything here is side-effect-free and timezone-pure so it can be unit
- * tested without a calendar connection; the orchestration that talks to Google
- * lives in `schedule-checkin.ts`.
- */
-
-/** Length of the check-in meeting. */
-export const CHECKIN_DURATION_MINUTES = 15;
-
-/**
- * Primary booking window in the user's local clock: the first open 15-minute
- * slot between 12pm and 5pm tomorrow.
- */
-export const PRIMARY_WINDOW = { startHour: 12, endHour: 17 } as const;
-
-/**
- * Fallback window when the primary 12pm–5pm window is fully booked: widen on
- * both ends to 8am–8pm and take the earliest open slot there.
- */
-export const WIDE_WINDOW = { startHour: 8, endHour: 20 } as const;
-
-/** The fixed, single-encoded first-week prompt carried by the CTA deep link. */
-const CTA_ENCODED_PROMPT =
-  "What%20would%20you%20recommend%20I%20tackle%20first%20this%20week%3F%20Propose%20it%20but%20wait%20for%20my%20go-ahead%20before%20doing%20anything";
-
-export interface CheckinNames {
-  /** The user's collected name. Blank/omitted → dropped from the title. */
-  userName?: string;
-  /** The assistant's display name. Blank/omitted → dropped from the title. */
-  assistantName?: string;
-}
-
-/**
- * Build the check-in event title. Locked typography, four cases:
- *   both names → `{me} <> {you}: Day 2 Check-in`
- *   me only    → `{me}: Day 2 Check-in`
- *   you only   → `{you}: Day 2 Check-in`
- *   neither    → `Day 2 Check-in`
- */
-export function buildCheckinTitle({
-  userName,
-  assistantName,
-}: CheckinNames): string {
-  const me = userName?.trim();
-  const you = assistantName?.trim();
-  if (me && you) return `${me} <> ${you}: Day 2 Check-in`;
-  if (me) return `${me}: Day 2 Check-in`;
-  if (you) return `${you}: Day 2 Check-in`;
-  return "Day 2 Check-in";
-}
-
-/**
- * Build the HTML event description with the default first-run substitutions.
- *
- * Google Calendar strips nearly all styling, so the body relies only on the
- * tags that survive (`<p>`, `<strong>`, `<a>`, emoji) and makes the CTA a bold
- * link rather than a styled button. The deep link opens a fresh conversation
- * (`uuid`) pre-seeded with the first-week prompt.
- */
-export function buildCheckinDescription(uuid: string): string {
-  const href = `https://www.vellum.ai/assistant/conversations/${uuid}?prompt=${CTA_ENCODED_PROMPT}&utm_source=onboarding&utm_medium=calendar_event`;
-  return [
-    "<p>👋 <strong>Hi, it was great to meet you properly.</strong></p>",
-    "<p>You just set me up, and I've already started learning <strong>what you're working on</strong>. This 15 minutes is the natural place to put that to work. I'll walk you through one thing I'd like to do for you this week.</p>",
-    `<p><a href="${href}"><strong>Let's go →</strong></a></p>`,
-    "<p>Click the link and we'll get started.</p>",
-  ].join("\n");
-}
-
-// ---------------------------------------------------------------------------
-// Timezone math
-//
-// We resolve wall-clock windows ("tomorrow 12:00 in America/New_York") to
-// absolute instants using Intl, so DST transitions and arbitrary offsets are
-// handled without a date library.
-// ---------------------------------------------------------------------------
-
-/**
- * Offset (local − UTC, in ms) that `timeZone` has at the given instant.
- * Derived by formatting the instant in the zone and diffing the wall clock.
- */
-function tzOffsetMs(utcMs: number, timeZone: string): number {
-  const dtf = new Intl.DateTimeFormat("en-US", {
-    timeZone,
-    hour12: false,
-    year: "numeric",
-    month: "2-digit",
-    day: "2-digit",
-    hour: "2-digit",
-    minute: "2-digit",
-    second: "2-digit",
-  });
-  const map: Record<string, string> = {};
-  for (const part of dtf.formatToParts(new Date(utcMs))) {
-    if (part.type !== "literal") map[part.type] = part.value;
-  }
-  // `hourCycle: h23` can emit "24" for midnight on some runtimes — normalize.
-  let hour = Number(map.hour);
-  if (hour === 24) hour = 0;
-  const asUtc = Date.UTC(
-    Number(map.year),
-    Number(map.month) - 1,
-    Number(map.day),
-    hour,
-    Number(map.minute),
-    Number(map.second),
-  );
-  return asUtc - utcMs;
-}
-
-/**
- * Convert a wall-clock time in `timeZone` to an absolute epoch-ms instant.
- * Refines once to settle DST boundaries where the naive offset guess differs
- * from the offset that actually applies at the resolved instant.
- */
-export function zonedWallTimeToUtcMs(
-  year: number,
-  month: number,
-  day: number,
-  hour: number,
-  minute: number,
-  timeZone: string,
-): number {
-  const guess = Date.UTC(year, month - 1, day, hour, minute);
-  const off1 = tzOffsetMs(guess, timeZone);
-  let utc = guess - off1;
-  const off2 = tzOffsetMs(utc, timeZone);
-  if (off2 !== off1) utc = guess - off2;
-  return utc;
-}
-
-/** Calendar date (1-based month) that is "tomorrow" in `timeZone` at `nowMs`. */
-export function tomorrowInTimeZone(
-  nowMs: number,
-  timeZone: string,
-): { year: number; month: number; day: number } {
-  const dtf = new Intl.DateTimeFormat("en-US", {
-    timeZone,
-    year: "numeric",
-    month: "2-digit",
-    day: "2-digit",
-  });
-  const map: Record<string, string> = {};
-  for (const part of dtf.formatToParts(new Date(nowMs))) {
-    if (part.type !== "literal") map[part.type] = part.value;
-  }
-  // Add a day via UTC arithmetic (handles month/year rollover), then read the
-  // wall-clock date back out — we only care about Y/M/D, not the instant.
-  const tomorrow = new Date(
-    Date.UTC(Number(map.year), Number(map.month) - 1, Number(map.day)) +
-      24 * 60 * 60 * 1000,
-  );
-  return {
-    year: tomorrow.getUTCFullYear(),
-    month: tomorrow.getUTCMonth() + 1,
-    day: tomorrow.getUTCDate(),
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Slot finding
-// ---------------------------------------------------------------------------
-
-/** A half-open busy interval `[start, end)` in epoch ms. */
-export interface BusyInterval {
-  start: number;
-  end: number;
-}
-
-/** Subset of a Google Calendar event needed to decide whether it blocks time. */
-export interface GcalEvent {
-  status?: string;
-  transparency?: string;
-  start?: { dateTime?: string; date?: string };
-  end?: { dateTime?: string; date?: string };
-  attendees?: Array<{ self?: boolean; responseStatus?: string }>;
-}
-
-/**
- * Derive busy intervals (epoch ms) from listed calendar events, approximating
- * freeBusy semantics under the calendar.events scope (which authorizes
- * events.list/insert but not freeBusy.query). Skips events that don't occupy
- * the user's time: cancelled, transparent ("free"), all-day (date-only), and
- * ones the user has declined.
- */
-export function extractBusyFromEvents(events: GcalEvent[]): BusyInterval[] {
-  const intervals: BusyInterval[] = [];
-  for (const event of events) {
-    if (event.status === "cancelled") continue;
-    if (event.transparency === "transparent") continue;
-    // All-day events (date-only) don't block a 15-minute afternoon slot.
-    if (!event.start?.dateTime || !event.end?.dateTime) continue;
-    const self = event.attendees?.find((a) => a.self);
-    if (self?.responseStatus === "declined") continue;
-
-    const start = Date.parse(event.start.dateTime);
-    const end = Date.parse(event.end.dateTime);
-    if (Number.isFinite(start) && Number.isFinite(end) && end > start) {
-      intervals.push({ start, end });
-    }
-  }
-  return intervals;
-}
-
-/**
- * Earliest start (epoch ms) of a free `durationMs` slot inside
- * `[windowStart, windowEnd)`, or `null` if the window is fully booked.
- *
- * Walks the busy intervals in order, advancing a cursor past each overlap; the
- * first gap wide enough to fit the duration wins. This returns the *first*
- * open slot, which is exactly the "first open time slot in the window"
- * behavior the onboarding flow wants.
- */
-export function findFirstOpenSlot(
-  windowStart: number,
-  windowEnd: number,
-  busy: BusyInterval[],
-  durationMs: number,
-): number | null {
-  const relevant = busy
-    .filter((b) => b.end > windowStart && b.start < windowEnd)
-    .sort((a, b) => a.start - b.start);
-
-  let cursor = windowStart;
-  for (const interval of relevant) {
-    if (interval.start - cursor >= durationMs) {
-      return cursor;
-    }
-    if (interval.end > cursor) {
-      cursor = interval.end;
-    }
-    if (cursor + durationMs > windowEnd) {
-      return null;
-    }
-  }
-  return cursor + durationMs <= windowEnd ? cursor : null;
-}
-
-export interface ChosenSlot {
-  /** Slot start, epoch ms. */
-  startMs: number;
-  /** Slot end, epoch ms. */
-  endMs: number;
-  /** Which window the slot came from — drives logging/telemetry only. */
-  window: "primary" | "wide" | "fallback";
-}
-
-/**
- * Pick the check-in slot for tomorrow in `timeZone` given the busy intervals.
- *
- * 1. First open 15-min slot in 12pm–5pm.
- * 2. If that window is full, widen to 8am–8pm and take the earliest open slot.
- * 3. If even that is full (pathological), fall back to 12:00 so a reminder
- *    still lands — better an overlapping check-in than none.
- */
-export function chooseCheckinSlot(
-  nowMs: number,
-  timeZone: string,
-  busy: BusyInterval[],
-): ChosenSlot {
-  const { year, month, day } = tomorrowInTimeZone(nowMs, timeZone);
-  const durationMs = CHECKIN_DURATION_MINUTES * 60 * 1000;
-
-  const at = (hour: number) =>
-    zonedWallTimeToUtcMs(year, month, day, hour, 0, timeZone);
-
-  const primaryStart = at(PRIMARY_WINDOW.startHour);
-  const primaryEnd = at(PRIMARY_WINDOW.endHour);
-  const wideStart = at(WIDE_WINDOW.startHour);
-  const wideEnd = at(WIDE_WINDOW.endHour);
-
-  const primary = findFirstOpenSlot(primaryStart, primaryEnd, busy, durationMs);
-  if (primary !== null) {
-    return { startMs: primary, endMs: primary + durationMs, window: "primary" };
-  }
-
-  const wide = findFirstOpenSlot(wideStart, wideEnd, busy, durationMs);
-  if (wide !== null) {
-    return { startMs: wide, endMs: wide + durationMs, window: "wide" };
-  }
-
-  return {
-    startMs: primaryStart,
-    endMs: primaryStart + durationMs,
-    window: "fallback",
-  };
-}
-
-/** Window covering both the primary and fallback ranges — the availability query span. */
-export function checkinAvailabilityWindow(
-  nowMs: number,
-  timeZone: string,
-): { timeMinMs: number; timeMaxMs: number } {
-  const { year, month, day } = tomorrowInTimeZone(nowMs, timeZone);
-  return {
-    timeMinMs: zonedWallTimeToUtcMs(
-      year,
-      month,
-      day,
-      WIDE_WINDOW.startHour,
-      0,
-      timeZone,
-    ),
-    timeMaxMs: zonedWallTimeToUtcMs(
-      year,
-      month,
-      day,
-      WIDE_WINDOW.endHour,
-      0,
-      timeZone,
-    ),
-  };
-}