@particle-academy/fancy-connector-core 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -6,6 +6,50 @@ All notable changes to `fancy-connector-core` are documented here, in
 **This package is pre-1.0, so breaking changes land in MINOR releases.** The
 version number is not a promise it can keep yet; the entries below are.
 
+## [0.10.0] - 2026-09-16
+
+Tynn #12 (MOIC's meeting bot): an RFC 5545 invite parser, written from
+scratch in both runtimes (the owner: no third-party code) — no provider
+generates it; it lives beside the other pure helpers. Additive;
+`CONNECTOR_API_VERSION` stays at 1.
+
+### Added
+
+- **`parseInvite` / `Ical::parse`** — raw invite text to a structured
+  `Invite`: METHOD (REQUEST/CANCEL), UID, SEQUENCE, SUMMARY/DESCRIPTION/
+  LOCATION (RFC 5545-unescaped, folded lines joined first), STATUS,
+  ORGANIZER and every ATTENDEE (name, email, role, partstat), and an RRULE
+  when the event recurs. `DTSTART`/`DTEND` always come back as UTC
+  instants: a `Z` suffix passes through, a `TZID` resolves through the
+  calendar's own `VTIMEZONE` (its DAYLIGHT/STANDARD sub-components, each
+  with a yearly BYMONTH+BYDAY transition rule — an unknown TZID is refused
+  BY NAME, never guessed), and a value with neither (RFC 5545's FLOATING
+  time) is treated as UTC — a decision named rather than left to look like
+  an oversight, because resolving one correctly needs the READER's
+  timezone, which nothing in the invite carries.
+- **`nextOccurrence` / `Ical::nextOccurrence`** — the next occurrence at or
+  after a given instant, for a recurring or a one-off invite alike; `null`
+  once the series (or the single occurrence) has nothing left to offer.
+  RRULE support is intentionally narrow: `FREQ` daily/weekly/monthly/yearly
+  with `INTERVAL`, `COUNT` and `UNTIL`, and `BYDAY` for WEEKLY only — no
+  `BYMONTHDAY`, `BYSETPOS`, `BYWEEKNO`, `BYYEARDAY`, `WKST`, `EXDATE` or
+  `RDATE`. A recurring invite using one of those still parses (its RRULE
+  fields are read, never dropped); `nextOccurrence` is what does not
+  attempt to walk it.
+- **`joinTargets` / `Ical::joinTargets`** — the ALLOW-LISTED places a bot
+  can actually join, in the order they appear in the text: Google Meet,
+  Zoom (with the meeting id and passcode read out of the URL itself),
+  Microsoft Teams, and a dial-in phone number with its own passcode line.
+  Anything else — Webex, a generic link, an unrecognised dial-in shape —
+  is not returned: a shape this package does not know is a shape a bot
+  should not guess at.
+- **`fixtures/ical/`** — six authored cases (the floor, a VTIMEZONE
+  resolution, a weekly recurrence with four `nextOccurrence` boundary
+  queries, a CANCEL sharing its REQUEST's uid at a higher sequence, an
+  allow-listed join-target extraction from a folded/escaped DESCRIPTION,
+  and the negative case: a non-allow-listed link ignored). Both runtimes
+  read it; `README.md` names the decision each case pins.
+
 ## [0.9.0] - 2026-09-15
 
 The verification half of Tynn #11 (Resend inbound email, signed by Svix),

package/dist/index.cjs

@@ -75,12 +75,15 @@ __export(src_exports, {
   isSharedTokenScheme: () => isSharedTokenScheme,
   isSharedTokenSpec: () => isSharedTokenSpec,
   isUnconditionallyRetryable: () => isUnconditionallyRetryable,
+  joinTargets: () => joinTargets,
   leaseAction: () => leaseAction,
   leaseFromResponse: () => leaseFromResponse,
   leaseRenewAt: () => leaseRenewAt,
   leaseState: () => leaseState,
   linkRanges: () => linkRanges,
   measure: () => measure,
+  nextOccurrence: () => nextOccurrence,
+  parseInvite: () => parseInvite,
   parseMime: () => parseMime,
   payloadHash: () => payloadHash,
   postChain: () => postChain,
@@ -980,6 +983,325 @@ function unchecked(contract) {
   };
 }
 
+// src/ical.ts
+function unfold(text) {
+  return text.replace(/\r\n|\r|\n/g, "\n").replace(/\n[ \t]/g, "");
+}
+function unescapeText(value) {
+  return value.replace(/\\[nN]/g, "\n").replace(/\\,/g, ",").replace(/\\;/g, ";").replace(/\\\\/g, "\\");
+}
+function parseLine(line) {
+  const colon = findUnquoted(line, ":");
+  const head = colon === -1 ? line : line.slice(0, colon);
+  const value = colon === -1 ? "" : line.slice(colon + 1);
+  const [name = "", ...paramParts] = head.split(";");
+  const params = {};
+  for (const part of paramParts) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    const key = part.slice(0, eq).toUpperCase();
+    let raw = part.slice(eq + 1);
+    if (raw.startsWith('"') && raw.endsWith('"')) raw = raw.slice(1, -1);
+    params[key] = raw;
+  }
+  return { name: name.toUpperCase(), params, value };
+}
+function findUnquoted(line, char) {
+  let quoted = false;
+  for (let i = 0; i < line.length; i++) {
+    if (line[i] === '"') quoted = !quoted;
+    else if (line[i] === char && !quoted) return i;
+  }
+  return -1;
+}
+function blockLines(lines, name) {
+  const blocks = [];
+  let depth = 0;
+  let current = null;
+  for (const raw of lines) {
+    const upper = raw.toUpperCase();
+    if (upper === `BEGIN:${name}`) {
+      if (depth === 0) current = [];
+      depth++;
+      continue;
+    }
+    if (upper === `END:${name}`) {
+      depth--;
+      if (depth === 0 && current !== null) {
+        blocks.push(current);
+        current = null;
+      }
+      continue;
+    }
+    if (current !== null) current.push(raw);
+  }
+  return blocks;
+}
+var WEEKDAY_CODES = ["SU", "MO", "TU", "WE", "TH", "FR", "SA"];
+function parseByDayOrdinal(token) {
+  const match = /^(-?\d+)([A-Z]{2})$/.exec(token);
+  if (!match) throw new Error(`ical: VTIMEZONE rule has an unreadable BYDAY "${token}"`);
+  const [, ordinalText, weekdayText] = match;
+  const weekday = WEEKDAY_CODES.indexOf(weekdayText ?? "");
+  if (weekday === -1) throw new Error(`ical: VTIMEZONE rule names an unknown weekday "${weekdayText}"`);
+  return { ordinal: Number(ordinalText), weekday };
+}
+function parseTzTransition(lines) {
+  const props = lines.map(parseLine);
+  const get = (name) => props.find((p) => p.name === name)?.value;
+  const offsetFrom = get("TZOFFSETFROM");
+  const offsetTo = get("TZOFFSETTO");
+  const rrule = get("RRULE");
+  if (!offsetFrom || !offsetTo || !rrule) {
+    throw new Error("ical: a VTIMEZONE sub-component needs TZOFFSETFROM, TZOFFSETTO and an RRULE");
+  }
+  const parts = Object.fromEntries(rrule.split(";").map((p) => p.split("=")));
+  const month = Number(parts.BYMONTH);
+  const { ordinal, weekday } = parseByDayOrdinal(parts.BYDAY ?? "");
+  if (!month || Number.isNaN(ordinal)) {
+    throw new Error(`ical: this package only reads a yearly BYMONTH+BYDAY transition rule, got "${rrule}"`);
+  }
+  return { offsetFrom, offsetTo, month, ordinal, weekday };
+}
+function offsetMinutes(offset) {
+  const match = /^([+-])(\d{2}):?(\d{2})/.exec(offset);
+  if (!match) throw new Error(`ical: unreadable UTC offset "${offset}"`);
+  const sign = match[1] === "-" ? -1 : 1;
+  return sign * (Number(match[2]) * 60 + Number(match[3]));
+}
+function nthWeekdayOfMonth(year, month1, weekday, ordinal) {
+  if (ordinal > 0) {
+    const first = Date.UTC(year, month1 - 1, 1);
+    const firstWeekday = new Date(first).getUTCDay();
+    const offset2 = (weekday - firstWeekday + 7) % 7;
+    return 1 + offset2 + (ordinal - 1) * 7;
+  }
+  const lastDay = new Date(Date.UTC(year, month1, 0)).getUTCDate();
+  const last = Date.UTC(year, month1 - 1, lastDay);
+  const lastWeekday = new Date(last).getUTCDay();
+  const offset = (lastWeekday - weekday + 7) % 7;
+  return lastDay - offset - (-ordinal - 1) * 7;
+}
+function parseTimezones(lines) {
+  const zones = /* @__PURE__ */ new Map();
+  for (const block of blockLines(lines, "VTIMEZONE")) {
+    const tzid = block.map(parseLine).find((p) => p.name === "TZID")?.value;
+    if (!tzid) continue;
+    const standardBlocks = blockLines(block, "STANDARD");
+    const daylightBlocks = blockLines(block, "DAYLIGHT");
+    const standardBlock = standardBlocks[0];
+    if (!standardBlock) {
+      throw new Error(`ical: VTIMEZONE "${tzid}" has no STANDARD component`);
+    }
+    zones.set(tzid, {
+      standard: parseTzTransition(standardBlock),
+      daylight: daylightBlocks[0] ? parseTzTransition(daylightBlocks[0]) : null
+    });
+  }
+  return zones;
+}
+function resolveTz(zone, y, mo, d, h, mi, s) {
+  const naiveUtcMs = Date.UTC(y, mo - 1, d, h, mi, s);
+  if (!zone.daylight) {
+    return new Date(naiveUtcMs - offsetMinutes(zone.standard.offsetTo) * 6e4).toISOString();
+  }
+  const springDay = nthWeekdayOfMonth(y, zone.daylight.month, zone.daylight.weekday, zone.daylight.ordinal);
+  const fallDay = nthWeekdayOfMonth(y, zone.standard.month, zone.standard.weekday, zone.standard.ordinal);
+  const spring = Date.UTC(y, zone.daylight.month - 1, springDay);
+  const fall = Date.UTC(y, zone.standard.month - 1, fallDay);
+  const inDaylight = naiveUtcMs >= spring && naiveUtcMs < fall;
+  const offset = inDaylight ? zone.daylight.offsetTo : zone.standard.offsetTo;
+  return new Date(naiveUtcMs - offsetMinutes(offset) * 6e4).toISOString();
+}
+function parseDateTimeParts(value) {
+  const match = /^(\d{4})(\d{2})(\d{2})T(\d{2})(\d{2})(\d{2})(Z)?$/.exec(value);
+  if (!match) throw new Error(`ical: unreadable date-time "${value}"`);
+  return {
+    y: Number(match[1]),
+    mo: Number(match[2]),
+    d: Number(match[3]),
+    h: Number(match[4]),
+    mi: Number(match[5]),
+    s: Number(match[6]),
+    utc: Boolean(match[7])
+  };
+}
+function resolveInstant(prop, zones) {
+  const parts = parseDateTimeParts(prop.value);
+  if (parts.utc) return new Date(Date.UTC(parts.y, parts.mo - 1, parts.d, parts.h, parts.mi, parts.s)).toISOString();
+  const tzid = prop.params.TZID;
+  if (!tzid) {
+    return new Date(Date.UTC(parts.y, parts.mo - 1, parts.d, parts.h, parts.mi, parts.s)).toISOString();
+  }
+  const zone = zones.get(tzid);
+  if (!zone) {
+    throw new Error(`ical: DTSTART/DTEND names TZID "${tzid}", which this calendar's VTIMEZONE does not define`);
+  }
+  return resolveTz(zone, parts.y, parts.mo, parts.d, parts.h, parts.mi, parts.s);
+}
+function emailOf(value) {
+  return value.replace(/^mailto:/i, "");
+}
+function parseAttendee(prop) {
+  return {
+    name: prop.params.CN ?? null,
+    email: emailOf(prop.value),
+    role: prop.params.ROLE ?? null,
+    partstat: prop.params.PARTSTAT ?? null
+  };
+}
+var FREQS = ["DAILY", "WEEKLY", "MONTHLY", "YEARLY"];
+function parseRRule(value) {
+  const parts = Object.fromEntries(
+    value.split(";").map((p) => {
+      const eq = p.indexOf("=");
+      return [p.slice(0, eq).toUpperCase(), p.slice(eq + 1)];
+    })
+  );
+  const freq = parts.FREQ;
+  if (!FREQS.includes(freq)) {
+    throw new Error(`ical: RRULE FREQ must be one of ${FREQS.join(", ")}, got "${parts.FREQ}"`);
+  }
+  return {
+    freq,
+    interval: parts.INTERVAL ? Number(parts.INTERVAL) : 1,
+    count: parts.COUNT ? Number(parts.COUNT) : null,
+    until: parts.UNTIL ? resolveInstant({ name: "UNTIL", params: {}, value: parts.UNTIL }, /* @__PURE__ */ new Map()) : null,
+    byDay: parts.BYDAY ? parts.BYDAY.split(",") : null
+  };
+}
+function parseInvite(raw) {
+  const lines = unfold(raw).split("\n").filter((l) => l.length > 0);
+  const zones = parseTimezones(lines);
+  const eventBlocks = blockLines(lines, "VEVENT");
+  const firstEvent = eventBlocks[0];
+  if (!firstEvent) throw new Error("ical: no VEVENT in this calendar");
+  const props = firstEvent.map(parseLine);
+  const methodValue = (lines.find((l) => l.toUpperCase().startsWith("METHOD:")) ?? "").split(":")[1];
+  const get = (name) => props.find((p) => p.name === name);
+  const getAll = (name) => props.filter((p) => p.name === name);
+  const text = (name) => {
+    const p = get(name);
+    return p ? unescapeText(p.value) : null;
+  };
+  const method = (methodValue ?? "REQUEST").trim().toUpperCase();
+  if (method !== "REQUEST" && method !== "CANCEL") {
+    throw new Error(`ical: METHOD must be REQUEST or CANCEL, got "${methodValue}"`);
+  }
+  const uidProp = get("UID");
+  if (!uidProp) throw new Error("ical: VEVENT has no UID");
+  const dtstartProp = get("DTSTART");
+  if (!dtstartProp) throw new Error("ical: VEVENT has no DTSTART");
+  const dtendProp = get("DTEND");
+  const organizerProp = get("ORGANIZER");
+  const rruleProp = get("RRULE");
+  return {
+    method,
+    uid: uidProp.value,
+    sequence: get("SEQUENCE") ? Number(get("SEQUENCE").value) : 0,
+    summary: text("SUMMARY"),
+    description: text("DESCRIPTION"),
+    location: text("LOCATION"),
+    status: get("STATUS")?.value ?? null,
+    dtstart: resolveInstant(dtstartProp, zones),
+    dtend: dtendProp ? resolveInstant(dtendProp, zones) : null,
+    organizer: organizerProp ? { name: organizerProp.params.CN ?? null, email: emailOf(organizerProp.value) } : null,
+    attendees: getAll("ATTENDEE").map(parseAttendee),
+    rrule: rruleProp ? parseRRule(rruleProp.value) : null
+  };
+}
+var DAY_MS = 864e5;
+function addCalendarUnit(ms, freq, interval) {
+  const d = new Date(ms);
+  if (freq === "DAILY") return ms + interval * DAY_MS;
+  if (freq === "WEEKLY") return ms + interval * 7 * DAY_MS;
+  const months = freq === "YEARLY" ? interval * 12 : interval;
+  const day = d.getUTCDate();
+  const next = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + months, 1, d.getUTCHours(), d.getUTCMinutes(), d.getUTCSeconds()));
+  const daysInNext = new Date(Date.UTC(next.getUTCFullYear(), next.getUTCMonth() + 1, 0)).getUTCDate();
+  next.setUTCDate(Math.min(day, daysInNext));
+  return next.getTime();
+}
+function* occurrences(rrule, dtstartMs) {
+  const untilMs = rrule.until ? Date.parse(rrule.until) : null;
+  let n = 0;
+  const emit = (ms) => {
+    if (untilMs !== null && ms > untilMs) return false;
+    n++;
+    return true;
+  };
+  if (rrule.freq === "WEEKLY" && rrule.byDay?.length) {
+    const wanted = [...new Set(rrule.byDay.map((d) => WEEKDAY_CODES.indexOf(d)))].sort((a, b) => a - b);
+    const dtstart = new Date(dtstartMs);
+    const timeOfDay = dtstartMs - Date.UTC(dtstart.getUTCFullYear(), dtstart.getUTCMonth(), dtstart.getUTCDate());
+    const startOfWeek = dtstartMs - timeOfDay - dtstart.getUTCDay() * DAY_MS;
+    let weekIndex = 0;
+    while (true) {
+      if (weekIndex % rrule.interval === 0) {
+        for (const weekday of wanted) {
+          const candidate = startOfWeek + weekIndex * 7 * DAY_MS + weekday * DAY_MS + timeOfDay;
+          if (candidate < dtstartMs) continue;
+          if (!emit(candidate)) return;
+          yield candidate;
+          if (rrule.count && n >= rrule.count) return;
+        }
+      }
+      weekIndex++;
+    }
+  }
+  let current = dtstartMs;
+  while (true) {
+    if (!emit(current)) return;
+    yield current;
+    if (rrule.count && n >= rrule.count) return;
+    current = addCalendarUnit(current, rrule.freq, rrule.interval);
+  }
+}
+function nextOccurrence(invite, afterIso) {
+  const afterMs = Date.parse(afterIso);
+  const dtstartMs = Date.parse(invite.dtstart);
+  if (!invite.rrule) {
+    return dtstartMs >= afterMs ? invite.dtstart : null;
+  }
+  for (const ms of occurrences(invite.rrule, dtstartMs)) {
+    if (ms >= afterMs) return new Date(ms).toISOString();
+  }
+  return null;
+}
+var ZOOM_LINK = /https:\/\/[\w.-]*zoom\.us\/j\/(\d+)(\?[^\s)]*)?/g;
+var MEET_LINK = /https:\/\/meet\.google\.com\/[a-z0-9-]+/gi;
+var TEAMS_LINK = /https:\/\/teams\.(?:microsoft|live)\.com\/l\/meetup-join\/[^\s)]+/gi;
+var DIAL_LINE = /^Dial(?:-in)?[:\s]+([+0-9][0-9\s().-]{6,}\d)/im;
+var PASSCODE_LINE = /Passcode[:\s]+([A-Za-z0-9]+)/i;
+function joinTargets(invite) {
+  const text = invite.description ?? "";
+  const targets = [];
+  for (const match of text.matchAll(ZOOM_LINK)) {
+    const query = match[2] ?? "";
+    const passcode = /[?&]pwd=([^&\s]+)/.exec(query)?.[1] ?? null;
+    targets.push({
+      index: match.index ?? 0,
+      target: { kind: "zoom", url: match[0], meetingId: match[1] ?? null, passcode, phone: null }
+    });
+  }
+  for (const match of text.matchAll(MEET_LINK)) {
+    targets.push({ index: match.index ?? 0, target: { kind: "google-meet", url: match[0], meetingId: null, passcode: null, phone: null } });
+  }
+  for (const match of text.matchAll(TEAMS_LINK)) {
+    targets.push({ index: match.index ?? 0, target: { kind: "teams", url: match[0], meetingId: null, passcode: null, phone: null } });
+  }
+  const dial = DIAL_LINE.exec(text);
+  const dialedPhone = dial?.[1];
+  if (dial && dialedPhone !== void 0) {
+    const passcode = PASSCODE_LINE.exec(text)?.[1] ?? null;
+    targets.push({
+      index: dial.index,
+      target: { kind: "dial-in", url: null, meetingId: null, passcode, phone: dialedPhone.trim() }
+    });
+  }
+  return targets.sort((a, b) => a.index - b.index).map((t) => t.target);
+}
+
 // src/idempotency.ts
 var DEFAULT_IDEMPOTENCY_WINDOW_SECONDS = 24 * 60 * 60;
 var MAX_IDEMPOTENCY_KEY_LENGTH = 255;
@@ -1920,12 +2242,15 @@ function hasDelivery(value) {
   isSharedTokenScheme,
   isSharedTokenSpec,
   isUnconditionallyRetryable,
+  joinTargets,
   leaseAction,
   leaseFromResponse,
   leaseRenewAt,
   leaseState,
   linkRanges,
   measure,
+  nextOccurrence,
+  parseInvite,
   parseMime,
   payloadHash,
   postChain,