@sockethub/platform-carddav 1.0.0-beta.4 → 1.0.0-beta.6

package/README.md

@@ -14,7 +14,7 @@ through the standard Sockethub credentials flow.
 
 ## Discovery cache
 
-Each `query`, `create`, `update`, and `delete` needs the account's address book list to
+Each `query`, `sync`, `create`, `update`, and `delete` needs the account's address book list to
 check the target. The platform caches that discovery result in memory for
 `packageConfig.discoveryCacheTtlMs` (default `300000`, 5 minutes; `0`
 disables the cache). Entries are keyed by an HMAC of the protocol, service URL,
@@ -52,6 +52,8 @@ that endpoint.
 
 - `fetch`: discover address books.
 - `query`: list or search contacts.
+- `sync`: report what changed in one address book since a sync token
+  (RFC 6578 WebDAV Sync).
 - `create`: create a vCard with collision protection.
 - `update`: update a vCard only when its ETag still matches.
 - `delete`: delete a vCard only when its ETag still matches.
@@ -96,6 +98,42 @@ Use `sc.contextFor("carddav")` as the request context.
 }
 ```
 
+### Sync changes
+
+`sync` reports changes without listing the whole address book each time. Send
+it without an `object` for the initial sync, which returns every contact and a
+`syncToken`:
+
+```json
+{
+  "type": "sync",
+  "actor": { "id": "carddav:alice", "type": "person" },
+  "target": {
+    "id": "https://contacts.example/addressbooks/alice/personal/",
+    "type": "addressBook"
+  }
+}
+```
+
+The response is a collection with `items` (contacts in the same shape as
+`query` results), `removed` (ids of contacts deleted since the token),
+`syncToken`, and `truncated`. Store the token as an opaque string per address
+book and send it back as `"object": { "syncToken": "..." }` to receive only
+what changed since then. When `truncated` is `true`, store the new token and
+sync again until it is `false`.
+
+Send `"object": { "tokenOnly": true }` to get the address book's current
+`syncToken` with empty `items` and `removed`, without listing every contact.
+Read it before loading the contacts you need, then sync with it later. A
+server that exposes no token returns `carddav:sync-unsupported`.
+
+On `carddav:sync-token-invalid`, drop the stored token and sync again without
+one. On `carddav:sync-unsupported`, the server does not offer WebDAV Sync; fall
+back to `query`. Other sync errors are `carddav:sync-failed`. A server that
+rejects a token without a `DAV:` precondition (a 400, 409, or 412) is
+reported as `carddav:sync-token-invalid`, so a retry without a token reports
+the real cause.
+
 ### Create a contact
 
 ```json
@@ -138,4 +176,5 @@ array removes them.
 The initial implementation reads vCard 3.0 and 4.0 and writes vCard 4.0. Stable
 errors use the `carddav:` prefix, including `authentication-failed`,
 `unsupported-authentication`, `invalid-address-book`, `invalid-resource`,
-`conflict`, `not-found`, and `unsupported-update`.
+`conflict`, `not-found`, `unsupported-update`, `sync-token-invalid`,
+`sync-unsupported`, and `sync-failed`.

package/dist/dav.d.ts

@@ -1,11 +1,16 @@
 import { type DavAuthentication, DavClient, DavFailure, type DavNetworkOptions } from "@sockethub/dav";
-import type { AddressBookDescription, Contact, ContactInput, ContactQuery } from "./types.js";
+import type { AddressBookDescription, Contact, ContactInput, ContactQuery, ContactSyncResult } from "./types.js";
 export { DavFailure as CardDavFailure };
 export declare class CardDavClient extends DavClient {
     constructor(url: string, authentication: DavAuthentication, timeoutMs?: number, networkOptions?: DavNetworkOptions);
     discoverAddressBooks(): Promise<AddressBookDescription[]>;
     private discoverFrom;
     query(book: AddressBookDescription, query?: ContactQuery): Promise<Contact[]>;
+    /**
+     * Incremental sync (RFC 6578). Without `syncToken`, lists every contact
+     * in the address book; with one, lists only what changed since then.
+     */
+    sync(book: AddressBookDescription, syncToken?: string): Promise<ContactSyncResult>;
     create(book: AddressBookDescription, input: ContactInput): Promise<{
         id: string;
         uid: string;

package/dist/index.d.ts

@@ -12,6 +12,21 @@ export default class CardDav implements PlatformInterface {
     cleanup(done: PlatformCallback): void;
     fetch(job: ActivityStream, credentials: CardDavCredentials, done: PlatformCallback): void;
     query(job: ActivityStream, credentials: CardDavCredentials, done: PlatformCallback): void;
+    /**
+     * Incremental address book sync (RFC 6578 WebDAV Sync). Without
+     * `object.syncToken`, returns every contact plus a token; with one,
+     * returns only contacts changed and ids removed since that token. Store
+     * the returned `syncToken` opaquely and send it next time. When
+     * `truncated` is true, sync again with the new token before relying on
+     * the result being complete. `carddav:sync-token-invalid` means start
+     * over without a token; `carddav:sync-unsupported` means fall back to
+     * `query`.
+     *
+     * With `object.tokenOnly: true`, returns the address book's current
+     * token and no contacts, so a client can start tracking changes
+     * without downloading every contact first.
+     */
+    sync(job: ActivityStream, credentials: CardDavCredentials, done: PlatformCallback): void;
     create(job: ActivityStream, credentials: CardDavCredentials, done: PlatformCallback): void;
     update(job: ActivityStream, credentials: CardDavCredentials, done: PlatformCallback): void;
     delete(job: ActivityStream, credentials: CardDavCredentials, done: PlatformCallback): void;

package/dist/index.js

@@ -42683,9 +42683,10 @@ function xmlText(value) {
     return predefined[entity.toLowerCase()] ?? reference;
   });
 }
-function parseDavXml(xml) {
+function parseDavXml(xml, options = {}) {
   return new XMLParser({
     ignoreAttributes: false,
+    parseTagValue: options.parseTagValue ?? true,
     removeNSPrefix: true,
     processEntities: false,
     tagValueProcessor: (_tagName, value) => xmlText(value),
@@ -42864,6 +42865,16 @@ function digestChallenge(header) {
   return;
 }
 var quote = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', "\\\"")}"`;
+var isStatus = (value, code) => new RegExp(`\\s${code}(?:\\s|$)`).test(String(value ?? ""));
+function davPreconditions(xml) {
+  try {
+    const error = parseDavXml(xml).error;
+    return error && typeof error === "object" ? Object.keys(error) : [];
+  } catch {
+    return [];
+  }
+}
+var xmlEscape = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 
 class DavClient {
   authentication;
@@ -42908,9 +42919,10 @@ class DavClient {
     this.assertAllowed(url);
     let response;
     try {
+      const { passForbidden: _, ...fetchInit } = init;
       const authorization = this.authorization(url, init);
       response = await this.fetchImpl(url, {
-        ...init,
+        ...fetchInit,
         redirect: "manual",
         signal,
         headers: {
@@ -42954,7 +42966,7 @@ class DavClient {
       }
       throw new DavFailure(`${this.errorPrefix}:${authAttempts > 0 ? "authentication-failed" : "unsupported-authentication"}`);
     }
-    if (response.status === 401 || response.status === 403) {
+    if (response.status === 401 || response.status === 403 && !init.passForbidden) {
       await response.body?.cancel().catch(() => {});
       throw new DavFailure(`${this.errorPrefix}:authentication-failed`);
     }
@@ -42975,6 +42987,175 @@ class DavClient {
       await response.body?.cancel().catch(() => {});
       throw new DavFailure(`${this.errorPrefix}:invalid-response`);
     }
+    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",
+      passForbidden: true,
+      headers: {
+        depth: "0",
+        "content-type": "application/xml; charset=utf-8"
+      },
+      body: `<?xml version="1.0" encoding="utf-8"?>
+<d:sync-collection xmlns:d="DAV:"${namespaces ? ` ${namespaces}` : ""}>
+ ${syncToken ? `<d:sync-token>${xmlEscape(syncToken)}</d:sync-token>` : "<d:sync-token/>"}
+ <d:sync-level>1</d:sync-level>
+ <d:prop>${prop}</d:prop>
+</d:sync-collection>`
+    });
+    if (response.status !== 207) {
+      let body = "";
+      try {
+        body = await response.text();
+      } catch {}
+      const preconditions = davPreconditions(body);
+      const prefix = this.errorPrefix;
+      if (preconditions.includes("valid-sync-token"))
+        throw new DavFailure(`${prefix}:sync-token-invalid`);
+      if (preconditions.includes("supported-report"))
+        throw new DavFailure(`${prefix}:sync-unsupported`);
+      if (response.status === 404)
+        throw new DavFailure(`${prefix}:not-found`);
+      if ([400, 409, 412].includes(response.status) && syncToken)
+        throw new DavFailure(`${prefix}:sync-token-invalid`);
+      if (response.status === 403)
+        throw new DavFailure(`${prefix}:authentication-failed`);
+      if ([400, 405, 415, 501].includes(response.status))
+        throw new DavFailure(`${prefix}:sync-unsupported`);
+      throw new DavFailure(`${prefix}:sync-failed`);
+    }
+    let multistatus;
+    try {
+      const parsed = parseDavXml(await response.text(), {
+        parseTagValue: false
+      }).multistatus;
+      if (!parsed || typeof parsed !== "object")
+        throw new Error;
+      multistatus = parsed;
+    } catch {
+      throw new DavFailure(`${this.errorPrefix}:invalid-response`);
+    }
+    const token = multistatus["sync-token"];
+    if (typeof token !== "string" || token.trim() === "")
+      throw new DavFailure(`${this.errorPrefix}:invalid-response`);
+    const result = {
+      changed: [],
+      removed: [],
+      syncToken: token.trim(),
+      truncated: false
+    };
+    for (const item of asArray(multistatus.response)) {
+      const href = davHref(item.href);
+      if (!href)
+        throw new DavFailure(`${this.errorPrefix}:invalid-response`);
+      const id = new URL(href, collection).href;
+      const status = item.status;
+      if (id === collection.href || `${id}/` === collection.href) {
+        if (isStatus(status, 507))
+          result.truncated = true;
+        continue;
+      }
+      if (!isDavCollectionChild(collection.href, id))
+        throw new DavFailure(`${this.errorPrefix}:invalid-response`);
+      if (isStatus(status, 404))
+        result.removed.push(id);
+      else
+        result.changed.push({ id, props: successfulProps(item) });
+    }
+    return result;
+  }
+  async syncResources(collection, options, syncToken) {
+    const property = options.data.slice(options.data.indexOf(":") + 1);
+    const sync = await this.syncCollection(collection, `<d:getetag/><${options.data}/>`, syncToken, options.namespaces);
+    const resources = [];
+    const missing = new Map;
+    const add = (id, value, etag) => {
+      const data = value && typeof value === "object" ? value["#text"] : value;
+      if (typeof data !== "string")
+        return false;
+      resources.push({
+        id,
+        data,
+        ...typeof etag === "string" ? { etag } : {}
+      });
+      return true;
+    };
+    for (const member of sync.changed)
+      if (!add(member.id, member.props[property], member.props.getetag))
+        missing.set(member.id, member.props.getetag);
+    if (missing.size) {
+      const hrefs = [...missing.keys()].map((id) => `<d:href>${xmlEscape(new URL(id).pathname)}</d:href>`).join("");
+      const response = await this.request(collection, {
+        method: "REPORT",
+        headers: {
+          depth: "1",
+          "content-type": "application/xml; charset=utf-8"
+        },
+        body: `<?xml version="1.0" encoding="utf-8"?>
+<${options.multiget} xmlns:d="DAV:" ${options.namespaces}>
+ <d:prop><d:getetag/><${options.data}/></d:prop>
+ ${hrefs}
+</${options.multiget}>`
+      });
+      if (response.status !== 207)
+        return rejectDavResponse(response, `${this.errorPrefix}:sync-failed`);
+      for (const item of await this.readMultistatus(response)) {
+        const href = davHref(item.href);
+        if (!href)
+          continue;
+        const id = new URL(href, collection).href;
+        if (!missing.has(id))
+          continue;
+        if (isStatus(item.status, 404)) {
+          sync.removed.push(id);
+          missing.delete(id);
+          continue;
+        }
+        const props = successfulProps(item);
+        if (add(id, props[property], props.getetag ?? missing.get(id)))
+          missing.delete(id);
+      }
+      if (missing.size)
+        throw new DavFailure(`${this.errorPrefix}:invalid-response`);
+    }
+    return {
+      resources,
+      removed: sync.removed,
+      syncToken: sync.syncToken,
+      truncated: sync.truncated
+    };
+  }
+  async readMultistatus(response) {
     try {
       const parsed = parseDavXml(await response.text());
       return asArray(parsed.multistatus?.response);
@@ -43275,7 +43456,7 @@ var ActivityStreamSchema = {
 var package_default = {
   name: "@sockethub/schemas",
   description: "JSON schema files for validating Sockethub Activity Streams",
-  version: "3.0.0-beta.4",
+  version: "3.0.0-beta.6",
   type: "module",
   private: false,
   author: "Nick Jennings <nick@silverbucket.net>",
@@ -43345,7 +43526,7 @@ var package_default = {
     "ajv-formats": "^2.1.1",
     "ajv-formats-draft2019": "^1.6.1"
   },
-  gitHead: "639c296a7332f192a1b3f7e86ef6603b5b67bbaa",
+  gitHead: "604f3da8850a19a4fd5f5e5dcec10bf283e9085e",
   types: "./dist/index.d.ts"
 };
 
@@ -44306,6 +44487,14 @@ function queryBody(query) {
  ${filter}
 </c:addressbook-query>`;
 }
+function contact(data, id, etag) {
+  try {
+    return parseVCard(data, id, typeof etag === "string" ? etag : undefined);
+  } catch {
+    throw new DavFailure("carddav:invalid-response");
+  }
+}
+
 class CardDavClient extends DavClient {
   constructor(url, authentication, timeoutMs = 15000, networkOptions = {}) {
     super(url, authentication, "carddav", timeoutMs, networkOptions);
@@ -44371,29 +44560,30 @@ class CardDavClient extends DavClient {
     });
     if (response.status !== 207)
       return rejectDavResponse(response, "carddav:query-failed");
-    let parsed;
-    try {
-      parsed = parseDavXml(await response.text());
-    } catch {
-      throw new DavFailure("carddav:invalid-response");
-    }
     const contacts = [];
-    for (const item of asArray(parsed.multistatus?.response)) {
+    for (const item of await this.readMultistatus(response)) {
       const props = successfulProps(item);
       const itemHref = davHref(item.href);
       const data = props["address-data"];
       if (!itemHref || typeof data !== "string")
         continue;
-      try {
-        contacts.push(parseVCard(data, new URL(itemHref, book.id).href, typeof props.getetag === "string" ? props.getetag : undefined));
-      } catch {
-        throw new DavFailure("carddav:invalid-response");
-      }
+      contacts.push(contact(data, new URL(itemHref, book.id).href, props.getetag));
       if (query.limit && contacts.length >= query.limit)
         break;
     }
     return contacts;
   }
+  async sync(book, syncToken) {
+    const { resources, ...result } = await this.syncResources(new URL(book.id), {
+      namespaces: 'xmlns:c="urn:ietf:params:xml:ns:carddav"',
+      data: "c:address-data",
+      multiget: "c:addressbook-multiget"
+    }, syncToken);
+    return {
+      ...result,
+      items: resources.map((resource) => contact(resource.data, resource.id, resource.etag))
+    };
+  }
   async create(book, input) {
     const card = buildVCard(input, []);
     const resource = new URL(`${encodeURIComponent(card.uid)}.vcf`, book.id.endsWith("/") ? book.id : `${book.id}/`);
@@ -44486,7 +44676,7 @@ class CardDavClient extends DavClient {
 var package_default2 = {
   name: "@sockethub/platform-carddav",
   description: "A Sockethub platform for CardDAV address books and contacts",
-  version: "1.0.0-beta.4",
+  version: "1.0.0-beta.6",
   type: "module",
   private: false,
   license: "LGPL-3.0+",
@@ -44515,21 +44705,21 @@ var package_default2 = {
     test: "bun test src/"
   },
   dependencies: {
-    "@sockethub/dav": "^1.0.0-beta.4",
-    "@sockethub/schemas": "^3.0.0-beta.4"
+    "@sockethub/dav": "^1.0.0-beta.6",
+    "@sockethub/schemas": "^3.0.0-beta.6"
   },
   devDependencies: {
     "@types/bun": "latest"
   },
   peerDependencies: {
-    "@sockethub/server": "^5.0.0-beta.4"
+    "@sockethub/server": "^5.0.0-beta.6"
   },
   peerDependenciesMeta: {
     "@sockethub/server": {
       optional: true
     }
   },
-  gitHead: "639c296a7332f192a1b3f7e86ef6603b5b67bbaa"
+  gitHead: "604f3da8850a19a4fd5f5e5dcec10bf283e9085e"
 };
 
 // src/schema.ts
@@ -44637,7 +44827,7 @@ var shared = {
   vcardVersion: { enum: ["3.0", "4.0"] },
   updateSupported: { type: "boolean" }
 };
-var contact = {
+var contact2 = {
   type: "object",
   required: ["type", "name"],
   additionalProperties: false,
@@ -44658,6 +44848,13 @@ var query = {
     limit: { type: "integer", minimum: 1, maximum: 1000 }
   }
 };
+var syncToken = { type: "string", minLength: 1, maxLength: 4096 };
+var sync = {
+  type: "object",
+  additionalProperties: false,
+  properties: { syncToken, tokenOnly: { const: true } },
+  not: { required: ["syncToken", "tokenOnly"] }
+};
 var deletion = {
   type: "object",
   required: ["id", "type", "etag"],
@@ -44665,11 +44862,11 @@ var deletion = {
   properties: { id: shared.id, type: shared.type, etag: shared.etag }
 };
 var updateContact = {
-  ...contact,
+  ...contact2,
   required: ["type", "name", "id", "uid", "etag"]
 };
 var responseContact = {
-  ...contact,
+  ...contact2,
   required: ["id", "type", "uid", "name", "vcardVersion", "updateSupported"]
 };
 var mutation = {
@@ -44727,10 +44924,20 @@ var PlatformCardDavSchema = {
   messages: {
     required: ["type", "actor"],
     properties: {
-      type: { enum: ["fetch", "query", "create", "update", "delete"] },
+      type: {
+        enum: ["fetch", "query", "sync", "create", "update", "delete"]
+      },
       actor,
       target,
-      object: { oneOf: [contact, query, deletion] }
+      object: {
+        oneOf: [
+          contact2,
+          query,
+          deletion,
+          { ...sync, required: ["syncToken"] },
+          { ...sync, required: ["tokenOnly"] }
+        ]
+      }
     }
   },
   messageConstraints: {
@@ -44747,7 +44954,11 @@ var PlatformCardDavSchema = {
         required: ["type", "actor", "target"]
       },
       {
-        properties: { type: { const: "create" }, object: contact },
+        properties: { type: { const: "sync" }, object: sync },
+        required: ["type", "actor", "target"]
+      },
+      {
+        properties: { type: { const: "create" }, object: contact2 },
         required: ["type", "actor", "target", "object"]
       },
       {
@@ -44800,6 +45011,30 @@ var PlatformCardDavSchema = {
           }
         }
       },
+      {
+        type: "object",
+        required: [
+          "@context",
+          "type",
+          "totalItems",
+          "items",
+          "removed",
+          "syncToken",
+          "truncated"
+        ],
+        additionalProperties: false,
+        properties: {
+          "@context": { type: "array", items: { type: "string" } },
+          id: { type: ["string", "null"] },
+          type: { const: "collection" },
+          summary: { type: "string" },
+          totalItems: { type: "integer", minimum: 0 },
+          items: { type: "array", items: responseContact },
+          removed: { type: "array", items: shared.id },
+          syncToken,
+          truncated: { type: "boolean" }
+        }
+      },
       {
         type: "object",
         required: ["@context", "type", "actor", "target", "object"],
@@ -44825,7 +45060,14 @@ class CardDav {
   discovery = new DiscoveryCache;
   config = {
     persist: false,
-    requireCredentials: ["fetch", "query", "create", "update", "delete"],
+    requireCredentials: [
+      "fetch",
+      "query",
+      "sync",
+      "create",
+      "update",
+      "delete"
+    ],
     connectTimeoutMs: 15000,
     allowPrivateAddresses: false,
     allowInsecureHttp: false,
@@ -44866,6 +45108,23 @@ class CardDav {
       items
     })).catch((error) => this.fail(job, error, done, credentials)).finally(() => client.close().catch(() => {}));
   }
+  sync(job, credentials, done) {
+    const client = this.client(credentials);
+    const input = job.object ?? {};
+    this.book(client, credentials, job.target?.id ?? "").then((book) => input.tokenOnly ? client.currentSyncToken(new URL(book.id)).then((syncToken) => ({
+      items: [],
+      removed: [],
+      syncToken,
+      truncated: false
+    })) : client.sync(book, input.syncToken)).then((result) => done(null, {
+      "@context": CONTEXT,
+      ...job.id ? { id: job.id } : {},
+      type: "collection",
+      summary: "CardDAV changes",
+      totalItems: result.items.length,
+      ...result
+    })).catch((error) => this.fail(job, error, done, credentials)).finally(() => client.close().catch(() => {}));
+  }
   create(job, credentials, done) {
     const client = this.client(credentials);
     this.book(client, credentials, job.target?.id ?? "").then((book) => client.create(book, job.object)).then((result) => done(null, this.mutation(job, "create", result))).catch((error) => this.fail(job, error, done, credentials)).finally(() => client.close().catch(() => {}));
@@ -44946,4 +45205,4 @@ export {
   parseVCard
 };
 
-//# debugId=4AD528BB46F9866F64756E2164756E21
+//# debugId=9916E0836EEA9D2664756E2164756E21