@meith/plugin-dues 0.16.0 → 0.17.0

package/README.md

@@ -40,27 +40,40 @@ history behind it, and a checkout a visitor can actually go through. See
 1. **Register the plugin** where plugins are registered:
 
    ```ts
-   // apps/community/community.plugins.ts (this repository's own demo and
-   // test boards register their versions in community.demo.plugins.ts,
-   // behind DEMO_MODE and DUES_TEST_BOARD)
+   // apps/community/community.plugins.ts
    import { dues } from '@meith/plugin-dues'
 
-   export const INSTALLED_PLUGINS = [
-     { key: 'dues', plugin: dues({ currency: 'gbp', graceDays: 7 }) },
-   ]
+   export const INSTALLED_PLUGINS = [{ key: 'dues', plugin: dues }]
    ```
 
-   `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.
+   That is the whole of it — `dues` needs no constructor argument, which is
+   what lets a marketplace install register it from the key alone. Every
+   board-specific choice is made afterwards, in the browser.
+
+   A board that registers plugins in code and genuinely needs a code-only
+   escape hatch — an extra redirect host for a proxy or a loopback address,
+   or code-declared seed plans for a demo or test board — calls `createDues`
+   instead: `createDues({ extraRedirectHosts: ['proxy.example'] })`. This
+   repository's own demo and test boards do exactly that, in
+   `community.demo.plugins.ts`, behind `DEMO_MODE` and `DUES_TEST_BOARD`. A
+   seed plan populates the plan table on the board's first run and is
+   ignored once it has rows — after that, the panel owns the plans, exactly
+   as for a board that never declared any.
 
 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.
+3. **Settings**, all under Admin → Plugins → Dues:
+   - **Currency** and **Grace period** — the board's default currency (a
+     plan can still be priced in any ISO 4217 code; this is what a new plan
+     defaults to, what the ledger shows, and the fallback when a Stripe
+     event carries no currency of its own) and the days a lapsed renewal
+     keeps access. `DUES_CURRENCY` and `DUES_GRACE_DAYS` override them from
+     the environment, on the same rule as the keys below.
+   - **`DUES_STRIPE_SECRET_KEY`** and **`DUES_STRIPE_WEBHOOK_SECRET`** — set
+     in the environment, or filled in here. Environment wins, and the
+     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.
@@ -70,6 +83,18 @@ history behind it, and a checkout a visitor can actually go through. See
 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.
 
+### What a marketplace install cannot reach
+
+`allowedRedirectHosts` — the hosts a route's redirect may point an absolute
+URL at — is declared on the plugin definition itself, and the host reads it
+before any setting resolves. There is no way for a setting to feed it, so
+the zero-argument `dues` export carries only Stripe's own two hosts
+(`checkout.stripe.com`, `billing.stripe.com`), which is everything the
+checkout and billing-portal flows need. A board that must add another host
+registers `createDues({ extraRedirectHosts: [...] })` in code instead — the
+one piece of Dues configuration that stays code-only because the plugin API
+has no other way to express it.
+
 ## Plans
 
 A plan is made and edited in the panel. It has a permanent key, a name, a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@meith/plugin-dues",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Membership dues for a Meith board: Stripe-backed subscriptions as a contained plugin.",
   "license": "LGPL-3.0-or-later",
   "repository": {
@@ -20,8 +20,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@meith/plugin-kit": "^0.16.0",
-    "@meith/theme-kit": "^0.16.0"
+    "@meith/plugin-kit": "^0.17.0",
+    "@meith/theme-kit": "^0.17.0"
   },
   "peerDependencies": {
     "react": "^19.2.0"

package/src/config.ts

@@ -14,9 +14,13 @@ export interface DuesPlanInput {
   readonly hidden?: boolean
 }
 
+/**
+ * What a board still configures in code, when it registers the plugin with
+ * arguments rather than taking the zero-argument export. `currency` and
+ * `graceDays` moved to plugin settings — see `resolveDuesConfig` — because a
+ * marketplace install can only supply a key, never a constructor argument.
+ */
 export interface DuesConfigInput {
-  readonly currency: string
-  readonly graceDays?: number
   readonly label?: string
   readonly plans?: readonly DuesPlanInput[]
   readonly extraRedirectHosts?: readonly string[]
@@ -35,34 +39,72 @@ export interface DuesPlan {
   readonly hidden: boolean
 }
 
-export interface DuesConfig {
-  readonly currency: string
-  readonly graceDays: number
+/** The half of the configuration fixed at plugin registration. */
+export interface DuesStaticConfig {
   readonly label: string
   readonly seedPlans: readonly DuesPlan[]
   readonly extraRedirectHosts: readonly string[]
 }
 
+/** The static half plus the settings an operator edits in the panel. */
+export interface DuesConfig extends DuesStaticConfig {
+  readonly currency: string
+  readonly graceDays: number
+}
+
 const PLAN_KEY = /^[a-z][a-z0-9-]{0,39}$/
 const MAX_GRANTABLE_DAYS = 2 * 366
 
+export const DEFAULT_CURRENCY = 'usd'
+export const DEFAULT_GRACE_DAYS = 7
+export const MIN_GRACE_DAYS = 0
+export const MAX_GRACE_DAYS = 30
+
+/**
+ * The board-wide currency is a `select` setting, and a select needs a fixed
+ * list of options — unlike a plan's own currency (still any ISO 4217 code,
+ * typed into the plan form), this is the curated set an operator picks a
+ * default from. Labels are bare codes, on purpose: they need no translation
+ * and cost nothing in the message catalog.
+ */
+export const DUES_CURRENCY_OPTIONS: readonly { readonly value: string; readonly label: string }[] =
+  [
+    { value: 'usd', label: 'USD' },
+    { value: 'eur', label: 'EUR' },
+    { value: 'gbp', label: 'GBP' },
+    { value: 'cad', label: 'CAD' },
+    { value: 'aud', label: 'AUD' },
+    { value: 'nzd', label: 'NZD' },
+    { value: 'chf', label: 'CHF' },
+    { value: 'jpy', label: 'JPY' },
+    { value: 'sek', label: 'SEK' },
+    { value: 'nok', label: 'NOK' },
+    { value: 'dkk', label: 'DKK' },
+    { value: 'pln', label: 'PLN' },
+    { value: 'czk', label: 'CZK' },
+    { value: 'sgd', label: 'SGD' },
+    { value: 'hkd', label: 'HKD' },
+    { value: 'inr', label: 'INR' },
+    { value: 'brl', label: 'BRL' },
+    { value: 'mxn', label: 'MXN' },
+    { value: 'zar', label: 'ZAR' },
+  ]
+
 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.',
-    )
-  }
-
+/**
+ * Validates the code-configured half of the plugin — a plan's `currency` is
+ * still supplied per-plan on the admin form, but a code-declared *seed* plan
+ * has none of its own, so it always seeds under whatever the `currency`
+ * setting resolves to when the board's first request seeds it. That means
+ * the period-plus-grace cap below cannot know the actual `graceDays` in
+ * force (a setting, resolved per request) — it checks against the worst
+ * case, `MAX_GRACE_DAYS`, so no seed can exceed the board's two-year grant
+ * cap no matter how the setting is later changed.
+ */
+export function parseDuesConfig(input: DuesConfigInput = {}): DuesStaticConfig {
   const label = (input.label ?? 'Membership').trim()
   if (label === '') refuse('label must not be empty.')
 
@@ -116,10 +158,10 @@ export function parseDuesConfig(input: DuesConfigInput): DuesConfig {
     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) {
+    if (periodCeilingDays(parsed) + MAX_GRACE_DAYS > 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.',
+        `${where}: the period plus the longest possible grace window can reach past two ` +
+          'years, and the board caps a plugin grant at two years. Sell a shorter pass.',
       )
     }
 
@@ -142,10 +184,38 @@ export function parseDuesConfig(input: DuesConfigInput): DuesConfig {
   }
 
   return {
-    currency: input.currency.toLowerCase(),
-    graceDays,
     label,
     seedPlans: plans,
     extraRedirectHosts: input.extraRedirectHosts ?? [],
   }
 }
+
+function clampGraceDays(value: number): number {
+  if (!Number.isFinite(value)) return DEFAULT_GRACE_DAYS
+  return Math.min(MAX_GRACE_DAYS, Math.max(MIN_GRACE_DAYS, Math.round(value)))
+}
+
+/**
+ * Merges the static, code-declared half of the configuration with the two
+ * settings an operator edits in the panel. Settings have no refusal path —
+ * unlike `parseDuesConfig`, a bad value here is repaired rather than thrown:
+ * an unrecognised currency falls back to the default, and an out-of-range
+ * grace period is clamped to 0–30 days. `resolvePluginSettings` already
+ * guarantees a `select` setting's stored value is one of its declared
+ * options, so the currency check below is a second, cheap line of defence
+ * rather than the one this depends on.
+ */
+export function resolveDuesConfig(
+  staticConfig: DuesStaticConfig,
+  settings: Readonly<Record<string, string | number | boolean>>,
+): DuesConfig {
+  const rawCurrency = String(settings.currency ?? DEFAULT_CURRENCY).toLowerCase()
+  const currency = isCurrencyCode(rawCurrency) ? rawCurrency : DEFAULT_CURRENCY
+
+  const rawGraceDays = settings.grace_days
+  const graceDays = clampGraceDays(
+    typeof rawGraceDays === 'number' ? rawGraceDays : DEFAULT_GRACE_DAYS,
+  )
+
+  return { ...staticConfig, currency, graceDays }
+}

package/src/definition.tsx

@@ -6,7 +6,15 @@ import {
   type PluginRuntimeContext,
 } from '@meith/plugin-kit'
 
-import { type DuesConfigInput, parseDuesConfig } from './config'
+import {
+  DEFAULT_CURRENCY,
+  DEFAULT_GRACE_DAYS,
+  DUES_CURRENCY_OPTIONS,
+  type DuesConfig,
+  type DuesConfigInput,
+  parseDuesConfig,
+  resolveDuesConfig,
+} from './config'
 import {
   buildServices,
   type DuesServices,
@@ -33,26 +41,66 @@ import { runReconcile, runSweep } from './tasks'
 import { CodesPage, LedgerPage, MembersPage, PlansAdminPage, StatusPage } from './ui/admin'
 import { GoPage, ManagePage, PlansPage, ReturnPage } from './ui/pages'
 
-export function dues(input: DuesConfigInput): PluginDefinition {
-  const config = parseDuesConfig(input)
+/**
+ * The code-configured path: still takes constructor arguments, for a board
+ * that registers Dues directly in `community.plugins.ts` rather than
+ * through a marketplace install. `dues`, below, is this called with none —
+ * the zero-argument export a marketplace install actually uses.
+ */
+export function createDues(input: DuesConfigInput = {}): PluginDefinition {
+  const staticConfig = parseDuesConfig(input)
+
+  // Resolved fresh per call: `currency` and `graceDays` are settings, so a
+  // request made after an operator edits them must see the new value, not
+  // one baked in when the plugin was registered.
+  const configFor = (context: PluginRuntimeContext): DuesConfig =>
+    resolveDuesConfig(staticConfig, context.settings)
 
   const route =
     (
       fn: (services: DuesServices, request: PluginRequest) => Promise<PluginResponse>,
     ): ((request: PluginRequest, context: PluginRuntimeContext) => Promise<PluginResponse>) =>
     (request, context) =>
-      fn(buildServices(config, context), request)
+      fn(buildServices(configFor(context), context), request)
 
   return definePlugin({
     key: 'dues',
     name: 'Dues',
-    version: '0.16.0',
-    description: en['dues.definition.description'].replace('{label}', config.label.toLowerCase()),
+    version: '0.17.0',
+    description: en['dues.definition.description'].replace(
+      '{label}',
+      staticConfig.label.toLowerCase(),
+    ),
     descriptionKey: 'dues.definition.description',
-    descriptionArgs: { label: config.label.toLowerCase() },
+    descriptionArgs: { label: staticConfig.label.toLowerCase() },
     apiVersion: '0',
 
     settings: [
+      {
+        key: 'currency',
+        label: en['dues.definition.setting.currency.label'],
+        labelKey: 'dues.definition.setting.currency.label',
+        type: 'select',
+        options: DUES_CURRENCY_OPTIONS,
+        env: 'DUES_CURRENCY',
+        default: DEFAULT_CURRENCY,
+        description: en['dues.definition.setting.currency.description'],
+        descriptionKey: 'dues.definition.setting.currency.description',
+      },
+      {
+        key: 'grace_days',
+        label: en['dues.definition.setting.graceDays.label'],
+        labelKey: 'dues.definition.setting.graceDays.label',
+        type: 'number',
+        env: 'DUES_GRACE_DAYS',
+        default: DEFAULT_GRACE_DAYS,
+        // PluginSetting has no descriptionArgs — unlike the definition's own
+        // description, a setting's is translated with no interpolation — so
+        // the range is spelled out in the catalog text itself, and MIN/MAX
+        // below only need to stay in sync with the words there by hand.
+        description: en['dues.definition.setting.graceDays.description'],
+        descriptionKey: 'dues.definition.setting.graceDays.description',
+      },
       {
         key: 'stripe_secret_key',
         label: en['dues.definition.setting.secret.label'],
@@ -103,7 +151,7 @@ export function dues(input: DuesConfigInput): PluginDefinition {
         id: 'reconcile',
         intervalSeconds: 300,
         run: async (context) => {
-          const services = buildServices(config, context)
+          const services = buildServices(configFor(context), context)
           const result = await runReconcile(entitlementDeps(services), services.stripe)
           if (
             result.ordersSettled +
@@ -120,7 +168,7 @@ export function dues(input: DuesConfigInput): PluginDefinition {
         id: 'sweep',
         intervalSeconds: 3600,
         run: async (context) => {
-          const services = buildServices(config, context)
+          const services = buildServices(configFor(context), context)
           const expired = await runSweep(entitlementDeps(services))
           if (expired > 0) context.logger.info('dues: memberships expired', { expired })
         },
@@ -233,24 +281,24 @@ export function dues(input: DuesConfigInput): PluginDefinition {
     pages: [
       {
         path: '',
-        title: config.label,
+        title: staticConfig.label,
         access: 'anonymous',
-        render: (context) => PlansPage({ config, context }),
+        render: (context) => PlansPage({ config: configFor(context), context }),
       },
       {
         path: 'return',
         title: en['dues.definition.page.return'],
         titleKey: 'dues.definition.page.return',
         access: 'member',
-        render: (context) => ReturnPage({ config, context }),
+        render: (context) => ReturnPage({ config: configFor(context), context }),
       },
       {
         path: 'manage',
-        title: en['dues.definition.manage'].replace('{label}', config.label.toLowerCase()),
+        title: en['dues.definition.manage'].replace('{label}', staticConfig.label.toLowerCase()),
         titleKey: 'dues.definition.manage',
-        titleArgs: { label: config.label.toLowerCase() },
+        titleArgs: { label: staticConfig.label.toLowerCase() },
         access: 'member',
-        render: (context) => ManagePage({ config, context }),
+        render: (context) => ManagePage({ config: configFor(context), context }),
       },
       {
         path: 'go',
@@ -259,12 +307,12 @@ export function dues(input: DuesConfigInput): PluginDefinition {
         access: 'member',
         render: (context) =>
           GoPage({
-            config,
+            config: configFor(context),
             context,
             allowedHosts: [
               'checkout.stripe.com',
               'billing.stripe.com',
-              ...config.extraRedirectHosts,
+              ...staticConfig.extraRedirectHosts,
             ],
           }),
       },
@@ -275,13 +323,13 @@ export function dues(input: DuesConfigInput): PluginDefinition {
         path: 'status',
         title: en['dues.definition.page.status'],
         titleKey: 'dues.definition.page.status',
-        render: (context) => StatusPage({ config, context }),
+        render: (context) => StatusPage({ config: configFor(context), context }),
       },
       {
         path: 'plans',
         title: en['dues.definition.page.plans'],
         titleKey: 'dues.definition.page.plans',
-        render: (context) => PlansAdminPage({ config, context }),
+        render: (context) => PlansAdminPage({ config: configFor(context), context }),
       },
       {
         path: 'members',
@@ -293,23 +341,23 @@ export function dues(input: DuesConfigInput): PluginDefinition {
         path: 'codes',
         title: en['dues.definition.page.codes'],
         titleKey: 'dues.definition.page.codes',
-        render: (context) => CodesPage({ config, context }),
+        render: (context) => CodesPage({ config: configFor(context), context }),
       },
       {
         path: 'ledger',
         title: en['dues.definition.page.ledger'],
         titleKey: 'dues.definition.page.ledger',
-        render: (context) => LedgerPage({ config, context }),
+        render: (context) => LedgerPage({ config: configFor(context), context }),
       },
     ],
 
     navigation: [
-      { key: 'plans', label: config.label, path: '', audience: 'members' },
+      { key: 'plans', label: staticConfig.label, path: '', audience: 'members' },
       {
         key: 'manage',
-        label: en['dues.definition.manage'].replace('{label}', config.label.toLowerCase()),
+        label: en['dues.definition.manage'].replace('{label}', staticConfig.label.toLowerCase()),
         labelKey: 'dues.definition.manage',
-        labelArgs: { label: config.label.toLowerCase() },
+        labelArgs: { label: staticConfig.label.toLowerCase() },
         path: 'manage',
         audience: 'members',
         under: 'plans',
@@ -319,7 +367,19 @@ export function dues(input: DuesConfigInput): PluginDefinition {
     allowedRedirectHosts: [
       'checkout.stripe.com',
       'billing.stripe.com',
-      ...config.extraRedirectHosts,
+      ...staticConfig.extraRedirectHosts,
     ],
   })
 }
+
+/**
+ * The zero-argument export: what a marketplace install actually registers.
+ * `allowedRedirectHosts` carries only Stripe's own hosts — a marketplace
+ * install cannot express a constructor argument, and `allowedRedirectHosts`
+ * is fixed on the definition at this call, before any settings resolve, so
+ * there is no later point where a board-configured host could be added. A
+ * board that genuinely needs another redirect host (a proxy, a loopback
+ * address for a test double) registers `createDues({ extraRedirectHosts })`
+ * directly instead.
+ */
+export const dues: PluginDefinition = createDues()

package/src/demo.ts

@@ -1,7 +1,7 @@
 import type { PluginData, PluginGrants, PluginNotify } from '@meith/plugin-kit'
 
 import { discountedPrice } from './codes'
-import { type DuesConfig, parseDuesConfig } from './config'
+import { type DuesConfig, parseDuesConfig, resolveDuesConfig } from './config'
 import { applyInternalEvent, type EntitlementDeps, settlePaidOrder } from './entitlement'
 import { addDays } from './period'
 import {
@@ -103,9 +103,9 @@ class DemoSeed {
   private counts = { plans: 0, codes: 0, orders: 0, memberships: 0, events: 0 }
 
   constructor(private readonly deps: DuesDemoDeps) {
-    this.config = parseDuesConfig({
+    this.config = resolveDuesConfig(parseDuesConfig({}), {
       currency: DUES_DEMO_CURRENCY,
-      graceDays: DUES_DEMO_GRACE_DAYS,
+      grace_days: DUES_DEMO_GRACE_DAYS,
     })
     this.clock = deps.now
     this.grants = deps.grants(() => this.clock)

package/src/index.ts

@@ -1,5 +1,9 @@
 export type { DuesConfigInput, DuesPlanInput } from './config'
-export { dues } from './definition'
+// `plugin` and `messages` (below) are the manifest-installable convention
+// board.plugins.json generation relies on (scripts/board-plugins-gen.mjs) —
+// re-exports, not a second definition, so `dues` stays the name everyone
+// reads in code that names it directly.
+export { createDues, dues, dues as plugin } from './definition'
 export {
   DUES_DEMO_CODES,
   DUES_DEMO_CURRENCY,
@@ -12,6 +16,6 @@ export {
   type DuesDemoSummary,
   seedDuesDemo,
 } from './demo'
-export { duesMessages } from './messages'
+export { duesMessages, duesMessages as messages } from './messages'
 export { SUBSCRIBED_EVENT_TYPES } from './stripe/events'
 export { signStripePayload } from './stripe/webhook'

package/src/messages/en.json

@@ -178,6 +178,10 @@
   "dues.definition.setting.apiBase.label": "Stripe API address",
   "dues.definition.setting.apiVersion.description": "Pinned so Stripe’s payload shapes change on a deploy, not on a Tuesday. Change it only alongside a plugin upgrade that expects the new shapes.",
   "dues.definition.setting.apiVersion.label": "Stripe API version",
+  "dues.definition.setting.currency.description": "The board’s default currency — shown on the ledger, and the fallback when a Stripe event carries none of its own. Each plan still records whatever currency its own price is in.",
+  "dues.definition.setting.currency.label": "Currency",
+  "dues.definition.setting.graceDays.description": "Days a lapsed renewal keeps access before the membership lapses — 0 to 30. A value outside that range is clamped rather than refused.",
+  "dues.definition.setting.graceDays.label": "Grace period, in days",
   "dues.definition.setting.secret.description": "The sk_live_… or sk_test_… key from the Stripe dashboard.",
   "dues.definition.setting.secret.label": "Stripe secret key",
   "dues.definition.setting.webhook.description": "The whsec_… secret of the webhook endpoint. Without it, payments are taken but can never confirm.",