@happyvertical/smrt-events 0.53.4 → 0.53.5

package/README.md

@@ -184,3 +184,80 @@ Owned asset helpers are available on both `Event` and `EventCollection` via
 | `@happyvertical/smrt-types` | Shared TypeScript types |
 | `@happyvertical/sql` | Database operations |
 | `@happyvertical/ai` | AI integration |
+
+### iCalendar source synchronization
+
+`parseICalendarEvents(source, ics, { floatingTimeZone?, limits? })` validates
+caller-supplied RFC 5545 text through the published `@happyvertical/icalendar`
+facade. `expandICalendarEvents(source, ics, options)` adds a required inclusive
+`rangeStart`/`rangeEnd` window. `syncICalendarSource({ db, source, ics, tenantId?,
+parse?, expansion? })` persists those records and returns `created`, `updated`,
+`unchanged`, and `retainedOnOmission: true`. Recurring feeds require `expansion`.
+Parsing/expansion require no database or network; sync supports SQLite and
+PostgreSQL with migrated Event/EventSeries schemas. Other dialects are not
+currently supported ([EventSeries FK gap #3469](https://github.com/happyvertical/smrt/issues/3469)); runtime-schema adapters are rejected before mutation.
+
+A tenant, source and UID identify a series. Its expanded occurrences use the
+original RECURRENCE-ID (UTC ISO instant for timed events, calendar date for
+all-day events), so a moved instance retains its ID. Non-recurring records use
+UID without an occurrence suffix. Recurring masters live in series/provenance;
+they are not duplicate Event rows alongside their first occurrence. RDATE is
+normalized using each RDATE property's own timezone and unioned with RRULE,
+duplicate instants collapse, and EXDATE slots persist as
+cancelled events. Detached records override their original slot, including a
+move beyond the requested window. Duplicate VEVENT identities reject the feed.
+
+Daily, weekly, monthly and yearly RRULEs use the SDK's public recurrence engine.
+The supported bounded subset is daily without BY filters; weekly BYDAY without
+ordinals; monthly BYDAY or BYMONTHDAY (not both), with BYSETPOS supported only for BYDAY; and yearly
+BYMONTH/BYMONTHDAY. Other BY combinations reject rather than risking unbounded
+search inside the recurrence engine. COUNT, UNTIL and INTERVAL apply throughout.
+Expansion rejects rather than truncates when it exceeds `limit` (default 1,000;
+maximum 10,000) or `maxIterations` (default 10,000; maximum 100,000, including
+slots before the window). Unsupported frequency, unknown recurrence properties,
+multiple RRULEs, EXRULE, DURATION, RDATE PERIOD and RECURRENCE-ID RANGE reject.
+SDK parser resource limits remain in force. Expand a practical window near the
+series start; very old or dense feeds may need a deliberate higher scan budget.
+
+IANA zones use the runtime's timezone database and the framework's wall-time
+conversion: DST gaps move forward and overlaps choose the first instant. UTC
+values stay UTC. Floating timed values require `parse.floatingTimeZone` (or the
+same option directly on parse/expand); no host zone is inferred. All-day DATEs
+use that policy or UTC, with exclusive DTEND and a default next-day end. A timed
+event without DTEND has zero duration. Timed recurrence keeps the exact elapsed
+duration of DTSTART to DTEND; all-day recurrence keeps calendar-day duration
+across DST. Date-only recurrence remains date-only.
+
+A higher SEQUENCE **or** a newer DTSTAMP accepts an update; equal/older versions
+are unchanged. Missing SEQUENCE is zero and missing DTSTAMP is the oldest
+stamp. A producer changing payload without either version marker is deliberately
+ignored. Each series retains the authoritative master's SDK-serialized document
+and version, including when a requested window contains no occurrences. Later
+windows expand that retained document when the supplied master is stale or equal,
+so unseen slots cannot be created from older payloads or recurrence rules. The
+master document is written in the same transaction as occurrence updates. The
+expansion requirement also applies to the retained document: a stale minimal
+cancellation that resolves to a recurring master requires a window. Without one,
+sync rejects and rolls back all writes; retry with bounded expansion.
+A cancellation is an update, and a newer scheduled record restores it.
+A minimal master cancellation (UID/STATUS/version without DTSTART) cancels known
+series events and stores a series tombstone that blocks older resurrection.
+No feed omission deletes events: outside-window records remain; omitted detached
+exceptions stay authoritative until that detached identity reappears with a
+newer version. A newer master removing EXDATE restores that generated slot.
+
+Every sync resolves its database configuration once and performs all writes on
+one transaction executor, including series creation. Failures propagate and
+roll back; callers may retry the same feed. An existing SQLite/PostgreSQL
+transaction is joined through an adapter savepoint, preserving caller rollback.
+The caller must authorize tenant/source access and serialize concurrent syncs
+for the same tenant/source; this API does not implement scheduling or locking.
+An active tenant context supplies an omitted tenantId and rejects a conflicting
+explicit tenantId, including a request for global rows. System contexts may
+explicitly import a tenant or global source.
+
+Source fetching (including conditional requests, unavailable-feed detection and
+retry scheduling) remains caller-owned. Pass only a successfully fetched feed;
+partial feeds are safe under omission retention. Sync performs no drafting or
+publication. Event metadata records UID, occurrence ID, version markers,
+RRULE/EXDATE/RDATE and whether the record is detached.

package/dist/calendar/icalendar.d.ts

@@ -0,0 +1,53 @@
+import { type ICalendarParseLimits } from '@happyvertical/icalendar';
+/** A stable upstream identity for a calendar master or detached occurrence. */
+export interface CalendarEventIdentity {
+    source: string;
+    uid: string;
+    recurrenceId?: string;
+}
+/** Parsed data SMRT needs before applying its persistence policy. */
+export interface CalendarParseOptions {
+    floatingTimeZone?: string;
+    limits?: ICalendarParseLimits;
+}
+export interface CalendarEventInput {
+    identity: CalendarEventIdentity;
+    name: string;
+    description: string;
+    startDate: Date | null;
+    endDate: Date | null;
+    allDay: boolean;
+    timeZone: string;
+    status: 'scheduled' | 'cancelled';
+    sequence: number | null;
+    dtstamp: Date | null;
+    recurrence: string | null;
+    /** True for a detached record, false for a generated occurrence. */
+    detached?: boolean;
+    excludedRecurrenceIds: string[];
+    additionalRecurrenceIds: string[];
+}
+/** A malformed calendar event cannot be given a stable source identity. */
+export declare class CalendarEventValidationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Parse VEVENT records with their RFC 5545 source identities and recurrence
+ * exception data. This does not fetch a feed or persist anything.
+ */
+export declare function parseICalendarEvents(source: string, ics: string, options?: CalendarParseOptions): CalendarEventInput[];
+export interface CalendarExpansionOptions extends CalendarParseOptions {
+    rangeStart: Date;
+    rangeEnd: Date;
+    /** Hard cap: exceeding it rejects the feed, never returns a partial success. */
+    limit?: number;
+    /** Includes occurrences scanned before the requested window. */
+    maxIterations?: number;
+}
+/** Expand a caller-bounded window through the SDK's public recurrence engine.
+ * Range endpoints are inclusive. Detached records replace their original slot;
+ * EXDATE slots are returned as cancellations so previously persisted occurrences
+ * are cancelled as well. No master is returned alongside its first occurrence.
+ */
+export declare function expandICalendarEvents(source: string, ics: string, options: CalendarExpansionOptions): CalendarEventInput[];
+//# sourceMappingURL=icalendar.d.ts.map

package/dist/calendar/icalendar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icalendar.d.ts","sourceRoot":"","sources":["../../src/calendar/icalendar.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,oBAAoB,EAE1B,MAAM,0BAA0B,CAAC;AAOlC,+EAA+E;AAC/E,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qEAAqE;AACrE,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,MAAM,CAAC,EAAE,oBAAoB,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,GAAG,WAAW,CAAC;IAClC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,OAAO,EAAE,IAAI,GAAG,IAAI,CAAC;IACrB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,oEAAoE;IACpE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,uBAAuB,EAAE,MAAM,EAAE,CAAC;CACnC;AAED,2EAA2E;AAC3E,qBAAa,4BAA6B,SAAQ,KAAK;gBACzC,OAAO,EAAE,MAAM;CAI5B;AAsED;;;GAGG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,oBAAyB,GACjC,kBAAkB,EAAE,CAkGtB;AAyBD,MAAM,WAAW,wBAAyB,SAAQ,oBAAoB;IACpE,UAAU,EAAE,IAAI,CAAC;IACjB,QAAQ,EAAE,IAAI,CAAC;IACf,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,wBAAwB,GAChC,kBAAkB,EAAE,CAqOtB"}

package/dist/calendar/sync.d.ts

@@ -0,0 +1,24 @@
+import type { SmrtClassOptions } from '@happyvertical/smrt-core';
+import { getDatabase } from '@happyvertical/sql';
+import { type CalendarExpansionOptions, type CalendarParseOptions } from './icalendar';
+export interface CalendarSourceSyncOptions extends Omit<SmrtClassOptions, 'db'> {
+    db: NonNullable<Parameters<typeof getDatabase>[0]>;
+    source: string;
+    ics: string;
+    tenantId?: string | null;
+    parse?: CalendarParseOptions;
+    expansion?: Omit<CalendarExpansionOptions, keyof CalendarParseOptions>;
+}
+export interface CalendarSourceSyncResult {
+    created: number;
+    updated: number;
+    unchanged: number;
+    /** Missing feed entries are deliberately retained; sync never deletes by omission. */
+    retainedOnOmission: true;
+}
+/**
+ * Persist one already-fetched calendar feed. The caller owns fetch, retries and
+ * authorization; every write runs through one required database transaction. Feed omission never deletes an existing event.
+ */
+export declare function syncICalendarSource(options: CalendarSourceSyncOptions): Promise<CalendarSourceSyncResult>;
+//# sourceMappingURL=sync.d.ts.map

package/dist/calendar/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../src/calendar/sync.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAGjE,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAIjD,OAAO,EAEL,KAAK,wBAAwB,EAC7B,KAAK,oBAAoB,EAG1B,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,yBACf,SAAQ,IAAI,CAAC,gBAAgB,EAAE,IAAI,CAAC;IACpC,EAAE,EAAE,WAAW,CAAC,UAAU,CAAC,OAAO,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,SAAS,CAAC,EAAE,IAAI,CAAC,wBAAwB,EAAE,MAAM,oBAAoB,CAAC,CAAC;CACxE;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,sFAAsF;IACtF,kBAAkB,EAAE,IAAI,CAAC;CAC1B;AAsTD;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,EAAE,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC,CA4BnC"}

package/dist/index.d.ts

@@ -6,6 +6,10 @@
  * @packageDocumentation
  */
 import './__smrt-register__.js';
+export type { CalendarEventIdentity, CalendarEventInput, CalendarExpansionOptions, CalendarParseOptions, } from './calendar/icalendar';
+export { CalendarEventValidationError, expandICalendarEvents, parseICalendarEvents, } from './calendar/icalendar';
+export type { CalendarSourceSyncOptions, CalendarSourceSyncResult, } from './calendar/sync';
+export { syncICalendarSource } from './calendar/sync';
 export { EventAssetCollection } from './collections/EventAssetCollection';
 export { EventCollection } from './collections/EventCollection';
 export { EventParticipantCollection } from './collections/EventParticipantCollection';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,wBAAwB,CAAC;AAEhC,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,0CAA0C,CAAC;AACtF,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAE5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,YAAY,EACV,SAAS,EACT,uBAAuB,EACvB,aAAa,GACd,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,YAAY,EACZ,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAE3D,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,mBAAmB,GACpB,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,OAAO,wBAAwB,CAAC;AAEhC,YAAY,EACV,qBAAqB,EACrB,kBAAkB,EAClB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,4BAA4B,EAC5B,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAChE,OAAO,EAAE,0BAA0B,EAAE,MAAM,0CAA0C,CAAC;AACtF,OAAO,EAAE,qBAAqB,EAAE,MAAM,qCAAqC,CAAC;AAE5E,OAAO,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAC;AACxE,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACvC,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAEnD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,YAAY,EACV,SAAS,EACT,uBAAuB,EACvB,aAAa,GACd,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,YAAY,EACZ,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,wBAAwB,EACxB,WAAW,EACX,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAE3D,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,gBAAgB,EAChB,cAAc,EACd,oBAAoB,EACpB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,UAAU,EACV,eAAe,EACf,sBAAsB,EACtB,gBAAgB,EAChB,eAAe,EACf,mBAAmB,GACpB,MAAM,SAAS,CAAC"}