@rmdes/indiekit-endpoint-donation 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,87 @@
+# @rmdes/indiekit-endpoint-donation
+
+Stripe-backed donation endpoint for Indiekit. Treats Stripe Products as
+campaigns, Stripe Checkout Sessions / PaymentIntents as donations,
+captures donor consent via Stripe Payment Link custom fields, and feeds
+a static Eleventy site with live JSON + rebuild triggers.
+
+## Status
+
+**Alpha — scaffold only.** Routes and views are in place; webhook
+verification, sync scheduling, and storage are implemented. Tested
+end-to-end is still TODO. Do not connect a live Stripe key against a
+production webhook URL yet.
+
+See [CLAUDE.md](./CLAUDE.md) for architecture, data model, and routes.
+
+## Install
+
+```bash
+npm install @rmdes/indiekit-endpoint-donation stripe
+```
+
+```js
+// indiekit.config.js
+import DonationEndpoint from "@rmdes/indiekit-endpoint-donation";
+
+export default {
+  plugins: [
+    "@indiekit/endpoint-auth",
+    new DonationEndpoint({
+      mountPath: "/donation",
+      // siteDir + rebuildTrigger usually picked up from env vars
+    }),
+    // ...
+  ],
+};
+```
+
+## Environment
+
+```bash
+STRIPE_SECRET_KEY=sk_live_…
+STRIPE_WEBHOOK_SECRET=whsec_…
+INDIEKIT_DONATION_SITE_DIR=/app/data/eleventy-site
+INDIEKIT_DONATION_REBUILD_TRIGGER=/app/data/eleventy-site/.rebuild-trigger
+INDIEKIT_DONATION_CURRENCY=EUR
+```
+
+## Stripe setup (one-time)
+
+1. Create a **Product** per campaign in Stripe Dashboard. Set product
+   metadata: `goal_cents`, `subtitle`, `campaign_starts`, `campaign_ends`,
+   `display_order`.
+2. Create a **Payment Link** for each Product. Add 3 custom fields:
+   - `consent` — dropdown: "Oui, avec mon nom" / "Oui, anonymement" /
+     "Non, garder privé" (required)
+   - `display_name` — text, optional (≤60 chars)
+   - `message` — text, optional (≤200 chars)
+3. Create a **Webhook endpoint** in Stripe pointing at
+   `https://yoursite.example/donation/webhook`. Subscribe to:
+   - `checkout.session.completed`
+   - `checkout.session.async_payment_succeeded`
+   - `invoice.paid`
+   - `charge.refunded`
+4. Copy the webhook signing secret (`whsec_…`) into `STRIPE_WEBHOOK_SECRET`.
+
+## Admin UI
+
+- `/donation` — dashboard (lifetime stats, recent donations, active campaigns)
+- `/donation/donations` — full donation list with filters
+- `/donation/donations/:id` — edit a single donation (display name, message, consent)
+- `/donation/campaigns` — cached campaign list (synced from Stripe)
+- `/donation/manual` — record an offline donation (cash, bank transfer)
+- `POST /donation/sync` — trigger an immediate Stripe Product sync
+- `POST /donation/rebuild` — touch the rebuild trigger file
+
+## Public API
+
+- `GET /donation/stats.json` — full live state (campaigns + recent
+  donations, donor names hidden if consent is false). Cache-Control: 60s.
+- `GET /donation/stats/:campaignId.json` — single-campaign totals.
+- `POST /donation/webhook` — Stripe webhook receiver (rejects without
+  signature).
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,147 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import express from "express";
+import { waitForReady } from "@rmdes/indiekit-startup-gate";
+
+import { dashboardController } from "./lib/controllers/dashboard.js";
+import { donationsController } from "./lib/controllers/donations.js";
+import { campaignsController } from "./lib/controllers/campaigns.js";
+import { manualController } from "./lib/controllers/manual.js";
+import { syncController } from "./lib/controllers/sync.js";
+import { consentController } from "./lib/controllers/consent.js";
+import { webhookController } from "./lib/controllers/webhook.js";
+import { statsController } from "./lib/controllers/stats.js";
+
+import { createIndexes } from "./lib/storage/indexes.js";
+import { startStripeSync, stopStripeSync } from "./lib/sync/scheduler.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const defaults = {
+  mountPath: "/donation",
+  // Hourly background sync of Stripe Products → campaigns cache.
+  syncInterval: 3600000,
+  // Site directory for rebuild trigger (file touch).
+  siteDir: process.env.INDIEKIT_DONATION_SITE_DIR ?? "/app/data/eleventy-site",
+  rebuildTrigger: process.env.INDIEKIT_DONATION_REBUILD_TRIGGER
+    ?? "/app/data/eleventy-site/.rebuild-trigger",
+  currency: process.env.INDIEKIT_DONATION_CURRENCY ?? "EUR",
+  // Stripe credentials from env. Required at runtime; checked on init.
+  stripeSecretKey: process.env.STRIPE_SECRET_KEY,
+  stripeWebhookSecret: process.env.STRIPE_WEBHOOK_SECRET,
+};
+
+export default class DonationEndpoint {
+  name = "Donation endpoint";
+
+  constructor(options = {}) {
+    this.options = { ...defaults, ...options };
+    this.mountPath = this.options.mountPath;
+  }
+
+  get localesDirectory() {
+    return path.join(__dirname, "locales");
+  }
+
+  get viewsDirectory() {
+    return path.join(__dirname, "views");
+  }
+
+  // Adds "Dons" to the admin sidebar.
+  get navigationItems() {
+    return {
+      href: this.options.mountPath,
+      text: "donation.title",
+      requiresDatabase: true,
+    };
+  }
+
+  // Adds a quick-action tile on the indiekit dashboard.
+  get shortcutItems() {
+    return {
+      url: path.join(this.options.mountPath, "manual"),
+      name: "donation.manual.action",
+      iconName: "createPost",
+      requiresDatabase: true,
+    };
+  }
+
+  // Authenticated admin routes — wrapped by indiekit's session middleware.
+  get routes() {
+    const router = express.Router();
+
+    router.get("/", dashboardController.get);
+
+    router.get("/donations", donationsController.list);
+    router.get("/donations/:id", donationsController.detail);
+    router.post("/donations/:id/edit", donationsController.update);
+    router.post("/donations/:id/consent", consentController.toggle);
+    router.post("/donations/:id/delete", donationsController.remove);
+
+    router.get("/campaigns", campaignsController.list);
+    router.get("/campaigns/:id", campaignsController.detail);
+    router.post("/campaigns/:id/edit", campaignsController.update);
+
+    router.get("/manual", manualController.form);
+    router.post("/manual", manualController.create);
+
+    router.post("/sync", syncController.runOnce);
+    router.post("/rebuild", syncController.triggerRebuild);
+
+    return router;
+  }
+
+  // Public routes — Stripe webhook + JSON stats consumed by the static site.
+  get routesPublic() {
+    const router = express.Router();
+
+    // Stripe sends raw body; mount express.raw() at this route only so
+    // signature verification works. Indiekit's global JSON parser would
+    // otherwise consume the body before we can verify the signature.
+    router.post(
+      "/webhook",
+      express.raw({ type: "application/json" }),
+      webhookController.receive,
+    );
+
+    router.get("/stats.json", statsController.json);
+    router.get("/stats/:campaignId.json", statsController.byCampaign);
+
+    return router;
+  }
+
+  init(Indiekit) {
+    Indiekit.addEndpoint(this);
+
+    Indiekit.addCollection("donations");
+    Indiekit.addCollection("campaignsCache");
+    Indiekit.addCollection("donationMeta");
+
+    // Make config + DB accessor available to controllers via application locals.
+    Indiekit.config.application.donationConfig = this.options;
+    Indiekit.config.application.donationEndpoint = this.mountPath;
+    Indiekit.config.application.getDonationDb = () => Indiekit.database;
+
+    // Background Stripe Product sync — only starts after Mongo is connected.
+    if (Indiekit.config.application.mongodbUrl && this.options.stripeSecretKey) {
+      this._stopGate = waitForReady(
+        async () => {
+          await createIndexes(Indiekit);
+          startStripeSync(Indiekit, this.options);
+        },
+        { label: "Donation" },
+      );
+    } else if (!this.options.stripeSecretKey) {
+      console.warn(
+        "[Donation] STRIPE_SECRET_KEY not set — admin UI will load but " +
+        "campaigns sync and webhook verification are disabled.",
+      );
+    }
+  }
+
+  destroy() {
+    this._stopGate?.();
+    stopStripeSync();
+  }
+}

package/lib/build/trigger.js

@@ -0,0 +1,35 @@
+/**
+ * Eleventy rebuild trigger via file touch.
+ * The Eleventy `--watch` process picks up the touch and rebuilds in ~0.6s.
+ * Safe to call multiple times in quick succession — chokidar debounces.
+ * @module build/trigger
+ */
+
+import { utimes, open, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+
+export async function triggerRebuild(application) {
+  const triggerPath = application.donationConfig?.rebuildTrigger;
+  if (!triggerPath) {
+    console.warn("[Donation] no rebuildTrigger configured; skipping touch");
+    return;
+  }
+  const now = new Date();
+  try {
+    await utimes(triggerPath, now, now);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      // Create the file (and parent dir) on first run.
+      try {
+        await mkdir(dirname(triggerPath), { recursive: true });
+        const fh = await open(triggerPath, "w");
+        await fh.close();
+        await utimes(triggerPath, now, now);
+      } catch (createErr) {
+        console.error(`[Donation] rebuild trigger create failed: ${createErr.message}`);
+      }
+    } else {
+      console.error(`[Donation] rebuild trigger touch failed: ${err.message}`);
+    }
+  }
+}

package/lib/controllers/campaigns.js

@@ -0,0 +1,61 @@
+/**
+ * Campaign list + detail + manual override.
+ * Campaigns are authoritatively defined in Stripe Products — this admin
+ * UI is read-mostly. The only writable fields are local overrides
+ * (e.g. a "do not display on /transparence/" flag if you want to hide
+ * a campaign from the public page without archiving it in Stripe).
+ * @module controllers/campaigns
+ */
+
+import { listCampaigns, getCampaign, upsertCampaign } from "../storage/campaigns.js";
+import { sumByCampaign } from "../storage/donations.js";
+
+async function list(request, response, next) {
+  try {
+    const { application } = request.app.locals;
+    const campaigns = await listCampaigns(application);
+    // Augment each campaign with its current donation total.
+    const augmented = await Promise.all(
+      campaigns.map(async (c) => {
+        const { total, count } = await sumByCampaign(application, c.stripe_product_id);
+        return { ...c, raised_cents: total, donor_count: count };
+      }),
+    );
+    response.render("donation-campaigns", {
+      title: request.__("donation.campaigns.title"),
+      campaigns: augmented,
+      baseUrl: application.donationEndpoint,
+    });
+  } catch (err) { next(err); }
+}
+
+async function detail(request, response, next) {
+  try {
+    const { application } = request.app.locals;
+    const c = await getCampaign(application, request.params.id);
+    if (!c) return response.status(404).render("donation-not-found");
+    const { total, count } = await sumByCampaign(application, c.stripe_product_id);
+    response.render("donation-campaign-edit", {
+      title: c.title,
+      campaign: { ...c, raised_cents: total, donor_count: count },
+      baseUrl: application.donationEndpoint,
+    });
+  } catch (err) { next(err); }
+}
+
+async function update(request, response, next) {
+  try {
+    const { application } = request.app.locals;
+    const c = await getCampaign(application, request.params.id);
+    if (!c) return response.status(404).render("donation-not-found");
+    // Only local overrides editable; everything else syncs from Stripe.
+    await upsertCampaign(application, {
+      ...c,
+      hidden_on_public: request.body.hidden_on_public === "on",
+      display_order: Number(request.body.display_order ?? c.display_order ?? 100),
+    });
+    response.redirect(`${application.donationEndpoint}/campaigns/${request.params.id}`);
+  } catch (err) { next(err); }
+}
+
+export const campaignsController = { list, detail, update };

package/lib/controllers/consent.js

@@ -0,0 +1,22 @@
+/**
+ * Toggle a donation's public-display consent flag.
+ * Used both by the admin UI (manual toggle from /donations/:id) and
+ * eventually by the donor self-service link (v2).
+ * @module controllers/consent
+ */
+
+import { getDonation, updateConsent } from "../storage/donations.js";
+import { triggerRebuild } from "../build/trigger.js";
+
+async function toggle(request, response, next) {
+  try {
+    const { application } = request.app.locals;
+    const current = await getDonation(application, request.params.id);
+    if (!current) return response.status(404).render("donation-not-found");
+    await updateConsent(application, request.params.id, !current.donor?.consent_public);
+    await triggerRebuild(application);
+    response.redirect(`${application.donationEndpoint}/donations/${request.params.id}`);
+  } catch (err) { next(err); }
+}
+
+export const consentController = { toggle };

package/lib/controllers/dashboard.js

@@ -0,0 +1,42 @@
+/**
+ * Donation admin dashboard.
+ * Shows lifetime stats, recent donations, active campaigns, and quick actions.
+ * @module controllers/dashboard
+ */
+
+import { lifetimeStats, listDonations } from "../storage/donations.js";
+import { listCampaigns } from "../storage/campaigns.js";
+
+async function get(request, response, next) {
+  const { application } = request.app.locals;
+
+  try {
+    const [stats, recent, campaigns] = await Promise.all([
+      lifetimeStats(application),
+      listDonations(application, { limit: 10 }),
+      listCampaigns(application),
+    ]);
+
+    const activeCampaigns = campaigns.filter((c) => c.active);
+    const archivedCampaigns = campaigns.filter((c) => !c.active);
+
+    response.render("donation-dashboard", {
+      title: request.__("donation.title"),
+      stats: {
+        lifetime_total_cents: stats.total ?? 0,
+        donation_count: stats.donation_count ?? 0,
+        donor_count: stats.donor_count ?? 0,
+        active_campaign_count: activeCampaigns.length,
+      },
+      recent,
+      activeCampaigns,
+      archivedCampaigns,
+      currency: application.donationConfig?.currency ?? "EUR",
+      baseUrl: application.donationEndpoint ?? "/donation",
+    });
+  } catch (err) {
+    next(err);
+  }
+}
+
+export const dashboardController = { get };

package/lib/controllers/donations.js

@@ -0,0 +1,70 @@
+/**
+ * Donations list + detail + edit + delete.
+ * @module controllers/donations
+ */
+
+import { listDonations, getDonation, upsertDonation, removeDonation } from "../storage/donations.js";
+
+async function list(request, response, next) {
+  try {
+    const { application } = request.app.locals;
+    const { campaign_id, source, page = 1, limit = 50 } = request.query;
+    const items = await listDonations(application, {
+      campaign_id,
+      source,
+      limit: Number(limit),
+      skip: (Number(page) - 1) * Number(limit),
+      includeRefunded: true,
+    });
+    response.render("donation-donations", {
+      title: request.__("donation.donations.title"),
+      donations: items,
+      filters: { campaign_id, source, page, limit },
+      baseUrl: application.donationEndpoint,
+    });
+  } catch (err) { next(err); }
+}
+
+async function detail(request, response, next) {
+  try {
+    const { application } = request.app.locals;
+    const donation = await getDonation(application, request.params.id);
+    if (!donation) return response.status(404).render("donation-not-found");
+    response.render("donation-donation-edit", {
+      title: donation.stripe_id,
+      donation,
+      baseUrl: application.donationEndpoint,
+    });
+  } catch (err) { next(err); }
+}
+
+async function update(request, response, next) {
+  // TODO: validate inputs, only allow editing display name / message / consent flag.
+  // Stripe data (amount, date, campaign, donor_id) is canonical from Stripe — not editable.
+  try {
+    const { application } = request.app.locals;
+    const current = await getDonation(application, request.params.id);
+    if (!current) return response.status(404).render("donation-not-found");
+    const next_ = {
+      ...current,
+      donor: {
+        ...current.donor,
+        display: request.body.display ?? current.donor.display,
+        message: request.body.message ?? current.donor.message,
+        consent_public: request.body.consent_public === "on",
+      },
+    };
+    await upsertDonation(application, next_);
+    response.redirect(`${application.donationEndpoint}/donations/${request.params.id}`);
+  } catch (err) { next(err); }
+}
+
+async function remove(request, response, next) {
+  try {
+    const { application } = request.app.locals;
+    await removeDonation(application, request.params.id);
+    response.redirect(`${application.donationEndpoint}/donations`);
+  } catch (err) { next(err); }
+}
+
+export const donationsController = { list, detail, update, remove };

package/lib/controllers/manual.js

@@ -0,0 +1,61 @@
+/**
+ * Manual offline-donation entry — fills the gap for cash/bank-transfer
+ * gifts that never went through Stripe.
+ * @module controllers/manual
+ */
+
+import { upsertDonation } from "../storage/donations.js";
+import { listCampaigns } from "../storage/campaigns.js";
+import { triggerRebuild } from "../build/trigger.js";
+
+async function form(request, response, next) {
+  try {
+    const { application } = request.app.locals;
+    const campaigns = await listCampaigns(application, { active: true });
+    response.render("donation-manual", {
+      title: request.__("donation.manual.title"),
+      campaigns,
+      baseUrl: application.donationEndpoint,
+    });
+  } catch (err) { next(err); }
+}
+
+async function create(request, response, next) {
+  try {
+    const { application } = request.app.locals;
+    const { amount, currency, campaign_id, donor_display, message, consent_public, date } = request.body;
+
+    const amount_cents = Math.round(Number(amount) * 100);
+    if (!amount_cents || !campaign_id || !date) {
+      return response.status(400).render("donation-manual-error", {
+        title: request.__("donation.manual.error.title"),
+        message: request.__("donation.manual.error.required"),
+        baseUrl: application.donationEndpoint,
+      });
+    }
+
+    const id = `manual_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const donation = {
+      stripe_id: id,
+      date: new Date(date),
+      amount_cents,
+      currency: currency || application.donationConfig?.currency || "EUR",
+      campaign_id,
+      recurring: false,
+      donor: {
+        donor_id: `manual_${id}`,
+        display: donor_display?.trim() || null,
+        consent_public: consent_public === "on",
+        message: message?.trim() || null,
+      },
+      source: "manual",
+      refunded: false,
+      meta: { entered_by: request.session?.me ?? "unknown", note: request.body.note ?? null },
+    };
+    await upsertDonation(application, donation);
+    await triggerRebuild(application);
+    response.redirect(application.donationEndpoint);
+  } catch (err) { next(err); }
+}
+
+export const manualController = { form, create };

package/lib/controllers/stats.js

@@ -0,0 +1,82 @@
+/**
+ * Public JSON stats endpoints.
+ * Consumed by the static Eleventy site at build time and (optionally)
+ * by client-side fetches for live counter updates without rebuild.
+ * @module controllers/stats
+ */
+
+import { lifetimeStats, listDonations, sumByCampaign } from "../storage/donations.js";
+import { listCampaigns } from "../storage/campaigns.js";
+
+async function json(request, response, next) {
+  try {
+    const { application } = request.app.locals;
+    const [stats, campaigns, donations] = await Promise.all([
+      lifetimeStats(application),
+      listCampaigns(application),
+      listDonations(application, { limit: 100 }),
+    ]);
+
+    // Augment campaigns with their current totals.
+    const enriched = await Promise.all(
+      campaigns.map(async (c) => {
+        const { total, count } = await sumByCampaign(application, c.stripe_product_id);
+        return {
+          id: c.stripe_product_id,
+          title: c.title,
+          subtitle: c.subtitle,
+          description: c.description,
+          goal_cents: c.goal_cents,
+          raised_cents: total,
+          donor_count: count,
+          active: c.active,
+          started: c.started,
+          ends: c.ends,
+          stripe_payment_link: c.stripe_payment_link,
+        };
+      }),
+    );
+
+    // Hide donor identifying info unless donor explicitly consented.
+    const sanitized = donations.map((d) => ({
+      id: d.stripe_id,
+      date: d.date,
+      amount_cents: d.amount_cents,
+      currency: d.currency,
+      campaign_id: d.campaign_id,
+      recurring: d.recurring,
+      donor: {
+        display: d.donor?.consent_public ? d.donor?.display : null,
+        consent_public: Boolean(d.donor?.consent_public),
+        message: d.donor?.consent_public ? d.donor?.message : null,
+      },
+    }));
+
+    response.setHeader("Cache-Control", "public, max-age=60");
+    response.json({
+      updated_at: new Date().toISOString(),
+      currency: application.donationConfig?.currency ?? "EUR",
+      lifetime_total_cents: stats.total ?? 0,
+      lifetime_donor_count: stats.donor_count ?? 0,
+      donation_count: stats.donation_count ?? 0,
+      campaigns: enriched,
+      donations: sanitized,
+    });
+  } catch (err) { next(err); }
+}
+
+async function byCampaign(request, response, next) {
+  try {
+    const { application } = request.app.locals;
+    const { total, count } = await sumByCampaign(application, request.params.campaignId);
+    response.setHeader("Cache-Control", "public, max-age=60");
+    response.json({
+      campaign_id: request.params.campaignId,
+      raised_cents: total,
+      donor_count: count,
+      updated_at: new Date().toISOString(),
+    });
+  } catch (err) { next(err); }
+}
+
+export const statsController = { json, byCampaign };

package/lib/controllers/sync.js

@@ -0,0 +1,25 @@
+/**
+ * Manual Stripe sync trigger + rebuild trigger.
+ * @module controllers/sync
+ */
+
+import { runFullSync } from "../sync/scheduler.js";
+import { triggerRebuild } from "../build/trigger.js";
+
+async function runOnce(request, response, next) {
+  try {
+    const { application } = request.app.locals;
+    const result = await runFullSync(application);
+    response.redirect(`${application.donationEndpoint}?synced=${result.upserted ?? 0}`);
+  } catch (err) { next(err); }
+}
+
+async function triggerRebuildAction(request, response, next) {
+  try {
+    const { application } = request.app.locals;
+    await triggerRebuild(application);
+    response.redirect(`${application.donationEndpoint}?rebuild=triggered`);
+  } catch (err) { next(err); }
+}
+
+export const syncController = { runOnce, triggerRebuild: triggerRebuildAction };