calendaryjs 0.2.3 → 0.3.0

package/dist/{events-Bm7R9XFB.d.ts → events-DSiv9j6V.d.ts}

@@ -228,8 +228,10 @@ interface ConstEvent<TMetadata extends Record<string, unknown> = Record<string,
      */
     month: number;
     /**
-     * Day of the month (1-31)
+     * Day of the month. `1`–`31`, or **negative to count from the end**
+     * (`-1` = last day, `-2` = second-to-last).
      * @example 25 // 25th day
+     * @example -1 // last day of the month
      */
     day: number;
     /**
@@ -292,9 +294,12 @@ interface FixedEvent<TMetadata extends Record<string, unknown> = Record<string,
 interface MonthlyEvent<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> extends BaseEventProperties<TMetadata, TCategory> {
     type: "monthly";
     /**
-     * Day of the month (1-31)
-     * Note: If day exceeds month's days (e.g., 31 in February), event is skipped for that month
+     * Day of the month. `1`–`31`, or **negative to count from the end**
+     * (`-1` = last day of every month, `-2` = second-to-last).
+     * Note: a positive day past the month's length (e.g. 31 in February) is
+     * skipped for that month.
      * @example 15 // 15th of each month
+     * @example -1 // last day of every month
      */
     day: number;
     /**
@@ -372,6 +377,43 @@ interface WeeklyEvent<TMetadata extends Record<string, unknown> = Record<string,
      */
     excludeDates?: string[];
 }
+/**
+ * DAILY - Recurring events every day, or every N days.
+ * Supports an interval, a date range, and date exclusions. With `interval > 1`
+ * the cadence is phased off `startDate` (or a fixed epoch when omitted) so
+ * "every N days" stays in step across the year boundary instead of resetting.
+ * @template TMetadata - Custom metadata type extending Record<string, unknown>
+ * @example
+ * // Every day
+ * { type: "daily", id: "standup" }
+ *
+ * // Every 3 days, anchored to a start date
+ * { type: "daily", id: "meds", interval: 3, startDate: "2025-01-01" }
+ */
+interface DailyEvent<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> extends BaseEventProperties<TMetadata, TCategory> {
+    type: "daily";
+    /**
+     * Recurrence interval in days (default: 1).
+     * @example 3 // every third day
+     */
+    interval?: number;
+    /**
+     * Anchor date for interval phasing and the lower bound (YYYY-MM-DD).
+     * With `interval > 1`, occurrences land on `startDate`, `startDate + interval`, …
+     * @example "2025-01-06"
+     */
+    startDate?: string;
+    /**
+     * End date for the recurrence (YYYY-MM-DD, inclusive).
+     * @example "2025-12-31"
+     */
+    endDate?: string;
+    /**
+     * Specific dates to exclude (YYYY-MM-DD).
+     * @example ["2025-12-25"]
+     */
+    excludeDates?: string[];
+}
 /**
  * FORMULA - Custom formula-based events
  * @template TMetadata - Custom metadata type extending Record<string, unknown>
@@ -434,11 +476,13 @@ interface NthWeekdayEvent<TMetadata extends Record<string, unknown> = Record<str
      * - `1`–`4`: 1st through 4th occurrence
      * - `-1`: last occurrence
      *
-     * Required in simple mode (paired with `month`). Omit for anchored mode.
+     * Required in simple mode. Omit for anchored mode.
      */
     nth?: 1 | 2 | 3 | 4 | -1;
     /**
-     * Month (1-12). Required in simple mode. Omit for anchored mode.
+     * Month (1-12). In simple mode, **omit to repeat every month** (e.g. the first
+     * Monday of every month); set it to pin one month (e.g. the 4th Thursday of
+     * November). Ignored in anchored mode.
      */
     month?: number;
     /**
@@ -488,7 +532,7 @@ interface RelativeEvent<TMetadata extends Record<string, unknown> = Record<strin
         weeks?: number;
     };
 }
-type CoreEventConfig<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> = ConstEvent<TMetadata, TCategory> | FixedEvent<TMetadata, TCategory> | MonthlyEvent<TMetadata, TCategory> | WeeklyEvent<TMetadata, TCategory> | NthWeekdayEvent<TMetadata, TCategory> | FormulaEvent<TMetadata, TCategory> | RelativeEvent<TMetadata, TCategory>;
+type CoreEventConfig<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> = ConstEvent<TMetadata, TCategory> | FixedEvent<TMetadata, TCategory> | MonthlyEvent<TMetadata, TCategory> | WeeklyEvent<TMetadata, TCategory> | DailyEvent<TMetadata, TCategory> | NthWeekdayEvent<TMetadata, TCategory> | FormulaEvent<TMetadata, TCategory> | RelativeEvent<TMetadata, TCategory>;
 /**
  * Generic event config - extended by plugins.
  * Use the generic parameter to enforce metadata types.
@@ -513,7 +557,7 @@ type EventConfig<TMetadata extends Record<string, unknown> = Record<string, unkn
 /**
  * Event type identifiers
  */
-type CoreEventType = "const" | "fixed" | "monthly" | "weekly" | "nth-weekday" | "formula" | "relative";
+type CoreEventType = "const" | "fixed" | "monthly" | "weekly" | "daily" | "nth-weekday" | "formula" | "relative";
 /**
  * Custom event configuration for overriding event properties.
  * Used by generator packages to allow customization of generated events.
@@ -587,4 +631,4 @@ type CustomEventConfig<TMetadata extends Record<string, unknown> = Record<string
  */
 type CustomEventResolver<TKey extends string, TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string, TExclude extends keyof BaseEventProperties = never> = (key: TKey) => CustomEventConfig<TMetadata, TCategory, TExclude> | undefined;
 
-export type { BaseEventProperties as B, ConflictResolver as C, DateString as D, EventConfig as E, FixedEvent as F, MonthlyEvent as M, NthWeekdayEvent as N, OverrideDatesMap as O, RelativeEvent as R, WeekdayIndex as W, ConflictAction as a, ConflictMap as b, ConflictResolverFn as c, ConstEvent as d, CoreEventConfig as e, CoreEventType as f, CustomEventConfig as g, CustomEventResolver as h, DateAnchor as i, FormulaEvent as j, Reminder as k, WeeklyEvent as l };
+export type { BaseEventProperties as B, ConflictResolver as C, DateString as D, EventConfig as E, FixedEvent as F, MonthlyEvent as M, NthWeekdayEvent as N, OverrideDatesMap as O, RelativeEvent as R, WeekdayIndex as W, ConflictAction as a, ConflictMap as b, ConflictResolverFn as c, ConstEvent as d, CoreEventConfig as e, CoreEventType as f, CustomEventConfig as g, CustomEventResolver as h, DailyEvent as i, DateAnchor as j, EventException as k, EventExceptions as l, FormulaEvent as m, Reminder as n, WeeklyEvent as o };

package/dist/index.cjs

@@ -86,6 +86,14 @@ function getYearsInRange(from, to) {
 function createDate(year, month, day) {
   return new Date(year, month - 1, day);
 }
+function getDaysInMonth(year, month) {
+  return new Date(year, month, 0).getDate();
+}
+function resolveDayOfMonth(day, year, month) {
+  if (day >= 0) return day;
+  const resolved = getDaysInMonth(year, month) + day + 1;
+  return resolved >= 1 ? resolved : null;
+}
 function addDays(date, days) {
   const result = new Date(date);
   result.setDate(result.getDate() + days);
@@ -127,7 +135,7 @@ var constEventHandler = {
   validate(event) {
     if (typeof event !== "object" || event === null) return false;
     const e = event;
-    return e.type === "const" && typeof e.month === "number" && e.month >= 1 && e.month <= 12 && typeof e.day === "number" && e.day >= 1 && e.day <= 31 && typeof e.title === "string" && typeof e.id === "string";
+    return e.type === "const" && typeof e.month === "number" && e.month >= 1 && e.month <= 12 && typeof e.day === "number" && e.day >= -31 && e.day <= 31 && e.day !== 0 && typeof e.title === "string" && typeof e.id === "string";
   },
   generate(event, year) {
     if (event.startYear !== void 0 && year < event.startYear) {
@@ -139,7 +147,9 @@ var constEventHandler = {
     if (event.excludeYears?.includes(year)) {
       return [];
     }
-    return [createDate(year, event.month, event.day)];
+    const day = resolveDayOfMonth(event.day, year, event.month);
+    if (day === null) return [];
+    return [createDate(year, event.month, day)];
   }
 };
 
@@ -159,14 +169,11 @@ var fixedEventHandler = {
 };
 
 // src/generators/monthly.ts
-function getDaysInMonth(year, month) {
-  return new Date(year, month, 0).getDate();
-}
 var monthlyEventHandler = {
   validate(event) {
     if (typeof event !== "object" || event === null) return false;
     const e = event;
-    return e.type === "monthly" && typeof e.day === "number" && e.day >= 1 && e.day <= 31 && typeof e.title === "string" && typeof e.id === "string";
+    return e.type === "monthly" && typeof e.day === "number" && e.day >= -31 && e.day <= 31 && e.day !== 0 && typeof e.title === "string" && typeof e.id === "string";
   },
   generate(event, year) {
     const dates = [];
@@ -184,10 +191,11 @@ var monthlyEventHandler = {
         continue;
       }
       const daysInMonth = getDaysInMonth(year, month);
-      if (event.day > daysInMonth) {
+      const day = resolveDayOfMonth(event.day, year, month);
+      if (day === null || day > daysInMonth) {
         continue;
       }
-      const date = createDate(year, month, event.day);
+      const date = createDate(year, month, day);
       const dateStr = formatDate(date);
       if (event.excludeDates?.includes(dateStr)) {
         continue;
@@ -265,6 +273,49 @@ var weeklyEventHandler = {
   }
 };
 
+// src/generators/daily.ts
+var PHASE_EPOCH = createDate(1970, 1, 1);
+var dailyEventHandler = {
+  validate(event) {
+    if (typeof event !== "object" || event === null) return false;
+    const e = event;
+    if (e.type !== "daily") return false;
+    if (typeof e.title !== "string" || typeof e.id !== "string") return false;
+    if (e.interval !== void 0 && (typeof e.interval !== "number" || e.interval < 1))
+      return false;
+    return true;
+  },
+  generate(event, year) {
+    const interval = event.interval ?? 1;
+    const yearEnd = createDate(year, 12, 31);
+    const startLimit = event.startDate ? parseDate(event.startDate) : null;
+    const endLimit = event.endDate ? parseDate(event.endDate) : null;
+    const anchor = startLimit ?? PHASE_EPOCH;
+    const dates = [];
+    let current = createDate(year, 1, 1);
+    while (current <= yearEnd) {
+      if (startLimit && current < startLimit) {
+        current = addDays(current, 1);
+        continue;
+      }
+      if (endLimit && current > endLimit) break;
+      if (interval > 1) {
+        const offset = daysBetween(anchor, current);
+        if (offset % interval !== 0) {
+          current = addDays(current, 1);
+          continue;
+        }
+      }
+      const dateStr = formatDate(current);
+      if (!event.excludeDates?.includes(dateStr)) {
+        dates.push(new Date(current));
+      }
+      current = addDays(current, 1);
+    }
+    return dates;
+  }
+};
+
 // src/generators/nth-weekday.ts
 function nthWeekdayInMonth(year, month, dayOfWeek, nth) {
   if (nth === -1) {
@@ -307,7 +358,7 @@ var nthWeekdayEventHandler = {
     const hasAnchored = e.after !== void 0;
     if (hasSimple && !hasAnchored) {
       if (typeof e.nth !== "number" || ![1, 2, 3, 4, -1].includes(e.nth)) return false;
-      if (typeof e.month !== "number" || e.month < 1 || e.month > 12)
+      if (e.month !== void 0 && (typeof e.month !== "number" || e.month < 1 || e.month > 12))
         return false;
     } else if (!hasAnchored) {
       return false;
@@ -331,9 +382,17 @@ var nthWeekdayEventHandler = {
       }
       return candidate ? [candidate] : [];
     }
-    if (event.nth !== void 0 && event.month !== void 0) {
-      const date = nthWeekdayInMonth(year, event.month, event.dayOfWeek, event.nth);
-      return date ? [date] : [];
+    if (event.nth !== void 0) {
+      if (event.month !== void 0) {
+        const date = nthWeekdayInMonth(year, event.month, event.dayOfWeek, event.nth);
+        return date ? [date] : [];
+      }
+      const dates = [];
+      for (let month = 1; month <= 12; month++) {
+        const date = nthWeekdayInMonth(year, month, event.dayOfWeek, event.nth);
+        if (date) dates.push(date);
+      }
+      return dates;
     }
     return [];
   }
@@ -650,6 +709,27 @@ var SearchBuilder = class {
     this.options.hasAllCategories = categories;
     return this;
   }
+  /**
+   * Filter by event type(s) — match any (e.g. `"weekly"`, `"daily"`, a plugin type).
+   */
+  type(...types) {
+    this.options.types = types;
+    return this;
+  }
+  /**
+   * Filter by status — match any (e.g. hide cancelled by listing the ones you want).
+   */
+  status(...status) {
+    this.options.status = status;
+    return this;
+  }
+  /**
+   * Filter by source — match any (the plugin / feed / subscription that produced it).
+   */
+  source(...source) {
+    this.options.source = source;
+    return this;
+  }
   /**
    * Search by metadata key-value pairs.
    * Supports nested objects and case-insensitive string matching.
@@ -897,6 +977,15 @@ function executeSearch(events, options) {
       return options.hasAllCategories.every((cat) => e.categories.includes(cat));
     });
   }
+  if (options.types && options.types.length > 0) {
+    results = results.filter((e) => options.types.includes(e.type));
+  }
+  if (options.status && options.status.length > 0) {
+    results = results.filter((e) => e.status !== void 0 && options.status.includes(e.status));
+  }
+  if (options.source && options.source.length > 0) {
+    results = results.filter((e) => e.source !== void 0 && options.source.includes(e.source));
+  }
   if (options.metadata) {
     results = results.filter((e) => matchesMetadata(e.metadata, options.metadata));
   }
@@ -990,6 +1079,7 @@ var CalendaryInstance = class _CalendaryInstance {
     this.eventTypeHandlers.set("fixed", fixedEventHandler);
     this.eventTypeHandlers.set("monthly", monthlyEventHandler);
     this.eventTypeHandlers.set("weekly", weeklyEventHandler);
+    this.eventTypeHandlers.set("daily", dailyEventHandler);
     this.eventTypeHandlers.set("nth-weekday", nthWeekdayEventHandler);
     this.eventTypeHandlers.set(
       "formula",
@@ -1086,6 +1176,27 @@ var CalendaryInstance = class _CalendaryInstance {
       events: c.events
     });
   }
+  /**
+   * Export events as a portable {@link Collection} — the inverse of {@link load}.
+   * Serializes the plain event configs plus a manifest of the plugins their event
+   * types need, so the result round-trips back through `load()`. Pass it to
+   * `JSON.stringify` for a `.cdy` document.
+   *
+   * @param options.group - export a single group; omit to export every group's events.
+   * @param options.name - the collection name (also the default group id on re-load).
+   * @param options.version - an informational version stamp.
+   */
+  toCollection(options = {}) {
+    const groups = options.group !== void 0 ? [this.groups.get(options.group)].filter((g) => g != null) : [...this.groups.values()];
+    const events = groups.flatMap((g) => g.events);
+    const usedTypes = new Set(events.map((e) => e.type));
+    const plugins = [...this.plugins.values()].filter((p) => Object.keys(p.eventTypes ?? {}).some((t) => usedTypes.has(t))).map((p) => p.name);
+    const out = { events };
+    if (options.name) out.collection = options.name;
+    if (options.version) out.version = options.version;
+    if (plugins.length) out.plugins = plugins;
+    return out;
+  }
   removeGroup(groupId) {
     this.groups.delete(groupId);
     this.dirty = true;
@@ -1106,12 +1217,18 @@ var CalendaryInstance = class _CalendaryInstance {
     return this;
   }
   generateEvents(from, to) {
+    if (this.dirty) {
+      this.cache.invalidate();
+      this.dirty = false;
+    }
     const cacheKey = `${from}:${to}`;
-    if (!this.dirty && this.cache.has(cacheKey)) {
+    if (this.cache.has(cacheKey)) {
       return this.cache.get(cacheKey);
     }
     const events = [];
-    const years = getYearsInRange(from, to);
+    const inRange = getYearsInRange(from, to);
+    const years = inRange.length ? [inRange[0] - 1, ...inRange, inRange[inRange.length - 1] + 1] : inRange;
+    const seen = /* @__PURE__ */ new Set();
     for (const group of this.groups.values()) {
       if (!group.enabled) continue;
       for (const eventConfig of group.events) {
@@ -1124,6 +1241,10 @@ var CalendaryInstance = class _CalendaryInstance {
             let dateStr = formatDate(date);
             if (directives.startDate && dateStr < directives.startDate) continue;
             if (directives.endDate && dateStr > directives.endDate) continue;
+            const occYear = +dateStr.slice(0, 4);
+            if (directives.startYear !== void 0 && occYear < directives.startYear) continue;
+            if (directives.endYear !== void 0 && occYear > directives.endYear) continue;
+            if (directives.excludeYears?.includes(occYear)) continue;
             const exception = directives.exceptions?.[dateStr];
             if (exception && "skip" in exception) {
               continue;
@@ -1143,6 +1264,13 @@ var CalendaryInstance = class _CalendaryInstance {
               }
             }
             if (!isDateInRange(dateStr, from, to)) continue;
+            const dedupeKey = JSON.stringify([
+              group.id,
+              eventConfig.id,
+              dateStr
+            ]);
+            if (seen.has(dedupeKey)) continue;
+            seen.add(dedupeKey);
             const calendarEvent = this.createCalendarEvent(
               eventConfig,
               group,
@@ -1161,13 +1289,13 @@ var CalendaryInstance = class _CalendaryInstance {
     });
     this.cache.set(cacheKey, events);
     this.index.index(events);
-    this.dirty = false;
     return events;
   }
   createCalendarEvent(config, group, dateStr, override) {
     const base = config;
     const event = {
       id: generateEventId(base.id, dateStr),
+      type: base.type,
       sourceEventId: base.id,
       title: base.title,
       date: dateStr,
@@ -1223,13 +1351,16 @@ var CalendaryInstance = class _CalendaryInstance {
    * Get calendar days for a date range
    */
   getDays(options) {
-    const { groups } = options;
+    const { groups, types } = options;
     const fromStr = normalizeDateInput(options.from);
     const toStr = normalizeDateInput(options.to);
     let events = this.generateEvents(fromStr, toStr);
     if (groups && groups.length > 0) {
       events = events.filter((e) => groups.includes(e.groupId));
     }
+    if (types && types.length > 0) {
+      events = events.filter((e) => types.includes(e.type));
+    }
     const eventsByDate = /* @__PURE__ */ new Map();
     for (const event of events) {
       const existing = eventsByDate.get(event.date) || [];

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { E as EventConfig, B as BaseEventProperties, D as DateString, C as ConflictResolver, a as ConflictAction } from './events-Bm7R9XFB.cjs';
-export { b as ConflictMap, c as ConflictResolverFn, d as ConstEvent, e as CoreEventConfig, f as CoreEventType, g as CustomEventConfig, h as CustomEventResolver, i as DateAnchor, F as FixedEvent, j as FormulaEvent, M as MonthlyEvent, N as NthWeekdayEvent, O as OverrideDatesMap, R as RelativeEvent, k as Reminder, W as WeekdayIndex, l as WeeklyEvent } from './events-Bm7R9XFB.cjs';
+import { E as EventConfig, B as BaseEventProperties, D as DateString, C as ConflictResolver, a as ConflictAction } from './events-DSiv9j6V.cjs';
+export { b as ConflictMap, c as ConflictResolverFn, d as ConstEvent, e as CoreEventConfig, f as CoreEventType, g as CustomEventConfig, h as CustomEventResolver, i as DailyEvent, j as DateAnchor, k as EventException, l as EventExceptions, F as FixedEvent, m as FormulaEvent, M as MonthlyEvent, N as NthWeekdayEvent, O as OverrideDatesMap, R as RelativeEvent, n as Reminder, W as WeekdayIndex, o as WeeklyEvent } from './events-DSiv9j6V.cjs';
 
 /**
  * Group configuration
@@ -71,6 +71,11 @@ interface Group extends GroupConfig {
  * ```
  */
 interface CalendarEvent<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> extends BaseEventProperties<TMetadata, TCategory> {
+    /**
+     * The originating event-config `type` (e.g. `"const"`, `"weekly"`, `"daily"`,
+     * or a plugin type). Lets a consumer group or filter occurrences by kind.
+     */
+    type: string;
     /** Original event ID from the event config */
     sourceEventId: string;
     /** Date in YYYY-MM-DD format */
@@ -269,6 +274,9 @@ interface SearchOptions {
     keywordsContain?: string[];
     categories?: string[];
     hasAllCategories?: string[];
+    types?: string[];
+    status?: ("confirmed" | "tentative" | "cancelled")[];
+    source?: string[];
     metadata?: MetadataQuery;
     minPriority?: number;
     maxPriority?: number;
@@ -368,6 +376,18 @@ declare class SearchBuilder<TMetadata extends Record<string, unknown> = Record<s
      * Filter by categories (must have all)
      */
     hasAllCategories(categories: string[]): this;
+    /**
+     * Filter by event type(s) — match any (e.g. `"weekly"`, `"daily"`, a plugin type).
+     */
+    type(...types: string[]): this;
+    /**
+     * Filter by status — match any (e.g. hide cancelled by listing the ones you want).
+     */
+    status(...status: ("confirmed" | "tentative" | "cancelled")[]): this;
+    /**
+     * Filter by source — match any (the plugin / feed / subscription that produced it).
+     */
+    source(...source: string[]): this;
     /**
      * Search by metadata key-value pairs.
      * Supports nested objects and case-insensitive string matching.
@@ -512,6 +532,21 @@ declare class CalendaryInstance<TMetadata extends Record<string, unknown> = Reco
      * Nothing is fetched or executed behind your back.
      */
     load(collection: Collection | string): this;
+    /**
+     * Export events as a portable {@link Collection} — the inverse of {@link load}.
+     * Serializes the plain event configs plus a manifest of the plugins their event
+     * types need, so the result round-trips back through `load()`. Pass it to
+     * `JSON.stringify` for a `.cdy` document.
+     *
+     * @param options.group - export a single group; omit to export every group's events.
+     * @param options.name - the collection name (also the default group id on re-load).
+     * @param options.version - an informational version stamp.
+     */
+    toCollection(options?: {
+        name?: string;
+        version?: string;
+        group?: string;
+    }): Collection;
     removeGroup(groupId: string): this;
     getGroup(groupId: string): Group | undefined;
     getGroups(): Group[];

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { E as EventConfig, B as BaseEventProperties, D as DateString, C as ConflictResolver, a as ConflictAction } from './events-Bm7R9XFB.js';
-export { b as ConflictMap, c as ConflictResolverFn, d as ConstEvent, e as CoreEventConfig, f as CoreEventType, g as CustomEventConfig, h as CustomEventResolver, i as DateAnchor, F as FixedEvent, j as FormulaEvent, M as MonthlyEvent, N as NthWeekdayEvent, O as OverrideDatesMap, R as RelativeEvent, k as Reminder, W as WeekdayIndex, l as WeeklyEvent } from './events-Bm7R9XFB.js';
+import { E as EventConfig, B as BaseEventProperties, D as DateString, C as ConflictResolver, a as ConflictAction } from './events-DSiv9j6V.js';
+export { b as ConflictMap, c as ConflictResolverFn, d as ConstEvent, e as CoreEventConfig, f as CoreEventType, g as CustomEventConfig, h as CustomEventResolver, i as DailyEvent, j as DateAnchor, k as EventException, l as EventExceptions, F as FixedEvent, m as FormulaEvent, M as MonthlyEvent, N as NthWeekdayEvent, O as OverrideDatesMap, R as RelativeEvent, n as Reminder, W as WeekdayIndex, o as WeeklyEvent } from './events-DSiv9j6V.js';
 
 /**
  * Group configuration
@@ -71,6 +71,11 @@ interface Group extends GroupConfig {
  * ```
  */
 interface CalendarEvent<TMetadata extends Record<string, unknown> = Record<string, unknown>, TCategory extends string = string> extends BaseEventProperties<TMetadata, TCategory> {
+    /**
+     * The originating event-config `type` (e.g. `"const"`, `"weekly"`, `"daily"`,
+     * or a plugin type). Lets a consumer group or filter occurrences by kind.
+     */
+    type: string;
     /** Original event ID from the event config */
     sourceEventId: string;
     /** Date in YYYY-MM-DD format */
@@ -269,6 +274,9 @@ interface SearchOptions {
     keywordsContain?: string[];
     categories?: string[];
     hasAllCategories?: string[];
+    types?: string[];
+    status?: ("confirmed" | "tentative" | "cancelled")[];
+    source?: string[];
     metadata?: MetadataQuery;
     minPriority?: number;
     maxPriority?: number;
@@ -368,6 +376,18 @@ declare class SearchBuilder<TMetadata extends Record<string, unknown> = Record<s
      * Filter by categories (must have all)
      */
     hasAllCategories(categories: string[]): this;
+    /**
+     * Filter by event type(s) — match any (e.g. `"weekly"`, `"daily"`, a plugin type).
+     */
+    type(...types: string[]): this;
+    /**
+     * Filter by status — match any (e.g. hide cancelled by listing the ones you want).
+     */
+    status(...status: ("confirmed" | "tentative" | "cancelled")[]): this;
+    /**
+     * Filter by source — match any (the plugin / feed / subscription that produced it).
+     */
+    source(...source: string[]): this;
     /**
      * Search by metadata key-value pairs.
      * Supports nested objects and case-insensitive string matching.
@@ -512,6 +532,21 @@ declare class CalendaryInstance<TMetadata extends Record<string, unknown> = Reco
      * Nothing is fetched or executed behind your back.
      */
     load(collection: Collection | string): this;
+    /**
+     * Export events as a portable {@link Collection} — the inverse of {@link load}.
+     * Serializes the plain event configs plus a manifest of the plugins their event
+     * types need, so the result round-trips back through `load()`. Pass it to
+     * `JSON.stringify` for a `.cdy` document.
+     *
+     * @param options.group - export a single group; omit to export every group's events.
+     * @param options.name - the collection name (also the default group id on re-load).
+     * @param options.version - an informational version stamp.
+     */
+    toCollection(options?: {
+        name?: string;
+        version?: string;
+        group?: string;
+    }): Collection;
     removeGroup(groupId: string): this;
     getGroup(groupId: string): Group | undefined;
     getGroups(): Group[];