@devessentials/zfy-cli 0.1.0

package/dist/mcp/server.js

@@ -0,0 +1,593 @@
+#!/usr/bin/env node
+
+// src/mcp/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z as z2 } from "zod";
+
+// src/sdk/schemas.ts
+import { z } from "zod";
+var dateOrUnix = z.union([z.string(), z.number()]);
+var AddressSchema = z.object({
+  line1: z.string().nullish(),
+  line2: z.string().nullish(),
+  city: z.string().nullish(),
+  state: z.string().nullish(),
+  postal_code: z.string().nullish(),
+  country: z.string().nullish()
+}).partial().passthrough();
+var ContactSchema = z.object({
+  id: z.string(),
+  email: z.string().nullish(),
+  first_name: z.string().nullish(),
+  last_name: z.string().nullish(),
+  name: z.string().nullish(),
+  phone: z.string().nullish(),
+  address: AddressSchema.nullish(),
+  created: dateOrUnix.nullish(),
+  updated: dateOrUnix.nullish()
+}).passthrough();
+var CampaignSchema = z.object({
+  id: z.string(),
+  name: z.string().nullish(),
+  type: z.string().nullish(),
+  status: z.string().nullish(),
+  goal: z.number().nullish(),
+  raised: z.number().nullish(),
+  currency: z.string().nullish(),
+  created: dateOrUnix.nullish()
+}).passthrough();
+var PaymentLineItemSchema = z.object({
+  id: z.string().nullish(),
+  description: z.string().nullish(),
+  amount: z.number().nullish(),
+  quantity: z.number().nullish()
+}).passthrough();
+var PaymentSchema = z.object({
+  id: z.string(),
+  amount: z.number(),
+  currency: z.string().nullish(),
+  status: z.string().nullish(),
+  type: z.string().nullish(),
+  contact_id: z.string().nullish(),
+  contact: ContactSchema.nullish(),
+  campaign_id: z.string().nullish(),
+  campaign: CampaignSchema.nullish(),
+  line_items: z.array(PaymentLineItemSchema).nullish(),
+  tax_receipt_eligible_amount: z.number().nullish(),
+  refunded: z.boolean().nullish(),
+  refunded_amount: z.number().nullish(),
+  created: dateOrUnix
+}).passthrough();
+var ListResponseSchema = (item) => z.object({
+  data: z.array(item),
+  has_more: z.boolean(),
+  next_cursor: z.string().nullish()
+});
+
+// src/sdk/client.ts
+var ZeffyApiError = class extends Error {
+  constructor(status, message, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "ZeffyApiError";
+  }
+  status;
+  body;
+};
+var ZeffyClient = class {
+  apiKey;
+  baseUrl;
+  maxRetries;
+  fetchFn;
+  requestTimestamps = [];
+  rateLimit;
+  constructor(opts) {
+    if (!opts.apiKey) throw new Error("ZeffyClient: apiKey is required");
+    this.apiKey = opts.apiKey;
+    this.baseUrl = (opts.baseUrl ?? "https://api.zeffy.com/api/v1").replace(/\/+$/, "");
+    this.maxRetries = opts.maxRetries ?? 5;
+    this.fetchFn = opts.fetch ?? globalThis.fetch;
+    this.rateLimit = opts.rateLimitPerMinute ?? 90;
+  }
+  async throttle() {
+    const now = Date.now();
+    const windowStart = now - 6e4;
+    this.requestTimestamps = this.requestTimestamps.filter((t) => t > windowStart);
+    if (this.requestTimestamps.length >= this.rateLimit) {
+      const oldest = this.requestTimestamps[0];
+      if (oldest !== void 0) {
+        const waitMs = 6e4 - (now - oldest) + 50;
+        await sleep(waitMs);
+      }
+    }
+    this.requestTimestamps.push(Date.now());
+  }
+  async request(path3, params) {
+    const url = new URL(this.baseUrl + path3);
+    if (params) {
+      for (const [k, v] of Object.entries(params)) {
+        if (v === void 0 || v === null) continue;
+        url.searchParams.set(k, String(v));
+      }
+    }
+    let attempt = 0;
+    while (true) {
+      await this.throttle();
+      const res = await this.fetchFn(url.toString(), {
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          Accept: "application/json",
+          "User-Agent": "zfy-cli/0.1.0 (+https://github.com/EssentialsDev/zfy-cli)"
+        }
+      });
+      if (res.ok) {
+        return await res.json();
+      }
+      const retryable = res.status === 429 || res.status >= 500 && res.status < 600;
+      if (retryable && attempt < this.maxRetries) {
+        const retryAfter = parseRetryAfter(res.headers.get("retry-after"));
+        const backoff = retryAfter ?? Math.min(2 ** attempt * 500, 3e4);
+        await sleep(backoff);
+        attempt++;
+        continue;
+      }
+      let body;
+      try {
+        body = await res.json();
+      } catch {
+        body = await res.text().catch(() => void 0);
+      }
+      const msg = typeof body === "object" && body && "message" in body ? String(body.message) : res.statusText || `HTTP ${res.status}`;
+      throw new ZeffyApiError(res.status, msg, body);
+    }
+  }
+  async list(path3, schema, params = {}) {
+    const raw = await this.request(path3, params);
+    const parsed = ListResponseSchema(schema).safeParse(raw);
+    if (!parsed.success) {
+      throw new ZeffyApiError(
+        500,
+        `Failed to parse response from ${path3}: ${parsed.error.message}`,
+        raw
+      );
+    }
+    return parsed.data;
+  }
+  async *iterate(path3, schema, params = {}) {
+    let cursor;
+    const pageLimit = typeof params["limit"] === "number" ? params["limit"] : 100;
+    while (true) {
+      const page = await this.list(path3, schema, {
+        ...params,
+        limit: pageLimit,
+        starting_after: cursor
+      });
+      for (const item of page.data) yield item;
+      if (!page.has_more || !page.next_cursor) return;
+      cursor = page.next_cursor;
+    }
+  }
+  async collect(path3, schema, params = {}, max) {
+    const out = [];
+    for await (const item of this.iterate(path3, schema, params)) {
+      out.push(item);
+      if (max !== void 0 && out.length >= max) break;
+    }
+    return out;
+  }
+};
+function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+function parseRetryAfter(header) {
+  if (!header) return void 0;
+  const secs = Number(header);
+  if (Number.isFinite(secs)) return Math.max(0, secs * 1e3);
+  const dateMs = Date.parse(header);
+  if (!Number.isNaN(dateMs)) return Math.max(0, dateMs - Date.now());
+  return void 0;
+}
+
+// src/sdk/payments.ts
+function toParams(f) {
+  const out = {
+    limit: f.limit,
+    starting_after: f.starting_after,
+    currency: f.currency,
+    status: f.status,
+    type: f.type,
+    contact_id: f.contact_id,
+    campaign_id: f.campaign_id
+  };
+  if (f.created_gte !== void 0) out["created[gte]"] = f.created_gte;
+  if (f.created_lte !== void 0) out["created[lte]"] = f.created_lte;
+  return out;
+}
+var PaymentsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  list(filters = {}) {
+    return this.client.list("/payments", PaymentSchema, toParams(filters));
+  }
+  iterate(filters = {}) {
+    return this.client.iterate("/payments", PaymentSchema, toParams(filters));
+  }
+  collect(filters = {}, max) {
+    return this.client.collect("/payments", PaymentSchema, toParams(filters), max);
+  }
+};
+
+// src/sdk/contacts.ts
+function toParams2(f) {
+  const out = {
+    limit: f.limit,
+    starting_after: f.starting_after,
+    email: f.email
+  };
+  if (f.created_gte !== void 0) out["created[gte]"] = f.created_gte;
+  if (f.created_lte !== void 0) out["created[lte]"] = f.created_lte;
+  if (f.updated_gte !== void 0) out["updated[gte]"] = f.updated_gte;
+  if (f.updated_lte !== void 0) out["updated[lte]"] = f.updated_lte;
+  return out;
+}
+var ContactsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  list(filters = {}) {
+    return this.client.list("/contacts", ContactSchema, toParams2(filters));
+  }
+  iterate(filters = {}) {
+    return this.client.iterate("/contacts", ContactSchema, toParams2(filters));
+  }
+  collect(filters = {}, max) {
+    return this.client.collect("/contacts", ContactSchema, toParams2(filters), max);
+  }
+};
+
+// src/sdk/campaigns.ts
+function toParams3(f) {
+  const out = {
+    limit: f.limit,
+    starting_after: f.starting_after
+  };
+  if (f.created_gte !== void 0) out["created[gte]"] = f.created_gte;
+  if (f.created_lte !== void 0) out["created[lte]"] = f.created_lte;
+  return out;
+}
+var CampaignsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  list(filters = {}) {
+    return this.client.list("/campaigns", CampaignSchema, toParams3(filters));
+  }
+  iterate(filters = {}) {
+    return this.client.iterate("/campaigns", CampaignSchema, toParams3(filters));
+  }
+  collect(filters = {}, max) {
+    return this.client.collect("/campaigns", CampaignSchema, toParams3(filters), max);
+  }
+};
+
+// src/report/eoy.ts
+import { fromZonedTime } from "date-fns-tz";
+async function buildEoyReport(zeffy, opts) {
+  const tz = opts.timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC";
+  const start = fromZonedTime(`${opts.year}-01-01T00:00:00`, tz);
+  const end = fromZonedTime(`${opts.year + 1}-01-01T00:00:00`, tz);
+  const created_gte = Math.floor(start.getTime() / 1e3);
+  const created_lte = Math.floor(end.getTime() / 1e3) - 1;
+  const excludeRefunded = opts.excludeRefunded ?? true;
+  const payments = [];
+  for await (const p of zeffy.payments.iterate({
+    created_gte,
+    created_lte,
+    currency: opts.currency,
+    status: opts.status
+  })) {
+    if (excludeRefunded && p.refunded) continue;
+    payments.push(p);
+  }
+  const donorMap = /* @__PURE__ */ new Map();
+  let currency = opts.currency ?? "USD";
+  for (const p of payments) {
+    if (p.currency) currency = p.currency;
+    const contactId = p.contact_id ?? p.contact?.id ?? null;
+    const key = contactId ?? `__anon__:${p.id}`;
+    const dateIso = toIsoString(p.created);
+    let donor = donorMap.get(key);
+    if (!donor) {
+      const c = p.contact;
+      donor = {
+        contact_id: contactId,
+        name: contactName(c),
+        email: c?.email ?? null,
+        address: c?.address ?? null,
+        total_amount: 0,
+        donation_count: 0,
+        payments: []
+      };
+      donorMap.set(key, donor);
+    }
+    donor.total_amount += p.amount;
+    donor.donation_count += 1;
+    donor.payments.push({
+      id: p.id,
+      date: dateIso,
+      amount: p.amount,
+      campaign: p.campaign?.name ?? null,
+      campaign_id: p.campaign_id ?? p.campaign?.id ?? null,
+      status: p.status ?? null
+    });
+  }
+  const donors = [...donorMap.values()].sort((a, b) => b.total_amount - a.total_amount);
+  const totals = donors.reduce(
+    (acc, d) => {
+      acc.total_amount += d.total_amount;
+      acc.donation_count += d.donation_count;
+      acc.donor_count += 1;
+      return acc;
+    },
+    { total_amount: 0, donor_count: 0, donation_count: 0 }
+  );
+  return {
+    year: opts.year,
+    timezone: tz,
+    currency,
+    generated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    totals,
+    donors
+  };
+}
+function contactName(c) {
+  if (!c) return null;
+  if (c.name) return c.name;
+  const parts = [c.first_name, c.last_name].filter(Boolean);
+  return parts.length ? parts.join(" ") : null;
+}
+function toIsoString(v) {
+  if (v == null) return "";
+  if (typeof v === "number") return new Date(v * 1e3).toISOString();
+  const n = Number(v);
+  if (Number.isFinite(n) && String(n) === v) return new Date(n * 1e3).toISOString();
+  return new Date(v).toISOString();
+}
+
+// src/report/formats/csv.ts
+import { stringify } from "csv-stringify/sync";
+
+// src/report/formats/md.ts
+function formatMarkdown(report, topN = 25) {
+  const lines = [];
+  const cur = report.currency;
+  lines.push(`# Donation report \u2014 ${report.year}`);
+  lines.push("");
+  lines.push(`Generated ${report.generated_at} \xB7 Timezone ${report.timezone}`);
+  lines.push("");
+  lines.push(`## Totals`);
+  lines.push(`- Total raised: ${money(report.totals.total_amount, cur)}`);
+  lines.push(`- Unique donors: ${report.totals.donor_count}`);
+  lines.push(`- Total donations: ${report.totals.donation_count}`);
+  if (report.totals.donor_count > 0) {
+    const avg = report.totals.total_amount / report.totals.donor_count;
+    lines.push(`- Average per donor: ${money(avg, cur)}`);
+  }
+  lines.push("");
+  lines.push(`## Top ${Math.min(topN, report.donors.length)} donors`);
+  lines.push("");
+  lines.push("| # | Donor | Email | Gifts | Total |");
+  lines.push("| --- | --- | --- | ---: | ---: |");
+  report.donors.slice(0, topN).forEach((d, i) => {
+    lines.push(
+      `| ${i + 1} | ${escape(d.name ?? "(anonymous)")} | ${escape(d.email ?? "")} | ${d.donation_count} | ${money(d.total_amount, cur)} |`
+    );
+  });
+  if (report.donors.length > topN) {
+    lines.push("");
+    lines.push(`_\u2026and ${report.donors.length - topN} more donors._`);
+  }
+  return lines.join("\n") + "\n";
+}
+function money(n, currency) {
+  try {
+    return new Intl.NumberFormat("en-US", { style: "currency", currency }).format(n);
+  } catch {
+    return `${n.toFixed(2)} ${currency}`;
+  }
+}
+function escape(s) {
+  return s.replace(/\|/g, "\\|");
+}
+
+// src/report/formats/pdf.ts
+import { mkdir, writeFile, readFile, stat } from "fs/promises";
+import path from "path";
+import PDFDocument from "pdfkit";
+var LOGO_MAX_BYTES = 2 * 1024 * 1024;
+
+// src/sdk/index.ts
+var Zeffy = class {
+  client;
+  payments;
+  contacts;
+  campaigns;
+  constructor(opts) {
+    const options = typeof opts === "string" ? { apiKey: opts } : opts;
+    this.client = new ZeffyClient(options);
+    this.payments = new PaymentsResource(this.client);
+    this.contacts = new ContactsResource(this.client);
+    this.campaigns = new CampaignsResource(this.client);
+  }
+};
+
+// src/cli/config.ts
+import { mkdir as mkdir2, readFile as readFile2, writeFile as writeFile2, chmod, unlink } from "fs/promises";
+import path2 from "path";
+import os from "os";
+function configDir() {
+  const xdg = process.env["XDG_CONFIG_HOME"];
+  if (xdg) return path2.join(xdg, "zfy");
+  return path2.join(os.homedir(), ".config", "zfy");
+}
+function configPath() {
+  return path2.join(configDir(), "config.json");
+}
+async function readConfig() {
+  try {
+    const raw = await readFile2(configPath(), "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "object" && parsed ? parsed : {};
+  } catch (err) {
+    if (err.code === "ENOENT") return {};
+    throw err;
+  }
+}
+async function resolveApiKey() {
+  const env = process.env["ZEFFY_API_KEY"];
+  if (env && env.trim()) return env.trim();
+  const cfg = await readConfig();
+  return cfg.api_key;
+}
+
+// src/mcp/server.ts
+var DEFAULT_MAX = 1e3;
+async function getClient() {
+  const key = await resolveApiKey();
+  if (!key) {
+    throw new Error(
+      "Zeffy API key not configured. Set ZEFFY_API_KEY in the MCP server env, or run `zfy auth set` on this machine."
+    );
+  }
+  return new Zeffy({ apiKey: key });
+}
+function dateToUnix(d) {
+  if (!d) return void 0;
+  const ms = Date.parse(/^\d{4}-\d{2}-\d{2}$/.test(d) ? `${d}T00:00:00Z` : d);
+  if (Number.isNaN(ms)) throw new Error(`Invalid date: ${d}`);
+  return Math.floor(ms / 1e3);
+}
+function asText(value) {
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+var server = new McpServer({ name: "zfy", version: "0.1.0" });
+server.registerTool(
+  "zeffy_list_payments",
+  {
+    description: "List Zeffy donations (payments). Cursor pagination is handled automatically \u2014 use `limit` to cap result size.",
+    inputSchema: {
+      from: z2.string().optional().describe("Earliest date (YYYY-MM-DD or ISO datetime)"),
+      to: z2.string().optional().describe("Latest date (YYYY-MM-DD or ISO datetime)"),
+      status: z2.string().optional(),
+      currency: z2.string().optional(),
+      type: z2.string().optional(),
+      campaign_id: z2.string().optional(),
+      contact_id: z2.string().optional(),
+      limit: z2.number().int().positive().max(5e3).default(DEFAULT_MAX)
+    }
+  },
+  async (args) => {
+    const zeffy = await getClient();
+    const data = await zeffy.payments.collect(
+      {
+        created_gte: dateToUnix(args.from),
+        created_lte: dateToUnix(args.to),
+        status: args.status,
+        currency: args.currency,
+        type: args.type,
+        campaign_id: args.campaign_id,
+        contact_id: args.contact_id
+      },
+      args.limit
+    );
+    return asText(data);
+  }
+);
+server.registerTool(
+  "zeffy_list_contacts",
+  {
+    description: "List Zeffy contacts (donors). Use `email` to look up a single donor.",
+    inputSchema: {
+      email: z2.string().optional(),
+      created_from: z2.string().optional(),
+      created_to: z2.string().optional(),
+      updated_from: z2.string().optional(),
+      updated_to: z2.string().optional(),
+      limit: z2.number().int().positive().max(5e3).default(DEFAULT_MAX)
+    }
+  },
+  async (args) => {
+    const zeffy = await getClient();
+    const data = await zeffy.contacts.collect(
+      {
+        email: args.email,
+        created_gte: dateToUnix(args.created_from),
+        created_lte: dateToUnix(args.created_to),
+        updated_gte: dateToUnix(args.updated_from),
+        updated_lte: dateToUnix(args.updated_to)
+      },
+      args.limit
+    );
+    return asText(data);
+  }
+);
+server.registerTool(
+  "zeffy_list_campaigns",
+  {
+    description: "List Zeffy campaigns (donation forms, events, etc.).",
+    inputSchema: {
+      created_from: z2.string().optional(),
+      created_to: z2.string().optional(),
+      limit: z2.number().int().positive().max(5e3).default(DEFAULT_MAX)
+    }
+  },
+  async (args) => {
+    const zeffy = await getClient();
+    const data = await zeffy.campaigns.collect(
+      {
+        created_gte: dateToUnix(args.created_from),
+        created_lte: dateToUnix(args.created_to)
+      },
+      args.limit
+    );
+    return asText(data);
+  }
+);
+server.registerTool(
+  "zeffy_eoy_report",
+  {
+    description: "Generate an end-of-year donation report aggregated per donor. Returns JSON, or a Markdown summary if format='markdown'.",
+    inputSchema: {
+      year: z2.number().int().min(1900).max(9999),
+      format: z2.enum(["json", "markdown"]).default("json"),
+      timezone: z2.string().optional().describe("IANA timezone (default: UTC)"),
+      currency: z2.string().optional(),
+      status: z2.string().optional(),
+      include_refunded: z2.boolean().default(false),
+      top: z2.number().int().positive().max(500).default(25)
+    }
+  },
+  async (args) => {
+    const zeffy = await getClient();
+    const report = await buildEoyReport(zeffy, {
+      year: args.year,
+      timezone: args.timezone ?? "UTC",
+      currency: args.currency,
+      status: args.status,
+      excludeRefunded: !args.include_refunded
+    });
+    const text = args.format === "markdown" ? formatMarkdown(report, args.top) : JSON.stringify(report, null, 2);
+    return { content: [{ type: "text", text }] };
+  }
+);
+var transport = new StdioServerTransport();
+server.connect(transport).catch((err) => {
+  console.error(`zfy-mcp failed to start: ${err instanceof Error ? err.message : String(err)}`);
+  process.exit(1);
+});