@nimbus-dev/connectors 0.2.1 → 0.2.3

package/shared/env-json-api.ts

@@ -0,0 +1,209 @@
+/**
+ * env-json-api — the read-only JSON GET client that 31 connectors had each
+ * written out by hand.
+ *
+ * The shape below appeared, byte for byte, in every one of them:
+ *
+ * ```ts
+ * function apiToken(): string {
+ *   const t = process.env["X_TOKEN"]?.trim();
+ *   if (t === undefined || t === "") throw new Error("X_TOKEN is not set");
+ *   return t;
+ * }
+ * function authHeader(): Record<string, string> {
+ *   return { Authorization: `Bearer ${apiToken()}`, Accept: "application/json" };
+ * }
+ * async function xGet(path: string): Promise<unknown> {
+ *   const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
+ *   const text = await res.text();
+ *   if (!res.ok) throw new Error(`X ${String(res.status)}: ${text.slice(0, 400)}`);
+ *   return JSON.parse(text) as unknown;
+ * }
+ * ```
+ *
+ * Only four things ever varied: the base URL, the service label in the error,
+ * the auth header, and (never, in practice) the 400-character snippet cap. So
+ * those are the inputs and the rest is here once.
+ *
+ * This is deliberately NOT `rest-tool-kit`'s `makeRestFetcher`. That one returns
+ * `{ ok, status, json, text }` for callers that branch on status; these 31
+ * connectors all throw on a non-2xx and return parsed JSON, and rewriting their
+ * tool bodies to the other contract would have been a behaviour change rather
+ * than a deduplication. Both shapes are legitimate; this module owns the
+ * throwing one.
+ *
+ * Environment is read at CALL time, not at module load. That is not incidental:
+ * the connectors behaved that way (their `apiToken()` ran per request), tests
+ * depend on being able to set the variable after import, and a connector must
+ * fail with "X_TOKEN is not set" on the tool call rather than at startup.
+ */
+
+import { stripTrailingSlashes } from "./strip-trailing-slashes.ts";
+
+/** Body-snippet length in the thrown error. The value every connector used. */
+export const DEFAULT_SNIPPET_MAX = 400;
+
+/**
+ * `process.env[name]`, trimmed. Throws `"<name> is not set"` when the variable
+ * is absent, empty, or whitespace only.
+ *
+ * Distinct from `requireProcessEnv` in `mcp-tool-kit`, which does not trim: a
+ * variable set to a single space passes that check and then produces an
+ * `Authorization: Bearer ` header and a puzzling 401. Every one of the 31
+ * connectors trimmed, so trimming is the behaviour being preserved here.
+ */
+export function requiredEnv(name: string): string {
+  const raw = process.env[name]?.trim();
+  if (raw === undefined || raw === "") {
+    throw new Error(`${name} is not set`);
+  }
+  return raw;
+}
+
+/** `process.env[name]`, trimmed, or `fallback` when absent or empty. */
+export function optionalEnv(name: string, fallback: string): string {
+  const raw = process.env[name]?.trim();
+  return raw === undefined || raw === "" ? fallback : raw;
+}
+
+/**
+ * A required base URL from the environment, with trailing slashes stripped so
+ * `${base}${path}` cannot produce a double slash.
+ */
+export function requiredBaseUrl(name: string): string {
+  return stripTrailingSlashes(requiredEnv(name));
+}
+
+/** An optional base URL from the environment, trailing slashes stripped. */
+export function optionalBaseUrl(name: string, fallback: string): string {
+  return stripTrailingSlashes(optionalEnv(name, fallback));
+}
+
+/** Builds the request headers. Called per request, so it reads env at call time. */
+export type HeaderFactory = () => Record<string, string>;
+
+/**
+ * `{ [header]: "<scheme> <token>", Accept: "application/json", ...extra }` where
+ * `token` is the trimmed value of `env`.
+ *
+ * `scheme` is the RFC 7235 auth scheme — `"Bearer"` for most, but the tree also
+ * contains `"Token"` (Readwise, dbt, Flagsmith) and lowercase `"token"` (Snyk),
+ * which are what those APIs actually accept and so are not normalised. Pass
+ * `scheme: ""` for the APIs that want the bare credential with no scheme
+ * (Bitrise, LaunchDarkly), and `header` for the ones that use their own header
+ * instead of `Authorization` (Codemagic, Dependency-Track, Metabase, Zotero).
+ */
+export function envAuthHeaders(cfg: {
+  readonly env: string;
+  readonly scheme?: string;
+  readonly header?: string;
+  readonly extra?: Record<string, string>;
+}): HeaderFactory {
+  const header = cfg.header ?? "Authorization";
+  const scheme = cfg.scheme ?? "Bearer";
+  return (): Record<string, string> => {
+    const token = requiredEnv(cfg.env);
+    return {
+      [header]: scheme === "" ? token : `${scheme} ${token}`,
+      Accept: "application/json",
+      ...cfg.extra,
+    };
+  };
+}
+
+/**
+ * The fetch the getter and the poster use. Defaults to the global `fetch`.
+ *
+ * A seam because the connectors that reach a self-hosted control plane (argocd,
+ * flux, mlflow) use `fetchWithTimeout` instead: a server that stops answering
+ * should fail the tool call, not hang it. A timeout was the whole reason they
+ * had carried hand-written copies of this getter.
+ */
+export type JsonFetch = (url: string, init: RequestInit) => Promise<Response>;
+
+export interface JsonApiConfig {
+  /**
+   * Base URL the path is appended to. A function when the base itself comes
+   * from the environment, so it is resolved per request rather than at import.
+   */
+  readonly base: string | (() => string);
+  /** Service name that prefixes a failure, e.g. `"Stripe 404: ..."`. */
+  readonly label: string;
+  readonly headers: HeaderFactory;
+  /** Body-snippet length in the error. Defaults to {@link DEFAULT_SNIPPET_MAX}. */
+  readonly snippetMax?: number;
+  /** Overrides the global `fetch` — see {@link JsonFetch}. */
+  readonly fetch?: JsonFetch;
+}
+
+/**
+ * One request against `config`, shared by the getter and the poster: resolve the
+ * base, send what `init` builds from the request headers, and return the body
+ * text — throwing `"<errorPrefix> <status>: <body snippet>"` on any non-2xx.
+ *
+ * The base is resolved BEFORE the headers are built, so a connector missing both
+ * its URL and its credential names the URL first, as every hand-written copy did.
+ */
+function sendFor(
+  config: JsonApiConfig,
+): (
+  path: string,
+  init: (headers: Record<string, string>) => RequestInit,
+  errorPrefix: string,
+) => Promise<string> {
+  const { base, headers } = config;
+  const snippetMax = config.snippetMax ?? DEFAULT_SNIPPET_MAX;
+  const doFetch = config.fetch ?? ((url, init) => fetch(url, init));
+  return async (path, init, errorPrefix) => {
+    const root = typeof base === "string" ? base : base();
+    const res = await doFetch(`${root}${path}`, init(headers()));
+    const text = await res.text();
+    if (!res.ok) {
+      throw new Error(`${errorPrefix} ${String(res.status)}: ${text.slice(0, snippetMax)}`);
+    }
+    return text;
+  };
+}
+
+/**
+ * A `(path) => Promise<unknown>` GET client for `config`. Resolves to the parsed
+ * JSON body, and throws `"<label> <status>: <body snippet>"` on any non-2xx.
+ *
+ * `path` is appended to the base as given — callers build it, and must
+ * `encodeURIComponent` any user-supplied segment, exactly as before.
+ */
+export function createJsonGetter(config: JsonApiConfig): (path: string) => Promise<unknown> {
+  const { label } = config;
+  const send = sendFor(config);
+  return async (path: string): Promise<unknown> =>
+    JSON.parse(await send(path, (headers) => ({ headers }), label)) as unknown;
+}
+
+/**
+ * The mutating twin of {@link createJsonGetter}: a `(path, body) => Promise<unknown>`
+ * POST client that sends `body` as JSON (adding `Content-Type: application/json` to
+ * the request headers) and resolves to the parsed response — `{}` when the response
+ * body is empty, as a mutation's often is.
+ *
+ * Throws `"<label> <path> <status>: <body snippet>"` on any non-2xx: unlike the
+ * getter's, the message names the path, so a failed mutation says which endpoint
+ * refused it. The argocd and mlflow write tools each carried a copy of this.
+ */
+export function createJsonPoster(
+  config: JsonApiConfig,
+): (path: string, body: unknown) => Promise<unknown> {
+  const { label } = config;
+  const send = sendFor(config);
+  return async (path: string, body: unknown): Promise<unknown> => {
+    const text = await send(
+      path,
+      (headers) => ({
+        method: "POST",
+        headers: { ...headers, "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      }),
+      `${label} ${path}`,
+    );
+    return text === "" ? {} : (JSON.parse(text) as unknown);
+  };
+}

package/shared/fetch-json-text.ts

@@ -0,0 +1,27 @@
+/**
+ * fetch-json-text — send a JSON API request and hand back the raw response text.
+ *
+ * `atlassian-json-fetch.ts` (jira, confluence) and notion built this request the same way around
+ * different credentials: their own headers first, `Content-Type: application/json` only when the
+ * request has a body, and any header the caller passes in `init` overriding all of them. A non-2xx
+ * is reported rather than thrown, because these APIs put the useful diagnostic in the error body.
+ */
+export async function fetchJsonText(
+  url: string,
+  baseHeaders: Readonly<Record<string, string>>,
+  init?: RequestInit,
+): Promise<{ ok: boolean; status: number; text: string }> {
+  const headers: Record<string, string> = { ...baseHeaders };
+  if (init?.body !== undefined) {
+    headers["Content-Type"] = "application/json";
+  }
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      ...headers,
+      ...(init?.headers as Record<string, string> | undefined),
+    },
+  });
+  const text = await res.text();
+  return { ok: res.ok, status: res.status, text };
+}

package/shared/github-rest.ts

@@ -0,0 +1,62 @@
+/**
+ * github-rest — the GitHub REST client the `github` and `github-actions`
+ * connectors share.
+ *
+ * Both talk to the same API with the same token and had each written out its
+ * base URL, its default headers, the fetch built from them and the
+ * `/repos/<owner>/<repo>` path. The pinned `X-GitHub-Api-Version` lived in three
+ * places, so a bump had to find all three.
+ */
+
+import { makeRestFetcher, type RestFetchResult } from "./rest-tool-kit.ts";
+
+export const GH_API = "https://api.github.com";
+
+/** The media type GitHub documents for its REST API. */
+export const GH_ACCEPT = "application/vnd.github+json";
+
+/** The REST API version both connectors are written against. */
+export const GH_API_VERSION = "2022-11-28";
+
+/** Sent with every request, beside the Bearer token. */
+export const GH_HEADERS: Record<string, string> = {
+  Accept: GH_ACCEPT,
+  "X-GitHub-Api-Version": GH_API_VERSION,
+};
+
+/** A Bearer-authenticated JSON request against {@link GH_API} (a relative path or a same-origin URL). */
+export function ghFetch(token: string, path: string, init?: RequestInit): Promise<RestFetchResult> {
+  return makeRestFetcher({ apiBase: GH_API, token, defaultHeaders: GH_HEADERS })(path, init);
+}
+
+/** `/repos/<owner>/<repo>`, both segments URI-encoded. */
+export function ghRepoPath(owner: string, repo: string): string {
+  return `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
+}
+
+/** The paging arguments every GitHub list tool accepts. */
+export interface GhPaging {
+  readonly perPage?: number | undefined;
+  readonly page?: number | undefined;
+}
+
+/**
+ * GitHub's paging parameters, in the order every list tool sends them: `per_page` (30 when not
+ * given — GitHub's own default), then `page` only when one was given.
+ */
+export function setGhPaging(params: URLSearchParams, paging: GhPaging): void {
+  params.set("per_page", String(paging.perPage ?? 30));
+  if (paging.page !== undefined) {
+    params.set("page", String(paging.page));
+  }
+}
+
+/**
+ * `path` plus the query string `setQuery` builds, as the relative path {@link ghFetch} takes. The
+ * parameters keep the order `setQuery` sets them in.
+ */
+export function ghQueryPath(path: string, setQuery: (params: URLSearchParams) => void): string {
+  const u = new URL(`${GH_API}${path}`);
+  setQuery(u.searchParams);
+  return `${u.pathname}${u.search}`;
+}

package/shared/graphql-json.ts

@@ -0,0 +1,60 @@
+/**
+ * graphql-json — one GraphQL-over-HTTP request, for the connectors whose API is a
+ * GraphQL endpoint read as plain JSON (dagster, wiz).
+ *
+ * Both had written out the same request and the same reading of the response
+ * envelope: a present `errors` member fails the call even when `data` came back
+ * too, and an absent `data` member fails it as well. That reading is a rule about
+ * what a partial GraphQL answer means, and it belongs in one place.
+ *
+ * Linear and Monte Carlo read the envelope differently (an `errors` ARRAY that
+ * must be non-empty, messages joined, a result union) and keep their own clients.
+ */
+
+/** Body-snippet length in the thrown errors. The value both connectors used. */
+const SNIPPET_MAX = 400;
+
+export interface GraphqlRequest {
+  /** The GraphQL endpoint. */
+  readonly url: string;
+  /** Service name that prefixes every failure, e.g. `"Wiz 401: ..."`. */
+  readonly label: string;
+  /** Auth headers; `Content-Type` and `Accept` (both `application/json`) are added after them. */
+  readonly headers: Readonly<Record<string, string>>;
+  readonly query: string;
+  /** Omitted from the request body entirely when undefined. */
+  readonly variables?: Record<string, unknown>;
+}
+
+/**
+ * POST `query` (and `variables`) to `url` and resolve to the response's `data`.
+ *
+ * Throws `"<label> <status>: <body snippet>"` on a non-2xx,
+ * `"<label> GraphQL error: <errors snippet>"` when the response carries `errors`,
+ * and `"<label> GraphQL: response missing \`data\` field"` when it carries no `data`.
+ */
+export async function postGraphql<T>(request: GraphqlRequest): Promise<T> {
+  const res = await fetch(request.url, {
+    method: "POST",
+    headers: {
+      ...request.headers,
+      "Content-Type": "application/json",
+      Accept: "application/json",
+    },
+    body: JSON.stringify({ query: request.query, variables: request.variables }),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`${request.label} ${String(res.status)}: ${text.slice(0, SNIPPET_MAX)}`);
+  }
+  const parsed = JSON.parse(text) as { data?: T; errors?: unknown };
+  if (parsed.errors !== undefined) {
+    throw new Error(
+      `${request.label} GraphQL error: ${JSON.stringify(parsed.errors).slice(0, SNIPPET_MAX)}`,
+    );
+  }
+  if (parsed.data === undefined) {
+    throw new Error(`${request.label} GraphQL: response missing \`data\` field`);
+  }
+  return parsed.data;
+}

package/shared/imap-mail-core.ts

@@ -55,3 +55,94 @@ export function formatAddress(a: MailAddress): string {
   }
   return addr;
 }
+
+/**
+ * Message ENVELOPE — RFC 2822 header fields only.
+ *
+ * These five declarations were written out identically in `imap/src/imap-core.ts`
+ * and `protonmail/src/mail-core.ts`, differing only in the `Imap`/`Mail` name
+ * prefix. Both connectors index the same thing through the same protocol, so
+ * there was never a second shape here — only a second copy. Each core now
+ * aliases these, keeping its own names for its own callers.
+ */
+export interface MailEnvelope {
+  readonly date?: Date | string | null;
+  readonly subject?: string | null;
+  readonly messageId?: string | null;
+  readonly from?: readonly MailAddress[];
+  readonly to?: readonly MailAddress[];
+  readonly cc?: readonly MailAddress[];
+}
+
+/**
+ * Attachment METADATA only — filename, size, mimetype. NEVER the bytes.
+ * Derived from BODYSTRUCTURE.
+ */
+export interface MailAttachmentMeta {
+  readonly filename: string | null;
+  readonly sizeBytes: number | null;
+  readonly mimeType: string | null;
+}
+
+/**
+ * A single mailbox message reduced to header + attachment-metadata + a capped
+ * text preview. This is the ONLY shape these connectors ever materialize; it
+ * has no field that could carry attachment content or a full body.
+ */
+export interface MailMessageMeta {
+  readonly uid: number;
+  readonly mailbox: string;
+  readonly uidValidity: string | null;
+  readonly envelope: MailEnvelope;
+  readonly attachments: readonly MailAttachmentMeta[];
+  /** Plain-text body preview, already capped to {@link PREVIEW_MAX_CHARS}. */
+  readonly preview: string;
+}
+
+/** Listing options. */
+export interface MailListOptions {
+  readonly mailbox?: string;
+  readonly limit?: number;
+}
+
+/** Search options — searches header/envelope fields, never body-content scans. */
+export interface MailSearchOptions {
+  readonly query: string;
+  readonly mailbox?: string;
+  readonly limit?: number;
+}
+
+/**
+ * Minimal IMAP client surface these connectors depend on. Implemented for real
+ * by `shared/imapflow-adapter.ts` and by a fake in tests. Deliberately exposes
+ * ONLY header/attachment-metadata + capped-preview reads.
+ */
+export interface MailClient {
+  /** List the most recent messages (header + attachment metadata + preview). */
+  list(options: MailListOptions): Promise<MailMessageMeta[]>;
+  /** Fetch one message's header + attachment metadata + preview by uid. */
+  get(uid: number, mailbox?: string): Promise<MailMessageMeta | null>;
+  /** Search by subject/from/to substring; returns matching message metas. */
+  search(options: MailSearchOptions): Promise<MailMessageMeta[]>;
+}
+
+/** Outgoing message for the SMTP send tool. */
+export interface SendMailInput {
+  readonly to: string;
+  readonly subject: string;
+  readonly body: string;
+  readonly cc?: string;
+  readonly bcc?: string;
+}
+
+/** Result of a send (message id assigned by the SMTP server, if any). */
+export interface SendMailResult {
+  readonly messageId: string | null;
+  readonly accepted: readonly string[];
+  readonly rejected: readonly string[];
+}
+
+/** Minimal SMTP mailer surface; implemented for real over nodemailer. */
+export interface SmtpMailer {
+  send(input: SendMailInput): Promise<SendMailResult>;
+}

package/shared/imap-tool-kit.ts

@@ -1,4 +1,4 @@
-import type { WriteToolRegistrar } from "./consent-kit.ts";
+import type { WriteToolConfig, WriteToolRegistrar } from "./consent-kit.ts";
 /**
  * Shared tool-layer helpers for the IMAP/JMAP email connectors (imap, protonmail).
  * Extracted to eliminate byte-identical duplication in tools.ts across those two
@@ -10,6 +10,10 @@ import type { WriteToolRegistrar } from "./consent-kit.ts";
  * connector-specific envelope/meta mappers are deliberately NOT extracted here
  * (they implement different local interfaces and are out of scope per the dedup
  * brief).
+ *
+ * The mail-SEND pieces — `sendArgs`, {@link outgoingMail} and {@link mailSendConsent} —
+ * serve every email connector that sends, whatever its transport: imap, protonmail and
+ * apple through the factory below, and fastmail (JMAP), gmail and outlook directly.
  */
 
 import { z } from "zod";
@@ -54,6 +58,55 @@ export const emailToolSchemas = {
   sendArgs,
 } as const;
 
+// ---------------------------------------------------------------------------
+// Shared mail-send helpers (every connector that sends or drafts a new message)
+// ---------------------------------------------------------------------------
+
+/** What a send or draft tool hands its transport. */
+export interface OutgoingMail {
+  readonly to: string;
+  readonly subject: string;
+  readonly body: string;
+  readonly cc?: string;
+  readonly bcc?: string;
+}
+
+/**
+ * The outgoing message for validated `sendArgs`-shaped input: an empty `cc` or `bcc` is
+ * left out rather than handed on as an empty header.
+ */
+export function outgoingMail(args: {
+  readonly to: string;
+  readonly subject: string;
+  readonly body: string;
+  readonly cc?: string | undefined;
+  readonly bcc?: string | undefined;
+}): OutgoingMail {
+  return {
+    to: args.to,
+    subject: args.subject,
+    body: args.body,
+    ...(args.cc !== undefined && args.cc !== "" ? { cc: args.cc } : {}),
+    ...(args.bcc !== undefined && args.bcc !== "" ? { bcc: args.bcc } : {}),
+  };
+}
+
+/**
+ * The consent declaration every mail-send tool shares, given its action type (`mutates`).
+ * A sent mail cannot be recalled and nothing remains to query, so the recipient and
+ * subject ARE the pre-state; the recipient is what the write scope is checked against.
+ */
+export function mailSendConsent<T extends { readonly to: string; readonly subject: string }>(
+  mutates: string,
+): WriteToolConfig<T> {
+  return {
+    mutates,
+    recoverable: false,
+    capturePreState: (p) => Promise.resolve({ to: p.to, subject: p.subject }),
+    scopeTargetOf: (p) => ({ kind: "recipient", value: p.to }),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Shared view transformer (imap + protonmail tools.ts — viewMessage)
 // ---------------------------------------------------------------------------
@@ -259,30 +312,11 @@ export function registerEmailConnectorTools(opts: {
 
   registerWriteTool(
     `${toolPrefix}_mail_send`,
-    {
-      mutates: `${toolPrefix}.mail.send`,
-      // A sent mail cannot be recalled and nothing remains to query, so the recipient and
-      // subject ARE the pre-state.
-      recoverable: false,
-      capturePreState: (p) => Promise.resolve({ to: p.to, subject: p.subject }),
-      scopeTargetOf: (p) => ({ kind: "recipient", value: p.to }),
-    },
+    mailSendConsent(`${toolPrefix}.mail.send`),
     descriptions.send,
     sendArgs,
-    async (parsedData): Promise<McpListResult> => {
-      const parsed = { success: true as const, data: parsedData };
-      const input: { to: string; subject: string; body: string; cc?: string; bcc?: string } = {
-        to: parsed.data.to,
-        subject: parsed.data.subject,
-        body: parsed.data.body,
-      };
-      if (parsed.data.cc !== undefined && parsed.data.cc !== "") {
-        input.cc = parsed.data.cc;
-      }
-      if (parsed.data.bcc !== undefined && parsed.data.bcc !== "") {
-        input.bcc = parsed.data.bcc;
-      }
-      const res = await mailer.send(input);
+    async (args): Promise<McpListResult> => {
+      const res = await mailer.send(outgoingMail(args));
       return mcpJsonResult({
         messageId: res.messageId,
         accepted: res.accepted,