@devessentials/zfy-cli 0.1.0

package/dist/cli/index.js

@@ -0,0 +1,979 @@
+#!/usr/bin/env node
+
+// src/cli/index.ts
+import { Command as Command6 } from "commander";
+import pc4 from "picocolors";
+
+// src/cli/auth.ts
+import { Command } from "commander";
+import pc2 from "picocolors";
+
+// src/cli/config.ts
+import { mkdir, readFile, writeFile, chmod, unlink } from "fs/promises";
+import path from "path";
+import os from "os";
+function configDir() {
+  const xdg = process.env["XDG_CONFIG_HOME"];
+  if (xdg) return path.join(xdg, "zfy");
+  return path.join(os.homedir(), ".config", "zfy");
+}
+function configPath() {
+  return path.join(configDir(), "config.json");
+}
+async function readConfig() {
+  try {
+    const raw = await readFile(configPath(), "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed === "object" && parsed ? parsed : {};
+  } catch (err) {
+    if (err.code === "ENOENT") return {};
+    throw err;
+  }
+}
+async function writeConfig(cfg) {
+  const dir = configDir();
+  await mkdir(dir, { recursive: true, mode: 448 });
+  const p = configPath();
+  await writeFile(p, JSON.stringify(cfg, null, 2) + "\n", { mode: 384 });
+  await chmod(p, 384).catch(() => {
+  });
+  return p;
+}
+async function clearConfig() {
+  try {
+    await unlink(configPath());
+    return true;
+  } catch (err) {
+    if (err.code === "ENOENT") return false;
+    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;
+}
+function getConfigPath() {
+  return configPath();
+}
+
+// src/cli/util.ts
+import { createInterface } from "readline";
+import pc from "picocolors";
+
+// 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(path4, params) {
+    const url = new URL(this.baseUrl + path4);
+    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(path4, schema, params = {}) {
+    const raw = await this.request(path4, params);
+    const parsed = ListResponseSchema(schema).safeParse(raw);
+    if (!parsed.success) {
+      throw new ZeffyApiError(
+        500,
+        `Failed to parse response from ${path4}: ${parsed.error.message}`,
+        raw
+      );
+    }
+    return parsed.data;
+  }
+  async *iterate(path4, schema, params = {}) {
+    let cursor;
+    const pageLimit = typeof params["limit"] === "number" ? params["limit"] : 100;
+    while (true) {
+      const page = await this.list(path4, 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(path4, schema, params = {}, max) {
+    const out = [];
+    for await (const item of this.iterate(path4, 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/json.ts
+function formatJson(report, pretty = true) {
+  return pretty ? JSON.stringify(report, null, 2) : JSON.stringify(report);
+}
+
+// src/report/formats/csv.ts
+import { stringify } from "csv-stringify/sync";
+function formatCsv(report) {
+  const rows = report.donors.map((d) => ({
+    contact_id: d.contact_id ?? "",
+    name: d.name ?? "",
+    email: d.email ?? "",
+    address_line1: d.address?.line1 ?? "",
+    address_line2: d.address?.line2 ?? "",
+    city: d.address?.city ?? "",
+    state: d.address?.state ?? "",
+    postal_code: d.address?.postal_code ?? "",
+    country: d.address?.country ?? "",
+    donation_count: d.donation_count,
+    total_amount: d.total_amount.toFixed(2),
+    currency: report.currency,
+    year: report.year
+  }));
+  return stringify(rows, { header: true });
+}
+
+// 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 as mkdir2, writeFile as writeFile2, readFile as readFile2, stat } from "fs/promises";
+import path2 from "path";
+import PDFDocument from "pdfkit";
+var LOGO_MAX_BYTES = 2 * 1024 * 1024;
+var LOGO_MIN_PIXELS = 64;
+var LOGO_ASPECT_TOLERANCE = 0.1;
+var DEFAULT_LOGO_SIZE = 64;
+async function validateLogo(logoPath) {
+  let stats;
+  try {
+    stats = await stat(logoPath);
+  } catch {
+    return { ok: false, reason: `file not found: ${logoPath}` };
+  }
+  if (!stats.isFile()) return { ok: false, reason: `not a regular file: ${logoPath}` };
+  if (stats.size > LOGO_MAX_BYTES) {
+    return {
+      ok: false,
+      reason: `file too large (${formatBytes(stats.size)}, max ${formatBytes(LOGO_MAX_BYTES)})`
+    };
+  }
+  const head = await readFile2(logoPath);
+  const dims = readImageDimensions(head);
+  if (!dims) {
+    return { ok: false, reason: "unsupported format (only PNG and JPEG are accepted)" };
+  }
+  if (dims.width < LOGO_MIN_PIXELS || dims.height < LOGO_MIN_PIXELS) {
+    return {
+      ok: false,
+      reason: `image too small (${dims.width}\xD7${dims.height}, minimum ${LOGO_MIN_PIXELS}\xD7${LOGO_MIN_PIXELS})`
+    };
+  }
+  const ratio = dims.width / dims.height;
+  if (Math.abs(ratio - 1) > LOGO_ASPECT_TOLERANCE) {
+    return {
+      ok: false,
+      reason: `image is not square (${dims.width}\xD7${dims.height}); supply a square PNG/JPEG (e.g. 512\xD7512)`
+    };
+  }
+  return { ok: true, width: dims.width, height: dims.height, format: dims.format };
+}
+function readImageDimensions(buf) {
+  if (buf.length >= 24 && buf[0] === 137 && buf[1] === 80 && buf[2] === 78 && buf[3] === 71) {
+    return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20), format: "png" };
+  }
+  if (buf.length >= 4 && buf[0] === 255 && buf[1] === 216) {
+    let off = 2;
+    while (off < buf.length - 9) {
+      if (buf[off] !== 255) {
+        off++;
+        continue;
+      }
+      while (off < buf.length && buf[off] === 255) off++;
+      const marker = buf[off];
+      if (marker === void 0) return null;
+      off++;
+      if (marker === 217 || marker === 218) return null;
+      const segLen = buf.readUInt16BE(off);
+      const isSof = marker >= 192 && marker <= 207 && marker !== 196 && marker !== 200 && marker !== 204;
+      if (isSof && off + 7 <= buf.length) {
+        const height = buf.readUInt16BE(off + 3);
+        const width = buf.readUInt16BE(off + 5);
+        return { width, height, format: "jpeg" };
+      }
+      off += segLen;
+    }
+  }
+  return null;
+}
+function formatBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / 1024 / 1024).toFixed(2)} MB`;
+}
+var DEFAULT_RECEIPT_TEXT = "Thank you for your generous support. No goods or services were provided in exchange for these contributions. Please consult your tax advisor regarding deductibility.";
+async function writePdfReceipts(report, outDir, opts = {}) {
+  await mkdir2(outDir, { recursive: true });
+  const effective = await resolveLogoOptions(opts);
+  const written = [];
+  for (const donor of report.donors) {
+    const filename = receiptFilename(donor, report.year);
+    const fullPath = path2.join(outDir, filename);
+    const buf = await renderDonorPdf(donor, report, effective);
+    await writeFile2(fullPath, buf);
+    written.push(fullPath);
+  }
+  return written;
+}
+async function resolveLogoOptions(opts) {
+  if (!opts.logoPath) return opts;
+  const result = await validateLogo(opts.logoPath);
+  if (result.ok) return opts;
+  const out = opts.warnStream ?? process.stderr;
+  out.write(`zfy: skipping logo \u2014 ${result.reason}
+`);
+  const next = { ...opts };
+  delete next.logoPath;
+  return next;
+}
+var ACCENT = "#1f3a5f";
+var MUTED = "#6b7280";
+var RULE = "#e5e7eb";
+var ROW_ALT = "#f9fafb";
+function renderDonorPdf(donor, report, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const doc = new PDFDocument({ size: "LETTER", margin: 54 });
+    const chunks = [];
+    doc.on("data", (c) => chunks.push(c));
+    doc.on("end", () => resolve(Buffer.concat(chunks)));
+    doc.on("error", reject);
+    const orgName = opts.orgName ?? "Your Organization";
+    const left = doc.page.margins.left;
+    const right = doc.page.width - doc.page.margins.right;
+    const usable = right - left;
+    doc.rect(left, doc.y, usable, 3).fill(ACCENT);
+    doc.moveDown(0.7);
+    doc.fillColor("black");
+    const headerY = doc.y;
+    const logoSize = opts.logoSize ?? DEFAULT_LOGO_SIZE;
+    if (opts.logoPath) {
+      try {
+        doc.image(opts.logoPath, left, headerY, { fit: [logoSize, logoSize] });
+      } catch {
+      }
+    }
+    doc.font("Helvetica-Bold").fontSize(20).fillColor("black").text(orgName, left + (opts.logoPath ? logoSize + 14 : 0), headerY + 4, {
+      width: usable
+    });
+    doc.font("Helvetica").fontSize(9).fillColor(MUTED).text(`OFFICIAL DONATION RECEIPT \xB7 ${report.year}`, {
+      characterSpacing: 1.2
+    });
+    doc.moveDown(1.5);
+    doc.fillColor("black");
+    const blockTop = doc.y;
+    const colWidth = (usable - 20) / 2;
+    doc.font("Helvetica-Bold").fontSize(9).fillColor(MUTED).text("ISSUED TO", left, blockTop, {
+      width: colWidth,
+      characterSpacing: 1
+    });
+    doc.moveDown(0.3);
+    doc.font("Helvetica-Bold").fontSize(12).fillColor("black").text(donor.name ?? "(Anonymous donor)", {
+      width: colWidth
+    });
+    doc.font("Helvetica").fontSize(10).fillColor("#374151");
+    if (donor.email) doc.text(donor.email, { width: colWidth });
+    if (donor.address) {
+      const a = donor.address;
+      const addrLines = [
+        a.line1,
+        a.line2,
+        [a.city, a.state, a.postal_code].filter(Boolean).join(", "),
+        a.country
+      ].filter(Boolean);
+      for (const line of addrLines) doc.text(line, { width: colWidth });
+    }
+    const rightColX = left + colWidth + 20;
+    doc.font("Helvetica-Bold").fontSize(9).fillColor(MUTED).text("ISSUED", rightColX, blockTop, {
+      width: colWidth,
+      characterSpacing: 1
+    });
+    doc.moveDown(0.3);
+    doc.font("Helvetica").fontSize(10).fillColor("black").text(formatIssuedDate(report.generated_at), { width: colWidth });
+    doc.moveDown(0.5);
+    doc.font("Helvetica-Bold").fontSize(9).fillColor(MUTED).text("DONATIONS", {
+      width: colWidth,
+      characterSpacing: 1
+    });
+    doc.moveDown(0.3);
+    doc.font("Helvetica").fontSize(10).fillColor("black").text(`${donor.donation_count} gift${donor.donation_count === 1 ? "" : "s"} in ${report.year}`, {
+      width: colWidth
+    });
+    doc.x = left;
+    doc.y = Math.max(doc.y, blockTop + 110);
+    doc.moveDown(0.5);
+    const boxY = doc.y;
+    doc.roundedRect(left, boxY, usable, 64, 6).fill(ACCENT);
+    doc.font("Helvetica").fontSize(9).fillColor("#cbd5e1").text("TOTAL CONTRIBUTED", left + 20, boxY + 14, {
+      characterSpacing: 1.2,
+      width: usable - 40
+    });
+    doc.font("Helvetica-Bold").fontSize(28).fillColor("white").text(money2(donor.total_amount, report.currency), left + 20, boxY + 28, {
+      width: usable - 40
+    });
+    doc.y = boxY + 64;
+    doc.moveDown(1.2);
+    doc.fillColor("black");
+    doc.font("Helvetica-Bold").fontSize(10).text("Itemized gifts", left);
+    doc.moveDown(0.5);
+    const tableTop = doc.y;
+    const colDate = left;
+    const colCampaign = left + 90;
+    const colAmount = right;
+    const rowHeight = 22;
+    doc.rect(left, tableTop, usable, rowHeight).fill(ROW_ALT);
+    doc.font("Helvetica-Bold").fontSize(9).fillColor(MUTED).text("DATE", colDate + 10, tableTop + 7, { characterSpacing: 1 });
+    doc.text("CAMPAIGN", colCampaign, tableTop + 7, { characterSpacing: 1 });
+    doc.text("AMOUNT", left, tableTop + 7, {
+      width: usable - 10,
+      align: "right",
+      characterSpacing: 1
+    });
+    let rowY = tableTop + rowHeight;
+    donor.payments.forEach((p, i) => {
+      if (i % 2 === 1) {
+        doc.rect(left, rowY, usable, rowHeight).fill(ROW_ALT);
+      }
+      doc.font("Helvetica").fontSize(10).fillColor("black").text(p.date ? p.date.slice(0, 10) : "\u2014", colDate + 10, rowY + 7);
+      doc.text(p.campaign ?? "\u2014", colCampaign, rowY + 7, {
+        width: colAmount - colCampaign - 90,
+        ellipsis: true
+      });
+      doc.text(money2(p.amount, report.currency), left, rowY + 7, {
+        width: usable - 10,
+        align: "right"
+      });
+      rowY += rowHeight;
+    });
+    doc.moveTo(left, rowY).lineTo(right, rowY).strokeColor(RULE).lineWidth(0.5).stroke();
+    doc.y = rowY + 20;
+    doc.moveTo(left, doc.y).lineTo(right, doc.y).strokeColor(RULE).lineWidth(0.5).stroke();
+    doc.moveDown(0.8);
+    doc.font("Helvetica-Oblique").fontSize(8.5).fillColor(MUTED).text(opts.receiptText ?? DEFAULT_RECEIPT_TEXT, left, doc.y, {
+      width: usable,
+      align: "left",
+      lineGap: 2
+    });
+    doc.end();
+  });
+}
+function formatIssuedDate(iso) {
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return iso;
+  return d.toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric" });
+}
+function money2(n, currency) {
+  try {
+    return new Intl.NumberFormat("en-US", { style: "currency", currency }).format(n);
+  } catch {
+    return `${n.toFixed(2)} ${currency}`;
+  }
+}
+function receiptFilename(donor, year) {
+  const slug = (donor.name ?? donor.email ?? donor.contact_id ?? "anonymous").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "").slice(0, 60);
+  return `${year}-${slug || "anonymous"}.pdf`;
+}
+
+// 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/util.ts
+async function loadClientOrExit() {
+  const key = await resolveApiKey();
+  if (!key) {
+    console.error(
+      pc.red("No Zeffy API key configured.") + "\nRun " + pc.bold("zfy auth set") + " or export " + pc.bold("ZEFFY_API_KEY") + "."
+    );
+    process.exit(1);
+  }
+  return new Zeffy({ apiKey: key });
+}
+function parseDateToUnix(input, endOfDay = false) {
+  if (!input) return void 0;
+  const trimmed = input.trim();
+  if (/^\d{10}$/.test(trimmed)) return Number(trimmed);
+  if (/^\d{13}$/.test(trimmed)) return Math.floor(Number(trimmed) / 1e3);
+  const iso = /^\d{4}-\d{2}-\d{2}$/.test(trimmed) ? endOfDay ? `${trimmed}T23:59:59` : `${trimmed}T00:00:00` : trimmed;
+  const ms = Date.parse(iso);
+  if (Number.isNaN(ms)) throw new Error(`Invalid date: ${input}`);
+  return Math.floor(ms / 1e3);
+}
+async function promptHidden(question) {
+  process.stdout.write(question);
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    const rl = createInterface({ input: stdin, output: process.stdout });
+    const onData = (char) => {
+      const s = char.toString();
+      if (s === "\n" || s === "\r" || s === "\r\n") return;
+      process.stdout.write("*");
+    };
+    if (typeof stdin.setRawMode === "function") {
+      try {
+        stdin.setRawMode(false);
+      } catch {
+      }
+    }
+    stdin.on("data", onData);
+    rl.question("", (answer) => {
+      stdin.removeListener("data", onData);
+      rl.close();
+      process.stdout.write("\n");
+      resolve(answer.trim());
+    });
+  });
+}
+function printJson(value) {
+  process.stdout.write(JSON.stringify(value, null, 2) + "\n");
+}
+
+// src/cli/auth.ts
+function authCommand() {
+  const cmd = new Command("auth").description("Manage Zeffy API credentials");
+  cmd.command("set").description("Store a Zeffy API key in your local config").option("--key <key>", "API key (skips the prompt)").action(async (opts) => {
+    const key = opts.key ?? await promptHidden("Zeffy API key: ");
+    if (!key) {
+      console.error(pc2.red("No key provided."));
+      process.exit(1);
+    }
+    const path4 = await writeConfig({ api_key: key });
+    console.log(pc2.green("Saved.") + ` ${pc2.dim(path4)}`);
+  });
+  cmd.command("status").description("Verify the current API key by calling the Zeffy API").action(async () => {
+    const key = await resolveApiKey();
+    if (!key) {
+      console.log(pc2.yellow("Not authenticated. Run `zfy auth set` or set ZEFFY_API_KEY."));
+      process.exit(1);
+    }
+    const zeffy = new Zeffy({ apiKey: key });
+    try {
+      const res = await zeffy.campaigns.list({ limit: 1 });
+      const sample = res.data[0];
+      console.log(pc2.green("Authenticated."));
+      if (sample) {
+        console.log(pc2.dim(`Sample campaign: ${sample.name ?? sample.id}`));
+      } else {
+        console.log(pc2.dim("(No campaigns yet on this account.)"));
+      }
+    } catch (err) {
+      if (err instanceof ZeffyApiError) {
+        console.error(pc2.red(`API error ${err.status}: ${err.message}`));
+      } else {
+        console.error(pc2.red(String(err)));
+      }
+      process.exit(1);
+    }
+  });
+  cmd.command("clear").description("Remove the stored API key from disk").action(async () => {
+    const removed = await clearConfig();
+    console.log(removed ? pc2.green("Cleared.") : pc2.dim("No stored credential to clear."));
+  });
+  cmd.command("path").description("Print the path to the config file").action(async () => {
+    const cfg = await readConfig();
+    console.log(getConfigPath() + (cfg.api_key ? "" : pc2.dim(" (empty)")));
+  });
+  return cmd;
+}
+
+// src/cli/payments.ts
+import { Command as Command2 } from "commander";
+function paymentsCommand() {
+  const cmd = new Command2("payments").description("List Zeffy payments");
+  cmd.command("list").description("List payments with optional filters (JSON output)").option("--from <date>", "Start date (YYYY-MM-DD or Unix seconds)").option("--to <date>", "End date (YYYY-MM-DD or Unix seconds)").option("--status <status>", "Filter by payment status").option("--currency <code>", "Filter by 3-letter currency code").option("--type <type>", "Filter by payment type").option("--campaign <id>", "Filter by campaign id").option("--contact <id>", "Filter by contact id").option("--limit <n>", "Stop after N records (default: all)", (v) => Number(v)).action(async (opts) => {
+    const zeffy = await loadClientOrExit();
+    const filters = {
+      created_gte: parseDateToUnix(opts["from"]),
+      created_lte: parseDateToUnix(opts["to"], true),
+      status: opts["status"],
+      currency: opts["currency"],
+      type: opts["type"],
+      campaign_id: opts["campaign"],
+      contact_id: opts["contact"]
+    };
+    const max = typeof opts["limit"] === "number" ? opts["limit"] : void 0;
+    const data = await zeffy.payments.collect(filters, max);
+    printJson(data);
+  });
+  return cmd;
+}
+
+// src/cli/contacts.ts
+import { Command as Command3 } from "commander";
+function contactsCommand() {
+  const cmd = new Command3("contacts").description("List Zeffy contacts (donors)");
+  cmd.command("list").description("List contacts with optional filters (JSON output)").option("--email <email>", "Filter by email").option("--created-from <date>", "Created at or after (YYYY-MM-DD)").option("--created-to <date>", "Created at or before (YYYY-MM-DD)").option("--updated-from <date>", "Updated at or after (YYYY-MM-DD)").option("--updated-to <date>", "Updated at or before (YYYY-MM-DD)").option("--limit <n>", "Stop after N records (default: all)", (v) => Number(v)).action(async (opts) => {
+    const zeffy = await loadClientOrExit();
+    const filters = {
+      email: opts["email"],
+      created_gte: parseDateToUnix(opts["createdFrom"]),
+      created_lte: parseDateToUnix(opts["createdTo"], true),
+      updated_gte: parseDateToUnix(opts["updatedFrom"]),
+      updated_lte: parseDateToUnix(opts["updatedTo"], true)
+    };
+    const max = typeof opts["limit"] === "number" ? opts["limit"] : void 0;
+    const data = await zeffy.contacts.collect(filters, max);
+    printJson(data);
+  });
+  return cmd;
+}
+
+// src/cli/campaigns.ts
+import { Command as Command4 } from "commander";
+function campaignsCommand() {
+  const cmd = new Command4("campaigns").description("List Zeffy campaigns");
+  cmd.command("list").description("List campaigns (JSON output)").option("--created-from <date>", "Created at or after (YYYY-MM-DD)").option("--created-to <date>", "Created at or before (YYYY-MM-DD)").option("--limit <n>", "Stop after N records", (v) => Number(v)).action(async (opts) => {
+    const zeffy = await loadClientOrExit();
+    const filters = {
+      created_gte: parseDateToUnix(opts["createdFrom"]),
+      created_lte: parseDateToUnix(opts["createdTo"], true)
+    };
+    const max = typeof opts["limit"] === "number" ? opts["limit"] : void 0;
+    const data = await zeffy.campaigns.collect(filters, max);
+    printJson(data);
+  });
+  return cmd;
+}
+
+// src/cli/report.ts
+import { Command as Command5 } from "commander";
+import { writeFile as writeFile3, mkdir as mkdir3 } from "fs/promises";
+import path3 from "path";
+import pc3 from "picocolors";
+function reportCommand() {
+  const cmd = new Command5("report").description("Generate donation reports");
+  cmd.command("eoy").description("End-of-year donation report aggregated per donor").requiredOption("--year <year>", "Calendar year, e.g. 2025", (v) => Number(v)).option("--format <format>", "json | csv | md | pdf", "json").option("--out <path>", "Output file (or directory, for pdf). Defaults to stdout.").option("--timezone <tz>", "IANA timezone (e.g. America/Los_Angeles). Defaults to system tz.").option("--currency <code>", "Filter to a single currency code").option("--status <status>", "Filter to a single payment status (e.g. succeeded)").option("--include-refunded", "Include refunded payments (excluded by default)").option("--top <n>", "Markdown: limit donor table to top N", (v) => Number(v)).option("--org <name>", "PDF: organization name for the header").option("--logo <path>", "PDF: path to a square PNG/JPEG logo (~512\xD7512, max 2 MB)").option("--logo-size <pt>", "PDF: edge length of the square logo slot in points (default 64)", (v) => Number(v)).option("--receipt-text <text>", "PDF: override receipt boilerplate").action(async (opts) => {
+    const year = opts["year"];
+    if (!Number.isInteger(year) || year < 1900 || year > 9999) {
+      console.error(pc3.red(`Invalid --year: ${opts["year"]}`));
+      process.exit(1);
+    }
+    const format = String(opts["format"] ?? "json").toLowerCase();
+    const zeffy = await loadClientOrExit();
+    const report = await buildEoyReport(zeffy, {
+      year,
+      timezone: opts["timezone"],
+      currency: opts["currency"],
+      status: opts["status"],
+      excludeRefunded: !opts["includeRefunded"]
+    });
+    const outPath = opts["out"];
+    if (format === "pdf") {
+      const dir = outPath ?? path3.join(process.cwd(), `eoy-${year}-receipts`);
+      const written = await writePdfReceipts(report, dir, {
+        orgName: opts["org"],
+        receiptText: opts["receiptText"],
+        logoPath: opts["logo"],
+        logoSize: typeof opts["logoSize"] === "number" ? opts["logoSize"] : void 0
+      });
+      console.error(pc3.green(`Wrote ${written.length} receipts to ${dir}`));
+      return;
+    }
+    let body;
+    if (format === "csv") body = formatCsv(report);
+    else if (format === "md" || format === "markdown") {
+      const topN = typeof opts["top"] === "number" ? opts["top"] : 25;
+      body = formatMarkdown(report, topN);
+    } else if (format === "json") body = formatJson(report);
+    else {
+      console.error(pc3.red(`Unknown --format: ${format}`));
+      process.exit(1);
+    }
+    if (outPath) {
+      await mkdir3(path3.dirname(path3.resolve(outPath)), { recursive: true });
+      await writeFile3(outPath, body);
+      console.error(pc3.green(`Wrote ${outPath}`));
+    } else {
+      process.stdout.write(body.endsWith("\n") ? body : body + "\n");
+    }
+  });
+  return cmd;
+}
+
+// src/cli/index.ts
+var program = new Command6();
+program.name("zfy").description("Third-party CLI for the Zeffy API \u2014 donations data for nonprofits and AI agents.").version("0.1.0");
+program.addCommand(authCommand());
+program.addCommand(paymentsCommand());
+program.addCommand(contactsCommand());
+program.addCommand(campaignsCommand());
+program.addCommand(reportCommand());
+program.parseAsync(process.argv).catch((err) => {
+  if (err instanceof ZeffyApiError) {
+    console.error(pc4.red(`Zeffy API error ${err.status}: ${err.message}`));
+    if (err.body && process.env["DEBUG"]) console.error(err.body);
+  } else {
+    console.error(pc4.red(err instanceof Error ? err.message : String(err)));
+  }
+  process.exit(1);
+});