indico-plugin-group-registration 0.1.0__tar.gz

indico_plugin_group_registration-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+coverage.xml
+htmlcov/
+*.mo
+
+# Plugin asset build artifacts
+node_modules/
+indico_group_registration/static/dist/
+webpack-build-config.json
+url_map.json

indico_plugin_group_registration-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: indico-plugin-group-registration
+Version: 0.1.0
+Summary: Participant-run group registration with plan-based discounts for Indico
+Project-URL: Homepage, https://github.com/indico/indico
+Author: RobotHanzo
+License-Expression: MIT
+Classifier: Environment :: Plugins
+Classifier: Environment :: Web Environment
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <3.13,>=3.12.2
+Requires-Dist: indico>=3.3
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Indico Group Registration
+
+Participant-run group registration with plan-based discounts for
+[Indico](https://github.com/indico/indico) 3.3.
+
+A participant picks a **group plan** while registering, gets a code and a join
+link, and shares them however they like. Everyone who joins pays that plan's
+rate straight away. The group **confirms itself** the moment the plan's seat
+count is filled — there is no button to press. If it never fills, the plugin
+reprices it at the reconciliation deadline and reports what each member still
+owes.
+
+Organizers set the plans and the disclaimer. They never have to create a group.
+
+## How it works
+
+### Plans
+
+An organizer defines plans per registration form. A plan is a seat count and a
+rate:
+
+```json
+[
+  {"id": "p3",  "label": "Group of 3",  "size": 3,  "type": "percent", "value": 10},
+  {"id": "p10", "label": "Group of 10", "size": 10, "type": "percent", "value": 15},
+  {"id": "p25", "label": "Group of 25", "size": 25, "type": "amount",  "value": 50}
+]
+```
+
+The seat count is both the **target and the cap**: filling it confirms the
+group, and the group is then full.
+
+### Lifecycle
+
+| State | What it means |
+| --- | --- |
+| `forming` | Seats filling. Members pay the chosen plan's rate, whenever they like. |
+| `confirmed` | The seat count was reached. Automatic. The rate is final and never gets worse. |
+| `short` | The deadline passed with seats empty. Repriced to whatever the group does qualify for; balances may be due. |
+| `dissolved` | A manager took it apart. Everyone is back on the standard rate. |
+
+The only transition a human triggers is dissolution.
+
+### Reconciliation, and the one thing to know before enabling this
+
+Members may pay before their group fills. If the group then falls short, the
+plugin reprices everyone — including people who have already paid.
+
+**Indico has no concept of a partial payment or a balance.** A transaction is
+one amount against one registration, and its checkout would charge the whole
+new price again rather than the difference. So an already-paid member whose
+price rises stays `complete` as far as Indico is concerned, and only this
+plugin knows they owe anything.
+
+The plugin gives organizers a **Balances due** list (paid amount, new price,
+delta) and e-mails every affected member, but a person collects the money — at
+the desk or by transfer, recorded as a manual payment. Two settings soften it:
+
+- set the **reconciliation deadline** well before the event, so balances
+  surface while there is still time to chase them;
+- turn off **allow early payment** if you would rather not chase anyone.
+
+### Sharing a group
+
+The group panel shows the group code and the join link, each with a copy
+button. **The plugin sends no invitations.** There is no invite box and no way
+for a participant to make your server e-mail a stranger. Leaders share the link
+themselves.
+
+The plugin does send e-mails that nobody can trigger on demand: group
+confirmed, group short with the new rate, and group dissolved.
+
+## Installation
+
+```bash
+pip install indico-plugin-group-registration
+```
+
+Add it to `indico.conf`:
+
+```python
+PLUGINS = {'group_registration'}
+```
+
+Then create the tables and build the assets:
+
+```bash
+indico db --all-plugins upgrade
+indico setup create-symlinks --help   # if you serve plugin static files
+python bin/maintenance/build-assets.py plugin /path/to/IndicoGroupRegistration
+```
+
+Restart Indico and its Celery workers — the reconciliation task runs every
+fifteen minutes from the Celery beat schedule.
+
+## Configuration
+
+Event management → **Group registration**, then pick a registration form.
+Nothing changes on a form until group registration is enabled for it.
+
+| Setting | Default | Notes |
+| --- | --- | --- |
+| Plans | – | JSON, validated on save |
+| Discount applies to | Registration fee | Or the whole price, including paid options |
+| Reconciliation deadline | Registration end | Set it well before the event |
+| Allow paying before the group fills | on | |
+| Groups per person | 1 | 0 for no limit |
+| Count registrations awaiting approval | on | Withdrawn and rejected never count |
+| Reprice a confirmed group that loses a member | off | Nobody should be rebilled over somebody else's moderation |
+| Disclaimer | a sensible default | Versioned; the version and time of acceptance are stored per membership |
+
+Enabling group registration provisions two fields on the form:
+
+- **`ext__group_plan`** — the plan picker the participant fills in. Put it
+  wherever you like in the form.
+- **`ext__group_discount`** — a manager-only field carrying the discount. It is
+  locked, written only by the plugin, and appears as a named line on the
+  invoice. Leave it alone; the plugin puts it back if it is removed.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest
+ruff check .
+```
+
+The tests here are unit tests over the money arithmetic and the code handling;
+they do not need a database or Indico's pytest plugin.
+
+## How it hooks into Indico
+
+Nothing in core is patched. See `docs/EXTENSION-POINTS.md` for the full map
+with file-and-line references, and `docs/PLAN.md` for the design. The short
+version:
+
+- registration field types via `signals.core.get_fields`
+- the registration lifecycle via `registration_created`, `registration_deleted`
+  and `registration_state_updated`
+- `is_field_data_locked` to keep core out of the plugin's own field
+- `registrant_list_items` for the Group column
+- `before-render-registration-info` for the group panel
+- the React field registry via `regformCustomFields`
+- `get_template_customization_paths` to name the discount on the checkout page,
+  using `{% extends '~...' %}` so it inherits the core template rather than
+  forking it
+
+## Licence
+
+MIT.

indico_plugin_group_registration-0.1.0/README.md

@@ -0,0 +1,150 @@
+# Indico Group Registration
+
+Participant-run group registration with plan-based discounts for
+[Indico](https://github.com/indico/indico) 3.3.
+
+A participant picks a **group plan** while registering, gets a code and a join
+link, and shares them however they like. Everyone who joins pays that plan's
+rate straight away. The group **confirms itself** the moment the plan's seat
+count is filled — there is no button to press. If it never fills, the plugin
+reprices it at the reconciliation deadline and reports what each member still
+owes.
+
+Organizers set the plans and the disclaimer. They never have to create a group.
+
+## How it works
+
+### Plans
+
+An organizer defines plans per registration form. A plan is a seat count and a
+rate:
+
+```json
+[
+  {"id": "p3",  "label": "Group of 3",  "size": 3,  "type": "percent", "value": 10},
+  {"id": "p10", "label": "Group of 10", "size": 10, "type": "percent", "value": 15},
+  {"id": "p25", "label": "Group of 25", "size": 25, "type": "amount",  "value": 50}
+]
+```
+
+The seat count is both the **target and the cap**: filling it confirms the
+group, and the group is then full.
+
+### Lifecycle
+
+| State | What it means |
+| --- | --- |
+| `forming` | Seats filling. Members pay the chosen plan's rate, whenever they like. |
+| `confirmed` | The seat count was reached. Automatic. The rate is final and never gets worse. |
+| `short` | The deadline passed with seats empty. Repriced to whatever the group does qualify for; balances may be due. |
+| `dissolved` | A manager took it apart. Everyone is back on the standard rate. |
+
+The only transition a human triggers is dissolution.
+
+### Reconciliation, and the one thing to know before enabling this
+
+Members may pay before their group fills. If the group then falls short, the
+plugin reprices everyone — including people who have already paid.
+
+**Indico has no concept of a partial payment or a balance.** A transaction is
+one amount against one registration, and its checkout would charge the whole
+new price again rather than the difference. So an already-paid member whose
+price rises stays `complete` as far as Indico is concerned, and only this
+plugin knows they owe anything.
+
+The plugin gives organizers a **Balances due** list (paid amount, new price,
+delta) and e-mails every affected member, but a person collects the money — at
+the desk or by transfer, recorded as a manual payment. Two settings soften it:
+
+- set the **reconciliation deadline** well before the event, so balances
+  surface while there is still time to chase them;
+- turn off **allow early payment** if you would rather not chase anyone.
+
+### Sharing a group
+
+The group panel shows the group code and the join link, each with a copy
+button. **The plugin sends no invitations.** There is no invite box and no way
+for a participant to make your server e-mail a stranger. Leaders share the link
+themselves.
+
+The plugin does send e-mails that nobody can trigger on demand: group
+confirmed, group short with the new rate, and group dissolved.
+
+## Installation
+
+```bash
+pip install indico-plugin-group-registration
+```
+
+Add it to `indico.conf`:
+
+```python
+PLUGINS = {'group_registration'}
+```
+
+Then create the tables and build the assets:
+
+```bash
+indico db --all-plugins upgrade
+indico setup create-symlinks --help   # if you serve plugin static files
+python bin/maintenance/build-assets.py plugin /path/to/IndicoGroupRegistration
+```
+
+Restart Indico and its Celery workers — the reconciliation task runs every
+fifteen minutes from the Celery beat schedule.
+
+## Configuration
+
+Event management → **Group registration**, then pick a registration form.
+Nothing changes on a form until group registration is enabled for it.
+
+| Setting | Default | Notes |
+| --- | --- | --- |
+| Plans | – | JSON, validated on save |
+| Discount applies to | Registration fee | Or the whole price, including paid options |
+| Reconciliation deadline | Registration end | Set it well before the event |
+| Allow paying before the group fills | on | |
+| Groups per person | 1 | 0 for no limit |
+| Count registrations awaiting approval | on | Withdrawn and rejected never count |
+| Reprice a confirmed group that loses a member | off | Nobody should be rebilled over somebody else's moderation |
+| Disclaimer | a sensible default | Versioned; the version and time of acceptance are stored per membership |
+
+Enabling group registration provisions two fields on the form:
+
+- **`ext__group_plan`** — the plan picker the participant fills in. Put it
+  wherever you like in the form.
+- **`ext__group_discount`** — a manager-only field carrying the discount. It is
+  locked, written only by the plugin, and appears as a named line on the
+  invoice. Leave it alone; the plugin puts it back if it is removed.
+
+## Development
+
+```bash
+pip install -e '.[dev]'
+pytest
+ruff check .
+```
+
+The tests here are unit tests over the money arithmetic and the code handling;
+they do not need a database or Indico's pytest plugin.
+
+## How it hooks into Indico
+
+Nothing in core is patched. See `docs/EXTENSION-POINTS.md` for the full map
+with file-and-line references, and `docs/PLAN.md` for the design. The short
+version:
+
+- registration field types via `signals.core.get_fields`
+- the registration lifecycle via `registration_created`, `registration_deleted`
+  and `registration_state_updated`
+- `is_field_data_locked` to keep core out of the plugin's own field
+- `registrant_list_items` for the Group column
+- `before-render-registration-info` for the group panel
+- the React field registry via `regformCustomFields`
+- `get_template_customization_paths` to name the discount on the checkout page,
+  using `{% extends '~...' %}` so it inherits the core template rather than
+  forking it
+
+## Licence
+
+MIT.

indico_plugin_group_registration-0.1.0/indico_group_registration/__init__.py

@@ -0,0 +1,15 @@
+"""Participant-run group registration for Indico.
+
+A participant picks a group plan while registering, gets a code and a join
+link, and shares them however they like.  Everyone who joins pays that plan's
+rate straight away.  The group locks itself the moment the plan's seat count is
+filled; if it never fills, the plugin reprices it at the reconciliation
+deadline and reports what each member still owes.
+"""
+
+from indico.util.i18n import make_bound_gettext
+
+
+__version__ = '0.1.0'
+
+_ = make_bound_gettext('group_registration')

indico_plugin_group_registration-0.1.0/indico_group_registration/blueprint.py

@@ -0,0 +1,34 @@
+from indico.core.plugins import IndicoPluginBlueprint
+
+from indico_group_registration.controllers import display, management
+
+
+blueprint = IndicoPluginBlueprint('group_registration', __name__, url_prefix='/event/<int:event_id>')
+
+# -- participant -------------------------------------------------------------
+
+blueprint.add_url_rule('/registrations/<int:reg_form_id>/group/join/<join_uuid>', 'join_link',
+                       display.RHGroupJoinLink)
+blueprint.add_url_rule('/registrations/<int:reg_form_id>/group/check-code', 'check_code',
+                       display.RHCheckGroupCode)
+blueprint.add_url_rule('/registrations/<int:reg_form_id>/group/leave', 'leave_group',
+                       display.RHLeaveGroup, methods=('POST',))
+blueprint.add_url_rule('/registrations/<int:reg_form_id>/group/new-link', 'regenerate_link',
+                       display.RHRegenerateJoinLink, methods=('POST',))
+blueprint.add_url_rule('/registrations/<int:reg_form_id>/group/plan', 'switch_plan',
+                       display.RHSwitchPlan, methods=('POST',))
+
+# -- management --------------------------------------------------------------
+
+blueprint.add_url_rule('/manage/group-registration/', 'manage_overview',
+                       management.RHGroupOverview)
+blueprint.add_url_rule('/manage/registration/<int:reg_form_id>/groups/', 'manage_groups',
+                       management.RHManageGroups)
+blueprint.add_url_rule('/manage/registration/<int:reg_form_id>/groups/settings', 'manage_settings',
+                       management.RHGroupSettings, methods=('GET', 'POST'))
+blueprint.add_url_rule('/manage/registration/<int:reg_form_id>/groups/balances', 'manage_balances',
+                       management.RHGroupBalances)
+blueprint.add_url_rule('/manage/registration/<int:reg_form_id>/groups/<int:group_id>/dissolve', 'dissolve_group',
+                       management.RHDissolveGroup, methods=('POST',))
+blueprint.add_url_rule('/manage/registration/<int:reg_form_id>/groups/<int:group_id>/reconcile', 'reconcile_group',
+                       management.RHReconcileGroup, methods=('POST',))

indico_plugin_group_registration-0.1.0/indico_group_registration/client/js/GroupPlanInput.jsx

@@ -0,0 +1,298 @@
+// The participant-facing plan picker.
+//
+// It writes a single object into the registration form:
+//   {mode: 'none' | 'create' | 'join', plan, name, code, accepted}
+// The backend validates the same shape again -- this component exists to make
+// the choice, and its consequences, legible before anyone submits.
+
+import checkCodeURL from 'indico-url:plugin_group_registration.check_code';
+
+import _ from 'lodash';
+import PropTypes from 'prop-types';
+import React, {useCallback, useEffect, useMemo, useRef, useState} from 'react';
+import {useField} from 'react-final-form';
+import {Checkbox, Form, Input, Loader, Message, Radio} from 'semantic-ui-react';
+
+import {Param, Translate} from 'indico/react/i18n';
+import {indicoAxios} from 'indico/utils/axios';
+
+import './GroupPlanInput.module.scss';
+
+const MODE_NONE = 'none';
+const MODE_CREATE = 'create';
+const MODE_JOIN = 'join';
+
+const EMPTY = {mode: MODE_NONE, plan: null, name: '', code: '', accepted: false};
+
+function formatMoney(amount, currency) {
+  try {
+    return new Intl.NumberFormat(document.documentElement.lang || 'en', {
+      style: 'currency',
+      currency,
+    }).format(amount);
+  } catch {
+    return `${amount} ${currency}`;
+  }
+}
+
+/** What one member pays under a plan, given the standard fee. */
+function planPrice(plan, basePrice) {
+  if (!plan || !plan.type || !plan.value) {
+    return basePrice;
+  }
+  const discount = plan.type === 'percent' ? (basePrice * plan.value) / 100 : plan.value;
+  return Math.max(basePrice - Math.min(discount, basePrice), 0);
+}
+
+/** The code as it is shown: two halves, because people retype it. */
+function normalizeCode(value) {
+  return (value || '').toUpperCase().replace(/[^A-Z0-9]/g, '');
+}
+
+export default function GroupPlanInput({
+  htmlName,
+  disabled,
+  eventId,
+  regformId,
+  plans,
+  currency,
+  basePrice,
+  disclaimer,
+  allowEarlyPayment,
+  enabled,
+}) {
+  const {input} = useField(htmlName, {allowNull: true});
+  const value = input.value || EMPTY;
+  const groupPlans = useMemo(() => plans.filter(p => p.size > 1), [plans]);
+
+  const [lookup, setLookup] = useState({state: 'idle'});
+  const lookupSeq = useRef(0);
+
+  const update = useCallback(
+    patch => {
+      input.onChange({...EMPTY, ...value, ...patch});
+    },
+    [input, value]
+  );
+
+  // -- code lookup ---------------------------------------------------------
+
+  const runLookup = useMemo(
+    () =>
+      _.debounce(async code => {
+        const seq = ++lookupSeq.current;
+        if (code.length < 4) {
+          setLookup({state: 'idle'});
+          return;
+        }
+        setLookup({state: 'loading'});
+        let response;
+        try {
+          response = await indicoAxios.get(checkCodeURL({event_id: eventId, reg_form_id: regformId}), {
+            params: {code},
+          });
+        } catch {
+          if (seq === lookupSeq.current) {
+            setLookup({state: 'error', error: Translate.string('Could not check that code.')});
+          }
+          return;
+        }
+        if (seq !== lookupSeq.current) {
+          // A newer keystroke already won.
+          return;
+        }
+        setLookup(
+          response.data.valid
+            ? {state: 'found', group: response.data}
+            : {state: 'error', error: response.data.error}
+        );
+      }, 400),
+    [eventId, regformId]
+  );
+
+  useEffect(() => {
+    if (value.mode === MODE_JOIN) {
+      runLookup(normalizeCode(value.code));
+    } else {
+      setLookup({state: 'idle'});
+    }
+    return () => runLookup.cancel();
+  }, [value.mode, value.code, runLookup]);
+
+  // A join link drops the code in the query string; pick it up once.
+  const prefilled = useRef(false);
+  useEffect(() => {
+    if (prefilled.current || disabled) {
+      return;
+    }
+    prefilled.current = true;
+    const code = new URLSearchParams(window.location.search).get('group_code');
+    if (code) {
+      input.onChange({...EMPTY, mode: MODE_JOIN, code: normalizeCode(code)});
+    }
+    // Only ever runs once, deliberately.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [disabled]);
+
+  if (!enabled || !groupPlans.length) {
+    return null;
+  }
+
+  const chosenPlan = groupPlans.find(p => p.id === value.plan) || null;
+  const needsAcceptance = value.mode === MODE_CREATE || value.mode === MODE_JOIN;
+
+  return (
+    <div styleName="group-plan" data-mode={value.mode}>
+      <Form.Group grouped>
+        <Radio
+          label={Translate.string('Register individually')}
+          checked={value.mode === MODE_NONE}
+          disabled={disabled}
+          onChange={() => input.onChange({...EMPTY})}
+        />
+        <Radio
+          label={Translate.string('Create a group and invite people')}
+          checked={value.mode === MODE_CREATE}
+          disabled={disabled}
+          onChange={() => update({mode: MODE_CREATE, code: '', accepted: false})}
+        />
+        <Radio
+          label={Translate.string('Join a group with a code')}
+          checked={value.mode === MODE_JOIN}
+          disabled={disabled}
+          onChange={() => update({mode: MODE_JOIN, plan: null, name: '', accepted: false})}
+        />
+      </Form.Group>
+
+      {value.mode === MODE_CREATE && (
+        <div styleName="panel">
+          <div styleName="plans">
+            {groupPlans.map(plan => (
+              <label key={plan.id} styleName="plan" data-selected={plan.id === value.plan}>
+                <Radio
+                  checked={plan.id === value.plan}
+                  disabled={disabled}
+                  onChange={() => update({plan: plan.id, accepted: false})}
+                />
+                <span styleName="plan-label">{plan.label}</span>
+                <span styleName="plan-seats">
+                  <Translate>
+                    <Param name="size" value={plan.size} /> members
+                  </Translate>
+                </span>
+                <span styleName="plan-price">
+                  {formatMoney(planPrice(plan, basePrice), currency)}
+                  <small>
+                    <Translate>each</Translate>
+                  </small>
+                </span>
+              </label>
+            ))}
+          </div>
+
+          <Form.Field required>
+            <label htmlFor="group-name-input">
+              <Translate>Group name</Translate>
+            </label>
+            <Input
+              id="group-name-input"
+              value={value.name}
+              disabled={disabled}
+              maxLength={80}
+              placeholder={Translate.string('e.g. your department or company')}
+              onChange={(evt, {value: name}) => update({name})}
+            />
+          </Form.Field>
+
+          {chosenPlan && (
+            <Message info>
+              <Translate>
+                You will get a code and a link to share. Your group confirms itself as soon as{' '}
+                <Param name="size" value={chosenPlan.size} /> people have joined, and the rate is
+                then final.
+              </Translate>
+            </Message>
+          )}
+        </div>
+      )}
+
+      {value.mode === MODE_JOIN && (
+        <div styleName="panel">
+          <Form.Field required>
+            <label htmlFor="group-code-input">
+              <Translate>Group code</Translate>
+            </label>
+            <Input
+              id="group-code-input"
+              value={value.code}
+              disabled={disabled}
+              maxLength={9}
+              placeholder="ABCD-2345"
+              onChange={(evt, {value: code}) => update({code: normalizeCode(code), accepted: false})}
+              icon={lookup.state === 'loading' ? <Loader active inline size="tiny" /> : undefined}
+            />
+          </Form.Field>
+
+          {lookup.state === 'error' && <Message negative>{lookup.error}</Message>}
+          {lookup.state === 'found' && (
+            <Message positive>
+              <Message.Header>{lookup.group.name}</Message.Header>
+              <p>
+                <Translate>
+                  <Param name="members" value={lookup.group.members} /> of{' '}
+                  <Param name="target" value={lookup.group.target} /> members ·{' '}
+                  <Param
+                    name="price"
+                    value={formatMoney(planPrice(lookup.group.plan, basePrice), currency)}
+                  />{' '}
+                  for you
+                </Translate>
+              </p>
+            </Message>
+          )}
+        </div>
+      )}
+
+      {needsAcceptance && (
+        <div styleName="disclaimer">
+          {disclaimer && <p>{disclaimer}</p>}
+          {!allowEarlyPayment && (
+            <p>
+              <Translate>
+                You will not be able to pay until your group is complete.
+              </Translate>
+            </p>
+          )}
+          <Checkbox
+            label={Translate.string('I understand and accept these conditions')}
+            checked={!!value.accepted}
+            disabled={disabled}
+            onChange={(evt, {checked}) => update({accepted: checked})}
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+GroupPlanInput.propTypes = {
+  htmlName: PropTypes.string.isRequired,
+  disabled: PropTypes.bool,
+  eventId: PropTypes.number.isRequired,
+  regformId: PropTypes.number.isRequired,
+  plans: PropTypes.array,
+  currency: PropTypes.string.isRequired,
+  basePrice: PropTypes.number,
+  disclaimer: PropTypes.string,
+  allowEarlyPayment: PropTypes.bool,
+  enabled: PropTypes.bool,
+};
+
+GroupPlanInput.defaultProps = {
+  disabled: false,
+  plans: [],
+  basePrice: 0,
+  disclaimer: '',
+  allowEarlyPayment: true,
+  enabled: false,
+};