daffy-cli 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# daffy-cli
+
+CLI for the [Daffy Public API](https://docs.daffy.org). Search nonprofits, make donations, check balances, send gifts, and more — straight from the terminal.
+
+## Quick Start
+
+```bash
+cd daffy-cli
+npm install
+npm run build
+```
+
+Set your API key (get one at https://www.daffy.org/settings/api):
+
+```bash
+export DAFFY_API_KEY="your-key-here"
+```
+
+Run a command:
+
+```bash
+node dist/bin.js balance
+```
+
+## Commands
+
+### Account
+
+```bash
+daffy-cli me                          # Your profile
+daffy-cli balance                     # Your fund balance
+daffy-cli causes                      # Your selected causes
+```
+
+### Non-Profits
+
+```bash
+daffy-cli search "khan academy"       # Search by name
+daffy-cli search --cause 1            # Filter by cause ID
+daffy-cli search "schools" --page 2   # Paginate results
+daffy-cli nonprofit 261544963         # Details by EIN
+```
+
+### Donations
+
+```bash
+daffy-cli donations                   # List your donations
+daffy-cli donations --page 2          # Page through results
+daffy-cli donate --ein 261544963 --amount 25
+daffy-cli donate --ein 261544963 --amount 25 --note "Keep it up"
+daffy-cli cancel 12345                # Cancel a pending donation
+```
+
+### Contributions
+
+```bash
+daffy-cli contributions               # List your contributions
+daffy-cli contributions --page 3
+```
+
+### Gifts
+
+```bash
+daffy-cli gifts                       # List your gifts
+daffy-cli gift <code>                 # Gift details by code
+daffy-cli gift create --name "Alex" --amount 25
+```
+
+## JSON Output
+
+Append `--json` to any command to get raw API JSON instead of formatted output. Useful for scripting and piping:
+
+```bash
+daffy-cli balance --json
+daffy-cli search "khan academy" --json | jq '.items[].name'
+daffy-cli donations --json --page 2
+```
+
+## Options
+
+| Flag | Description |
+|---|---|
+| `--help`, `-h` | Show usage |
+| `--json` | Output raw JSON (works with every command) |
+| `--yes`, `-y` | Skip confirmation prompts (for `donate`, `cancel`, `gift create`) |
+| `--page N` | Page number for paginated commands |
+
+## Environment Variables
+
+| Variable | Description |
+|---|---|
+| `DAFFY_API_KEY` | **Required.** Your Daffy API key. |
+| `NO_COLOR` | Set to any value to disable colored output. |
+
+## Publishing
+
+```bash
+npm pack --dry-run   # Preview what gets published (only dist/)
+npm publish          # Publish to npm
+```
+
+After publishing:
+
+```bash
+npx daffy-cli balance
+```

package/dist/args.js

@@ -0,0 +1,43 @@
+export function getFlag(args, name) {
+    const prefix = `--${name}`;
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === prefix && i + 1 < args.length) {
+            return args[i + 1];
+        }
+        if (args[i]?.startsWith(`${prefix}=`)) {
+            return args[i].slice(prefix.length + 1);
+        }
+    }
+    return undefined;
+}
+export function requireFlag(args, name) {
+    const value = getFlag(args, name);
+    if (!value) {
+        console.error(`Error: --${name} is required.`);
+        process.exit(1);
+    }
+    return value;
+}
+const BOOLEAN_FLAGS = new Set(["--yes", "-y", "--json"]);
+export function getPositional(args, index) {
+    let pos = 0;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (BOOLEAN_FLAGS.has(arg))
+            continue;
+        if (arg.startsWith("--")) {
+            if (!arg.includes("="))
+                i++; // skip flag value unless --flag=value
+            continue;
+        }
+        if (arg.startsWith("-"))
+            continue;
+        if (pos === index)
+            return arg;
+        pos++;
+    }
+    return undefined;
+}
+export function hasFlag(args, name) {
+    return args.includes(`--${name}`);
+}

package/dist/bin.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { ApiError } from "./client.js";
+import { setJsonMode } from "./output.js";
+const HELP = `
+daffy-cli — CLI for the Daffy Public API
+
+Usage: daffy-cli <command> [options]
+
+Commands:
+  me                          Show your profile
+  user <username>             Show a user's profile
+  balance                     Show your fund balance
+  search <query> [--cause N]  Search non-profits
+  nonprofit <ein>             Show non-profit details
+  donations [--page N]        List your donations
+  donate --ein <ein> --amount <n> [--note "..."]
+                              Create a donation
+  cancel <id>                 Cancel a donation
+  contributions [--page N]    List your contributions
+  causes                      List your causes
+  gifts [--page N]            List your gifts
+  gift <code>                 Show gift details
+  gift create --name <n> --amount <n>
+                              Create a gift
+
+Options:
+  --json                      Output raw JSON instead of formatted text
+  --yes, -y                   Skip confirmation prompts
+
+Environment:
+  DAFFY_API_KEY               Your Daffy API key (required)
+                              Get one at https://www.daffy.org/settings/api
+  NO_COLOR                    Disable color output
+`;
+const commands = {
+    me: () => import("./commands/me.js"),
+    user: () => import("./commands/user.js"),
+    balance: () => import("./commands/balance.js"),
+    search: () => import("./commands/search.js"),
+    nonprofit: () => import("./commands/nonprofit.js"),
+    donations: () => import("./commands/donations.js"),
+    donate: () => import("./commands/donate.js"),
+    cancel: () => import("./commands/cancel.js"),
+    contributions: () => import("./commands/contributions.js"),
+    causes: () => import("./commands/causes.js"),
+    gifts: () => import("./commands/gifts.js"),
+    gift: () => import("./commands/gift.js"),
+};
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        console.log(HELP);
+        process.exit(0);
+    }
+    const name = args[0];
+    const loader = commands[name];
+    if (!loader) {
+        console.error(`Unknown command: ${name}\nRun "daffy-cli --help" for usage.`);
+        process.exit(1);
+    }
+    if (args.includes("--json"))
+        setJsonMode(true);
+    const mod = await loader();
+    await mod.run(args.slice(1));
+}
+main().catch((err) => {
+    if (err instanceof ApiError) {
+        console.error(`\nAPI Error (${err.status}): ${err.body}`);
+    }
+    else {
+        console.error(`\nError: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    process.exit(1);
+});

package/dist/client.js

@@ -0,0 +1,50 @@
+const BASE_URL = "https://public.daffy.org";
+export class ApiError extends Error {
+    status;
+    body;
+    constructor(status, body) {
+        super(`API error ${status}: ${body}`);
+        this.status = status;
+        this.body = body;
+        this.name = "ApiError";
+    }
+}
+function getApiKey() {
+    const key = process.env.DAFFY_API_KEY;
+    if (!key) {
+        console.error("Error: DAFFY_API_KEY environment variable is required.\n" +
+            "Get your API key at https://www.daffy.org/settings/api");
+        process.exit(1);
+    }
+    return key;
+}
+async function request(method, path, body) {
+    const url = `${BASE_URL}${path}`;
+    const headers = {
+        "X-Api-Key": getApiKey(),
+        Accept: "application/json",
+    };
+    const init = { method, headers };
+    if (body) {
+        headers["Content-Type"] = "application/json";
+        init.body = JSON.stringify(body);
+    }
+    const res = await fetch(url, init);
+    if (!res.ok) {
+        const text = await res.text();
+        throw new ApiError(res.status, text);
+    }
+    const text = await res.text();
+    if (!text)
+        return {};
+    return JSON.parse(text);
+}
+export function get(path) {
+    return request("GET", path);
+}
+export function post(path, body) {
+    return request("POST", path, body);
+}
+export function del(path) {
+    return request("DELETE", path);
+}

package/dist/commands/balance.js

@@ -0,0 +1,15 @@
+import { get } from "../client.js";
+import { renderKeyValue, formatMoney } from "../output.js";
+export async function run(_args) {
+    const bal = (await get("/v1/users/me/balance"));
+    renderKeyValue({
+        title: "Fund Balance",
+        data: bal,
+        fields: [
+            ["Available", formatMoney(bal.available_balance)],
+            ["Portfolio", formatMoney(bal.portfolio_balance)],
+            ["Pending Deposits", formatMoney(bal.pending_deposit_balance)],
+            ["Total", formatMoney(bal.amount)],
+        ],
+    });
+}

package/dist/commands/cancel.js

@@ -0,0 +1,18 @@
+import { del } from "../client.js";
+import { getPositional } from "../args.js";
+import { renderMessage } from "../output.js";
+import { confirm } from "../prompt.js";
+export async function run(args) {
+    const id = getPositional(args, 0);
+    if (!id) {
+        console.error("Usage: daffy-cli cancel <donation_id>");
+        process.exit(1);
+    }
+    const ok = await confirm(`Cancel donation ${id}?`, args);
+    if (!ok) {
+        renderMessage("Cancelled.", { cancelled: false, id });
+        return;
+    }
+    await del(`/v1/donations/${encodeURIComponent(id)}`);
+    renderMessage(`\nDonation ${id} cancelled.`, { cancelled: true, id });
+}

package/dist/commands/causes.js

@@ -0,0 +1,12 @@
+import { get } from "../client.js";
+import { renderTable } from "../output.js";
+export async function run(_args) {
+    const user = (await get("/v1/users/me"));
+    const causes = (await get(`/v1/users/${user.id}/causes`));
+    renderTable({
+        title: "Your Causes",
+        data: causes,
+        headers: ["ID", "Name"],
+        rows: causes.map((c) => [String(c.id), c.name]),
+    });
+}

package/dist/commands/contributions.js

@@ -0,0 +1,21 @@
+import { get } from "../client.js";
+import { getFlag } from "../args.js";
+import { renderTable, formatStatus } from "../output.js";
+export async function run(args) {
+    const page = getFlag(args, "page");
+    const qs = page ? `?page=${page}` : "";
+    const data = (await get(`/v1/contributions${qs}`));
+    renderTable({
+        title: "Your Contributions",
+        data,
+        headers: ["Amount", "Currency", "Type", "Status", "Date"],
+        rows: data.items.map((c) => [
+            `$${(c.units * c.valuation).toFixed(2)}`,
+            c.currency,
+            c.type.replace(/_/g, " "),
+            formatStatus(c.status),
+            c.created_at.slice(0, 10),
+        ]),
+        meta: data.meta,
+    });
+}

package/dist/commands/donate.js

@@ -0,0 +1,38 @@
+import { get, post } from "../client.js";
+import { requireFlag, getFlag } from "../args.js";
+import { renderKeyValue, formatMoney, formatStatus } from "../output.js";
+import { confirm } from "../prompt.js";
+export async function run(args) {
+    const ein = requireFlag(args, "ein");
+    const amountStr = requireFlag(args, "amount");
+    const note = getFlag(args, "note");
+    const amount = parseFloat(amountStr);
+    if (isNaN(amount) || amount <= 0) {
+        console.error("Error: --amount must be a positive number.");
+        process.exit(1);
+    }
+    const np = (await get(`/v1/non_profits/${encodeURIComponent(ein)}`));
+    console.log(`\nDonate ${formatMoney(amount)} to ${np.name} (${np.ein})`);
+    if (note)
+        console.log(`Note: "${note}"`);
+    const ok = await confirm("\nProceed?", args);
+    if (!ok) {
+        console.log("Cancelled.");
+        return;
+    }
+    const body = { ein, amount };
+    if (note)
+        body.note = note;
+    const donation = (await post("/v1/donations", body));
+    renderKeyValue({
+        title: "Donation Created",
+        data: donation,
+        fields: [
+            ["ID", donation.id],
+            ["Amount", formatMoney(donation.amount)],
+            ["Non-Profit", donation.non_profit.name],
+            ["Status", formatStatus(donation.status)],
+            ["Date", donation.created_at.slice(0, 10)],
+        ],
+    });
+}

package/dist/commands/donations.js

@@ -0,0 +1,21 @@
+import { get } from "../client.js";
+import { getFlag } from "../args.js";
+import { renderTable, formatMoney, formatStatus } from "../output.js";
+export async function run(args) {
+    const page = getFlag(args, "page");
+    const qs = page ? `?page=${page}` : "";
+    const data = (await get(`/v1/donations${qs}`));
+    renderTable({
+        title: "Your Donations",
+        data,
+        headers: ["ID", "Amount", "Non-Profit", "Status", "Date"],
+        rows: data.items.map((d) => [
+            String(d.id),
+            formatMoney(d.amount),
+            d.non_profit.name.slice(0, 30),
+            formatStatus(d.status),
+            d.created_at.slice(0, 10),
+        ]),
+        meta: data.meta,
+    });
+}

package/dist/commands/gift.js

@@ -0,0 +1,60 @@
+import { get, post } from "../client.js";
+import { getPositional, requireFlag } from "../args.js";
+import { renderKeyValue, formatMoney, formatStatus } from "../output.js";
+import { confirm } from "../prompt.js";
+export async function run(args) {
+    const first = getPositional(args, 0);
+    if (first === "create") {
+        await createGift(args);
+    }
+    else if (first) {
+        await showGift(first);
+    }
+    else {
+        console.error("Usage: daffy-cli gift <code> | daffy-cli gift create --name <n> --amount <n>");
+        process.exit(1);
+    }
+}
+async function showGift(code) {
+    const gift = (await get(`/v1/gifts/${encodeURIComponent(code)}`));
+    renderKeyValue({
+        title: "Gift Details",
+        data: gift,
+        fields: [
+            ["Code", gift.code],
+            ["Name", gift.name],
+            ["Amount", formatMoney(gift.amount)],
+            ["Status", formatStatus(gift.status)],
+            ["Claimed", gift.claimed ? "Yes" : "No"],
+            ["URL", gift.url],
+            ["Created", gift.created_at.slice(0, 10)],
+        ],
+    });
+}
+async function createGift(args) {
+    const name = requireFlag(args, "name");
+    const amountStr = requireFlag(args, "amount");
+    const amount = parseFloat(amountStr);
+    if (isNaN(amount) || amount < 18) {
+        console.error("Error: --amount must be at least 18.");
+        process.exit(1);
+    }
+    console.log(`\nCreate gift "${name}" for ${formatMoney(amount)}`);
+    const ok = await confirm("\nProceed?", args);
+    if (!ok) {
+        console.log("Cancelled.");
+        return;
+    }
+    const gift = (await post("/v1/gifts", { name, amount }));
+    renderKeyValue({
+        title: "Gift Created",
+        data: gift,
+        fields: [
+            ["Code", gift.code],
+            ["Name", gift.name],
+            ["Amount", formatMoney(gift.amount)],
+            ["Status", formatStatus(gift.status)],
+            ["URL", gift.url],
+        ],
+    });
+}

package/dist/commands/gifts.js

@@ -0,0 +1,21 @@
+import { get } from "../client.js";
+import { getFlag } from "../args.js";
+import { renderTable, formatMoney, formatStatus } from "../output.js";
+export async function run(args) {
+    const page = getFlag(args, "page");
+    const qs = page ? `?page=${page}` : "";
+    const data = (await get(`/v1/gifts${qs}`));
+    renderTable({
+        title: "Your Gifts",
+        data,
+        headers: ["Code", "Name", "Amount", "Status", "Date"],
+        rows: data.items.map((g) => [
+            g.code.slice(0, 8) + "...",
+            g.name.slice(0, 25),
+            formatMoney(g.amount),
+            formatStatus(g.status),
+            g.created_at.slice(0, 10),
+        ]),
+        meta: data.meta,
+    });
+}

package/dist/commands/me.js

@@ -0,0 +1,16 @@
+import { get } from "../client.js";
+import { renderKeyValue } from "../output.js";
+export async function run(_args) {
+    const user = (await get("/v1/users/me"));
+    renderKeyValue({
+        title: "Your Profile",
+        data: user,
+        fields: [
+            ["Name", user.name],
+            ["Username", user.slug],
+            ["Fund", user.fund_name],
+            ["Onboarding", user.onboarding_status],
+            ["Avatar", user.avatar],
+        ],
+    });
+}

package/dist/commands/nonprofit.js

@@ -0,0 +1,22 @@
+import { get } from "../client.js";
+import { getPositional } from "../args.js";
+import { renderKeyValue } from "../output.js";
+export async function run(args) {
+    const ein = getPositional(args, 0);
+    if (!ein) {
+        console.error("Usage: daffy-cli nonprofit <ein>");
+        process.exit(1);
+    }
+    const np = (await get(`/v1/non_profits/${encodeURIComponent(ein)}`));
+    renderKeyValue({
+        title: np.name,
+        data: np,
+        fields: [
+            ["EIN", np.ein],
+            ["Website", np.website],
+            ["Location", [np.city, np.state].filter(Boolean).join(", ") || null],
+            ["Cause", np.cause?.name],
+            ["URL", np.public_url],
+        ],
+    });
+}

package/dist/commands/search.js

@@ -0,0 +1,29 @@
+import { get } from "../client.js";
+import { getPositional, getFlag } from "../args.js";
+import { renderTable } from "../output.js";
+export async function run(args) {
+    const query = getPositional(args, 0);
+    const causeId = getFlag(args, "cause");
+    const page = getFlag(args, "page");
+    const params = new URLSearchParams();
+    if (query)
+        params.set("query", query);
+    if (causeId)
+        params.set("cause_id", causeId);
+    if (page)
+        params.set("page", page);
+    const qs = params.toString();
+    const data = (await get(`/v1/non_profits${qs ? `?${qs}` : ""}`));
+    renderTable({
+        title: "Non-Profit Search Results",
+        data,
+        headers: ["EIN", "Name", "City", "State"],
+        rows: data.items.map((np) => [
+            np.ein,
+            np.name.slice(0, 40),
+            np.city || "—",
+            np.state || "—",
+        ]),
+        meta: data.meta,
+    });
+}

package/dist/commands/user.js

@@ -0,0 +1,21 @@
+import { get } from "../client.js";
+import { getPositional } from "../args.js";
+import { renderKeyValue } from "../output.js";
+export async function run(args) {
+    const username = getPositional(args, 0);
+    if (!username) {
+        console.error("Usage: daffy-cli user <username>");
+        process.exit(1);
+    }
+    const user = (await get(`/v1/users/${encodeURIComponent(username)}`));
+    renderKeyValue({
+        title: user.name,
+        data: user,
+        fields: [
+            ["Username", user.slug],
+            ["Fund", user.fund_name],
+            ["Onboarding", user.onboarding_status],
+            ["Avatar", user.avatar],
+        ],
+    });
+}

package/dist/format.js

@@ -0,0 +1,59 @@
+const NO_COLOR = "NO_COLOR" in process.env;
+const BOLD = NO_COLOR ? "" : "\x1b[1m";
+const DIM = NO_COLOR ? "" : "\x1b[2m";
+const GREEN = NO_COLOR ? "" : "\x1b[32m";
+const YELLOW = NO_COLOR ? "" : "\x1b[33m";
+const CYAN = NO_COLOR ? "" : "\x1b[36m";
+const RED = NO_COLOR ? "" : "\x1b[31m";
+const RESET = NO_COLOR ? "" : "\x1b[0m";
+export function printKeyValue(pairs) {
+    const maxKey = Math.max(...pairs.map(([k]) => k.length));
+    for (const [key, value] of pairs) {
+        const display = value === null || value === undefined ? `${DIM}—${RESET}` : String(value);
+        console.log(`  ${BOLD}${key.padEnd(maxKey)}${RESET}  ${display}`);
+    }
+}
+export function printTable(headers, rows) {
+    if (rows.length === 0) {
+        console.log(`${DIM}  No results.${RESET}`);
+        return;
+    }
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
+    const header = headers.map((h, i) => h.padEnd(widths[i])).join("  ");
+    console.log(`  ${DIM}${header}${RESET}`);
+    console.log(`  ${DIM}${widths.map((w) => "─".repeat(w)).join("──")}${RESET}`);
+    for (const row of rows) {
+        const line = row.map((cell, i) => cell.padEnd(widths[i])).join("  ");
+        console.log(`  ${line}`);
+    }
+}
+export function printMeta(meta) {
+    console.log(`\n  ${DIM}Page ${meta.page} of ${meta.last} (${meta.count} total)${RESET}`);
+}
+export function formatMoney(amount) {
+    return `${GREEN}$${amount.toLocaleString("en-US", { minimumFractionDigits: 2, maximumFractionDigits: 2 })}${RESET}`;
+}
+export function formatStatus(status) {
+    switch (status) {
+        case "completed":
+        case "success":
+        case "approved":
+        case "claimed":
+            return `${GREEN}${status}${RESET}`;
+        case "pending":
+        case "scheduled":
+        case "waiting_for_funds":
+        case "new":
+            return `${YELLOW}${status}${RESET}`;
+        case "failed":
+        case "rejected":
+        case "not_completed":
+        case "denied":
+            return `${RED}${status}${RESET}`;
+        default:
+            return `${CYAN}${status}${RESET}`;
+    }
+}
+export function heading(text) {
+    console.log(`\n${BOLD}${text}${RESET}\n`);
+}

package/dist/output.js

@@ -0,0 +1,31 @@
+import { heading, printKeyValue, printTable, printMeta, formatMoney, formatStatus } from "./format.js";
+let jsonMode = false;
+export function setJsonMode(enabled) {
+    jsonMode = enabled;
+}
+export function renderKeyValue({ title, data, fields }) {
+    if (jsonMode) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    heading(title);
+    printKeyValue(fields);
+}
+export function renderTable({ title, data, headers, rows, meta }) {
+    if (jsonMode) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    heading(title);
+    printTable(headers, rows);
+    if (meta)
+        printMeta(meta);
+}
+export function renderMessage(message, data) {
+    if (jsonMode) {
+        console.log(JSON.stringify(data, null, 2));
+        return;
+    }
+    console.log(message);
+}
+export { formatMoney, formatStatus };

package/dist/prompt.js

@@ -0,0 +1,16 @@
+import * as readline from "node:readline";
+export function confirm(message, args) {
+    if (args.includes("--yes") || args.includes("-y")) {
+        return Promise.resolve(true);
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    return new Promise((resolve) => {
+        rl.question(`${message} [y/N] `, (answer) => {
+            rl.close();
+            resolve(answer.toLowerCase() === "y" || answer.toLowerCase() === "yes");
+        });
+    });
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "daffy-cli",
+  "version": "0.1.0",
+  "description": "CLI for the Daffy Public API — search nonprofits, donate, check balances, and more",
+  "type": "module",
+  "bin": {
+    "daffy-cli": "./dist/bin.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/bin.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "daffy",
+    "donations",
+    "charity",
+    "nonprofit",
+    "cli"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "@types/node": "^20.11.0"
+  }
+}