@nimbus-dev/connectors 0.2.4 → 0.4.0

package/connectors/outlook/src/tools.ts

@@ -37,12 +37,54 @@ function graphRequest(
   return makeRestFetcher({ apiBase: GRAPH, token })(pathOrUrl, init);
 }
 
+/** `a@x, ,b@y` as Graph recipients, empty entries dropped. */
+function graphRecipients(list: string): { emailAddress: { address: string } }[] {
+  return list
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+    .map((address) => ({ emailAddress: { address } }));
+}
+
+/** What `outlook_mail_send` and `outlook_draft_create` both build the message from. */
+interface MailFields {
+  readonly to: string;
+  readonly subject: string;
+  readonly body: string;
+  readonly contentType?: "text" | "html" | undefined;
+  readonly cc?: string | undefined;
+  readonly bcc?: string | undefined;
+}
+
+/**
+ * The Graph `message` resource: the body of `POST /me/messages` (a draft) and the `message` member
+ * of `POST /me/sendMail`. cc and bcc are left out when absent or empty.
+ */
+function graphMessage(data: MailFields): Record<string, unknown> {
+  const message: Record<string, unknown> = {
+    subject: data.subject,
+    body: {
+      contentType: (data.contentType ?? "text") === "html" ? "HTML" : "Text",
+      content: data.body,
+    },
+    toRecipients: graphRecipients(data.to),
+  };
+  if (data.cc !== undefined && data.cc !== "") {
+    message["ccRecipients"] = graphRecipients(data.cc);
+  }
+  if (data.bcc !== undefined && data.bcc !== "") {
+    message["bccRecipients"] = graphRecipients(data.bcc);
+  }
+  return message;
+}
+
 /** Tool names exposed by this connector — for contract/introspection tests. */
 export const OUTLOOK_TOOL_NAMES = [
   "outlook_mail_folders",
   "outlook_mail_list",
   "outlook_mail_read",
   "outlook_mail_send",
+  "outlook_draft_create",
   "outlook_calendar_list",
   "outlook_calendar_get",
   "outlook_calendar_create",
@@ -170,33 +212,10 @@ export function registerOutlookTools(
       outlookMailSendArgs,
       async (data) => {
         const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
-        const toList = data.to
-          .split(",")
-          .map((s) => s.trim())
-          .filter((s) => s.length > 0);
-        const message: Record<string, unknown> = {
-          subject: data.subject,
-          body: {
-            contentType: (data.contentType ?? "text") === "html" ? "HTML" : "Text",
-            content: data.body,
-          },
-          toRecipients: toList.map((addr) => ({
-            emailAddress: { address: addr },
-          })),
-        };
-        if (data.cc !== undefined && data.cc !== "") {
-          const ccList = data.cc
-            .split(",")
-            .map((s) => s.trim())
-            .filter((s) => s.length > 0);
-          message["ccRecipients"] = ccList.map((addr) => ({
-            emailAddress: { address: addr },
-          }));
-        }
         const r = await graphRequest(token, "/me/sendMail", {
           method: "POST",
           headers: { "Content-Type": "application/json" },
-          body: JSON.stringify({ message, saveToSentItems: true }),
+          body: JSON.stringify({ message: graphMessage(data), saveToSentItems: true }),
         });
         if (!r.ok) {
           throw new Error(`Graph ${String(r.status)}: ${r.text.slice(0, 200)}`);
@@ -206,6 +225,37 @@ export function registerOutlookTools(
     );
   }
 
+  const outlookDraftCreateArgs = outlookMailSendArgs.extend({
+    bcc: headerLine({ max: 2000 }).optional(),
+  });
+
+  if (outlookToolShouldRegister("outlook_draft_create", grantedOutlookScopes)) {
+    registerWriteTool(
+      "outlook_draft_create",
+      {
+        mutates: "outlook.draft.create",
+        // The draft sits in Drafts until the owner deletes or sends it, and nothing is sent.
+        recoverable: true,
+        scopeTargetOf: (p) => ({ kind: "recipient", value: p.to }),
+      },
+      "Save an email as a DRAFT in the owner's Drafts folder via Microsoft Graph; it is not sent, and the owner reviews and sends it from Outlook.",
+      outlookDraftCreateArgs,
+      async (data) => {
+        const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
+        const r = await graphRequest(token, "/me/messages", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(graphMessage(data)),
+        });
+        if (!r.ok) {
+          throw new Error(`Graph ${String(r.status)}: ${r.text.slice(0, 200)}`);
+        }
+        const created = r.json as { id?: unknown; webLink?: unknown } | null;
+        return mcpJsonResult({ id: created?.id, webLink: created?.webLink });
+      },
+    );
+  }
+
   const outlookCalendarListArgs = z.object({
     startDateTime: z.string().min(1),
     endDateTime: z.string().min(1),

package/connectors/readwise/nimbus.extension.json

@@ -1,7 +1,7 @@
 {
   "id": "com.nimbus.readwise",
   "displayName": "Readwise",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Readwise connector (read-only). Surfaces the user's saved book/article highlights as `readwise:highlight` items in the local index — the highlighted excerpt text, the user's note, the parent book/article id, the location + location type, the color, tags, and the source article URL (for web highlights) — plus their parent books/articles as `readwise:book` items (title, author, category, source, highlight count, document note, tags, ASIN, source + Readwise book-review URLs), so a highlight's `book_id` resolves to a real indexed record. Useful for answering reading questions (\"what did I highlight about retries?\", \"which book was that note in?\") without leaving Nimbus. Token API-token auth (`Authorization: Token <token>` — Django-REST-Framework token auth, NOT Bearer). The SaaS host (readwise.io) is fixed. Readwise paginates both `/api/v2/highlights/` and `/api/v2/books/` by page number (DRF `{ count, next, previous, results }` envelope, page_size=1000). `highlighted_at` / `last_highlight_at` / `updated` are ISO-8601 (converted to epoch-ms on index). Book `external_id`s are namespaced `book/<id>` because Readwise numbers books and highlights in separate sequences. Documents / daily-review and the Reader v3 API remain deferred follow-ups.",
   "author": "Nimbus",
   "entrypoint": "dist/server.js",
@@ -11,5 +11,13 @@
   },
   "hitlRequired": [],
   "syncInterval": 600,
+  "sync": {
+    "contract": "1",
+    "intervalSeconds": 600,
+    "itemTypes": ["highlight", "book"]
+  },
+  "credentials": {
+    "token": { "env": "READWISE_TOKEN" }
+  },
   "minNimbusVersion": "0.2.0"
 }

package/connectors/readwise/src/book-mapping.ts

@@ -0,0 +1,109 @@
+/**
+ * A Readwise book (`GET /api/v2/books/`) as a sync item. Ported from the gateway's
+ * `readwise-book-mapping.ts` (Nimbus origin/main 61e034a5) with every field rule unchanged;
+ * `test/mapping-parity.test.ts` pins each field to what the gateway stored.
+ *
+ * `externalId` is `book/<numeric id>`, NOT the bare id. Readwise numbers books and highlights in
+ * separate sequences, so book 9001 and highlight 9001 both exist, and the gateway's item key is
+ * `<service>:<externalId>`: a bare id would let one type's row overwrite the other's.
+ */
+import {
+  asRecord,
+  namedTags,
+  numberField,
+  parseIsoMs,
+  type ReadwiseMappingContext,
+  type ReadwiseSyncItem,
+  stringField,
+} from "./record-fields.ts";
+
+/** Keeps `readwise:book/<id>` distinct from the highlight `readwise:<id>`. */
+export const READWISE_BOOK_EXTERNAL_ID_PREFIX = "book/";
+
+/** Trimmed string field, or null when absent/blank. */
+function trimmedField(row: Record<string, unknown>, key: string): string | null {
+  const raw = stringField(row, key);
+  if (raw === undefined) {
+    return null;
+  }
+  const trimmed = raw.trim();
+  return trimmed === "" ? null : trimmed;
+}
+
+function firstNonNull(candidates: readonly (string | null)[], fallback: string): string {
+  for (const candidate of candidates) {
+    if (candidate !== null) {
+      return candidate;
+    }
+  }
+  return fallback;
+}
+
+export function mapReadwiseBookToItem(
+  raw: unknown,
+  ctx: ReadwiseMappingContext,
+): ReadwiseSyncItem | null {
+  const row = asRecord(raw);
+  if (row === undefined) {
+    return null;
+  }
+
+  const idNum = numberField(row, "id");
+  if (idNum === undefined) {
+    return null;
+  }
+  const id = String(idNum);
+
+  const title = trimmedField(row, "title");
+  const author = trimmedField(row, "author");
+  const category = trimmedField(row, "category");
+  const source = trimmedField(row, "source");
+  const documentNote = trimmedField(row, "document_note");
+  const asin = trimmedField(row, "asin");
+  const sourceUrl = trimmedField(row, "source_url");
+  const highlightsUrl = trimmedField(row, "highlights_url");
+  const numHighlights = numberField(row, "num_highlights") ?? null;
+  const tags = namedTags(row["tags"]);
+
+  const lastHighlightAt = parseIsoMs(row["last_highlight_at"]);
+  const updatedAt = parseIsoMs(row["updated"]);
+
+  const titleText = firstNonNull([title, author], `Book ${id}`);
+  const bodyPreview = firstNonNull([documentNote, author, category], titleText);
+
+  // Kindle/ePub books have no public source URL; the Readwise book-review page
+  // is the only stable, user-openable URL for them.
+  const canonicalUrl = sourceUrl ?? highlightsUrl;
+
+  const modifiedAt = updatedAt ?? lastHighlightAt ?? ctx.syncedAt;
+
+  const metadata: Record<string, unknown> = {
+    // NUMBER, not the stringified id: a highlight stores its parent as
+    // `metadata.book_id` (a number), and this is the field that joins them.
+    book_id: idNum,
+    title,
+    author,
+    category,
+    source,
+    num_highlights: numHighlights,
+    asin,
+    tags,
+    document_note: documentNote,
+    source_url: sourceUrl,
+    highlights_url: highlightsUrl,
+    last_highlight_at: lastHighlightAt,
+    updated_at: updatedAt,
+    canonical_url: canonicalUrl,
+  };
+
+  return {
+    type: "book",
+    externalId: `${READWISE_BOOK_EXTERNAL_ID_PREFIX}${id}`,
+    title: titleText,
+    bodyPreview,
+    url: canonicalUrl,
+    canonicalUrl,
+    modifiedAt,
+    metadata,
+  };
+}

package/connectors/readwise/src/extension.ts

@@ -0,0 +1,11 @@
+// Entry point of the signed Readwise extension (bundled to dist/server.js by `build:extension`).
+// Kept apart from server.ts so the standalone/gateway entry stays untouched; bootstrap only.
+// Only this entry registers the reserved `__nimbus_sync` tool; server.ts users never see it.
+import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { registerReadwiseSyncTool } from "./sync-tool.ts";
+import { registerReadwiseTools } from "./tools.ts";
+
+await runReadOnlyMcpConnector("nimbus-readwise", (reg) => {
+  registerReadwiseTools(reg);
+  registerReadwiseSyncTool(reg);
+});

package/connectors/readwise/src/highlight-mapping.ts

@@ -0,0 +1,88 @@
+/**
+ * A Readwise highlight (`GET /api/v2/highlights/`) as a sync item. Ported from the gateway's
+ * `readwise-highlight-mapping.ts` (Nimbus origin/main 61e034a5) with every field rule unchanged:
+ * a migrated user's rows are updated in place only while `type` and `externalId` stay
+ * byte-identical, and `test/mapping-parity.test.ts` pins every other field to what the gateway
+ * stored. Highlights keep the BARE numeric id as `externalId`.
+ */
+import {
+  asRecord,
+  namedTags,
+  numberField,
+  parseIsoMs,
+  type ReadwiseMappingContext,
+  type ReadwiseSyncItem,
+  stringField,
+} from "./record-fields.ts";
+
+const TITLE_MAX = 80;
+
+export function mapReadwiseHighlightToItem(
+  raw: unknown,
+  ctx: ReadwiseMappingContext,
+): ReadwiseSyncItem | null {
+  const row = asRecord(raw);
+  if (row === undefined) {
+    return null;
+  }
+
+  const idNum = numberField(row, "id");
+  if (idNum === undefined) {
+    return null;
+  }
+  const id = String(idNum);
+
+  const text = stringField(row, "text") ?? null;
+  const note = stringField(row, "note") ?? null;
+  const location = numberField(row, "location") ?? null;
+  const locationType = stringField(row, "location_type") ?? null;
+  const color = stringField(row, "color") ?? null;
+  const bookId = numberField(row, "book_id") ?? null;
+  const sourceUrl = stringField(row, "url") ?? null;
+  const tags = namedTags(row["tags"]);
+
+  const highlightedAt = parseIsoMs(row["highlighted_at"]);
+  const updatedAt = parseIsoMs(row["updated"]);
+
+  const trimmedText = text === null ? "" : text.trim();
+  let title: string;
+  if (trimmedText === "") {
+    title = `Highlight ${id}`;
+  } else if (trimmedText.length > TITLE_MAX) {
+    title = `${trimmedText.slice(0, TITLE_MAX)}…`;
+  } else {
+    title = trimmedText;
+  }
+
+  const bodyPreview = note !== null && note !== "" ? note : (text ?? "");
+
+  const canonicalUrl = sourceUrl !== null && sourceUrl !== "" ? sourceUrl : null;
+
+  const modifiedAt = updatedAt ?? highlightedAt ?? ctx.syncedAt;
+
+  const metadata: Record<string, unknown> = {
+    highlight_id: id,
+    text,
+    note,
+    book_id: bookId,
+    location,
+    location_type: locationType,
+    color,
+    tags,
+    source_url: canonicalUrl,
+    highlighted_at: highlightedAt,
+    updated_at: updatedAt,
+    canonical_url: canonicalUrl,
+  };
+
+  return {
+    type: "highlight",
+    externalId: id,
+    title,
+    bodyPreview,
+    url: canonicalUrl,
+    canonicalUrl,
+    modifiedAt,
+    metadata,
+  };
+}

package/connectors/readwise/src/readwise-base.ts

@@ -0,0 +1,6 @@
+/**
+ * The Readwise origin, in ONE place: the read tools and the sync walk both import it. There is no
+ * environment or argument override — the SaaS host is fixed — so the only way to point either at
+ * another host is to substitute this module in a test-only build.
+ */
+export const READWISE_BASE = "https://readwise.io";

package/connectors/readwise/src/record-fields.ts

@@ -0,0 +1,72 @@
+/*
+ * Field readers for the two Readwise mappers, ported unchanged from the gateway's
+ * `unknown-record.ts` and `_lib/field-helpers.ts` (Nimbus origin/main 61e034a5). Each rule is
+ * load-bearing for parity with rows the gateway already indexed, so none of them is "simplified":
+ * `shared/search-filter.ts` has an `asRecord` of the same rule but a `stringField` that returns ""
+ * rather than `undefined`, which would change what a missing field maps to.
+ */
+
+export function asRecord(v: unknown): Record<string, unknown> | undefined {
+  if (v === null || typeof v !== "object" || Array.isArray(v)) {
+    return undefined;
+  }
+  return v as Record<string, unknown>;
+}
+
+export function stringField(r: Record<string, unknown>, key: string): string | undefined {
+  const v = r[key];
+  return typeof v === "string" ? v : undefined;
+}
+
+export function numberField(r: Record<string, unknown>, key: string): number | undefined {
+  const v = r[key];
+  return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
+
+/**
+ * The non-empty `name` values of an array of tag objects (`[{ id, name }]`), in input order. A
+ * non-array yields `[]`; an entry that is not a plain object, or whose `name` is absent, not a
+ * string, or empty, is skipped.
+ */
+export function namedTags(raw: unknown): string[] {
+  if (!Array.isArray(raw)) {
+    return [];
+  }
+  const names: string[] = [];
+  for (const t of raw) {
+    const row = asRecord(t);
+    if (row === undefined) {
+      continue;
+    }
+    const name = stringField(row, "name");
+    if (name !== undefined && name !== "") {
+      names.push(name);
+    }
+  }
+  return names;
+}
+
+/** An ISO-8601 string as epoch ms, or `null` when it is not a string or does not parse. */
+export function parseIsoMs(v: unknown): number | null {
+  return typeof v === "string" && Number.isFinite(Date.parse(v)) ? Date.parse(v) : null;
+}
+
+/**
+ * The one item shape both mappers emit: a sync-v1 `SyncItem` with the body as a preview. Exactly
+ * these eight fields — `service` and `syncedAt` are the gateway's, never the item's.
+ */
+export interface ReadwiseSyncItem {
+  readonly type: "highlight" | "book";
+  readonly externalId: string;
+  readonly title: string;
+  readonly bodyPreview: string;
+  readonly url: string | null;
+  readonly canonicalUrl: string | null;
+  readonly modifiedAt: number;
+  readonly metadata: Record<string, unknown>;
+}
+
+export interface ReadwiseMappingContext {
+  /** The walk's `now`: only the `modifiedAt` fallback for a row with no usable timestamp. */
+  readonly syncedAt: number;
+}

package/connectors/readwise/src/sync-tool.ts

@@ -0,0 +1,56 @@
+/**
+ * The reserved `__nimbus_sync` tool (sync contract v1, `@nimbus-dev/sdk/sync`). Registered by the
+ * extension entry (`extension.ts`) ONLY: the standalone and gateway-bundled `server.ts` never
+ * offers it. A read tool — it only GETs Readwise — and it takes no URL: the host is fixed in
+ * `readwise-base.ts`, and the cursor only ever selects a stream and a page number.
+ */
+import { SYNC_TOOL_NAME, type SyncRequest } from "@nimbus-dev/sdk/sync";
+import { z } from "zod";
+import type { McpListResult } from "../../../shared/mcp-tool-kit.ts";
+import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import { type ReadwiseFetch, readwiseSyncPage } from "./sync.ts";
+
+const SYNC_REQUEST = z.object({
+  cursor: z.string().nullable(),
+  depth: z.enum(["metadata_only", "summary", "full"]),
+  historyFloorMs: z.number().optional(),
+});
+
+/**
+ * The parsed arguments as the SDK's `SyncRequest`. Typed both ways on purpose: `depth` must stay the
+ * SDK's `SyncDepth`, and an absent `historyFloorMs` stays absent rather than `undefined`.
+ */
+function toSyncRequest(args: z.infer<typeof SYNC_REQUEST>): SyncRequest {
+  return {
+    cursor: args.cursor,
+    depth: args.depth,
+    ...(args.historyFloorMs === undefined ? {} : { historyFloorMs: args.historyFloorMs }),
+  };
+}
+
+export interface ReadwiseSyncToolOptions {
+  /** Defaults to the global `fetch`; tests serve Readwise through it. */
+  readonly fetch?: ReadwiseFetch;
+}
+
+export function registerReadwiseSyncTool(
+  reg: ZodToolRegistrar,
+  options: ReadwiseSyncToolOptions = {},
+): void {
+  reg(
+    SYNC_TOOL_NAME,
+    "Nimbus gateway sync (contract v1): one page of the user's Readwise highlights, then books, per call. Reserved for the gateway.",
+    SYNC_REQUEST,
+    async (args): Promise<McpListResult> => {
+      const request = toSyncRequest(args);
+      // `depth` and `historyFloorMs` are accepted and ignored: the gateway applies depth itself,
+      // and Readwise's walk was never bounded by a history floor.
+      const response = await readwiseSyncPage(request.cursor, {
+        // Read per call, as the read tools do, so a token set after start-up is used.
+        token: process.env["READWISE_TOKEN"],
+        ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+      });
+      return { content: [{ type: "text", text: JSON.stringify(response) }] };
+    },
+  );
+}