@sockethub/platform-caldav 1.0.0-beta.5 → 1.0.0-beta.6

package/README.md

@@ -133,7 +133,10 @@ The collection contains calendar objects such as:
 ```
 
 Each returned item contains its resource `id`, `uid`, `etag`, and
-`updateSupported`. Keep the ETag for later update or delete requests. Use date
+`updateSupported`, plus `created` and `lastModified` (UTC) when the resource
+records them; `lastModified` falls back to `DTSTAMP`. These two are output
+only and ignored on create and update. Keep the ETag for later update or
+delete requests. Use date
 ranges for large calendars; responses larger than 10 MiB are rejected.
 
 ### Sync changes
@@ -185,6 +188,15 @@ When `truncated` is `true`, the server limited the result. The returned token
 covers exactly the changes delivered, so store it and sync again until
 `truncated` is `false`.
 
+To track changes without downloading a calendar's history, start from the
+current token instead of an initial sync. Send `"object": { "tokenOnly": true }`
+to get the calendar's current `syncToken` with empty `items` and `removed`,
+then `query` the date range you need, then `sync` with the token on later
+passes. Read the token before the `query`, so nothing changed in between is
+missed. Later syncs still report changes to any item in the calendar,
+including old ones. A server that exposes no token returns
+`caldav:sync-unsupported`.
+
 Calendar resources that hold neither an event nor a task, such as journals, are
 left out of `items`.
 
@@ -299,8 +311,12 @@ Update sends the complete event or task returned by `query`, including `id`,
 `uid`, and `etag`. Increment `sequence` when changing scheduling information.
 An update is rejected when `updateSupported` is false, which protects recurrence
 exceptions, exclusion dates, and multi-component resources from being lost.
-Properties outside Sockethub's item model, such as `CATEGORIES` and `X-`
-properties, are not preserved when an otherwise supported item is updated.
+Update changes only the stored properties whose fields differ from the stored
+item, plus `DTSTAMP` and `LAST-MODIFIED`. Everything else stays as it was,
+including `CATEGORIES`, `X-` properties, `CREATED`, `VTIMEZONE` blocks, and
+parameters on unchanged attendees and alarms. A field left out of the update
+removes its property. A changed field is written from the item model, so
+parameters the model does not carry are dropped from that property.
 
 ```json
 {

package/dist/dav.d.ts

@@ -15,7 +15,12 @@ export declare class CalDavClient extends DavClient {
      * task in the calendar; with one, lists only what changed since then.
      */
     sync(calendar: CalendarDescription, syncToken?: string): Promise<CalendarSyncResult>;
-    update(id: string, etag: string, body: string): Promise<{
+    /**
+     * Replace a resource if its ETag still matches. `body` is either the new
+     * resource or a function that builds it from the stored one, so changes
+     * can be applied without losing what the item model does not carry.
+     */
+    update(id: string, etag: string, body: string | ((stored: string) => string)): Promise<{
         id: string;
         etag?: string;
     }>;

package/dist/ical.d.ts

@@ -1,7 +1,14 @@
 import type { CalendarItem, CalendarObjectInput } from "./types.js";
 /** Fold one iCalendar content line at 75 UTF-8 octets (74 after continuation). */
 export declare function foldLine(line: string): string;
-export declare function buildICalendar(input: CalendarObjectInput, now?: Date): {
+/**
+ * Serialize an item as a single-component iCalendar resource. `created`
+ * stamps `CREATED` with `now`; pass it only for a new resource, so an update
+ * does not move the creation time.
+ */
+export declare function buildICalendar(input: CalendarObjectInput, now?: Date, { created }?: {
+    created?: boolean;
+}): {
     uid: string;
     body: string;
 };

package/dist/index.d.ts

@@ -39,6 +39,11 @@ export default class CalDav implements PlatformInterface {
      * the result being complete. `caldav:sync-token-invalid` means start
      * over without a token; `caldav:sync-unsupported` means fall back to
      * `query`.
+     *
+     * With `object.tokenOnly: true`, returns the calendar's current token
+     * and no items, so a client can start tracking changes without
+     * downloading history: get the token first, then `query` the range it
+     * needs, then `sync` with the token on later passes.
      */
     sync(job: ActivityStream, credentials: CalDavCredentials, done: PlatformCallback): void;
     update(job: ActivityStream, credentials: CalDavCredentials, done: PlatformCallback): void;

package/dist/index.js

@@ -66381,6 +66381,35 @@ class DavClient {
     }
     return this.readMultistatus(response);
   }
+  async currentSyncToken(collection) {
+    const response = await this.request(collection, {
+      method: "PROPFIND",
+      headers: {
+        depth: "0",
+        "content-type": "application/xml; charset=utf-8"
+      },
+      body: `<?xml version="1.0" encoding="utf-8"?>
+<d:propfind xmlns:d="DAV:"><d:prop><d:sync-token/></d:prop></d:propfind>`
+    });
+    if (response.status === 404)
+      return rejectDavResponse(response, `${this.errorPrefix}:not-found`);
+    if (response.status !== 207) {
+      await response.body?.cancel().catch(() => {});
+      throw new DavFailure(`${this.errorPrefix}:invalid-response`);
+    }
+    let responses;
+    try {
+      responses = asArray(parseDavXml(await response.text(), {
+        parseTagValue: false
+      }).multistatus?.response);
+    } catch {
+      throw new DavFailure(`${this.errorPrefix}:invalid-response`);
+    }
+    const token = successfulProps(responses[0] ?? {})["sync-token"];
+    if (typeof token !== "string" || token.trim() === "")
+      throw new DavFailure(`${this.errorPrefix}:sync-unsupported`);
+    return token.trim();
+  }
   async syncCollection(collection, prop, syncToken, namespaces = "") {
     const response = await this.request(collection, {
       method: "REPORT",
@@ -66819,7 +66848,7 @@ var ActivityStreamSchema = {
 var package_default = {
   name: "@sockethub/schemas",
   description: "JSON schema files for validating Sockethub Activity Streams",
-  version: "3.0.0-beta.5",
+  version: "3.0.0-beta.6",
   type: "module",
   private: false,
   author: "Nick Jennings <nick@silverbucket.net>",
@@ -66889,7 +66918,7 @@ var package_default = {
     "ajv-formats": "^2.1.1",
     "ajv-formats-draft2019": "^1.6.1"
   },
-  gitHead: "cc4ffdd9714ebbd8372a88c4f2d795974e04029e",
+  gitHead: "604f3da8850a19a4fd5f5e5dcec10bf283e9085e",
   types: "./dist/index.d.ts"
 };
 
@@ -68036,7 +68065,7 @@ function timeZoneRange(input, fallbackYear) {
   const last = years.length ? Math.max(...years) : fallbackYear;
   return [first - 1, Math.max(last + 1, first + 30)];
 }
-function buildICalendar(input, now = new Date) {
+function buildICalendar(input, now = new Date, { created = false } = {}) {
   const uid = input.uid ?? `${randomUUID()}@sockethub`;
   if (/[\r\n%/\\]/.test(uid))
     throw new Error("invalid uid");
@@ -68055,6 +68084,8 @@ function buildICalendar(input, now = new Date) {
     `BEGIN:${component}`,
     `UID:${escapeText(uid)}`,
     `DTSTAMP:${utcDateTime(now.toISOString(), "now")}`,
+    ...created ? [`CREATED:${utcDateTime(now.toISOString(), "now")}`] : [],
+    `LAST-MODIFIED:${utcDateTime(now.toISOString(), "now")}`,
     `SUMMARY:${escapeText(input.name)}`
   ];
   if (input.content)
@@ -68101,6 +68132,13 @@ function parseDate(value) {
     return `${value.slice(0, 4)}-${value.slice(4, 6)}-${value.slice(6, 8)}T${value.slice(9, 11)}:${value.slice(11, 13)}:${value.slice(13, 15)}`;
   return value;
 }
+function utcTimestamp(value) {
+  if (!value || !/^\d{8}T\d{6}Z$/.test(value))
+    return;
+  const iso = parseDate(value);
+  const parsed = new Date(iso);
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString().replace(".000Z", "Z") === iso ? iso : undefined;
+}
 var STATUSES = {
   event: ["tentative", "confirmed", "cancelled"],
   task: ["needs-action", "in-process", "completed", "cancelled"]
@@ -68176,6 +68214,13 @@ function parseICalendar(body, id, etag) {
     name: unescapeText(summary),
     updateSupported: isUpdateSupported(body)
   };
+  const created = utcTimestamp(first("CREATED")?.value);
+  const hasMethod = lines.slice(0, begin).some((line) => /^METHOD[;:]/i.test(line));
+  const lastModified = utcTimestamp(first("LAST-MODIFIED")?.value) ?? (hasMethod ? undefined : utcTimestamp(first("DTSTAMP")?.value));
+  if (created)
+    item.created = created;
+  if (lastModified)
+    item.lastModified = lastModified;
   if (first("DESCRIPTION"))
     item.content = unescapeText(first("DESCRIPTION")?.value ?? "");
   if (first("LOCATION"))
@@ -68460,7 +68505,8 @@ class CalDavClient extends DavClient {
       return rejectDavResponse(current, "caldav:not-found");
     if (!current.ok)
       return rejectDavResponse(current, "caldav:update-failed");
-    if (!isUpdateSupported(await current.text()))
+    const stored = await current.text();
+    if (!isUpdateSupported(stored))
       throw new CalDavFailure("caldav:unsupported-update");
     const response = await this.request(resource, {
       method: "PUT",
@@ -68468,7 +68514,7 @@ class CalDavClient extends DavClient {
         "content-type": "text/calendar; charset=utf-8",
         "if-match": etag
       },
-      body
+      body: typeof body === "function" ? body(stored) : body
     });
     if (response.status === 412)
       return rejectDavResponse(response, "caldav:conflict");
@@ -68678,11 +68724,126 @@ END:VCALENDAR\r
     skipped
   };
 }
+
+// src/patch.ts
+var GROUPS = [
+  { fields: ["name"], names: ["SUMMARY"] },
+  { fields: ["content"], names: ["DESCRIPTION"] },
+  { fields: ["location"], names: ["LOCATION"] },
+  { fields: ["url"], names: ["URL"] },
+  {
+    fields: ["startTime", "endTime", "due", "allDay", "timeZone"],
+    names: ["DTSTART", "DTEND", "DUE"]
+  },
+  { fields: ["status"], names: ["STATUS"] },
+  { fields: ["completedTime"], names: ["COMPLETED"] },
+  { fields: ["percentComplete"], names: ["PERCENT-COMPLETE"] },
+  { fields: ["sequence"], names: ["SEQUENCE"] },
+  { fields: ["recurrence"], names: ["RRULE"] },
+  { fields: ["organizer"], names: ["ORGANIZER"] },
+  { fields: ["attendees"], names: ["ATTENDEE"] },
+  { fields: ["attachments"], names: ["ATTACH"] },
+  { fields: ["reminders"], names: ["VALARM"] },
+  { fields: [], names: ["DTSTAMP", "LAST-MODIFIED"] }
+];
+function logicalLines(body) {
+  const lines = [];
+  for (const line of body.split(/\r?\n/)) {
+    if (/^[ \t]/.test(line) && lines.length)
+      lines[lines.length - 1].push(line);
+    else
+      lines.push([line]);
+  }
+  while (lines.length && lines[lines.length - 1].join("") === "")
+    lines.pop();
+  return lines;
+}
+var unfolded = (raw) => raw.map((line, index) => index ? line.slice(1) : line).join("");
+var propertyName = (raw) => (unfolded(raw).match(/^[^;:]*/)?.[0] ?? "").toUpperCase();
+function componentBounds(lines) {
+  const begin = lines.findIndex((raw) => /^BEGIN:(?:VEVENT|VTODO)$/.test(unfolded(raw)));
+  if (begin === -1)
+    return;
+  const name = unfolded(lines[begin]).slice("BEGIN:".length);
+  const end = lines.findIndex((raw, index) => index > begin && unfolded(raw) === `END:${name}`);
+  return end === -1 ? undefined : { begin, end, name };
+}
+function units(lines) {
+  const result = [];
+  let alarm;
+  for (const raw of lines) {
+    const text = unfolded(raw);
+    if (alarm) {
+      alarm.push(...raw);
+      if (text === "END:VALARM") {
+        result.push({ name: "VALARM", raw: alarm });
+        alarm = undefined;
+      }
+    } else if (text === "BEGIN:VALARM")
+      alarm = [...raw];
+    else
+      result.push({ name: propertyName(raw), raw });
+  }
+  if (alarm)
+    result.push({ name: "", raw: alarm });
+  return result;
+}
+function canonical(value) {
+  return JSON.stringify(value, (_key, entry) => entry && typeof entry === "object" && !Array.isArray(entry) ? Object.fromEntries(Object.keys(entry).sort().map((key) => [key, entry[key]])) : entry);
+}
+function sameField(current, next, field) {
+  if (field === "allDay")
+    return current.allDay === true === (next.allDay === true);
+  return canonical(current[field]) === canonical(next[field]);
+}
+function patchICalendar(stored, item, generated) {
+  const current = parseICalendar(stored, "");
+  if (current.type !== item.type)
+    return { uid: item.uid ?? current.uid, body: generated };
+  const lines = logicalLines(stored);
+  const bounds = componentBounds(lines);
+  const fresh = logicalLines(generated);
+  const freshBounds = componentBounds(fresh);
+  if (!bounds || !freshBounds)
+    throw new Error("invalid calendar data");
+  const freshUnits = units(fresh.slice(freshBounds.begin + 1, freshBounds.end));
+  const replaced = new Set;
+  for (const group of GROUPS)
+    if (!group.fields.length || !group.fields.every((field) => sameField(current, item, field)))
+      for (const name of group.names)
+        replaced.add(name);
+  const freshNames = new Set(freshUnits.map((unit) => unit.name));
+  if (replaced.has("DTSTART") && (freshNames.has("DTEND") || freshNames.has("DUE")))
+    replaced.add("DURATION");
+  const kept = [];
+  let insertAt;
+  for (const unit of units(lines.slice(bounds.begin + 1, bounds.end))) {
+    if (replaced.has(unit.name))
+      insertAt ??= kept.length;
+    else
+      kept.push(unit);
+  }
+  const added = freshUnits.filter((unit) => replaced.has(unit.name));
+  kept.splice(insertAt ?? kept.length, 0, ...added);
+  const zone = item.timeZone;
+  const freshZone = fresh.findIndex((raw) => unfolded(raw) === "BEGIN:VTIMEZONE");
+  const zones = zone && replaced.has("DTSTART") && freshZone !== -1 && freshZone < freshBounds.begin && !lines.slice(0, bounds.begin).concat(lines.slice(bounds.end + 1)).some((raw) => unfolded(raw) === `TZID:${zone}`) ? fresh.slice(freshZone, freshBounds.begin) : [];
+  const output = [
+    ...lines.slice(0, bounds.begin),
+    ...zones,
+    lines[bounds.begin],
+    ...kept.map((unit) => unit.raw),
+    ...lines.slice(bounds.end)
+  ].flat();
+  return { uid: current.uid, body: `${output.join(`\r
+`)}\r
+` };
+}
 // package.json
 var package_default2 = {
   name: "@sockethub/platform-caldav",
   description: "A Sockethub platform for synchronizing CalDAV calendars, events, and tasks",
-  version: "1.0.0-beta.5",
+  version: "1.0.0-beta.6",
   type: "module",
   private: false,
   license: "LGPL-3.0+",
@@ -68716,16 +68877,16 @@ var package_default2 = {
     test: "bun test src/"
   },
   dependencies: {
-    "@sockethub/dav": "^1.0.0-beta.5",
-    "@sockethub/schemas": "^3.0.0-beta.5",
-    "@sockethub/util": "^1.0.0-beta.5",
+    "@sockethub/dav": "^1.0.0-beta.6",
+    "@sockethub/schemas": "^3.0.0-beta.6",
+    "@sockethub/util": "^1.0.0-beta.6",
     undici: "^7.30.0"
   },
   devDependencies: {
     "@types/bun": "latest"
   },
   peerDependencies: {
-    "@sockethub/server": "^5.0.0-beta.5"
+    "@sockethub/server": "^5.0.0-beta.6"
   },
   peerDependenciesMeta: {
     "@sockethub/server": {
@@ -68733,7 +68894,7 @@ var package_default2 = {
     }
   },
   types: "./dist/index.d.ts",
-  gitHead: "cc4ffdd9714ebbd8372a88c4f2d795974e04029e"
+  gitHead: "604f3da8850a19a4fd5f5e5dcec10bf283e9085e"
 };
 
 // src/schema.ts
@@ -68863,7 +69024,9 @@ var shared = {
   attendees: { type: "array", maxItems: 1000, items: person },
   reminders: { type: "array", maxItems: 100, items: reminder },
   attachments: { type: "array", maxItems: 100, items: attachment },
-  updateSupported: { type: "boolean" }
+  updateSupported: { type: "boolean" },
+  created: { type: "string", format: "date-time" },
+  lastModified: { type: "string", format: "date-time" }
 };
 var eventObject = {
   type: "object",
@@ -68934,7 +69097,8 @@ var syncToken = { type: "string", minLength: 1, maxLength: 4096 };
 var syncObject = {
   type: "object",
   additionalProperties: false,
-  properties: { syncToken }
+  properties: { syncToken, tokenOnly: { const: true } },
+  not: { required: ["syncToken", "tokenOnly"] }
 };
 var calendarItem2 = { oneOf: [eventObject, taskObject] };
 var mutationObject = {
@@ -68977,7 +69141,8 @@ var PlatformCalDavSchema = {
           taskObject,
           deleteObject,
           queryObject,
-          { ...syncObject, required: ["syncToken"] }
+          { ...syncObject, required: ["syncToken"] },
+          { ...syncObject, required: ["tokenOnly"] }
         ]
       }
     }
@@ -69286,7 +69451,9 @@ class CalDav {
       if (!target.components.includes(input.type)) {
         throw new CalDavFailure("caldav:unsupported-component");
       }
-      const calendarData = buildICalendar(input);
+      const calendarData = buildICalendar(input, new Date, {
+        created: true
+      });
       const created = await client.create(target, calendarData.uid, calendarData.body);
       done(null, {
         "@context": CONTEXT,
@@ -69317,7 +69484,12 @@ class CalDav {
   sync(job, credentials, done) {
     const client = this.client(credentials);
     const input = job.object ?? {};
-    this.calendar(client, credentials, job.target?.id ?? "").then((calendar) => client.sync(calendar, input.syncToken)).then((result) => done(null, {
+    this.calendar(client, credentials, job.target?.id ?? "").then((calendar) => input.tokenOnly ? client.currentSyncToken(new URL(calendar.id)).then((syncToken) => ({
+      items: [],
+      removed: [],
+      syncToken,
+      truncated: false
+    })) : client.sync(calendar, input.syncToken)).then((result) => done(null, {
       "@context": CONTEXT,
       ...job.id ? { id: job.id } : {},
       type: "collection",
@@ -69332,7 +69504,12 @@ class CalDav {
     this.calendar(client, credentials, job.target?.id ?? "").then((calendar) => {
       this.assertResource(calendar.id, input.id ?? "");
       const generated = buildICalendar(input);
-      return client.update(input.id ?? "", input.etag ?? "", generated.body).then((updated) => ({ updated, uid: generated.uid }));
+      let uid = generated.uid;
+      return client.update(input.id ?? "", input.etag ?? "", (stored) => {
+        const patched = patchICalendar(stored, input, generated.body);
+        uid = patched.uid;
+        return patched.body;
+      }).then((updated) => ({ updated, uid }));
     }).then(({ updated, uid }) => done(null, this.mutationResponse(job, "update", updated.id, input.type, uid, updated.etag))).catch((error) => this.fail(job, error, done, credentials)).finally(() => client.close().catch(() => {}));
   }
   delete(job, credentials, done) {
@@ -69461,4 +69638,4 @@ export {
   foldLine
 };
 
-//# debugId=16184EE35BE0342464756E2164756E21
+//# debugId=0BA1D0264BEB87B464756E2164756E21