@devosurf/tesser-connectors 0.1.0-alpha.0

package/google-calendar/index.ts

@@ -0,0 +1,454 @@
+// Google Calendar connector — second connector behind the shared `google` Provider.
+
+import { z } from "zod";
+import { RetryableError, TerminalError } from "@devosurf/tesser-sdk";
+import {
+  action,
+  defineConnector,
+  oauth2,
+  trigger,
+  type ActionCtx,
+  type ClassifyError,
+} from "@devosurf/tesser-sdk/connector";
+import { googleProvider } from "../providers/google.js";
+
+// Google overloads 403: rate-limit 403s are retryable, permission 403s are terminal.
+// The default "4xx terminal" mapping double-penalizes rate limits, so promote the two
+// usageLimits reasons (and 429) to retry; everything else keeps the default. Family rule
+// shared across the Google connectors (see the google-platform deep-dive).
+const googleClassifyError: ClassifyError = (err) => {
+  if (err.status === 429) return "retry";
+  if (err.status === 403 && /rateLimitExceeded|userRateLimitExceeded/.test(err.bodySnippet)) {
+    return "retry";
+  }
+  return undefined;
+};
+
+const eventShape = z.object({
+  id: z.string(),
+  summary: z.string(),
+  start: z.string(),
+  end: z.string(),
+  htmlLink: z.string().optional(),
+});
+
+const calendarShape = z.object({
+  id: z.string(),
+  summary: z.string(),
+  primary: z.boolean(),
+});
+
+const busySlot = z.object({ start: z.string(), end: z.string() });
+const freeBusyShape = z.object({
+  calendars: z.record(z.string(), z.object({ busy: z.array(busySlot) })),
+});
+
+type RawEvent = {
+  id: string;
+  summary?: string;
+  htmlLink?: string;
+  start?: { dateTime?: string; date?: string };
+  end?: { dateTime?: string; date?: string };
+  updated?: string;
+  status?: string;
+};
+
+type RawCalendarListEntry = {
+  id: string;
+  summary?: string;
+  primary?: boolean;
+};
+
+function mapEvent(raw: RawEvent): z.infer<typeof eventShape> {
+  return {
+    id: raw.id,
+    summary: raw.summary ?? "",
+    start: raw.start?.dateTime ?? raw.start?.date ?? "",
+    end: raw.end?.dateTime ?? raw.end?.date ?? "",
+    ...(raw.htmlLink !== undefined ? { htmlLink: raw.htmlLink } : {}),
+  };
+}
+
+function mapCalendar(raw: RawCalendarListEntry): z.infer<typeof calendarShape> {
+  return {
+    id: raw.id,
+    summary: raw.summary ?? "",
+    primary: raw.primary ?? false,
+  };
+}
+
+const eventsPath = (calendarId: string) =>
+  `/calendars/${encodeURIComponent(calendarId)}/events`;
+const eventPath = (calendarId: string, eventId: string) =>
+  `${eventsPath(calendarId)}/${encodeURIComponent(eventId)}`;
+
+// Build the Events resource body shared by create/update.
+function eventBody(i: {
+  summary: string;
+  startIso: string;
+  endIso: string;
+  description?: string | undefined;
+  attendees?: string[] | undefined;
+}): Record<string, unknown> {
+  return {
+    summary: i.summary,
+    start: { dateTime: i.startIso },
+    end: { dateTime: i.endIso },
+    ...(i.description !== undefined ? { description: i.description } : {}),
+    ...(i.attendees !== undefined ? { attendees: i.attendees.map((email) => ({ email })) } : {}),
+  };
+}
+
+type EventListPage = {
+  items?: RawEvent[];
+  nextPageToken?: string;
+  nextSyncToken?: string;
+};
+
+type EventListResult =
+  | { gone: false; items: RawEvent[]; nextSyncToken?: string }
+  | { gone: true; items: []; nextSyncToken?: undefined };
+
+async function eventListPage(
+  ctx: ActionCtx,
+  calendarId: string,
+  query: Record<string, string | number | boolean | undefined>,
+): Promise<EventListPage | "gone"> {
+  const res = (await ctx.http.get(eventsPath(calendarId), { query, raw: true })) as Response;
+  const text = await res.text().catch(() => "");
+  if (res.status >= 200 && res.status < 300) {
+    return (text.length > 0 ? JSON.parse(text) : {}) as EventListPage;
+  }
+  if (res.status === 410) return "gone";
+
+  const bodySnippet = text.slice(0, 600);
+  const msg = `provider responded ${res.status} for GET ${eventsPath(calendarId)}${
+    bodySnippet ? ` — ${bodySnippet}` : ""
+  }`;
+  const classified = googleClassifyError({ status: res.status, bodySnippet, url: eventsPath(calendarId) });
+  if (classified === "retry" || res.status === 408 || res.status === 425 || res.status >= 500) {
+    throw new RetryableError(msg);
+  }
+  throw new TerminalError(msg);
+}
+
+async function listEventPages(
+  ctx: ActionCtx,
+  calendarId: string,
+  baseQuery: Record<string, string | number | boolean | undefined>,
+): Promise<EventListResult> {
+  const items: RawEvent[] = [];
+  let pageToken: string | undefined;
+  let nextSyncToken: string | undefined;
+  for (let page = 0; page < 100; page++) {
+    const res = await eventListPage(ctx, calendarId, {
+      ...baseQuery,
+      ...(pageToken !== undefined ? { pageToken } : {}),
+    });
+    if (res === "gone") return { gone: true, items: [] };
+    items.push(...(res.items ?? []));
+    if (res.nextSyncToken !== undefined) nextSyncToken = res.nextSyncToken;
+    if (res.nextPageToken === undefined) {
+      return {
+        gone: false,
+        items,
+        ...(nextSyncToken !== undefined ? { nextSyncToken } : {}),
+      };
+    }
+    pageToken = res.nextPageToken;
+  }
+  throw new RetryableError(`calendar events pagination exceeded safety cap for ${eventsPath(calendarId)}`);
+}
+
+function eventStartKey(raw: RawEvent): string {
+  return raw.start?.dateTime ?? raw.start?.date ?? "";
+}
+
+export default defineConnector({
+  id: "google-calendar",
+  describe: "Google Calendar events",
+  provider: googleProvider,
+  baseUrl: "https://www.googleapis.com/calendar/v3",
+  auth: oauth2({
+    provider: "google",
+    scopes: [
+      "https://www.googleapis.com/auth/calendar.events",
+      "https://www.googleapis.com/auth/calendar.readonly",
+    ],
+  }),
+  samples: {
+    "events.list": [
+      {
+        id: "evt1",
+        summary: "Standup",
+        start: "2026-01-01T09:00:00Z",
+        end: "2026-01-01T09:15:00Z",
+      },
+    ],
+    "events.get": {
+      id: "evt1",
+      summary: "Standup",
+      start: "2026-01-01T09:00:00Z",
+      end: "2026-01-01T09:15:00Z",
+      htmlLink: "https://calendar.google.com/event?eid=evt1",
+    },
+    "events.create": {
+      id: "evt2",
+      summary: "Created",
+      start: "2026-01-02T09:00:00Z",
+      end: "2026-01-02T10:00:00Z",
+      htmlLink: "https://calendar.google.com/event?eid=evt2",
+    },
+    "events.update": {
+      id: "evt2",
+      summary: "Rescheduled",
+      start: "2026-01-02T11:00:00Z",
+      end: "2026-01-02T12:00:00Z",
+      htmlLink: "https://calendar.google.com/event?eid=evt2",
+    },
+    "events.delete": { id: "evt2", deleted: true },
+    "calendars.list": [
+      { id: "primary", summary: "Ada", primary: true },
+      { id: "team@example.com", summary: "Team", primary: false },
+    ],
+    "freebusy.query": {
+      calendars: {
+        primary: { busy: [{ start: "2026-01-01T09:00:00Z", end: "2026-01-01T09:30:00Z" }] },
+      },
+    },
+    "trigger:eventCreated": {
+      id: "evt3",
+      summary: "New meeting",
+      start: "2026-01-03T09:00:00Z",
+      end: "2026-01-03T10:00:00Z",
+      htmlLink: "https://calendar.google.com/event?eid=evt3",
+    },
+    "trigger:eventStarting": {
+      id: "evt4",
+      summary: "Starting soon",
+      start: "2026-01-04T09:00:00Z",
+      end: "2026-01-04T10:00:00Z",
+      htmlLink: "https://calendar.google.com/event?eid=evt4",
+    },
+  },
+  actions: {
+    events: {
+      list: action({
+        describe: "List upcoming events",
+        input: z.object({
+          calendarId: z.string().default("primary"),
+          timeMin: z.string().optional(),
+          maxResults: z.number().int().min(1).max(250).default(10),
+        }),
+        output: z.array(eventShape),
+        safety: "read",
+        classifyError: googleClassifyError,
+        run: async (ctx, i) => {
+          const res = (await ctx.http.get(eventsPath(i.calendarId), {
+            query: {
+              maxResults: i.maxResults,
+              singleEvents: "true",
+              orderBy: "startTime",
+              ...(i.timeMin !== undefined ? { timeMin: i.timeMin } : {}),
+            },
+          })) as { items?: RawEvent[] };
+          return (res.items ?? []).map(mapEvent);
+        },
+      }),
+      get: action({
+        describe: "Fetch one event by id",
+        input: z.object({
+          calendarId: z.string().default("primary"),
+          eventId: z.string().min(1),
+        }),
+        output: eventShape,
+        safety: "read",
+        classifyError: googleClassifyError,
+        run: async (ctx, i) => {
+          const res = (await ctx.http.get(eventPath(i.calendarId, i.eventId))) as RawEvent;
+          return mapEvent(res);
+        },
+      }),
+      create: action({
+        describe: "Create an event",
+        input: z.object({
+          calendarId: z.string().default("primary"),
+          summary: z.string().min(1),
+          startIso: z.string(),
+          endIso: z.string(),
+          description: z.string().optional(),
+          attendees: z.array(z.string()).optional(),
+          sendUpdates: z.enum(["all", "externalOnly", "none"]).optional(),
+        }),
+        output: eventShape,
+        classifyError: googleClassifyError,
+        run: async (ctx, i) => {
+          const res = (await ctx.http.post(eventsPath(i.calendarId), eventBody(i), {
+            ...(i.sendUpdates !== undefined ? { query: { sendUpdates: i.sendUpdates } } : {}),
+          })) as RawEvent;
+          return mapEvent(res);
+        },
+      }),
+      update: action({
+        describe: "Replace an event (full PUT)",
+        input: z.object({
+          calendarId: z.string().default("primary"),
+          eventId: z.string().min(1),
+          summary: z.string().min(1),
+          startIso: z.string(),
+          endIso: z.string(),
+          description: z.string().optional(),
+          attendees: z.array(z.string()).optional(),
+          sendUpdates: z.enum(["all", "externalOnly", "none"]).optional(),
+        }),
+        output: eventShape,
+        classifyError: googleClassifyError,
+        run: async (ctx, i) => {
+          const res = (await ctx.http.put(eventPath(i.calendarId, i.eventId), eventBody(i), {
+            ...(i.sendUpdates !== undefined ? { query: { sendUpdates: i.sendUpdates } } : {}),
+          })) as RawEvent;
+          return mapEvent(res);
+        },
+      }),
+      delete: action({
+        describe: "Delete an event; deleting an already-gone event is a no-op success",
+        input: z.object({
+          calendarId: z.string().default("primary"),
+          eventId: z.string().min(1),
+          sendUpdates: z.enum(["all", "externalOnly", "none"]).optional(),
+        }),
+        output: z.object({ id: z.string(), deleted: z.boolean() }),
+        // A delete carries no idempotency key, so it stays a write with no auto-retry. We
+        // read the status in raw mode instead of letting ctx.http classify, because 404/410
+        // mean "already gone" and must resolve to idempotent success, not failure. OBSERVED
+        // behavior: the delete reference documents only an empty 2xx body, not a 410 on a
+        // repeat delete; 410 is the documented stale-sync signal elsewhere, but on a single
+        // event DELETE it means the event is gone. Treat both as a no-op success.
+        run: async (ctx, i) => {
+          const res = (await ctx.http.delete(eventPath(i.calendarId, i.eventId), {
+            raw: true,
+            ...(i.sendUpdates !== undefined ? { query: { sendUpdates: i.sendUpdates } } : {}),
+          })) as Response;
+          const s = res.status;
+          if (s === 404 || s === 410 || (s >= 200 && s < 300)) {
+            return { id: i.eventId, deleted: true };
+          }
+          const msg = `provider responded ${s} for DELETE ${eventPath(i.calendarId, i.eventId)}`;
+          if (s === 429 || s >= 500) throw new RetryableError(msg);
+          throw new TerminalError(msg);
+        },
+      }),
+    },
+    calendars: {
+      list: action({
+        describe: "List calendars on the connected account",
+        input: z.object({}),
+        output: z.array(calendarShape),
+        safety: "read",
+        classifyError: googleClassifyError,
+        run: async (ctx) => {
+          const out: z.infer<typeof calendarShape>[] = [];
+          let pageToken: string | undefined;
+          // Loop pages inside run() with a sane cap (calendarList max 250/page).
+          for (let page = 0; page < 20; page++) {
+            const res = (await ctx.http.get("/users/me/calendarList", {
+              query: { maxResults: 250, ...(pageToken !== undefined ? { pageToken } : {}) },
+            })) as { items?: RawCalendarListEntry[]; nextPageToken?: string };
+            for (const c of res.items ?? []) out.push(mapCalendar(c));
+            if (!res.nextPageToken) break;
+            pageToken = res.nextPageToken;
+          }
+          return out;
+        },
+      }),
+    },
+    freebusy: {
+      query: action({
+        describe: "Query busy windows for one or more calendars",
+        input: z.object({
+          timeMin: z.string(),
+          timeMax: z.string(),
+          calendarIds: z.array(z.string()).min(1).default(["primary"]),
+        }),
+        output: freeBusyShape,
+        safety: "read",
+        classifyError: googleClassifyError,
+        run: async (ctx, i) => {
+          const res = (await ctx.http.post("/freeBusy", {
+            timeMin: i.timeMin,
+            timeMax: i.timeMax,
+            items: i.calendarIds.map((id) => ({ id })),
+          })) as {
+            calendars?: Record<string, { busy?: Array<{ start: string; end: string }> }>;
+          };
+          const calendars: Record<string, { busy: Array<{ start: string; end: string }> }> = {};
+          for (const [id, cal] of Object.entries(res.calendars ?? {})) {
+            calendars[id] = { busy: (cal.busy ?? []).map((b) => ({ start: b.start, end: b.end })) };
+          }
+          return { calendars };
+        },
+      }),
+    },
+  },
+  triggers: {
+    eventCreated: trigger.poll({
+      describe: "Fires for each newly created or changed event (syncToken poll)",
+      input: z.object({ calendarId: z.string().default("primary") }),
+      output: eventShape,
+      interval: { default: "2m", floor: "1m" },
+      order: "oldest-first",
+      poll: async (ctx, params, cursor) => {
+        const syncToken = typeof cursor === "string" && cursor.length > 0 ? cursor : undefined;
+        const listed = await listEventPages(ctx, params.calendarId, {
+          maxResults: 2500,
+          singleEvents: "true",
+          ...(syncToken !== undefined ? { syncToken } : {}),
+        });
+        if (listed.gone) return { items: [], nextCursor: null };
+        // First activation establishes the syncToken cursor without backfilling the calendar.
+        if (syncToken === undefined) {
+          return { items: [], ...(listed.nextSyncToken !== undefined ? { nextCursor: listed.nextSyncToken } : {}) };
+        }
+        return {
+          items: listed.items.filter((event) => event.status !== "cancelled"),
+          ...(listed.nextSyncToken !== undefined ? { nextCursor: listed.nextSyncToken } : {}),
+        };
+      },
+      dedupeKey: (item) => {
+        const event = item as RawEvent;
+        return `${event.id}:${event.updated ?? eventStartKey(event)}`;
+      },
+      map: (item) => mapEvent(item as RawEvent),
+    }),
+    eventStarting: trigger.poll({
+      describe: "Fires for each event entering the upcoming window (poll)",
+      input: z.object({
+        calendarId: z.string().default("primary"),
+        leadMinutes: z.number().int().min(1).max(1440).default(10),
+      }),
+      output: eventShape,
+      interval: { default: "1m", floor: "1m" },
+      order: "oldest-first",
+      poll: async (ctx, params) => {
+        // This is a window trigger, not a generic upcoming-events list: bound the poll to
+        // [now, now+lead] and dedupe by occurrence start so an event fires as it enters.
+        const now = Date.now();
+        const res = (await ctx.http.get(eventsPath(params.calendarId), {
+          query: {
+            timeMin: new Date(now).toISOString(),
+            timeMax: new Date(now + params.leadMinutes * 60_000).toISOString(),
+            maxResults: 50,
+            singleEvents: "true",
+            orderBy: "startTime",
+          },
+        })) as { items?: RawEvent[] };
+        return res.items ?? [];
+      },
+      dedupeKey: (item) => {
+        const event = item as RawEvent;
+        return `${event.id}:${eventStartKey(event)}`;
+      },
+      map: (item) => mapEvent(item as RawEvent),
+    }),
+  },
+});

package/google-docs/index.ts

@@ -0,0 +1,162 @@
+// Google Docs connector — sits behind the shared `google` Provider (one OAuth app backs
+// gmail + google-calendar + google-docs). The Docs v1 API is effectively documents.get +
+// documents.create + documents.batchUpdate, where batchUpdate drives a fiddly 0-based
+// UTF-16 index model. We HIDE that model behind high-level actions (appendText via
+// endOfSegmentLocation, replacePlaceholders via replaceAllText) and never expose raw
+// batchUpdate.
+//
+// No triggers: the Docs API has no webhooks, no push, no change feed, and no list
+// endpoint. "When a doc changes / a doc is created in folder X" is a Drive capability and
+// belongs in the Google Drive connector (files.watch / files.list).
+
+import { z } from "zod";
+import { action, defineConnector, oauth2, type ActionCtx } from "@devosurf/tesser-sdk/connector";
+import { googleProvider } from "../providers/google.js";
+
+// --- Plain-text flattening of a document body ---------------------------------
+
+type RawTextRun = { content?: string };
+type RawParagraphElement = { textRun?: RawTextRun };
+type RawParagraph = { elements?: RawParagraphElement[] };
+type RawStructuralElement = { paragraph?: RawParagraph };
+type RawDocument = {
+  documentId?: string;
+  title?: string;
+  body?: { content?: RawStructuralElement[] };
+};
+
+// Walk body.content[].paragraph.elements[].textRun.content and concatenate. textRun
+// content already carries its own trailing newline per paragraph, so a straight join
+// reproduces the document's line breaks without extra index math.
+function flattenBody(doc: RawDocument): string {
+  let text = "";
+  for (const el of doc.body?.content ?? []) {
+    for (const pe of el.paragraph?.elements ?? []) {
+      text += pe.textRun?.content ?? "";
+    }
+  }
+  return text;
+}
+
+function docPath(documentId: string): string {
+  return `/documents/${encodeURIComponent(documentId)}`;
+}
+
+// --- Output shapes (our stable mapped shapes, never the raw provider blob) -----
+
+const documentRead = z.object({
+  documentId: z.string(),
+  title: z.string(),
+  text: z.string(),
+});
+
+const documentRef = z.object({ documentId: z.string() });
+
+const replaceResult = z.object({
+  documentId: z.string(),
+  replacedCount: z.number().int(),
+});
+
+type BatchUpdateReply = { replaceAllText?: { occurrencesChanged?: number } };
+type BatchUpdateResponse = { documentId?: string; replies?: BatchUpdateReply[] };
+
+async function batchUpdate(
+  ctx: ActionCtx,
+  documentId: string,
+  requests: unknown[],
+): Promise<BatchUpdateResponse> {
+  return (await ctx.http.post(`${docPath(documentId)}:batchUpdate`, { requests })) as BatchUpdateResponse;
+}
+
+export default defineConnector({
+  id: "google-docs",
+  describe: "Google Docs — read, create, and template-fill documents",
+  provider: googleProvider,
+  baseUrl: "https://docs.googleapis.com/v1",
+  auth: oauth2({
+    provider: "google",
+    scopes: [
+      // documents = RW on Docs content (get + create + batchUpdate).
+      "https://www.googleapis.com/auth/documents",
+      // drive.file = open/create app docs and place them in a folder without the
+      // restricted drive scopes.
+      "https://www.googleapis.com/auth/drive.file",
+    ],
+  }),
+  // No idempotencyHeader: the Docs API has no idempotency key, so writes stay
+  // non-retrying (a retried create makes a 2nd doc; a retried append duplicates text).
+  samples: {
+    "documents.get": {
+      documentId: "1aBcD",
+      title: "Quarterly report",
+      text: "Heading\nFirst line.\nSecond line.\n",
+    },
+    "documents.create": { documentId: "1aBcD", title: "New doc" },
+    "documents.appendText": { documentId: "1aBcD" },
+    "documents.replacePlaceholders": { documentId: "1aBcD", replacedCount: 3 },
+  },
+  actions: {
+    documents: {
+      get: action({
+        describe: "Read a document's title and full plain text",
+        input: z.object({ documentId: z.string().min(1) }),
+        output: documentRead,
+        safety: "read",
+        run: async (ctx, i) => {
+          const doc = (await ctx.http.get(docPath(i.documentId))) as RawDocument;
+          return {
+            documentId: doc.documentId ?? i.documentId,
+            title: doc.title ?? "",
+            text: flattenBody(doc),
+          };
+        },
+      }),
+      create: action({
+        describe: "Create a new blank document with the given title",
+        input: z.object({ title: z.string().min(1) }),
+        output: documentRef.extend({ title: z.string() }),
+        // Non-idempotent write: no provider idempotency key, so no retrySafe override.
+        run: async (ctx, i) => {
+          const doc = (await ctx.http.post("/documents", { title: i.title })) as RawDocument;
+          return { documentId: doc.documentId ?? "", title: doc.title ?? i.title };
+        },
+      }),
+      appendText: action({
+        describe: "Append text to the end of a document's body (no index math)",
+        input: z.object({ documentId: z.string().min(1), text: z.string().min(1) }),
+        output: documentRef,
+        // endOfSegmentLocation appends at the end of the body, so we never compute a
+        // 0-based UTF-16 index. Non-idempotent: a retry duplicates the appended text.
+        run: async (ctx, i) => {
+          const res = await batchUpdate(ctx, i.documentId, [
+            { insertText: { endOfSegmentLocation: {}, text: i.text } },
+          ]);
+          return { documentId: res.documentId ?? i.documentId };
+        },
+      }),
+      replacePlaceholders: action({
+        describe: "Replace placeholder tokens throughout a document (one atomic batch)",
+        input: z.object({
+          documentId: z.string().min(1),
+          // e.g. { "{{name}}": "Ada", "{{date}}": "2026-06-13" }
+          replacements: z.record(z.string(), z.string()),
+        }),
+        output: replaceResult,
+        // replaceAllText is index-free and re-runnable (an already-replaced token is a
+        // harmless no-op), making this the most retry-friendly write here. Still a
+        // "write" with no retrySafe override: we do not auto-retry writes.
+        run: async (ctx, i) => {
+          const requests = Object.entries(i.replacements).map(([key, value]) => ({
+            replaceAllText: { containsText: { text: key, matchCase: true }, replaceText: value },
+          }));
+          const res = await batchUpdate(ctx, i.documentId, requests);
+          const replacedCount = (res.replies ?? []).reduce(
+            (sum, r) => sum + (r.replaceAllText?.occurrencesChanged ?? 0),
+            0,
+          );
+          return { documentId: res.documentId ?? i.documentId, replacedCount };
+        },
+      }),
+    },
+  },
+});