@remit/calendar-service 0.0.21 → 1.0.1

package/dist/task.d.ts

@@ -0,0 +1,33 @@
+import type { CalendarCollectionItem, CalendarTaskItem, ICalendarTaskRepository, PutCalendarTaskInput } from "@remit/data-ports";
+import ICAL from "ical.js";
+import { type CalendarResult } from "./errors.js";
+/** A task as a person describes it, before it is iCalendar. */
+export interface CalendarTaskFields {
+    summary: string;
+    description: string;
+    /** ISO 8601 with a zone offset, or `YYYY-MM-DD` when `allDay`. */
+    due: string;
+    allDay: boolean;
+    /** IANA zone the due time is anchored in. `""` anchors it in UTC. */
+    timeZone: string;
+    completed: boolean;
+}
+interface ParsedTask {
+    component: ICAL.Component;
+    todo: ICAL.Component;
+    uid: string;
+}
+/** Reads a VCALENDAR carrying exactly one VTODO with a UID and a DUE. */
+export declare const parseTaskCalendar: (icalData: string) => Promise<CalendarResult<ParsedTask>>;
+/** Builds the VCALENDAR text for a new task. */
+export declare const buildTaskCalendar: (fields: CalendarTaskFields, uid: string, now: Date) => CalendarResult<string>;
+/** Rewrites a stored task with a patch. */
+export declare const updateTaskCalendar: (icalData: string, patch: Partial<CalendarTaskFields>, collectionTimezone: string, now: Date) => Promise<CalendarResult<string>>;
+/** Turns one task resource into the row that stores it. */
+export declare const prepareCalendarTask: (collection: Pick<CalendarCollectionItem, "calendarId" | "timezone">, resourceName: string, icalData: string) => Promise<CalendarResult<PutCalendarTaskInput>>;
+/** Every task due in a window, across the collections given, in due order. */
+export declare const listTasksInWindow: (repository: Pick<ICalendarTaskRepository, "listByDueRange">, collections: readonly CalendarCollectionItem[], window: {
+    from: string;
+    to: string;
+}) => Promise<CalendarTaskItem[]>;
+export {};

package/dist/task.js

@@ -0,0 +1,153 @@
+import ICAL from "ical.js";
+import { CALENDAR_PRODID, readEventTime } from "./build.js";
+import { calendarFailure } from "./errors.js";
+import { computeEtag } from "./etag.js";
+import { readCalendarComponent, serializeCalendar } from "./parse.js";
+import { readString } from "./project.js";
+import { resolveTime, tzidOf } from "./time.js";
+/** Reads a VCALENDAR carrying exactly one VTODO with a UID and a DUE. */
+export const parseTaskCalendar = async (icalData) => {
+    const read = await readCalendarComponent(icalData);
+    if (!read.ok)
+        return read;
+    const component = read.value;
+    if (component.name !== "vcalendar") {
+        return calendarFailure("NotACalendar", "expected a VCALENDAR");
+    }
+    const todos = component.getAllSubcomponents("vtodo");
+    if (todos.length !== 1 || component.getAllSubcomponents("vevent").length) {
+        return calendarFailure("UnsupportedComponent", "a task resource holds exactly one VTODO and no VEVENT");
+    }
+    const todo = todos[0];
+    const uid = todo.getFirstPropertyValue("uid");
+    if (typeof uid !== "string" || uid === "") {
+        return calendarFailure("MissingUid", "the VTODO declares no UID");
+    }
+    if (!(todo.getFirstPropertyValue("due") instanceof ICAL.Time)) {
+        return calendarFailure("MissingDtStart", "the VTODO declares no DUE");
+    }
+    return { ok: true, value: { component, todo, uid } };
+};
+const setText = (todo, name, value) => {
+    todo.removeAllProperties(name);
+    if (value !== "")
+        todo.addPropertyWithValue(name, value);
+};
+const currentFields = (todo, collectionTimezone) => {
+    const due = todo.getFirstPropertyValue("due");
+    const tzid = tzidOf(todo.getFirstProperty("due"));
+    const resolved = due instanceof ICAL.Time
+        ? resolveTime(due, tzid, collectionTimezone)
+        : null;
+    return {
+        summary: readString(todo, "summary"),
+        description: readString(todo, "description"),
+        due: resolved
+            ? resolved.isDate
+                ? resolved.isoOffset.slice(0, 10)
+                : resolved.isoOffset
+            : "",
+        allDay: resolved?.isDate ?? false,
+        timeZone: tzid,
+        completed: readString(todo, "status").toUpperCase() === "COMPLETED",
+    };
+};
+/**
+ * Writes a patch onto a VTODO. The due fields are one fact between them, so
+ * touching any rewrites DUE from the values the task would then have.
+ */
+const applyTaskFields = (todo, patch, collectionTimezone, now) => {
+    if (patch.summary !== undefined)
+        setText(todo, "summary", patch.summary);
+    if (patch.description !== undefined) {
+        setText(todo, "description", patch.description);
+    }
+    if (patch.completed !== undefined) {
+        setText(todo, "status", patch.completed ? "COMPLETED" : "NEEDS-ACTION");
+        todo.removeAllProperties("completed");
+        if (patch.completed) {
+            todo.addPropertyWithValue("completed", ICAL.Time.fromJSDate(now, true));
+        }
+    }
+    const touchesDue = patch.due !== undefined ||
+        patch.allDay !== undefined ||
+        patch.timeZone !== undefined;
+    if (!touchesDue)
+        return { ok: true, value: null };
+    const current = todo.hasProperty("due")
+        ? currentFields(todo, collectionTimezone)
+        : { due: "", allDay: false, timeZone: "" };
+    const allDay = patch.allDay ?? current.allDay;
+    const timeZone = patch.timeZone ?? current.timeZone;
+    const due = readEventTime(patch.due ?? current.due, allDay, timeZone);
+    if (!due.ok)
+        return due;
+    todo.removeAllProperties("due");
+    const property = new ICAL.Property("due");
+    todo.addProperty(property);
+    property.setValue(due.value);
+    if (!due.value.isDate && timeZone !== "") {
+        property.setParameter("tzid", timeZone);
+    }
+    return { ok: true, value: null };
+};
+/** Builds the VCALENDAR text for a new task. */
+export const buildTaskCalendar = (fields, uid, now) => {
+    const calendar = new ICAL.Component("vcalendar");
+    calendar.addPropertyWithValue("version", "2.0");
+    calendar.addPropertyWithValue("prodid", CALENDAR_PRODID);
+    const todo = new ICAL.Component("vtodo");
+    calendar.addSubcomponent(todo);
+    todo.addPropertyWithValue("uid", uid);
+    todo.addPropertyWithValue("dtstamp", ICAL.Time.fromJSDate(now, true));
+    const applied = applyTaskFields(todo, fields, fields.timeZone, now);
+    if (!applied.ok)
+        return applied;
+    return { ok: true, value: serializeCalendar(calendar) };
+};
+/** Rewrites a stored task with a patch. */
+export const updateTaskCalendar = async (icalData, patch, collectionTimezone, now) => {
+    const parsed = await parseTaskCalendar(icalData);
+    if (!parsed.ok)
+        return parsed;
+    const { todo, component } = parsed.value;
+    const applied = applyTaskFields(todo, patch, collectionTimezone, now);
+    if (!applied.ok)
+        return applied;
+    todo.removeAllProperties("dtstamp");
+    todo.addPropertyWithValue("dtstamp", ICAL.Time.fromJSDate(now, true));
+    return { ok: true, value: serializeCalendar(component) };
+};
+/** Turns one task resource into the row that stores it. */
+export const prepareCalendarTask = async (collection, resourceName, icalData) => {
+    const parsed = await parseTaskCalendar(icalData);
+    if (!parsed.ok)
+        return parsed;
+    const { todo, uid } = parsed.value;
+    const fields = currentFields(todo, collection.timezone);
+    const due = resolveTime(todo.getFirstPropertyValue("due"), tzidOf(todo.getFirstProperty("due")), collection.timezone);
+    return {
+        ok: true,
+        value: {
+            calendarId: collection.calendarId,
+            resourceName,
+            icalUid: uid,
+            icalData,
+            etag: computeEtag(icalData),
+            summary: fields.summary,
+            description: fields.description,
+            due: due.isoOffset,
+            dueAt: due.isoUtc,
+            allDay: due.isDate,
+            completed: fields.completed,
+        },
+    };
+};
+/** Every task due in a window, across the collections given, in due order. */
+export const listTasksInWindow = async (repository, collections, window) => {
+    const tasks = [];
+    for (const collection of collections) {
+        tasks.push(...(await repository.listByDueRange(collection.calendarId, window.from, window.to)));
+    }
+    return tasks.sort((left, right) => left.dueAt.localeCompare(right.dueAt));
+};

package/dist/window.d.ts

@@ -1,3 +1,4 @@
+import type { CalendarParticipation as CalendarParticipationValue } from "@remit/api-openapi-types";
 import type { CalendarCollectionItem, CalendarObjectItem, ICalendarEventIndexRepository, ICalendarObjectRepository } from "@remit/data-ports";
 /**
  * How far before the window occurrences are read, so one that started earlier
@@ -30,6 +31,8 @@ export interface CalendarInstance {
     zoneCertainty: CalendarObjectItem["zoneCertainty"];
     etag: string;
     hasRecurrence: boolean;
+    /** Where the reader stands on this occurrence, read from the bytes it came from. */
+    participation: CalendarParticipationValue;
 }
 export interface CalendarWindowRepositories {
     calendarObject: Pick<ICalendarObjectRepository, "find" | "listIncompleteExpansions">;
@@ -49,7 +52,7 @@ export interface CalendarWindow {
  * written to serve the read. A series is served from one source or the other,
  * never merged from both, so an occurrence cannot appear twice.
  */
-export declare const listCalendarInstances: (repositories: CalendarWindowRepositories, collections: CalendarCollectionItem[], window: CalendarWindow) => Promise<CalendarInstance[]>;
+export declare const listCalendarInstances: (repositories: CalendarWindowRepositories, collections: CalendarCollectionItem[], window: CalendarWindow, self: ReadonlySet<string>) => Promise<CalendarInstance[]>;
 /**
  * The occurrences of one resource in a window, read from that resource alone:
  * its own index rows where the index reaches the window, and a live expansion
@@ -57,7 +60,7 @@ export declare const listCalendarInstances: (repositories: CalendarWindowReposit
  */
 export declare const listObjectInstances: (repositories: {
     calendarEventIndex: Pick<ICalendarEventIndexRepository, "listForObject">;
-}, collection: CalendarCollectionItem, object: CalendarObjectItem, window: CalendarWindow) => Promise<CalendarInstance[]>;
+}, collection: CalendarCollectionItem, object: CalendarObjectItem, window: CalendarWindow, self: ReadonlySet<string>) => Promise<CalendarInstance[]>;
 /** A stretch of time somebody is busy in, as instants. */
 export interface BusySpan {
     startMs: number;
@@ -65,8 +68,8 @@ export interface BusySpan {
 }
 /**
  * Whether an occurrence consumes free/busy time. A cancelled event is not
- * something to work around, and one marked TRANSP:TRANSPARENT was written
- * precisely to say so.
+ * something to work around, one the reader declined is not one they attend,
+ * and one marked TRANSP:TRANSPARENT was written precisely to say so.
  */
 export declare const isBusy: (instance: CalendarInstance) => boolean;
 /**
@@ -82,4 +85,4 @@ export declare const mergeBusySpans: (spans: BusySpan[]) => BusySpan[];
  * clipped to the window so a span never claims time outside what was asked
  * for.
  */
-export declare const listBusySpans: (repositories: CalendarWindowRepositories, collections: CalendarCollectionItem[], window: CalendarWindow) => Promise<BusySpan[]>;
+export declare const listBusySpans: (repositories: CalendarWindowRepositories, collections: CalendarCollectionItem[], window: CalendarWindow, self: ReadonlySet<string>) => Promise<BusySpan[]>;

package/dist/window.js

@@ -1,6 +1,7 @@
-import { CalendarEventStatus, CalendarTransparency } from "@remit/domain-enums";
+import { CalendarEventStatus, CalendarParticipation, CalendarTransparency, } from "@remit/domain-enums";
 import { expandCalendarWindow } from "./expand.js";
 import { parseCalendar } from "./parse.js";
+import { participationAtSlot } from "./participation.js";
 import { toOffsetIso, toUtcIso } from "./time.js";
 /**
  * How far before the window occurrences are read, so one that started earlier
@@ -15,7 +16,14 @@ import { toOffsetIso, toUtcIso } from "./time.js";
  */
 export const CALENDAR_WINDOW_LOOKBACK_DAYS = 31;
 const LOOKBACK_MS = CALENDAR_WINDOW_LOOKBACK_DAYS * 24 * 60 * 60 * 1000;
-const instanceOf = (collection, object, occurrence) => ({
+const parsedOrThrow = async (object) => {
+    const parsed = await parseCalendar(object.icalData);
+    if (!parsed.ok) {
+        throw new Error(`stored calendar object ${object.calendarObjectId} no longer parses: ${parsed.error.message}`);
+    }
+    return parsed.value;
+};
+const instanceOf = (collection, object, parsed, self, occurrence) => ({
     calendarId: collection.calendarId,
     calendarObjectId: object.calendarObjectId,
     recurrenceId: occurrence.recurrenceId,
@@ -31,6 +39,7 @@ const instanceOf = (collection, object, occurrence) => ({
     zoneCertainty: object.zoneCertainty,
     etag: object.etag,
     hasRecurrence: object.hasRecurrence,
+    participation: participationAtSlot(parsed, collection.timezone, occurrence.recurrenceId, self),
 });
 /**
  * Every occurrence in a window, across the collections given.
@@ -40,7 +49,7 @@ const instanceOf = (collection, object, occurrence) => ({
  * written to serve the read. A series is served from one source or the other,
  * never merged from both, so an occurrence cannot appear twice.
  */
-export const listCalendarInstances = async (repositories, collections, window) => {
+export const listCalendarInstances = async (repositories, collections, window, self) => {
     const fromMs = Date.parse(window.from);
     const toMs = Date.parse(window.to);
     const lookbackFrom = toUtcIso(fromMs - LOOKBACK_MS);
@@ -52,28 +61,30 @@ export const listCalendarInstances = async (repositories, collections, window) =
         const live = await repositories.calendarObject.listIncompleteExpansions(collection.calendarId, window.to);
         const liveIds = new Set(live.map((object) => object.calendarObjectId));
         const rows = await repositories.calendarEventIndex.listByStartRange(collection.calendarId, lookbackFrom, window.to);
-        // One read per resource that actually appears in the window, cached across
-        // its own occurrences.
+        // One read and one parse per resource that actually appears in the window,
+        // cached across its own occurrences. The parse is what the reader's own
+        // answer is read from.
         const byId = new Map();
         for (const row of rows) {
             if (liveIds.has(row.calendarObjectId))
                 continue;
             if (!byId.has(row.calendarObjectId)) {
-                byId.set(row.calendarObjectId, await repositories.calendarObject.find(collection.calendarId, row.calendarObjectId));
+                const object = await repositories.calendarObject.find(collection.calendarId, row.calendarObjectId);
+                byId.set(row.calendarObjectId, object ? { object, parsed: await parsedOrThrow(object) } : null);
             }
-            const object = byId.get(row.calendarObjectId);
-            if (!object)
+            const read = byId.get(row.calendarObjectId);
+            if (!read)
                 continue;
-            instances.push(instanceOf(collection, object, row));
+            instances.push(instanceOf(collection, read.object, read.parsed, self, row));
         }
         for (const object of live) {
-            const parsed = await parseCalendar(object.icalData);
-            if (!parsed.ok) {
-                throw new Error(`stored calendar object ${object.calendarObjectId} no longer parses: ${parsed.error.message}`);
-            }
-            const occurrences = expandCalendarWindow(parsed.value, collection.timezone, { fromMs: fromMs - LOOKBACK_MS, toMs });
+            const parsed = await parsedOrThrow(object);
+            const occurrences = expandCalendarWindow(parsed, collection.timezone, {
+                fromMs: fromMs - LOOKBACK_MS,
+                toMs,
+            });
             for (const occurrence of occurrences) {
-                instances.push(instanceOf(collection, object, occurrence));
+                instances.push(instanceOf(collection, object, parsed, self, occurrence));
             }
         }
     }
@@ -86,28 +97,22 @@ export const listCalendarInstances = async (repositories, collections, window) =
  * its own index rows where the index reaches the window, and a live expansion
  * of it where it does not.
  */
-export const listObjectInstances = async (repositories, collection, object, window) => {
+export const listObjectInstances = async (repositories, collection, object, window, self) => {
     const fromMs = Date.parse(window.from);
     const toMs = Date.parse(window.to);
+    const parsed = await parsedOrThrow(object);
     const indexReaches = object.expandedThrough === "" || object.expandedThrough >= window.to;
     const occurrences = indexReaches
         ? await repositories.calendarEventIndex.listForObject(collection.calendarId, object.calendarObjectId)
-        : await expandObject(object, collection.timezone, fromMs, toMs);
+        : expandCalendarWindow(parsed, collection.timezone, {
+            fromMs: fromMs - LOOKBACK_MS,
+            toMs,
+        });
     return occurrences
-        .map((occurrence) => instanceOf(collection, object, occurrence))
+        .map((occurrence) => instanceOf(collection, object, parsed, self, occurrence))
         .filter((instance) => overlapsWindow(instance, fromMs, toMs))
         .sort((left, right) => left.startAt.localeCompare(right.startAt));
 };
-const expandObject = async (object, timezone, fromMs, toMs) => {
-    const parsed = await parseCalendar(object.icalData);
-    if (!parsed.ok) {
-        throw new Error(`stored calendar object ${object.calendarObjectId} no longer parses: ${parsed.error.message}`);
-    }
-    return expandCalendarWindow(parsed.value, timezone, {
-        fromMs: fromMs - LOOKBACK_MS,
-        toMs,
-    });
-};
 const overlapsWindow = (instance, fromMs, toMs) => {
     const startMs = Date.parse(instance.startAt);
     if (startMs >= toMs)
@@ -118,11 +123,12 @@ const overlapsWindow = (instance, fromMs, toMs) => {
 };
 /**
  * Whether an occurrence consumes free/busy time. A cancelled event is not
- * something to work around, and one marked TRANSP:TRANSPARENT was written
- * precisely to say so.
+ * something to work around, one the reader declined is not one they attend,
+ * and one marked TRANSP:TRANSPARENT was written precisely to say so.
  */
 export const isBusy = (instance) => instance.transparency === CalendarTransparency.Opaque &&
-    instance.status !== CalendarEventStatus.Cancelled;
+    instance.status !== CalendarEventStatus.Cancelled &&
+    instance.participation !== CalendarParticipation.Declined;
 /**
  * Collapses overlapping and touching spans into the stretches they cover.
  *
@@ -150,10 +156,10 @@ export const mergeBusySpans = (spans) => {
  * clipped to the window so a span never claims time outside what was asked
  * for.
  */
-export const listBusySpans = async (repositories, collections, window) => {
+export const listBusySpans = async (repositories, collections, window, self) => {
     const fromMs = Date.parse(window.from);
     const toMs = Date.parse(window.to);
-    const instances = await listCalendarInstances(repositories, collections, window);
+    const instances = await listCalendarInstances(repositories, collections, window, self);
     return mergeBusySpans(instances.filter(isBusy).map((instance) => ({
         startMs: Math.max(Date.parse(instance.startAt), fromMs),
         endMs: Math.min(Date.parse(instance.endAt), toMs),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@remit/calendar-service",
-	"version": "0.0.21",
+	"version": "1.0.1",
 	"description": "iCalendar (RFC 5545) parsing, projection and recurrence expansion over the calendar store",
 	"type": "module",
 	"main": "dist/index.js",