@meith/plugin-dues 0.1.0

package/LICENSE.md

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/README.md

@@ -0,0 +1,182 @@
+# Dues
+
+Sells **membership of a usergroup** on a Meith board, through Stripe — a
+monthly or yearly subscription, a fixed-term pass from a day to two years, or
+a lifetime membership — each a plan an administrator shapes in the panel:
+name, price, currency, and length are the operator's call. A pass or a
+lifetime plan can be bought for yourself **or gifted to another member by
+name**.
+
+What a paying member gets is whatever the group carries: forum access, a
+badge, a name colour. Dues never makes a permission decision — it decides who
+is in a group and until when, through the board's own
+[timed-grant capability](../../docs/plugin-api.md#timed-group-grants), and
+every guarantee that capability makes applies here. The load-bearing one:
+**a grant always expires on its own.** If this plugin is removed, its tasks
+stop, or Stripe closes the account, every sold membership drains away at its
+own boundary and the board is left correct.
+
+**Try it before you read any of this**: [demo.meith.dev](https://demo.meith.dev)
+runs this plugin against a Stripe that is not Stripe — a shop with a year of
+history behind it, and a checkout a visitor can actually go through. See
+[demo mode](../../docs/demo-mode.md#the-shop-and-a-stripe-that-is-not-stripe).
+
+## Setting up a board
+
+1. **Register the plugin** where plugins are registered:
+
+   ```ts
+   // apps/community/community.plugins.ts (this repository's board uses
+   // DUES_TEST_BOARD=1 to switch a test-shaped version of this on)
+   import { dues } from '@meith/plugin-dues'
+
+   export const INSTALLED_PLUGINS = [
+     { key: 'dues', plugin: dues({ currency: 'gbp', graceDays: 7 }) },
+   ]
+   ```
+
+   `plans` may also be declared here as **seeds** — they populate the plan
+   table on the board's first run and are ignored once it has rows. After
+   that, the panel owns the plans.
+
+2. **On the board**: create the group a plan will grant (its permissions,
+   badge and colour are the product), then tick **may be granted by plugins**
+   on its screen under Admin → Groups. Staff, system and power-carrying
+   groups refuse the tick, on purpose.
+3. **Keys**: set `DUES_STRIPE_SECRET_KEY` and `DUES_STRIPE_WEBHOOK_SECRET` in
+   the environment, or fill them under Admin → Plugins → Dues. Environment
+   wins, and the settings screen says which source is in force.
+4. **Migrations**: run `community upgrade`.
+5. **Make the plans** under Admin → Plugins → Dues → plans — see
+   [Plans](#plans) below.
+6. **The webhook**: in Stripe, add an endpoint at
+   `https://your.board/api/plugins/dues/hook/stripe` subscribed to the events
+   the status page lists, and put its `whsec_…` in the settings.
+7. **Prove it**: the status page (Admin → Plugins → Dues → status) should read
+   green; buy a pass yourself in test mode before turning the live key on.
+
+## Plans
+
+A plan is made and edited in the panel. It has a permanent key, a name, a
+description, the group it grants, a price in minor units, its own three-letter
+currency, and one of three billing shapes:
+
+- **A pass** — one payment for a fixed stretch, one day to two years
+  (including the grace window; the board caps a plugin grant at two years,
+  and a pass respects the cap rather than pretending otherwise).
+- **A subscription** — renews monthly or yearly until cancelled. It bills
+  against a real Stripe price: leave the box empty and the plugin mints a
+  product and price to match the form, or paste a `price_…` id made in the
+  Stripe dashboard. Subscriptions are never giftable.
+- **Lifetime** — one payment, no renewal, no end date. Under the hood the
+  board still only ever grants a bounded window (about 23 months), and the
+  hourly sweep re-issues it long before it drains — so if the plugin is ever
+  removed, access ends at the window's edge instead of leaving unaccountable
+  permanent rows. Holding lifetime makes further purchases for that group
+  refuse; holding a subscription blocks buying lifetime until the renewal is
+  cancelled.
+
+Editing is safe by construction: **every order snapshots its plan** — name,
+price, currency, length — so a change never rewrites what anyone already
+bought. A subscription price change mints a new Stripe price; running
+subscriptions keep billing what they signed up for, and only the next buyer
+sees the new number. Plans are never deleted — **archiving** takes one off
+sale while everyone who holds it keeps it. The plan key is permanent because
+it is how orders, memberships and the ledger refer to the plan forever.
+
+## How it decides things
+
+- **A pass stacks.** Buying a fixed pass while holding one adds to the end —
+  paying early never wastes time. Subscriptions refuse a second subscription
+  for the same group, lifetime refuses everything after it — there is nothing
+  left to sell that member.
+- **Gifts are one-off purchases only** — passes and lifetime. An
+  auto-renewing gift would charge the buyer's card forever for someone
+  else's membership; that is a support disaster by design, so it is refused
+  when the plan is made. The recipient is notified the moment their gift is
+  paid for — the board's own bell and e-mail, honouring their notification
+  preferences.
+- **Checkout is rate-limited** — ten starts a minute per member, enforced by
+  the host before the handler runs — so a stuck retry loop or a hostile
+  script cannot mint orders and Stripe sessions at wire speed.
+- **Nothing is granted from a redirect.** The return page waits; only the
+  signature-verified webhook (or the reconcile task reading Stripe's own
+  record) turns money into membership. Amounts must match the order exactly —
+  a mismatch grants nothing and flags the order for an administrator.
+- **A failed renewal means grace, not the door.** Access holds for
+  `graceDays` past the period; Stripe retries on its own schedule; the member
+  is told through the board's own notifications — bell and e-mail, per their
+  preferences — and sees what happened on their manage page.
+- **A refund or chargeback revokes immediately** — the only path that takes
+  access away early — and lands in the ledger as a negative amount.
+- **Cancelling keeps what was paid for.** Cancel-at-period-end, always.
+- **Lost webhooks are ordinary.** The five-minute reconcile task settles
+  pending orders from Stripe's records and replays any stored event that
+  failed; the hourly sweep tidies lapsed rows the expiry already handled.
+
+## Discount codes
+
+Minted under Admin → Plugins → Dues → discount codes: a percentage off,
+optionally locked to one plan, capped to a number of redemptions, or given an
+expiry date. Members type the code in the box on any plan card.
+
+- **A code discounts what Stripe charges, not what the order records** — the
+  order snapshots the discounted amount, so the exact-match rule between
+  payment and order still holds.
+- **On a pass or lifetime plan** the whole price drops. **On a
+  subscription** the discount
+  becomes a real Stripe coupon (created on the code's first use, `duration:
+  once`), so the first invoice is discounted and renewals bill in full — both
+  numbers come from Stripe's own arithmetic.
+- **A 100% code on a pass or lifetime plan is a comp.** Stripe is never
+  contacted: the order settles on the spot for zero and the recipient belongs
+  immediately. This is the intended way to comp a member — including a
+  lifetime comp.
+- **Redemptions count at settlement**, not at checkout, so an abandoned
+  checkout never burns a use. Two people racing the last redemption of a
+  capped code can both succeed — the count is honest about money that
+  actually moved.
+- **Codes are never deleted.** Switch one off and it refuses from that moment;
+  its history stays.
+- Stripe refuses charges under its per-currency minimum (about £0.30), so a
+  deep discount on a cheap plan can fail at Stripe's page. 100%-off passes
+  are exempt — they never reach Stripe.
+
+## The admin desk
+
+Admin → Plugins → Dues → memberships acts on any sold membership:
+
+- **Extend** adds days to the period end and moves the group grant with it —
+  a grant, not a charge, so the ledger is untouched.
+- **Cancel renewal** is the same cancel-at-period-end a member can do from
+  their manage page, for when someone asks support instead.
+- **Revoke now** removes access on the spot and tells Stripe to stop billing
+  a subscription. It does not move money — issue any refund in the Stripe
+  dashboard, and the refund webhook records it (and would have revoked on its
+  own).
+- **Clear the flag** acknowledges a needs-attention row once you have looked
+  at it; flagged orders are cleared from the status screen.
+
+Every one of these actions lands in the board's admin action log as
+`plugin.route`, alongside everything else administrators do.
+
+## What the operator owns
+
+VAT and invoicing, the refund policy and statutory cancellation rights, and
+what your jurisdiction requires around selling recurring services — prices
+here are simply what the member pays. Refunds are issued in the Stripe
+dashboard and flow back as webhooks.
+
+## Testing
+
+- `pnpm vitest run plugins/dues` — the unit suites: money, periods,
+  configuration refusals, the Stripe client against a scripted fetch, webhook
+  signatures, event mapping across Stripe API versions.
+- `pnpm vitest run tests/dues-lifecycle.test.ts` — the whole life of a
+  membership against real SQL: purchase, gift, stacking, replay, mismatch,
+  renewal, grace, cancel, refund-revoke, reconcile, sweep, discount codes,
+  and the admin desk.
+- `pnpm test:e2e e2e/dues-purchase-no-js.spec.ts` — a real browser buys a
+  pass, gifts one, and redeems a minted code on the test board
+  (`DUES_TEST_BOARD=1`), against a fake Stripe on loopback, with the suite
+  signing webhooks the way Stripe would.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@meith/plugin-dues",
+  "version": "0.1.0",
+  "description": "Membership dues for a Meith board: Stripe-backed subscriptions as a contained plugin.",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "plugins/dues"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@meith/plugin-kit": "^0.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19.2.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.3"
+  }
+}

package/src/codes.ts

@@ -0,0 +1,47 @@
+import { randomBytes } from 'node:crypto'
+
+export const CODE_ALPHABET = 'ABCDEFGHJKMNPQRSTUVWXYZ23456789'
+const CODE_SHAPE = /^[A-Z0-9][A-Z0-9-]{2,31}$/
+
+export function generateCode(): string {
+  const bytes = randomBytes(8)
+  let out = ''
+  for (let index = 0; index < 8; index += 1) {
+    if (index === 4) out += '-'
+    out += CODE_ALPHABET[bytes[index]! % CODE_ALPHABET.length]
+  }
+  return out
+}
+
+export function normalizeCode(input: string): string {
+  return input.trim().toUpperCase()
+}
+
+export function validCodeShape(code: string): boolean {
+  return CODE_SHAPE.test(code)
+}
+
+export function discountedPrice(priceMinor: number, percentOff: number): number {
+  return Math.max(0, Math.round((priceMinor * (100 - percentOff)) / 100))
+}
+
+export interface UsableCode {
+  readonly percentOff: number
+  readonly planKey: string | null
+  readonly maxRedemptions: number | null
+  readonly redeemedCount: number
+  readonly expiresAt: Date | null
+  readonly disabled: boolean
+}
+
+export type CodeProblem = 'disabled' | 'expired' | 'exhausted' | 'wrong-plan'
+
+export function codeProblem(code: UsableCode, planKey: string, now: Date): CodeProblem | null {
+  if (code.disabled) return 'disabled'
+  if (code.expiresAt !== null && code.expiresAt <= now) return 'expired'
+  if (code.maxRedemptions !== null && code.redeemedCount >= code.maxRedemptions) {
+    return 'exhausted'
+  }
+  if (code.planKey !== null && code.planKey !== planKey) return 'wrong-plan'
+  return null
+}

package/src/config.ts

@@ -0,0 +1,153 @@
+import { isCurrencyCode, isValidMinorAmount } from './money'
+import { parsePeriod, periodCeilingDays, type Period } from './period'
+
+export interface DuesPlanInput {
+  readonly key: string
+  readonly name: string
+  readonly description?: string
+  readonly group: string
+  readonly price: number
+  readonly billing:
+    | { readonly mode: 'auto'; readonly interval: 'month' | 'year'; readonly stripePriceId: string }
+    | { readonly mode: 'fixed'; readonly period: string }
+  readonly giftable?: boolean
+  readonly hidden?: boolean
+}
+
+export interface DuesConfigInput {
+  readonly currency: string
+  readonly graceDays?: number
+  readonly label?: string
+  readonly plans?: readonly DuesPlanInput[]
+  readonly extraRedirectHosts?: readonly string[]
+}
+
+export interface DuesPlan {
+  readonly key: string
+  readonly name: string
+  readonly description: string | null
+  readonly group: string
+  readonly price: number
+  readonly billing:
+    | { readonly mode: 'auto'; readonly interval: 'month' | 'year'; readonly stripePriceId: string }
+    | { readonly mode: 'fixed'; readonly period: string; readonly parsed: Period }
+  readonly giftable: boolean
+  readonly hidden: boolean
+}
+
+export interface DuesConfig {
+  readonly currency: string
+  readonly graceDays: number
+  readonly label: string
+  readonly seedPlans: readonly DuesPlan[]
+  readonly extraRedirectHosts: readonly string[]
+}
+
+const PLAN_KEY = /^[a-z][a-z0-9-]{0,39}$/
+const MAX_GRANTABLE_DAYS = 2 * 366
+
+function refuse(message: string): never {
+  throw new Error(`dues plugin configuration: ${message}`)
+}
+
+export function parseDuesConfig(input: DuesConfigInput): DuesConfig {
+  if (!isCurrencyCode(input.currency)) {
+    refuse(`"${input.currency}" is not a three-letter ISO 4217 currency code.`)
+  }
+
+  const graceDays = input.graceDays ?? 7
+  if (!Number.isInteger(graceDays) || graceDays < 0 || graceDays > 30) {
+    refuse(
+      `graceDays is ${String(input.graceDays)}. It is the window a lapsed payment keeps ` +
+        'access for, 0 to 30 days.',
+    )
+  }
+
+  const label = (input.label ?? 'Membership').trim()
+  if (label === '') refuse('label must not be empty.')
+
+  const seen = new Set<string>()
+  const plans = (input.plans ?? []).map((plan): DuesPlan => {
+    const where = `plan "${plan.key}"`
+
+    if (!PLAN_KEY.test(plan.key)) {
+      refuse(`${where}: keys are lower-case letters, digits and hyphens.`)
+    }
+    if (seen.has(plan.key)) refuse(`${where} is declared twice.`)
+    seen.add(plan.key)
+
+    if (plan.name.trim() === '') refuse(`${where}: needs a name members will read.`)
+    if (!PLAN_KEY.test(plan.group)) {
+      refuse(`${where}: "${plan.group}" is not a valid group key.`)
+    }
+    if (!isValidMinorAmount(plan.price)) {
+      refuse(
+        `${where}: price must be a positive whole number of minor units — 500 is £5.00. ` +
+          'A decimal here is almost always a hundredfold mistake.',
+      )
+    }
+
+    if (plan.billing.mode === 'auto') {
+      if (!plan.billing.stripePriceId.startsWith('price_')) {
+        refuse(
+          `${where}: an auto-renewing plan needs the Stripe price id (price_…) it bills ` +
+            'against. Create the price in the Stripe dashboard and paste its id.',
+        )
+      }
+      if (plan.giftable === true) {
+        refuse(
+          `${where}: an auto-renewing plan cannot be a gift. It would charge the buyer's ` +
+            "card forever for someone else's membership — sell a fixed-term pass instead.",
+        )
+      }
+      return {
+        key: plan.key,
+        name: plan.name.trim(),
+        description: plan.description?.trim() || null,
+        group: plan.group,
+        price: plan.price,
+        billing: plan.billing,
+        giftable: false,
+        hidden: plan.hidden === true,
+      }
+    }
+
+    const parsed = parsePeriod(plan.billing.period)
+    if (parsed === null) {
+      refuse(
+        `${where}: "${plan.billing.period}" is not an ISO-8601 period like P90D, P1M or P1Y.`,
+      )
+    }
+    if (periodCeilingDays(parsed) + graceDays > MAX_GRANTABLE_DAYS) {
+      refuse(
+        `${where}: the period plus grace can reach past two years, and the board caps a ` +
+          'plugin grant at two years. Sell a shorter pass.',
+      )
+    }
+
+    return {
+      key: plan.key,
+      name: plan.name.trim(),
+      description: plan.description?.trim() || null,
+      group: plan.group,
+      price: plan.price,
+      billing: { ...plan.billing, parsed },
+      giftable: plan.giftable !== false,
+      hidden: plan.hidden === true,
+    }
+  })
+
+  for (const host of input.extraRedirectHosts ?? []) {
+    if (!/^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/.test(host)) {
+      refuse(`"${host}" is not a plain host name.`)
+    }
+  }
+
+  return {
+    currency: input.currency.toLowerCase(),
+    graceDays,
+    label,
+    seedPlans: plans,
+    extraRedirectHosts: input.extraRedirectHosts ?? [],
+  }
+}