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

package/lib/controllers/webhook.js

@@ -0,0 +1,72 @@
+/**
+ * Stripe webhook receiver.
+ * @module controllers/webhook
+ *
+ * Implementation notes:
+ * - express.raw() must be applied at this route so signature verification
+ *   sees the original bytes (see index.js routesPublic).
+ * - Signature verification rejects unsigned / replayed payloads.
+ * - Only events listed in HANDLED_EVENTS are processed; everything else
+ *   returns 200 OK without action (so Stripe doesn't retry).
+ */
+
+import { verifyStripeSignature } from "../stripe/verify-signature.js";
+import { mapSessionToDonation } from "../stripe/map-session.js";
+import { upsertDonation, markRefunded } from "../storage/donations.js";
+import { triggerRebuild } from "../build/trigger.js";
+
+// Locked-in per chardonsbleus decision 2026-05-21:
+//   - checkout.session.completed
+//   - checkout.session.async_payment_succeeded
+//   - invoice.paid (recurring)
+//   - charge.refunded (rollback)
+const HANDLED_EVENTS = new Set([
+  "checkout.session.completed",
+  "checkout.session.async_payment_succeeded",
+  "invoice.paid",
+  "charge.refunded",
+]);
+
+async function receive(request, response, next) {
+  try {
+    const { application } = request.app.locals;
+    const cfg = application.donationConfig ?? {};
+    if (!cfg.stripeWebhookSecret) {
+      console.error("[Donation] STRIPE_WEBHOOK_SECRET missing");
+      return response.status(503).json({ error: "webhook secret not configured" });
+    }
+
+    const sig = request.headers["stripe-signature"];
+    let event;
+    try {
+      event = verifyStripeSignature({
+        payload: request.body,            // Buffer from express.raw()
+        signature: sig,
+        secret: cfg.stripeWebhookSecret,
+      });
+    } catch (err) {
+      console.warn(`[Donation] webhook signature rejected: ${err.message}`);
+      return response.status(400).json({ error: "invalid signature" });
+    }
+
+    if (!HANDLED_EVENTS.has(event.type)) {
+      // Acknowledge so Stripe doesn't retry; we just don't act on it.
+      return response.status(200).json({ received: true, handled: false, type: event.type });
+    }
+
+    if (event.type === "charge.refunded") {
+      const stripeId = event.data?.object?.payment_intent ?? event.data?.object?.id;
+      if (stripeId) await markRefunded(application, stripeId);
+    } else {
+      const donation = await mapSessionToDonation(event, cfg);
+      if (donation) await upsertDonation(application, donation);
+    }
+
+    await triggerRebuild(application);
+    return response.status(200).json({ received: true, handled: true, type: event.type });
+  } catch (err) {
+    next(err);
+  }
+}
+
+export const webhookController = { receive };

package/lib/storage/campaigns.js

@@ -0,0 +1,43 @@
+/**
+ * Campaign cache CRUD.
+ * Campaigns are owned by Stripe; this collection is a queryable cache
+ * synced from Stripe Products hourly + on-demand.
+ * @module storage/campaigns
+ */
+
+function collection(application) {
+  return application.collections?.get("campaignsCache");
+}
+
+export async function upsertCampaign(application, campaign) {
+  const c = collection(application);
+  if (!c) throw new Error("campaignsCache unavailable");
+  await c.updateOne(
+    { stripe_product_id: campaign.stripe_product_id },
+    { $set: { ...campaign, last_synced_at: new Date() } },
+    { upsert: true },
+  );
+}
+
+export async function listCampaigns(application, { active } = {}) {
+  const c = collection(application);
+  if (!c) return [];
+  const query = {};
+  if (typeof active === "boolean") query.active = active;
+  return c.find(query).sort({ active: -1, display_order: 1, ends: -1 }).toArray();
+}
+
+export async function getCampaign(application, stripe_product_id) {
+  const c = collection(application);
+  if (!c) return null;
+  return c.findOne({ stripe_product_id });
+}
+
+export async function deactivateCampaign(application, stripe_product_id) {
+  const c = collection(application);
+  if (!c) return;
+  await c.updateOne(
+    { stripe_product_id },
+    { $set: { active: false, last_synced_at: new Date() } },
+  );
+}

package/lib/storage/donations.js

@@ -0,0 +1,134 @@
+/**
+ * Donation CRUD against MongoDB.
+ * @module storage/donations
+ */
+
+function collection(application) {
+  return application.collections?.get("donations");
+}
+
+/**
+ * Insert a donation, upsert by stripe_id so duplicate webhooks are idempotent.
+ * @param {object} application - indiekit application locals
+ * @param {object} donation - shape per CLAUDE.md
+ * @returns {Promise<object>} the upserted donation
+ */
+export async function upsertDonation(application, donation) {
+  const c = collection(application);
+  if (!c) throw new Error("donations collection unavailable");
+  const now = new Date();
+  const doc = {
+    ...donation,
+    updated_at: now,
+    created_at: donation.created_at ?? now,
+  };
+  await c.updateOne(
+    { stripe_id: donation.stripe_id },
+    { $set: doc, $setOnInsert: { _firstSeenAt: now } },
+    { upsert: true },
+  );
+  return c.findOne({ stripe_id: donation.stripe_id });
+}
+
+/**
+ * List donations with filters.
+ * @param {object} application
+ * @param {object} [opts]
+ * @param {string} [opts.campaign_id]
+ * @param {string} [opts.source] - "stripe" | "givewp_migrated" | "manual"
+ * @param {boolean} [opts.includeRefunded]
+ * @param {number} [opts.limit=50]
+ * @param {number} [opts.skip=0]
+ */
+export async function listDonations(application, opts = {}) {
+  const c = collection(application);
+  if (!c) return [];
+  const query = {};
+  if (opts.campaign_id) query.campaign_id = opts.campaign_id;
+  if (opts.source) query.source = opts.source;
+  if (!opts.includeRefunded) query.refunded = { $ne: true };
+  return c
+    .find(query)
+    .sort({ date: -1 })
+    .skip(opts.skip ?? 0)
+    .limit(opts.limit ?? 50)
+    .toArray();
+}
+
+/** Sum amounts for a campaign (in cents). */
+export async function sumByCampaign(application, campaign_id) {
+  const c = collection(application);
+  if (!c) return { total: 0, count: 0 };
+  const [agg] = await c
+    .aggregate([
+      { $match: { campaign_id, refunded: { $ne: true } } },
+      { $group: { _id: null, total: { $sum: "$amount_cents" }, count: { $sum: 1 } } },
+    ])
+    .toArray();
+  return agg ?? { total: 0, count: 0 };
+}
+
+/** Lifetime stats: total raised, unique donors. */
+export async function lifetimeStats(application) {
+  const c = collection(application);
+  if (!c) return { total: 0, donor_count: 0, donation_count: 0 };
+  const [agg] = await c
+    .aggregate([
+      { $match: { refunded: { $ne: true } } },
+      {
+        $group: {
+          _id: null,
+          total: { $sum: "$amount_cents" },
+          donation_count: { $sum: 1 },
+          donors: { $addToSet: "$donor.donor_id" },
+        },
+      },
+      {
+        $project: {
+          _id: 0,
+          total: 1,
+          donation_count: 1,
+          donor_count: { $size: "$donors" },
+        },
+      },
+    ])
+    .toArray();
+  return agg ?? { total: 0, donor_count: 0, donation_count: 0 };
+}
+
+export async function getDonation(application, id) {
+  const c = collection(application);
+  if (!c) return null;
+  return c.findOne({ stripe_id: id });
+}
+
+export async function updateConsent(application, id, consent_public) {
+  const c = collection(application);
+  if (!c) throw new Error("donations collection unavailable");
+  await c.updateOne(
+    { stripe_id: id },
+    {
+      $set: {
+        "donor.consent_public": Boolean(consent_public),
+        "donor.display": consent_public ? null : undefined, // don't auto-clear; admin decides
+        updated_at: new Date(),
+      },
+    },
+  );
+  return getDonation(application, id);
+}
+
+export async function markRefunded(application, id, refundedAt = new Date()) {
+  const c = collection(application);
+  if (!c) throw new Error("donations collection unavailable");
+  await c.updateOne(
+    { stripe_id: id },
+    { $set: { refunded: true, refunded_at: refundedAt, updated_at: new Date() } },
+  );
+}
+
+export async function removeDonation(application, id) {
+  const c = collection(application);
+  if (!c) throw new Error("donations collection unavailable");
+  await c.deleteOne({ stripe_id: id });
+}

package/lib/storage/indexes.js

@@ -0,0 +1,33 @@
+/**
+ * MongoDB index creation for donation collections.
+ * Called once on init() after waitForReady gate clears.
+ * @module storage/indexes
+ */
+
+export async function createIndexes(Indiekit) {
+  const collections = Indiekit.config.application.collections;
+  if (!collections) return;
+
+  const donations = collections.get("donations");
+  if (donations) {
+    await donations.createIndex({ stripe_id: 1 }, { unique: true, name: "stripe_id_unique" });
+    await donations.createIndex({ campaign_id: 1, date: -1 }, { name: "campaign_date" });
+    await donations.createIndex({ "donor.donor_id": 1, date: -1 }, { name: "donor_date" });
+    await donations.createIndex({ source: 1, date: -1 }, { name: "source_date" });
+    await donations.createIndex({ refunded: 1 }, { sparse: true, name: "refunded_sparse" });
+    await donations.createIndex({ date: -1 }, { name: "date_desc" });
+  }
+
+  const campaigns = collections.get("campaignsCache");
+  if (campaigns) {
+    await campaigns.createIndex({ stripe_product_id: 1 }, { unique: true, name: "product_id_unique" });
+    await campaigns.createIndex({ active: 1, display_order: 1 }, { name: "active_order" });
+  }
+
+  const meta = collections.get("donationMeta");
+  if (meta) {
+    await meta.createIndex({ key: 1 }, { unique: true, name: "key_unique" });
+  }
+
+  console.log("[Donation] indexes ensured on donations, campaignsCache, donationMeta");
+}

package/lib/stripe/client.js

@@ -0,0 +1,31 @@
+/**
+ * Lazy Stripe SDK singleton.
+ * Created on first access so the plugin can boot even with no key
+ * (admin UI still loads, just shows a "Stripe not configured" banner).
+ * @module stripe/client
+ */
+
+import Stripe from "stripe";
+
+let _client = null;
+
+export function getStripe(cfg) {
+  if (!cfg?.stripeSecretKey) {
+    throw new Error("STRIPE_SECRET_KEY not configured");
+  }
+  if (!_client) {
+    _client = new Stripe(cfg.stripeSecretKey, {
+      // Pin API version to avoid surprise behavior changes; bump
+      // intentionally when reviewing Stripe changelogs.
+      apiVersion: "2025-09-30.acacia",
+      typescript: false,
+      maxNetworkRetries: 2,
+      timeout: 15000,
+      appInfo: {
+        name: "indiekit-endpoint-donation",
+        version: "0.1.0",
+      },
+    });
+  }
+  return _client;
+}

package/lib/stripe/map-product.js

@@ -0,0 +1,25 @@
+/**
+ * Map a Stripe Product (+ its primary Payment Link) → campaigns schema.
+ * @module stripe/map-product
+ */
+
+/**
+ * @param {object} product - Stripe Product object (with metadata)
+ * @param {string|null} paymentLinkUrl - Resolved Payment Link URL
+ * @returns {object} campaign document
+ */
+export function mapProductToCampaign(product, paymentLinkUrl = null) {
+  const m = product.metadata ?? {};
+  return {
+    stripe_product_id: product.id,
+    title: product.name,
+    subtitle: m.subtitle ?? "",
+    description: product.description ?? "",
+    goal_cents: Number(m.goal_cents ?? 0) || 0,
+    active: Boolean(product.active),
+    started: m.campaign_starts ? new Date(m.campaign_starts) : null,
+    ends: m.campaign_ends ? new Date(m.campaign_ends) : null,
+    display_order: Number(m.display_order ?? 100),
+    stripe_payment_link: paymentLinkUrl,
+  };
+}

package/lib/stripe/map-session.js

@@ -0,0 +1,86 @@
+/**
+ * Map a Stripe webhook event (Checkout Session, Invoice, etc.) →
+ * donation schema.
+ * @module stripe/map-session
+ *
+ * Custom field labels expected on the Payment Link (decided 2026-05-21):
+ *   - "Afficher mon don ?"  dropdown: named | anon | hide
+ *   - "Nom à afficher (optionnel)"  text
+ *   - "Message court (optionnel)"   text
+ */
+
+const CONSENT_KEY = "consent";       // dropdown
+const DISPLAY_KEY = "display_name";  // text
+const MESSAGE_KEY = "message";       // text
+
+function customField(session, key) {
+  const fields = session?.custom_fields ?? [];
+  return fields.find((f) => f.key === key);
+}
+
+function readConsent(session) {
+  const f = customField(session, CONSENT_KEY);
+  const value = f?.dropdown?.value ?? "anon"; // safe default
+  // Map the three options to the internal flags.
+  // - "named":  consent_public=true,  display set (from display field)
+  // - "anon":   consent_public=true,  display=null (shown as "Anonyme")
+  // - "hide":   consent_public=false, display=null (hidden from public list)
+  switch (value) {
+    case "named":
+      return { consent_public: true, named: true };
+    case "anon":
+      return { consent_public: true, named: false };
+    case "hide":
+    default:
+      return { consent_public: false, named: false };
+  }
+}
+
+export async function mapSessionToDonation(event, _cfg) {
+  const session = event.data?.object;
+  if (!session) return null;
+
+  // Resolve product_id from line items (Stripe webhook embeds them).
+  const lineItem = session.line_items?.data?.[0] ?? session.lines?.data?.[0];
+  const campaign_id =
+    lineItem?.price?.product ??
+    session.metadata?.campaign_id ??
+    null;
+
+  if (!campaign_id) {
+    console.warn(`[Donation] webhook event ${event.id} had no resolvable campaign_id`);
+    return null;
+  }
+
+  const { consent_public, named } = readConsent(session);
+  const displayField = customField(session, DISPLAY_KEY)?.text?.value?.trim() || null;
+  const messageField = customField(session, MESSAGE_KEY)?.text?.value?.trim() || null;
+
+  const display = named ? (displayField || "Donateur") : null;
+  const message = consent_public ? messageField : null;
+
+  return {
+    stripe_id: session.id ?? session.payment_intent ?? event.id,
+    date: new Date((session.created ?? event.created) * 1000),
+    amount_cents: session.amount_total ?? session.amount_paid ?? 0,
+    currency: (session.currency ?? "eur").toUpperCase(),
+    campaign_id,
+    recurring: event.type === "invoice.paid",
+    donor: {
+      donor_id: session.customer ?? `session_${session.id}`,
+      display,
+      consent_public,
+      message,
+    },
+    source: "stripe",
+    refunded: false,
+    meta: {
+      event_type: event.type,
+      payment_status: session.payment_status,
+      payment_intent: session.payment_intent,
+      mode: session.mode,
+    },
+    created_at: new Date(),
+    updated_at: new Date(),
+  };
+}

package/lib/stripe/verify-signature.js

@@ -0,0 +1,15 @@
+/**
+ * Stripe webhook signature verification.
+ * Wraps stripe.webhooks.constructEvent so we have a single place to
+ * adjust signing logic + log rejections.
+ * @module stripe/verify-signature
+ */
+
+import Stripe from "stripe";
+
+export function verifyStripeSignature({ payload, signature, secret }) {
+  if (!signature) throw new Error("missing Stripe-Signature header");
+  if (!secret) throw new Error("missing webhook secret");
+  // Stripe SDK's static helper doesn't require an instance.
+  return Stripe.webhooks.constructEvent(payload, signature, secret);
+}

package/lib/sync/scheduler.js

@@ -0,0 +1,65 @@
+/**
+ * Hourly background sync of Stripe Products → campaignsCache.
+ * Stripe is the source of truth; this collection is just a queryable mirror.
+ * @module sync/scheduler
+ */
+
+import { getStripe } from "../stripe/client.js";
+import { mapProductToCampaign } from "../stripe/map-product.js";
+import { upsertCampaign, listCampaigns, deactivateCampaign } from "../storage/campaigns.js";
+
+let _interval = null;
+let _running = false;
+
+export async function runFullSync(Indiekit) {
+  if (_running) return { skipped: true };
+  _running = true;
+  try {
+    const application = Indiekit.config?.application ?? Indiekit;
+    const cfg = application.donationConfig;
+    const stripe = getStripe(cfg);
+
+    // List all products + their default prices + payment links.
+    // For now: just products + metadata. Payment Link resolution can come later
+    // when we add `lib/stripe/payment-links.js`.
+    const products = await stripe.products.list({ active: true, limit: 100 });
+
+    let upserted = 0;
+    for (const product of products.data) {
+      const campaign = mapProductToCampaign(product, null);
+      await upsertCampaign(application, campaign);
+      upserted++;
+    }
+
+    // Mark previously-cached campaigns no longer in Stripe as inactive.
+    const seenIds = new Set(products.data.map((p) => p.id));
+    const cached = await listCampaigns(application);
+    for (const c of cached) {
+      if (!seenIds.has(c.stripe_product_id) && c.active) {
+        await deactivateCampaign(application, c.stripe_product_id);
+      }
+    }
+
+    console.log(`[Donation] sync ok: upserted ${upserted} campaigns`);
+    return { upserted, deactivated: cached.length - upserted };
+  } catch (err) {
+    console.error(`[Donation] sync failed: ${err.message}`);
+    return { error: err.message };
+  } finally {
+    _running = false;
+  }
+}
+
+export function startStripeSync(Indiekit, options) {
+  // Fire once on startup, then every hour.
+  runFullSync(Indiekit).catch((e) => console.error("[Donation] initial sync error:", e));
+  _interval = setInterval(
+    () => runFullSync(Indiekit).catch((e) => console.error("[Donation] periodic sync error:", e)),
+    options.syncInterval ?? 3600000,
+  );
+}
+
+export function stopStripeSync() {
+  if (_interval) clearInterval(_interval);
+  _interval = null;
+}

package/locales/en.json

@@ -0,0 +1,69 @@
+{
+  "donation": {
+    "title": "Donations",
+    "description": "Manage Stripe-backed donations and campaigns",
+    "never": "Never",
+    "save": "Save",
+    "cancel": "Cancel",
+    "edit": "Edit",
+    "delete": "Delete",
+    "confirm": "Are you sure?",
+
+    "stats": {
+      "title": "Overview",
+      "lifetime_total": "Lifetime total",
+      "donor_count": "Unique donors",
+      "donation_count": "Donations",
+      "active_campaigns": "Active campaigns",
+      "last_sync": "Last Stripe sync"
+    },
+
+    "actions": {
+      "title": "Actions",
+      "sync_stripe": "Sync from Stripe",
+      "trigger_rebuild": "Trigger site rebuild",
+      "add_manual": "Add offline donation"
+    },
+
+    "donations": {
+      "title": "Donations",
+      "empty": "No donations yet."
+    },
+
+    "campaigns": {
+      "title": "Campaigns",
+      "active": "Active",
+      "archived": "Archived",
+      "synced_from_stripe": "Synced from Stripe",
+      "raised": "Raised",
+      "goal": "Goal",
+      "donors": "Donors",
+      "hidden_on_public": "Hide on public transparence page"
+    },
+
+    "manual": {
+      "title": "Add an offline donation",
+      "action": "Add donation",
+      "fields": {
+        "amount": "Amount (€)",
+        "campaign": "Campaign",
+        "date": "Date received",
+        "donor_display": "Donor name (or leave empty for anonymous)",
+        "message": "Donor message",
+        "consent_public": "Show donor name publicly",
+        "note": "Internal note (not shown publicly)"
+      },
+      "error": {
+        "title": "Could not add donation",
+        "required": "Amount, campaign, and date are required."
+      }
+    },
+
+    "consent": {
+      "public": "Public",
+      "anonymous": "Anonymous",
+      "hidden": "Hidden",
+      "toggle": "Toggle public display"
+    }
+  }
+}

package/locales/fr.json

@@ -0,0 +1,69 @@
+{
+  "donation": {
+    "title": "Dons",
+    "description": "Gérer les dons et campagnes Stripe",
+    "never": "Jamais",
+    "save": "Enregistrer",
+    "cancel": "Annuler",
+    "edit": "Modifier",
+    "delete": "Supprimer",
+    "confirm": "Êtes-vous sûr ?",
+
+    "stats": {
+      "title": "Aperçu",
+      "lifetime_total": "Total collecté à vie",
+      "donor_count": "Donateurs uniques",
+      "donation_count": "Dons",
+      "active_campaigns": "Campagnes actives",
+      "last_sync": "Dernière synchronisation Stripe"
+    },
+
+    "actions": {
+      "title": "Actions",
+      "sync_stripe": "Synchroniser depuis Stripe",
+      "trigger_rebuild": "Déclencher la reconstruction du site",
+      "add_manual": "Ajouter un don hors-ligne"
+    },
+
+    "donations": {
+      "title": "Dons",
+      "empty": "Aucun don pour le moment."
+    },
+
+    "campaigns": {
+      "title": "Campagnes",
+      "active": "Actives",
+      "archived": "Archivées",
+      "synced_from_stripe": "Synchronisées depuis Stripe",
+      "raised": "Collecté",
+      "goal": "Objectif",
+      "donors": "Donateurs",
+      "hidden_on_public": "Masquer sur la page de transparence publique"
+    },
+
+    "manual": {
+      "title": "Ajouter un don hors-ligne",
+      "action": "Ajouter un don",
+      "fields": {
+        "amount": "Montant (€)",
+        "campaign": "Campagne",
+        "date": "Date de réception",
+        "donor_display": "Nom du donateur (vide = anonyme)",
+        "message": "Message du donateur",
+        "consent_public": "Afficher le nom publiquement",
+        "note": "Note interne (non publique)"
+      },
+      "error": {
+        "title": "Impossible d'ajouter le don",
+        "required": "Le montant, la campagne et la date sont requis."
+      }
+    },
+
+    "consent": {
+      "public": "Public",
+      "anonymous": "Anonyme",
+      "hidden": "Masqué",
+      "toggle": "Basculer l'affichage public"
+    }
+  }
+}