calendaryjs-plugin-ics 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 calendaryjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# calendaryjs-plugin-ics
+
+ICS (RFC 5545) export for [calendaryjs](https://github.com/calendaryjs/calendaryjs). Turn generated calendar occurrences into a standard `.ics` `VCALENDAR` that Apple Calendar, Google Calendar, Outlook and anything else can subscribe to.
+
+It is an **edge integration**: calendaryjs owns the calendar core; this package only serializes its plain output. It adds **zero runtime dependency** to the core and works on any plain object shaped like a `CalendarEvent`.
+
+## Features
+
+- **📤 One VEVENT per occurrence** — events come in already expanded, so no `RRULE` is emitted. Lunar / hijri / formula dates and per-occurrence `exceptions` & `overrideDates` (already applied by the core) all export correctly.
+- **⏰ Reminders → `VALARM`** — each lead-time reminder becomes a relative-trigger alarm (`DISPLAY` or `EMAIL`).
+- **🔢 Priority → `PRIORITY`** — calendaryjs `priority` (CSS `z-index`: higher = on top) is inverted into ICS `PRIORITY` (1 = highest), with a pluggable mapper.
+- **🎨 Display fields** — `DESCRIPTION`, `LOCATION`, `URL`, `CATEGORIES`, `STATUS`, plus RFC 7986 `COLOR` / `IMAGE`.
+- **✅ Spec-correct output** — CRLF line endings, octet-aware line folding (75-octet, no multi-byte splits), RFC 5545 text escaping.
+- **🧪 Deterministic** — pass a fixed `dtstamp` for byte-stable, diff-friendly files.
+
+## Installation
+
+```bash
+pnpm add calendaryjs calendaryjs-plugin-ics
+```
+
+## Requirements
+
+- `calendaryjs` >= 0.1.0
+
+## Quick Start
+
+```typescript
+import { calendary } from "calendaryjs";
+import { toICS } from "calendaryjs-plugin-ics";
+
+const cal = calendary();
+cal.addGroup({
+  id: "holidays",
+  name: "Holidays",
+  events: [
+    { type: "const", id: "newyear", month: 1, day: 1, title: "New Year" },
+    { type: "const", id: "christmas", month: 12, day: 25, title: "Christmas" },
+  ],
+});
+
+const events = cal.getEventsInRange("2025-01-01", "2025-12-31");
+const ics = toICS(events, { calendarName: "Holidays" });
+
+// → write `ics` to a .ics file, or serve it from an endpoint
+```
+
+## API
+
+### `toICS(events, options?) → string`
+
+Serialize an array of occurrences into a full `VCALENDAR` document.
+
+```typescript
+interface ICSOptions {
+  prodId?: string; // PRODID. Default "-//calendaryjs//calendaryjs-plugin-ics//EN"
+  calendarName?: string; // X-WR-CALNAME — the calendar's display name
+  method?: string; // METHOD, e.g. "PUBLISH"
+  dtstamp?: Date; // DTSTAMP for every event. Default: now (pass a fixed Date for stable output)
+  priorityMap?: (priority: number) => number; // override priority → ICS PRIORITY (return 0 to omit)
+}
+```
+
+### `eventToVEvent(event, options?) → string`
+
+Serialize a single occurrence to one folded `VEVENT` block (no `VCALENDAR` wrapper).
+
+Also exported: `veventLines` (unfolded lines), `defaultPriorityMap`, and the low-level `escapeText` / `foldLine` helpers.
+
+## Field mapping
+
+| calendaryjs                        | ICS                                       |
+| ---------------------------------- | ----------------------------------------- |
+| `date` + `startTime`/`endTime`     | `DTSTART` / `DTEND` (floating local time) |
+| `date` (all-day / no time)         | `DTSTART;VALUE=DATE` + exclusive `DTEND`  |
+| `duration` (minutes)               | `DURATION` (when `endTime` is absent)     |
+| `title`                            | `SUMMARY`                                 |
+| `description` / `location` / `url` | `DESCRIPTION` / `LOCATION` / `URL`        |
+| `categories` / `status`            | `CATEGORIES` / `STATUS`                   |
+| `priority` (z-index)               | `PRIORITY` (inverted, 1 = highest)        |
+| `color` / `icon`                   | `COLOR` / `IMAGE` (RFC 7986)              |
+| `reminders[]` (minutes before)     | `VALARM` with `TRIGGER:-PTnM`             |
+| `source` / `groupId` / id + `date` | a stable, unique `UID`                    |
+
+### Notes
+
+- **Timezones.** Timed events export as **floating local time** (no `Z`, no `TZID`) — the core stays timezone-neutral, so occurrences render in the viewer's local zone.
+- **Reminder & duration units** are **minutes**.
+- **`exceptions` / `overrideDates`** are resolved by the core before export (skipped occurrences are already gone, overrides already applied), so no `EXDATE` / `RECURRENCE-ID` is needed for the per-occurrence form.
+
+## Roadmap
+
+- `RRULE` compaction for Gregorian-expressible recurrences (with `EXDATE` / `RECURRENCE-ID` for exceptions).
+- ICS **import** (`.ics` → event configs).
+
+## Related Packages
+
+- [calendaryjs](https://github.com/calendaryjs/calendaryjs/tree/main/packages/calendaryjs) — core engine
+- [calendaryjs-plugin-lunar](https://github.com/calendaryjs/calendaryjs/tree/main/packages/lunar) — lunar calendar
+- [calendaryjs-plugin-liturgical](https://github.com/calendaryjs/calendaryjs/tree/main/packages/liturgical) — liturgical calendar
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,145 @@
+'use strict';
+
+// src/escape.ts
+var encoder = new TextEncoder();
+function escapeText(value) {
+  return value.replace(/\\/g, "\\\\").replace(/;/g, "\\;").replace(/,/g, "\\,").replace(/\r\n|\r|\n/g, "\\n");
+}
+function foldLine(line) {
+  if (encoder.encode(line).length <= 75) return line;
+  let result = "";
+  let segment = "";
+  let segmentBytes = 0;
+  for (const char of line) {
+    const charBytes = encoder.encode(char).length;
+    const cap = result === "" ? 75 : 74;
+    if (segmentBytes + charBytes > cap) {
+      result += result === "" ? segment : `\r
+ ${segment}`;
+      segment = char;
+      segmentBytes = charBytes;
+    } else {
+      segment += char;
+      segmentBytes += charBytes;
+    }
+  }
+  result += result === "" ? segment : `\r
+ ${segment}`;
+  return result;
+}
+
+// src/format.ts
+var pad2 = (value) => String(value).padStart(2, "0");
+function formatDate(date) {
+  return date.replace(/-/g, "");
+}
+function formatTime(time) {
+  const [h = "0", m = "0", s = "0"] = time.split(":");
+  return `${pad2(h)}${pad2(m)}${pad2(s)}`;
+}
+function formatDateTime(date, time) {
+  return `${formatDate(date)}T${formatTime(time)}`;
+}
+function formatStamp(date) {
+  return `${date.getUTCFullYear()}${pad2(date.getUTCMonth() + 1)}${pad2(date.getUTCDate())}T${pad2(date.getUTCHours())}${pad2(date.getUTCMinutes())}${pad2(date.getUTCSeconds())}Z`;
+}
+function nextDateValue(date) {
+  const [y, m, d] = date.split("-").map(Number);
+  const next = new Date(Date.UTC(y, m - 1, d + 1));
+  return `${next.getUTCFullYear()}${pad2(next.getUTCMonth() + 1)}${pad2(next.getUTCDate())}`;
+}
+function formatDuration(minutes) {
+  if (minutes <= 0) return "PT0M";
+  const hours = Math.floor(minutes / 60);
+  const mins = minutes % 60;
+  return `PT${hours ? `${hours}H` : ""}${mins ? `${mins}M` : ""}`;
+}
+
+// src/vevent.ts
+function defaultPriorityMap(priority) {
+  if (priority <= 0) return 0;
+  return Math.max(1, 9 - Math.min(priority, 8));
+}
+function valarmLines(reminder, fallback) {
+  const text = escapeText(reminder.message ?? fallback);
+  const lines = [
+    "BEGIN:VALARM",
+    `ACTION:${reminder.type === "email" ? "EMAIL" : "DISPLAY"}`,
+    `TRIGGER:-PT${Math.abs(reminder.trigger)}M`,
+    `DESCRIPTION:${text}`
+  ];
+  if (reminder.type === "email") lines.push(`SUMMARY:${text}`);
+  lines.push("END:VALARM");
+  return lines;
+}
+function veventLines(event, options = {}) {
+  const lines = ["BEGIN:VEVENT"];
+  const localPart = [event.groupId, event.sourceEventId ?? slug(event.title), event.date].filter(Boolean).join("-");
+  lines.push(`UID:${localPart}@${event.source ?? "calendaryjs"}`);
+  lines.push(`DTSTAMP:${formatStamp(options.dtstamp ?? /* @__PURE__ */ new Date())}`);
+  const allDay = event.allDay === true || !event.startTime;
+  if (allDay) {
+    lines.push(`DTSTART;VALUE=DATE:${formatDate(event.date)}`);
+    lines.push(`DTEND;VALUE=DATE:${nextDateValue(event.date)}`);
+  } else {
+    lines.push(`DTSTART:${formatDateTime(event.date, event.startTime)}`);
+    if (event.endTime) {
+      lines.push(`DTEND:${formatDateTime(event.date, event.endTime)}`);
+    } else if (event.duration) {
+      lines.push(`DURATION:${formatDuration(event.duration)}`);
+    }
+  }
+  lines.push(`SUMMARY:${escapeText(event.title)}`);
+  if (event.description) lines.push(`DESCRIPTION:${escapeText(event.description)}`);
+  if (event.location) lines.push(`LOCATION:${escapeText(event.location)}`);
+  if (event.url) lines.push(`URL:${event.url}`);
+  if (event.categories?.length) {
+    lines.push(`CATEGORIES:${event.categories.map(escapeText).join(",")}`);
+  }
+  if (event.status) lines.push(`STATUS:${event.status.toUpperCase()}`);
+  if (event.priority !== void 0) {
+    const map = options.priorityMap ?? defaultPriorityMap;
+    const icsPriority = map(event.priority);
+    if (icsPriority > 0) lines.push(`PRIORITY:${icsPriority}`);
+  }
+  if (event.color) lines.push(`COLOR:${event.color}`);
+  if (event.icon) lines.push(`IMAGE;VALUE=URI:${event.icon}`);
+  for (const reminder of event.reminders ?? []) {
+    lines.push(...valarmLines(reminder, event.title));
+  }
+  lines.push("END:VEVENT");
+  return lines;
+}
+function eventToVEvent(event, options = {}) {
+  return veventLines(event, options).map(foldLine).join("\r\n");
+}
+function slug(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "event";
+}
+
+// src/to-ics.ts
+var DEFAULT_PRODID = "-//calendaryjs//calendaryjs-plugin-ics//EN";
+function toICS(events, options = {}) {
+  const stamp = options.dtstamp ?? /* @__PURE__ */ new Date();
+  const lines = [
+    "BEGIN:VCALENDAR",
+    "VERSION:2.0",
+    `PRODID:${options.prodId ?? DEFAULT_PRODID}`,
+    "CALSCALE:GREGORIAN"
+  ];
+  if (options.method) lines.push(`METHOD:${options.method}`);
+  if (options.calendarName) lines.push(`X-WR-CALNAME:${escapeText(options.calendarName)}`);
+  const eventOptions = { ...options, dtstamp: stamp };
+  for (const event of events) {
+    lines.push(...veventLines(event, eventOptions));
+  }
+  lines.push("END:VCALENDAR");
+  return lines.map(foldLine).join("\r\n") + "\r\n";
+}
+
+exports.defaultPriorityMap = defaultPriorityMap;
+exports.escapeText = escapeText;
+exports.eventToVEvent = eventToVEvent;
+exports.foldLine = foldLine;
+exports.toICS = toICS;
+exports.veventLines = veventLines;

package/dist/index.d.cts

@@ -0,0 +1,140 @@
+/**
+ * Plain, structural shape the ICS exporter consumes. A calendaryjs
+ * `CalendarEvent` satisfies it (see the structural assertion in
+ * `to-ics.test.ts`), but so does any plain object — keeping this package an
+ * edge integration that never forces a calendaryjs runtime dependency.
+ *
+ * One `ICSEvent` = one already-expanded occurrence (a single calendar day).
+ * The core has already applied recurrence, `exceptions` and `overrideDates`,
+ * so the exporter emits one `VEVENT` per occurrence and needs no `RRULE`.
+ */
+interface ICSEvent {
+    /** Occurrence date, `YYYY-MM-DD`. Required → `DTSTART`. */
+    date: string;
+    /** Required → `SUMMARY`. */
+    title: string;
+    /** All-day occurrence (no clock time) → `DTSTART;VALUE=DATE`. */
+    allDay?: boolean;
+    /** Start clock time, `HH:mm` or `HH:mm:ss` (floating/local). */
+    startTime?: string;
+    /** End clock time, `HH:mm` or `HH:mm:ss`. */
+    endTime?: string;
+    /** Duration in **minutes** → `DURATION` (used when `endTime` is absent). */
+    duration?: number;
+    /** → `DESCRIPTION`. */
+    description?: string;
+    /** → `LOCATION`. */
+    location?: string;
+    /** → `URL`. */
+    url?: string;
+    /** Origin feed/plugin — used as the `UID` domain so re-imports dedupe. */
+    source?: string;
+    /** → `CATEGORIES`. */
+    categories?: string[];
+    /**
+     * calendaryjs display precedence (CSS `z-index`: higher = on top, default 0).
+     * Inverted into ICS `PRIORITY` (1 = highest, 9 = lowest, 0 = undefined) by
+     * {@link ICSOptions.priorityMap}.
+     */
+    priority?: number;
+    /** → `STATUS` (`CONFIRMED` / `TENTATIVE` / `CANCELLED`). */
+    status?: "confirmed" | "tentative" | "cancelled";
+    /** CSS3 colour name → `COLOR` (RFC 7986). */
+    color?: string;
+    /** Image URI → `IMAGE` (RFC 7986). */
+    icon?: string;
+    /** Lead-time reminders → one `VALARM` each. */
+    reminders?: ICSReminder[];
+    /** Originating config id — part of a stable `UID`. */
+    sourceEventId?: string;
+    /** Group id — part of a stable `UID`. */
+    groupId?: string;
+}
+/** A single reminder → one `VALARM` with a relative `TRIGGER`. */
+interface ICSReminder {
+    /** `notification` → `ACTION:DISPLAY`; `email` → `ACTION:EMAIL`. */
+    type?: "notification" | "email";
+    /** Lead time in **minutes before** the occurrence → `TRIGGER:-PTnM`. */
+    trigger: number;
+    /** Reminder text → `DESCRIPTION` (falls back to the event title). */
+    message?: string;
+}
+/** Options for {@link toICS} and {@link eventToVEvent}. */
+interface ICSOptions {
+    /** `PRODID`. Default `-//calendaryjs//calendaryjs-plugin-ics//EN`. */
+    prodId?: string;
+    /** `X-WR-CALNAME` — the calendar's display name. */
+    calendarName?: string;
+    /** `METHOD` (e.g. `PUBLISH`). Omitted by default. */
+    method?: string;
+    /**
+     * `DTSTAMP` for every event. Defaults to the current time; pass a fixed
+     * `Date` for deterministic, diff-friendly output.
+     */
+    dtstamp?: Date;
+    /**
+     * Map a calendaryjs `priority` (z-index) to an ICS `PRIORITY` (1 = highest,
+     * 9 = lowest). Return `0` to omit. Default: importance inverts to rank, so a
+     * higher calendaryjs priority becomes a lower (more urgent) ICS number.
+     */
+    priorityMap?: (priority: number) => number;
+}
+
+/**
+ * Serialize an array of already-expanded occurrences into a single RFC 5545
+ * `VCALENDAR` document (CRLF line endings, octet-folded). One `VEVENT` is
+ * emitted per occurrence — no `RRULE` — so non-Gregorian recurrences (lunar,
+ * hijri) and per-occurrence `exceptions`/`overrideDates` (already applied by
+ * the core) export correctly.
+ *
+ * @example
+ * ```typescript
+ * import { calendary } from "calendaryjs";
+ * import { toICS } from "calendaryjs-plugin-ics";
+ *
+ * const cal = calendary();
+ * // ... add events ...
+ * const events = cal.getEventsInRange("2025-01-01", "2025-12-31");
+ * const ics = toICS(events, { calendarName: "Family" });
+ * ```
+ */
+declare function toICS(events: ICSEvent[], options?: ICSOptions): string;
+
+/**
+ * Default mapping from a calendaryjs `priority` (z-index: higher = more
+ * important, unbounded, default 0) to an ICS `PRIORITY` (1 = highest, 9 =
+ * lowest, 0 = undefined). Importance inverts to rank and is clamped to 1–9, so
+ * `0` stays undefined, `1` → `9` (low) and `≥8` → `1` (top).
+ */
+declare function defaultPriorityMap(priority: number): number;
+/**
+ * Serialize one occurrence into the raw (unfolded) lines of a `VEVENT`
+ * component. Used by {@link toICS}; folding is applied when the calendar is
+ * assembled. Returns lines so the caller controls folding/joining.
+ */
+declare function veventLines(event: ICSEvent, options?: ICSOptions): string[];
+/**
+ * Serialize one occurrence to a folded `VEVENT` block (CRLF-joined). For a
+ * full calendar use {@link toICS}.
+ */
+declare function eventToVEvent(event: ICSEvent, options?: ICSOptions): string;
+
+/**
+ * RFC 5545 text escaping and content-line folding.
+ */
+/**
+ * Escape a TEXT value per RFC 5545 §3.3.11: backslash, semicolon, comma and
+ * newlines. The backslash must be replaced first so the escapes it introduces
+ * are not double-escaped.
+ */
+declare function escapeText(value: string): string;
+/**
+ * Fold a single content line to ≤75 octets per RFC 5545 §3.1, breaking on
+ * octet (UTF-8 byte) boundaries — never inside a multi-byte character — and
+ * continuing with CRLF + a single leading space. Continuation lines reserve
+ * one octet for that space, so their content cap is 74. Short lines are
+ * returned unchanged.
+ */
+declare function foldLine(line: string): string;
+
+export { type ICSEvent, type ICSOptions, type ICSReminder, defaultPriorityMap, escapeText, eventToVEvent, foldLine, toICS, veventLines };

package/dist/index.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Plain, structural shape the ICS exporter consumes. A calendaryjs
+ * `CalendarEvent` satisfies it (see the structural assertion in
+ * `to-ics.test.ts`), but so does any plain object — keeping this package an
+ * edge integration that never forces a calendaryjs runtime dependency.
+ *
+ * One `ICSEvent` = one already-expanded occurrence (a single calendar day).
+ * The core has already applied recurrence, `exceptions` and `overrideDates`,
+ * so the exporter emits one `VEVENT` per occurrence and needs no `RRULE`.
+ */
+interface ICSEvent {
+    /** Occurrence date, `YYYY-MM-DD`. Required → `DTSTART`. */
+    date: string;
+    /** Required → `SUMMARY`. */
+    title: string;
+    /** All-day occurrence (no clock time) → `DTSTART;VALUE=DATE`. */
+    allDay?: boolean;
+    /** Start clock time, `HH:mm` or `HH:mm:ss` (floating/local). */
+    startTime?: string;
+    /** End clock time, `HH:mm` or `HH:mm:ss`. */
+    endTime?: string;
+    /** Duration in **minutes** → `DURATION` (used when `endTime` is absent). */
+    duration?: number;
+    /** → `DESCRIPTION`. */
+    description?: string;
+    /** → `LOCATION`. */
+    location?: string;
+    /** → `URL`. */
+    url?: string;
+    /** Origin feed/plugin — used as the `UID` domain so re-imports dedupe. */
+    source?: string;
+    /** → `CATEGORIES`. */
+    categories?: string[];
+    /**
+     * calendaryjs display precedence (CSS `z-index`: higher = on top, default 0).
+     * Inverted into ICS `PRIORITY` (1 = highest, 9 = lowest, 0 = undefined) by
+     * {@link ICSOptions.priorityMap}.
+     */
+    priority?: number;
+    /** → `STATUS` (`CONFIRMED` / `TENTATIVE` / `CANCELLED`). */
+    status?: "confirmed" | "tentative" | "cancelled";
+    /** CSS3 colour name → `COLOR` (RFC 7986). */
+    color?: string;
+    /** Image URI → `IMAGE` (RFC 7986). */
+    icon?: string;
+    /** Lead-time reminders → one `VALARM` each. */
+    reminders?: ICSReminder[];
+    /** Originating config id — part of a stable `UID`. */
+    sourceEventId?: string;
+    /** Group id — part of a stable `UID`. */
+    groupId?: string;
+}
+/** A single reminder → one `VALARM` with a relative `TRIGGER`. */
+interface ICSReminder {
+    /** `notification` → `ACTION:DISPLAY`; `email` → `ACTION:EMAIL`. */
+    type?: "notification" | "email";
+    /** Lead time in **minutes before** the occurrence → `TRIGGER:-PTnM`. */
+    trigger: number;
+    /** Reminder text → `DESCRIPTION` (falls back to the event title). */
+    message?: string;
+}
+/** Options for {@link toICS} and {@link eventToVEvent}. */
+interface ICSOptions {
+    /** `PRODID`. Default `-//calendaryjs//calendaryjs-plugin-ics//EN`. */
+    prodId?: string;
+    /** `X-WR-CALNAME` — the calendar's display name. */
+    calendarName?: string;
+    /** `METHOD` (e.g. `PUBLISH`). Omitted by default. */
+    method?: string;
+    /**
+     * `DTSTAMP` for every event. Defaults to the current time; pass a fixed
+     * `Date` for deterministic, diff-friendly output.
+     */
+    dtstamp?: Date;
+    /**
+     * Map a calendaryjs `priority` (z-index) to an ICS `PRIORITY` (1 = highest,
+     * 9 = lowest). Return `0` to omit. Default: importance inverts to rank, so a
+     * higher calendaryjs priority becomes a lower (more urgent) ICS number.
+     */
+    priorityMap?: (priority: number) => number;
+}
+
+/**
+ * Serialize an array of already-expanded occurrences into a single RFC 5545
+ * `VCALENDAR` document (CRLF line endings, octet-folded). One `VEVENT` is
+ * emitted per occurrence — no `RRULE` — so non-Gregorian recurrences (lunar,
+ * hijri) and per-occurrence `exceptions`/`overrideDates` (already applied by
+ * the core) export correctly.
+ *
+ * @example
+ * ```typescript
+ * import { calendary } from "calendaryjs";
+ * import { toICS } from "calendaryjs-plugin-ics";
+ *
+ * const cal = calendary();
+ * // ... add events ...
+ * const events = cal.getEventsInRange("2025-01-01", "2025-12-31");
+ * const ics = toICS(events, { calendarName: "Family" });
+ * ```
+ */
+declare function toICS(events: ICSEvent[], options?: ICSOptions): string;
+
+/**
+ * Default mapping from a calendaryjs `priority` (z-index: higher = more
+ * important, unbounded, default 0) to an ICS `PRIORITY` (1 = highest, 9 =
+ * lowest, 0 = undefined). Importance inverts to rank and is clamped to 1–9, so
+ * `0` stays undefined, `1` → `9` (low) and `≥8` → `1` (top).
+ */
+declare function defaultPriorityMap(priority: number): number;
+/**
+ * Serialize one occurrence into the raw (unfolded) lines of a `VEVENT`
+ * component. Used by {@link toICS}; folding is applied when the calendar is
+ * assembled. Returns lines so the caller controls folding/joining.
+ */
+declare function veventLines(event: ICSEvent, options?: ICSOptions): string[];
+/**
+ * Serialize one occurrence to a folded `VEVENT` block (CRLF-joined). For a
+ * full calendar use {@link toICS}.
+ */
+declare function eventToVEvent(event: ICSEvent, options?: ICSOptions): string;
+
+/**
+ * RFC 5545 text escaping and content-line folding.
+ */
+/**
+ * Escape a TEXT value per RFC 5545 §3.3.11: backslash, semicolon, comma and
+ * newlines. The backslash must be replaced first so the escapes it introduces
+ * are not double-escaped.
+ */
+declare function escapeText(value: string): string;
+/**
+ * Fold a single content line to ≤75 octets per RFC 5545 §3.1, breaking on
+ * octet (UTF-8 byte) boundaries — never inside a multi-byte character — and
+ * continuing with CRLF + a single leading space. Continuation lines reserve
+ * one octet for that space, so their content cap is 74. Short lines are
+ * returned unchanged.
+ */
+declare function foldLine(line: string): string;
+
+export { type ICSEvent, type ICSOptions, type ICSReminder, defaultPriorityMap, escapeText, eventToVEvent, foldLine, toICS, veventLines };

package/dist/index.js

@@ -0,0 +1,138 @@
+// src/escape.ts
+var encoder = new TextEncoder();
+function escapeText(value) {
+  return value.replace(/\\/g, "\\\\").replace(/;/g, "\\;").replace(/,/g, "\\,").replace(/\r\n|\r|\n/g, "\\n");
+}
+function foldLine(line) {
+  if (encoder.encode(line).length <= 75) return line;
+  let result = "";
+  let segment = "";
+  let segmentBytes = 0;
+  for (const char of line) {
+    const charBytes = encoder.encode(char).length;
+    const cap = result === "" ? 75 : 74;
+    if (segmentBytes + charBytes > cap) {
+      result += result === "" ? segment : `\r
+ ${segment}`;
+      segment = char;
+      segmentBytes = charBytes;
+    } else {
+      segment += char;
+      segmentBytes += charBytes;
+    }
+  }
+  result += result === "" ? segment : `\r
+ ${segment}`;
+  return result;
+}
+
+// src/format.ts
+var pad2 = (value) => String(value).padStart(2, "0");
+function formatDate(date) {
+  return date.replace(/-/g, "");
+}
+function formatTime(time) {
+  const [h = "0", m = "0", s = "0"] = time.split(":");
+  return `${pad2(h)}${pad2(m)}${pad2(s)}`;
+}
+function formatDateTime(date, time) {
+  return `${formatDate(date)}T${formatTime(time)}`;
+}
+function formatStamp(date) {
+  return `${date.getUTCFullYear()}${pad2(date.getUTCMonth() + 1)}${pad2(date.getUTCDate())}T${pad2(date.getUTCHours())}${pad2(date.getUTCMinutes())}${pad2(date.getUTCSeconds())}Z`;
+}
+function nextDateValue(date) {
+  const [y, m, d] = date.split("-").map(Number);
+  const next = new Date(Date.UTC(y, m - 1, d + 1));
+  return `${next.getUTCFullYear()}${pad2(next.getUTCMonth() + 1)}${pad2(next.getUTCDate())}`;
+}
+function formatDuration(minutes) {
+  if (minutes <= 0) return "PT0M";
+  const hours = Math.floor(minutes / 60);
+  const mins = minutes % 60;
+  return `PT${hours ? `${hours}H` : ""}${mins ? `${mins}M` : ""}`;
+}
+
+// src/vevent.ts
+function defaultPriorityMap(priority) {
+  if (priority <= 0) return 0;
+  return Math.max(1, 9 - Math.min(priority, 8));
+}
+function valarmLines(reminder, fallback) {
+  const text = escapeText(reminder.message ?? fallback);
+  const lines = [
+    "BEGIN:VALARM",
+    `ACTION:${reminder.type === "email" ? "EMAIL" : "DISPLAY"}`,
+    `TRIGGER:-PT${Math.abs(reminder.trigger)}M`,
+    `DESCRIPTION:${text}`
+  ];
+  if (reminder.type === "email") lines.push(`SUMMARY:${text}`);
+  lines.push("END:VALARM");
+  return lines;
+}
+function veventLines(event, options = {}) {
+  const lines = ["BEGIN:VEVENT"];
+  const localPart = [event.groupId, event.sourceEventId ?? slug(event.title), event.date].filter(Boolean).join("-");
+  lines.push(`UID:${localPart}@${event.source ?? "calendaryjs"}`);
+  lines.push(`DTSTAMP:${formatStamp(options.dtstamp ?? /* @__PURE__ */ new Date())}`);
+  const allDay = event.allDay === true || !event.startTime;
+  if (allDay) {
+    lines.push(`DTSTART;VALUE=DATE:${formatDate(event.date)}`);
+    lines.push(`DTEND;VALUE=DATE:${nextDateValue(event.date)}`);
+  } else {
+    lines.push(`DTSTART:${formatDateTime(event.date, event.startTime)}`);
+    if (event.endTime) {
+      lines.push(`DTEND:${formatDateTime(event.date, event.endTime)}`);
+    } else if (event.duration) {
+      lines.push(`DURATION:${formatDuration(event.duration)}`);
+    }
+  }
+  lines.push(`SUMMARY:${escapeText(event.title)}`);
+  if (event.description) lines.push(`DESCRIPTION:${escapeText(event.description)}`);
+  if (event.location) lines.push(`LOCATION:${escapeText(event.location)}`);
+  if (event.url) lines.push(`URL:${event.url}`);
+  if (event.categories?.length) {
+    lines.push(`CATEGORIES:${event.categories.map(escapeText).join(",")}`);
+  }
+  if (event.status) lines.push(`STATUS:${event.status.toUpperCase()}`);
+  if (event.priority !== void 0) {
+    const map = options.priorityMap ?? defaultPriorityMap;
+    const icsPriority = map(event.priority);
+    if (icsPriority > 0) lines.push(`PRIORITY:${icsPriority}`);
+  }
+  if (event.color) lines.push(`COLOR:${event.color}`);
+  if (event.icon) lines.push(`IMAGE;VALUE=URI:${event.icon}`);
+  for (const reminder of event.reminders ?? []) {
+    lines.push(...valarmLines(reminder, event.title));
+  }
+  lines.push("END:VEVENT");
+  return lines;
+}
+function eventToVEvent(event, options = {}) {
+  return veventLines(event, options).map(foldLine).join("\r\n");
+}
+function slug(value) {
+  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "event";
+}
+
+// src/to-ics.ts
+var DEFAULT_PRODID = "-//calendaryjs//calendaryjs-plugin-ics//EN";
+function toICS(events, options = {}) {
+  const stamp = options.dtstamp ?? /* @__PURE__ */ new Date();
+  const lines = [
+    "BEGIN:VCALENDAR",
+    "VERSION:2.0",
+    `PRODID:${options.prodId ?? DEFAULT_PRODID}`,
+    "CALSCALE:GREGORIAN"
+  ];
+  if (options.method) lines.push(`METHOD:${options.method}`);
+  if (options.calendarName) lines.push(`X-WR-CALNAME:${escapeText(options.calendarName)}`);
+  const eventOptions = { ...options, dtstamp: stamp };
+  for (const event of events) {
+    lines.push(...veventLines(event, eventOptions));
+  }
+  lines.push("END:VCALENDAR");
+  return lines.map(foldLine).join("\r\n") + "\r\n";
+}
+
+export { defaultPriorityMap, escapeText, eventToVEvent, foldLine, toICS, veventLines };

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "calendaryjs-plugin-ics",
+  "version": "0.1.0",
+  "description": "ICS (RFC 5545) export for calendaryjs — serialize generated calendar occurrences to a standard .ics VCALENDAR (VEVENT, VALARM reminders, PRIORITY, CATEGORIES, COLOR/IMAGE). The edge integration: calendaryjs owns the core, ICS rides at the boundary.",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "keywords": [
+    "ics",
+    "icalendar",
+    "rfc5545",
+    "vevent",
+    "vcalendar",
+    "export",
+    "calendar",
+    "calendaryjs",
+    "calendaryjs-plugin",
+    "plugin"
+  ],
+  "calendaryjs": {
+    "category": "integration"
+  },
+  "author": "calendaryjs",
+  "license": "MIT",
+  "peerDependencies": {
+    "calendaryjs": ">=0.1.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.2",
+    "vitest": "^4.0.18",
+    "calendaryjs": "0.2.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "tsup": {
+    "entry": [
+      "src/index.ts"
+    ],
+    "format": [
+      "esm",
+      "cjs"
+    ],
+    "dts": true,
+    "clean": true,
+    "treeshake": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/calendaryjs/calendaryjs.git",
+    "directory": "packages/ics"
+  },
+  "homepage": "https://github.com/calendaryjs/calendaryjs/tree/main/packages/ics#readme",
+  "bugs": {
+    "url": "https://github.com/calendaryjs/calendaryjs/issues"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "tsup",
+    "test:coverage": "vitest run --coverage"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}