@lanes-sh/link 0.1.0

package/src/connectivity/transports/dav/capabilities.ts

@@ -0,0 +1,151 @@
+import { READ_BUNDLE, WRITE_BUNDLE, type DiscoveredCapability } from '#connectivity';
+import { DEFAULT_MAX_RANGE_DAYS, OPERATIONS, object } from './operations.ts';
+
+/**
+ * What a DAV connection exposes, as data.
+ *
+ * Fixed, like `imap`: WebDAV describes collections, never operations. The list
+ * is conditioned on the service so a manifest pointing at a calendar never
+ * shows contact tools.
+ *
+ * Extracted from `discover()` because it is a hundred and thirty lines of
+ * declaration wrapped around three lines of behaviour, and reading the
+ * behaviour meant scrolling past all of it.
+ */
+export function davCapabilities(service: 'caldav' | 'carddav'): DiscoveredCapability[] {
+  const calendar = service === 'caldav';
+
+  return calendar
+        ? [
+            {
+              name: OPERATIONS.listCalendars,
+              description: 'List the calendars in the account.',
+              bundle: READ_BUNDLE,
+              inputSchema: object({}),
+              target: { operation: OPERATIONS.listCalendars },
+            },
+            {
+              name: OPERATIONS.listEvents,
+              description:
+                'Events between two dates, with repeating events already expanded into instances.',
+              bundle: READ_BUNDLE,
+              inputSchema: object(
+                {
+                  calendar: {
+                    type: 'string',
+                    description: 'Calendar name from list_calendars. Defaults to every calendar.',
+                  },
+                  start: { type: 'string', description: 'ISO 8601 date or date-time.' },
+                  end: {
+                    type: 'string',
+                    description: `ISO 8601. At most ${DEFAULT_MAX_RANGE_DAYS} days after start.`,
+                  },
+                  limit: { type: 'integer', minimum: 1, maximum: 200, default: 50 },
+                },
+                ['start', 'end'],
+              ),
+              target: { operation: OPERATIONS.listEvents },
+            },
+            {
+              name: OPERATIONS.getEvent,
+              description: 'One event by its UID, optionally with its raw iCalendar text.',
+              bundle: READ_BUNDLE,
+              inputSchema: object(
+                {
+                  calendar: { type: 'string' },
+                  uid: { type: 'string', description: 'UID as list_events reports it.' },
+                  include_raw: { type: 'boolean', default: false },
+                },
+                ['uid'],
+              ),
+              target: { operation: OPERATIONS.getEvent },
+            },
+            {
+              name: OPERATIONS.updateEvent,
+              description:
+                'Change an existing event. Only the fields you pass are touched; attendees, alarms and repetition are preserved.',
+              bundle: WRITE_BUNDLE,
+              inputSchema: object(
+                {
+                  calendar: { type: 'string' },
+                  uid: { type: 'string' },
+                  summary: { type: 'string' },
+                  start: { type: 'string', description: 'ISO 8601 date or date-time.' },
+                  end: { type: 'string', description: 'ISO 8601 date or date-time.' },
+                  all_day: { type: 'boolean' },
+                  location: { type: 'string', description: 'Empty string clears it.' },
+                  description: { type: 'string', description: 'Empty string clears it.' },
+                },
+                ['uid'],
+              ),
+              target: { operation: OPERATIONS.updateEvent },
+            },
+            {
+              name: OPERATIONS.deleteEvent,
+              description: 'Delete an event. This goes to the calendar\'s trash, not permanently.',
+              bundle: WRITE_BUNDLE,
+              inputSchema: object(
+                { calendar: { type: 'string' }, uid: { type: 'string' } },
+                ['uid'],
+              ),
+              target: { operation: OPERATIONS.deleteEvent },
+            },
+            {
+              name: OPERATIONS.createEvent,
+              description: 'Create an event in a calendar.',
+              bundle: WRITE_BUNDLE,
+              inputSchema: object(
+                {
+                  calendar: { type: 'string' },
+                  summary: { type: 'string' },
+                  start: { type: 'string', description: 'ISO 8601 date or date-time.' },
+                  end: { type: 'string', description: 'ISO 8601 date or date-time.' },
+                  all_day: { type: 'boolean', default: false },
+                  location: { type: 'string' },
+                  description: { type: 'string' },
+                },
+                ['calendar', 'summary', 'start', 'end'],
+              ),
+              target: { operation: OPERATIONS.createEvent },
+            },
+          ]
+        : [
+            {
+              name: OPERATIONS.listAddressbooks,
+              description: 'List the address books in the account.',
+              bundle: READ_BUNDLE,
+              inputSchema: object({}),
+              target: { operation: OPERATIONS.listAddressbooks },
+            },
+            {
+              name: OPERATIONS.searchContacts,
+              description: 'Search contacts by name or email address.',
+              bundle: READ_BUNDLE,
+              inputSchema: object(
+                {
+                  query: { type: 'string', description: 'Matched against name and email.' },
+                  limit: { type: 'integer', minimum: 1, maximum: 100, default: 25 },
+                },
+                ['query'],
+              ),
+              target: { operation: OPERATIONS.searchContacts },
+            },
+            {
+              name: OPERATIONS.createContact,
+              description: 'Add a contact to an address book.',
+              bundle: WRITE_BUNDLE,
+              inputSchema: object(
+                {
+                  addressbook: { type: 'string', description: 'Defaults to the first one.' },
+                  full_name: { type: 'string' },
+                  emails: { type: 'array', items: { type: 'string' } },
+                  phones: { type: 'array', items: { type: 'string' } },
+                  organization: { type: 'string' },
+                  note: { type: 'string' },
+                },
+                ['full_name'],
+              ),
+              target: { operation: OPERATIONS.createContact },
+            },
+          ];
+}

package/src/connectivity/transports/dav/client.ts

@@ -0,0 +1,226 @@
+import type { ConnectorContext, ToolResult } from '#connectivity';
+import { parseEvents } from './ical.ts';
+import { PRINCIPAL_BODY, davRequest, hrefOfProperty, type DavReply } from './request.ts';
+import { DEFAULT_MAX_RANGE_DAYS, HOME_KEY } from './operations.ts';
+import {
+  CALDAV,
+  CARDDAV,
+  DAV,
+  escapeXml,
+  find,
+  findAll,
+  parseDav,
+  successful,
+  textOf,
+} from './xml.ts';
+import type { Collection, DavConnectorOptions } from './index.ts';
+
+/**
+ * A DAV session for one connection.
+ *
+ * Holds the three things every operation needs and nothing else: how to make an
+ * authorised request, where this account's collections live, and how to find a
+ * single object by uid. `request`, `collections` and `locate` are public
+ * because the calendar and contact operations are free functions in their own
+ * files — the class is the transport, not the feature set.
+ */
+export class DavClient {
+  constructor(
+    private readonly options: DavConnectorOptions,
+    private readonly doFetch: typeof globalThis.fetch,
+    private readonly context: ConnectorContext,
+  ) {}
+
+  /** The longest event window this server will answer — the provider's fact. */
+  get maxRangeDays(): number {
+    return this.options.maxRangeDays ?? DEFAULT_MAX_RANGE_DAYS;
+  }
+
+  private get calendar(): boolean {
+    return this.options.service === 'caldav';
+  }
+
+  request(
+    url: string,
+    method: string,
+    body?: string,
+    headers: Record<string, string> = {},
+  ): Promise<DavReply> {
+    return davRequest(this.doFetch, (request: Request) => this.context.authorize(request), url, method, body, headers);
+  }
+
+  /**
+   * The account's collection home, resolved once and remembered per connection.
+   *
+   * Three round trips — well-known, principal, home-set — which is why it is
+   * cached; and cached in per-connection state rather than in the capability
+   * target, because that cache is shared by every account of the provider.
+   * Re-resolved whenever it is missing or has stopped working, so an Apple
+   * partition migration heals itself instead of needing a re-connect.
+   */
+  private async home(): Promise<string> {
+    const remembered = await this.context.provider.state.get(HOME_KEY);
+    if (remembered) return remembered;
+
+    const resolved = await this.resolveHome();
+    await this.context.provider.state.set(HOME_KEY, resolved);
+    return resolved;
+  }
+
+  private async resolveHome(): Promise<string> {
+    const namespace = this.calendar ? CALDAV : CARDDAV;
+    const property = this.calendar ? 'calendar-home-set' : 'addressbook-home-set';
+
+    // Two places to ask, in order. RFC 6764's well-known path is a bootstrap
+    // *hint*, and a server is free not to answer there — iCloud's contacts host
+    // returns a 207 whose propstat is 404, which is "not here" wearing the
+    // costume of a success. Falling back to the root is what every DAV client
+    // does, and it is where iCloud actually answers.
+    const candidates = [
+      new URL(this.calendar ? '/.well-known/caldav' : '/.well-known/carddav', this.options.baseUrl)
+        .href,
+      new URL('/', this.options.baseUrl).href,
+    ];
+
+    let principalHref: string | undefined;
+    let principalFoundAt: string | undefined;
+    let lastStatus = 0;
+
+    for (const candidate of candidates) {
+      const reply = await this.request(candidate, 'PROPFIND', PRINCIPAL_BODY, { depth: '0' });
+      lastStatus = reply.status;
+      if (reply.status >= 400) continue;
+
+      const href = hrefOfProperty(parseDav(reply.text), `{${DAV}}current-user-principal`);
+      if (href) {
+        principalHref = href;
+        principalFoundAt = reply.url;
+        break;
+      }
+    }
+
+    if (lastStatus === 401 || lastStatus === 403) {
+      throw new Error(
+        `The server refused discovery (${lastStatus}).` +
+          (this.options.troubleshooting ? ` ${this.options.troubleshooting}` : ''),
+      );
+    }
+    if (!principalHref || !principalFoundAt) {
+      throw new Error('The server did not say which principal you are.');
+    }
+
+    const principalUrl = new URL(principalHref, principalFoundAt).href;
+    const homeBody =
+      `<?xml version="1.0" encoding="utf-8"?>` +
+      `<d:propfind xmlns:d="DAV:" xmlns:x="${namespace}">` +
+      `<d:prop><x:${property}/></d:prop></d:propfind>`;
+
+    const second = await this.request(principalUrl, 'PROPFIND', homeBody, { depth: '0' });
+    const homeHref = hrefOfProperty(parseDav(second.text), `{${namespace}}${property}`);
+
+    if (!homeHref) throw new Error('The server did not say where your collections live.');
+    return new URL(homeHref, second.url).href;
+  }
+
+  /**
+   * The collections in the home, filtered to the ones this service can use.
+   *
+   * The `VEVENT` filter is not cosmetic: iCloud publishes Reminders lists as
+   * CalDAV collections holding `VTODO`, and without this they show up as
+   * calendars that are always empty — which is Home Assistant's single
+   * most-reported CalDAV complaint.
+   */
+  async collections(): Promise<Collection[]> {
+    const namespace = this.calendar ? CALDAV : CARDDAV;
+    const body =
+      `<?xml version="1.0" encoding="utf-8"?>` +
+      `<d:propfind xmlns:d="DAV:" xmlns:x="${namespace}">` +
+      `<d:prop><d:resourcetype/><d:displayname/>` +
+      (this.calendar ? `<x:supported-calendar-component-set/>` : '') +
+      `</d:prop></d:propfind>`;
+
+    const result = await this.request(await this.home(), 'PROPFIND', body, { depth: '1' });
+    const responses = findAll(parseDav(result.text), `{${DAV}}response`);
+    const collections: Collection[] = [];
+
+    for (const response of responses) {
+      const href = textOf(response, `{${DAV}}href`);
+      if (!href) continue;
+
+      const props = successful(response);
+      if (props.length === 0) continue;
+
+      const isRightType = props.some(
+        (prop) =>
+          findAll(prop, `{${namespace}}${this.calendar ? 'calendar' : 'addressbook'}`).length > 0,
+      );
+      if (!isRightType) continue;
+
+      // A collection that declares its components but not VEVENT is a Reminders
+      // list. Silence on the question is treated as "yes": some servers omit the
+      // property entirely, and dropping those would hide real calendars.
+      if (this.calendar) {
+        const declared = props.some(
+          (prop) => findAll(prop, `{${CALDAV}}supported-calendar-component-set`).length > 0,
+        );
+        const holdsEvents = props.some((prop) =>
+          findAll(prop, `{${CALDAV}}comp`).some((comp) => comp.attributes['name'] === 'VEVENT'),
+        );
+        if (declared && !holdsEvents) continue;
+      }
+
+      collections.push({
+        // A display name is optional, and iCloud omits it on the default
+        // address book. The last path segment is a poor name but a usable one;
+        // the whole href is neither, and this value is what a caller passes back
+        // in as `calendar` or `addressbook`.
+        name:
+          props.map((prop) => textOf(prop, `{${DAV}}displayname`)).find(Boolean) ??
+          href.split('/').filter(Boolean).pop() ??
+          href,
+        href: new URL(href, result.url).href,
+      });
+    }
+
+    return collections;
+  }
+
+  async locate(
+    uid: string,
+    calendarName?: string,
+  ): Promise<{ href: string; etag: string | undefined; ical: string; calendar: string } | null> {
+    const escaped = escapeXml(uid);
+    const body =
+      `<?xml version="1.0" encoding="utf-8"?>` +
+      `<c:calendar-query xmlns:d="DAV:" xmlns:c="${CALDAV}">` +
+      `<d:prop><d:getetag/><c:calendar-data/></d:prop>` +
+      `<c:filter><c:comp-filter name="VCALENDAR"><c:comp-filter name="VEVENT">` +
+      `<c:prop-filter name="UID"><c:text-match collation="i;octet">${escaped}</c:text-match></c:prop-filter>` +
+      `</c:comp-filter></c:comp-filter></c:filter></c:calendar-query>`;
+
+    const calendars = (await this.collections()).filter(
+      (collection) => !calendarName || collection.name === calendarName,
+    );
+
+    for (const collection of calendars) {
+      const reply = await this.request(collection.href, 'REPORT', body, { depth: '1' });
+      if (reply.status >= 400) continue;
+
+      for (const response of findAll(parseDav(reply.text), `{${DAV}}response`)) {
+        const href = textOf(response, `{${DAV}}href`);
+        const ical = textOf(response, `{${CALDAV}}calendar-data`);
+        if (!href || !ical) continue;
+
+        return {
+          href: new URL(href, reply.url).href,
+          etag: textOf(response, `{${DAV}}getetag`),
+          ical,
+          calendar: collection.name,
+        };
+      }
+    }
+
+    return null;
+  }
+
+}

package/src/connectivity/transports/dav/contacts.ts

@@ -0,0 +1,75 @@
+import type { ToolResult } from '#connectivity';
+import { buildContact, parseContacts } from './ical.ts';
+import { error, json } from './request.ts';
+import { CARDDAV, DAV, escapeXml, findAll, parseDav, textOf } from './xml.ts';
+import type { DavClient } from './client.ts';
+
+/** CardDAV's two operations. Same shape as `calendar.ts`, and same reason. */
+
+export async function createContact(
+  dav: DavClient,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+    const books = await dav.collections();
+    const wanted = args['addressbook'] ? String(args['addressbook']) : undefined;
+    const book = wanted ? books.find((entry) => entry.name === wanted) : books[0];
+    if (!book) return error(wanted ? `No address book named "${wanted}".` : 'No address books.');
+
+    const uid = crypto.randomUUID();
+    const vcard = buildContact({
+      uid,
+      fullName: String(args['full_name'] ?? ''),
+      emails: args['emails'] as string[] | undefined,
+      phones: args['phones'] as string[] | undefined,
+      organization: args['organization'] as string | undefined,
+      note: args['note'] as string | undefined,
+    });
+
+    const href = new URL(`${uid}.vcf`, `${book.href.replace(/\/?$/, '/')}`).href;
+    const reply = await dav.request(href, 'PUT', vcard, {
+      'content-type': 'text/vcard; charset=utf-8',
+      'if-none-match': '*',
+    });
+
+    if (reply.status >= 400) {
+      return error(`The server refused the contact (${reply.status}). ${reply.text.slice(0, 200)}`);
+    }
+
+    return json({ created: true, uid, addressbook: book.name });
+  }
+
+export async function searchContacts(
+  dav: DavClient,
+  args: Readonly<Record<string, unknown>>,
+): Promise<ToolResult> {
+    const query = String(args['query'] ?? '');
+    if (!query) return error('query is required.');
+    const limit = Math.min(Number(args['limit'] ?? 25) || 25, 100);
+
+    const escaped = escapeXml(query);
+    const body =
+      `<?xml version="1.0" encoding="utf-8"?>` +
+      `<c:addressbook-query xmlns:d="DAV:" xmlns:c="${CARDDAV}">` +
+      `<d:prop><d:getetag/><c:address-data/></d:prop>` +
+      `<c:filter test="anyof">` +
+      `<c:prop-filter name="FN"><c:text-match collation="i;unicode-casemap" match-type="contains">${escaped}</c:text-match></c:prop-filter>` +
+      `<c:prop-filter name="EMAIL"><c:text-match collation="i;unicode-casemap" match-type="contains">${escaped}</c:text-match></c:prop-filter>` +
+      `</c:filter></c:addressbook-query>`;
+
+    const contacts: unknown[] = [];
+
+    for (const collection of await dav.collections()) {
+      const result = await dav.request(collection.href, 'REPORT', body, { depth: '1' });
+      if (result.status >= 400) continue;
+
+      for (const response of findAll(parseDav(result.text), `{${DAV}}response`)) {
+        const data = textOf(response, `{${CARDDAV}}address-data`);
+        if (!data) continue;
+        for (const contact of parseContacts(data)) {
+          contacts.push({ ...contact, addressbook: collection.name });
+        }
+      }
+    }
+
+    return json({ query, contacts: contacts.slice(0, limit) });
+  }